deploy: d8d47be4a5

api/macros/index.md

@@ -18,6 +18,7 @@ Some aspects of the library can be configured by defining preprocessor macros **
 ## Parsing
 
 - [**JSON_PRECISE_STREAM_POSITION**](https://json.nlohmann.me/api/macros/json_precise_stream_position/index.md) - opt in to leaving an input stream positioned right after a parsed number
+- [**JSON_STRICT_BINARY_UTF8**](https://json.nlohmann.me/api/macros/json_strict_binary_utf8/index.md) - opt in to checking strings for valid UTF-8 in the CBOR, UBJSON, BJData, and BSON writers
 - [**JSON_STRICT_NUL_HANDLING**](https://json.nlohmann.me/api/macros/json_strict_nul_handling/index.md) - opt in to rejecting a NUL byte in the input instead of treating it as end of input
 
 ## Language support

api/macros/json_brace_init_copy_semantics.md

@@ -115,3 +115,4 @@ The default value is `0` (disabled — existing behavior is preserved).
 ## Version history
 
 - Added in version 3.13.0.
+- Planned to become the default (with the macro removed) in version 4.0.0.

api/macros/json_brace_init_copy_semantics/index.md

@@ -104,3 +104,4 @@ int main()
 ## Version history
 
 - Added in version 3.13.0 unreleased.
+- Planned to become the default (with the macro removed) in version 4.0.0.

api/macros/json_no_automatic_udls.md

@@ -43,9 +43,9 @@ By default, `#!cpp JSON_NO_AUTOMATIC_UDLS` is not defined, and `<nlohmann/json.h
 
     ```cpp
     // compiled with -DJSON_NO_AUTOMATIC_UDLS for the whole project
-    #include <nlohmann/json.hpp>
 
     // this file uses the literals, so it includes them explicitly
+    // (the header includes <nlohmann/json.hpp> itself)
     #include <nlohmann/json_literals.hpp>
 
     int main()
@@ -62,6 +62,7 @@ By default, `#!cpp JSON_NO_AUTOMATIC_UDLS` is not defined, and `<nlohmann/json.h
 - [`operator""_json`](../operator_literal_json.md)
 - [`operator""_json_pointer`](../operator_literal_json_pointer.md)
 - [`JSON_USE_GLOBAL_UDLS`](json_use_global_udls.md) - place user-defined string literals (UDLs) into the global namespace
+- [Compile times](../../integration/compile_times.md) - options to reduce compile times
 
 ## Version history
 

api/macros/json_no_automatic_udls/index.md

@@ -34,9 +34,9 @@ The code below includes the library without the literals and adds them in a sing
 
 ```
 // compiled with -DJSON_NO_AUTOMATIC_UDLS for the whole project
-#include <nlohmann/json.hpp>
 
 // this file uses the literals, so it includes them explicitly
+// (the header includes <nlohmann/json.hpp> itself)
 #include <nlohmann/json_literals.hpp>
 
 int main()
@@ -53,6 +53,7 @@ Without the include of `<nlohmann/json_literals.hpp>`, the code would fail to co
 - [`operator""_json`](https://json.nlohmann.me/api/operator_literal_json/index.md)
 - [`operator""_json_pointer`](https://json.nlohmann.me/api/operator_literal_json_pointer/index.md)
 - [`JSON_USE_GLOBAL_UDLS`](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md) - place user-defined string literals (UDLs) into the global namespace
+- [Compile times](https://json.nlohmann.me/integration/compile_times/index.md) - options to reduce compile times
 
 ## Version history
 

api/macros/json_strict_binary_utf8.md

@@ -0,0 +1,101 @@
+# JSON_STRICT_BINARY_UTF8
+
+```cpp
+#define JSON_STRICT_BINARY_UTF8 /* value */
+```
+
+When defined to `1`, the `error_handler` parameter of the binary writers [`to_cbor`](../basic_json/to_cbor.md),
+[`to_ubjson`](../basic_json/to_ubjson.md), [`to_bjdata`](../basic_json/to_bjdata.md), and
+[`to_bson`](../basic_json/to_bson.md) defaults to [`error_handler_t::strict`](../basic_json/error_handler_t.md) instead
+of `error_handler_t::keep`. These writers then check every string value and object key for valid UTF-8 and throw
+[`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) for ill-formed UTF-8, like
+[`dump`](../basic_json/dump.md) does. Without it, they write the bytes unchanged. An `error_handler` passed explicitly
+always takes precedence.
+
+The macro does not affect:
+
+- [`to_msgpack`](../basic_json/to_msgpack.md): the MessagePack specification allows a `str` value to contain bytes that
+  are not valid UTF-8, so its `error_handler` always defaults to `keep`.
+- [`to_bon8`](../basic_json/to_bon8.md): BON8 always checks, because the UTF-8 lead bytes mark where a string ends.
+- The binary readers ([`from_cbor`](../basic_json/from_cbor.md), [`from_msgpack`](../basic_json/from_msgpack.md),
+  [`from_ubjson`](../basic_json/from_ubjson.md), [`from_bjdata`](../basic_json/from_bjdata.md),
+  [`from_bson`](../basic_json/from_bson.md)): none of these formats requires a decoder to reject ill-formed UTF-8, so
+  they always return the bytes unchanged.
+
+## Default definition
+
+The default value is `0` (disabled, the behavior of version 3.12.0 and earlier is preserved).
+
+```cpp
+#define JSON_STRICT_BINARY_UTF8 0
+```
+
+## Notes
+
+!!! note "Background"
+
+    CBOR, UBJSON, BJData, and BSON all require strings to be UTF-8. Up to version 3.12.0, the writers did not check
+    this, so they could produce output that other decoders reject. Checking by default would break code that stores
+    other encodings (for instance ISO 8859-1) in a string and only ever writes it to a binary format. You can pass
+    `error_handler_t::strict` to each call, or use this macro to check by default ahead of version 4.0.0, where
+    `strict` is planned to become the default (see
+    [#5529](https://github.com/nlohmann/json/issues/5529) and [#5651](https://github.com/nlohmann/json/issues/5651)).
+
+!!! warning "Opt-in only"
+
+    This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no
+    effect.
+
+!!! note "ABI compatibility"
+
+    The value of this macro is encoded in the [namespace](../../features/namespace.md) (tag `_sbu8`), resulting in
+    distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program
+    without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.
+
+## Examples
+
+??? example "Example: default behavior (macro not defined)"
+
+    Without the macro, the bytes are written unchanged:
+
+    ```cpp
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        auto v = json::to_cbor(json("\xFF"));
+        // v is {0x61, 0xFF}
+    }
+    ```
+
+??? example "Example: opt-in check (macro defined to 1)"
+
+    With the macro, ill-formed UTF-8 is rejected:
+
+    ```cpp
+    #define JSON_STRICT_BINARY_UTF8 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        auto v = json::to_cbor(json("\xFF"));
+        // throws type_error.316: invalid UTF-8 byte at index 0: 0xFF
+    }
+    ```
+
+## See also
+
+- [**to_cbor**](../basic_json/to_cbor.md) - create a CBOR serialization of a JSON value
+- [**to_ubjson**](../basic_json/to_ubjson.md) - create a UBJSON serialization of a JSON value
+- [**to_bjdata**](../basic_json/to_bjdata.md) - create a BJData serialization of a JSON value
+- [**to_bson**](../basic_json/to_bson.md) - create a BSON serialization of a JSON value
+- [**error_handler_t**](../basic_json/error_handler_t.md) - how [`dump`](../basic_json/dump.md) treats ill-formed UTF-8
+
+## Version history
+
+- Added in version 3.13.0.
+- Planned to become the default (with the macro removed) in version 4.0.0.

api/macros/json_strict_binary_utf8/index.md

@@ -0,0 +1,83 @@
+# JSON_STRICT_BINARY_UTF8
+
+```
+#define JSON_STRICT_BINARY_UTF8 /* value */
+```
+
+When defined to `1`, the `error_handler` parameter of the binary writers [`to_cbor`](https://json.nlohmann.me/api/basic_json/to_cbor/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) defaults to [`error_handler_t::strict`](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md) instead of `error_handler_t::keep`. These writers then check every string value and object key for valid UTF-8 and throw [`type_error.316`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error316) for ill-formed UTF-8, like [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) does. Without it, they write the bytes unchanged. An `error_handler` passed explicitly always takes precedence.
+
+The macro does not affect:
+
+- [`to_msgpack`](https://json.nlohmann.me/api/basic_json/to_msgpack/index.md): the MessagePack specification allows a `str` value to contain bytes that are not valid UTF-8, so its `error_handler` always defaults to `keep`.
+- [`to_bon8`](https://json.nlohmann.me/api/basic_json/to_bon8/index.md): BON8 always checks, because the UTF-8 lead bytes mark where a string ends.
+- The binary readers ([`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), [`from_bson`](https://json.nlohmann.me/api/basic_json/from_bson/index.md)): none of these formats requires a decoder to reject ill-formed UTF-8, so they always return the bytes unchanged.
+
+## Default definition
+
+The default value is `0` (disabled, the behavior of version 3.12.0 and earlier is preserved).
+
+```
+#define JSON_STRICT_BINARY_UTF8 0
+```
+
+## Notes
+
+Background
+
+CBOR, UBJSON, BJData, and BSON all require strings to be UTF-8. Up to version 3.12.0, the writers did not check this, so they could produce output that other decoders reject. Checking by default would break code that stores other encodings (for instance ISO 8859-1) in a string and only ever writes it to a binary format. You can pass `error_handler_t::strict` to each call, or use this macro to check by default ahead of version 4.0.0, where `strict` is planned to become the default (see [#5529](https://github.com/nlohmann/json/issues/5529) and [#5651](https://github.com/nlohmann/json/issues/5651)).
+
+Opt-in only
+
+This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
+
+ABI compatibility
+
+The value of this macro is encoded in the [namespace](https://json.nlohmann.me/features/namespace/index.md) (tag `_sbu8`), resulting in distinct symbol names. Translation units compiled with and without it can therefore be linked into the same program without One Definition Rule (ODR) violations, but they cannot exchange instances of library types.
+
+## Examples
+
+Example: default behavior (macro not defined)
+
+Without the macro, the bytes are written unchanged:
+
+```
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    auto v = json::to_cbor(json("\xFF"));
+    // v is {0x61, 0xFF}
+}
+```
+
+Example: opt-in check (macro defined to 1)
+
+With the macro, ill-formed UTF-8 is rejected:
+
+```
+#define JSON_STRICT_BINARY_UTF8 1
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    auto v = json::to_cbor(json("\xFF"));
+    // throws type_error.316: invalid UTF-8 byte at index 0: 0xFF
+}
+```
+
+## See also
+
+- [**to_cbor**](https://json.nlohmann.me/api/basic_json/to_cbor/index.md) - create a CBOR serialization of a JSON value
+- [**to_ubjson**](https://json.nlohmann.me/api/basic_json/to_ubjson/index.md) - create a UBJSON serialization of a JSON value
+- [**to_bjdata**](https://json.nlohmann.me/api/basic_json/to_bjdata/index.md) - create a BJData serialization of a JSON value
+- [**to_bson**](https://json.nlohmann.me/api/basic_json/to_bson/index.md) - create a BSON serialization of a JSON value
+- [**error_handler_t**](https://json.nlohmann.me/api/basic_json/error_handler_t/index.md) - how [`dump`](https://json.nlohmann.me/api/basic_json/dump/index.md) treats ill-formed UTF-8
+
+## Version history
+
+- Added in version 3.13.0 unreleased.
+- Planned to become the default (with the macro removed) in version 4.0.0.

api/macros/json_use_implicit_conversions.md

@@ -5,7 +5,9 @@
 ```
 
 When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. The
-value directly affects [`operator ValueType`](../basic_json/operator_ValueType.md).
+value directly affects [`operator ValueType`](../basic_json/operator_ValueType.md) and the
+[converting constructor](../basic_json/basic_json.md) from a `basic_json` specialization with a different string
+type (overload 4).
 
 ## Default definition
 
@@ -42,7 +44,7 @@ By default, implicit conversions are enabled.
 
 ## Examples
 
-??? example
+??? example "Example: implicit conversion"
 
     This is an example for an implicit conversion:
 
@@ -59,6 +61,25 @@ By default, implicit conversions are enabled.
     auto s = j.get<std::string>();
     ```
 
+??? example "Example: conversion between `basic_json` specializations"
+
+    A `basic_json` specialization with a different string type is also no longer converted implicitly when
+    `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`:
+
+    ```cpp
+    using wjson = nlohmann::basic_json<std::map, std::vector, std::wstring>;
+
+    void load(const nlohmann::json& j);
+
+    wjson wj = /* ... */;
+    load(wj);                            // error: no implicit conversion
+    load(nlohmann::json(wj));            // OK: explicit conversion
+    load(wj.get<nlohmann::json>());      // OK: explicit conversion
+    ```
+
+    Specializations that share the same string type, such as `json` and `ordered_json`, remain implicitly
+    convertible.
+
 ## See also
 
 - [**operator ValueType**](../basic_json/operator_ValueType.md) - get a value (implicit)
@@ -68,3 +89,4 @@ By default, implicit conversions are enabled.
 ## Version history
 
 - Added in version 3.9.0.
+- Also affects the conversion between `basic_json` specializations with different string types since version 3.13.0.

api/macros/json_use_implicit_conversions/index.md

@@ -4,7 +4,7 @@
 #define JSON_USE_IMPLICIT_CONVERSIONS /* value */
 ```
 
-When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. The value directly affects [`operator ValueType`](https://json.nlohmann.me/api/basic_json/operator_ValueType/index.md).
+When defined to `0`, implicit conversions are switched off. By default, implicit conversions are switched on. The value directly affects [`operator ValueType`](https://json.nlohmann.me/api/basic_json/operator_ValueType/index.md) and the [converting constructor](https://json.nlohmann.me/api/basic_json/basic_json/index.md) from a `basic_json` specialization with a different string type (overload 4).
 
 ## Default definition
 
@@ -34,7 +34,7 @@ Implicit conversions can also be controlled with the CMake option [`JSON_Implici
 
 ## Examples
 
-Example
+Example: implicit conversion
 
 This is an example for an implicit conversion:
 
@@ -50,6 +50,23 @@ json j = "Hello, world!";
 auto s = j.get<std::string>();
 ```
 
+Example: conversion between `basic_json` specializations
+
+A `basic_json` specialization with a different string type is also no longer converted implicitly when `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`:
+
+```
+using wjson = nlohmann::basic_json<std::map, std::vector, std::wstring>;
+
+void load(const nlohmann::json& j);
+
+wjson wj = /* ... */;
+load(wj);                            // error: no implicit conversion
+load(nlohmann::json(wj));            // OK: explicit conversion
+load(wj.get<nlohmann::json>());      // OK: explicit conversion
+```
+
+Specializations that share the same string type, such as `json` and `ordered_json`, remain implicitly convertible.
+
 ## See also
 
 - [**operator ValueType**](https://json.nlohmann.me/api/basic_json/operator_ValueType/index.md) - get a value (implicit)
@@ -59,3 +76,4 @@ auto s = j.get<std::string>();
 ## Version history
 
 - Added in version 3.9.0.
+- Also affects the conversion between `basic_json` specializations with different string types since version 3.13.0 unreleased.

api/macros/json_use_legacy_discarded_value_comparison.md

@@ -81,3 +81,6 @@ When the macro is not defined, the library will define it to its default value.
 ## Version history
 
 - Added in version 3.11.0.
+- Fixed in version 3.13.0 so `<=` and `>=` also emulate the legacy behavior in C++20 when the JSON value is the
+  right-hand operand of a scalar comparison; before, only the 3-way-comparison-rewritten candidate was found, which
+  yielded `#!cpp false` instead of `#!cpp true`.

api/macros/json_use_legacy_discarded_value_comparison/index.md

@@ -74,3 +74,4 @@ The code below switches on the legacy discarded value comparison behavior in the
 ## Version history
 
 - Added in version 3.11.0.
+- Fixed in version 3.13.0 unreleased so `<=` and `>=` also emulate the legacy behavior in C++20 when the JSON value is the right-hand operand of a scalar comparison; before, only the 3-way-comparison-rewritten candidate was found, which yielded `false` instead of `true`.