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>

docs/mkdocs/docs/api/basic_json/operator_ge.md

@@ -60,6 +60,14 @@ Linear.
       2. Comparing a `NaN` with another `NaN`.
       3. Comparing a `NaN` and any other number.
 
+    For arrays and objects, the elements are compared in order. If the comparison 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: for instance, `[NaN] < [1, NaN]` and
+    `[1] <= [NaN]` are `#!cpp true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all
+    yield `#!cpp false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the
+    same for all language standards. The same program can therefore order such values differently when it is compiled
+    with a different language standard.
+
 !!! note "Operator overload resolution"
 
     Since C++20 overload resolution will consider the _rewritten candidate_ generated from

docs/mkdocs/docs/api/basic_json/operator_gt.md

@@ -60,6 +60,14 @@ Linear.
       2. Comparing a `NaN` with another `NaN`.
       3. Comparing a `NaN` and any other number.
 
+    For arrays and objects, the elements are compared in order. If the comparison 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: for instance, `[NaN] < [1, NaN]` and
+    `[1] <= [NaN]` are `#!cpp true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all
+    yield `#!cpp false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the
+    same for all language standards. The same program can therefore order such values differently when it is compiled
+    with a different language standard.
+
 !!! note "Operator overload resolution"
 
     Since C++20 overload resolution will consider the _rewritten candidate_ generated from

docs/mkdocs/docs/api/basic_json/operator_le.md

@@ -61,6 +61,14 @@ Linear.
       2. Comparing a `NaN` with another `NaN`.
       3. Comparing a `NaN` and any other number.
 
+    For arrays and objects, the elements are compared in order. If the comparison 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: for instance, `[NaN] < [1, NaN]` and
+    `[1] <= [NaN]` are `#!cpp true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all
+    yield `#!cpp false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the
+    same for all language standards. The same program can therefore order such values differently when it is compiled
+    with a different language standard.
+
 !!! note "Operator overload resolution"
 
     Since C++20 overload resolution will consider the _rewritten candidate_ generated from

docs/mkdocs/docs/api/basic_json/operator_lt.md

@@ -71,6 +71,14 @@ Linear.
       2. Comparing a `NaN` with another `NaN`.
       3. Comparing a `NaN` and any other number.
 
+    For arrays and objects, the elements are compared in order. If the comparison 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: for instance, `[NaN] < [1, NaN]` and
+    `[1] <= [NaN]` are `#!cpp true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all
+    yield `#!cpp false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the
+    same for all language standards. The same program can therefore order such values differently when it is compiled
+    with a different language standard.
+
 !!! note "Operator overload resolution"
 
     Since C++20 overload resolution will consider the _rewritten candidate_ generated from

docs/mkdocs/docs/api/basic_json/operator_spaceship.md

@@ -55,6 +55,10 @@ Linear.
         1. Comparing a `NaN` with itself.
         2. Comparing a `NaN` with another `NaN`.
         3. Comparing a `NaN` and any other number.
+    - For arrays and objects, the elements are compared in order. If the comparison reaches a `NaN` and a number (or
+      another `NaN`) before any other difference, the result is `std::partial_ordering::unordered`. (Without C++20, the
+      comparison operators `<`, `<=`, `>`, and `>=` use the comparison of the containers, which treats such a pair as
+      equivalent; see [**operator<**](operator_lt.md).)
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json/parse.md

@@ -130,11 +130,13 @@ outside of a string, invalid) byte; see the [FAQ entry](../../home/faq.md#nul-by
 
     Contiguous inputs (strings, string views, vectors, arrays, pointer ranges) are the fastest to parse. A
     `#!cpp std::istream` comes close: the parser scans the characters its stream buffer holds in bulk, without reading
-    ahead, so the stream is left exactly where it would be after reading one character at a time. A `#!cpp FILE*` is
-    read one character at a time, but the file is locked only once, so other threads that use the same `FILE` object
-    wait until parsing is done. See [input sources and performance](../../features/parsing/index.md#input-sources-and-performance),
-    [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md), and
-    [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md).
+    ahead, so the stream is left exactly where it would be after reading one character at a time. With glibc
+    and the Apple C library, the characters the `#!cpp FILE` holds in its buffer are scanned in bulk like a stream's;
+    elsewhere a `#!cpp FILE*` is read one character at a time. Where the C library has unlocked stdio functions, the
+    file is locked only once, so other threads that use the same `FILE` object wait until parsing is done, unless
+    [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) is defined to `1`. See
+    [input sources and performance](../../features/parsing/index.md#input-sources-and-performance) and
+    [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md).
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json/sax_parse.md

@@ -124,9 +124,10 @@ consumer `sax` has a super-linear complexity.
 
 A UTF-8 byte order mark is silently ignored.
 
-When reading from a `#!c FILE*`, the file is locked while it is parsed. The lock is recursive, so the SAX handler may
-use the same file with stdio functions, but it must not wait for another thread that uses the same `FILE` object; see
-[`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md).
+When reading from a `#!c FILE*` where the C library has unlocked stdio functions, the file is locked while it is parsed,
+unless [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) is defined to `1`.
+The lock is recursive, so the SAX handler may use the same file with stdio functions, but it must not wait for another
+thread that uses the same `FILE` object.
 
 ## Examples