docs: format tables, use the Oxford comma, drop discarded-value remarks

Reformat the two UBJSON mapping tables that this PR changed (uniform column
widths, padded cells), use the serial comma in lists of three or more in the
added text, and restore the original type_error.321 bullet in to_ubjson.md.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann committed 2026-10-25 20:05:29 +01:00
1 parent 9d9bf927ff
commit 24ff6eaa43
4 files changed
+49 -49

No files matched your search

@@ -89,7 +89,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
- Throws [out_of_range.406](../../home/exceptions.md#jsonexceptionout_of_range406) if a high-precision number, or a - Throws [out_of_range.406](../../home/exceptions.md#jsonexceptionout_of_range406) if a high-precision number, or a
float64 when `number_float_t` is `float`, does not fit into `number_float_t` float64 when `number_float_t` is `float`, does not fit into `number_float_t`
- Throws [out_of_range.408](../../home/exceptions.md#jsonexceptionout_of_range408) if the count of an optimized - Throws [out_of_range.408](../../home/exceptions.md#jsonexceptionout_of_range408) if the count of an optimized
container exceeds the capacity of the container (or of `std::size_t`), or if an optimized array of `Z`, `T` or `F` has container exceeds the capacity of the container (or of `std::size_t`), or if an optimized array of `Z`, `T`, or `F` has
more than 1,048,576 elements more than 1,048,576 elements
## Complexity ## Complexity
+2 -2
View File
@@ -114,5 +114,5 @@ Linear in the size of the JSON value `j`.
- Added `error_handler` parameter in version 3.13.0. Its default, `keep`, writes the bytes of a string or object key - Added `error_handler` parameter in version 3.13.0. 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 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`. [`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 array element was - Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
skipped, and an object member was written as a key without a value, producing invalid UBJSON. array or object was silently skipped, producing invalid UBJSON.
@@ -44,29 +44,29 @@ Consider the following JSON value (shown formatted for readability):
The library uses the following mapping from JSON values types to UBJSON types according to the UBJSON specification: The library uses the following mapping from JSON values types to UBJSON types according to the UBJSON specification:
| JSON value type | value/range | UBJSON type | marker | | JSON value type | value/range | UBJSON type | marker |
|-----------------|-------------------------------------------|----------------|--------| |-----------------|-------------------------------------------|--------------------------------------------------|-----------|
| null | `null` | null | `Z` | | null | `null` | null | `Z` |
| boolean | `true` | true | `T` | | boolean | `true` | true | `T` |
| boolean | `false` | false | `F` | | boolean | `false` | false | `F` |
| number_integer | -9223372036854775808..-2147483649 | int64 | `L` | | number_integer | -9223372036854775808..-2147483649 | int64 | `L` |
| number_integer | -2147483648..-32769 | int32 | `l` | | number_integer | -2147483648..-32769 | int32 | `l` |
| number_integer | -32768..-129 | int16 | `I` | | number_integer | -32768..-129 | int16 | `I` |
| number_integer | -128..127 | int8 | `i` | | number_integer | -128..127 | int8 | `i` |
| number_integer | 128..255 | uint8 | `U` | | number_integer | 128..255 | uint8 | `U` |
| number_integer | 256..32767 | int16 | `I` | | number_integer | 256..32767 | int16 | `I` |
| number_integer | 32768..2147483647 | int32 | `l` | | number_integer | 32768..2147483647 | int32 | `l` |
| number_integer | 2147483648..9223372036854775807 | int64 | `L` | | number_integer | 2147483648..9223372036854775807 | int64 | `L` |
| number_unsigned | 0..127 | int8 | `i` | | number_unsigned | 0..127 | int8 | `i` |
| number_unsigned | 128..255 | uint8 | `U` | | number_unsigned | 128..255 | uint8 | `U` |
| number_unsigned | 256..32767 | int16 | `I` | | number_unsigned | 256..32767 | int16 | `I` |
| number_unsigned | 32768..2147483647 | int32 | `l` | | number_unsigned | 32768..2147483647 | int32 | `l` |
| number_unsigned | 2147483648..9223372036854775807 | int64 | `L` | | number_unsigned | 2147483648..9223372036854775807 | int64 | `L` |
| number_unsigned | 9223372036854775808..18446744073709551615 | high-precision | `H` | | number_unsigned | 9223372036854775808..18446744073709551615 | high-precision | `H` |
| number_float | *any value* | float64 (float32 if `number_float_t` is `float`) | `D` (`d`) | | number_float | *any value* | float64 (float32 if `number_float_t` is `float`) | `D` (`d`) |
| string | *with shortest length indicator* | string | `S` | | string | *with shortest length indicator* | string | `S` |
| array | *see notes on optimized format* | array | `[` | | array | *see notes on optimized format* | array | `[` |
| object | *see notes on optimized format* | object | `{` | | object | *see notes on optimized format* | object | `{` |
!!! success "Complete mapping" !!! success "Complete mapping"
@@ -109,10 +109,10 @@ The library uses the following mapping from JSON values types to UBJSON types ac
have the same type and adds the type marker to the beginning of the container. The `use_type` parameter must only be have the same type and adds the type marker to the beginning of the container. The `use_type` parameter must only be
used together with `use_size = true`: combining `use_type` with `use_size = false` throws used together with `use_size = true`: combining `use_type` with `use_size = false` throws
[`other_error.502`](../../home/exceptions.md#jsonexceptionother_error502) if the value contains a non-empty array, [`other_error.502`](../../home/exceptions.md#jsonexceptionother_error502) if the value contains a non-empty array,
object or binary value. object, or binary value.
Two elements have the same type if they are written with the same type marker. For example, `[1, 2]` is written with Two elements have the same type if they are written with the same type marker. For example, `[1, 2]` is written with
the type `i`, but `[1, 200]` (`i`, `U`), `[true, false]` (`T`, `F`) and `[1, 2.5]` (`i`, `D`) are not; an empty the type `i`, but `[1, 200]` (`i`, `U`), `[true, false]` (`T`, `F`), and `[1, 2.5]` (`i`, `D`) are not; an empty
container is never given a `$` annotation of its own (an array of empty arrays is still typed `[`). container is never given a `$` annotation of its own (an array of empty arrays is still typed `[`).
Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the
@@ -148,30 +148,30 @@ The library uses the following mapping from JSON values types to UBJSON types ac
The library maps UBJSON types to JSON value types as follows: The library maps UBJSON types to JSON value types as follows:
| UBJSON type | JSON value type | marker | | UBJSON type | JSON value type | marker |
|-------------|-----------------------------------------|--------| |----------------|--------------------------------------------------|--------|
| no-op | *no value, next value is read* | `N` | | no-op | *no value, next value is read* | `N` |
| null | `null` | `Z` | | null | `null` | `Z` |
| false | `false` | `F` | | false | `false` | `F` |
| true | `true` | `T` | | true | `true` | `T` |
| float32 | number_float | `d` | | float32 | number_float | `d` |
| float64 | number_float | `D` | | float64 | number_float | `D` |
| uint8 | number_unsigned | `U` | | uint8 | number_unsigned | `U` |
| int8 | number_integer | `i` | | int8 | number_integer | `i` |
| int16 | number_integer | `I` | | int16 | number_integer | `I` |
| int32 | number_integer | `l` | | int32 | number_integer | `l` |
| int64 | number_integer | `L` | | int64 | number_integer | `L` |
| string | string | `S` | | string | string | `S` |
| char | string | `C` | | char | string | `C` |
| high-precision | number_unsigned, number_integer or number_float | `H` | | high-precision | number_unsigned, number_integer, or number_float | `H` |
| array | array (optimized values are supported) | `[` | | array | array (optimized values are supported) | `[` |
| object | object (optimized values are supported) | `{` | | object | object (optimized values are supported) | `{` |
!!! info "High-precision numbers" !!! info "High-precision numbers"
The payload of `H` is a length-prefixed string that is parsed as a JSON number (surrounding whitespace is ignored). The payload of `H` is a length-prefixed string that is parsed as a JSON number (surrounding whitespace is ignored).
Integer text in the range of `number_unsigned_t` (non-negative) or `number_integer_t` (negative) is stored as such; Integer text in the range of `number_unsigned_t` (non-negative) or `number_integer_t` (negative) is stored as such;
any other valid number text (larger or smaller integers, fractions, exponents such as `1e2`) is stored as any other valid number text (larger or smaller integers, fractions, and exponents such as `1e2`) is stored as
`number_float`, so precision may be lost. Text that is not a valid JSON number raises `number_float`, so precision may be lost. Text that is not a valid JSON number raises
[`parse_error.115`](../../home/exceptions.md#jsonexceptionparse_error115), a number outside the range of [`parse_error.115`](../../home/exceptions.md#jsonexceptionparse_error115), a number outside the range of
`number_float_t` (`1e999`) raises [`out_of_range.406`](../../home/exceptions.md#jsonexceptionout_of_range406). `number_float_t` (`1e999`) raises [`out_of_range.406`](../../home/exceptions.md#jsonexceptionout_of_range406).
@@ -180,7 +180,7 @@ The library maps UBJSON types to JSON value types as follows:
Every well-formed UBJSON value can be converted to a JSON value, with these exceptions: a high-precision number 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`](../../home/exceptions.md#jsonexceptionout_of_range406)), outside the range of `number_float_t` ([`out_of_range.406`](../../home/exceptions.md#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 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`](../../home/exceptions.md#jsonexceptionout_of_range408)). High-precision numbers that container ([`out_of_range.408`](../../home/exceptions.md#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 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. with a parse error.
@@ -192,7 +192,7 @@ The library maps UBJSON types to JSON value types as follows:
!!! info "Type marker of optimized containers" !!! info "Type marker of optimized containers"
The type marker after `$` must be one of `Z`, `N`, `T`, `F`, `i`, `U`, `I`, `l`, `L`, `d`, `D`, `H`, `C`, `S`, `[` or The type marker after `$` must be one of `Z`, `N`, `T`, `F`, `i`, `U`, `I`, `l`, `L`, `d`, `D`, `H`, `C`, `S`, `[`, or
`{`. It is checked even if the count is 0; any other marker raises `{`. It is checked even if the count is 0; any other marker raises
[`parse_error.112`](../../home/exceptions.md#jsonexceptionparse_error112). A counted object typed `N` (`{$N#i1 ...`) [`parse_error.112`](../../home/exceptions.md#jsonexceptionparse_error112). A counted object typed `N` (`{$N#i1 ...`)
is not supported. is not supported.
+1 -1
View File
@@ -1229,7 +1229,7 @@ A JSON Patch operation 'test' failed. The unsuccessful operation is also printed
### json.exception.other_error.502 ### json.exception.other_error.502
[`to_ubjson`](../api/basic_json/to_ubjson.md) and [`to_bjdata`](../api/basic_json/to_bjdata.md) were called with [`to_ubjson`](../api/basic_json/to_ubjson.md) and [`to_bjdata`](../api/basic_json/to_bjdata.md) were called with
`use_type = true` but `use_size = false` for a value that contains a non-empty array, object or binary value. UBJSON `use_type = true` but `use_size = false` for a value that contains a non-empty array, object, or binary value. UBJSON
requires a size marker (`#`) after a type marker (`$`); scalars and empty containers do not throw. requires a size marker (`#`) after a type marker (`$`); scalars and empty containers do not throw.
!!! failure "Example message" !!! failure "Example message"