deploy: 4d46bce4e1

api/macros/index.md

@@ -31,6 +31,7 @@ Some aspects of the library can be configured by defining preprocessor macros **
 - [**JSON_HAS_RANGES**](https://json.nlohmann.me/api/macros/json_has_ranges/index.md) - control `std::ranges` support
 - [**JSON_HAS_STD_FORMAT**](https://json.nlohmann.me/api/macros/json_has_std_format/index.md) - control `std::format`/`std::formatter` support
 - [**JSON_HAS_THREE_WAY_COMPARISON**](https://json.nlohmann.me/api/macros/json_has_three_way_comparison/index.md) - control 3-way comparison support
+- [**JSON_NO_AUTOMATIC_UDLS**](https://json.nlohmann.me/api/macros/json_no_automatic_udls/index.md) - do not include the user-defined string literals (UDLs) automatically
 - [**JSON_NO_IO**](https://json.nlohmann.me/api/macros/json_no_io/index.md) - switch off functions relying on certain C++ I/O headers
 - [**JSON_NO_THREAD_LOCAL**](https://json.nlohmann.me/api/macros/json_no_thread_local/index.md) - switch off the use of `thread_local` storage
 - [**JSON_SKIP_UNSUPPORTED_COMPILER_CHECK**](https://json.nlohmann.me/api/macros/json_skip_unsupported_compiler_check/index.md) - do not warn about unsupported compilers
@@ -56,6 +57,7 @@ Some aspects of the library can be configured by defining preprocessor macros **
 
 - [**JSON_BRACE_INIT_COPY_SEMANTICS**](https://json.nlohmann.me/api/macros/json_brace_init_copy_semantics/index.md) - opt in to copy/move semantics for single-element brace initialization
 - [**JSON_DISABLE_ENUM_SERIALIZATION**](https://json.nlohmann.me/api/macros/json_disable_enum_serialization/index.md) - switch off default serialization/deserialization functions for enums
+- [**JSON_DISABLE_TUPLE_REFERENCE_CONVERSION**](https://json.nlohmann.me/api/macros/json_disable_tuple_reference_conversion/index.md) - switch off conversion from a one-element tuple of a JSON reference
 - [**JSON_USE_IMPLICIT_CONVERSIONS**](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md) - control implicit conversions
 
 ## Comparison behavior

api/macros/json_disable_tuple_reference_conversion.md

@@ -0,0 +1,114 @@
+# JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
+
+```cpp
+#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION /* value */
+```
+
+When defined to `1`, a `basic_json` value can no longer be constructed from a one-element `std::tuple` whose element is
+a reference to that `basic_json` type, such as `std::tuple<json&>`, `std::tuple<const json&>`, or `std::tuple<json&&>`.
+These are the tuples created by `std::forward_as_tuple(j)`.
+
+## Default definition
+
+The default value is `0` (disabled — existing behavior is preserved).
+
+```cpp
+#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 0
+```
+
+## Notes
+
+!!! note "Background"
+
+    By default, `basic_json` can be constructed from any `std::tuple` whose elements can be converted to JSON; the result
+    is an array. This includes `std::tuple<json&>`, which becomes a one-element array.
+
+    `std::tuple` only converts another tuple element by element if its element type cannot be constructed from the whole
+    source tuple. Because `json` *can* be constructed from `std::tuple<json&>`, `std::tuple` instead converts the whole
+    tuple into a single `json` value. This has two surprising effects:
+
+    ```cpp
+    json j = true;
+
+    // rejected by some standard libraries (e.g., libc++); with others, the
+    // reference binds to a temporary that is destroyed right away
+    std::tuple<const json&> t1(std::forward_as_tuple(j));
+
+    // compiles, but std::get<0>(t2) is [true], not true
+    std::tuple<json> t2(std::forward_as_tuple(j));
+    ```
+
+    Enabling this macro removes the conversion, so both tuples are converted element by element: `std::get<0>(t1)`
+    refers to `j`, and `std::get<0>(t2)` is a copy of `j` (see [#2226](https://github.com/nlohmann/json/issues/2226)).
+
+!!! warning "Opt-in only"
+
+    This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
+
+!!! note "Affected conversions"
+
+    Only one-element tuples holding a reference to the **same** `basic_json` type are affected. Constructing a JSON value
+    from them no longer compiles:
+
+    ```cpp
+    json j = true;
+    json a = std::forward_as_tuple(j);  // error with the macro enabled
+    json b = json::array({j});          // use this instead: [true]
+    ```
+
+    Tuples holding a JSON value (`std::make_tuple(j)`), tuples with more than one element, and tuples holding references
+    to other types (including other `basic_json` specializations) are converted to arrays as before.
+
+!!! hint "CMake option"
+
+    This behavior can also be controlled with the CMake option
+    [`JSON_DisableTupleReferenceConversion`](../../integration/cmake.md#json_disabletuplereferenceconversion)
+    (`OFF` by default) which defines `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION` accordingly.
+
+## Examples
+
+??? example "Default behavior (macro not defined)"
+
+    ```cpp
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        json j = true;
+
+        std::tuple<json> t(std::forward_as_tuple(j));
+        // std::get<0>(t) is [true] -- the whole tuple was converted
+    }
+    ```
+
+??? example "Conversion disabled (macro defined to 1)"
+
+    ```cpp
+    #define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        json j = true;
+
+        std::tuple<json> t(std::forward_as_tuple(j));
+        // std::get<0>(t) is true -- a copy of j
+
+        std::tuple<const json&> r(std::forward_as_tuple(j));
+        // std::get<0>(r) refers to j
+    }
+    ```
+
+## See also
+
+- [**basic_json(CompatibleType&&)**](../basic_json/basic_json.md) - the affected constructor
+- [:simple-cmake: JSON_DisableTupleReferenceConversion](../../integration/cmake.md#json_disabletuplereferenceconversion) -
+  CMake option to control the macro
+
+## Version history
+
+- Added in version 3.13.0.

api/macros/json_disable_tuple_reference_conversion/index.md

@@ -0,0 +1,103 @@
+# JSON_DISABLE_TUPLE_REFERENCE_CONVERSION
+
+```
+#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION /* value */
+```
+
+When defined to `1`, a `basic_json` value can no longer be constructed from a one-element `std::tuple` whose element is a reference to that `basic_json` type, such as `std::tuple<json&>`, `std::tuple<const json&>`, or `std::tuple<json&&>`. These are the tuples created by `std::forward_as_tuple(j)`.
+
+## Default definition
+
+The default value is `0` (disabled — existing behavior is preserved).
+
+```
+#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 0
+```
+
+## Notes
+
+Background
+
+By default, `basic_json` can be constructed from any `std::tuple` whose elements can be converted to JSON; the result is an array. This includes `std::tuple<json&>`, which becomes a one-element array.
+
+`std::tuple` only converts another tuple element by element if its element type cannot be constructed from the whole source tuple. Because `json` *can* be constructed from `std::tuple<json&>`, `std::tuple` instead converts the whole tuple into a single `json` value. This has two surprising effects:
+
+```
+json j = true;
+
+// rejected by some standard libraries (e.g., libc++); with others, the
+// reference binds to a temporary that is destroyed right away
+std::tuple<const json&> t1(std::forward_as_tuple(j));
+
+// compiles, but std::get<0>(t2) is [true], not true
+std::tuple<json> t2(std::forward_as_tuple(j));
+```
+
+Enabling this macro removes the conversion, so both tuples are converted element by element: `std::get<0>(t1)` refers to `j`, and `std::get<0>(t2)` is a copy of `j` (see [#2226](https://github.com/nlohmann/json/issues/2226)).
+
+Opt-in only
+
+This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
+
+Affected conversions
+
+Only one-element tuples holding a reference to the **same** `basic_json` type are affected. Constructing a JSON value from them no longer compiles:
+
+```
+json j = true;
+json a = std::forward_as_tuple(j);  // error with the macro enabled
+json b = json::array({j});          // use this instead: [true]
+```
+
+Tuples holding a JSON value (`std::make_tuple(j)`), tuples with more than one element, and tuples holding references to other types (including other `basic_json` specializations) are converted to arrays as before.
+
+CMake option
+
+This behavior can also be controlled with the CMake option [`JSON_DisableTupleReferenceConversion`](https://json.nlohmann.me/integration/cmake/#json_disabletuplereferenceconversion) (`OFF` by default) which defines `JSON_DISABLE_TUPLE_REFERENCE_CONVERSION` accordingly.
+
+## Examples
+
+Default behavior (macro not defined)
+
+```
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    json j = true;
+
+    std::tuple<json> t(std::forward_as_tuple(j));
+    // std::get<0>(t) is [true] -- the whole tuple was converted
+}
+```
+
+Conversion disabled (macro defined to 1)
+
+```
+#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    json j = true;
+
+    std::tuple<json> t(std::forward_as_tuple(j));
+    // std::get<0>(t) is true -- a copy of j
+
+    std::tuple<const json&> r(std::forward_as_tuple(j));
+    // std::get<0>(r) refers to j
+}
+```
+
+## See also
+
+- [**basic_json(CompatibleType&&)**](https://json.nlohmann.me/api/basic_json/basic_json/index.md) - the affected constructor
+- [JSON_DisableTupleReferenceConversion](https://json.nlohmann.me/integration/cmake/#json_disabletuplereferenceconversion) - CMake option to control the macro
+
+## Version history
+
+- Added in version 3.13.0.

api/macros/json_no_automatic_udls.md

@@ -0,0 +1,68 @@
+# JSON_NO_AUTOMATIC_UDLS
+
+```cpp
+#define JSON_NO_AUTOMATIC_UDLS
+```
+
+When defined, `<nlohmann/json.hpp>` does not include `<nlohmann/json_literals.hpp>`, so the user-defined string
+literals [`operator""_json`](../operator_literal_json.md) and
+[`operator""_json_pointer`](../operator_literal_json_pointer.md) are not declared. Include
+`<nlohmann/json_literals.hpp>` in the files that use them.
+
+The literals are ordinary inline functions whose bodies call the parser, so every translation unit that includes them
+instantiates the parser — even if it never parses anything itself. Defining `JSON_NO_AUTOMATIC_UDLS` for a whole project
+avoids this cost in translation units that do not parse (e.g., ones that only define types and conversions or pass
+`json` values around) and reduces their compile time.
+
+## Default definition
+
+By default, `#!cpp JSON_NO_AUTOMATIC_UDLS` is not defined, and `<nlohmann/json.hpp>` includes
+`<nlohmann/json_literals.hpp>`.
+
+```cpp
+#undef JSON_NO_AUTOMATIC_UDLS
+```
+
+## Notes
+
+!!! info "Header `<nlohmann/json_literals.hpp>`"
+
+    The header includes `<nlohmann/json.hpp>` itself and places the literals according to
+    [`JSON_USE_GLOBAL_UDLS`](json_use_global_udls.md). It is part of the multi-header sources (`include/nlohmann`)
+    and of the single-header sources (`single_include/nlohmann`), next to `json.hpp`.
+
+!!! info "C++ modules"
+
+    The `nlohmann.json` [module](../../features/modules.md) always exports the literals, regardless of this macro.
+
+## Examples
+
+??? example
+
+    The code below includes the library without the literals and adds them in a single translation unit.
+
+    ```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
+    #include <nlohmann/json_literals.hpp>
+
+    int main()
+    {
+        auto j = R"({"foo": 42})"_json;
+        return j.at("/foo"_json_pointer) == 42 ? 0 : 1;
+    }
+    ```
+
+    Without the include of `<nlohmann/json_literals.hpp>`, the code would fail to compile.
+
+## See also
+
+- [`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
+
+## Version history
+
+- Added in version 3.13.0.

api/macros/json_no_automatic_udls/index.md

@@ -0,0 +1,59 @@
+# JSON_NO_AUTOMATIC_UDLS
+
+```
+#define JSON_NO_AUTOMATIC_UDLS
+```
+
+When defined, `<nlohmann/json.hpp>` does not include `<nlohmann/json_literals.hpp>`, so the user-defined string literals [`operator""_json`](https://json.nlohmann.me/api/operator_literal_json/index.md) and [`operator""_json_pointer`](https://json.nlohmann.me/api/operator_literal_json_pointer/index.md) are not declared. Include `<nlohmann/json_literals.hpp>` in the files that use them.
+
+The literals are ordinary inline functions whose bodies call the parser, so every translation unit that includes them instantiates the parser — even if it never parses anything itself. Defining `JSON_NO_AUTOMATIC_UDLS` for a whole project avoids this cost in translation units that do not parse (e.g., ones that only define types and conversions or pass `json` values around) and reduces their compile time.
+
+## Default definition
+
+By default, `JSON_NO_AUTOMATIC_UDLS` is not defined, and `<nlohmann/json.hpp>` includes `<nlohmann/json_literals.hpp>`.
+
+```
+#undef JSON_NO_AUTOMATIC_UDLS
+```
+
+## Notes
+
+Header `<nlohmann/json_literals.hpp>`
+
+The header includes `<nlohmann/json.hpp>` itself and places the literals according to [`JSON_USE_GLOBAL_UDLS`](https://json.nlohmann.me/api/macros/json_use_global_udls/index.md). It is part of the multi-header sources (`include/nlohmann`) and of the single-header sources (`single_include/nlohmann`), next to `json.hpp`.
+
+C++ modules
+
+The `nlohmann.json` [module](https://json.nlohmann.me/features/modules/index.md) always exports the literals, regardless of this macro.
+
+## Examples
+
+Example
+
+The code below includes the library without the literals and adds them in a single translation unit.
+
+```
+// compiled with -DJSON_NO_AUTOMATIC_UDLS for the whole project
+#include <nlohmann/json.hpp>
+
+// this file uses the literals, so it includes them explicitly
+#include <nlohmann/json_literals.hpp>
+
+int main()
+{
+    auto j = R"({"foo": 42})"_json;
+    return j.at("/foo"_json_pointer) == 42 ? 0 : 1;
+}
+```
+
+Without the include of `<nlohmann/json_literals.hpp>`, the code would fail to compile.
+
+## See also
+
+- [`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
+
+## Version history
+
+- Added in version 3.13.0.

api/macros/json_strict_nul_handling.md

@@ -16,7 +16,8 @@ byte is still not rejected:
   [`from_msgpack`](../basic_json/from_msgpack.md), [`from_ubjson`](../basic_json/from_ubjson.md)) are never affected: there, `0x00` is ordinary data.
 - A bare `const char*` pointer has no length of its own, so its length is still determined with `strlen()`. The first
   NUL byte therefore still marks the end of the input, and nothing after it is read.
-- One trailing `'\0'` at the end of a `char` array (e.g., a string literal) is trimmed; see the warning below.
+- One trailing `'\0'` at the end of a `char`, `wchar_t`, `char16_t`, `char32_t`, or (C++20) `char8_t` array (e.g., a
+  string literal) is trimmed; see the warning below.
 
 ## Default definition
 
@@ -57,13 +58,15 @@ The default value is `0` (disabled — existing behavior is preserved).
     This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no
     effect.
 
-    Enabling it also changes how a `char` array (including a string literal, e.g. `json::parse("123")`) is read: such
-    an array normally carries a trailing `'\0'` contributed by the compiler, not by the source text. With this macro
-    enabled, that one trailing byte is trimmed if present so that parsing a string literal keeps working; every other
-    byte in the array - including any `'\0'` that is not the very last element - is read as real data and rejected
-    like any other unexpected byte. Arrays of any other element type (`unsigned char`, `std::uint8_t`, ...), as used
-    for CBOR or MessagePack, are never affected by this trimming; their full extent - including a genuine trailing
-    `0x00` - is always preserved, in both states of this macro.
+    Enabling it also changes how an array of a text-literal element type (`char`, `wchar_t`, `char16_t`, `char32_t`,
+    or, since C++20, `char8_t` - including a string literal, e.g. `json::parse("123")` or `json::parse(L"123")`) is
+    read: such an array normally carries a trailing `'\0'` contributed by the compiler, not by the source text. With
+    this macro enabled, that one trailing element is trimmed if present so that parsing a string literal keeps
+    working, for any of these character types; every other element in the array - including any `'\0'` that is not
+    the very last element - is read as real data and rejected like any other unexpected byte. Arrays of any other
+    element type (`unsigned char`, `std::uint8_t`, ...), as used for CBOR or MessagePack, are never affected by this
+    trimming; their full extent - including a genuine trailing `0x00` - is always preserved, in both states of this
+    macro.
 
 !!! note "ABI compatibility"
 

api/macros/json_strict_nul_handling/index.md

@@ -10,7 +10,7 @@ The macro only affects the JSON text parser ([`parse`](https://json.nlohmann.me/
 
 - The binary formats ([`from_bjdata`](https://json.nlohmann.me/api/basic_json/from_bjdata/index.md), [`from_bon8`](https://json.nlohmann.me/api/basic_json/from_bon8/index.md), [`from_bson`](https://json.nlohmann.me/api/basic_json/from_bson/index.md), [`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)) are never affected: there, `0x00` is ordinary data.
 - A bare `const char*` pointer has no length of its own, so its length is still determined with `strlen()`. The first NUL byte therefore still marks the end of the input, and nothing after it is read.
-- One trailing `'\0'` at the end of a `char` array (e.g., a string literal) is trimmed; see the warning below.
+- One trailing `'\0'` at the end of a `char`, `wchar_t`, `char16_t`, `char32_t`, or (C++20) `char8_t` array (e.g., a string literal) is trimmed; see the warning below.
 
 ## Default definition
 
@@ -39,7 +39,7 @@ Opt-in only
 
 This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no effect.
 
-Enabling it also changes how a `char` array (including a string literal, e.g. `json::parse("123")`) is read: such an array normally carries a trailing `'\0'` contributed by the compiler, not by the source text. With this macro enabled, that one trailing byte is trimmed if present so that parsing a string literal keeps working; every other byte in the array - including any `'\0'` that is not the very last element - is read as real data and rejected like any other unexpected byte. Arrays of any other element type (`unsigned char`, `std::uint8_t`, ...), as used for CBOR or MessagePack, are never affected by this trimming; their full extent - including a genuine trailing `0x00` - is always preserved, in both states of this macro.
+Enabling it also changes how an array of a text-literal element type (`char`, `wchar_t`, `char16_t`, `char32_t`, or, since C++20, `char8_t` - including a string literal, e.g. `json::parse("123")` or `json::parse(L"123")`) is read: such an array normally carries a trailing `'\0'` contributed by the compiler, not by the source text. With this macro enabled, that one trailing element is trimmed if present so that parsing a string literal keeps working, for any of these character types; every other element in the array - including any `'\0'` that is not the very last element - is read as real data and rejected like any other unexpected byte. Arrays of any other element type (`unsigned char`, `std::uint8_t`, ...), as used for CBOR or MessagePack, are never affected by this trimming; their full extent - including a genuine trailing `0x00` - is always preserved, in both states of this macro.
 
 ABI compatibility
 

api/macros/json_use_global_udls.md

@@ -15,7 +15,7 @@ The default value is `1`.
 #define JSON_USE_GLOBAL_UDLS 1
 ```
 
-When the macro is not defined, the library will define it to its default value.
+When the macro is not defined, the library behaves as if it were defined to its default value.
 
 ## Notes
 
@@ -32,6 +32,11 @@ When the macro is not defined, the library will define it to its default value.
     [`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`ON` by default) which defines
     `JSON_USE_GLOBAL_UDLS` accordingly.
 
+!!! info "Leaving out the literals"
+
+    If [`JSON_NO_AUTOMATIC_UDLS`](json_no_automatic_udls.md) is defined, the literals are only declared where
+    `<nlohmann/json_literals.hpp>` is included; this macro then applies to that header.
+
 ## Examples
 
 ??? example "Example 1: Default behavior"
@@ -92,6 +97,7 @@ When the macro is not defined, the library will define it to its default value.
 
 - [`operator""_json`](../operator_literal_json.md)
 - [`operator""_json_pointer`](../operator_literal_json_pointer.md)
+- [`JSON_NO_AUTOMATIC_UDLS`](json_no_automatic_udls.md) - do not include the user-defined string literals automatically
 - [:simple-cmake: JSON_GlobalUDLs](../../integration/cmake.md#json_globaludls) - CMake option to control the macro
 
 ## Version history

api/macros/json_use_global_udls/index.md

@@ -14,7 +14,7 @@ The default value is `1`.
 #define JSON_USE_GLOBAL_UDLS 1
 ```
 
-When the macro is not defined, the library will define it to its default value.
+When the macro is not defined, the library behaves as if it were defined to its default value.
 
 ## Notes
 
@@ -28,6 +28,10 @@ CMake option
 
 The placement of user-defined string literals can also be controlled with the CMake option [`JSON_GlobalUDLs`](https://json.nlohmann.me/integration/cmake/#json_globaludls) (`ON` by default) which defines `JSON_USE_GLOBAL_UDLS` accordingly.
 
+Leaving out the literals
+
+If [`JSON_NO_AUTOMATIC_UDLS`](https://json.nlohmann.me/api/macros/json_no_automatic_udls/index.md) is defined, the literals are only declared where `<nlohmann/json_literals.hpp>` is included; this macro then applies to that header.
+
 ## Examples
 
 Example 1: Default behavior
@@ -87,6 +91,7 @@ Output:
 
 - [`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_NO_AUTOMATIC_UDLS`](https://json.nlohmann.me/api/macros/json_no_automatic_udls/index.md) - do not include the user-defined string literals automatically
 - [JSON_GlobalUDLs](https://json.nlohmann.me/integration/cmake/#json_globaludls) - CMake option to control the macro
 
 ## Version history