📝 overworked documentation (re-added constructor examples)

doc/examples/basic_json__CompatibleArrayType.cpp

@@ -1,58 +0,0 @@
-#include <json.hpp>
-#include <deque>
-#include <list>
-#include <forward_list>
-#include <set>
-#include <unordered_set>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create an array from std::vector
-    std::vector<int> c_vector {1, 2, 3, 4};
-    json j_vec(c_vector);
-
-    // create an array from std::deque
-    std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
-    json j_deque(c_deque);
-
-    // create an array from std::list
-    std::list<bool> c_list {true, true, false, true};
-    json j_list(c_list);
-
-    // create an array from std::forward_list
-    std::forward_list<int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
-    json j_flist(c_flist);
-
-    // create an array from std::array
-    std::array<unsigned long, 4> c_array {{1, 2, 3, 4}};
-    json j_array(c_array);
-
-    // create an array from std::set
-    std::set<std::string> c_set {"one", "two", "three", "four", "one"};
-    json j_set(c_set); // only one entry for "one" is used
-
-    // create an array from std::unordered_set
-    std::unordered_set<std::string> c_uset {"one", "two", "three", "four", "one"};
-    json j_uset(c_uset); // only one entry for "one" is used
-
-    // create an array from std::multiset
-    std::multiset<std::string> c_mset {"one", "two", "one", "four"};
-    json j_mset(c_mset); // both entries for "one" are used
-
-    // create an array from std::unordered_multiset
-    std::unordered_multiset<std::string> c_umset {"one", "two", "one", "four"};
-    json j_umset(c_umset); // both entries for "one" are used
-
-    // serialize the JSON arrays
-    std::cout << j_vec << '\n';
-    std::cout << j_deque << '\n';
-    std::cout << j_list << '\n';
-    std::cout << j_flist << '\n';
-    std::cout << j_array << '\n';
-    std::cout << j_set << '\n';
-    std::cout << j_uset << '\n';
-    std::cout << j_mset << '\n';
-    std::cout << j_umset << '\n';
-}

doc/examples/basic_json__CompatibleArrayType.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/3BIhBw91FUVuHE1D"><b>online</b></a>

doc/examples/basic_json__CompatibleArrayType.output

@@ -1,9 +0,0 @@
-[1,2,3,4]
-[1.2,2.3,3.4,5.6]
-[true,true,false,true]
-[12345678909876,23456789098765,34567890987654,45678909876543]
-[1,2,3,4]
-["four","one","three","two"]
-["four","three","two","one"]
-["four","one","one","two"]
-["four","two","one","one"]

doc/examples/basic_json__CompatibleIntegerNumberType.cpp

@@ -1,27 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create values of different integer types
-    short n42 = 42;
-    int n23 = 23;
-    long n1024 = 1024;
-    int_least32_t n17 = 17;
-    uint8_t n8 = 8;
-
-    // create JSON numbers
-    json j42(n42);
-    json j23(n23);
-    json j1024(n1024);
-    json j17(n17);
-    json j8(n8);
-
-    // serialize the JSON numbers
-    std::cout << j42 << '\n';
-    std::cout << j23 << '\n';
-    std::cout << j1024 << '\n';
-    std::cout << j17 << '\n';
-    std::cout << j8 << '\n';
-}

doc/examples/basic_json__CompatibleIntegerNumberType.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/PcMzhcu2RpD7KSwr"><b>online</b></a>

doc/examples/basic_json__CompatibleIntegerNumberType.output

@@ -1,5 +0,0 @@
-42
-23
-1024
-17
-8

doc/examples/basic_json__CompatibleNumberFloatType.cpp

@@ -1,21 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create values of different floating-point types
-    float f42 = 42.23;
-    float f_nan = 1.0f / 0.0f;
-    double f23 = 23.42;
-
-    // create JSON numbers
-    json j42(f42);
-    json j_nan(f_nan);
-    json j23(f23);
-
-    // serialize the JSON numbers
-    std::cout << j42 << '\n';
-    std::cout << j_nan << '\n';
-    std::cout << j23 << '\n';
-}

doc/examples/basic_json__CompatibleNumberFloatType.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/2TCYWSrOxnR05AZI"><b>online</b></a>

doc/examples/basic_json__CompatibleNumberFloatType.output

@@ -1,3 +0,0 @@
-42.2299995422363
-null
-23.42

doc/examples/basic_json__CompatibleObjectType.cpp

@@ -1,41 +0,0 @@
-#include <json.hpp>
-#include <unordered_map>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create an object from std::map
-    std::map<std::string, int> c_map
-    {
-        {"one", 1}, {"two", 2}, {"three", 3}
-    };
-    json j_map(c_map);
-
-    // create an object from std::unordered_map
-    std::unordered_map<const char*, double> c_umap
-    {
-        {"one", 1.2}, {"two", 2.3}, {"three", 3.4}
-    };
-    json j_umap(c_umap);
-
-    // create an object from std::multimap
-    std::multimap<std::string, bool> c_mmap
-    {
-        {"one", true}, {"two", true}, {"three", false}, {"three", true}
-    };
-    json j_mmap(c_mmap); // only one entry for key "three" is used
-
-    // create an object from std::unordered_multimap
-    std::unordered_multimap<std::string, bool> c_ummap
-    {
-        {"one", true}, {"two", true}, {"three", false}, {"three", true}
-    };
-    json j_ummap(c_ummap); // only one entry for key "three" is used
-
-    // serialize the JSON objects
-    std::cout << j_map << '\n';
-    std::cout << j_umap << '\n';
-    std::cout << j_mmap << '\n';
-    std::cout << j_ummap << '\n';
-}

doc/examples/basic_json__CompatibleObjectType.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/JzLCMcSXNsh4uVWa"><b>online</b></a>

doc/examples/basic_json__CompatibleObjectType.output

@@ -1,4 +0,0 @@
-{"one":1,"three":3,"two":2}
-{"one":1.2,"three":3.4,"two":2.3}
-{"one":true,"three":false,"two":true}
-{"one":true,"three":false,"two":true}

doc/examples/basic_json__CompatibleStringType.cpp

@@ -1,15 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create a string value
-    std::string s = "The quick brown fox jumps over the lazy dog.";
-
-    // create a JSON string value
-    json j = s;
-
-    // serialize the JSON string
-    std::cout << j << '\n';
-}

doc/examples/basic_json__CompatibleStringType.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/b9hbCY8zfOiTOuoK"><b>online</b></a>

doc/examples/basic_json__CompatibleStringType.output

@@ -1 +0,0 @@
-"The quick brown fox jumps over the lazy dog."

doc/examples/basic_json__CompatibleType.cpp

@@ -0,0 +1,211 @@
+#include <json.hpp>
+#include <deque>
+#include <list>
+#include <forward_list>
+#include <set>
+#include <unordered_map>
+#include <unordered_set>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // ============
+    // object types
+    // ============
+
+    // create an object from an object_t value
+    json::object_t object_value = { {"one", 1}, {"two", 2} };
+    json j_object_t(object_value);
+
+    // create an object from std::map
+    std::map<std::string, int> c_map
+    {
+        {"one", 1}, {"two", 2}, {"three", 3}
+    };
+    json j_map(c_map);
+
+    // create an object from std::unordered_map
+    std::unordered_map<const char*, double> c_umap
+    {
+        {"one", 1.2}, {"two", 2.3}, {"three", 3.4}
+    };
+    json j_umap(c_umap);
+
+    // create an object from std::multimap
+    std::multimap<std::string, bool> c_mmap
+    {
+        {"one", true}, {"two", true}, {"three", false}, {"three", true}
+    };
+    json j_mmap(c_mmap); // only one entry for key "three" is used
+
+    // create an object from std::unordered_multimap
+    std::unordered_multimap<std::string, bool> c_ummap
+    {
+        {"one", true}, {"two", true}, {"three", false}, {"three", true}
+    };
+    json j_ummap(c_ummap); // only one entry for key "three" is used
+
+    // serialize the JSON objects
+    std::cout << j_object_t << '\n';
+    std::cout << j_map << '\n';
+    std::cout << j_umap << '\n';
+    std::cout << j_mmap << '\n';
+    std::cout << j_ummap << "\n\n";
+
+
+    // ===========
+    // array types
+    // ===========
+
+    // create an array from an array_t value
+    json::array_t array_value = {"one", "two", 3, 4.5, false};
+    json j_array_t(array_value);
+
+    // create an array from std::vector
+    std::vector<int> c_vector {1, 2, 3, 4};
+    json j_vec(c_vector);
+
+    // create an array from std::deque
+    std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
+    json j_deque(c_deque);
+
+    // create an array from std::list
+    std::list<bool> c_list {true, true, false, true};
+    json j_list(c_list);
+
+    // create an array from std::forward_list
+    std::forward_list<int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
+    json j_flist(c_flist);
+
+    // create an array from std::array
+    std::array<unsigned long, 4> c_array {{1, 2, 3, 4}};
+    json j_array(c_array);
+
+    // create an array from std::set
+    std::set<std::string> c_set {"one", "two", "three", "four", "one"};
+    json j_set(c_set); // only one entry for "one" is used
+
+    // create an array from std::unordered_set
+    std::unordered_set<std::string> c_uset {"one", "two", "three", "four", "one"};
+    json j_uset(c_uset); // only one entry for "one" is used
+
+    // create an array from std::multiset
+    std::multiset<std::string> c_mset {"one", "two", "one", "four"};
+    json j_mset(c_mset); // both entries for "one" are used
+
+    // create an array from std::unordered_multiset
+    std::unordered_multiset<std::string> c_umset {"one", "two", "one", "four"};
+    json j_umset(c_umset); // both entries for "one" are used
+
+    // serialize the JSON arrays
+    std::cout << j_array_t << '\n';
+    std::cout << j_vec << '\n';
+    std::cout << j_deque << '\n';
+    std::cout << j_list << '\n';
+    std::cout << j_flist << '\n';
+    std::cout << j_array << '\n';
+    std::cout << j_set << '\n';
+    std::cout << j_uset << '\n';
+    std::cout << j_mset << '\n';
+    std::cout << j_umset << "\n\n";
+
+
+    // ============
+    // string types
+    // ============
+
+    // create string from a string_t value
+    json::string_t string_value = "The quick brown fox jumps over the lazy dog.";
+    json j_string_t(string_value);
+
+    // create a JSON string directly from a string literal
+    json j_string_literal("The quick brown fox jumps over the lazy dog.");
+
+    // create string from std::string
+    std::string s_stdstring = "The quick brown fox jumps over the lazy dog.";
+    json j_stdstring(s_stdstring);
+
+    // serialize the JSON strings
+    std::cout << j_string_t << '\n';
+    std::cout << j_string_literal << '\n';
+    std::cout << j_stdstring << "\n\n";
+
+
+    // ============
+    // number types
+    // ============
+
+    // create a JSON number from number_integer_t
+    json::number_integer_t value_integer_t = -42;
+    json j_integer_t(value_integer_t);
+
+    // create a JSON number from number_unsigned_t
+    json::number_integer_t value_unsigned_t = 17;
+    json j_unsigned_t(value_unsigned_t);
+
+    // create a JSON number from an anonymous enum
+    enum { enum_value = 17 };
+    json j_enum(enum_value);
+
+    // create values of different integer types
+    short n_short = 42;
+    int n_int = -23;
+    long n_long = 1024;
+    int_least32_t n_int_least32_t = -17;
+    uint8_t n_uint8_t = 8;
+
+    // create (integer) JSON numbers
+    json j_short(n_short);
+    json j_int(n_int);
+    json j_long(n_long);
+    json j_int_least32_t(n_int_least32_t);
+    json j_uint8_t(n_uint8_t);
+
+    // create values of different floating-point types
+    json::number_float_t v_ok = 3.141592653589793;
+    json::number_float_t v_nan = NAN;
+    json::number_float_t v_infinity = INFINITY;
+
+    // create values of different floating-point types
+    float n_float = 42.23;
+    float n_float_nan = 1.0f / 0.0f;
+    double n_double = 23.42;
+
+    // create (floating point) JSON numbers
+    json j_ok(v_ok);
+    json j_nan(v_nan);
+    json j_infinity(v_infinity);
+    json j_float(n_float);
+    json j_float_nan(n_float_nan);
+    json j_double(n_double);
+
+    // serialize the JSON numbers
+    std::cout << j_integer_t << '\n';
+    std::cout << j_unsigned_t << '\n';
+    std::cout << j_enum << '\n';
+    std::cout << j_short << '\n';
+    std::cout << j_int << '\n';
+    std::cout << j_long << '\n';
+    std::cout << j_int_least32_t << '\n';
+    std::cout << j_uint8_t << '\n';
+    std::cout << j_ok << '\n';
+    std::cout << j_nan << '\n';
+    std::cout << j_infinity << '\n';
+    std::cout << j_float << '\n';
+    std::cout << j_float_nan << '\n';
+    std::cout << j_double << "\n\n";
+
+
+    // =============
+    // boolean types
+    // =============
+
+    // create boolean values
+    json j_truth = true;
+    json j_falsity = false;
+
+    // serialize the JSON booleans
+    std::cout << j_truth << '\n';
+    std::cout << j_falsity << '\n';
+}

doc/examples/basic_json__CompatibleType.link

@@ -0,0 +1 @@
+<a target="_blank" href="http://melpon.org/wandbox/permlink/VM7W2kpE7sIYJ5DW"><b>online</b></a>

doc/examples/basic_json__CompatibleType.output

@@ -0,0 +1,38 @@
+{"one":1,"two":2}
+{"one":1,"three":3,"two":2}
+{"one":1.2,"three":3.4,"two":2.3}
+{"one":true,"three":false,"two":true}
+{"one":true,"three":false,"two":true}
+
+["one","two",3,4.5,false]
+[1,2,3,4]
+[1.2,2.3,3.4,5.6]
+[true,true,false,true]
+[12345678909876,23456789098765,34567890987654,45678909876543]
+[1,2,3,4]
+["four","one","three","two"]
+["four","three","two","one"]
+["four","one","one","two"]
+["four","two","one","one"]
+
+"The quick brown fox jumps over the lazy dog."
+"The quick brown fox jumps over the lazy dog."
+"The quick brown fox jumps over the lazy dog."
+
+-42
+17
+17
+42
+-23
+1024
+-17
+8
+3.14159265358979
+null
+null
+42.2299995422363
+null
+23.42
+
+true
+false

doc/examples/basic_json__array_t.cpp

@@ -1,15 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create an array_t value
-    json::array_t value = {"one", "two", 3, 4.5, false};
-
-    // create a JSON array from the value
-    json j(value);
-
-    // serialize the JSON array
-    std::cout << j << '\n';
-}

doc/examples/basic_json__array_t.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/dTbSNAvl6TqrMEAn"><b>online</b></a>

doc/examples/basic_json__array_t.output

@@ -1 +0,0 @@
-["one","two",3,4.5,false]

doc/examples/basic_json__boolean_t.cpp

@@ -1,14 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create boolean values
-    json j_truth = true;
-    json j_falsity = false;
-
-    // serialize the JSON booleans
-    std::cout << j_truth << '\n';
-    std::cout << j_falsity << '\n';
-}

doc/examples/basic_json__boolean_t.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/VmVl9pyrQp8LyOnU"><b>online</b></a>

doc/examples/basic_json__boolean_t.output

@@ -1,2 +0,0 @@
-true
-false

doc/examples/basic_json__const_int.cpp

@@ -1,15 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // an anonymous enum
-    enum { t = 17 };
-
-    // create a JSON number from the enum
-    json j(t);
-
-    // serialize the JSON numbers
-    std::cout << j << '\n';
-}

doc/examples/basic_json__const_int.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/3xQ1qy7BT9OrSSCo"><b>online</b></a>

doc/examples/basic_json__const_int.output

@@ -1 +0,0 @@
-17

doc/examples/basic_json__number_float_t.cpp

@@ -1,21 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create values of different floating-point types
-    json::number_float_t v_ok = 3.141592653589793;
-    json::number_float_t v_nan = NAN;
-    json::number_float_t v_infinity = INFINITY;
-
-    // create JSON numbers
-    json j_ok(v_ok);
-    json j_nan(v_nan);
-    json j_infinity(v_infinity);
-
-    // serialize the JSON numbers
-    std::cout << j_ok << '\n';
-    std::cout << j_nan << '\n';
-    std::cout << j_infinity << '\n';
-}

doc/examples/basic_json__number_float_t.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/OTgOxjIAKFvxpFdm"><b>online</b></a>

doc/examples/basic_json__number_float_t.output

@@ -1,3 +0,0 @@
-3.14159265358979
-null
-null

doc/examples/basic_json__number_integer_t.cpp

@@ -1,14 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create a JSON number from number_integer_t
-    json::number_integer_t value = 42;
-
-    json j(value);
-
-    // serialize the JSON numbers
-    std::cout << j << '\n';
-}

doc/examples/basic_json__number_integer_t.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/cCQRCvjXdRM9YpT5"><b>online</b></a>

doc/examples/basic_json__number_integer_t.output

@@ -1 +0,0 @@
-42

doc/examples/basic_json__object_t.cpp

@@ -1,15 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create an object_t value
-    json::object_t value = { {"one", 1}, {"two", 2} };
-
-    // create a JSON object from the value
-    json j(value);
-
-    // serialize the JSON object
-    std::cout << j << '\n';
-}

doc/examples/basic_json__object_t.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/DgtHcz5L6JphTOGJ"><b>online</b></a>

doc/examples/basic_json__object_t.output

@@ -1 +0,0 @@
-{"one":1,"two":2}

doc/examples/basic_json__string_t.cpp

@@ -1,15 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create an string_t value
-    json::string_t value = "The quick brown fox jumps over the lazy doc";
-
-    // create a JSON string from the value
-    json j(value);
-
-    // serialize the JSON array
-    std::cout << j << '\n';
-}

doc/examples/basic_json__string_t.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/cwNYP1q2mT8CFLTk"><b>online</b></a>

doc/examples/basic_json__string_t.output

@@ -1 +0,0 @@
-"The quick brown fox jumps over the lazy doc"

doc/examples/basic_json__string_t_value_type.cpp

@@ -1,12 +0,0 @@
-#include <json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create a JSON string directly from a string literal
-    json j("The quick brown fox jumps over the lazy doc");
-
-    // serialize the JSON array
-    std::cout << j << '\n';
-}

doc/examples/basic_json__string_t_value_type.link

@@ -1 +0,0 @@
-<a target="_blank" href="http://melpon.org/wandbox/permlink/AtV4zVErfLwkileg"><b>online</b></a>

doc/examples/basic_json__string_t_value_type.output

@@ -1 +0,0 @@
-"The quick brown fox jumps over the lazy doc"

src/json.hpp

@@ -1907,31 +1907,70 @@ class basic_json
     }
 
     /*!
-    @brief forwards the parameter to json_serializer<U>::to_json method (U = uncvref_t<T>)
+    @brief create a JSON value
 
-    this constructor is chosen if:
+    This is a "catch all" constructor for all compatible JSON types; that is,
-    - T is not derived from std::istream
+    types for which a `to_json()` method exsits. The constructor forwards the
-    - T is not @ref basic_json (to avoid hijacking copy/move constructors)
+    parameter @a val to that method (to `json_serializer<U>::to_json` method
-    - T is not a @ref basic_json nested type (@ref json_pointer, @ref iterator, etc ...)
+    with `U = uncvref_t<CompatibleType>`, to be exact).
-    - @ref json_serializer<U> has a to_json(basic_json_t&, T&&) method
+
+    Template type @a CompatibleType includes, but is not limited to, the
+    following types:
+    - **arrays**: @ref array_t and all kinds of compatible containers such as
+      `std::vector`, `std::deque`, `std::list`, `std::forward_list`,
+      `std::array`, `std::set`, `std::unordered_set`, `std::multiset`, and
+      `unordered_multiset` with a `value_type` from which a @ref basic_json
+      value can be constructed.
+    - **objects**: @ref object_t and all kinds of compatible associative
+      containers such as `std::map`, `std::unordered_map`, `std::multimap`,
+      and `std::unordered_multimap` with a `key_type` compatible to
+      @ref string_t and a `value_type` from which a @ref basic_json value can
+      be constructed.
+    - **strings**: @ref string_t, string literals, and all compatible string
+      containers can be used.
+    - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
+      @ref number_float_t, and all convertible number types such as `int`,
+      `size_t`, `int64_t`, `float` or `double` can be used.
+    - **boolean**: @ref boolean_t / `bool` can be used.
+
+    See the examples below.
+
+    @tparam CompatibleType a type such that:
+    - @a CompatibleType is not derived from `std::istream`,
+    - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
+         constructors),
+    - @a CompatibleType is not a @ref basic_json nested type (e.g.,
+         @ref json_pointer, @ref iterator, etc ...)
+    - @ref @ref json_serializer<U> has a
+         `to_json(basic_json_t&, CompatibleType&&)` method
+
+    @tparam U = `uncvref_t<CompatibleType>`
 
     @param[in] val the value to be forwarded
 
-    @throw what json_serializer<U>::to_json throws
+    @complexity Usually linear in the size of the passed @a val, also
+                depending on the implementation of the called `to_json()`
+                method.
+
+    @throw what `json_serializer<U>::to_json()` throws
+
+    @liveexample{The following code shows the constructor with several
+    compatible types.,basic_json__CompatibleType}
 
     @since version 2.1.0
     */
-    template<typename T, typename U = detail::uncvref_t<T>,
+    template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
              detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
                                  not std::is_same<U, basic_json_t>::value and
                                  not detail::is_basic_json_nested_type<
                                      basic_json_t, U>::value and
                                  detail::has_to_json<basic_json, U>::value,
                                  int> = 0>
-    basic_json(T && val) noexcept(noexcept(JSONSerializer<U>::to_json(
+    basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
-            std::declval<basic_json_t&>(), std::forward<T>(val))))
+                std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
     {
-        JSONSerializer<U>::to_json(*this, std::forward<T>(val));
+        JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
+        assert_invariant();
     }
 
     /*!
@@ -7950,7 +7989,7 @@ class basic_json
     @complexity Constant.
 
     @liveexample{The following code exemplifies `type_name()` for all JSON
-    types.,typename}
+    types.,type_name}
 
     @since version 1.0.0
     */
@@ -7975,7 +8014,6 @@ class basic_json
                     return "number";
             }
         }
-
     }
 
   private:

src/json.hpp.re2c

@@ -1907,31 +1907,70 @@ class basic_json
     }
 
     /*!
-    @brief forwards the parameter to json_serializer<U>::to_json method (U = uncvref_t<T>)
+    @brief create a JSON value
 
-    this constructor is chosen if:
+    This is a "catch all" constructor for all compatible JSON types; that is,
-    - T is not derived from std::istream
+    types for which a `to_json()` method exsits. The constructor forwards the
-    - T is not @ref basic_json (to avoid hijacking copy/move constructors)
+    parameter @a val to that method (to `json_serializer<U>::to_json` method
-    - T is not a @ref basic_json nested type (@ref json_pointer, @ref iterator, etc ...)
+    with `U = uncvref_t<CompatibleType>`, to be exact).
-    - @ref json_serializer<U> has a to_json(basic_json_t&, T&&) method
+
+    Template type @a CompatibleType includes, but is not limited to, the
+    following types:
+    - **arrays**: @ref array_t and all kinds of compatible containers such as
+      `std::vector`, `std::deque`, `std::list`, `std::forward_list`,
+      `std::array`, `std::set`, `std::unordered_set`, `std::multiset`, and
+      `unordered_multiset` with a `value_type` from which a @ref basic_json
+      value can be constructed.
+    - **objects**: @ref object_t and all kinds of compatible associative
+      containers such as `std::map`, `std::unordered_map`, `std::multimap`,
+      and `std::unordered_multimap` with a `key_type` compatible to
+      @ref string_t and a `value_type` from which a @ref basic_json value can
+      be constructed.
+    - **strings**: @ref string_t, string literals, and all compatible string
+      containers can be used.
+    - **numbers**: @ref number_integer_t, @ref number_unsigned_t,
+      @ref number_float_t, and all convertible number types such as `int`,
+      `size_t`, `int64_t`, `float` or `double` can be used.
+    - **boolean**: @ref boolean_t / `bool` can be used.
+
+    See the examples below.
+
+    @tparam CompatibleType a type such that:
+    - @a CompatibleType is not derived from `std::istream`,
+    - @a CompatibleType is not @ref basic_json (to avoid hijacking copy/move
+         constructors),
+    - @a CompatibleType is not a @ref basic_json nested type (e.g.,
+         @ref json_pointer, @ref iterator, etc ...)
+    - @ref @ref json_serializer<U> has a
+         `to_json(basic_json_t&, CompatibleType&&)` method
+
+    @tparam U = `uncvref_t<CompatibleType>`
 
     @param[in] val the value to be forwarded
 
-    @throw what json_serializer<U>::to_json throws
+    @complexity Usually linear in the size of the passed @a val, also
+                depending on the implementation of the called `to_json()`
+                method.
+
+    @throw what `json_serializer<U>::to_json()` throws
+
+    @liveexample{The following code shows the constructor with several
+    compatible types.,basic_json__CompatibleType}
 
     @since version 2.1.0
     */
-    template<typename T, typename U = detail::uncvref_t<T>,
+    template<typename CompatibleType, typename U = detail::uncvref_t<CompatibleType>,
              detail::enable_if_t<not std::is_base_of<std::istream, U>::value and
                                  not std::is_same<U, basic_json_t>::value and
                                  not detail::is_basic_json_nested_type<
                                      basic_json_t, U>::value and
                                  detail::has_to_json<basic_json, U>::value,
                                  int> = 0>
-    basic_json(T && val) noexcept(noexcept(JSONSerializer<U>::to_json(
+    basic_json(CompatibleType && val) noexcept(noexcept(JSONSerializer<U>::to_json(
-            std::declval<basic_json_t&>(), std::forward<T>(val))))
+                std::declval<basic_json_t&>(), std::forward<CompatibleType>(val))))
     {
-        JSONSerializer<U>::to_json(*this, std::forward<T>(val));
+        JSONSerializer<U>::to_json(*this, std::forward<CompatibleType>(val));
+        assert_invariant();
     }
 
     /*!
@@ -7950,7 +7989,7 @@ class basic_json
     @complexity Constant.
 
     @liveexample{The following code exemplifies `type_name()` for all JSON
-    types.,typename}
+    types.,type_name}
 
     @since version 1.0.0
     */
@@ -7975,7 +8014,6 @@ class basic_json
                     return "number";
             }
         }
-
     }
 
   private: