deploy: cdfb130fa6

api/basic_json/basic_json.md

@@ -67,7 +67,11 @@ basic_json(basic_json&& other) noexcept;
     - **objects**: [`object_t`](object_t.md) and all kinds of compatible associative containers such as `std::map`,
      `std::unordered_map`, `std::multimap`, and `std::unordered_multimap` with a `key_type` compatible to `string_t`
      and a `value_type` from which a `basic_json` value can be constructed.
-    - **strings**: `string_t`, string literals, and all compatible string containers can be used.
+    - **strings**: `string_t`, string literals, and all compatible string containers can be used. Since version 3.13.0,
+      this includes `#!cpp std::u8string` (C++20): its code units are stored as a JSON string and
+      [`get<std::u8string>()`](get.md) reads it back (in version 3.12.0, a `#!cpp std::u8string` was stored as an array
+      of numbers; `get<std::u8string>()` still accepts such an array). `#!cpp std::u8string_view` and `#!cpp char8_t`
+      arrays are not strings; they are stored as arrays of code units.
 
     !!! note "Rvalue containers are moved from"
 
@@ -93,10 +97,18 @@ basic_json(basic_json&& other) noexcept;
     The constructor tries to convert the internal `m_value` of the parameter. Each member value (object, array, string,
     etc.) is serialized via the corresponding `to_json()` overload. For objects and strings, the conversion requires
     that the *target* `basic_json` type's `object_t::key_type` (or `string_t`) be directly constructible from the
-    *source* type's corresponding member type via `is_constructible`. If this requirement is not met, the conversion
-    does not fail to compile; instead, it silently falls back to the array-conversion path, which represents objects
-    as arrays of `[key, value]` pairs and strings as arrays of character codes. This is a known limitation tracked in
-    [issue #3425](https://github.com/nlohmann/json/issues/3425).
+    *source* type's corresponding member type via `is_constructible`. If this requirement is not met, the result
+    depends on the *source* string type:
+
+    - If it is a range of characters (it has `begin()` and `end()`, as `std::string` does), the conversion falls back to
+      the array-conversion path, which represents objects as arrays of `[key, value]` pairs and strings as arrays of
+      character codes. This result has a different type than the source value, so the constructor's
+      [`JSON_ASSERT`](../macros/json_assert.md) fails; with its default definition, `assert`, the program aborts unless
+      `NDEBUG` is defined, in which case the array is returned.
+    - Otherwise, the conversion does not compile, even though `#!cpp std::is_constructible` reports `#!cpp true`; for
+      example, when converting a `basic_json` whose `string_t` is the `alt_string` of the unit tests to `json`.
+
+    This is a known limitation tracked in [issue #3425](https://github.com/nlohmann/json/issues/3425).
 
 5. Creates a JSON value of type array or object from the passed initializer list `init`. In case `type_deduction` is
    `#!cpp true` (default), the type of the JSON value to be created is deducted from the initializer list `init`

api/basic_json/basic_json/index.md

@@ -58,7 +58,7 @@ basic_json(basic_json&& other) noexcept;
 
    - **arrays**: [`array_t`](https://json.nlohmann.me/api/basic_json/array_t/index.md) and all kinds of compatible containers such as `std::vector`, `std::deque`, `std::list`, `std::forward_list`, `std::array`, `std::valarray`, `std::set`, `std::unordered_set`, `std::multiset`, and `std::unordered_multiset` with a `value_type` from which a `basic_json` value can be constructed.
    - **objects**: [`object_t`](https://json.nlohmann.me/api/basic_json/object_t/index.md) and all kinds of compatible associative containers such as `std::map`, `std::unordered_map`, `std::multimap`, and `std::unordered_multimap` with a `key_type` compatible to `string_t` and a `value_type` from which a `basic_json` value can be constructed.
-   - **strings**: `string_t`, string literals, and all compatible string containers can be used.
+   - **strings**: `string_t`, string literals, and all compatible string containers can be used. Since version 3.13.0 unreleased, this includes `std::u8string` (C++20): its code units are stored as a JSON string and [`get<std::u8string>()`](https://json.nlohmann.me/api/basic_json/get/index.md) reads it back (in version 3.12.0, a `std::u8string` was stored as an array of numbers; `get<std::u8string>()` still accepts such an array). `std::u8string_view` and `char8_t` arrays are not strings; they are stored as arrays of code units.
 
    Rvalue containers are moved from
 
@@ -72,7 +72,12 @@ basic_json(basic_json&& other) noexcept;
 
 1. This is a constructor for existing `basic_json` types. It does not hijack copy/move constructors, since the parameter has different template arguments than the current ones.
 
-   The constructor tries to convert the internal `m_value` of the parameter. Each member value (object, array, string, etc.) is serialized via the corresponding `to_json()` overload. For objects and strings, the conversion requires that the *target* `basic_json` type's `object_t::key_type` (or `string_t`) be directly constructible from the *source* type's corresponding member type via `is_constructible`. If this requirement is not met, the conversion does not fail to compile; instead, it silently falls back to the array-conversion path, which represents objects as arrays of `[key, value]` pairs and strings as arrays of character codes. This is a known limitation tracked in [issue #3425](https://github.com/nlohmann/json/issues/3425).
+   The constructor tries to convert the internal `m_value` of the parameter. Each member value (object, array, string, etc.) is serialized via the corresponding `to_json()` overload. For objects and strings, the conversion requires that the *target* `basic_json` type's `object_t::key_type` (or `string_t`) be directly constructible from the *source* type's corresponding member type via `is_constructible`. If this requirement is not met, the result depends on the *source* string type:
+
+   - If it is a range of characters (it has `begin()` and `end()`, as `std::string` does), the conversion falls back to the array-conversion path, which represents objects as arrays of `[key, value]` pairs and strings as arrays of character codes. This result has a different type than the source value, so the constructor's [`JSON_ASSERT`](https://json.nlohmann.me/api/macros/json_assert/index.md) fails; with its default definition, `assert`, the program aborts unless `NDEBUG` is defined, in which case the array is returned.
+   - Otherwise, the conversion does not compile, even though `std::is_constructible` reports `true`; for example, when converting a `basic_json` whose `string_t` is the `alt_string` of the unit tests to `json`.
+
+   This is a known limitation tracked in [issue #3425](https://github.com/nlohmann/json/issues/3425).
 
 1. Creates a JSON value of type array or object from the passed initializer list `init`. In case `type_deduction` is `true` (default), the type of the JSON value to be created is deducted from the initializer list `init` according to the following rules:
 

api/basic_json/get.md

@@ -130,6 +130,12 @@ overload (3).
     `#!cpp json(true).get<double>()` throw. This is the behavior of all 3.x versions;
     [`basic_json_view::get<T>()`](../basic_json_view/get.md) behaves the same.
 
+!!! note "`std::u8string` conversions"
+
+    Since version 3.13.0, `#!cpp get<std::u8string>()` (C++20) reads a JSON string; it also accepts an array of numbers,
+    the form in which version 3.12.0 stored a `#!cpp std::u8string`. Any other JSON type throws
+    [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) ("type must be string or array").
+
 !!! note "`std::optional` conversions"
 
     Prior to version 3.13.0, `#!cpp get<std::optional<T>>()` (and other conversions to `std::optional<T>`) failed to

api/basic_json/get/index.md

@@ -102,6 +102,10 @@ Booleans as numbers
 
 A JSON boolean converts to `0` or `1` for every arithmetic type **except** [`number_integer_t`](https://json.nlohmann.me/api/basic_json/number_integer_t/index.md), [`number_unsigned_t`](https://json.nlohmann.me/api/basic_json/number_unsigned_t/index.md) and [`number_float_t`](https://json.nlohmann.me/api/basic_json/number_float_t/index.md) (by default `std::int64_t`, `std::uint64_t`, and `double`), for which `get<T>()` throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) ("type must be number, but is boolean"). So `json(true).get<int>()` is `1`, while `json(true).get<std::int64_t>()` and `json(true).get<double>()` throw. This is the behavior of all 3.x versions; [`basic_json_view::get<T>()`](https://json.nlohmann.me/api/basic_json_view/get/index.md) behaves the same.
 
+`std::u8string` conversions
+
+Since version 3.13.0 unreleased, `get<std::u8string>()` (C++20) reads a JSON string; it also accepts an array of numbers, the form in which version 3.12.0 stored a `std::u8string`. Any other JSON type throws [`type_error.302`](https://json.nlohmann.me/home/exceptions/#jsonexceptiontype_error302) ("type must be string or array").
+
 `std::optional` conversions
 
 Prior to version 3.13.0 unreleased, `get<std::optional<T>>()` (and other conversions to `std::optional<T>`) failed to compile in every configuration, due to an internal implementation bug that made the `from_json` overload for `std::optional` unreachable regardless of the [`JSON_USE_IMPLICIT_CONVERSIONS`](https://json.nlohmann.me/api/macros/json_use_implicit_conversions/index.md) setting. This has been fixed.

api/basic_json/object_t.md

@@ -102,9 +102,12 @@ objects.
 
 When converting an object from one `basic_json` specialization to another via the
 [converting constructor](basic_json.md) (overload 4), the target `object_t`'s `key_type` must be
-directly constructible from the source `basic_json`'s `string_t` type (or more generally, from the
-source object's key type). If this requirement is not met, the conversion does not fail; instead,
-the object is silently converted as an array of key-value pairs, which is incorrect. See
+directly constructible from the source object's key type (with the default `std::map`, the source `basic_json`'s
+`string_t`). If this requirement is not met and the source string type is a range of characters, the
+object is converted as an array of key-value pairs, which is incorrect: the converting constructor's
+[`JSON_ASSERT`](../macros/json_assert.md) fails; with its default definition, `assert`, the program aborts unless
+`NDEBUG` is defined, in which case the array is returned. If the source string type is not a range of characters, the
+conversion does not compile at all. See [`basic_json`](basic_json.md) and
 [issue #3425](https://github.com/nlohmann/json/issues/3425) for details and an example.
 
 ## Examples

api/basic_json/object_t/index.md

@@ -76,7 +76,7 @@ The order name/value pairs are added to the object are *not* preserved by the li
 
 ### Cross-`basic_json` conversion requirements
 
-When converting an object from one `basic_json` specialization to another via the [converting constructor](https://json.nlohmann.me/api/basic_json/basic_json/index.md) (overload 4), the target `object_t`'s `key_type` must be directly constructible from the source `basic_json`'s `string_t` type (or more generally, from the source object's key type). If this requirement is not met, the conversion does not fail; instead, the object is silently converted as an array of key-value pairs, which is incorrect. See [issue #3425](https://github.com/nlohmann/json/issues/3425) for details and an example.
+When converting an object from one `basic_json` specialization to another via the [converting constructor](https://json.nlohmann.me/api/basic_json/basic_json/index.md) (overload 4), the target `object_t`'s `key_type` must be directly constructible from the source object's key type (with the default `std::map`, the source `basic_json`'s `string_t`). If this requirement is not met and the source string type is a range of characters, the object is converted as an array of key-value pairs, which is incorrect: the converting constructor's [`JSON_ASSERT`](https://json.nlohmann.me/api/macros/json_assert/index.md) fails; with its default definition, `assert`, the program aborts unless `NDEBUG` is defined, in which case the array is returned. If the source string type is not a range of characters, the conversion does not compile at all. See [`basic_json`](https://json.nlohmann.me/api/basic_json/basic_json/index.md) and [issue #3425](https://github.com/nlohmann/json/issues/3425) for details and an example.
 
 ## Examples
 

api/basic_json/operator%2B%3D.md

@@ -27,6 +27,16 @@ reference operator+=(initializer_list_t init);
     `init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`.
     Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`.
 
+    !!! note "Single braced JSON value"
+
+        For a call such as `#!cpp arr += {obj}`, where the initializer list contains a single JSON value `obj`,
+        compilers may disagree unless
+        [`JSON_BRACE_INIT_COPY_SEMANTICS`](../macros/json_brace_init_copy_semantics.md) is defined to `1`: GCC, for
+        example, selects this overload and appends a single-element array `[obj]`, whereas Clang selects the
+        `basic_json` overload and appends a copy of `obj`. With the macro, GCC and Clang both append a copy of `obj`.
+        To get a portable result without the macro, write `#!cpp arr += obj` to append a copy, or
+        `#!cpp arr += json::array({obj})` to append a single-element array.
+
 ## Iterator invalidation
 
 For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators (including

api/basic_json/operator+=/index.md

@@ -24,6 +24,10 @@ reference operator+=(initializer_list_t init);
 
    `init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`. Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`.
 
+   Single braced JSON value
+
+   For a call such as `arr += {obj}`, where the initializer list contains a single JSON value `obj`, compilers may disagree unless [`JSON_BRACE_INIT_COPY_SEMANTICS`](https://json.nlohmann.me/api/macros/json_brace_init_copy_semantics/index.md) is defined to `1`: GCC, for example, selects this overload and appends a single-element array `[obj]`, whereas Clang selects the `basic_json` overload and appends a copy of `obj`. With the macro, GCC and Clang both append a copy of `obj`. To get a portable result without the macro, write `arr += obj` to append a copy, or `arr += json::array({obj})` to append a single-element array.
+
 ## Iterator invalidation
 
 For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators (including the [`end()`](https://json.nlohmann.me/api/basic_json/end/index.md) iterator) and all references to the elements are invalidated. Otherwise, only the [`end()`](https://json.nlohmann.me/api/basic_json/end/index.md) iterator is invalidated.

api/basic_json/operator_ge.md

@@ -60,6 +60,14 @@ Linear.
       2. Comparing a `NaN` with another `NaN`.
       3. Comparing a `NaN` and any other number.
 
+    For arrays and objects, the elements are compared in order. If the comparison reaches a `NaN` and a number (or
+    another `NaN`) before any other difference, the result depends on the language standard. Before C++20, the pair
+    counts as equivalent and the following elements (or the sizes) decide: for instance, `[NaN] < [1, NaN]` and
+    `[1] <= [NaN]` are `#!cpp true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all
+    yield `#!cpp false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the
+    same for all language standards. The same program can therefore order such values differently when it is compiled
+    with a different language standard.
+
 !!! note "Operator overload resolution"
 
     Since C++20 overload resolution will consider the _rewritten candidate_ generated from

api/basic_json/operator_ge/index.md

@@ -51,6 +51,8 @@ Comparing `NaN`
 1. Comparing a `NaN` with another `NaN`.
 1. Comparing a `NaN` and any other number.
 
+For arrays and objects, the elements are compared in order. If the comparison reaches a `NaN` and a number (or another `NaN`) before any other difference, the result depends on the language standard. Before C++20, the pair counts as equivalent and the following elements (or the sizes) decide: for instance, `[NaN] < [1, NaN]` and `[1] <= [NaN]` are `true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all yield `false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the same for all language standards. The same program can therefore order such values differently when it is compiled with a different language standard.
+
 Operator overload resolution
 
 Since C++20 overload resolution will consider the *rewritten candidate* generated from [`operator<=>`](https://json.nlohmann.me/api/basic_json/operator_spaceship/index.md).

api/basic_json/operator_gt.md

@@ -60,6 +60,14 @@ Linear.
       2. Comparing a `NaN` with another `NaN`.
       3. Comparing a `NaN` and any other number.
 
+    For arrays and objects, the elements are compared in order. If the comparison reaches a `NaN` and a number (or
+    another `NaN`) before any other difference, the result depends on the language standard. Before C++20, the pair
+    counts as equivalent and the following elements (or the sizes) decide: for instance, `[NaN] < [1, NaN]` and
+    `[1] <= [NaN]` are `#!cpp true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all
+    yield `#!cpp false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the
+    same for all language standards. The same program can therefore order such values differently when it is compiled
+    with a different language standard.
+
 !!! note "Operator overload resolution"
 
     Since C++20 overload resolution will consider the _rewritten candidate_ generated from

api/basic_json/operator_gt/index.md

@@ -51,6 +51,8 @@ Comparing `NaN`
 1. Comparing a `NaN` with another `NaN`.
 1. Comparing a `NaN` and any other number.
 
+For arrays and objects, the elements are compared in order. If the comparison reaches a `NaN` and a number (or another `NaN`) before any other difference, the result depends on the language standard. Before C++20, the pair counts as equivalent and the following elements (or the sizes) decide: for instance, `[NaN] < [1, NaN]` and `[1] <= [NaN]` are `true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all yield `false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the same for all language standards. The same program can therefore order such values differently when it is compiled with a different language standard.
+
 Operator overload resolution
 
 Since C++20 overload resolution will consider the *rewritten candidate* generated from [`operator<=>`](https://json.nlohmann.me/api/basic_json/operator_spaceship/index.md).

api/basic_json/operator_le.md

@@ -61,6 +61,14 @@ Linear.
       2. Comparing a `NaN` with another `NaN`.
       3. Comparing a `NaN` and any other number.
 
+    For arrays and objects, the elements are compared in order. If the comparison reaches a `NaN` and a number (or
+    another `NaN`) before any other difference, the result depends on the language standard. Before C++20, the pair
+    counts as equivalent and the following elements (or the sizes) decide: for instance, `[NaN] < [1, NaN]` and
+    `[1] <= [NaN]` are `#!cpp true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all
+    yield `#!cpp false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the
+    same for all language standards. The same program can therefore order such values differently when it is compiled
+    with a different language standard.
+
 !!! note "Operator overload resolution"
 
     Since C++20 overload resolution will consider the _rewritten candidate_ generated from

api/basic_json/operator_le/index.md

@@ -51,6 +51,8 @@ Comparing `NaN`
 1. Comparing a `NaN` with another `NaN`.
 1. Comparing a `NaN` and any other number.
 
+For arrays and objects, the elements are compared in order. If the comparison reaches a `NaN` and a number (or another `NaN`) before any other difference, the result depends on the language standard. Before C++20, the pair counts as equivalent and the following elements (or the sizes) decide: for instance, `[NaN] < [1, NaN]` and `[1] <= [NaN]` are `true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all yield `false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the same for all language standards. The same program can therefore order such values differently when it is compiled with a different language standard.
+
 Operator overload resolution
 
 Since C++20 overload resolution will consider the *rewritten candidate* generated from [`operator<=>`](https://json.nlohmann.me/api/basic_json/operator_spaceship/index.md).

api/basic_json/operator_lt.md

@@ -71,6 +71,14 @@ Linear.
       2. Comparing a `NaN` with another `NaN`.
       3. Comparing a `NaN` and any other number.
 
+    For arrays and objects, the elements are compared in order. If the comparison reaches a `NaN` and a number (or
+    another `NaN`) before any other difference, the result depends on the language standard. Before C++20, the pair
+    counts as equivalent and the following elements (or the sizes) decide: for instance, `[NaN] < [1, NaN]` and
+    `[1] <= [NaN]` are `#!cpp true`. Since C++20, the whole comparison is unordered, and `<`, `<=`, `>`, and `>=` all
+    yield `#!cpp false`. Otherwise (for example `[1, NaN] < [2, NaN]`, or objects whose keys differ), the result is the
+    same for all language standards. The same program can therefore order such values differently when it is compiled
+    with a different language standard.
+
 !!! note "Operator overload resolution"
 
     Since C++20 overload resolution will consider the _rewritten candidate_ generated from