JSON for Modern C++  3.7.2

◆ at() [5/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>
reference nlohmann::basic_json::at ( size_type  idx)
inline

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

Parameters
[in]idxindex of the element to access
Returns
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 and written 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  json array = {"first", "2nd", "third", "fourth"};
10 
11  // output element at index 2 (third element)
12  std::cout << array.at(2) << '\n';
13 
14  // change element at index 1 (second element) to "second"
15  array.at(1) = "second";
16 
17  // output changed array
18  std::cout << array << '\n';
19 
20 
21  // exception type_error.304
22  try
23  {
24  // use at() on a non-array type
25  json str = "I am a string";
26  str.at(0) = "Another string";
27  }
28  catch (json::type_error& e)
29  {
30  std::cout << e.what() << '\n';
31  }
32 
33  // exception out_of_range.401
34  try
35  {
36  // try to write beyond the array limit
37  array.at(5) = "sixth";
38  }
39  catch (json::out_of_range& e)
40  {
41  std::cout << e.what() << '\n';
42  }
43 }

Output (play with this example online):
"third"
["first","second","third","fourth"]
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.401] array index 5 is out of range
The example code above can be translated with
g++ -std=c++11 -Isingle_include doc/examples/at__size_type.cpp -o at__size_type 

Definition at line 17521 of file json.hpp.

nlohmann::basic_json::at
reference at(size_type idx)
access specified array element with bounds checking
Definition: json.hpp:17521
nlohmann::basic_json::out_of_range
detail::out_of_range out_of_range
exception indicating access out of the defined range
Definition: json.hpp:14782
nlohmann::basic_json::array
static basic_json array(initializer_list_t init={})
explicitly create an array from an initializer list
Definition: json.hpp:16091
nlohmann::basic_json::type_error
detail::type_error type_error
exception indicating executing a member function with a wrong type
Definition: json.hpp:14780
nlohmann::json
basic_json<> json
default JSON class
Definition: json.hpp:2445