json/docs/mkdocs/docs/api/operator_gtgt.md

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

Exception safety

Strong guarantee: if an exception is thrown, there are no changes in j.

Exceptions

• Throws parse_error.101 in case of an unexpected token, or if i has no stream buffer (#!cpp i.rdbuf() == nullptr, for instance #!cpp std::istream(nullptr)).
• If reading from i reaches the end of the input and eofbit is part of i's exceptions() mask, the std::ios_base::failure thrown by i itself propagates instead of a parse_error, the same as it would for the standard library's own extraction operators.

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, 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
input >> j2;  // parses the next value

!!! warning "A number must be followed by whitespace"

A number is only terminated by the character that follows it. That character is read from the stream to detect the
end of the number, and it is **not** put back. When a value that is a number is immediately followed by the next
value, the first character of that next value is lost:

```cpp
std::istringstream input("1true");
json j1, j2;
input >> j1;  // j1 == 1
input >> j2;  // throws parse_error.101: the stream now starts at "rue"
```

Separating the values with whitespace avoids this, because the character that is eaten is then the separator:

```cpp
std::istringstream input("1 true");
json j1, j2;
input >> j1;  // j1 == 1
input >> j2;  // j2 == true
```

Only numbers are affected. Values ending in a self-delimiting character do not read past themselves, so
`truefalse`, `[1][2]`, `{"a":1}{"b":2}`, and `"a""b"` can be read back to back without a separator.

Define [`JSON_PRECISE_STREAM_POSITION`](macros/json_precise_stream_position.md) to `1` to leave the terminating character in the stream
instead, so that the stream is positioned right after the value for every value type and no separator is
needed. This is tracked in [#5340](https://github.com/nlohmann/json/issues/5340).

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;`.

See the [migration guide](../integration/migration_guide.md#parsing) for how to update existing code.

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
• JSON_PRECISE_STREAM_POSITION - opt in to leaving the stream positioned right after a number
• JSON_DISABLE_STREAM_BULK_SCAN - read the stream one character at a time

Version history

• Added in version 1.0.0.
• JSON_STRICT_NUL_HANDLING added 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.
• JSON_PRECISE_STREAM_POSITION added in version 3.13.0 to optionally leave the character that terminates a number in the stream; planned to become the default in version 4.0.0.
• Fixed a null pointer dereference for an std::istream without a stream buffer (now throws parse_error.101), and a crash (std::terminate) when i has eofbit in its exception mask, in version 3.13.0.
• Changed to the strong exception safety guarantee in version 3.13.0: j is no longer left with a partially parsed value if parsing throws.
• Scans the characters in the stream buffer of i in bulk in version 3.13.0; the position of i after the call is unchanged (JSON_DISABLE_STREAM_BULK_SCAN restores reading one character at a time).