Reorganize directories (#3462)

* 🦃 move files * 🦃 rename doc folder to docs * 🦃 rename test folder to tests
2026-07-11 21:15:10 +00:00 · 2022-05-01 09:41:50 +02:00
parent 5352856f04
commit b21c345179
865 changed files with 52 additions and 51 deletions
@@ -0,0 +1,209 @@
+# <small>nlohmann::basic_json::</small>operator[]
+
+```cpp
+// (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;
+```
+
+1. Returns a reference to the array element at specified location `idx`.
+2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by value.
+3. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
+   `#!cpp typename object_comparator_t::is_transparent` denotes a type.
+4. Returns a reference to the element with specified JSON pointer `ptr`.
+
+## Template parameters
+
+`KeyType`
+:   A type for an object key other than [`json_pointer`](../json_pointer/index.md) that is comparable with
+    [`string_t`](string_t.md) using  [`object_comparator_t`](object_comparator_t.md).
+    This can also be a string view (C++17).
+
+## Parameters
+
+`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
+    
+## Return value
+
+1. (const) reference to the element at index `idx`
+2. (const) reference to the element at key `key`
+3. (const) reference to the element at key `key`
+4. (const) reference to the element pointed to by `ptr`
+
+## Exception safety
+
+Strong exception safety: if an exception occurs, the original value stays intact.
+
+## Exceptions
+
+1. The function can throw the following exceptions:
+    - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
+      or null; in that case, using the `[]` operator with an index makes no sense.
+2. The function can throw the following exceptions:
+    - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an object
+      or null; in that case, using the `[]` operator with a key makes no sense.
+3. See 2.
+4. The function can throw the following exceptions:
+    - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
+      JSON pointer `ptr` begins with '0'.
+    - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
+      JSON pointer `ptr` is not a number.
+    - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used
+      in the passed JSON pointer `ptr` for the const version.
+    - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
+      not be resolved.
+
+## Complexity
+
+1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`.
+2. Logarithmic in the size of the container.
+3. Logarithmic in the size of the container.
+4. Logarithmic in the size of the container.
+
+## Notes
+
+!!! 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)**!
+
+1. 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.
+
+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
+   make `key` a valid reference. In case the value was `#!json null` before, it is converted to an object.
+
+3. See 2.
+
+4. `null` values are created in arrays and objects if necessary.
+   
+    In particular:
+
+    - If the JSON pointer points to an object key that does not exist, it is created and filled with a `#!json null`
+      value before a reference to it is returned.
+    - If the JSON pointer points to an array index that does not exist, it is created and filled with a `#!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`.
+    - The special value `-` is treated as a synonym for the index past the end.
+
+## Examples
+
+??? 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/operatorarray__size_type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operatorarray__size_type.output"
+    ```
+
+??? example "Example (1): access specified array element"
+
+    The example below shows how array elements can be read using the `[]` operator.
+
+    ```cpp
+    --8<-- "examples/operatorarray__size_type_const.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operatorarray__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/operatorarray__key_type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operatorarray__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/operatorarray__key_type_const.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operatorarray__key_type_const.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/operatorjson_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operatorjson_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/operatorjson_pointer_const.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operatorjson_pointer_const.output"
+    ```
+
+## See also
+
+- see [`at`](at.md) for access by reference with range checking
+- see [`value`](value.md) for access with default value
+
+## Version history
+
+1. Added in version 1.0.0.
+2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) in version 3.11.0.
+3. Added in version 3.11.0.
+4. Added in version 2.0.0.