1# basic_json::operator[] 2 3```cpp 4// (1) 5reference operator[](size_type idx); 6const_reference operator[](size_type idx) const; 7 8// (2) 9reference operator[](const typename object_t::key_type& key); 10const_reference operator[](const typename object_t::key_type& key) const; 11template<typename T> 12reference operator[](T* key); 13template<typename T> 14const_reference operator[](T* key) const; 15 16// (3) 17reference operator[](const json_pointer& ptr); 18const_reference operator[](const json_pointer& ptr) const; 19``` 20 211. Returns a reference to the element at specified location `idx`. 222. Returns a reference to the element at with specified key `key`. 233. Returns a reference to the element at with specified JSON pointer `ptr`. 24 25## Template parameters 26 27`T` 28: string literal convertible to `object_t::key_type` 29 30## Parameters 31 32`idx` (in) 33: index of the element to access 34 35`key` (in) 36: object key of the elements to remove 37 38`ptr` (in) 39: JSON pointer to the desired element 40 41## Return value 42 431. reference to the element at index `idx` 442. reference to the element at key `key` 453. reference to the element pointed to by `ptr` 46 47## Exceptions 48 491. The function can throw the following exceptions: 50 - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array 51 or null; in that cases, using the `[]` operator with an index makes no sense. 522. The function can throw the following exceptions: 53 - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array 54 or null; in that cases, using the `[]` operator with an index makes no sense. 553. The function can throw the following exceptions: 56 - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed 57 JSON pointer `ptr` begins with '0'. 58 - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed 59 JSON pointer `ptr` is not a number. 60 - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used 61 in the passed JSON pointer `ptr` for the const version. 62 - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can 63 not be resolved. 64 65## Notes 66 67!!! danger 68 69 1. If the element with key `idx` does not exist, the behavior is undefined. 70 2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by an assertion**! 71 721. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), then the 73 array is silently filled up with `#!json null` values to make `idx` a valid reference to the last stored element. In 74 case the value was `#!json null` before, it is converted to an array. 75 762. If `key` is not found in the object, then it is silently added to the object and filled with a `#!json null` value to 77 make `key` a valid reference. In case the value was `#!json null` before, it is converted to an object. 78 793. `null` values are created in arrays and objects if necessary. 80 81 In particular: 82 83 - If the JSON pointer points to an object key that does not exist, it is created an filled with a `#!json null` 84 value before a reference to it is returned. 85 - If the JSON pointer points to an array index that does not exist, it is created an filled with a `#!json null` 86 value before a reference to it is returned. All indices between the current maximum and the given index are also 87 filled with `#!json null`. 88 - The special value `-` is treated as a synonym for the index past the end. 89 90## Exception safety 91 92Strong exception safety: if an exception occurs, the original value stays intact. 93 94## Complexity 95 961. Constant if `idx` is in the range of the array. Otherwise linear in `idx - size()`. 972. Logarithmic in the size of the container. 983. Constant 99 100## Example 101 102??? example 103 104 The example below shows how array elements can be read and written using `[]` operator. Note the addition of 105 `#!json null` values. 106 107 ```cpp 108 --8<-- "examples/operatorarray__size_type.cpp" 109 ``` 110 111 Output: 112 113 ```json 114 --8<-- "examples/operatorarray__size_type.output" 115 ``` 116 117??? example 118 119 The example below shows how array elements can be read using the `[]` operator. 120 121 ```cpp 122 --8<-- "examples/operatorarray__size_type_const.cpp" 123 ``` 124 125 Output: 126 127 ```json 128 --8<-- "examples/operatorarray__size_type_const.output" 129 ``` 130 131??? example 132 133 The example below shows how object elements can be read and written using the `[]` operator. 134 135 ```cpp 136 --8<-- "examples/operatorarray__key_type.cpp" 137 ``` 138 139 Output: 140 141 ```json 142 --8<-- "examples/operatorarray__key_type.output" 143 ``` 144 145??? example 146 147 The example below shows how object elements can be read using the `[]` operator. 148 149 ```cpp 150 --8<-- "examples/operatorarray__key_type_const.cpp" 151 ``` 152 153 Output: 154 155 ```json 156 --8<-- "examples/operatorarray__key_type_const.output" 157 ``` 158 159??? example 160 161 The example below shows how values can be read and written using JSON Pointers. 162 163 ```cpp 164 --8<-- "examples/operatorjson_pointer.cpp" 165 ``` 166 167 Output: 168 169 ```json 170 --8<-- "examples/operatorjson_pointer.output" 171 ``` 172 173??? example 174 175 The example below shows how values can be read using JSON Pointers. 176 177 ```cpp 178 --8<-- "examples/operatorjson_pointer_const.cpp" 179 ``` 180 181 Output: 182 183 ```json 184 --8<-- "examples/operatorjson_pointer_const.output" 185 ``` 186 187## Version history 188 1891. Added in version 1.0.0. 1902. Added in version 1.0.0. Overloads for `T* key` added in version 1.1.0. 1913. Added in version 2.0.0. 192