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

@@ -64,18 +64,7 @@ values of that type directly to a `basic_json` instance, and they will automatic
 rather than arrays:
 
 ```cpp
-using custom_json = nlohmann::basic_json<
-    nlohmann::ordered_map,  // ObjectType
-    std::vector,            // ArrayType
-    std::string,            // StringType
-    bool,                   // BooleanType
-    std::int64_t,           // NumberIntegerType
-    std::uint64_t,          // NumberUnsignedType
-    double,                 // NumberFloatType
-    std::allocator,         // AllocatorType
-    nlohmann::adl_serializer,
-    std::vector<std::byte>  // Custom BinaryType
->;
+using custom_json = nlohmann::ordered_json::with_binary_t<std::vector<std::byte>>;
 
 std::vector<std::byte> data{std::byte{1}, std::byte{2}, std::byte{3}};
 custom_json j = data;  // Creates a binary value, not an array

docs/mkdocs/docs/api/basic_json/object_t.md

@@ -26,7 +26,8 @@ To store objects in C++, a type is defined by the template parameters described
 
 `StringType`
 :   the type of the keys or names (e.g., `std::string`). The comparison function `std::less<StringType>` is used to
-    order elements inside the container.
+    order elements inside the container. `object_t::key_type` must be implicitly convertible to `string_t` (required by the
+    binary formats).
 
 `AllocatorType`
 :   the allocator to use for objects (e.g., `std::allocator`)

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

@@ -67,7 +67,7 @@ By default, implicit conversions are enabled.
     `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`:
 
     ```cpp
-    using wjson = nlohmann::basic_json<std::map, std::vector, std::wstring>;
+    using wjson = nlohmann::json::with_string_t<std::wstring>;
 
     void load(const nlohmann::json& j);
 

docs/mkdocs/docs/community/roadmap.md

@@ -36,13 +36,26 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js
 ## API stability
 
 Releases follow [semantic versioning](https://semver.org): a minor or patch release of version 3.x does not break code
-that uses the public API. In particular, a 3.x release does not:
+that uses the public API, unless that code opts in to a change with a macro as described [below](#version-40). In
+particular, a 3.x release does not:
 
-- change the signature of a function (its parameter types, return type, number of parameters, or the const-ness of a
-  member function);
-- remove or rename a function or class;
+- make breaking changes to the signature of a function: the types or order of its existing parameters, its return type,
+  its `noexcept` or `constexpr` specifier, or the const-ness of a member function. New parameters may be added if they
+  have a default value;
+- remove or rename a function or class, or change the template parameters of a public class template;
 - change which exceptions a function throws, or the [exception ids](../home/exceptions.md);
-- change access specifiers or default arguments.
+- change access specifiers, or change or remove existing default arguments. New default arguments may be added;
+- change the JSON type that a valid input parses to, or the text that `dump()` produces for a valid value;
+- accept input that was rejected before, or reject input that was accepted before;
+- change the order in which the keys of an object are iterated. The default type sorts keys, and
+  [`ordered_json`](../api/ordered_json.md) keeps insertion order;
+- change when iterators, pointers, or references are invalidated, or the state of a moved-from `basic_json`;
+- add or remove implicit conversions from `basic_json`;
+- change how `to_json` and `from_json` functions are found, or the behavior of
+  [`adl_serializer`](../api/adl_serializer/index.md);
+- add pure virtual functions to the [`json_sax`](../api/json_sax/index.md) interface;
+- remove, rename, renumber, or add enumerators of `value_t`;
+- remove or rename a documented macro, CMake option, CMake target, or header, or change what a documented macro does.
 
 Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are
 documented in the [release notes](../home/releases.md).
@@ -51,13 +64,14 @@ The following are **not** part of the public API and may change in any release,
 
 - The text of exception messages returned by `what()`. Use the [exception id](../home/exceptions.md) to tell errors
   apart.
-- The ABI, including `sizeof(basic_json)` and the memory layout of its values. Recompile your code when you upgrade the
-  library. The [versioned inline namespace](../features/namespace.md) turns mixing versions into a link error.
+- The ABI, including `sizeof(basic_json)` and the memory layout of its values. The
+  [versioned inline namespace](../features/namespace.md) turns mixing versions into a link error.
+- The hash values returned by `std::hash` for `basic_json`. Numbers that compare equal still hash equally.
 - Everything in namespace `nlohmann::detail`, and macros and type traits that are not documented in the
   [API reference](../api/basic_json/index.md).
 
-Changes that would break the public API are only added behind a macro whose default keeps the 3.x behavior, see
-[Version 4.0](#version-40).
+Breaking changes are only added behind a macro whose default keeps the 3.x behavior. See [Version 4.0](#version-40) and
+the [macro overview](../features/macros.md).
 
 ## Version 4.0
 

docs/mkdocs/docs/examples/as_base_class.cpp

@@ -15,19 +15,7 @@ class base_class_with_hidden_members
     }
 };
 
-using json = nlohmann::basic_json <
-             std::map,
-             std::vector,
-             std::string,
-             bool,
-             std::int64_t,
-             std::uint64_t,
-             double,
-             std::allocator,
-             nlohmann::adl_serializer,
-             std::vector<std::uint8_t>,
-             base_class_with_hidden_members
-             >;
+using json = nlohmann::json::with_base_class_t<base_class_with_hidden_members>;
 
 int main()
 {

docs/mkdocs/docs/examples/contains__json_pointer.cpp

@@ -19,25 +19,9 @@ int main()
               << j.contains("/array/1"_json_pointer) << '\n'
               << j.contains("/array/-"_json_pointer) << '\n'
               << j.contains("/array/4"_json_pointer) << '\n'
-              << j.contains("/baz"_json_pointer) << std::endl;
-
-    try
-    {
-        // try to use an array index with leading '0'
-        j.contains("/array/01"_json_pointer);
-    }
-    catch (const json::parse_error& e)
-    {
-        std::cout << e.what() << '\n';
-    }
-
-    try
-    {
-        // try to use an array index that is not a number
-        j.contains("/array/one"_json_pointer);
-    }
-    catch (const json::parse_error& e)
-    {
-        std::cout << e.what() << '\n';
-    }
+              << j.contains("/baz"_json_pointer) << '\n'
+              // an array index with a leading '0' is not found
+              << j.contains("/array/01"_json_pointer) << '\n'
+              // an array index that is not a number is not found
+              << j.contains("/array/one"_json_pointer) << std::endl;
 }

docs/mkdocs/docs/examples/contains__json_pointer.output

@@ -5,3 +5,5 @@ true
 false
 false
 false
+false
+false

docs/mkdocs/docs/examples/custom_array_type.cpp

@@ -1,11 +1,10 @@
 #include <iostream>
-#include <map>
 
 #include <nlohmann/json.hpp>
 
 #include "custom_array_type.hpp"
 
-using custom_json = nlohmann::basic_json<std::map, custom_array_type>;
+using custom_json = nlohmann::json::with_array_t<custom_array_type>;
 
 int main()
 {

docs/mkdocs/docs/examples/custom_binary_type.cpp

@@ -1,16 +1,10 @@
-#include <cstdint>
 #include <iostream>
-#include <map>
-#include <string>
-#include <vector>
 
 #include <nlohmann/json.hpp>
 
 #include "custom_binary_type.hpp"
 
-using custom_json = nlohmann::basic_json<std::map, std::vector, std::string, bool,
-      std::int64_t, std::uint64_t, double, std::allocator,
-      nlohmann::adl_serializer, custom_binary_type>;
+using custom_json = nlohmann::json::with_binary_t<custom_binary_type>;
 
 int main()
 {

docs/mkdocs/docs/examples/custom_object_type.cpp

@@ -1,12 +1,11 @@
 #include <iostream>
 #include <type_traits>
-#include <vector>
 
 #include <nlohmann/json.hpp>
 
 #include "custom_object_type.hpp"
 
-using custom_json = nlohmann::basic_json<custom_object_type, std::vector>;
+using custom_json = nlohmann::json::with_object_t<custom_object_type>;
 
 int main()
 {

docs/mkdocs/docs/examples/custom_string_type.cpp

@@ -1,12 +1,10 @@
 #include <iostream>
-#include <map>
-#include <vector>
 
 #include <nlohmann/json.hpp>
 
 #include "custom_string_type.hpp"
 
-using custom_json = nlohmann::basic_json<std::map, std::vector, custom_string_type>;
+using custom_json = nlohmann::json::with_string_t<custom_string_type>;
 
 int main()
 {

docs/mkdocs/docs/examples/parse_error.cpp

@@ -8,7 +8,7 @@ int main()
     try
     {
         // parsing input with a syntax error
-        json::parse("[1,2,3,]");
+        json j = json::parse("[1,2,3,]");
     }
     catch (const json::parse_error& e)
     {

docs/mkdocs/docs/features/types/number_handling.md

@@ -351,9 +351,8 @@ The number types can be changed with template parameters.
 
     A `basic_json` type that uses `#!c long double` as floating-point type.
 
-    ```cpp hl_lines="2"
-    using json_ld = nlohmann::basic_json<std::map, std::vector, std::string, bool,
-                                         std::int64_t, std::uint64_t, long double>;
+    ```cpp hl_lines="1"
+    using json_ld = nlohmann::json::with_float_t<long double>;
     ```
 
     Note values should then be parsed with `json_ld::parse` rather than `json::parse` as the latter would parse

docs/mkdocs/docs/features/types/template_parameters.md

@@ -8,6 +8,10 @@ these requirements so they do not have to be discovered by trial and error. Each
 that are known to work for that parameter and the ones that do not, checked against Boost 1.83, Abseil 20250127.0,
 Folly, EASTL 3.21, `ankerl::unordered_dense`, `phmap`, `gtl`, `robin_hood`, `tsl::ordered_map`, and Qt 6.
 
+To change a single template parameter and keep the others, use the member alias templates
+[`with_*_t`](../../api/basic_json/with_t.md); for instance, `nlohmann::json::with_float_t<long double>` is `json` with
+`#!cpp long double` as [`number_float_t`](../../api/basic_json/number_float_t.md).
+
 ## How to read this page
 
 Requirements are split into two groups:
@@ -143,7 +147,7 @@ struct unordered_map_object
     using base_t::base_t;
 };
 
-using unordered_json = nlohmann::basic_json<unordered_map_object>;
+using unordered_json = nlohmann::json::with_object_t<unordered_map_object>;
 ```
 
 Whether `#!cpp std::unordered_map` can be instantiated at all depends on the standard library: `object_t` is formed
@@ -176,7 +180,7 @@ struct flat_hash_object
     using base_t::base_t;
 };
 
-using flat_hash_json = nlohmann::basic_json<flat_hash_object>;
+using flat_hash_json = nlohmann::json::with_object_t<flat_hash_object>;
 ```
 
 `absl::node_hash_map` keeps references to the mapped values valid across insertions; `absl::flat_hash_map` does not,

docs/mkdocs/docs/integration/migration_guide.md

@@ -116,7 +116,7 @@ function to use instead.
     === "Deprecated"
   
           ```cpp
-          using my_json = nlohmann::basic_json<std::map, std::vector, my_string_type>;
+          using my_json = nlohmann::json::with_string_t<my_string_type>;
           nlohmann::json_pointer<my_json> ptr("/foo/bar/1");
           ```
   

docs/mkdocs/docs/integration/package_managers.md

@@ -125,10 +125,24 @@ meson wrap install nlohmann_json
 Please see the Meson project for any issues regarding the packaging.
 
 The provided `meson.build` can also be used as an alternative to CMake for installing `nlohmann_json` system-wide in
-which case a [pkg-config](pkg-config.md) file is installed. To use it, have your build system require the
-`nlohmann_json` pkg-config dependency. In Meson, it is preferred to use the
-[`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a subproject fallback, rather than
-using the subproject directly.
+which case a [pkg-config](pkg-config.md) file and the CMake package config files are installed. To use it, have your build system require
+the `nlohmann_json` pkg-config dependency, or use [`find_package(nlohmann_json)`](cmake.md#external) in CMake. In Meson,
+it is preferred to use the [`dependency()`](https://mesonbuild.com/Reference-manual.html#dependency) object with a
+subproject fallback, rather than using the subproject directly.
+
+The options that change the library's configuration are available in Meson as well, named like the
+[CMake options](cmake.md#cmake-options) without the `JSON_` prefix: `MultipleHeaders`, `GlobalUDLs`,
+`ImplicitConversions`, `DisableEnumSerialization`, `DisableTupleReferenceConversion`, `Diagnostics`,
+`Diagnostic_Positions`, `LegacyDiscardedValueComparison`, `StrictNulHandling`, `StrictBinaryUTF8`, and
+`DeleteDeprecatedFunctions`. They have the same defaults as in CMake, except that
+`MultipleHeaders` is `false`. Set them with `-D` when setting up the build, or with the subproject name as prefix when
+the library is used as a subproject:
+
+```shell
+meson setup build -Dnlohmann_json:Diagnostics=true
+```
+
+The resulting compile definitions are part of the Meson dependency, the pkg-config file, and the CMake target.
 
 ??? example "Example: Wrap"