// (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).
For the non-const versions 1. and 4., when passing an array index that does not exist, it is created and filled with a #!json null value before a reference to it is returned. For this, a reallocation can happen, in which case all iterators (including the end() iterator) and all references to the elements are invalidated.
For ordered_json, also passing an object key to the non-const versions 2., 3., and 4., a reallocation can happen which again invalidates all iterators and all references.
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
idxkeykeyptrStrong 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.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).idx is in the range of the array. Otherwise, linear in idx - size().!!! danger “Undefined behavior and runtime assertions”
The following cases apply to the **const** overloads; the non-const overloads instead insert the missing element (see the notes below). 1. If the element at index `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.!!! note “Creating intermediate levels that don't exist yet”
When the JSON pointer traverses intermediate levels that don't exist at all yet (not just a missing leaf), each missing level is created as an array or an object depending on whether the corresponding pointer token parses as a non-negative integer: a numeric token creates an array, a non-numeric token creates an object. For example, on an initially `#!json null` value, `/foo/0/0/0` creates nested arrays, while `/foo/one/one/one` creates nested objects. This is not specified by the JSON Pointer RFC; it is this library's own, intentional disambiguation rule. See also [JSON Pointer](../../features/json_pointer.md).
??? 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.std::string_view-convertible keys, as already supported by at, value, find, and other lookup functions.