Add with_*_t alias templates to create basic_json types with changed template parameters (#5758)

* Add helper types to make it easier to create a basic_json type with modified template parameters

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

* Rename with_changed_*_t aliases to with_*_t and merge integer/unsigned aliases

Per review discussion on #3898 between gregmarr and nlohmann:
- rename with_changed_X_t to with_X_t for brevity
- replace the separate with_changed_integer_t/with_changed_unsigned_t
  aliases with a single with_integers_t<NumberIntegerType2, NumberUnsignedType2>
- add @sa doc comment links for the upcoming documentation page

Co-authored-by: Raphael Grimm <1005058+barcode@users.noreply.github.com>
Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Add documentation for the with_*_t member alias templates

Add docs/mkdocs/docs/api/basic_json/with_t.md documenting 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,
with an accompanying example, and link the page from the basic_json member
types list and the mkdocs navigation.

Co-authored-by: Raphael Grimm <1005058+barcode@users.noreply.github.com>
Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Add tests for the with_*_t member alias templates

Check with std::is_same that each with_*_t alias produces the expected
basic_json type, and that with_string_t keeps nlohmann::ordered_map as
the object type when used on ordered_json.

Co-authored-by: Raphael Grimm <1005058+barcode@users.noreply.github.com>
Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Fix with_t nav entry and document chaining of the with_*_t aliases

Indent the with_t entry in mkdocs.yml so it is listed under basic_json,
explain that the aliases can be chained and work on ordered_json, and
test both, including json::with_object_t<ordered_map> == ordered_json.

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

* Add docset entry for basic_json::with_t

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

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Co-authored-by: barcode <barcode@example.com>
Co-authored-by: Raphael Grimm <1005058+barcode@users.noreply.github.com>

docs/docset/docSet.sql

@@ -131,6 +131,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::to_string', 'Meth
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::to_ubjson', 'Function', 'api/basic_json/to_ubjson/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::value', 'Method', 'api/basic_json/value/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::value_t', 'Enum', 'api/basic_json/value_t/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::with_t', 'Type', 'api/basic_json/with_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::~basic_json', 'Method', 'api/basic_json/~basic_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json', 'Class', 'api/json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('json_pointer', 'Class', 'api/json_pointer/index.html');

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/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/examples/json_base_class_t.cpp

@@ -13,19 +13,7 @@ class visitor_adaptor_with_metadata
     void do_visit(const Ptr& ptr, const Fnc& fnc) const;
 };
 
-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>,
-             visitor_adaptor_with_metadata
-             >;
+using json = nlohmann::json::with_base_class_t<visitor_adaptor_with_metadata>;
 
 template <class Fnc>
 void visitor_adaptor_with_metadata::visit(const Fnc& fnc) const

docs/mkdocs/docs/examples/with_t.cpp

@@ -0,0 +1,18 @@
+#include <iostream>
+#include <map>
+#include <nlohmann/json.hpp>
+
+// a JSON type that stores objects in a std::map (which keeps keys sorted)
+// instead of the default ordered associative container
+using sorted_json = nlohmann::json::with_object_t<std::map>;
+
+int main()
+{
+    sorted_json j;
+    j["c"] = 1;
+    j["a"] = 2;
+    j["b"] = 3;
+
+    // keys are sorted, because std::map is used to store the object
+    std::cout << j.dump() << std::endl;
+}

docs/mkdocs/docs/examples/with_t.output

@@ -0,0 +1 @@
+{"a":2,"b":3,"c":1}

docs/mkdocs/mkdocs.yml

@@ -232,6 +232,7 @@ nav:
           - 'update': api/basic_json/update.md
           - 'value': api/basic_json/value.md
           - 'value_t': api/basic_json/value_t.md
+          - 'with_t': api/basic_json/with_t.md
       - byte_container_with_subtype:
           - 'Overview': api/byte_container_with_subtype/index.md
           - '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md