lib/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2025-07-29 23:01:16 +03:00
Code Activity

📝 add more API documentation

Browse Source
This commit is contained in:
Niels Lohmann
2020-08-12 14:29:25 +02:00
parent fe89049aee
commit 874f49e945
22 changed files with 285 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
doc/mkdocs/docs/api/basic_json/operator[].md
View File

@ -47,51 +47,45 @@ const_reference operator[](const json_pointer& ptr) const;
## 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
cases, using the `[]` operator with an index makes no sense.
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
or null; in that cases, 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 array or null; in that
cases, using the `[]` operator with an index makes no sense.
- Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array
or null; in that cases, using the `[]` operator with an index makes no sense.
3. 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.
- 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.
## Notes
!!! danger
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 an assertion**!
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 an assertion**!
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.
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.
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. `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 an filled with a `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 an filled with a `null` value before a reference to it
is returned. All indices between the current maximum and the given
index are also filled with `null`.
- The special value `-` is treated as a synonym for the index past the
end.
- If the JSON pointer points to an object key that does not exist, it is created an 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 an 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.
## Exception safety
@ -107,9 +101,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
??? example
The example below shows how array elements can be read and
written using `[]` operator. Note the addition of `null`
values.
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"
@ -123,8 +116,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
??? example
The example below shows how array elements can be read using
the `[]` operator.
The example below shows how array elements can be read using the `[]` operator.
```cpp
--8<-- "examples/operatorarray__size_type_const.cpp"
@ -138,8 +130,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
??? example
The example below shows how object elements can be read and
written using the `[]` operator.
The example below shows how object elements can be read and written using the `[]` operator.
```cpp
--8<-- "examples/operatorarray__key_type.cpp"
@ -153,8 +144,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
??? example
The example below shows how object elements can be read using
the `[]` operator.
The example below shows how object elements can be read using the `[]` operator.
```cpp
--8<-- "examples/operatorarray__key_type_const.cpp"