deploy: d8d47be4a5

api/basic_json/as_base_class.md

@@ -0,0 +1,53 @@
+# <small>nlohmann::basic_json::</small>as_base_class
+
+```cpp
+json_base_class_t& as_base_class() noexcept;
+const json_base_class_t& as_base_class() const noexcept;
+```
+
+Returns a reference to this object as its custom base class [`json_base_class_t`](json_base_class_t.md). No copy is
+made.
+
+Since `basic_json` derives from `json_base_class_t`, a member of `basic_json` hides any member of the custom base class
+with the same name. This function makes such hidden members accessible again.
+
+## Return value
+
+reference to this object as [`json_base_class_t`](json_base_class_t.md)
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+The function is equivalent to `static_cast<json_base_class_t&>(j)` (or `static_cast<const json_base_class_t&>(j)`).
+
+## Examples
+
+??? example
+
+    The example shows how to use `as_base_class` to access members of the custom base class that are hidden by members
+    of `basic_json`.
+    
+    ```cpp
+    --8<-- "examples/as_base_class.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/as_base_class.output"
+    ```
+
+## See also
+
+- [json_base_class_t](json_base_class_t.md) - type of the custom base class
+
+## Version history
+
+- Added in version 3.13.0.

api/basic_json/as_base_class/index.md

@@ -0,0 +1,91 @@
+# nlohmann::basic_json::as_base_class
+
+```
+json_base_class_t& as_base_class() noexcept;
+const json_base_class_t& as_base_class() const noexcept;
+```
+
+Returns a reference to this object as its custom base class [`json_base_class_t`](https://json.nlohmann.me/api/basic_json/json_base_class_t/index.md). No copy is made.
+
+Since `basic_json` derives from `json_base_class_t`, a member of `basic_json` hides any member of the custom base class with the same name. This function makes such hidden members accessible again.
+
+## Return value
+
+reference to this object as [`json_base_class_t`](https://json.nlohmann.me/api/basic_json/json_base_class_t/index.md)
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Constant.
+
+## Notes
+
+The function is equivalent to `static_cast<json_base_class_t&>(j)` (or `static_cast<const json_base_class_t&>(j)`).
+
+## Examples
+
+Example
+
+The example shows how to use `as_base_class` to access members of the custom base class that are hidden by members of `basic_json`.
+
+```
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+class base_class_with_hidden_members
+{
+  public:
+    const char* type_name() const noexcept
+    {
+        return "my_type_name";
+    }
+
+    std::size_t size() const noexcept
+    {
+        return 42;
+    }
+};
+
+using json = nlohmann::basic_json <
+             std::map,
+             std::vector,
+             std::string,
+             bool,
+             std::int64_t,
+             std::uint64_t,
+             double,
+             std::allocator,
+             nlohmann::adl_serializer,
+             std::vector<std::uint8_t>,
+             base_class_with_hidden_members
+             >;
+
+int main()
+{
+    json j = {1, 2, 3};
+
+    // the members of basic_json hide the members of the base class
+    std::cout << j.type_name() << ' ' << j.size() << '\n';
+
+    // access the hidden members of the base class
+    std::cout << j.as_base_class().type_name() << ' ' << j.as_base_class().size() << '\n';
+}
+```
+
+Output:
+
+```
+array 3
+my_type_name 42
+```
+
+## See also
+
+- [json_base_class_t](https://json.nlohmann.me/api/basic_json/json_base_class_t/index.md) - type of the custom base class
+
+## Version history
+
+- Added in version 3.13.0 unreleased.

api/basic_json/at.md

@@ -238,5 +238,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 1. Added in version 1.0.0.
 2. Added in version 1.0.0.
-3. Added in version 3.11.0.
+3. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
+   already supported by [`operator[]`](operator[].md), [`value`](value.md), [`find`](find.md), and other lookup
+   functions.
 4. Added in version 2.0.0.

api/basic_json/at/index.md

@@ -674,5 +674,5 @@ Output:
 
 1. Added in version 1.0.0.
 1. Added in version 1.0.0.
-1. Added in version 3.11.0.
+1. Added in version 3.11.0. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`value`](https://json.nlohmann.me/api/basic_json/value/index.md), [`find`](https://json.nlohmann.me/api/basic_json/find/index.md), and other lookup functions.
 1. Added in version 2.0.0.

api/basic_json/basic_json.md

@@ -293,6 +293,15 @@ basic_json(basic_json&& other) noexcept;
         When used without parentheses around an empty initializer list, `basic_json()` is called instead of this
         function, yielding the JSON `#!json null` value.
 
+- Overload 4:
+
+    !!! info "Implicit conversion"
+
+        The conversion is implicit unless [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md)
+        is defined to `0` and `BasicJsonType::string_t` differs from `string_t`. In that case, the constructor is
+        `explicit`, so a JSON value with a different string type is no longer silently converted, for example when it is
+        passed to a function taking `#!cpp const json&`. Write `#!cpp json(other)` or `#!cpp other.get<json>()` instead.
+
 - Overload 7:
 
     !!! info "Preconditions"
@@ -466,7 +475,8 @@ basic_json(basic_json&& other) noexcept;
 1. Since version 1.0.0.
 2. Since version 1.0.0.
 3. Since version 2.1.0.
-4. Since version 3.2.0.
+4. Since version 3.2.0. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since
+   version 3.13.0.
 5. Since version 1.0.0.
 6. Since version 1.0.0.
 7. Since version 1.0.0. Fixed in version 3.13.0 to also check the iterator range for binary values; before, a range

api/basic_json/basic_json/index.md

@@ -226,6 +226,12 @@ this requirement is not met.
 
   When used without parentheses around an empty initializer list, `basic_json()` is called instead of this function, yielding the JSON `null` value.
 
+- Overload 4:
+
+  Implicit conversion
+
+  The conversion is implicit unless [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md) is defined to `0` and `BasicJsonType::string_t` differs from `string_t`. In that case, the constructor is `explicit`, so a JSON value with a different string type is no longer silently converted, for example when it is passed to a function taking `const json&`. Write `json(other)` or `other.get<json>()` instead.
+
 - Overload 7:
 
   Preconditions
@@ -824,7 +830,7 @@ null
 1. Since version 1.0.0.
 1. Since version 1.0.0.
 1. Since version 2.1.0.
-1. Since version 3.2.0.
+1. Since version 3.2.0. Explicit for different string types if `JSON_USE_IMPLICIT_CONVERSIONS` is `0` since version 3.13.0 unreleased.
 1. Since version 1.0.0.
 1. Since version 1.0.0.
 1. Since version 1.0.0. Fixed in version 3.13.0 unreleased to also check the iterator range for binary values; before, a range that did not cover the whole value (such as `(end(), end())`) was accepted and the whole binary value was copied, unlike the other primitive types.

api/basic_json/contains.md

@@ -131,7 +131,9 @@ Logarithmic in the size of the JSON object.
 ## Version history
 
 1. Added in version 3.11.0.
-2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0.
+2. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Fixed in
+   version 3.13.0 to consistently accept `std::string_view`-convertible keys, as already supported by
+   [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup functions.
 3. Added in version 3.7.0.
 4. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of
    causing undefined behavior at runtime.

api/basic_json/contains/index.md

@@ -204,6 +204,6 @@ false
 ## Version history
 
 1. Added in version 3.11.0.
-1. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0.
+1. Added in version 3.6.0. Extended template `KeyType` to support comparable types in version 3.11.0. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`value`](https://json.nlohmann.me/api/basic_json/value/index.md), and other lookup functions.
 1. Added in version 3.7.0.
 1. Deleted overloads for integral key types added in version 3.13.0 unreleased to reject such calls at compile time instead of causing undefined behavior at runtime.

api/basic_json/count.md

@@ -84,6 +84,8 @@ Logarithmic in the size of the JSON object.
 ## Version history
 
 1. Added in version 3.11.0.
-2. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0.
+2. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0. Fixed in version 3.13.0 to
+   consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md),
+   [`at`](at.md), [`value`](value.md), and other lookup functions.
 3. Deleted overload for integral key types added in version 3.13.0 to reject such calls at compile time instead of
    causing undefined behavior at runtime.

api/basic_json/count/index.md

@@ -113,5 +113,5 @@ number of elements with key "three": 0
 ## Version history
 
 1. Added in version 3.11.0.
-1. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0.
+1. Added in version 1.0.0. Changed parameter `key` type to `KeyType&&` in version 3.11.0. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`value`](https://json.nlohmann.me/api/basic_json/value/index.md), and other lookup functions.
 1. Deleted overload for integral key types added in version 3.13.0 unreleased to reject such calls at compile time instead of causing undefined behavior at runtime.

api/basic_json/dump.md

@@ -25,10 +25,12 @@ and `ensure_ascii` parameters.
     result consists of ASCII characters only.
 
 `error_handler` (in)
-:   how to react on decoding errors; there are three possible values (see [`error_handler_t`](error_handler_t.md):
+:   how to react on decoding errors; there are four possible values (see [`error_handler_t`](error_handler_t.md):
     `strict` (throws an exception in case a decoding error occurs; default), `replace` (replace invalid UTF-8 sequences
-    with U+FFFD), and `ignore` (ignore invalid UTF-8 sequences during serialization; all valid bytes are copied to the
-    output unchanged, and invalid bytes are dropped)).
+    with U+FFFD), `ignore` (ignore invalid UTF-8 sequences during serialization; all valid bytes are copied to the
+    output unchanged, and invalid bytes are dropped), and `keep` (write the ill-formed bytes to the output as is,
+    without escaping them, even if `ensure_ascii` is `#!cpp true`; the result is then not valid UTF-8, but equals the
+    input bytes exactly, and well-formed characters around the ill-formed bytes are still escaped as usual)).
     
 ## Return value
 
@@ -94,3 +96,4 @@ Binary values are serialized as an object containing two keys:
 - Indentation character `indent_char`, option `ensure_ascii` and exceptions added in version 3.0.0.
 - Error handlers added in version 3.4.0.
 - Serialization of binary values added in version 3.8.0.
+- Error handler `keep` added in version 3.13.0.

api/basic_json/dump/index.md

@@ -17,7 +17,7 @@ Serialization function for JSON values. The function tries to mimic Python's [`j
 
 `ensure_ascii` (in) : If `ensure_ascii` is true, all non-ASCII characters in the output are escaped with `\uXXXX` sequences, and the result consists of ASCII characters only.
 
-`error_handler` (in) : how to react on decoding errors; there are three possible values (see [`error_handler_t`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md): `strict` (throws an exception in case a decoding error occurs; default), `replace` (replace invalid UTF-8 sequences with U+FFFD), and `ignore` (ignore invalid UTF-8 sequences during serialization; all valid bytes are copied to the output unchanged, and invalid bytes are dropped)).
+`error_handler` (in) : how to react on decoding errors; there are four possible values (see [`error_handler_t`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md): `strict` (throws an exception in case a decoding error occurs; default), `replace` (replace invalid UTF-8 sequences with U+FFFD), `ignore` (ignore invalid UTF-8 sequences during serialization; all valid bytes are copied to the output unchanged, and invalid bytes are dropped), and `keep` (write the ill-formed bytes to the output as is, without escaping them, even if `ensure_ascii` is `true`; the result is then not valid UTF-8, but equals the input bytes exactly, and well-formed characters around the ill-formed bytes are still escaped as usual)).
 
 ## Return value
 
@@ -177,3 +177,4 @@ string with ignored invalid characters: "äü"
 - Indentation character `indent_char`, option `ensure_ascii` and exceptions added in version 3.0.0.
 - Error handlers added in version 3.4.0.
 - Serialization of binary values added in version 3.8.0.
+- Error handler `keep` added in version 3.13.0 unreleased.

api/basic_json/emplace.md

@@ -70,3 +70,5 @@ Logarithmic in the size of the container, O(log(`size()`)).
 ## Version history
 
 - Since version 2.0.8.
+- Fixed in version 3.13.0: for [`ordered_json`](../ordered_json.md), the value could previously only be passed as an
+  rvalue; it can now also be passed as an lvalue or a `#!cpp const` lvalue, matching the behavior of `json`.

api/basic_json/emplace/index.md

@@ -95,3 +95,4 @@ null
 ## Version history
 
 - Since version 2.0.8.
+- Fixed in version 3.13.0 unreleased: for [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md), the value could previously only be passed as an rvalue; it can now also be passed as an lvalue or a `const` lvalue, matching the behavior of `json`.

api/basic_json/erase.md

@@ -213,5 +213,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
 2. Added in version 1.0.0. Added support for binary types in version 3.8.0.
 3. Added in version 1.0.0.
-4. Added in version 3.11.0.
+4. Added in version 3.11.0. Fixed in version 3.13.0 to consistently accept `std::string_view`-convertible keys, as
+   already supported by [`operator[]`](operator[].md), [`at`](at.md), [`value`](value.md), and other lookup
+   functions.
 5. Added in version 1.0.0.

api/basic_json/erase/index.md

@@ -309,5 +309,5 @@ Output:
 1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
 1. Added in version 1.0.0. Added support for binary types in version 3.8.0.
 1. Added in version 1.0.0.
-1. Added in version 3.11.0.
+1. Added in version 3.11.0. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`value`](https://json.nlohmann.me/api/basic_json/value/index.md), and other lookup functions.
 1. Added in version 1.0.0.

api/basic_json/error_handler_t.md

@@ -4,15 +4,31 @@
 enum class error_handler_t {
     strict,
     replace,
-    ignore
+    ignore,
+    keep
 };
 ```
 
-This enumeration is used in the [`dump`](dump.md) function to choose how to treat decoding errors while serializing a
-`basic_json` value. Three values are differentiated:
+This enumeration is used to choose how to treat ill-formed UTF-8 in a string value or object key:
+
+- [`dump`](dump.md) uses it while serializing a `basic_json` value to text.
+- [`to_cbor`](to_cbor.md), [`to_msgpack`](to_msgpack.md), [`to_ubjson`](to_ubjson.md), [`to_bjdata`](to_bjdata.md),
+  and [`to_bson`](to_bson.md) use it while serializing a `basic_json` value to that binary format. Their default is
+  `keep`, as no binary writer checked before this parameter was added. CBOR, UBJSON, BJData, and BSON require valid
+  UTF-8, so for these four the default is `strict` if [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md)
+  is enabled; MessagePack's specification explicitly allows a string to contain ill-formed UTF-8, so `to_msgpack`
+  stays at `keep`. `to_bon8` does not take this parameter: BON8 always validates, since UTF-8 lead bytes are
+  structural to that format.
+- [`from_cbor`](from_cbor.md), [`from_msgpack`](from_msgpack.md), [`from_ubjson`](from_ubjson.md),
+  [`from_bjdata`](from_bjdata.md), and [`from_bson`](from_bson.md) use it while parsing that binary format, to decide
+  whether to check a string value or object key for well-formed UTF-8 at all; by default (`keep`) they do not, as no
+  binary reader did before this parameter was added. `from_bon8` does not take this parameter, for the same reason
+  `to_bon8` does not.
+
+Four values are differentiated:
 
 strict
-:   throw a `type_error` exception in case of invalid UTF-8
+:   throw a `type_error`/`parse_error` exception in case of invalid UTF-8
 
 replace
 :   replace invalid UTF-8 sequences with U+FFFD (� REPLACEMENT CHARACTER)
@@ -20,6 +36,12 @@ replace
 ignore
 :   ignore invalid UTF-8 sequences; all valid bytes are copied to the output unchanged, and invalid bytes are dropped
 
+keep
+:   keep invalid UTF-8 sequences unchanged; only meaningful for the binary formats mentioned above, since [`dump`]
+    (dump.md) itself must produce text, and `keep` there writes the ill-formed bytes to the output as is, so the
+    result is then not valid UTF-8 (but still equals the input bytes exactly, including around any well-formed
+    characters, which are still escaped as usual)
+
 ## Examples
 
 ??? example
@@ -45,3 +67,5 @@ ignore
 ## Version history
 
 - Added in version 3.4.0.
+- Added `keep`, and made this enumeration apply to the binary readers and writers in addition to `dump`, in version
+  3.13.0.

api/basic_json/error_handler_t/index.md

@@ -4,18 +4,27 @@
 enum class error_handler_t {
     strict,
     replace,
-    ignore
+    ignore,
+    keep
 };
 ```
 
-This enumeration is used in the [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) function to choose how to treat decoding errors while serializing a `basic_json` value. Three values are differentiated:
+This enumeration is used to choose how to treat ill-formed UTF-8 in a string value or object key:
 
-strict : throw a `type_error` exception in case of invalid UTF-8
+- [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) uses it while serializing a `basic_json` value to text.
+- [`to_cbor`](https://json.nlohmann.me/api/basic_json/to_cbor/index.md), [`to_msgpack`](https://json.nlohmann.me/api/basic_json/to_msgpack/index.md), [`to_ubjson`](https://json.nlohmann.me/api/basic_json/to_ubjson/index.md), [`to_bjdata`](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md), and [`to_bson`](https://json.nlohmann.me/api/basic_json/to_bson/index.md) use it while serializing a `basic_json` value to that binary format. Their default is `keep`, as no binary writer checked before this parameter was added. CBOR, UBJSON, BJData, and BSON require valid UTF-8, so for these four the default is `strict` if [`JSON_STRICT_BINARY_UTF8`](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) is enabled; MessagePack's specification explicitly allows a string to contain ill-formed UTF-8, so `to_msgpack` stays at `keep`. `to_bon8` does not take this parameter: BON8 always validates, since UTF-8 lead bytes are structural to that format.
+- [`from_cbor`](https://json.nlohmann.me/api/basic_json/from_cbor/index.md), [`from_msgpack`](https://json.nlohmann.me/api/basic_json/from_msgpack/index.md), [`from_ubjson`](https://json.nlohmann.me/api/basic_json/from_ubjson/index.md), [`from_bjdata`](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md), and [`from_bson`](https://json.nlohmann.me/api/basic_json/from_bson/index.md) use it while parsing that binary format, to decide whether to check a string value or object key for well-formed UTF-8 at all; by default (`keep`) they do not, as no binary reader did before this parameter was added. `from_bon8` does not take this parameter, for the same reason `to_bon8` does not.
+
+Four values are differentiated:
+
+strict : throw a `type_error`/`parse_error` exception in case of invalid UTF-8
 
 replace : replace invalid UTF-8 sequences with U+FFFD (� REPLACEMENT CHARACTER)
 
 ignore : ignore invalid UTF-8 sequences; all valid bytes are copied to the output unchanged, and invalid bytes are dropped
 
+keep : keep invalid UTF-8 sequences unchanged; only meaningful for the binary formats mentioned above, since \[`dump`\] (dump.md) itself must produce text, and `keep` there writes the ill-formed bytes to the output as is, so the result is then not valid UTF-8 (but still equals the input bytes exactly, including around any well-formed characters, which are still escaped as usual)
+
 ## Examples
 
 Example
@@ -45,7 +54,8 @@ int main()
               << j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)
               << "\nstring with ignored invalid characters: "
               << j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)
-              << '\n';
+              << "\nstring with the invalid byte kept as is (" << j_invalid.dump(-1, ' ', false, json::error_handler_t::keep).size()
+              << " bytes, not valid UTF-8 itself)\n";
 }
 ```
 
@@ -55,6 +65,7 @@ Output:
 [json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
 string with replaced invalid characters: "ä�ü"
 string with ignored invalid characters: "äü"
+string with the invalid byte kept as is (7 bytes, not valid UTF-8 itself)
 ```
 
 ## See also
@@ -65,3 +76,4 @@ string with ignored invalid characters: "äü"
 ## Version history
 
 - Added in version 3.4.0.
+- Added `keep`, and made this enumeration apply to the binary readers and writers in addition to `dump`, in version 3.13.0.

api/basic_json/find.md

@@ -88,6 +88,8 @@ Logarithmic in the size of the JSON object.
 ## Version history
 
 1. Added in version 3.11.0.
-2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0.
+2. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Fixed in version 3.13.0 to
+   consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](operator[].md),
+   [`at`](at.md), [`value`](value.md), and other lookup functions.
 3. Deleted overloads for integral key types added in version 3.13.0 to reject such calls at compile time instead of
    causing undefined behavior at runtime.

api/basic_json/find/index.md

@@ -122,5 +122,5 @@ value at key "two": 2
 ## Version history
 
 1. Added in version 3.11.0.
-1. Added in version 1.0.0. Changed to support comparable types in version 3.11.0.
+1. Added in version 1.0.0. Changed to support comparable types in version 3.11.0. Fixed in version 3.13.0 unreleased to consistently accept `std::string_view`-convertible keys, as already supported by [`operator[]`](https://json.nlohmann.me/api/basic_json/operator%5B%5D/index.md), [`at`](https://json.nlohmann.me/api/basic_json/at/index.md), [`value`](https://json.nlohmann.me/api/basic_json/value/index.md), and other lookup functions.
 1. Deleted overloads for integral key types added in version 3.13.0 unreleased to reject such calls at compile time instead of causing undefined behavior at runtime.

api/basic_json/from_bjdata.md

@@ -5,12 +5,14 @@
 template<typename InputType>
 static basic_json from_bjdata(InputType&& i,
                               const bool strict = true,
-                              const bool allow_exceptions = true);
+                              const bool allow_exceptions = true,
+                              const error_handler_t error_handler = error_handler_t::keep);
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_bjdata(IteratorType first, SentinelType last,
                               const bool strict = true,
-                              const bool allow_exceptions = true);
+                              const bool allow_exceptions = true,
+                              const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the BJData (Binary JData) serialization format.
@@ -58,6 +60,12 @@ The exact mapping and its limitations are described on a [dedicated page](../../
 `allow_exceptions` (in)
 :   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
 
+`error_handler` (in)
+:   how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](error_handler_t.md).
+    BJData does not require a decoder to reject ill-formed UTF-8, so checking is opt-in: the default, `keep`, does not
+    check at all, as every binary reader did before this parameter was added; `strict` checks and throws;
+    `replace`/`ignore` sanitize the string the same way [`dump`](dump.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
@@ -73,7 +81,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
   the end of the file was not reached when `strict` was set to true
 - Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
 - Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
-  successfully
+  successfully, or if a string value or object key is not valid UTF-8 and `error_handler` is `strict`
 - Throws [out_of_range.408](../../home/exceptions.md#jsonexceptionout_of_range408) if the size of an optimized container
   or n-dimensional array cannot be represented by `std::size_t`
 
@@ -111,3 +119,4 @@ Linear in the size of the input.
 - Added in version 3.11.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Added `error_handler` parameter in version 3.13.0.

api/basic_json/from_bjdata/index.md

@@ -5,12 +5,14 @@
 template<typename InputType>
 static basic_json from_bjdata(InputType&& i,
                               const bool strict = true,
-                              const bool allow_exceptions = true);
+                              const bool allow_exceptions = true,
+                              const error_handler_t error_handler = error_handler_t::keep);
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_bjdata(IteratorType first, SentinelType last,
                               const bool strict = true,
-                              const bool allow_exceptions = true);
+                              const bool allow_exceptions = true,
+                              const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the BJData (Binary JData) serialization format.
@@ -54,6 +56,8 @@ The exact mapping and its limitations are described on a [dedicated page](https:
 
 `allow_exceptions` (in) : whether to throw exceptions in case of a parse error (optional, `true` by default)
 
+`error_handler` (in) : how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md). BJData does not require a decoder to reject ill-formed UTF-8, so checking is opt-in: the default, `keep`, does not check at all, as every binary reader did before this parameter was added; `strict` checks and throws; `replace`/`ignore` sanitize the string the same way [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](https://json.nlohmann.me/api/basic_json/is_discarded/index.md).
@@ -66,7 +70,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 - Throws [parse_error.110](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error110) if the given input ends prematurely or the end of the file was not reached when `strict` was set to true
 - Throws [parse_error.112](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error112) if a parse error occurs
-- Throws [parse_error.113](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) if a string could not be parsed successfully
+- Throws [parse_error.113](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) if a string could not be parsed successfully, or if a string value or object key is not valid UTF-8 and `error_handler` is `strict`
 - Throws [out_of_range.408](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range408) if the size of an optimized container or n-dimensional array cannot be represented by `std::size_t`
 
 ## Complexity
@@ -125,3 +129,4 @@ Output:
 - Added in version 3.11.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
+- Added `error_handler` parameter in version 3.13.0 unreleased.

api/basic_json/from_bson.md

@@ -5,12 +5,14 @@
 template<typename InputType>
 static basic_json from_bson(InputType&& i,
                             const bool strict = true,
-                            const bool allow_exceptions = true);
+                            const bool allow_exceptions = true,
+                            const error_handler_t error_handler = error_handler_t::keep);
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_bson(IteratorType first, SentinelType last,
                             const bool strict = true,
-                            const bool allow_exceptions = true);
+                            const bool allow_exceptions = true,
+                            const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the BSON (Binary JSON) serialization format.
@@ -58,6 +60,12 @@ The exact mapping and its limitations are described on a [dedicated page](../../
 `allow_exceptions` (in)
 :   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
 
+`error_handler` (in)
+:   how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](error_handler_t.md).
+    BSON does not require a decoder to reject ill-formed UTF-8, so checking is opt-in: the default, `keep`, does not
+    check at all, as every binary reader did before this parameter was added; `strict` checks and throws;
+    `replace`/`ignore` sanitize the string the same way [`dump`](dump.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
@@ -75,6 +83,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
   invalid string or byte array length)
 - Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is
   encountered
+- Throws [`parse_error.113`](../../home/exceptions.md#jsonexceptionparse_error113) if a string value or object key is
+  not valid UTF-8 and `error_handler` is `strict`
 
 ## Complexity
 
@@ -111,6 +121,7 @@ Linear in the size of the input.
 - Added in version 3.4.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Added `error_handler` parameter in version 3.13.0.
 
 !!! warning "Deprecation"
 

api/basic_json/from_bson/index.md

@@ -5,12 +5,14 @@
 template<typename InputType>
 static basic_json from_bson(InputType&& i,
                             const bool strict = true,
-                            const bool allow_exceptions = true);
+                            const bool allow_exceptions = true,
+                            const error_handler_t error_handler = error_handler_t::keep);
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_bson(IteratorType first, SentinelType last,
                             const bool strict = true,
-                            const bool allow_exceptions = true);
+                            const bool allow_exceptions = true,
+                            const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the BSON (Binary JSON) serialization format.
@@ -54,6 +56,8 @@ The exact mapping and its limitations are described on a [dedicated page](https:
 
 `allow_exceptions` (in) : whether to throw exceptions in case of a parse error (optional, `true` by default)
 
+`error_handler` (in) : how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md). BSON does not require a decoder to reject ill-formed UTF-8, so checking is opt-in: the default, `keep`, does not check at all, as every binary reader did before this parameter was added; `strict` checks and throws; `replace`/`ignore` sanitize the string the same way [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](https://json.nlohmann.me/api/basic_json/is_discarded/index.md).
@@ -67,6 +71,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [`parse_error.110`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error110) if the given input ends prematurely or the end of the input was not reached when `strict` was set to true
 - Throws [`parse_error.112`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error112) if a parse error occurs (e.g., an invalid string or byte array length)
 - Throws [`parse_error.114`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error114) if an unsupported BSON record type is encountered
+- Throws [`parse_error.113`](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) if a string value or object key is not valid UTF-8 and `error_handler` is `strict`
 
 ## Complexity
 
@@ -126,6 +131,7 @@ Output:
 - Added in version 3.4.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
+- Added `error_handler` parameter in version 3.13.0 unreleased.
 
 Deprecation
 

api/basic_json/from_cbor.md

@@ -6,14 +6,16 @@ template<typename InputType>
 static basic_json from_cbor(InputType&& i,
                             const bool strict = true,
                             const bool allow_exceptions = true,
-                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
+                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error,
+                            const error_handler_t error_handler = error_handler_t::keep);
 
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_cbor(IteratorType first, SentinelType last,
                             const bool strict = true,
                             const bool allow_exceptions = true,
-                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
+                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error,
+                            const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the CBOR (Concise Binary Object Representation) serialization format.
@@ -65,6 +67,12 @@ The exact mapping and its limitations are described on a [dedicated page](../../
 :   how to treat CBOR tags (optional, `error` by default); see [`cbor_tag_handler_t`](cbor_tag_handler_t.md) for more
     information
 
+`error_handler` (in)
+:   how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](error_handler_t.md).
+    CBOR does not require a decoder to reject ill-formed UTF-8, so checking is opt-in: the default, `keep`, does not
+    check at all, as every binary reader did before this parameter was added; `strict` checks and throws;
+    `replace`/`ignore` sanitize the string the same way [`dump`](dump.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
@@ -80,8 +88,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
   the end of the file was not reached when `strict` was set to true
 - Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from CBOR were
   used in the given input or if the input is not valid CBOR
-- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a map key is not a string (keys of other
-  types are not supported, as JSON object keys are always strings) or a string is malformed
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a map key is not a string (keys of
+  other types are not supported, as JSON object keys are always strings), or if a string value or object key is not
+  valid UTF-8 and `error_handler` is `strict`
 
 ## Complexity
 
@@ -121,6 +130,7 @@ Linear in the size of the input.
 - Added `tag_handler` parameter in version 3.9.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Added `error_handler` parameter in version 3.13.0.
 
 !!! warning "Deprecation"
 

api/basic_json/from_cbor/index.md

@@ -6,14 +6,16 @@ template<typename InputType>
 static basic_json from_cbor(InputType&& i,
                             const bool strict = true,
                             const bool allow_exceptions = true,
-                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
+                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error,
+                            const error_handler_t error_handler = error_handler_t::keep);
 
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_cbor(IteratorType first, SentinelType last,
                             const bool strict = true,
                             const bool allow_exceptions = true,
-                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
+                            const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error,
+                            const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the CBOR (Concise Binary Object Representation) serialization format.
@@ -59,6 +61,8 @@ The exact mapping and its limitations are described on a [dedicated page](https:
 
 `tag_handler` (in) : how to treat CBOR tags (optional, `error` by default); see [`cbor_tag_handler_t`](https://json.nlohmann.me/api/basic_json/cbor_tag_handler_t/index.md) for more information
 
+`error_handler` (in) : how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md). CBOR does not require a decoder to reject ill-formed UTF-8, so checking is opt-in: the default, `keep`, does not check at all, as every binary reader did before this parameter was added; `strict` checks and throws; `replace`/`ignore` sanitize the string the same way [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](https://json.nlohmann.me/api/basic_json/is_discarded/index.md).
@@ -71,7 +75,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 - Throws [parse_error.110](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error110) if the given input ends prematurely or the end of the file was not reached when `strict` was set to true
 - Throws [parse_error.112](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error112) if unsupported features from CBOR were used in the given input or if the input is not valid CBOR
-- Throws [parse_error.113](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) if a map key is not a string (keys of other types are not supported, as JSON object keys are always strings) or a string is malformed
+- Throws [parse_error.113](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) if a map key is not a string (keys of other types are not supported, as JSON object keys are always strings), or if a string value or object key is not valid UTF-8 and `error_handler` is `strict`
 
 ## Complexity
 
@@ -133,6 +137,7 @@ Output:
 - Added `tag_handler` parameter in version 3.9.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
+- Added `error_handler` parameter in version 3.13.0 unreleased.
 
 Deprecation
 

api/basic_json/from_msgpack.md

@@ -5,12 +5,14 @@
 template<typename InputType>
 static basic_json from_msgpack(InputType&& i,
                                const bool strict = true,
-                               const bool allow_exceptions = true);
+                               const bool allow_exceptions = true,
+                               const error_handler_t error_handler = error_handler_t::keep);
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_msgpack(IteratorType first, SentinelType last,
                                const bool strict = true,
-                               const bool allow_exceptions = true);
+                               const bool allow_exceptions = true,
+                               const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the MessagePack serialization format.
@@ -58,6 +60,12 @@ The exact mapping and its limitations are described on a [dedicated page](../../
 `allow_exceptions` (in)
 :   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
 
+`error_handler` (in)
+:   how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](error_handler_t.md).
+    MessagePack's specification explicitly allows ill-formed UTF-8, so checking is opt-in: the default, `keep`, does
+    not check at all, as every binary reader did before this parameter was added; `strict` checks and throws;
+    `replace`/`ignore` sanitize the string the same way [`dump`](dump.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
@@ -73,8 +81,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
   the end of the file was not reached when `strict` was set to true
 - Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if unsupported features from
   MessagePack were used in the given input or if the input is not valid MessagePack
-- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a map key is not a string (keys of other
-  types are not supported, as JSON object keys are always strings) or a string is malformed
+- Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a map key is not a string (keys of
+  other types are not supported, as JSON object keys are always strings), or if a string value or object key is not
+  valid UTF-8 and `error_handler` is `strict`
 
 ## Complexity
 
@@ -113,6 +122,7 @@ Linear in the size of the input.
 - Added `allow_exceptions` parameter in version 3.2.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Added `error_handler` parameter in version 3.13.0.
 
 !!! warning "Deprecation"
 

api/basic_json/from_msgpack/index.md

@@ -5,12 +5,14 @@
 template<typename InputType>
 static basic_json from_msgpack(InputType&& i,
                                const bool strict = true,
-                               const bool allow_exceptions = true);
+                               const bool allow_exceptions = true,
+                               const error_handler_t error_handler = error_handler_t::keep);
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_msgpack(IteratorType first, SentinelType last,
                                const bool strict = true,
-                               const bool allow_exceptions = true);
+                               const bool allow_exceptions = true,
+                               const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the MessagePack serialization format.
@@ -54,6 +56,8 @@ The exact mapping and its limitations are described on a [dedicated page](https:
 
 `allow_exceptions` (in) : whether to throw exceptions in case of a parse error (optional, `true` by default)
 
+`error_handler` (in) : how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md). MessagePack's specification explicitly allows ill-formed UTF-8, so checking is opt-in: the default, `keep`, does not check at all, as every binary reader did before this parameter was added; `strict` checks and throws; `replace`/`ignore` sanitize the string the same way [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](https://json.nlohmann.me/api/basic_json/is_discarded/index.md).
@@ -66,7 +70,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 - Throws [parse_error.110](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error110) if the given input ends prematurely or the end of the file was not reached when `strict` was set to true
 - Throws [parse_error.112](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error112) if unsupported features from MessagePack were used in the given input or if the input is not valid MessagePack
-- Throws [parse_error.113](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) if a map key is not a string (keys of other types are not supported, as JSON object keys are always strings) or a string is malformed
+- Throws [parse_error.113](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) if a map key is not a string (keys of other types are not supported, as JSON object keys are always strings), or if a string value or object key is not valid UTF-8 and `error_handler` is `strict`
 
 ## Complexity
 
@@ -127,6 +131,7 @@ Output:
 - Added `allow_exceptions` parameter in version 3.2.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
+- Added `error_handler` parameter in version 3.13.0 unreleased.
 
 Deprecation
 

api/basic_json/from_ubjson.md

@@ -5,12 +5,14 @@
 template<typename InputType>
 static basic_json from_ubjson(InputType&& i,
                               const bool strict = true,
-                              const bool allow_exceptions = true);
+                              const bool allow_exceptions = true,
+                              const error_handler_t error_handler = error_handler_t::keep);
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_ubjson(IteratorType first, SentinelType last,
                               const bool strict = true,
-                              const bool allow_exceptions = true);
+                              const bool allow_exceptions = true,
+                              const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the UBJSON (Universal Binary JSON) serialization format.
@@ -58,6 +60,12 @@ The exact mapping and its limitations are described on a [dedicated page](../../
 `allow_exceptions` (in)
 :   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
 
+`error_handler` (in)
+:   how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](error_handler_t.md).
+    UBJSON does not require a decoder to reject ill-formed UTF-8, so checking is opt-in: the default, `keep`, does not
+    check at all, as every binary reader did before this parameter was added; `strict` checks and throws;
+    `replace`/`ignore` sanitize the string the same way [`dump`](dump.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
@@ -73,7 +81,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
   the end of the file was not reached when `strict` was set to true
 - Throws [parse_error.112](../../home/exceptions.md#jsonexceptionparse_error112) if a parse error occurs
 - Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed
-  successfully
+  successfully, or if a string value or object key is not valid UTF-8 and `error_handler` is `strict`
 - Throws [out_of_range.408](../../home/exceptions.md#jsonexceptionout_of_range408) if the size of an optimized container
   or n-dimensional array cannot be represented by `std::size_t`
 
@@ -112,6 +120,7 @@ Linear in the size of the input.
 - Added `allow_exceptions` parameter in version 3.2.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
+- Added `error_handler` parameter in version 3.13.0.
 
 !!! warning "Deprecation"
 

api/basic_json/from_ubjson/index.md

@@ -5,12 +5,14 @@
 template<typename InputType>
 static basic_json from_ubjson(InputType&& i,
                               const bool strict = true,
-                              const bool allow_exceptions = true);
+                              const bool allow_exceptions = true,
+                              const error_handler_t error_handler = error_handler_t::keep);
 // (2)
 template<typename IteratorType, typename SentinelType = IteratorType>
 static basic_json from_ubjson(IteratorType first, SentinelType last,
                               const bool strict = true,
-                              const bool allow_exceptions = true);
+                              const bool allow_exceptions = true,
+                              const error_handler_t error_handler = error_handler_t::keep);
 ```
 
 Deserializes a given input to a JSON value using the UBJSON (Universal Binary JSON) serialization format.
@@ -54,6 +56,8 @@ The exact mapping and its limitations are described on a [dedicated page](https:
 
 `allow_exceptions` (in) : whether to throw exceptions in case of a parse error (optional, `true` by default)
 
+`error_handler` (in) : how to treat a string value or object key that is not valid UTF-8; see [`error_handler_t`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md). UBJSON does not require a decoder to reject ill-formed UTF-8, so checking is opt-in: the default, `keep`, does not check at all, as every binary reader did before this parameter was added; `strict` checks and throws; `replace`/`ignore` sanitize the string the same way [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) would
+
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](https://json.nlohmann.me/api/basic_json/is_discarded/index.md).
@@ -66,7 +70,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 
 - Throws [parse_error.110](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error110) if the given input ends prematurely or the end of the file was not reached when `strict` was set to true
 - Throws [parse_error.112](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error112) if a parse error occurs
-- Throws [parse_error.113](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) if a string could not be parsed successfully
+- Throws [parse_error.113](https://json.nlohmann.me/home/exceptions/#jsonexceptionparse_error113) if a string could not be parsed successfully, or if a string value or object key is not valid UTF-8 and `error_handler` is `strict`
 - Throws [out_of_range.408](https://json.nlohmann.me/home/exceptions/#jsonexceptionout_of_range408) if the size of an optimized container or n-dimensional array cannot be represented by `std::size_t`
 
 ## Complexity
@@ -126,6 +130,7 @@ Output:
 - Added `allow_exceptions` parameter in version 3.2.0.
 - Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0 unreleased.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0 unreleased.
+- Added `error_handler` parameter in version 3.13.0 unreleased.
 
 Deprecation
 

api/basic_json/index.md

@@ -179,6 +179,7 @@ Direct access to the stored value of a JSON value.
 - [**get_ref**](https://json.nlohmann.me/api/basic_json/get_ref/index.md) - get a reference value
 - [**operator ValueType**](https://json.nlohmann.me/api/basic_json/operator_ValueType/index.md) - get a value
 - [**get_binary**](https://json.nlohmann.me/api/basic_json/get_binary/index.md) - get a binary value
+- [**as_base_class**](https://json.nlohmann.me/api/basic_json/as_base_class/index.md) - access the custom base class
 
 ### Element access
 

api/basic_json/json_base_class_t.md

@@ -27,6 +27,18 @@ A `CustomBaseClass` with non-static data members forfeits `basic_json`'s
 [standard layout](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType) guarantee. See
 [Template Parameter Requirements](../../features/types/template_parameters.md#custombaseclass).
 
+#### Name conflicts
+
+Since `basic_json` derives from `CustomBaseClass`, members of `basic_json` hide members of `CustomBaseClass` with the
+same name. Hidden members remain accessible via [`as_base_class`](as_base_class.md) or by casting the value to
+`json_base_class_t`.
+
+!!! warning "Avoid generic member names"
+
+    Future versions of the library may add members to `basic_json` that hide members of `CustomBaseClass` that are
+    accessible today. To reduce the risk of such conflicts, avoid generic names for the members of `CustomBaseClass`,
+    for instance by using a distinctive prefix.
+
 ## Examples
 
 ??? example
@@ -45,8 +57,10 @@ A `CustomBaseClass` with non-static data members forfeits `basic_json`'s
 
 ## See also
 
+- [as_base_class](as_base_class.md) - access the custom base class
 - [Template Parameter Requirements](../../features/types/template_parameters.md#custombaseclass) - the requirements for `CustomBaseClass`
 
 ## Version history
 
 - Added in version 3.12.0.
+- Made a public member type in version 3.13.0; it was private before, so it could not be named outside the class.

api/basic_json/json_base_class_t/index.md

@@ -20,6 +20,14 @@ The default value for `CustomBaseClass` is `void`. In this case, an [empty base
 
 The type `CustomBaseClass` has to be a default-constructible, non-`final` class. `basic_json` only supports copy/move construction/assignment if `CustomBaseClass` does so as well. A `CustomBaseClass` with non-static data members forfeits `basic_json`'s [standard layout](https://en.cppreference.com/w/cpp/named_req/StandardLayoutType) guarantee. See [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#custombaseclass).
 
+#### Name conflicts
+
+Since `basic_json` derives from `CustomBaseClass`, members of `basic_json` hide members of `CustomBaseClass` with the same name. Hidden members remain accessible via [`as_base_class`](https://json.nlohmann.me/api/basic_json/as_base_class/index.md) or by casting the value to `json_base_class_t`.
+
+Avoid generic member names
+
+Future versions of the library may add members to `basic_json` that hide members of `CustomBaseClass` that are accessible today. To reduce the risk of such conflicts, avoid generic names for the members of `CustomBaseClass`, for instance by using a distinctive prefix.
+
 ## Examples
 
 Example
@@ -128,8 +136,10 @@ Output:
 
 ## See also
 
+- [as_base_class](https://json.nlohmann.me/api/basic_json/as_base_class/index.md) - access the custom base class
 - [Template Parameter Requirements](https://json.nlohmann.me/features/types/template_parameters/#custombaseclass) - the requirements for `CustomBaseClass`
 
 ## Version history
 
 - Added in version 3.12.0.
+- Made a public member type in version 3.13.0 unreleased; it was private before, so it could not be named outside the class.