mirror of
https://github.com/nlohmann/json.git
synced 2026-10-02 12:40:32 +00:00
Niels Lohmann
63c10a51fc
* Review and extend the documentation, and check it in CI A review of all documentation pages found factual errors, dead links, missing cross-references, and gaps in examples. This fixes them and adds checks so the same problems are caught automatically. Fixes: - wrong signatures and version histories (operator!= C++20 member, binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...) - stale descriptions (number parsing since #5283, UBJSON table, SAX example that no longer compiled, tsl::ordered_map advice) - dead internal and external links; repology.org badges (the domain is suspended) replaced by badges that query the registries directly - deprecation notes link the migration guide; the guide itself fixed Additions: - "See also" sections, cross-references, 25 runnable examples, 12 Mermaid diagrams, new API pages for json_pointer::operator<=> and byte_container_with_subtype::operator==/!= - landing page, guides for untrusted input and performance - "unreleased" badge after versions newer than the latest release Checks: - strict documentation build (broken links/anchors fail it); CI and the publish workflow fetch the full history the build needs - weekly external link check, Mermaid syntax check in CI - check_structure.py: example titles, heading levels, alt texts, header links, docset index coverage; its unused-example check works again - all examples produce the same output on every platform Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Keep the customer links that could not be fixed A dead link on the customers page is still the evidence of where the use of the library was documented. Keep the original URLs of the entries without a working replacement (Marne, Cisco Webex Desk Camera, Philips Hue, CyberArk) and exclude exactly these URLs from the link check. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct the duplicate-key recipe's claim about SAX positions The SAX interface's key() receives no position either; only parse_error() does. Also note that the recipe does not report the path to the repeated key (see discussion #5085). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Say the library is available as a single header and mention json_fwd.hpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Correct documentation errors found while hunting for bugs - patch/patch_inplace: list the JSON pointer errors parse_error.106-109 and out_of_range.402/404, and quote the actual parse_error.105 message. - unflatten: list parse_error.106/107/108 and out_of_range.404. - to_bson: list out_of_range.415 (binary subtype above 255) and note that 412 and 415 are new in 3.13.0. - to_string: state that string_t must be convertible to std::string, also in the StringType requirements table. - JSON Lines: a `while (input >> j)` loop also throws after the last value for concatenated JSON values; show a loop that works for both. - BON8: a string gets 0xFF only if nothing follows it in the message; a string at the end of an array or object is ended by 0xFE. - custom_string_type.hpp: add operator+=(char), which the "Always required" list asks for (json_pointer::to_string, flatten, unflatten, and diff did not compile), and an ADL int_to_string for diff and items. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Cache the release headers with functools.lru_cache Codacy (Pylint) flagged the mutable default argument that header() used as its cache. functools.lru_cache keeps the same memoization without it. The script's output is unchanged. Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2.7 KiB
2.7 KiB
nlohmann::basic_json::is_discarded
constexpr bool is_discarded() const noexcept;
This function returns #!cpp true for a JSON value if either:
- the value was discarded during parsing with a callback function (see
parser_callback_t), or - the value is the result of parsing invalid JSON with parameter
allow_exceptionsset to#!cpp false; seeparsefor more information.
Return value
#!cpp true if type is discarded, #!cpp false otherwise.
Exception safety
No-throw guarantee: this member function never throws exceptions.
Complexity
Constant.
Notes
!!! note "Comparisons"
Discarded values are never compared equal with [`operator==`](operator_eq.md). That is, checking whether a JSON
value `j` is discarded will only work via:
```cpp
j.is_discarded()
```
because
```cpp
j == json::value_t::discarded
```
will always be `#!cpp false`.
!!! note "Removal during parsing with callback functions"
When a value is discarded by a callback function (see [`parser_callback_t`](parser_callback_t.md)) during parsing,
then it is removed when it is part of a structured value. For instance, if the second value of an array is discarded,
instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. If the top-level value
itself is discarded by the callback, the `parse` call returns a `#!json null` value.
After a successful parse, this function always returns #!cpp false: discarded values can only occur during parsing and
are either removed when inside a structured value or replaced by #!json null at the top level. The exception is parsing
with allow_exceptions set to #!cpp false: a parse error then yields a discarded value for which this function returns
#!cpp true (see parse).
Examples
??? example "Example: is_discarded() for ordinary JSON values"
The following code exemplifies `is_discarded()` for all JSON types.
```cpp
--8<-- "examples/is_discarded.cpp"
```
Output:
```json
--8<-- "examples/is_discarded.output"
```
??? example "Example: discarded values from parsing"
The following code shows the two situations in which a discarded value can be observed: parsing invalid JSON with
`allow_exceptions` set to `#!cpp false`, and a parser callback that discards the top-level value (which is replaced
by `#!json null` and therefore does *not* remain discarded).
```cpp
--8<-- "examples/is_discarded__parse.cpp"
```
Output:
```json
--8<-- "examples/is_discarded__parse.output"
```
Version history
- Added in version 1.0.0.