// (1) reference operator[](size_type idx); const_reference operator[](size_type idx) const; // (2) reference operator[](typename object_t::key_type key); const_reference operator[](const typename object_t::key_type& key) const; // (3) template<typename KeyType> reference operator[](KeyType&& key); template<typename KeyType> const_reference operator[](KeyType&& key) const; // (4) reference operator[](const json_pointer& ptr); const_reference operator[](const json_pointer& ptr) const;
idx
.key
. The non-const qualified overload takes the key by value.KeyType
is comparable with #!cpp typename object_t::key_type
and #!cpp typename object_comparator_t::is_transparent
denotes a type.ptr
.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 element 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.305
if the JSON value is not an array or null; in that case, using the []
operator with an index makes no sense.type_error.305
if the JSON value is not an object or null; in that case, using the []
operator with a key makes no sense.parse_error.106
if an array index in the passed JSON pointer ptr
begins with ‘0’.parse_error.109
if an array index in the passed JSON pointer ptr
is not a number.out_of_range.402
if the array index ‘-’ is used in the passed JSON pointer ptr
for the const version.out_of_range.404
if the JSON pointer ptr
can not be resolved.idx
is in the range of the array. Otherwise, linear in idx - size()
.!!! danger “Undefined behavior and runtime assertions”
1. If the element with key `idx` does not exist, the behavior is undefined. 2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by a [runtime assertion](../../features/assertions.md)**!
The non-const version may add values: If idx
is beyond the range of the array (i.e., idx >= size()
), then the array is silently filled up with #!json null
values to make idx
a valid reference to the last stored element. In case the value was #!json null
before, it is converted to an array.
If key
is not found in the object, then it is silently added to the object and filled with a #!json null
value to make key
a valid reference. In case the value was #!json null
before, it is converted to an object.
See 2.
null
values are created in arrays and objects if necessary.
In particular:
#!json null
value before a reference to it is returned.#!json null
value before a reference to it is returned. All indices between the current maximum and the given index are also filled with #!json null
.-
is treated as a synonym for the index past the end.??? example “Example: (1) access specified array element”
The example below shows how array elements can be read and written using `[]` operator. Note the addition of `#!json null` values. ```cpp --8<-- "examples/operator_array__size_type.cpp" ``` Output: ```json --8<-- "examples/operator_array__size_type.output" ```
??? example “Example: (1) access specified array element (const)”
The example below shows how array elements can be read using the `[]` operator. ```cpp --8<-- "examples/operator_array__size_type_const.cpp" ``` Output: ```json --8<-- "examples/operator_array__size_type_const.output" ```
??? example “Example: (2) access specified object element”
The example below shows how object elements can be read and written using the `[]` operator. ```cpp --8<-- "examples/operator_array__object_t_key_type.cpp" ``` Output: ```json --8<-- "examples/operator_array__object_t_key_type.output" ```
??? example “Example: (2) access specified object element (const)”
The example below shows how object elements can be read using the `[]` operator. ```cpp --8<-- "examples/operator_array__object_t_key_type_const.cpp" ``` Output: ```json --8<-- "examples/operator_array__object_t_key_type_const.output" ```
??? example “Example: (3) access specified object element using string_view”
The example below shows how object elements can be read using the `[]` operator. ```cpp --8<-- "examples/operator_array__keytype.c++17.cpp" ``` Output: ```json --8<-- "examples/operator_array__keytype.c++17.output" ```
??? example “Example: (3) access specified object element using string_view (const)”
The example below shows how object elements can be read using the `[]` operator. ```cpp --8<-- "examples/operator_array__keytype_const.c++17.cpp" ``` Output: ```json --8<-- "examples/operator_array__keytype_const.c++17.output" ```
??? example “Example: (4) access specified element via JSON Pointer”
The example below shows how values can be read and written using JSON Pointers. ```cpp --8<-- "examples/operator_array__json_pointer.cpp" ``` Output: ```json --8<-- "examples/operator_array__json_pointer.output" ```
??? example “Example: (4) access specified element via JSON Pointer (const)”
The example below shows how values can be read using JSON Pointers. ```cpp --8<-- "examples/operator_array__json_pointer_const.cpp" ``` Output: ```json --8<-- "examples/operator_array__json_pointer_const.output" ```
at
for access by reference with range checkingvalue
for access with default valueT* key
in version 1.1.0. Removed overloads for T* key
(replaced by 3) in version 3.11.0.