ceph/src/jaegertracing/opentelemetry-cpp/third_party/nlohmann-json/doc/mkdocs/docs/api/basic_json/operator[].md

   1 # <small>nlohmann::basic_json::</small>operator[]
   2
   3 ```cpp
   4 // (1)
   5 reference operator[](size_type idx);
   6 const_reference operator[](size_type idx) const;
   7
   8 // (2)
   9 reference operator[](const typename object_t::key_type& key);
  10 const_reference operator[](const typename object_t::key_type& key) const;
  11 template<typename T>
  12 reference operator[](T* key);
  13 template<typename T>
  14 const_reference operator[](T* key) const;
  15
  16 // (3)
  17 reference operator[](const json_pointer& ptr);
  18 const_reference operator[](const json_pointer& ptr) const;
  19 ```
  20
  21 1. Returns a reference to the array element at specified location `idx`.
  22 2. Returns a reference to the object element at with specified key `key`.
  23 3. 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 element to access
  37
  38 `ptr` (in)
  39 :   JSON pointer to the desired element
  40
  41 ## Return value
  42
  43 1. reference to the element at index `idx`
  44 2. reference to the element at key `key`
  45 3. reference to the element pointed to by `ptr`
  46
  47 ## Exception safety
  48
  49 Strong exception safety: if an exception occurs, the original value stays intact.
  50
  51 ## Exceptions
  52
  53 1. The function can throw the following exceptions:
  54     - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
  55       or null; in that case, using the `[]` operator with an index makes no sense.
  56 2. The function can throw the following exceptions:
  57     - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an object
  58       or null; in that case, using the `[]` operator with a key makes no sense.
  59 3. The function can throw the following exceptions:
  60     - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
  61       JSON pointer `ptr` begins with '0'.
  62     - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
  63       JSON pointer `ptr` is not a number.
  64     - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used
  65       in the passed JSON pointer `ptr` for the const version.
  66     - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
  67       not be resolved.
  68
  69 ## Complexity
  70
  71 1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
  72 2. Logarithmic in the size of the container.
  73 3. Constant
  74
  75 ## Notes
  76
  77 !!! danger
  78
  79     1. If the element with key `idx` does not exist, the behavior is undefined.
  80     2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by an assertion**!
  81
  82 1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), then the
  83    array is silently filled up with `#!json null` values to make `idx` a valid reference to the last stored element. In
  84    case the value was `#!json null` before, it is converted to an array.
  85
  86 2. If `key` is not found in the object, then it is silently added to the object and filled with a `#!json null` value to
  87    make `key` a valid reference. In case the value was `#!json null` before, it is converted to an object.
  88
  89 3. `null` values are created in arrays and objects if necessary.
  90
  91     In particular:
  92
  93     - If the JSON pointer points to an object key that does not exist, it is created and filled with a `#!json null`
  94       value before a reference to it is returned.
  95     - If the JSON pointer points to an array index that does not exist, it is created and filled with a `#!json null`
  96       value before a reference to it is returned. All indices between the current maximum and the given index are also
  97       filled with `#!json null`.
  98     - The special value `-` is treated as a synonym for the index past the end.
  99
 100 ## Examples
 101
 102 ??? example "Example (1): access specified array element"
 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 "Example (1): access specified array element"
 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 "Example (2): access specified object element"
 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 "Example (2): access specified object element"
 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 "Example (3): access specified element via JSON Pointer"
 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 "Example (3): access specified element via JSON Pointer"
 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 ## See also
 188
 189 - see [`at`](at.md) for access by reference with range checking
 190 - see [`value`](value.md) for access with default value
 191
 192 ## Version history
 193
 194 1. Added in version 1.0.0.
 195 2. Added in version 1.0.0. Overloads for `T* key` added in version 1.1.0.
 196 3. Added in version 2.0.0.