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>

docs/mkdocs/docs/examples/json_base_class_t.cpp

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

include/nlohmann/json.hpp

@@ -231,58 +231,63 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     ////////////////////////////////////////////////////////////////////////////////
 
     /// Json type using a different type for storing objects
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<template<typename, typename, typename...> class ObjectType2>
-    using with_changed_object_t = basic_json<ObjectType2, ArrayType, StringType, BooleanType,
+    using with_object_t = basic_json<ObjectType2, ArrayType, StringType, BooleanType,
           NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing arrays
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<template<typename, typename...> class ArrayType2>
-    using with_changed_array_t =  basic_json<ObjectType, ArrayType2, StringType, BooleanType,
+    using with_array_t =  basic_json<ObjectType, ArrayType2, StringType, BooleanType,
           NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing strings
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class StringType2>
-    using with_changed_string_t =  basic_json<ObjectType, ArrayType, StringType2, BooleanType,
+    using with_string_t =  basic_json<ObjectType, ArrayType, StringType2, BooleanType,
           NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing booleans
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class BooleanType2>
-    using with_changed_boolean_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType2,
+    using with_boolean_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType2,
           NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
-    /// Json type using a different type for storing signed integers
+    /// Json type using different types for storing signed and unsigned integers
-    template<class NumberIntegerType2>
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
-    using with_changed_integer_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    template<class NumberIntegerType2, class NumberUnsignedType2>
-          NumberIntegerType2, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+    using with_integers_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
-
+          NumberIntegerType2, NumberUnsignedType2, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
-    /// Json type using a different type for storing unsigned integers
-    template<class NumberUnsignedType2>
-    using with_changed_unsigned_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
-          NumberIntegerType, NumberUnsignedType2, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing floating point numbers
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class NumberFloatType2>
-    using with_changed_float_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_float_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
           NumberIntegerType, NumberUnsignedType, NumberFloatType2, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type as base allocator
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<template<typename> class AllocatorType2>
-    using with_changed_allocator_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_allocator_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
           NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType2, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type as json serializer
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<template<typename, typename = void> class JSONSerializer2>
-    using with_changed_json_serializer_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_json_serializer_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
           NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer2, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing binary data
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class BinaryType2>
-    using with_changed_binary_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_binary_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
           NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType2, CustomBaseClass>;
 
     /// Json type using a different type as base class
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class CustomBaseClass2>
-    using with_changed_base_class_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_base_class_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
           NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass2>;
 
     ////////////////

single_include/nlohmann/json.hpp

@@ -27353,59 +27353,64 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec
     ////////////////////////////////////////////////////////////////////////////////
 
     /// Json type using a different type for storing objects
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<template<typename, typename, typename...> class ObjectType2>
-    using with_changed_object_t = basic_json<ObjectType2, ArrayType, StringType, BooleanType,
+    using with_object_t = basic_json<ObjectType2, ArrayType, StringType, BooleanType,
-            NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+                                     NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing arrays
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<template<typename, typename...> class ArrayType2>
-    using with_changed_array_t =  basic_json<ObjectType, ArrayType2, StringType, BooleanType,
+    using with_array_t =  basic_json<ObjectType, ArrayType2, StringType, BooleanType,
-            NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+                                     NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing strings
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class StringType2>
-    using with_changed_string_t =  basic_json<ObjectType, ArrayType, StringType2, BooleanType,
+    using with_string_t =  basic_json<ObjectType, ArrayType, StringType2, BooleanType,
-            NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+                                      NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing booleans
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class BooleanType2>
-    using with_changed_boolean_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType2,
+    using with_boolean_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType2,
-            NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+                                       NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
-    /// Json type using a different type for storing signed integers
+    /// Json type using different types for storing signed and unsigned integers
-    template<class NumberIntegerType2>
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
-    using with_changed_integer_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    template<class NumberIntegerType2, class NumberUnsignedType2>
-            NumberIntegerType2, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+    using with_integers_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
-
+                                        NumberIntegerType2, NumberUnsignedType2, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
-    /// Json type using a different type for storing unsigned integers
-    template<class NumberUnsignedType2>
-    using with_changed_unsigned_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
-            NumberIntegerType, NumberUnsignedType2, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing floating point numbers
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class NumberFloatType2>
-    using with_changed_float_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_float_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
-            NumberIntegerType, NumberUnsignedType, NumberFloatType2, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
+                                     NumberIntegerType, NumberUnsignedType, NumberFloatType2, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type as base allocator
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<template<typename> class AllocatorType2>
-    using with_changed_allocator_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_allocator_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
-            NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType2, JSONSerializer, BinaryType, CustomBaseClass>;
+                                         NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType2, JSONSerializer, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type as json serializer
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<template<typename, typename = void> class JSONSerializer2>
-    using with_changed_json_serializer_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_json_serializer_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
-            NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer2, BinaryType, CustomBaseClass>;
+        NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer2, BinaryType, CustomBaseClass>;
 
     /// Json type using a different type for storing binary data
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class BinaryType2>
-    using with_changed_binary_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_binary_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
-            NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType2, CustomBaseClass>;
+                                      NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType2, CustomBaseClass>;
 
     /// Json type using a different type as base class
+    /// @sa https://json.nlohmann.me/api/basic_json/with_t/
     template<class CustomBaseClass2>
-    using with_changed_base_class_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
+    using with_base_class_t =  basic_json<ObjectType, ArrayType, StringType, BooleanType,
-            NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass2>;
+                                          NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType, CustomBaseClass2>;
 
     ////////////////
     // exceptions //

tests/src/unit-allocator.cpp

@@ -48,7 +48,7 @@ TEST_CASE("bad_alloc")
     SECTION("bad_alloc")
     {
         // create JSON type using the throwing allocator
-        using bad_json = nlohmann::json::with_changed_allocator_t<bad_allocator>;
+        using bad_json = nlohmann::json::with_allocator_t<bad_allocator>;
 
         // creating an object should throw
         CHECK_THROWS_AS(bad_json(bad_json::value_t::object), std::bad_alloc&);
@@ -122,7 +122,7 @@ void my_allocator_clean_up(T* p)
 TEST_CASE("controlled bad_alloc")
 {
     // create JSON type using the throwing allocator
-    using my_json = nlohmann::json::with_changed_allocator_t<my_allocator>;
+    using my_json = nlohmann::json::with_allocator_t<my_allocator>;
 
     SECTION("class json_value")
     {
@@ -574,7 +574,7 @@ TEST_CASE("bad my_allocator::construct")
 {
     SECTION("my_allocator::construct doesn't forward")
     {
-        using bad_alloc_json = nlohmann::json::with_changed_allocator_t<allocator_no_forward>;
+        using bad_alloc_json = nlohmann::json::with_allocator_t<allocator_no_forward>;
 
         bad_alloc_json j;
         j["test"] = bad_alloc_json::array_t();

tests/src/unit-alt-string.cpp

@@ -163,7 +163,7 @@ void int_to_string(alt_string& target, std::size_t value)
     target = std::to_string(value).c_str();
 }
 
-using alt_json = nlohmann::json::with_changed_string_t<alt_string>;
+using alt_json = nlohmann::json::with_string_t<alt_string>;
 
 bool operator<(const char* op1, const alt_string& op2) noexcept
 {

tests/src/unit-custom-base-class.cpp

@@ -38,7 +38,7 @@ class json_metadata
 };
 
 template<class T>
-using json_with_metadata = nlohmann::json::with_changed_base_class_t<json_metadata<T>>;
+using json_with_metadata = nlohmann::json::with_base_class_t<json_metadata<T>>;
 
 TEST_CASE("JSON Node Metadata")
 {
@@ -255,7 +255,7 @@ class visitor_adaptor
     void do_visit(const Ptr& ptr, const Fnc& fnc) const;
 };
 
-using json_with_visitor_t = nlohmann::json::with_changed_base_class_t<visitor_adaptor>;
+using json_with_visitor_t = nlohmann::json::with_base_class_t<visitor_adaptor>;
 
 template <class Fnc>
 void visitor_adaptor::visit(const Fnc& fnc) const

tests/src/unit-udt.cpp

@@ -684,7 +684,7 @@ static std::ostream& operator<<(std::ostream& os, small_pod l)
 TEST_CASE("custom serializer for pods" * doctest::test_suite("udt"))
 {
     using custom_json =
-        nlohmann::json::with_changed_json_serializer_t<pod_serializer>;
+        nlohmann::json::with_json_serializer_t<pod_serializer>;
 
     auto p = udt::small_pod{42, '/', 42};
     custom_json const j = p;
@@ -702,7 +702,7 @@ TEST_CASE("custom serializer for pods" * doctest::test_suite("udt"))
 template <typename T, typename>
 struct another_adl_serializer;
 
-using custom_json = nlohmann::json::with_changed_json_serializer_t<another_adl_serializer>;
+using custom_json = nlohmann::json::with_json_serializer_t<another_adl_serializer>;
 
 template <typename T, typename>
 struct another_adl_serializer