JSON for Modern C++  3.7.0

◆ at() [2/6]

template<template< typename U, typename V, typename... Args > class ObjectType = std::map, template< typename U, typename... Args > class ArrayType = std::vector, class StringType = std::string, class BooleanType = bool, class NumberIntegerType = std::int64_t, class NumberUnsignedType = std::uint64_t, class NumberFloatType = double, template< typename U > class AllocatorType = std::allocator, template< typename T, typename SFINAE=void > class JSONSerializer = adl_serializer>
const_reference nlohmann::basic_json::at ( size_type  idx) const
inline

Returns a const reference to the element at specified location idx, with bounds checking.

Parameters
[in]idxindex of the element to access
Returns
const reference to the element at index idx
Exceptions
type_error.304if the JSON value is not an array; in this case, calling at with an index makes no sense. See example below.
out_of_range.401if the index idx is out of range of the array; that is, idx >= size(). See example below.
Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
Complexity
Constant.
Since
version 1.0.0
Example
The example below shows how array elements can be read using at(). It also demonstrates the different exceptions that can be thrown.
1 #include <iostream>
2 #include <nlohmann/json.hpp>
3 
4 using json = nlohmann::json;
5 
6 int main()
7 {
8  // create JSON array
9  const json array = {"first", "2nd", "third", "fourth"};
10 
11  // output element at index 2 (third element)
12  std::cout << array.at(2) << '\n';
13 
14 
15  // exception type_error.304
16  try
17  {
18  // use at() on a non-array type
19  const json str = "I am a string";
20  std::cout << str.at(0) << '\n';
21  }
22  catch (json::type_error& e)
23  {
24  std::cout << e.what() << '\n';
25  }
26 
27  // exception out_of_range.401
28  try
29  {
30  // try to read beyond the array limit
31  std::cout << array.at(5) << '\n';
32  }
33  catch (json::out_of_range& e)
34  {
35  std::cout << e.what() << '\n';
36  }
37 }
basic_json<> json
default JSON class
Definition: json.hpp:2355
reference at(size_type idx)
access specified array element with bounds checking
Definition: json.hpp:17335
static basic_json array(initializer_list_t init={})
explicitly create an array from an initializer list
Definition: json.hpp:15905
detail::out_of_range out_of_range
exception indicating access out of the defined range
Definition: json.hpp:14645
detail::type_error type_error
exception indicating executing a member function with a wrong type
Definition: json.hpp:14643

Output (play with this example online):
"third"
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.401] array index 5 is out of range
The <a href= https://github.com/nlohmann/json/blob/develop/doc/examples/ at__size_type_const.cpp>example code above can be translated with
g++ -std=c++11 -Isingle_include doc/examples/
at__size_type_const.cpp -o 
at__size_type_const 

Definition at line 17387 of file json.hpp.