mirror of
https://github.com/nlohmann/json.git
synced 2026-07-11 13:05:11 +00:00
Niels Lohmann
e9c3985f0a
* 📡 Fix documentation gaps found in a full GitHub Discussions review 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> * 🚶 fix format Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
1.7 KiB
1.7 KiB
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\ris silently ignored,\r\nis 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 -- see its [notes](../../api/operator_gtgt.md#notes) for details.