This commit is contained in:
nlohmann committed 2026-10-27 12:14:00 +00:00
1 parent b36f8a9821
commit 11a863958e
1180 files changed
+14211 -6025

No files matched your search

+26 -12
View File
@@ -10,16 +10,23 @@ There are many ways elements in a JSON value can be accessed:
Testing whether a key or index exists before accessing it is also possible, with [`contains`](https://json.nlohmann.me/api/basic_json/contains/index.md) or [`find`](https://json.nlohmann.me/api/basic_json/find/index.md) (which returns an iterator to the value, or `end()` if it is not found).
How do I get a value out? Start at the top and follow the first question that applies:
```
flowchart TD
A["accessing a value"] --> B{"must it exist?"}
B -->|"yes, missing is an error"| C["at() -- throws"]
B -->|"yes, but checking is my job"| D["operator[] -- unchecked"]
B -->|"no, a fallback is fine"| E["value() -- default value"]
A --> F{"just testing first?"}
F -->|"yes"| G["contains() / find()"]
A["getting a value out"] --> P{{"nested path such as /server/port?"}}
P -->|"yes"| JP["JSON Pointer: at(ptr), value(ptr, default), contains(ptr)"]
P -->|"no, one key or index"| T{{"only testing whether it exists?"}}
T -->|"yes"| CF["contains() / find()"]
T -->|"no"| M{{"may it be missing?"}}
M -->|"yes, a fallback is fine"| V["value(key, default)"]
M -->|"yes, and missing is an error"| AT["at(): throws out_of_range"]
M -->|"no, it exists and its type is known"| OP["operator[] and get#lt;T#gt;()"]
OP -.- W["non-const operator[] inserts null for a missing key"]
```
Decision tree for reading a value: the labels on the arrows are the answers to the questions, and the boxes name the functions to use. The dashed line marks a side effect of the non-const `operator[]`.
## Does this key exist?
Use [`contains`](https://json.nlohmann.me/api/basic_json/contains/index.md) to test for a key; it does not modify the value and does not throw:
@@ -58,9 +65,16 @@ Use `contains`/`find` to test, and [`at`](https://json.nlohmann.me/features/elem
## See also
- [**operator[]**](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md) - unchecked access
- [**at**](https://json.nlohmann.me/api/basic_json/at/index.md) - checked access
- [**value**](https://json.nlohmann.me/api/basic_json/value/index.md) - access with default value
- [**contains**](https://json.nlohmann.me/api/basic_json/contains/index.md) and [**find**](https://json.nlohmann.me/api/basic_json/find/index.md) - test for existence
- [**front**](https://json.nlohmann.me/api/basic_json/front/index.md) and [**back**](https://json.nlohmann.me/api/basic_json/back/index.md) - first and last element
- [**items**](https://json.nlohmann.me/api/basic_json/items/index.md) - iterate over keys and values
- [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md) - unchecked access
- [`at`](https://json.nlohmann.me/api/basic_json/at/index.md) - checked access
- [`value`](https://json.nlohmann.me/api/basic_json/value/index.md) - access with default value
- [`contains`](https://json.nlohmann.me/api/basic_json/contains/index.md) - and [`find`](https://json.nlohmann.me/api/basic_json/find/index.md) - test for existence
- [`front`](https://json.nlohmann.me/api/basic_json/front/index.md) - and [`back`](https://json.nlohmann.me/api/basic_json/back/index.md) - first and last element
- [`items`](https://json.nlohmann.me/api/basic_json/items/index.md) - iterate over keys and values
- [Checked access: at](https://json.nlohmann.me/features/element_access/checked_access/index.md) - access with range checking
- [Unchecked access: operator[]](https://json.nlohmann.me/features/element_access/unchecked_access/index.md) - access without range checking
- [Access with default value: value](https://json.nlohmann.me/features/element_access/default_value/index.md) - fall back to a default instead of throwing
- [Iterators](https://json.nlohmann.me/features/iterators/index.md) - visit all elements of arrays and objects
- [JSON Pointer](https://json.nlohmann.me/features/json_pointer/index.md) - address nested values with a single string
- [Modifying values](https://json.nlohmann.me/features/modifying_values/index.md) - add, merge and remove elements
- [`basic_json`](https://json.nlohmann.me/api/basic_json/index.md) - all member functions