deploy: 95e9a5931c

features/arbitrary_types.md

@@ -215,6 +215,24 @@ For _derived_ classes and structs, use the following macros
     nlohmann::ordered_json j = p; // keys appear in declaration order: name, address, age
     ```
 
+!!! note "Zero-member types"
+
+    All 12 `NLOHMANN_DEFINE_TYPE_*`/`NLOHMANN_DEFINE_DERIVED_TYPE_*` macros (excluding the `WITH_NAMES` variants)
+    also accept types with no member variables to serialize, producing/accepting an empty JSON object `{}`
+    (or, for the derived-type macros, just the base class's own JSON representation):
+
+    ```cpp
+    namespace ns {
+        struct marker {
+            bool operator==(const marker&) const { return true; }
+            NLOHMANN_DEFINE_TYPE_INTRUSIVE(marker)
+        };
+    }
+
+    ns::marker m{};
+    nlohmann::json j = m; // {}
+    ```
+
 !!! note "No macro for non-default-constructible types"
 
     There is currently no `NLOHMANN_DEFINE_TYPE_*`-style macro for types that are not

features/arbitrary_types/index.md

@@ -198,6 +198,22 @@ ns::person p{"Ned Flanders", "744 Evergreen Terrace", 60};
 nlohmann::ordered_json j = p; // keys appear in declaration order: name, address, age
 ```
 
+Zero-member types
+
+All 12 `NLOHMANN_DEFINE_TYPE_*`/`NLOHMANN_DEFINE_DERIVED_TYPE_*` macros (excluding the `WITH_NAMES` variants) also accept types with no member variables to serialize, producing/accepting an empty JSON object `{}` (or, for the derived-type macros, just the base class's own JSON representation):
+
+```
+namespace ns {
+    struct marker {
+        bool operator==(const marker&) const { return true; }
+        NLOHMANN_DEFINE_TYPE_INTRUSIVE(marker)
+    };
+}
+
+ns::marker m{};
+nlohmann::json j = m; // {}
+```
+
 No macro for non-default-constructible types
 
 There is currently no `NLOHMANN_DEFINE_TYPE_*`-style macro for types that are not [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). This is not an intentional omission of documentation -- no such macro exists yet; see [How can I use `get()` for non-default constructible/non-copyable types?](#how-can-i-use-get-for-non-default-constructiblenon-copyable-types) for the manual pattern to use instead.

features/binary_formats/bson.md

@@ -109,6 +109,15 @@ The library maps BSON record types to JSON value types as follows:
     If BSON input must be validated for strict specification compliance, validate it separately before passing it to
     `from_bson()`.
 
+!!! warning "UTF-8 validation of string values"
+
+    The BSON specification requires `string` values (type `0x02`) to be valid UTF-8. This library validates the
+    bytes of every such string at decode time and rejects ill-formed UTF-8 with a
+    [`parse_error.113`](../../home/exceptions.md#jsonexceptionparse_error113) exception (or, with `allow_exceptions`
+    set to `false`, a discarded value), rather than only failing later when the resulting value is dumped. Element
+    (key) names and `binary` values (type `0x05`) are unaffected and are never validated, since they are read
+    byte-by-byte as a C string, or are not required to hold text, respectively.
+
 ??? example
 
     ```cpp

features/binary_formats/bson/index.md

@@ -118,6 +118,10 @@ The BSON reader is lenient in a few areas where the BSON specification is more r
 
 If BSON input must be validated for strict specification compliance, validate it separately before passing it to `from_bson()`.
 
+UTF-8 validation of string values
+
+The BSON specification requires `string` values (type `0x02`) to be valid UTF-8. This library validates the bytes of every such string at decode time and rejects ill-formed UTF-8 with a [`parse_error.113`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) exception (or, with `allow_exceptions` set to `false`, a discarded value), rather than only failing later when the resulting value is dumped. Element (key) names and `binary` values (type `0x05`) are unaffected and are never validated, since they are read byte-by-byte as a C string, or are not required to hold text, respectively.
+
 Example
 
 ```

features/binary_formats/cbor.md

@@ -176,6 +176,16 @@ The library maps CBOR types to JSON value types as follows:
 
     CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected.
 
+!!! warning "UTF-8 validation of text strings"
+
+    [RFC 8949, Section 3.1](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.1) requires CBOR text strings
+    (major type 3) to be valid UTF-8. This library validates the bytes of every text string (object keys included) at
+    decode time and rejects ill-formed UTF-8 with a
+    [`parse_error.113`](../../home/exceptions.md#jsonexceptionparse_error113) exception (or, with
+    `allow_exceptions` set to `false`, a discarded value), rather than only failing later when the resulting value is
+    dumped. Byte strings (major type 2) are unaffected and are never validated, since they are not required to hold
+    text.
+
 !!! warning "Tagged items"
 
     Tagged items (0xC0..0xDB) will throw a parse error by default. They can be ignored by passing `cbor_tag_handler_t::ignore` to function `from_cbor`, in which case the tag is skipped and the enclosed data item is parsed on its own. They can be stored by passing `cbor_tag_handler_t::store` to function `from_cbor`. Note that no tag is ever interpreted: for instance, a text string tagged with tag 0 (date/time) stays a string.

features/binary_formats/cbor/index.md

@@ -187,6 +187,10 @@ Object keys
 
 CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected.
 
+UTF-8 validation of text strings
+
+[RFC 8949, Section 3.1](https://www.rfc-editor.org/rfc/rfc8949.html#section-3.1) requires CBOR text strings (major type 3) to be valid UTF-8. This library validates the bytes of every text string (object keys included) at decode time and rejects ill-formed UTF-8 with a [`parse_error.113`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) exception (or, with `allow_exceptions` set to `false`, a discarded value), rather than only failing later when the resulting value is dumped. Byte strings (major type 2) are unaffected and are never validated, since they are not required to hold text.
+
 Tagged items
 
 Tagged items (0xC0..0xDB) will throw a parse error by default. They can be ignored by passing `cbor_tag_handler_t::ignore` to function `from_cbor`, in which case the tag is skipped and the enclosed data item is parsed on its own. They can be stored by passing `cbor_tag_handler_t::store` to function `from_cbor`. Note that no tag is ever interpreted: for instance, a text string tagged with tag 0 (date/time) stays a string.

features/binary_formats/messagepack.md

@@ -136,6 +136,14 @@ The library maps MessagePack types to JSON value types as follows:
 
     Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
 
+!!! warning "UTF-8 validation of string values"
+
+    The MessagePack specification requires `str` values (`fixstr`, `str 8`, `str 16`, `str 32`) to be valid UTF-8.
+    This library validates the bytes of every such string (object keys included) at decode time and rejects
+    ill-formed UTF-8 with a [`parse_error.113`](../../home/exceptions.md#jsonexceptionparse_error113) exception (or,
+    with `allow_exceptions` set to `false`, a discarded value), rather than only failing later when the resulting
+    value is dumped. `bin`/`ext`/`fixext` values are unaffected and are never validated, since they are not required
+    to hold text.
 
 ??? example
 

features/binary_formats/messagepack/index.md

@@ -150,6 +150,10 @@ Info
 
 Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
 
+UTF-8 validation of string values
+
+The MessagePack specification requires `str` values (`fixstr`, `str 8`, `str 16`, `str 32`) to be valid UTF-8. This library validates the bytes of every such string (object keys included) at decode time and rejects ill-formed UTF-8 with a [`parse_error.113`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) exception (or, with `allow_exceptions` set to `false`, a discarded value), rather than only failing later when the resulting value is dumped. `bin`/`ext`/`fixext` values are unaffected and are never validated, since they are not required to hold text.
+
 Example
 
 ```

features/namespace.md

@@ -19,6 +19,7 @@ The complete default namespace name is derived as follows:
     - [`JSON_BRACE_INIT_COPY_SEMANTICS`](../api/macros/json_brace_init_copy_semantics.md) defined non-zero appends
       `_bics`.
     - [`JSON_PRECISE_STREAM_POSITION`](../api/macros/json_precise_stream_position.md) defined non-zero appends `_psp`.
+    - [`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md) defined non-zero appends `_snul`.
 - The inline namespace ends with the suffix `_v` followed by the 3 components of the version number separated by
   underscores. To omit the version component, see [Disabling the version component](#disabling-the-version-component)
   below.

features/namespace/index.md

@@ -13,6 +13,7 @@ The complete default namespace name is derived as follows:
   - [`JSON_DIAGNOSTIC_POSITIONS`](https://json.nlohmann.me/api/macros/json_diagnostic_positions/index.md) defined non-zero appends `_dp`.
   - [`JSON_BRACE_INIT_COPY_SEMANTICS`](https://json.nlohmann.me/api/macros/json_brace_init_copy_semantics/index.md) defined non-zero appends `_bics`.
   - [`JSON_PRECISE_STREAM_POSITION`](https://json.nlohmann.me/api/macros/json_precise_stream_position/index.md) defined non-zero appends `_psp`.
+  - [`JSON_STRICT_NUL_HANDLING`](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md) defined non-zero appends `_snul`.
 - The inline namespace ends with the suffix `_v` followed by the 3 components of the version number separated by underscores. To omit the version component, see [Disabling the version component](#disabling-the-version-component) below.
 
 For example, the namespace name for version 3.11.2 with `JSON_DIAGNOSTICS` defined to `1` is:

features/types/template_parameters.md

@@ -562,7 +562,11 @@ binary32 or binary64 field and have no encoding for `#!cpp long double`.
 ## `AllocatorType`
 
 `AllocatorType` is instantiated with **one** argument, for each of `object_t`, `array_t`, `string_t`, `binary_t`,
-`basic_json`, and `#!cpp std::pair<const StringType, basic_json>`.
+`basic_json`, `#!cpp std::pair<const StringType, basic_json>`, and `#!cpp std::pair<StringType, basic_json>`.
+
+`AllocatorType` is not the only allocator a `basic_json` uses. It allocates the JSON values themselves, but most
+temporary storage is allocated with `#!cpp std::allocator`. This includes the parser's stacks and the stacks that
+process deeply nested values without recursion.
 
 ### Always required
 

features/types/template_parameters/index.md

@@ -928,7 +928,9 @@ If `std::numeric_limits<NumberFloatType>` describes an IEEE 754 binary32 or bina
 
 ## `AllocatorType`
 
-`AllocatorType` is instantiated with **one** argument, for each of `object_t`, `array_t`, `string_t`, `binary_t`, `basic_json`, and `std::pair<const StringType, basic_json>`.
+`AllocatorType` is instantiated with **one** argument, for each of `object_t`, `array_t`, `string_t`, `binary_t`, `basic_json`, `std::pair<const StringType, basic_json>`, and `std::pair<StringType, basic_json>`.
+
+`AllocatorType` is not the only allocator a `basic_json` uses. It allocates the JSON values themselves, but most temporary storage is allocated with `std::allocator`. This includes the parser's stacks and the stacks that process deeply nested values without recursion.
 
 ### Always required