amorfo77/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-09-12 03:07:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

Complete documentation for 3.11.0 (#3464)

Browse Source 
* 👥 update contributor and sponsor list

* 🚧 document BJData format

* 🚧 document BJData format

* 📝 clarified documentation of [json.exception.parse_error.112]

* ✏️ adjust titles

* 📝 add more examples

* 🚨 adjust warnings for index.md files

* 📝 add more examples

* 🔥 remove example for deprecated code

* 📝 add missing enum entry

* 📝 overwork table for binary formats

* ✅ add test to create table for binary formats

* 📝 fix wording in example

* 📝 add more examples

* Update iterators.md (#3481)

* ✨ add check for overloads to linter #3455

* 👥 update contributor list

* 📝 add more examples

* 📝 fix documentation

* 📝 add more examples

* 🎨 fix indentation

* 🔥 remove example for destructor

* 📝 overwork documentation

* Updated BJData documentation, #3464 (#3493)

* update bjdata.md for #3464

* Minor edit

* Fix URL typo

* Add info on demoting ND array to a 1-D optimized array when singleton dimension

Co-authored-by: Chaoqi Zhang <prncoprs@163.com>
Co-authored-by: Qianqian Fang <fangqq@gmail.com>
This commit is contained in:
Niels Lohmann
2022-05-17 13:08:56 +02:00
committed by GitHub
co-authored by Chaoqi Zhang Qianqian Fang
parent a8a547d7a2
commit 6a7392058e
102 changed files with 1990 additions and 247 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/mkdocs/docs/features/element_access/checked_access.md
+29 -15
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
docs/mkdocs/docs/features/element_access/unchecked_access.md
+26 -17
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"