External/json
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

📝 overwork documentation

Browse Source
This commit is contained in:
Niels Lohmann 2022-05-11 08:29:46 +02:00
parent fa14739448
commit 7942a158dc
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
4 changed files with 58 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/mkdocs/docs/api/basic_json/at.md
View File

@ -184,6 +184,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
## See also
- documentation on [checked access](../../features/element_access/checked_access.md)
- see [`operator[]`](operator%5B%5D.md) for unchecked access by reference
- see [`value`](value.md) for access with default value

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

@ -198,6 +198,8 @@ Strong exception safety: if an exception occurs, the original value stays intact
## See also
- documentation on [unchecked access](../../features/element_access/unchecked_access.md)
- documentation on [runtime assertions](../../features/assertions.md)
- see [`at`](at.md) for access by reference with range checking
- see [`value`](value.md) for access with default value

44
docs/mkdocs/docs/features/element_access/checked_access.md
View File

@ -2,9 +2,11 @@
## Overview
The `#!cpp at()` member function performs checked access; that is, it returns a reference to the desired value if it exists and throws a [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) otherwise.
The [`at`](../../api/basic_json/at.md) member function performs checked access; that is, it returns a reference to the
desired value if it exists and throws a [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range)
otherwise.
??? example
??? example "Read access"
Consider the following JSON value:
@ -18,18 +20,18 @@ The `#!cpp at()` member function performs checked access; that is, it returns a
Assume the value is parsed to a `json` variable `j`.
| expression | value |
| ---------- | ----- |
| `#!cpp j` | `#!json {"name": "Mary Smith", "age": 42, "hobbies": ["hiking", "reading"]}` |
| `#!cpp j.at("name")` | `#!json "Mary Smith"` |
| `#!cpp j.at("age")` | `#!json 42` |
| `#!cpp j.at("hobbies")` | `#!json ["hiking", "reading"]` |
| `#!cpp j.at("hobbies").at(0)` | `#!json "hiking"` |
| `#!cpp j.at("hobbies").at(1)` | `#!json "reading"` |
| expression | value |
|-------------------------------|------------------------------------------------------------------------------|
| `#!cpp j` | `#!json {"name": "Mary Smith", "age": 42, "hobbies": ["hiking", "reading"]}` |
| `#!cpp j.at("name")` | `#!json "Mary Smith"` |
| `#!cpp j.at("age")` | `#!json 42` |
| `#!cpp j.at("hobbies")` | `#!json ["hiking", "reading"]` |
| `#!cpp j.at("hobbies").at(0)` | `#!json "hiking"` |
| `#!cpp j.at("hobbies").at(1)` | `#!json "reading"` |
The return value is a reference, so it can be modified by the original value.
??? example
??? example "Write access"
```cpp
j.at("name") = "John Smith";
@ -45,9 +47,10 @@ The return value is a reference, so it can be modified by the original value.
}
```
When accessing an invalid index (i.e., an index greater than or equal to the array size) or the passed object key is non-existing, an exception is thrown.
When accessing an invalid index (i.e., an index greater than or equal to the array size) or the passed object key is
non-existing, an exception is thrown.
??? example
??? example "Accessing via invalid index or missing key"
```cpp
j.at("hobbies").at(3) = "cooking";
@ -59,13 +62,24 @@ When accessing an invalid index (i.e., an index greater than or equal to the arr
[json.exception.out_of_range.401] array index 3 is out of range
```
When you [extended diagnostic messages](../../home/exceptions.md#extended-diagnostic-messages) are enabled by
defining [`JSON_DIAGNOSTICS`](../../api/macros/json_diagnostics.md), the exception further gives information where
the key or index is missing or out of range.
```
[json.exception.out_of_range.401] (/hobbies) array index 3 is out of range
```
## Notes
!!! failure "Exceptions"
- `at` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error304) is thrown.
- [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) exceptions are thrown if the provided key is not found in an object or the provided index is invalid.
- [`at`](../../api/basic_json/at.md) can only be used with objects (with a string argument) or with arrays (with a
numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error304)
is thrown.
- [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) exceptions are thrown if the
provided key is not found in an object or the provided index is invalid.
## Summary

43
docs/mkdocs/docs/features/element_access/unchecked_access.md
View File

@ -2,9 +2,10 @@
## Overview
Elements in a JSON object and a JSON array can be accessed via `#!cpp operator[]` similar to a `#!cpp std::map` and a `#!cpp std::vector`, respectively.
Elements in a JSON object and a JSON array can be accessed via [`operator[]`](../../api/basic_json/operator%5B%5D.md)
similar to a `#!cpp std::map` and a `#!cpp std::vector`, respectively.
??? example
??? example "Read access"
Consider the following JSON value:
@ -18,18 +19,19 @@ Elements in a JSON object and a JSON array can be accessed via `#!cpp operator[]
Assume the value is parsed to a `json` variable `j`.
| expression | value |
| ---------- | ----- |
| `#!cpp j` | `#!json {"name": "Mary Smith", "age": 42, "hobbies": ["hiking", "reading"]}` |
| `#!cpp j["name"]` | `#!json "Mary Smith"` |
| `#!cpp j["age"]` | `#!json 42` |
| `#!cpp j["hobbies"]` | `#!json ["hiking", "reading"]` |
| `#!cpp j["hobbies"][0]` | `#!json "hiking"` |
| `#!cpp j["hobbies"][1]` | `#!json "reading"` |
| expression | value |
|-------------------------|------------------------------------------------------------------------------|
| `#!cpp j` | `#!json {"name": "Mary Smith", "age": 42, "hobbies": ["hiking", "reading"]}` |
| `#!cpp j["name"]` | `#!json "Mary Smith"` |
| `#!cpp j["age"]` | `#!json 42` |
| `#!cpp j["hobbies"]` | `#!json ["hiking", "reading"]` |
| `#!cpp j["hobbies"][0]` | `#!json "hiking"` |
| `#!cpp j["hobbies"][1]` | `#!json "reading"` |
The return value is a reference, so it can modify the original value. In case the passed object key is non-existing, a `#!json null` value is inserted which can be immediately be overwritten.
The return value is a reference, so it can modify the original value. In case the passed object key is non-existing, a
`#!json null` value is inserted which can be immediately be overwritten.
??? example
??? example "Write access"
```cpp
j["name"] = "John Smith";
@ -47,9 +49,10 @@ The return value is a reference, so it can modify the original value. In case th
}
```
When accessing an invalid index (i.e., an index greater than or equal to the array size), the JSON array is resized such that the passed index is the new maximal index. Intermediate values are filled with `#!json null`.
When accessing an invalid index (i.e., an index greater than or equal to the array size), the JSON array is resized such
that the passed index is the new maximal index. Intermediate values are filled with `#!json null`.
??? example
??? example "Filling up arrays with `#!json null` values"
```cpp
j["hobbies"][0] = "running";
@ -76,17 +79,23 @@ When accessing an invalid index (i.e., an index greater than or equal to the arr
- `#!cpp std::vector::operator[]` never inserts a new element.
- `#!cpp std::map::operator[]` is not available for const values.
The type `#!cpp json` wraps all JSON value types. It would be impossible to remove `operator[]` for const objects. At the same time, inserting elements for non-const objects is really convenient as it avoids awkward `insert` calls. To this end, we decided to have an inserting non-const behavior for both arrays and objects.
The type `#!cpp json` wraps all JSON value types. It would be impossible to remove
[`operator[]`](../../api/basic_json/operator%5B%5D.md) for const objects. At the same time, inserting elements for
non-const objects is really convenient as it avoids awkward `insert` calls. To this end, we decided to have an
inserting non-const behavior for both arrays and objects.
!!! info
The access is unchecked. In case the passed object key does not exist or the passed array index is invalid, no exception is thrown.
The access is unchecked. In case the passed object key does not exist or the passed array index is invalid, no
exception is thrown.
!!! danger
- It is **undefined behavior** to access a const object with a non-existing key.
- It is **undefined behavior** to access a const array with an invalid index.
- In debug mode, an **assertion** will fire in both cases. You can disable assertions by defining the preprocessor symbol `#!cpp NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](../macros.md#json_assertx).
- In debug mode, an **assertion** will fire in both cases. You can disable assertions by defining the preprocessor
symbol `#!cpp NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](../macros.md#json_assertx). See the documentation
on [runtime assertions](../assertions.md) for more information.
!!! failure "Exceptions"