// (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
idx
key
key
ptr
Strong 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 example below.out_of_range.401
if the index idx
is out of range of the array; that is, idx >= size()
. See 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 example below.out_of_range.403
if the key key
is not stored in the object; that is, find(key) == end()
. See example below.parse_error.106
if an array index in the passed JSON pointer ptr
begins with ‘0’. See example below.parse_error.109
if an array index in the passed JSON pointer ptr
is not a number. See example below.out_of_range.401
if an array index in the passed JSON pointer ptr
is out of range. See 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 example below.out_of_range.403
if the JSON pointer describes a key of an object which cannot be found. See example below.out_of_range.404
if the JSON pointer ptr
can not be resolved. See example below.??? 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 --8<-- "examples/at__size_type.cpp" ``` Output: ```json --8<-- "examples/at__size_type.output" ```
??? 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 --8<-- "examples/at__size_type_const.cpp" ``` Output: ```json --8<-- "examples/at__size_type_const.output" ```
??? 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 --8<-- "examples/at__object_t_key_type.cpp" ``` Output: ```json --8<-- "examples/at__object_t_key_type.output" ```
??? 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 --8<-- "examples/at__object_t_key_type_const.cpp" ``` Output: ```json --8<-- "examples/at__object_t_key_type_const.output" ```
??? 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 --8<-- "examples/at__keytype.c++17.cpp" ``` Output: ```json --8<-- "examples/at__keytype.c++17.output" ```
??? 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 --8<-- "examples/at__keytype_const.c++17.cpp" ``` Output: ```json --8<-- "examples/at__keytype_const.c++17.output" ```
??? 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 --8<-- "examples/at__json_pointer.cpp" ``` Output: ```json --8<-- "examples/at__json_pointer.output" ```
??? 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 --8<-- "examples/at__json_pointer_const.cpp" ``` Output: ```json --8<-- "examples/at__json_pointer_const.output" ```
operator[]
for unchecked access by referencevalue
for access with default value