mirror of https://github.com/nlohmann/json.git synced 2026-08-10 11:13:17 +00:00

Files

T

Niels LohmannandGitHub 31ba5208c8 docs: qualify the operator>> stream positioning guarantee (#5343 )

operator>>'s notes state that it leaves the stream positioned right
after the parsed value, so that concatenated JSON values can be read
back to back. That does not hold when the value is a number: a number
is only terminated by the character that follows it, and the lexer's
unget() is simulated (it rewinds only the lexer's own bookkeeping),
so that character stays consumed from the stream.

Document the actual behaviour: the guarantee holds for all value types
except numbers, which must be followed by whitespace. Also qualify the
cross-reference on the JSON Lines page, which repeated the unqualified
claim.

Documentation only; the behaviour itself is tracked in #5340.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-08-03 08:18:03 +02:00

1.8 KiB

Raw Blame History

JSON Lines

The JSON Lines format is a text format of newline-delimited JSON. In particular:

The input must be UTF-8 encoded.
Every line must be a valid JSON value.
The line separator must be \n. As \r is silently ignored, \r\n is also supported.
The final character may be \n, but is not required to be one.

!!! example "JSON Text example"

```json
{"name": "Gilbert", "wins": [["straight", "7♣"], ["one pair", "10♥"]]}
{"name": "Alexa", "wins": [["two pair", "4♠"], ["two pair", "9♠"]]}
{"name": "May", "wins": []}
{"name": "Deloise", "wins": [["three of a kind", "5♣"]]}
```

JSON Lines input with more than one value is treated as invalid JSON by the parse or accept functions. To process it line by line, functions like std::getline can be used:

!!! example "Example: Parse JSON Text input line by line"

The example below demonstrates how JSON Lines can be processed.

```cpp
--8<-- "examples/json_lines.cpp"
```

Output:

```json
--8<-- "examples/json_lines.output"
```

!!! warning "Note"

Using [`operator>>`](../../api/operator_gtgt.md) like

```cpp
json j;
while (input >> j)
{
    std::cout << j << std::endl;
}
```

with a JSON Lines input does not work, because the parser will try to parse one value after the last one.

This is different from parsing a stream of *concatenated* (non-newline-delimited) JSON values, for which
`operator>>` does work, provided that a value that is a number is followed by whitespace -- see its
[notes](../../api/operator_gtgt.md#notes) for details.

1.8 KiB Raw Blame History

JSON Lines

1.8 KiB

Raw Blame History