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/diff.md

@@ -8,7 +8,7 @@ static basic_json diff(const basic_json& source,
 Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling
 [`patch`](patch.md) function.
 
-For two JSON values `source` and `target`, the following code yields always `#!cpp true`:
+For two JSON values `source` and `target`, the following code always yields `#!cpp true`:
 ```cpp
 source.patch(diff(source, target)) == target;
 ```
@@ -27,7 +27,7 @@ a JSON patch to convert the `source` to `target`
 
 ## Exception safety
 
-Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
+Strong guarantee: `source` and `target` are never modified.
 
 ## Complexity
 

docs/mkdocs/docs/api/basic_json/from_bjdata.md

@@ -120,3 +120,12 @@ Linear in the size of the input.
 - 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"
+
+    - Overload (2) replaces calls to `from_bjdata` with a pointer and a length as first two parameters, which has been
+      deprecated in version 3.13.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_bjdata(ptr, len, ...);` with `#!cpp from_bjdata(ptr, ptr+len, ...);`.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.

docs/mkdocs/docs/api/basic_json/from_bon8.md

@@ -106,3 +106,12 @@ Linear in the size of the input.
 ## Version history
 
 - Added in version 3.13.0.
+
+!!! warning "Deprecation"
+
+    - Overload (2) replaces calls to `from_bon8` with a pointer and a length as first two parameters, which has been
+      deprecated in version 3.13.0. This overload will be removed in version 4.0.0. Please replace all calls like
+      `#!cpp from_bon8(ptr, len, ...);` with `#!cpp from_bon8(ptr, ptr+len, ...);`.
+
+    You should be warned by your compiler with a `-Wdeprecated-declarations` warning if you are using a deprecated
+    function.

docs/mkdocs/docs/api/basic_json/to_bjdata.md

@@ -68,6 +68,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is
+  discarded; example: `"cannot serialize discarded value to BJData"`
 
 ## Complexity
 
@@ -119,4 +121,6 @@ Linear in the size of the JSON value `j`.
 - BJData version parameter (for draft3 binary encoding) added in version 3.12.0.
 - Added `error_handler` parameter in version 3.13.0. Its default, `keep`, writes the bytes of a string or object key
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
-  [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
+  [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
+- Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
+  array or object was silently skipped, producing invalid BJData.

docs/mkdocs/docs/api/basic_json/to_bson.md

@@ -58,6 +58,9 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if a value nested in `j` is discarded
+  (the top-level value itself is covered by `type_error.317` above, since it must be an object); example:
+  `"cannot serialize discarded value to BSON"`
 
 ## Complexity
 
@@ -110,6 +113,8 @@ pass before anything is written.
 - Throws `out_of_range.412` and `out_of_range.415` since version 3.13.0.
 - Linear in the size of `j`, and no longer limited by the call stack for deeply nested values, since version 3.13.0.
 - `out_of_range.415` is now detected before anything is written, like the other exceptions above, since version 3.13.0.
+- Throws `type_error.321` for a discarded value nested in `j` since version 3.13.0; previously, it was silently
+  skipped, producing a document whose declared size did not match what was actually written.
 - Added `error_handler` parameter in version 3.13.0. Its default, `keep`, writes the bytes of a string or object key
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316` before anything

docs/mkdocs/docs/api/basic_json/to_cbor.md

@@ -49,6 +49,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is
+  discarded; example: `"cannot serialize discarded value to CBOR"`
 
 ## Complexity
 
@@ -86,3 +88,5 @@ Linear in the size of the JSON value `j`.
 - Added `error_handler` parameter in version 3.13.0. Its default, `keep`, writes the bytes of a string or object key
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
+- Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
+  array or object was silently skipped, producing invalid CBOR.

docs/mkdocs/docs/api/basic_json/to_msgpack.md

@@ -54,6 +54,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
   `"subtype 70000 is too large for the MessagePack ext type (max 255)"`
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict`
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is
+  discarded; example: `"cannot serialize discarded value to MessagePack"`
 
 ## Complexity
 
@@ -108,3 +110,5 @@ Linear in the size of the JSON value `j`.
 - Fixed in version 3.13.0 to serialize `number_integer_t`/`number_unsigned_t` pairs of different width correctly;
   before, integers could be serialized with the wrong value if `number_integer_t` was narrower than
   `number_unsigned_t`.
+- Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
+  array or object was silently skipped, producing invalid MessagePack.

docs/mkdocs/docs/api/basic_json/to_ubjson.md

@@ -61,6 +61,8 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va
 - Throws [type_error.316](../../home/exceptions.md#jsonexceptiontype_error316) if a string or object key in `j` is
   not valid UTF-8 and `error_handler` is `strict` (the default only if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled)
+- Throws [type_error.321](../../home/exceptions.md#jsonexceptiontype_error321) if `j` or a value nested in it is
+  discarded; example: `"cannot serialize discarded value to UBJSON"`
 
 ## Complexity
 
@@ -112,3 +114,5 @@ Linear in the size of the JSON value `j`.
 - Added `error_handler` parameter in version 3.13.0. Its default, `keep`, writes the bytes of a string or object key
   that is not valid UTF-8 unchanged, as before; `strict` (the default if
   [`JSON_STRICT_BINARY_UTF8`](../macros/json_strict_binary_utf8.md) is enabled) throws `type_error.316`.
+- Throws `type_error.321` for a discarded value since version 3.13.0; previously, a discarded value nested in an
+  array or object was silently skipped, producing invalid UBJSON.

docs/mkdocs/docs/api/macros/index.md

@@ -61,6 +61,11 @@ header. See also the [macro overview page](../../features/macros.md).
 - [**JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS**](json_use_objects_for_enum_keyed_maps.md) - opt in to storing maps with enum
   keys as objects
 
+## Deprecated functions
+
+- [**JSON_DELETE_DEPRECATED_FUNCTIONS**](json_delete_deprecated_functions.md) - opt in to deleting the deprecated
+  functions ahead of their removal in version 4.0.0
+
 ## Comparison behavior
 
 - [**JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON**](json_use_legacy_discarded_value_comparison.md) -

docs/mkdocs/docs/api/macros/json_delete_deprecated_functions.md

@@ -0,0 +1,96 @@
+# JSON_DELETE_DEPRECATED_FUNCTIONS
+
+```cpp
+#define JSON_DELETE_DEPRECATED_FUNCTIONS /* value */
+```
+
+When defined to `1`, all [deprecated functions](../../community/roadmap.md#removal-of-deprecated-functions) of the
+library are declared as deleted (`= delete`) instead of only being marked as deprecated. Code that still calls one of
+them no longer compiles. This way, you can find all calls that need to be replaced before version 4.0.0 removes these
+functions; the [migration guide](../../integration/migration_guide.md#replace-deprecated-functions) describes how.
+
+A deleted function, unlike a removed one, still takes part in overload resolution. A call that would select it
+therefore fails to compile instead of silently selecting another overload. This matters for the deprecated
+`from_*(ptr, len)` overloads of [`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_bon8`](../basic_json/from_bon8.md), and [`from_bson`](../basic_json/from_bson.md): without them, a call like
+`from_cbor(ptr, len)` would compile, read `ptr` as a NUL-terminated string, and convert `len` to the `strict` parameter.
+
+The macro does not affect the deprecated legacy comparison of discarded values, which is controlled by
+[`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](json_use_legacy_discarded_value_comparison.md).
+
+## Default definition
+
+The default value is `0` (disabled, the deprecated functions can still be called, and the compiler warns about it).
+
+```cpp
+#define JSON_DELETE_DEPRECATED_FUNCTIONS 0
+```
+
+## Notes
+
+!!! info "CMake option"
+
+    The macro can also be set with the CMake option
+    [`JSON_DeleteDeprecatedFunctions`](../../integration/cmake.md#json_deletedeprecatedfunctions) (`OFF` by default).
+
+!!! warning "Opt-in only"
+
+    This macro must be defined **before** including `<nlohmann/json.hpp>`. Defining it after the include has no
+    effect. Define it for the whole project to avoid different declarations of the same class in different
+    translation units.
+
+!!! note "ABI compatibility"
+
+    The macro only turns calls that compile into calls that do not; it does not change the layout or the behavior of
+    any type. Its value is therefore not encoded in the [namespace](../../features/namespace.md).
+
+## Examples
+
+??? example "Example: default behavior (macro not defined)"
+
+    Without the macro, the deprecated overload is called, and the compiler warns about it:
+
+    ```cpp
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        const std::vector<std::uint8_t> v = {0x82, 0x01, 0x02};
+        auto j = json::from_cbor(v.data(), v.size());
+        // warning: 'from_cbor' is deprecated: Since 3.8.0; use from_cbor(ptr, ptr + len)
+    }
+    ```
+
+??? example "Example: deleted deprecated functions (macro defined to 1)"
+
+    With the macro, the call does not compile:
+
+    ```cpp
+    #define JSON_DELETE_DEPRECATED_FUNCTIONS 1
+    #include <nlohmann/json.hpp>
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        const std::vector<std::uint8_t> v = {0x82, 0x01, 0x02};
+        auto j = json::from_cbor(v.data(), v.size());
+        // error: call to deleted function 'from_cbor'
+    }
+    ```
+
+## See also
+
+- [Roadmap: removal of deprecated functions](../../community/roadmap.md#removal-of-deprecated-functions) - the
+  deprecated functions and the version they were deprecated in
+- [Migration guide: replace deprecated functions](../../integration/migration_guide.md#replace-deprecated-functions) -
+  how to replace each deprecated function
+
+## Version history
+
+- Added in version 3.13.0.
+- Planned to be removed in version 4.0.0, which removes the deprecated functions. The deprecated `from_*(ptr, len)`
+  overloads stay deleted in version 4.0.0.

docs/mkdocs/docs/api/macros/json_disable_tuple_reference_conversion.md

@@ -112,3 +112,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.

docs/mkdocs/docs/api/macros/json_use_implicit_conversions.md

@@ -44,7 +44,7 @@ By default, implicit conversions are enabled.
 
 ## Examples
 
-??? example "Example: implicit conversion"
+??? example "Example: implicit and explicit conversions"
 
     This is an example for an implicit conversion:
 

docs/mkdocs/docs/api/macros/json_use_objects_for_enum_keyed_maps.md

@@ -69,7 +69,7 @@ The default value is `0` (disabled — existing behavior is preserved).
 
 ## Examples
 
-??? example "Default behavior (macro not defined)"
+??? example "Example: default behavior (macro not defined)"
 
     Without the macro, a map with enum keys is stored as an array of pairs:
 
@@ -96,7 +96,7 @@ The default value is `0` (disabled — existing behavior is preserved).
     }
     ```
 
-??? example "Objects for enum-keyed maps (macro defined to 1)"
+??? example "Example: objects for enum-keyed maps (macro defined to 1)"
 
     With the macro, the same map is stored as an object: