deploy: abbc29963a

features/binary_formats/ubjson/index.md

@@ -101,7 +101,11 @@ Two elements have the same type if they are written with the same type marker. F
 
 Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the receiving side is immediately informed on the number of elements of the container.
 
-An array whose type marker is `Z` (null), `T` (true) or `F` (false) stores no payload at all, because the marker already is the value. Its declared count is therefore the only thing that decides how much memory the receiving side allocates, and a handful of bytes can describe billions of elements. `from_ubjson` rejects such an array with [`out_of_range.408`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range408) when the count exceeds 1,048,576 (`1 << 20`), and `to_ubjson` writes longer arrays of these types in the counted but untyped form: the `$` type marker is dropped, the `#` count is kept, and every element is written with its own marker (`[#l 1048577 Z Z ...`), so any value it produces can be read back. Objects and untyped counted arrays are not subject to this limit.
+An array whose type marker is `Z` (null), `T` (true) or `F` (false) stores no payload at all, because the marker already is the value. Its declared count is therefore the only thing that decides how much memory the receiving side allocates, and a handful of bytes can describe billions of elements. `from_ubjson` rejects such an array with [`out_of_range.408`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range408) when the count exceeds 1,048,576 (`1 << 20`), or when the counts of all such arrays in the input add up to more than 1,048,576 plus *K* for every byte read so far, where *K* is the value of the macro [`JSON_UBJSON_VALUELESS_ELEMENTS_PER_BYTE`](https://json.nlohmann.me/api/macros/json_ubjson_valueless_elements_per_byte/index.md) (4 by default). `to_ubjson` therefore writes an array of these types in the counted but untyped form when it is longer than that, or when it would bring the total of the typed arrays written so far above 1,048,576: the `$` type marker is dropped, the `#` count is kept, and every element is written with its own marker (`[#l 1048577 Z Z ...`), so everything it produces can be read back. Only input from another encoder, or written by version 3.12.0 and earlier of this library, can exceed the limit: for example, 1,100 rows of 1,000 `null` values or 210,000 rows of 25, each with a `$Z` annotation. Version 3.12.0 writes a row in 5 bytes (6 above 255 elements, 8 above 32,767), which raises the limit by 5 *K* (6 *K*, 8 *K*), so rows of up to 5 *K* values (20 at the default) are never rejected. To read such a file, define the macro to a larger value (`8` is enough for the 1,100 rows of 1,000 `null` values; memory for the arrays then rises to about 20 *K* bytes per byte of input in a DOM); the macro's page explains how to choose a value and what it costs. The limit of one array of 1,048,576 elements does not depend on the macro. Objects and untyped counted arrays are not subject to this limit.
+
+An optimized array of type `N` (no-op) is empty whatever its count is, because a no-op is not a value. Its count is not passed on: `sax_parse` reports `start_array(0)` (versions before 3.13.0 reported the declared count), and the DOM parser reserves nothing for it.
+
+An optimized array of type `N` (no-op) is empty whatever its count is, because a no-op is not a value. Its count is not passed on: `sax_parse` reports `start_array(0)` (versions before 3.13.0 reported the declared count), and the DOM parser reserves nothing for it.
 
 Binary values
 
@@ -214,7 +218,7 @@ The payload of `H` is a length-prefixed string that is parsed as a JSON number (
 
 Complete mapping
 
-Every well-formed UBJSON value can be converted to a JSON value, with these exceptions: a high-precision number outside the range of `number_float_t` ([`out_of_range.406`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range406)), an optimized array of `Z`, `T`, or `F` with more than 1,048,576 elements, and a count that exceeds the capacity of the container ([`out_of_range.408`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range408)). High-precision numbers that do not fit an integer type are stored as floating-point numbers and may lose precision. Ill-formed input is rejected with a parse error.
+Every well-formed UBJSON value can be converted to a JSON value, with these exceptions: a high-precision number outside the range of `number_float_t` ([`out_of_range.406`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range406)), optimized arrays of `Z`, `T`, or `F` with more elements than the limit allows (1,048,576 plus [`JSON_UBJSON_VALUELESS_ELEMENTS_PER_BYTE`](https://json.nlohmann.me/api/macros/json_ubjson_valueless_elements_per_byte/index.md), 4 by default, per byte read), and a count that exceeds the capacity of the container ([`out_of_range.408`](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range408)). High-precision numbers that do not fit an integer type are stored as floating-point numbers and may lose precision. Ill-formed input is rejected with a parse error.
 
 Duplicate object keys