json/features/parsing/json_lines.md

JSON Lines

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

1. The input must be UTF-8 encoded.
2. Every line must be a valid JSON value.
3. The line separator must be \n. As \r is silently ignored, \r\n is also supported.
4. 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 and throw
a [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) exception. The same happens for a
stream of *concatenated* (non-newline-delimited) JSON values: `operator>>` reads them one at a time, but the loop
above throws after the last value. To read either format with `operator>>`, check for the end of the stream before
each read:

```cpp
json j;
while (input >> std::ws && input.peek() != std::char_traits<char>::eof())
{
    input >> j;
    std::cout << j << std::endl;
}
```

A value that is a number must be followed by whitespace -- see the [notes](../../api/operator_gtgt.md#notes) of
`operator>>` for details.