deploy: ef1cdb59ac

api/basic_json/to_bjdata.md

@@ -212,4 +212,6 @@ Linear in the size of the JSON value `j`.
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
-  array or object was silently skipped, producing invalid BJData.
+  array or object was silently skipped, producing invalid BJData.
+- Writes unsigned integers wider than 64 bits as high-precision numbers since version 3.13.0; previously, they were
+  silently truncated to 64 bits.

api/basic_json/to_bjdata/index.md

@@ -189,3 +189,4 @@ Output:
 - BJData version parameter (for draft3 binary encoding) added in version 3.12.0.
 - Added `error_handler` parameter in version 3.13.0 unreleased. Its default, `keep`, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before; `strict` (the default if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0 unreleased; previously, a discarded value nested in an array or object was silently skipped, producing invalid BJData.
+- Writes unsigned integers wider than 64 bits as high-precision numbers since version 3.13.0 unreleased; previously, they were silently truncated to 64 bits.

api/basic_json/to_bon8.md

@@ -37,8 +37,9 @@ With (2), the bytes written before the exception remain in the output adapter.
 
 ## Exceptions
 
-- Throws [out_of_range.407](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains an unsigned integer
-  above 9223372036854775807, which BON8 cannot represent
+- Throws [out_of_range.407](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains an integer outside
+  the range of int64 (an unsigned integer above 9223372036854775807, or, with a number type wider than 64 bits, any
+  integer beyond int64), which BON8 cannot represent
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if `j` contains a string that is not
   valid UTF-8
 - Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is

api/basic_json/to_bon8/index.md

@@ -33,7 +33,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
-- Throws [out_of_range.407](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains an unsigned integer above 9223372036854775807, which BON8 cannot represent
+- Throws [out_of_range.407](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains an integer outside the range of int64 (an unsigned integer above 9223372036854775807, or, with a number type wider than 64 bits, any integer beyond int64), which BON8 cannot represent
 - Throws [type_error.316](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if `j` contains a string that is not valid UTF-8
 - Throws [type_error.321](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error321) if `j` or a value nested in it is discarded; example: `"cannot serialize discarded value to BON8"`
 

api/basic_json/to_bson.md

@@ -47,6 +47,10 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 - Throws [`type_error.317`](../../home/exceptions.md#jsonexceptiontype_error317) if the top-level type of the JSON value
   is not an object; example: `"to serialize to BSON, top-level type must be object, but is string"`
+- Throws [`out_of_range.407`](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains a signed integer
+  outside the range of int64 or an unsigned integer outside the range of uint64, which is only possible with a number
+  type wider than 64 bits; example:
+  `"integer number 9223372036854775808 cannot be represented by BSON as it does not fit int64"`
 - Throws [`out_of_range.409`](../../home/exceptions.md#jsonexceptionout_of_range409) if a key in the JSON object contains
   a null byte (code point U+0000); example: `"BSON key cannot contain code point U+0000 (at byte 2)"`
 - Throws [`out_of_range.412`](../../home/exceptions.md#jsonexceptionout_of_range412) if the length of a document, array,
@@ -166,3 +170,5 @@ pass before anything is written.
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316` before anything
   is written.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0; previously, integers of a
+  number type wider than 64 bits were silently truncated.

api/basic_json/to_bson/index.md

@@ -39,6 +39,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 ## Exceptions
 
 - Throws [`type_error.317`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error317) if the top-level type of the JSON value is not an object; example: `"to serialize to BSON, top-level type must be object, but is string"`
+- Throws [`out_of_range.407`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains a signed integer outside the range of int64 or an unsigned integer outside the range of uint64, which is only possible with a number type wider than 64 bits; example: `"integer number 9223372036854775808 cannot be represented by BSON as it does not fit int64"`
 - Throws [`out_of_range.409`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range409) if a key in the JSON object contains a null byte (code point U+0000); example: `"BSON key cannot contain code point U+0000 (at byte 2)"`
 - Throws [`out_of_range.412`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range412) if the length of a document, array, string, or binary value exceeds the range of the 32-bit BSON length field; example: `"BSON length 2147483661 exceeds maximum of 2147483647"`
 - Throws [`out_of_range.415`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range415) if the subtype of a binary value exceeds 255, the maximum of the BSON binary subtype; example: `"subtype 70000 is too large for the BSON binary subtype (max 255)"`
@@ -139,3 +140,4 @@ Output:
 - `out_of_range.415` is now detected before anything is written, like the other exceptions above, since version 3.13.0 unreleased.
 - Throws `type_error.321` for a discarded value nested in `j` since version 3.13.0 unreleased; previously, it was silently skipped, producing a document whose declared size did not match what was actually written.
 - Added `error_handler` parameter in version 3.13.0 unreleased. Its default, `keep`, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before; `strict` (the default if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled) throws `type_error.316` before anything is written.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0 unreleased; previously, integers of a number type wider than 64 bits were silently truncated.

api/basic_json/to_cbor.md

@@ -46,6 +46,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
+- Throws [`out_of_range.407`](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains an integer
+  outside [-2^64, 2^64-1], which is only possible with a number type wider than 64 bits; example:
+  `"integer number 18446744073709551616 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]"`
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
@@ -113,3 +116,5 @@ Linear in the size of the JSON value `j`.
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
   array or object was silently skipped, producing invalid CBOR.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0; previously, integers of a
+  number type wider than 64 bits were silently truncated.

api/basic_json/to_cbor/index.md

@@ -38,6 +38,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
+- Throws [`out_of_range.407`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains an integer outside [-2^64, 2^64-1], which is only possible with a number type wider than 64 bits; example: `"integer number 18446744073709551616 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]"`
 - Throws [type_error.316](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if a string or object key in `j` is not valid UTF-8 and `error_handler` is `strict` (the default only if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled)
 - Throws [type_error.321](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error321) if `j` or a value nested in it is discarded; example: `"cannot serialize discarded value to CBOR"`
 
@@ -97,3 +98,4 @@ Output:
 - Compact representation of floating-point numbers added in version 3.8.0.
 - Added `error_handler` parameter in version 3.13.0 unreleased. Its default, `keep`, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before; `strict` (the default if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled) throws `type_error.316`.
 - Throws `type_error.321` for a discarded value since version 3.13.0 unreleased; previously, a discarded value nested in an array or object was silently skipped, producing invalid CBOR.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0 unreleased; previously, integers of a number type wider than 64 bits were silently truncated.

api/basic_json/to_msgpack.md

@@ -46,6 +46,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
+- Throws [`out_of_range.407`](../../home/exceptions.md#jsonexceptionout_of_range407) if `j` contains an integer
+  outside [-2^63, 2^64-1], which is only possible with a number type wider than 64 bits; example:
+  `"integer number 18446744073709551616 cannot be represented by MessagePack as it does not fit [-2^63, 2^64-1]"`
 - Throws [`out_of_range.412`](../../home/exceptions.md#jsonexceptionout_of_range412) if the length of a string, binary
   value, array, or object exceeds 4294967295, the maximum MessagePack can store; example:
   `"MessagePack length 4294967296 exceeds maximum of 4294967295"`
@@ -156,3 +159,5 @@ Linear in the size of the JSON value `j`.
   `number_unsigned_t`.
 - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
   array or object was silently skipped, producing invalid MessagePack.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0; previously, integers of a
+  number type wider than 64 bits were silently truncated.

api/basic_json/to_msgpack/index.md

@@ -38,6 +38,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 ## Exceptions
 
+- Throws [`out_of_range.407`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range407) if `j` contains an integer outside [-2^63, 2^64-1], which is only possible with a number type wider than 64 bits; example: `"integer number 18446744073709551616 cannot be represented by MessagePack as it does not fit [-2^63, 2^64-1]"`
 - Throws [`out_of_range.412`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range412) if the length of a string, binary value, array, or object exceeds 4294967295, the maximum MessagePack can store; example: `"MessagePack length 4294967296 exceeds maximum of 4294967295"`
 - Throws [`out_of_range.415`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range415) if the subtype of a binary value exceeds 255, the maximum of the MessagePack ext type; example: `"subtype 70000 is too large for the MessagePack ext type (max 255)"`
 - Throws [type_error.316](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) if a string or object key in `j` is not valid UTF-8 and `error_handler` is `strict`
@@ -133,3 +134,4 @@ Output:
 - Added `error_handler` parameter in version 3.13.0 unreleased. Its default, `keep`, writes the bytes of a string or object key that is not valid UTF-8 unchanged, as before.
 - Fixed in version 3.13.0 unreleased to serialize `number_integer_t`/`number_unsigned_t` pairs of different width correctly; before, integers could be serialized with the wrong value if `number_integer_t` was narrower than `number_unsigned_t`.
 - Throws `type_error.321` for a discarded value since version 3.13.0 unreleased; previously, a discarded value nested in an array or object was silently skipped, producing invalid MessagePack.
+- Throws `out_of_range.407` for integers that do not fit 64 bits since version 3.13.0 unreleased; previously, integers of a number type wider than 64 bits were silently truncated.

api/macros/json_disable_unlocked_file_io.md

@@ -10,6 +10,9 @@ earlier, instead of locking the file once and reading it with the unlocked stdio
 It does not change any result: values, exceptions, and the position of the file after parsing are the same either way.
 Only the speed and the locking of the file differ (see the notes on locking below).
 
+Builds with MemorySanitizer use `std::fgetc` automatically, because the inline `getc_unlocked` of glibc reads the stdio
+buffer directly, which glibc (not instrumented) filled, and MemorySanitizer would report it as uninitialized.
+
 ## Default definition
 
 The default value is `0`: the file is locked once and read with the unlocked stdio functions where they are available.

api/macros/json_disable_unlocked_file_io/index.md

@@ -8,6 +8,8 @@ When defined to `1`, parsing from a `FILE*` reads every character with `std::fge
 
 It does not change any result: values, exceptions, and the position of the file after parsing are the same either way. Only the speed and the locking of the file differ (see the notes on locking below).
 
+Builds with MemorySanitizer use `std::fgetc` automatically, because the inline `getc_unlocked` of glibc reads the stdio buffer directly, which glibc (not instrumented) filled, and MemorySanitizer would report it as uninitialized.
+
 ## Default definition
 
 The default value is `0`: the file is locked once and read with the unlocked stdio functions where they are available.

features/performance.md

@@ -20,32 +20,39 @@ below apply on every supported standard. This adapter exposes two optimizations
 
 - it can reconstruct already-consumed input on demand for error messages, instead of copying every character as it is
   read, and
-- the lexer can scan ordinary string characters directly out of the buffer, several bytes at a time, rather than one
-  character (and one function call) at a time.
+- the lexer can scan ordinary string characters, numbers, and indentation directly out of the buffer, several bytes at
+  a time, rather than one character (and one function call) at a time.
 
-A `#!cpp std::istream` (including `#!cpp std::ifstream`) or `#!cpp FILE*`, by contrast, is read through
-`input_stream_adapter` or `file_input_adapter`, which read one character (or one block, for binary formats) at a time
-and expose neither optimization -- the lexer falls back to the same byte-at-a-time path it uses for any
-non-contiguous, general-purpose iterator range. An iterator pair over non-contiguous but random-access storage (e.g.
-`#!cpp std::deque<char>::iterator`) gets the first optimization but not the second, since the byte-scanning fast path
-additionally requires contiguous storage.
+A `#!cpp std::istream` (including `#!cpp std::ifstream`) gets the same bulk scanning: `input_stream_adapter` scans the
+characters its stream buffer already holds (the *get area*) and asks the stream buffer for more only when they are used
+up. Nothing is read ahead, so the stream is left exactly where it would be after reading one character at a time, and
+[`operator>>`](../api/operator_gtgt.md) can still read several values from one stream. A stream buffer without a get
+area is read one character at a time. A `#!cpp FILE*` is still read one character at a time, but `file_input_adapter`
+locks the file once per parse instead of once per character. See
+[input sources and performance](parsing/index.md#input-sources-and-performance) for the full table. According to the
+description of [#5828](https://github.com/nlohmann/json/pull/5828), parsing from a stream is within about 10 to 20 % of
+parsing an equivalent `#!cpp std::string`.
 
-Practically: if the JSON text is already in memory, or small enough to read into memory, prefer passing a
-`#!cpp std::string`, a `#!cpp std::vector<char>`, or a pointer range to `parse` over a `#!cpp std::istream`. For a
-file, that means reading it into a string first and then parsing the string, rather than passing a
-`#!cpp std::ifstream` directly to `parse` -- the latter never benefits from either optimization:
+Inputs that are still read one character at a time: iterator ranges that are not contiguous (e.g.
+`#!cpp std::list<char>` or `#!cpp std::istreambuf_iterator<char>`), wide strings, and user-defined adapters. An
+iterator pair over non-contiguous but random-access storage (e.g. `#!cpp std::deque<char>::iterator`) gets the first
+optimization but not the second, since the byte-scanning fast path requires contiguous storage.
+
+Practically: a file can be passed directly to `parse`, which also avoids the memory for a copy of the file. Reading it
+into a string first is no longer necessary for speed:
 
 ```cpp
-// gets the contiguous fast paths
+// fast: the stream buffer's get area is scanned in bulk
 std::ifstream f("example.json");
-std::string contents((std::istreambuf_iterator<char>(f)), std::istreambuf_iterator<char>());
-json j = json::parse(contents);
-
-// does not: input_stream_adapter has no fast path
-std::ifstream f2("example.json");
-json j2 = json::parse(f2);
+json j = json::parse(f);
 ```
 
+Two macros switch the stream optimizations off without changing any result:
+[`JSON_DISABLE_STREAM_BULK_SCAN`](../api/macros/json_disable_stream_bulk_scan.md) for stream buffers that do not follow
+the usual `#!cpp std::streambuf` contract, and
+[`JSON_DISABLE_UNLOCKED_FILE_IO`](../api/macros/json_disable_unlocked_file_io.md) for programs in which another thread
+must use the same `#!cpp FILE` object while it is parsed.
+
 For contiguous input with many non-ASCII characters, [`JSON_USE_SIMDUTF`](../api/macros/json_use_simdutf.md) can
 additionally speed up UTF-8 validation by using the [simdutf](https://github.com/simdutf/simdutf) library instead of
 the built-in scalar validator; streaming inputs (files, `#!cpp std::istream`, wide strings, user-defined adapters)

features/performance/index.md

@@ -11,23 +11,22 @@ That said, how you use this library still makes a measurable difference. This pa
 For inputs backed by contiguous, single-byte memory -- a `std::string`, a `std::vector<char>`, a string literal, or a pointer range -- the library uses `iterator_input_adapter`, wrapped in a raw pointer so the fast paths below apply on every supported standard. This adapter exposes two optimizations the lexer detects at compile time:
 
 - it can reconstruct already-consumed input on demand for error messages, instead of copying every character as it is read, and
-- the lexer can scan ordinary string characters directly out of the buffer, several bytes at a time, rather than one character (and one function call) at a time.
+- the lexer can scan ordinary string characters, numbers, and indentation directly out of the buffer, several bytes at a time, rather than one character (and one function call) at a time.
 
-A `std::istream` (including `std::ifstream`) or `FILE*`, by contrast, is read through `input_stream_adapter` or `file_input_adapter`, which read one character (or one block, for binary formats) at a time and expose neither optimization -- the lexer falls back to the same byte-at-a-time path it uses for any non-contiguous, general-purpose iterator range. An iterator pair over non-contiguous but random-access storage (e.g. `std::deque<char>::iterator`) gets the first optimization but not the second, since the byte-scanning fast path additionally requires contiguous storage.
+A `std::istream` (including `std::ifstream`) gets the same bulk scanning: `input_stream_adapter` scans the characters its stream buffer already holds (the *get area*) and asks the stream buffer for more only when they are used up. Nothing is read ahead, so the stream is left exactly where it would be after reading one character at a time, and [`operator>>`](https://json.nlohmann.me/api/operator_gtgt/index.md) can still read several values from one stream. A stream buffer without a get area is read one character at a time. A `FILE*` is still read one character at a time, but `file_input_adapter` locks the file once per parse instead of once per character. See [input sources and performance](https://json.nlohmann.me/features/parsing/#input-sources-and-performance) for the full table. According to the description of [#5828](https://github.com/nlohmann/json/pull/5828), parsing from a stream is within about 10 to 20 % of parsing an equivalent `std::string`.
 
-Practically: if the JSON text is already in memory, or small enough to read into memory, prefer passing a `std::string`, a `std::vector<char>`, or a pointer range to `parse` over a `std::istream`. For a file, that means reading it into a string first and then parsing the string, rather than passing a `std::ifstream` directly to `parse` -- the latter never benefits from either optimization:
+Inputs that are still read one character at a time: iterator ranges that are not contiguous (e.g. `std::list<char>` or `std::istreambuf_iterator<char>`), wide strings, and user-defined adapters. An iterator pair over non-contiguous but random-access storage (e.g. `std::deque<char>::iterator`) gets the first optimization but not the second, since the byte-scanning fast path requires contiguous storage.
+
+Practically: a file can be passed directly to `parse`, which also avoids the memory for a copy of the file. Reading it into a string first is no longer necessary for speed:
 
 ```
-// gets the contiguous fast paths
+// fast: the stream buffer's get area is scanned in bulk
 std::ifstream f("example.json");
-std::string contents((std::istreambuf_iterator<char>(f)), std::istreambuf_iterator<char>());
-json j = json::parse(contents);
-
-// does not: input_stream_adapter has no fast path
-std::ifstream f2("example.json");
-json j2 = json::parse(f2);
+json j = json::parse(f);
 ```
 
+Two macros switch the stream optimizations off without changing any result: [`JSON_DISABLE_STREAM_BULK_SCAN`](https://json.nlohmann.me/api/macros/json_disable_stream_bulk_scan/index.md) for stream buffers that do not follow the usual `std::streambuf` contract, and [`JSON_DISABLE_UNLOCKED_FILE_IO`](https://json.nlohmann.me/api/macros/json_disable_unlocked_file_io/index.md) for programs in which another thread must use the same `FILE` object while it is parsed.
+
 For contiguous input with many non-ASCII characters, [`JSON_USE_SIMDUTF`](https://json.nlohmann.me/api/macros/json_use_simdutf/index.md) can additionally speed up UTF-8 validation by using the [simdutf](https://github.com/simdutf/simdutf) library instead of the built-in scalar validator; streaming inputs (files, `std::istream`, wide strings, user-defined adapters) always use the scalar path regardless of this macro.
 
 ## Large documents

home/exceptions.md

@@ -1106,9 +1106,19 @@ double-precision number when `number_float_t` is `#!cpp float`.
 
 ### json.exception.out_of_range.407
 
-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.
+An integer number cannot be represented by the binary format it is serialized to:
+
+- [BON8](../features/binary_formats/bon8.md) only stores integers that fit into int64, so
+  [`to_bon8`](../api/basic_json/to_bon8.md) throws for unsigned integers greater than 9223372036854775807.
+- [CBOR](../features/binary_formats/cbor.md), [MessagePack](../features/binary_formats/messagepack.md), and
+  [BSON](../features/binary_formats/bson.md) store integers in at most 64 bits. With the default number types, every
+  integer fits, but a [`number_integer_t`](../api/basic_json/number_integer_t.md) or
+  [`number_unsigned_t`](../api/basic_json/number_unsigned_t.md) wider than 64 bits (e.g., `__int128`) can hold values
+  outside the range of the format: [-2^64, 2^64-1] for CBOR, [-2^63, 2^64-1] for MessagePack, and the range of int64
+  (signed integers) or uint64 (unsigned integers) for BSON.
+
+[UBJSON](../features/binary_formats/ubjson.md) and [BJData](../features/binary_formats/bjdata.md) never throw this
+exception, because they serialize integers beyond 64 bits as high-precision numbers.
 
 !!! note "Former occurrences"
 
@@ -1117,11 +1127,17 @@ unsigned 64-bit integer type.
     - 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"
+    Before version 3.13.0, CBOR, MessagePack, and BSON silently truncated integers wider than 64 bits, and BJData
+    truncated unsigned integers wider than 64 bits.
+
+!!! failure "Example messages"
 
     ```
     integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
     ```
+    ```
+    integer number 1267650600228229401496703205376 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]
+    ```
 
 ### json.exception.out_of_range.408
 

home/exceptions/index.md

@@ -1078,7 +1078,12 @@ number overflow parsing '10E1000'
 
 ### json.exception.out_of_range.407
 
-An unsigned integer number greater than 9223372036854775807 cannot be represented in the binary format. This exception is only thrown by [`to_bon8`](https://json.nlohmann.me/api/basic_json/to_bon8/index.md), as [BON8](https://json.nlohmann.me/features/binary_formats/bon8/index.md) has no unsigned 64-bit integer type.
+An integer number cannot be represented by the binary format it is serialized to:
+
+- [BON8](https://json.nlohmann.me/features/binary_formats/bon8/index.md) only stores integers that fit into int64, so [`to_bon8`](https://json.nlohmann.me/api/basic_json/to_bon8/index.md) throws for unsigned integers greater than 9223372036854775807.
+- [CBOR](https://json.nlohmann.me/features/binary_formats/cbor/index.md), [MessagePack](https://json.nlohmann.me/features/binary_formats/messagepack/index.md), and [BSON](https://json.nlohmann.me/features/binary_formats/bson/index.md) store integers in at most 64 bits. With the default number types, every integer fits, but a [`number_integer_t`](https://json.nlohmann.me/api/basic_json/number_integer_t/index.md) or [`number_unsigned_t`](https://json.nlohmann.me/api/basic_json/number_unsigned_t/index.md) wider than 64 bits (e.g., `__int128`) can hold values outside the range of the format: [-2^64, 2^64-1] for CBOR, [-2^63, 2^64-1] for MessagePack, and the range of int64 (signed integers) or uint64 (unsigned integers) for BSON.
+
+[UBJSON](https://json.nlohmann.me/features/binary_formats/ubjson/index.md) and [BJData](https://json.nlohmann.me/features/binary_formats/bjdata/index.md) never throw this exception, because they serialize integers beyond 64 bits as high-precision numbers.
 
 Former occurrences
 
@@ -1087,12 +1092,18 @@ 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.
 
-Example message
+Before version 3.13.0 unreleased, CBOR, MessagePack, and BSON silently truncated integers wider than 64 bits, and BJData truncated unsigned integers wider than 64 bits.
+
+Example messages
 
 ```
 integer number 18446744073709551615 cannot be represented by BON8 as it does not fit int64
 ```
 
+```
+integer number 1267650600228229401496703205376 cannot be represented by CBOR as it does not fit [-2^64, 2^64-1]
+```
+
 ### json.exception.out_of_range.408
 
 The size of an array or object in a [binary format](https://json.nlohmann.me/features/binary_formats/index.md) exceeds the maximal capacity: the size following `#` for [UBJSON](https://json.nlohmann.me/features/binary_formats/ubjson/index.md)/[BJData](https://json.nlohmann.me/features/binary_formats/bjdata/index.md), or the encoded length for [CBOR](https://json.nlohmann.me/features/binary_formats/cbor/index.md).