Merge remote-tracking branch 'origin/develop' into claude/fix-issue-3989-db7e45

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md

@@ -9,10 +9,10 @@ enum class cbor_tag_handler_t
 };
 ```
 
-This enumeration is used in the [`from_cbor`](from_cbor.md) function to choose how to treat tags:
+This enumeration is used in [`from_cbor`](from_cbor.md) and [`sax_parse`](sax_parse.md) to choose how to treat tags:
 
 error
-:   throw a `parse_error` exception in case of a tag
+:   report a parse error in case of a tag (the `from_cbor` overloads throw a `parse_error` exception by default)
 
 ignore
 :   ignore tags

docs/mkdocs/docs/api/basic_json/index.md

@@ -109,6 +109,9 @@ The class satisfies the following concept requirements:
 - **initializer_list_t** - type for initializer lists of `basic_json` values
 - [**input_format_t**](input_format_t.md) - type to choose the format to parse
 - [**json_sax_t**](../json_sax/index.md) - type for SAX events
+- [**with_object_t, with_array_t, with_string_t, with_boolean_t, with_integers_t, with_float_t, with_allocator_t,
+  with_json_serializer_t, with_binary_t, with_base_class_t**](with_t.md) - types to create a `basic_json` type with
+  one (or two) replaced template parameters
 
 ### Exceptions
 

docs/mkdocs/docs/api/basic_json/sax_parse.md

@@ -8,7 +8,8 @@ static bool sax_parse(InputType&& i,
                       input_format_t format = input_format_t::json,
                       const bool strict = true,
                       const bool ignore_comments = false,
-                      const bool ignore_trailing_commas = false);
+                      const bool ignore_trailing_commas = false,
+                      const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
 
 // (2)
 template<class IteratorType, class SAX, class SentinelType = IteratorType>
@@ -17,13 +18,14 @@ static bool sax_parse(IteratorType first, SentinelType last,
                       input_format_t format = input_format_t::json,
                       const bool strict = true,
                       const bool ignore_comments = false,
-                      const bool ignore_trailing_commas = false);
+                      const bool ignore_trailing_commas = false,
+                      const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
 ```
 
 Read from input and generate SAX events
 
 1. Read from a compatible input.
-2. Read from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)
+2. Read from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support).
     
     The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted
     respectively as UTF-8, UTF-16, and UTF-32. If `SentinelType` differs from `IteratorType`, it must be comparable to
@@ -82,6 +84,10 @@ The SAX event lister must follow the interface of [`json_sax`](../json_sax/index
 :   whether trailing commas in arrays or objects should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
     (`#!cpp false`); (optional, `#!cpp false` by default)
 
+`tag_handler` (in)
+:   how to handle CBOR tags; see [`cbor_tag_handler_t`](cbor_tag_handler_t.md). Ignored for formats other than CBOR
+    (optional, `cbor_tag_handler_t::error` by default).
+
 `first` (in)
 :   iterator to the start of a character range
 
@@ -139,6 +145,7 @@ A UTF-8 byte order mark is silently ignored.
 - Added in version 3.2.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
 - Added `ignore_trailing_commas` in version 3.13.0.
+- Added `tag_handler` in version 3.13.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.
 - Recovering from parse errors (see [`parse_error`](../json_sax/parse_error.md)) added in version 3.13.0.
 - Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.

docs/mkdocs/docs/api/basic_json/with_t.md

@@ -0,0 +1,136 @@
+# <small>nlohmann::basic_json::</small>with_t
+
+Member alias templates `with_object_t`, `with_array_t`, `with_string_t`, `with_boolean_t`, `with_integers_t`,
+`with_float_t`, `with_allocator_t`, `with_json_serializer_t`, `with_binary_t`, and `with_base_class_t`.
+
+```cpp
+template<template<typename, typename, typename...> class ObjectType2>
+using with_object_t = basic_json<ObjectType2, ArrayType, StringType, BooleanType,
+      NumberIntegerType, NumberUnsignedType, NumberFloatType,
+      AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+
+template<template<typename, typename...> class ArrayType2>
+using with_array_t = basic_json<ObjectType, ArrayType2, StringType, BooleanType,
+      NumberIntegerType, NumberUnsignedType, NumberFloatType,
+      AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+
+template<class StringType2>
+using with_string_t = basic_json<ObjectType, ArrayType, StringType2, BooleanType,
+      NumberIntegerType, NumberUnsignedType, NumberFloatType,
+      AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+
+template<class BooleanType2>
+using with_boolean_t = basic_json<ObjectType, ArrayType, StringType, BooleanType2,
+      NumberIntegerType, NumberUnsignedType, NumberFloatType,
+      AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+
+template<class NumberIntegerType2, class NumberUnsignedType2>
+using with_integers_t = basic_json<ObjectType, ArrayType, StringType, BooleanType,
+      NumberIntegerType2, NumberUnsignedType2, NumberFloatType,
+      AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+
+template<class NumberFloatType2>
+using with_float_t = basic_json<ObjectType, ArrayType, StringType, BooleanType,
+      NumberIntegerType, NumberUnsignedType, NumberFloatType2,
+      AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+
+template<template<typename> class AllocatorType2>
+using with_allocator_t = basic_json<ObjectType, ArrayType, StringType, BooleanType,
+      NumberIntegerType, NumberUnsignedType, NumberFloatType,
+      AllocatorType2, JSONSerializer, BinaryType, CustomBaseClass>;
+
+template<template<typename, typename = void> class JSONSerializer2>
+using with_json_serializer_t = basic_json<ObjectType, ArrayType, StringType, BooleanType,
+      NumberIntegerType, NumberUnsignedType, NumberFloatType,
+      AllocatorType, JSONSerializer2, BinaryType, CustomBaseClass>;
+
+template<class BinaryType2>
+using with_binary_t = basic_json<ObjectType, ArrayType, StringType, BooleanType,
+      NumberIntegerType, NumberUnsignedType, NumberFloatType,
+      AllocatorType, JSONSerializer, BinaryType2, CustomBaseClass>;
+
+template<class CustomBaseClass2>
+using with_base_class_t = basic_json<ObjectType, ArrayType, StringType, BooleanType,
+      NumberIntegerType, NumberUnsignedType, NumberFloatType,
+      AllocatorType, JSONSerializer, BinaryType, CustomBaseClass2>;
+```
+
+These member alias templates make it easier to create a `basic_json` type that is identical to the current type except
+for one (or, in the case of `with_integers_t`, two) of its [template parameters](index.md#template-parameters).
+Spelling out all 11 template parameters of `basic_json` just to change a single one is verbose and error-prone; these
+aliases only require the replacement type(s).
+
+with_object_t&lt;ObjectType2&gt;
+:   replaces `ObjectType`
+
+with_array_t&lt;ArrayType2&gt;
+:   replaces `ArrayType`
+
+with_string_t&lt;StringType2&gt;
+:   replaces `StringType`
+
+with_boolean_t&lt;BooleanType2&gt;
+:   replaces `BooleanType`
+
+with_integers_t&lt;NumberIntegerType2, NumberUnsignedType2&gt;
+:   replaces both `NumberIntegerType` and `NumberUnsignedType`; the two are combined into a single alias because they
+    are usually changed together (for instance, when switching to fixed-width integer types)
+
+with_float_t&lt;NumberFloatType2&gt;
+:   replaces `NumberFloatType`
+
+with_allocator_t&lt;AllocatorType2&gt;
+:   replaces `AllocatorType`
+
+with_json_serializer_t&lt;JSONSerializer2&gt;
+:   replaces `JSONSerializer`
+
+with_binary_t&lt;BinaryType2&gt;
+:   replaces `BinaryType`
+
+with_base_class_t&lt;CustomBaseClass2&gt;
+:   replaces `CustomBaseClass`; see also [`json_base_class_t`](json_base_class_t.md)
+
+## Notes
+
+All other template parameters are kept unchanged, so the resulting type still uses, for instance, the same
+`ObjectType` unless `with_object_t` itself is used.
+
+The aliases are members of every `basic_json` specialization, including [`ordered_json`](../ordered_json.md), and the
+type they produce is again a `basic_json` specialization. They can therefore be chained to replace several template
+parameters at once:
+
+```cpp
+using my_json = nlohmann::json::with_integers_t<int, unsigned int>::with_float_t<float>;
+using my_ordered_json = nlohmann::ordered_json::with_string_t<std::wstring>;
+```
+
+The result is the same type as spelling out all template parameters, so the order of the chained aliases does not
+matter. For instance, `nlohmann::json::with_object_t<nlohmann::ordered_map>` is `nlohmann::ordered_json`.
+
+## Examples
+
+??? example
+
+    The following code shows how `with_object_t` can be used to create a JSON type that stores object elements in a
+    `std::map` and therefore keeps them sorted by key, unlike the default type which preserves insertion order
+    only when `nlohmann::ordered_json` is used.
+
+    ```cpp
+    --8<-- "examples/with_t.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/with_t.output"
+    ```
+
+## See also
+
+- [basic_json](index.md#template-parameters) - the template parameters that can be replaced
+- [json_base_class_t](json_base_class_t.md) - the type used for `CustomBaseClass`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md

@@ -50,9 +50,11 @@ The default value is `0` (disabled — existing behavior is preserved).
     ```
 
     Code that relies on these producing arrays must use `json::array()` instead (see below). Lists with more than one
-    element, and a single `[string, value]` pair such as `{{"key", "value"}}`, which still creates an object, are not
-    affected. The library's own conversions are not affected either: for example, `std::tuple<int>{5}` still becomes
-    `[5]`.
+    element, and a single `[string, value]` pair *written as a braced list*, such as `{{"key", "value"}}`, which still
+    creates an object, are not affected. This exception is based on how the pair is written, not on the shape of its
+    value: an existing JSON value that happens to be a two-element array with a string as its first element, such as
+    `json arr = {"key", 42};`, is still copied by `json j{arr};` rather than turned into an object. The library's own
+    conversions are not affected either: for example, `std::tuple<int>{5}` still becomes `[5]`.
 
 !!! note "ABI compatibility"