Niels Lohmann
ddffd920d0
Keep both sides in lexer.hpp (lookahead detection next to the new bulk-scan detection) and in the operator>> version history. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
3.8 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:
std::istringstream input("1true[2]");
json j1, j2, j3;
input >> j1; // j1 == 1, stream now positioned right after it
input >> j2; // j2 == true
input >> j3; // j3 == [2]
!!! note "Changed behavior for numbers"
A number is the only value whose end can be detected solely by reading the character that follows it. Up to
version 3.13.0 that character was consumed and not put back, so the stream was left one byte too far whenever a
number was immediately followed by another value: reading `1true` yielded `1` and left the stream at `rue`.
Values had to be separated by whitespace to work around this.
The terminating character is now only looked at and left in the stream, so no separator is required. Code that
relied on the extra byte being swallowed will observe it again.
Note that reading concatenated values does not work for JSON Lines (newline-delimited JSON) input -- see that page for why and for the recommended alternative.
By default, a '\0' (NUL) byte encountered while reading a value is treated as end of input, rather than as an
ordinary (and, outside of a string, invalid) byte; see the FAQ entry for
details and the JSON_STRICT_NUL_HANDLING macro to opt into rejecting it
instead. Because operator>> only parses a single value and does not require the rest of the stream to be consumed,
a NUL byte after a complete value has no effect on operator>> either way; it only matters while a value is still
being read.
!!! 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
- accept - check if the input is valid JSON
- parse - deserialize from a compatible input
JSON_STRICT_NUL_HANDLING- opt in to rejecting a NUL byte in the input instead of treating it as end of input
Version history
- Added in version 1.0.0.
- Changed in version 4.0.0 to leave the character that terminates a number in the stream, so that the stream is positioned right after the parsed value for every value type.
JSON_STRICT_NUL_HANDLINGadded in version 3.13.0 to optionally reject a NUL byte in the input instead of treating it as end of input; planned to become the default in version 4.0.0.