1# <small>nlohmann::basic_json::</small>operator[] 2 3```cpp 4// (1) 5reference operator[](size_type idx); 6const_reference operator[](size_type idx) const; 7 8// (2) 9reference operator[](typename object_t::key_type key); 10const_reference operator[](const typename object_t::key_type& key) const; 11 12// (3) 13template<typename KeyType> 14reference operator[](KeyType&& key); 15template<typename KeyType> 16const_reference operator[](KeyType&& key) const; 17 18// (4) 19reference operator[](const json_pointer& ptr); 20const_reference operator[](const json_pointer& ptr) const; 21``` 22 231. Returns a reference to the array element at specified location `idx`. 242. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by 25 value. 263. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and 27 `#!cpp typename object_comparator_t::is_transparent` denotes a type. 284. Returns a reference to the element with specified JSON pointer `ptr`. 29 30## Template parameters 31 32`KeyType` 33: A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with 34 [`string_t`](string_t.md) using [`object_comparator_t`](object_comparator_t.md). 35 This can also be a string view (C++17). 36 37## Parameters 38 39`idx` (in) 40: index of the element to access 41 42`key` (in) 43: object key of the element to access 44 45`ptr` (in) 46: JSON pointer to the desired element 47 48## Return value 49 501. (const) reference to the element at index `idx` 512. (const) reference to the element at key `key` 523. (const) reference to the element at key `key` 534. (const) reference to the element pointed to by `ptr` 54 55## Exception safety 56 57Strong exception safety: if an exception occurs, the original value stays intact. 58 59## Exceptions 60 611. The function can throw the following exceptions: 62 - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array 63 or null; in that case, using the `[]` operator with an index makes no sense. 642. The function can throw the following exceptions: 65 - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an object 66 or null; in that case, using the `[]` operator with a key makes no sense. 673. See 2. 684. The function can throw the following exceptions: 69 - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed 70 JSON pointer `ptr` begins with '0'. 71 - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed 72 JSON pointer `ptr` is not a number. 73 - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used 74 in the passed JSON pointer `ptr` for the const version. 75 - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can 76 not be resolved. 77 78## Complexity 79 801. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`. 812. Logarithmic in the size of the container. 823. Logarithmic in the size of the container. 834. Logarithmic in the size of the container. 84 85## Notes 86 87!!! danger "Undefined behavior and runtime assertions" 88 89 1. If the element with key `idx` does not exist, the behavior is undefined. 90 2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by a 91 [runtime assertion](../../features/assertions.md)**! 92 931. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), then the 94 array is silently filled up with `#!json null` values to make `idx` a valid reference to the last stored element. In 95 case the value was `#!json null` before, it is converted to an array. 96 972. If `key` is not found in the object, then it is silently added to the object and filled with a `#!json null` value to 98 make `key` a valid reference. In case the value was `#!json null` before, it is converted to an object. 99 1003. See 2. 101 1024. `null` values are created in arrays and objects if necessary. 103 104 In particular: 105 106 - If the JSON pointer points to an object key that does not exist, it is created and filled with a `#!json null` 107 value before a reference to it is returned. 108 - If the JSON pointer points to an array index that does not exist, it is created and filled with a `#!json null` 109 value before a reference to it is returned. All indices between the current maximum and the given index are also 110 filled with `#!json null`. 111 - The special value `-` is treated as a synonym for the index past the end. 112 113## Examples 114 115??? example "Example: (1) access specified array element" 116 117 The example below shows how array elements can be read and written using `[]` operator. Note the addition of 118 `#!json null` values. 119 120 ```cpp 121 --8<-- "examples/operator_array__size_type.cpp" 122 ``` 123 124 Output: 125 126 ```json 127 --8<-- "examples/operator_array__size_type.output" 128 ``` 129 130??? example "Example: (1) access specified array element (const)" 131 132 The example below shows how array elements can be read using the `[]` operator. 133 134 ```cpp 135 --8<-- "examples/operator_array__size_type_const.cpp" 136 ``` 137 138 Output: 139 140 ```json 141 --8<-- "examples/operator_array__size_type_const.output" 142 ``` 143 144??? example "Example: (2) access specified object element" 145 146 The example below shows how object elements can be read and written using the `[]` operator. 147 148 ```cpp 149 --8<-- "examples/operator_array__object_t_key_type.cpp" 150 ``` 151 152 Output: 153 154 ```json 155 --8<-- "examples/operator_array__object_t_key_type.output" 156 ``` 157 158??? example "Example: (2) access specified object element (const)" 159 160 The example below shows how object elements can be read using the `[]` operator. 161 162 ```cpp 163 --8<-- "examples/operator_array__object_t_key_type_const.cpp" 164 ``` 165 166 Output: 167 168 ```json 169 --8<-- "examples/operator_array__object_t_key_type_const.output" 170 ``` 171 172??? example "Example: (3) access specified object element using string_view" 173 174 The example below shows how object elements can be read using the `[]` operator. 175 176 ```cpp 177 --8<-- "examples/operator_array__keytype.c++17.cpp" 178 ``` 179 180 Output: 181 182 ```json 183 --8<-- "examples/operator_array__keytype.c++17.output" 184 ``` 185 186??? example "Example: (3) access specified object element using string_view (const)" 187 188 The example below shows how object elements can be read using the `[]` operator. 189 190 ```cpp 191 --8<-- "examples/operator_array__keytype_const.c++17.cpp" 192 ``` 193 194 Output: 195 196 ```json 197 --8<-- "examples/operator_array__keytype_const.c++17.output" 198 ``` 199 200??? example "Example: (4) access specified element via JSON Pointer" 201 202 The example below shows how values can be read and written using JSON Pointers. 203 204 ```cpp 205 --8<-- "examples/operator_array__json_pointer.cpp" 206 ``` 207 208 Output: 209 210 ```json 211 --8<-- "examples/operator_array__json_pointer.output" 212 ``` 213 214??? example "Example: (4) access specified element via JSON Pointer (const)" 215 216 The example below shows how values can be read using JSON Pointers. 217 218 ```cpp 219 --8<-- "examples/operator_array__json_pointer_const.cpp" 220 ``` 221 222 Output: 223 224 ```json 225 --8<-- "examples/operator_array__json_pointer_const.output" 226 ``` 227 228## See also 229 230- documentation on [unchecked access](../../features/element_access/unchecked_access.md) 231- documentation on [runtime assertions](../../features/assertions.md) 232- see [`at`](at.md) for access by reference with range checking 233- see [`value`](value.md) for access with default value 234 235## Version history 236 2371. Added in version 1.0.0. 2382. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) 239 in version 3.11.0. 2403. Added in version 3.11.0. 2414. Added in version 2.0.0. 242