// (1) reference at(size_type idx); const_reference at(size_type idx) const; // (2) reference at(const typename object_t::key_type& key); const_reference at(const typename object_t::key_type& key) const; // (3) template<typename KeyType> reference at(KeyType&& key); template<typename KeyType> const_reference at(KeyType&& key) const; // (4) reference at(const json_pointer& ptr); const_reference at(const json_pointer& ptr) const;
idx, with bounds checking.key, with bounds checking.KeyType is comparable with #!cpp typename object_t::key_type and #!cpp typename object_comparator_t::is_transparent denotes a type.ptr, with bounds checking.KeyType : A type for an object key other than json_pointer that is comparable with string_t using object_comparator_t. This can also be a string view (C++17).
idx (in) : index of the element to access
key (in) : object key of the elements to access
ptr (in) : JSON pointer to the desired element
idxkeykeyptrStrong exception safety: if an exception occurs, the original value stays intact.
type_error.304 if the JSON value is not an array; in this case, calling at with an index makes no sense. See the example below.out_of_range.401 if the index idx is out of range of the array; that is, idx >= size(). See the example below.type_error.304 if the JSON value is not an object; in this case, calling at with a key makes no sense. See the example below.out_of_range.403 if the key key is not stored in the object; that is, find(key) == end(). See the example below.parse_error.106 if an array index in the passed JSON pointer ptr begins with ‘0’. See the example below.parse_error.109 if an array index in the passed JSON pointer ptr is not a number. See the example below.out_of_range.401 if an array index in the passed JSON pointer ptr is out of range. See the example below.out_of_range.402 if the array index ‘-’ is used in the passed JSON pointer ptr. As at provides checked access (and no elements are implicitly inserted), the index ‘-’ is always invalid. See the example below.out_of_range.403 if the JSON pointer describes a key of an object which cannot be found. See the example below.out_of_range.404 if the JSON pointer ptr can not be resolved. See the example below.out_of_range.410 if an array index in the passed JSON pointer ptr exceeds the range of size_type (e.g., on 32-bit platforms).!!! warning “Deprecation”
Overload (4) also accepts a [`json_pointer`](../json_pointer/index.md) whose template argument is a `basic_json` specialization (e.g., `nlohmann::json_pointer<nlohmann::json>`) instead of a string type. This is deprecated since version 3.11.0 and will be removed in a future major version; use `basic_json::json_pointer` (for `json`, `nlohmann::json_pointer<std::string>`) instead. You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated function. See the [migration guide](../../integration/migration_guide.md#json-pointers) for how to update existing code.
??? example “Example: (1) access specified array element with bounds checking”
The example below shows how array elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON array
json array = {"first", "2nd", "third", "fourth"};
// output element at index 2 (third element)
std::cout << array.at(2) << '\n';
// change element at index 1 (second element) to "second"
array.at(1) = "second";
// output changed array
std::cout << array << '\n';
// exception type_error.304
try
{
// use at() on a non-array type
json str = "I am a string";
str.at(0) = "Another string";
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to write beyond the array limit
array.at(5) = "sixth";
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}
```
Output:
```json
"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
```
??? example “Example: (1) access specified array element with bounds checking”
The example below shows how array elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON array
const json array = {"first", "2nd", "third", "fourth"};
// output element at index 2 (third element)
std::cout << array.at(2) << '\n';
// exception type_error.304
try
{
// use at() on a non-array type
const json str = "I am a string";
std::cout << str.at(0) << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to read beyond the array limit
std::cout << array.at(5) << '\n';
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}
```
Output:
```json
"third"
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.401] array index 5 is out of range
```
??? example “Example: (2) access specified object element with bounds checking”
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON object
json object =
{
{"the good", "il buono"},
{"the bad", "il cattivo"},
{"the ugly", "il brutto"}
};
// output element with key "the ugly"
std::cout << object.at("the ugly") << '\n';
// change element with key "the bad"
object.at("the bad") = "il cattivo";
// output changed array
std::cout << object << '\n';
// exception type_error.304
try
{
// use at() on a non-object type
json str = "I am a string";
str.at("the good") = "Another string";
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to write at a nonexisting key
object.at("the fast") = "il rapido";
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}
```
Output:
```json
"il brutto"
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.403] key 'the fast' not found
```
??? example “Example: (2) access specified object element with bounds checking”
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON object
const json object =
{
{"the good", "il buono"},
{"the bad", "il cattivo"},
{"the ugly", "il brutto"}
};
// output element with key "the ugly"
std::cout << object.at("the ugly") << '\n';
// exception type_error.304
try
{
// use at() on a non-object type
const json str = "I am a string";
std::cout << str.at("the good") << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to read from a nonexisting key
std::cout << object.at("the fast") << '\n';
}
catch (const json::out_of_range)
{
std::cout << "out of range" << '\n';
}
}
```
Output:
```json
"il brutto"
[json.exception.type_error.304] cannot use at() with string
out of range
```
??? example “Example: (3) access specified object element using string_view with bounds checking”
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
```cpp
#include <iostream>
#include <string_view>
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
int main()
{
// create JSON object
json object =
{
{"the good", "il buono"},
{"the bad", "il cattivo"},
{"the ugly", "il brutto"}
};
// output element with key "the ugly" using string_view
std::cout << object.at("the ugly"sv) << '\n';
// change element with key "the bad" using string_view
object.at("the bad"sv) = "il cattivo";
// output changed array
std::cout << object << '\n';
// exception type_error.304
try
{
// use at() with string_view on a non-object type
json str = "I am a string";
str.at("the good"sv) = "Another string";
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to write at a nonexisting key using string_view
object.at("the fast"sv) = "il rapido";
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}
```
Output:
```json
"il brutto"
{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
[json.exception.type_error.304] cannot use at() with string
[json.exception.out_of_range.403] key 'the fast' not found
```
??? example “Example: (3) access specified object element using string_view with bounds checking”
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
```cpp
#include <iostream>
#include <string_view>
#include <nlohmann/json.hpp>
using namespace std::string_view_literals;
using json = nlohmann::json;
int main()
{
// create JSON object
const json object =
{
{"the good", "il buono"},
{"the bad", "il cattivo"},
{"the ugly", "il brutto"}
};
// output element with key "the ugly" using string_view
std::cout << object.at("the ugly"sv) << '\n';
// exception type_error.304
try
{
// use at() with string_view on a non-object type
const json str = "I am a string";
std::cout << str.at("the good"sv) << '\n';
}
catch (const json::type_error& e)
{
std::cout << e.what() << '\n';
}
// exception out_of_range.401
try
{
// try to read from a nonexisting key using string_view
std::cout << object.at("the fast"sv) << '\n';
}
catch (const json::out_of_range& e)
{
std::cout << "out of range" << '\n';
}
}
```
Output:
```json
"il brutto"
[json.exception.type_error.304] cannot use at() with string
out of range
```
??? example “Example: (4) access specified element via JSON Pointer”
The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
exceptions that can be thrown.
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create a JSON value
json j =
{
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
};
// read-only access
// output element with JSON pointer "/number"
std::cout << j.at("/number"_json_pointer) << '\n';
// output element with JSON pointer "/string"
std::cout << j.at("/string"_json_pointer) << '\n';
// output element with JSON pointer "/array"
std::cout << j.at("/array"_json_pointer) << '\n';
// output element with JSON pointer "/array/1"
std::cout << j.at("/array/1"_json_pointer) << '\n';
// writing access
// change the string
j.at("/string"_json_pointer) = "bar";
// output the changed string
std::cout << j["string"] << '\n';
// change an array element
j.at("/array/1"_json_pointer) = 21;
// output the changed array
std::cout << j["array"] << '\n';
// out_of_range.106
try
{
// try to use an array index with leading '0'
json::reference ref = j.at("/array/01"_json_pointer);
}
catch (const json::parse_error& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.109
try
{
// try to use an array index that is not a number
json::reference ref = j.at("/array/one"_json_pointer);
}
catch (const json::parse_error& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.401
try
{
// try to use an invalid array index
json::reference ref = j.at("/array/4"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.402
try
{
// try to use the array index '-'
json::reference ref = j.at("/array/-"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.403
try
{
// try to use a JSON pointer to a nonexistent object key
json::const_reference ref = j.at("/foo"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.404
try
{
// try to use a JSON pointer that cannot be resolved
json::reference ref = j.at("/number/foo"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}
```
Output:
```json
1
"foo"
[1,2]
2
"bar"
[1,21]
[json.exception.parse_error.106] parse error: array index '01' must not begin with '0'
[json.exception.parse_error.109] parse error: array index 'one' is not a number
[json.exception.out_of_range.401] array index 4 is out of range
[json.exception.out_of_range.402] array index '-' (2) is out of range
[json.exception.out_of_range.403] key 'foo' not found
[json.exception.out_of_range.404] unresolved reference token 'foo'
```
??? example “Example: (4) access specified element via JSON Pointer”
The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
that can be thrown.
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
using namespace nlohmann::literals;
int main()
{
// create a JSON value
const json j =
{
{"number", 1}, {"string", "foo"}, {"array", {1, 2}}
};
// read-only access
// output element with JSON pointer "/number"
std::cout << j.at("/number"_json_pointer) << '\n';
// output element with JSON pointer "/string"
std::cout << j.at("/string"_json_pointer) << '\n';
// output element with JSON pointer "/array"
std::cout << j.at("/array"_json_pointer) << '\n';
// output element with JSON pointer "/array/1"
std::cout << j.at("/array/1"_json_pointer) << '\n';
// out_of_range.109
try
{
// try to use an array index that is not a number
json::const_reference ref = j.at("/array/one"_json_pointer);
}
catch (const json::parse_error& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.401
try
{
// try to use an invalid array index
json::const_reference ref = j.at("/array/4"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.402
try
{
// try to use the array index '-'
json::const_reference ref = j.at("/array/-"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.403
try
{
// try to use a JSON pointer to a nonexistent object key
json::const_reference ref = j.at("/foo"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
// out_of_range.404
try
{
// try to use a JSON pointer that cannot be resolved
json::const_reference ref = j.at("/number/foo"_json_pointer);
}
catch (const json::out_of_range& e)
{
std::cout << e.what() << '\n';
}
}
```
Output:
```json
1
"foo"
[1,2]
2
[json.exception.parse_error.109] parse error: array index 'one' is not a number
[json.exception.out_of_range.401] array index 4 is out of range
[json.exception.out_of_range.402] array index '-' (2) is out of range
[json.exception.out_of_range.403] key 'foo' not found
[json.exception.out_of_range.404] unresolved reference token 'foo'
```
operator[] for unchecked access by referencevalue for access with default valuestd::string_view-convertible keys, as already supported by operator[], value, find, and other lookup functions.parse_error.109 instead of out_of_range.404 for a one-character array index that is not a digit (e.g., /x) in version 3.13.0, as it already did for longer ones.