mirror of
https://github.com/nlohmann/json.git
synced 2026-07-10 12:35:09 +00:00
Niels Lohmann
40f3caad4d
Reviewed all 1008 GitHub Discussions (2020-2026) for recurring questions that better or more visible documentation would have avoided. Adds/expands documentation for ~26 distinct gaps, including: - New "Debugging" page collecting natvis, GDB pretty printer, LLDB status, and JSON_DIAGNOSTICS pointers (previously scattered/undiscoverable) - Thread-safety and schema-validation FAQ entries - StringType's char-based requirement (no wstring/u16string/u32string) - Brace-initialization-yields-arrays warning directly on the constructor reference page (previously only in the FAQ, missed by users reading the constructor docs) - std::any exclusion from get<T>(), with a manual-dispatch example - Non-string-keyed std::map serializing as an array of pairs - ordered_json compatibility with NLOHMANN_DEFINE_TYPE_* macros (already worked, was undocumented) - std::array truncation on size-mismatched conversion (no exception) - static_cast vs. get<std::optional<T>>() divergence - Recipe for omitting a std::optional field instead of emitting null - No built-in nesting-depth limit during parsing + a callback-based workaround recipe - Recipe for streaming a large homogeneous array via parser callbacks - operator>> stream-position semantics for concatenated JSON values - JSON Pointer array-vs-object creation rule for non-existing paths - CMake target name (nlohmann_json_modules) needed to link C++20 modules - ESP-IDF/PlatformIO: no official package, link to a community fork - get(key, default) as the Python dict.get() equivalent - reserve() recipe for pre-allocating array capacity - JSONC as an alias for the existing ignore_comments/ignore_trailing_commas combination (distinct from the unsupported JSON5) - items() dereferenced-element type: decltype() idiom + detail-namespace stability caveat - Various macro/type-conversion limitations (MSGPACK_DEFINE_ARRAY equivalent, char-array round-tripping, ADL serializer macro gap) Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2.0 KiB
2.0 KiB
nlohmann::operator>>(basic_json)
std::istream& operator>>(std::istream& i, basic_json& j);
Deserializes an input stream to a JSON value.
Parameters
i(in, out)- input stream to read a serialized JSON value from
j(in, out)- JSON value to write the deserialized input to
Return value
the stream i
Exceptions
- Throws
parse_error.101in case of an unexpected token.
Complexity
Linear in the length of the input. The parser is a predictive LL(1) parser.
Notes
A UTF-8 byte order mark is silently ignored.
Invalid Unicode escapes and unpaired surrogates in the input are reported as
parse_error.101 with a detailed message.
operator>> parses exactly one JSON value and leaves the stream positioned right after it, so it can be called
repeatedly to read a sequence of concatenated JSON values from the same stream:
json j1, j2;
input >> j1; // parses the first value, stream now positioned right after it
input >> j2; // parses the next value
Note this does not work for JSON Lines (newline-delimited JSON) input -- see that page for why and for the recommended alternative.
!!! warning "Deprecation"
This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has
been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;`
with `#!cpp i >> j;`.
Examples
??? example
The example below shows how a JSON value is constructed by reading a serialization from a stream.
```cpp
--8<-- "examples/operator_deserialize.cpp"
```
Output:
```json
--8<-- "examples/operator_deserialize.output"
```
See also
Version history
- Added in version 1.0.0.