Skip to content

Commit 75a3b00

Browse files
committed
docs: correct test-data vendoring and parse()/operator>> claims per review
- README: the JSONTestSuite data is downloaded from nlohmann/json_test_data at configure time, not vendored/committed; say so. - README: only the updated suite runs y_ and n_ cases through strict parse(); the original suite's y_ cases go through operator>>. Narrow the claim. - parsing/index.md and operator_gtgt.md: note that operator>> consumes a number's terminating byte, so concatenated numbers must be whitespace-separated (1 2 works, 1true does not); structural and literal values are unaffected. Signed-off-by: manon <youdie006@users.noreply.github.com>
1 parent b65b09d commit 75a3b00

3 files changed

Lines changed: 13 additions & 2 deletions

File tree

README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1824,9 +1824,9 @@ The library itself consists of a single header file licensed under the MIT licen
18241824

18251825
### Standards compliance
18261826

1827-
The library targets strict conformance with [RFC 8259](https://tools.ietf.org/html/rfc8259.html). Both the original [JSONTestSuite](https://github.com/nst/JSONTestSuite) and its updated revision are vendored and exercised in CI (see [`tests/src/unit-testsuites.cpp`](https://github.com/nlohmann/json/blob/develop/tests/src/unit-testsuites.cpp)):
1827+
The library targets strict conformance with [RFC 8259](https://tools.ietf.org/html/rfc8259.html). Both the original [JSONTestSuite](https://github.com/nst/JSONTestSuite) and its updated revision are exercised in CI; their test data is downloaded from [`nlohmann/json_test_data`](https://github.com/nlohmann/json_test_data) at configure time rather than committed to this repository (see [`tests/src/unit-testsuites.cpp`](https://github.com/nlohmann/json/blob/develop/tests/src/unit-testsuites.cpp)):
18281828

1829-
- All mandatory `y_` (must-accept) and `n_` (must-reject) cases pass through the strict [`parse()`](https://json.nlohmann.me/api/basic_json/parse/) entry point.
1829+
- The updated revision runs all mandatory `y_` (must-accept) and `n_` (must-reject) cases through the strict [`parse()`](https://json.nlohmann.me/api/basic_json/parse/) entry point; the original suite runs its `n_` cases through `parse()` and its `y_` cases through [`operator>>`](https://json.nlohmann.me/api/operator_gtgt/).
18301830
- The `i_` (implementation-defined) cases are, by RFC 8259, free to be accepted *or* rejected, so "passing all `i_` cases" is not a meaningful conformance metric. The library makes deliberate, documented choices there: nesting depth is not artificially limited, a leading UTF-8 byte order mark is silently ignored, [Unicode noncharacters](https://www.unicode.org/faq/private_use.html#nonchar1) are forwarded unchanged, invalid UTF-8 and lone/unpaired UTF-16 surrogates are rejected (stricter than required), and a number that cannot be stored without becoming `NaN`/`INF` raises [`out_of_range.406`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range406).
18311831

18321832
One behavioral nuance is worth calling out, because a superficial test often misreads it as non-compliance: [`parse()`](https://json.nlohmann.me/api/basic_json/parse/) is strict and rejects trailing data after a value, whereas [`operator>>`](https://json.nlohmann.me/api/operator_gtgt/) follows relaxed iostream semantics — it parses a single value and leaves the stream positioned right after it. Feeding "a valid document followed by trailing bytes" through `operator>>` reports success; the same input through `parse()` is rejected. This is a documented two-API design, not a conformance gap. See [**parsing**](https://json.nlohmann.me/features/parsing/) for details.

docs/mkdocs/docs/api/operator_gtgt.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,11 @@ input >> j1; // parses the first value, stream now positioned right after it
4242
input >> j2; // parses the next value
4343
```
4444

45+
A number is terminated only by the character that follows it, and `operator>>` consumes that character, so consecutive
46+
numbers must be whitespace-separated: `1 2` reads as two values, but in `1true` the terminating `t` is consumed together
47+
with the `1`, leaving `rue` in the stream so the next extraction fails. Structural and literal values are self-delimiting
48+
and are not affected.
49+
4550
Note this does **not** work for [JSON Lines](../features/parsing/json_lines.md) (newline-delimited JSON) input --
4651
see that page for why and for the recommended alternative.
4752

docs/mkdocs/docs/features/parsing/index.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,12 @@ what makes it possible to read several concatenated values from the same stream,
4040
document followed by trailing bytes" is accepted rather than rejected. If you are validating conformance, or need to
4141
reject any input that is not exactly one JSON document, prefer `parse`.
4242
43+
One caveat when relying on this for concatenated values: a number is terminated only by the character that follows it,
44+
and `operator>>` consumes that character, so consecutive numbers must be whitespace-separated. `1 2` reads as two
45+
values, but in `1true` the terminating `t` is consumed together with the `1`, leaving `rue` in the stream, so the next
46+
extraction fails. Structural and literal values (objects, arrays, strings, `true`/`false`/`null`) are self-delimiting
47+
and are not affected.
48+
4349
## SAX vs. DOM parsing
4450
4551
The library offers two parsing models:

0 commit comments

Comments
 (0)