Clarify the reservation note for announced array counts

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann committed 2026-11-11 19:05:09 +01:00
1 parent 44b1e7b2b9
commit af2e1c73c1
1 file changed
+6 -6
@@ -72,15 +72,15 @@ For the binary formats, an announced size is never trusted outright:
(reported as a parse error) instead of triggering an oversized allocation. (reported as a parse error) instead of triggering an oversized allocation.
- When an array announces its number of elements and the array container supports `reserve()` (as `#!cpp std::vector`, - When an array announces its number of elements and the array container supports `reserve()` (as `#!cpp std::vector`,
the default, does), the library reserves storage for at most 16384 of them upfront, regardless of how large the the default, does), the library reserves storage for at most 16384 of them upfront, regardless of how large the
announced count is; further elements still grow the container normally as they are read. A count that no announced count is; further elements still grow the container normally as they are read. A truncated input whose
input backs, as in a truncated input, reserves at most that much until the parse error is reported. A parse that count is larger than its remaining bytes therefore reserves at most that much before the parse error is reported.
completes keeps storage for such a count only where the elements take no input at all, which the two Every array element takes at least one byte of input, except in the [UBJSON](../binary_formats/ubjson.md) arrays of
[UBJSON](../binary_formats/ubjson.md) cases below cover. type `Z`, `T` or `F` described below.
- An announced array or object size that exceeds what the target container could ever hold (its `max_size()`) is - An announced array or object size that exceeds what the target container could ever hold (its `max_size()`) is
rejected immediately as [`out_of_range.408`](../../home/exceptions.md#jsonexceptionout_of_range408), without rejected immediately as [`out_of_range.408`](../../home/exceptions.md#jsonexceptionout_of_range408), without
attempting to allocate anything. attempting to allocate anything.
- A [UBJSON](../binary_formats/ubjson.md) array of the no-op type (`[$N#<n>`) is empty whatever count it declares: a - A UBJSON array of the no-op type (`[$N#<n>`) is empty whatever count it declares: a SAX handler is told
SAX handler is told `start_array(0)` and the DOM parser reserves nothing. `start_array(0)` and the DOM parser reserves nothing.
- A UBJSON array of type `Z`, `T` or `F` has no payload, so its announced count is not bounded by the input. One array - A UBJSON array of type `Z`, `T` or `F` has no payload, so its announced count is not bounded by the input. One array
may announce at most 1,048,576 elements, and all such arrays of one input together may contain at most 1,048,576 may announce at most 1,048,576 elements, and all such arrays of one input together may contain at most 1,048,576
elements plus 4 for every byte read so far (checked when each array's header has been read); beyond that the input is elements plus 4 for every byte read so far (checked when each array's header has been read); beyond that the input is