docs: fix NaN ordering, FILE* locking and binary integer-range statements (#6088)

* docs: state that NaN ordering inside containers depends on the standard

When the element-wise comparison of arrays or objects reaches a NaN and
a number (or another NaN) before any other difference, the result
depends on the language standard. Before C++20 the pair counts as
equivalent and the following elements (or the sizes) decide, so
[1] <= [NaN] is true. Since C++20 the comparison is unordered and
<, <=, >, >= all yield false. Document this on operator<, <=, >, >=
and <=>.

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

* docs: fix the FILE* notes of parse() and the locking promise

The performance note of parse() said a FILE* is read one character at a
time. With glibc and the Apple C library the characters in the FILE's
buffer are scanned in bulk; only elsewhere is it one character at a
time. The file is locked once only where the C library has unlocked
stdio functions (not on musl, MinGW, newlib, with
JSON_DISABLE_UNLOCKED_FILE_IO, or under MSan). Qualify the promise on
parse.md, sax_parse.md, the parsing page and the performance page.

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

* docs: fix integer ranges in the MessagePack and BJData tables

number_integer_t is std::int64_t, so number_integer cannot hold values
above 9223372036854775807; those are number_unsigned. The MessagePack
row for uint 64 listed the range up to 18446744073709551615, and the
BJData table had a uint64 row for number_integer that can never be
selected. The CBOR table was already corrected.

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

* docs: name the macros that turn off FILE* locking and bulk scans

parse() and sax_parse() now say that the FILE* is locked unless
JSON_DISABLE_UNLOCKED_FILE_IO is defined to 1, and the input-source
table and the performance page name JSON_DISABLE_STREAM_BULK_SCAN and
JSON_DISABLE_UNLOCKED_FILE_IO with what each turns off.

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

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann authored and GitHub committed 2026-11-12 08:40:05 +01:00
1 parent 03ad4a3e7f
commit 07aa3d1d69
11 files changed
+62 -14

No files matched your search

@@ -88,7 +88,6 @@ The library uses the following mapping from JSON values types to BJData types ac
| number_integer | 65536..2147483647 | int32 | `l` |
| number_integer | 2147483648..4294967295 | uint32 | `m` |
| number_integer | 4294967296..9223372036854775807 | int64 | `L` |
| number_integer | 9223372036854775808..18446744073709551615 | uint64 | `M` |
| number_unsigned | 0..127 | int8 | `i` |
| number_unsigned | 128..255 | uint8 | `U` |
| number_unsigned | 256..32767 | int16 | `I` |