Fix contradictions between the documentation, the README, and the library (#5825)

- Discarded values: the legacy macro only changes <= and >=; != is true by default
- Out-of-range numbers are rejected while parsing, not stored as NaN
- merge_diff round trip: point to the ordered_json caveat
- ensure_ascii example shows the escaped output
- out_of_range.405 is thrown for "remove"/"move" on the root, not "add"
- CBOR stores binary subtypes as tags
- Integer/float comparison uses exact values, not conversion
- diff, flatten, and the binary writers are depth-bounded
- FAQ: max_digits10 for serialization, trailing commas are supported
- out_of_range.407 is still thrown by to_bon8
- FetchContent_MakeAvailable needs CMake 3.14
- json_fwd.hpp contents, operator< link, RFC 7396 for merge patch
- README: dump() wording, merge_diff, MSYS2/build2, patch comment typos,
  operator[] link, embedded CMake example aligned with the docs

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann authored and GitHub committed 2026-10-14 17:40:55 +02:00
1 parent 00170dab38
commit ccc005c012
22 files changed
+85 -64

No files matched your search

+15 -5
View File
@@ -889,7 +889,9 @@ contains other characters (e.g., `1a`), or `-` where it cannot be used.
### json.exception.out_of_range.405
The JSON Patch operations 'remove' and 'add' cannot be applied to the root element of the JSON value.
The JSON Patch operations 'remove' and 'move' cannot be applied to the root element of the JSON value. The exception is
also thrown when the parent or a reference token of an empty JSON Pointer is requested, for instance by
[`back`](../api/json_pointer/back.md) or [`pop_back`](../api/json_pointer/pop_back.md).
!!! failure "Example message"
@@ -914,15 +916,23 @@ double-precision number when `number_float_t` is `#!cpp float`.
### json.exception.out_of_range.407
This exception previously indicated that the UBJSON and BSON binary formats did not support integer numbers greater than
9223372036854775807 due to limitations in the implemented mapping. However, these limitations have since been resolved,
and this exception no longer occurs.
An unsigned integer number greater than 9223372036854775807 cannot be represented in the binary format. This exception
is only thrown by [`to_bon8`](../api/basic_json/to_bon8.md), as [BON8](../features/binary_formats/bon8.md) has no
unsigned 64-bit integer type.
!!! success "Exception cannot occur any more"
!!! note "Former occurrences"
The UBJSON and BSON writers used to throw this exception as well:
- Since version 3.9.0, integer numbers beyond int64 are serialized as high-precision UBJSON numbers.
- Since version 3.12.0, integer numbers beyond int64 are serialized as uint64 BSON numbers.
!!! failure "Example message"
```
integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
```
### json.exception.out_of_range.408
The size of an array or object in a [binary format](../features/binary_formats/index.md) exceeds the maximal capacity:
+6 -4
View File
@@ -66,7 +66,9 @@ Without the macro (default behavior), `json j{obj}` creates `[{"key":"value"}]`.
Can you add an option to ignore trailing commas?
This library does not support any feature that would jeopardize interoperability.
Yes, trailing commas in arrays and objects can be allowed by setting parameter `ignore_trailing_commas` of
[`parse`](../api/basic_json/parse.md) to `#!cpp true`; see [trailing commas](../features/trailing_commas.md). They are
rejected by default, and the library never adds them when serializing.
### Parse errors reading non-ASCII characters
@@ -230,11 +232,11 @@ Yes, you can. Please define the symbol [`JSON_DIAGNOSTICS`](../api/macros/json_d
- It seems that precision is lost when serializing a double.
- Can I change the precision for floating-point serialization?
The library uses `std::numeric_limits<number_float_t>::digits10` (15 for IEEE `double`s) digits for serialization. This value is sufficient to guarantee roundtripping. If one uses more than this number of digits of precision, then string -> value -> string is not guaranteed to round-trip.
The library serializes floating-point numbers with the shortest representation that parses back to the same value, using at most `std::numeric_limits<number_float_t>::max_digits10` (17 for IEEE `double`s) significant digits. This guarantees that value -> string -> value round-trips. The reverse direction, string -> value -> string, is only guaranteed for numbers with at most `std::numeric_limits<number_float_t>::digits10` (15 for IEEE `double`s) significant digits; a number with more digits may not be representable exactly and is then serialized as the closest `double`.
!!! quote "[cppreference.com](https://en.cppreference.com/w/cpp/types/numeric_limits/digits10)"
!!! quote "[cppreference.com](https://en.cppreference.com/w/cpp/types/numeric_limits/max_digits10)"
The value of `std::numeric_limits<T>::digits10` is the number of base-10 digits that can be represented by the type T without change, that is, any number with this many significant decimal digits can be converted to a value of type T and back to decimal form, without change due to rounding or overflow.
The value of `std::numeric_limits<T>::max_digits10` is the number of base-10 digits that are necessary to uniquely represent all distinct values of the type T, such as necessary for serialization/deserialization to text.
!!! tip