mirror of
https://github.com/nlohmann/json.git
synced 2026-10-25 23:38:58 +00:00
Docs: fill documentation gaps found in user questions
Add pages on class-hierarchy/smart-pointer/variant/chrono recipes, working without exceptions, and large, streamed and partial input. Extend the FAQ (23 entries, Known bugs first), parse error documentation (empty-input checklist, line/column, diagnostic positions), element access, conversions, creating values, ADL troubleshooting, memory, and build/distribution notes. Add 14 examples with generated output. Correct the statement that parse errors cannot be recovered from with -fno-exceptions. The topics come from recurring questions on Stack Overflow, Reddit, Hacker News, YouTube, and the project's GitHub discussions and issues. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
45 files changed
+1666
-8
No files matched your search
@@ -21,3 +21,42 @@ flowchart TD
|
||||
A --> F{"just testing first?"}
|
||||
F -->|"yes"| G["contains() / find()"]
|
||||
```
|
||||
|
||||
## Does this key exist?
|
||||
|
||||
Use [`contains`](../../api/basic_json/contains.md) to test for a key; it does not modify the value and does not throw:
|
||||
|
||||
```cpp
|
||||
json j = {{"name", "Mary"}, {"address", {{"city", "Berlin"}}}};
|
||||
|
||||
j.contains("name"); // true
|
||||
j.contains("age"); // false
|
||||
j.contains("city"); // false: contains() only looks at the top level
|
||||
j["address"].contains("city"); // true
|
||||
j.contains(json::json_pointer("/address/city")); // true: a JSON pointer tests a nested path in one call
|
||||
```
|
||||
|
||||
If the value is needed afterwards, [`find`](../../api/basic_json/find.md) tests and accesses with a single lookup:
|
||||
|
||||
```cpp
|
||||
if (auto it = j.find("name"); it != j.end())
|
||||
{
|
||||
std::cout << *it << '\n';
|
||||
}
|
||||
```
|
||||
|
||||
`contains` also returns `true` for a key whose value is `null`; use `j.contains("k") && !j["k"].is_null()` if a
|
||||
`null` should count as missing. To read a value with a fallback instead, see [`value`](default_value.md).
|
||||
|
||||
!!! warning "`operator[]` inserts missing keys"
|
||||
|
||||
Like `#!cpp std::map::operator[]`, the non-const [`operator[]`](unchecked_access.md) adds a `null` value if the key
|
||||
is missing. Testing a key with it therefore *changes the object*:
|
||||
|
||||
```cpp
|
||||
json j = {{"foo", 1}};
|
||||
bool absent = j["bar"].is_null(); // true, but j is now {"bar": null, "foo": 1}
|
||||
```
|
||||
|
||||
Use `contains`/`find` to test, and [`at`](checked_access.md) to access a value that must exist (it throws an
|
||||
[`out_of_range`](../../home/exceptions.md#out-of-range) exception otherwise).
|
||||
Reference in new issue
Block a user