JSON for Modern C++  3.0.1

◆ at() [1/6]

template<template< typename, typename, typename... > class ObjectType = std::map, template< typename, typename... > 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 > class AllocatorType = std::allocator, template< typename, typename=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 "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 }
static basic_json array(initializer_list_t init={})
explicitly create an array from an initializer list
Definition: json.hpp:8617
basic_json<> json
default JSON class
Definition: json.hpp:14379
reference at(size_type idx)
access specified array element with bounds checking
Definition: json.hpp:9984
detail::out_of_range out_of_range
exception indicating access out of the defined range
Definition: json.hpp:7435
detail::type_error type_error
exception indicating executing a member function with a wrong type
Definition: json.hpp:7433

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 -Isrc doc/examples/at__size_type.cpp -o at__size_type 

Definition at line 9984 of file json.hpp.