From 173f2a7407bb11bb9a043f5e5fc07eb4cc9a897f Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Tue, 4 Aug 2026 08:45:18 +0200 Subject: [PATCH] Documentation review: exceptions from binary-format hardening, and tuple reference types (#5359) * :memo: Document exceptions newly thrown by the binary-format hardening A round of binary-format input validation (#5274, #5284, #5287, #5332) added new failure modes without updating exceptions.md, and left two descriptions factually narrower than the code: - parse_error.110 said "CBOR or MessagePack"; BSON and UBJSON also throw it. Generalized, and added the BSON EOF example (#5332). - parse_error.112: added the BSON document-size mismatch example (#5287). - parse_error.113 said "while parsing a map key", but its own existing UBJSON char example already contradicted that. Broadened to cover invalid length specifications, and added the negative-string-length example (#5284). - out_of_range.408 said "of an UBJSON array or object"; CBOR now throws it too (#5274). Generalized and added both CBOR examples. Signed-off-by: Niels Lohmann * :memo: Correct which types may be referenced in a tuple extraction The note added in #5271 said a referenced type must be one the library stores "or an arithmetic type it can convert to/from". The parenthetical is wrong: is_compatible_reference_type requires an exact match against the stored types, so std::tuple is rejected by static_assert even though int converts fine as a value. Only the value case is permissive. Spell out the eight admissible types, give the int& counter-example, and separate the reference restriction from by-value conversion. Signed-off-by: Niels Lohmann --------- Signed-off-by: Niels Lohmann --- docs/mkdocs/docs/features/conversions.md | 10 ++++++-- docs/mkdocs/docs/home/exceptions.md | 29 ++++++++++++++++++++---- 2 files changed, 32 insertions(+), 7 deletions(-) diff --git a/docs/mkdocs/docs/features/conversions.md b/docs/mkdocs/docs/features/conversions.md index be85f5db6..2a48a05a4 100644 --- a/docs/mkdocs/docs/features/conversions.md +++ b/docs/mkdocs/docs/features/conversions.md @@ -66,8 +66,14 @@ auto t = j.get>(); // {1.0, "hello", 42} std::get<1>(refs) = "world"; // modifies j[1] in place ``` - A referenced type must be one the library actually stores (or an arithmetic type it can convert to/from); - otherwise this is a compile error. + A referenced element must name the type the library actually *stores* — one of [`boolean_t`](../api/basic_json/boolean_t.md), + [`number_integer_t`](../api/basic_json/number_integer_t.md), [`number_unsigned_t`](../api/basic_json/number_unsigned_t.md), + [`number_float_t`](../api/basic_json/number_float_t.md), [`string_t`](../api/basic_json/string_t.md), + [`binary_t`](../api/basic_json/binary_t.md), [`array_t`](../api/basic_json/array_t.md), or + [`object_t`](../api/basic_json/object_t.md). There is nothing else to refer to, so a reference to any other type is a + compile error even when a conversion would exist: `#!cpp std::tuple` is rejected, because the library stores a + `#!cpp number_integer_t` (`#!cpp std::int64_t` by default) and not an `#!cpp int`. This restriction applies only to + reference elements — a plain `#!cpp std::tuple` converts by value as usual. ## Implicit conversions diff --git a/docs/mkdocs/docs/home/exceptions.md b/docs/mkdocs/docs/home/exceptions.md index 235744009..f75872505 100644 --- a/docs/mkdocs/docs/home/exceptions.md +++ b/docs/mkdocs/docs/home/exceptions.md @@ -291,9 +291,10 @@ A JSON Pointer array index must be a number. ### json.exception.parse_error.110 -When parsing CBOR or MessagePack, the byte vector ends before the complete value has been read. +When parsing a [binary format](../features/binary_formats/index.md), the byte vector ends before the complete value has +been read. -!!! failure "Example message" +!!! failure "Example messages" ``` [json.exception.parse_error.110] parse error at byte 5: syntax error while parsing CBOR string: unexpected end of input @@ -301,6 +302,9 @@ When parsing CBOR or MessagePack, the byte vector ends before the complete value ``` [json.exception.parse_error.110] parse error at byte 2: syntax error while parsing UBJSON value: expected end of input; last byte: 0x5A ``` + ``` + [json.exception.parse_error.110] parse error at byte 8: syntax error while parsing BSON number: unexpected end of input + ``` ### json.exception.parse_error.112 @@ -329,10 +333,14 @@ An unexpected byte was read in a [binary format](../features/binary_formats/inde ``` [json.exception.parse_error.112] parse error at byte 9: syntax error while parsing CBOR value: negative integer overflow ``` + ``` + [json.exception.parse_error.112] parse error at byte 5: syntax error while parsing BSON document: document size 6 does not match the number of bytes read (5) + ``` ### json.exception.parse_error.113 -While parsing a map key, a value that is not a string has been read. +A string could not be read from a [binary format](../features/binary_formats/index.md): either a value that is not a +string was read where one was required (for instance as a map key), or the string's length specification is invalid. !!! failure "Example messages" @@ -345,6 +353,9 @@ While parsing a map key, a value that is not a string has been read. ``` [json.exception.parse_error.113] parse error at byte 2: syntax error while parsing UBJSON char: byte after 'C' must be in range 0x00..0x7F; last byte: 0x82 ``` + ``` + [json.exception.parse_error.113] parse error at byte 3: syntax error while parsing BJData string: string length must not be negative + ``` ### json.exception.parse_error.114 @@ -853,13 +864,21 @@ and this exception no longer occurs. ### json.exception.out_of_range.408 -The size (following `#`) of an UBJSON array or object exceeds the maximal capacity. +The size of an array or object in a [binary format](../features/binary_formats/index.md) exceeds the maximal capacity: +the size following `#` for [UBJSON](../features/binary_formats/ubjson.md)/[BJData](../features/binary_formats/bjdata.md), +or the encoded length for [CBOR](../features/binary_formats/cbor.md). -!!! failure "Example message" +!!! failure "Example messages" ``` excessive array size: 8658170730974374167 ``` + ``` + [json.exception.out_of_range.408] syntax error while parsing CBOR size: excessive array size + ``` + ``` + [json.exception.out_of_range.408] syntax error while parsing CBOR size: excessive map size + ``` ### json.exception.out_of_range.409