📝 improved documentation

doc/Doxyfile

-# Doxyfile 1.8.9.1
+# Doxyfile 1.8.14
 
 #---------------------------------------------------------------------------
 # Project related configuration options
@@ -6,7 +6,7 @@
 DOXYFILE_ENCODING      = UTF-8
 PROJECT_NAME           = "JSON for Modern C++"
 PROJECT_NUMBER         = 2.1.1
-PROJECT_BRIEF          = 
+PROJECT_BRIEF          =
 PROJECT_LOGO           =
 OUTPUT_DIRECTORY       = .
 CREATE_SUBDIRS         = NO
@@ -27,10 +27,10 @@ MULTILINE_CPP_IS_BRIEF = NO
 INHERIT_DOCS           = YES
 SEPARATE_MEMBER_PAGES  = YES
 TAB_SIZE               = 4
-ALIASES                = "complexity=@par Complexity\n"
-ALIASES                += liveexample{2}="@par Example\n \1 \n @includelineno \2.cpp \n Output (play with this example @htmlinclude \2.link):\n @verbinclude \2.output \n The example code above can be translated with @verbatim g++ -std=c++11 -Isrc doc/examples/\2.cpp -o \2 @endverbatim"
-ALIASES                += requirement="@par Requirements\n"
-ALIASES                += exceptionsafety="@par Exception safety\n"
+ALIASES                = "complexity=@par Complexity\n" \
+                         "liveexample{2}=@par Example\n \1 \n @includelineno \2.cpp \n Output (play with this example @htmlinclude \2.link):\n @verbinclude \2.output \n The <a href= https://github.com/nlohmann/json/blob/develop/doc/examples/\2.cpp>example code</a> above can be translated with @verbatim g++ -std=c++11 -Isrc doc/examples/\2.cpp -o \2 @endverbatim" \
+                         "requirement=@par Requirements\n" \
+                         "exceptionsafety=@par Exception safety\n"
 TCL_SUBST              =
 OPTIMIZE_OUTPUT_FOR_C  = NO
 OPTIMIZE_OUTPUT_JAVA   = NO
@@ -38,12 +38,14 @@ OPTIMIZE_FOR_FORTRAN   = NO
 OPTIMIZE_OUTPUT_VHDL   = NO
 EXTENSION_MAPPING      =
 MARKDOWN_SUPPORT       = YES
+TOC_INCLUDE_HEADINGS   = 0
 AUTOLINK_SUPPORT       = NO
 BUILTIN_STL_SUPPORT    = YES
 CPP_CLI_SUPPORT        = NO
 SIP_SUPPORT            = NO
 IDL_PROPERTY_SUPPORT   = YES
 DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
 SUBGROUPING            = YES
 INLINE_GROUPED_CLASSES = NO
 INLINE_SIMPLE_STRUCTS  = NO
@@ -97,12 +99,14 @@ WARNINGS               = YES
 WARN_IF_UNDOCUMENTED   = YES
 WARN_IF_DOC_ERROR      = YES
 WARN_NO_PARAMDOC       = YES
+WARN_AS_ERROR          = NO
 WARN_FORMAT            = "$file:$line: $text"
 WARN_LOGFILE           =
 #---------------------------------------------------------------------------
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
-INPUT                  = ../src/json.hpp index.md
+INPUT                  = ../src/json.hpp \
+                         index.md
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = NO
@@ -131,6 +135,8 @@ REFERENCES_LINK_SOURCE = NO
 SOURCE_TOOLTIPS        = YES
 USE_HTAGS              = NO
 VERBATIM_HEADERS       = NO
+CLANG_ASSISTED_PARSING = YES
+CLANG_OPTIONS          = -std=c++11
 #---------------------------------------------------------------------------
 # Configuration options related to the alphabetical class index
 #---------------------------------------------------------------------------
@@ -152,13 +158,14 @@ HTML_COLORSTYLE_HUE    = 220
 HTML_COLORSTYLE_SAT    = 100
 HTML_COLORSTYLE_GAMMA  = 80
 HTML_TIMESTAMP         = YES
+HTML_DYNAMIC_MENUS     = YES
 HTML_DYNAMIC_SECTIONS  = YES
 HTML_INDEX_NUM_ENTRIES = 100
 GENERATE_DOCSET        = YES
 DOCSET_FEEDNAME        = "Doxygen generated docs"
 DOCSET_BUNDLE_ID       = me.nlohmann.json
 DOCSET_PUBLISHER_ID    = me.nlohmann
-DOCSET_PUBLISHER_NAME  = Niels Lohmann
+DOCSET_PUBLISHER_NAME  = NielsLohmann
 GENERATE_HTMLHELP      = NO
 CHM_FILE               =
 HHC_LOCATION           =
@@ -215,6 +222,7 @@ LATEX_BATCHMODE        = NO
 LATEX_HIDE_INDICES     = NO
 LATEX_SOURCE_CODE      = NO
 LATEX_BIB_STYLE        = plain
+LATEX_TIMESTAMP        = NO
 #---------------------------------------------------------------------------
 # Configuration options related to the RTF output
 #---------------------------------------------------------------------------
@@ -308,6 +316,7 @@ DOTFILE_DIRS           =
 MSCFILE_DIRS           =
 DIAFILE_DIRS           =
 PLANTUML_JAR_PATH      =
+PLANTUML_CFG_FILE      =
 PLANTUML_INCLUDE_PATH  =
 DOT_GRAPH_MAX_NODES    = 50
 MAX_DOT_GRAPH_DEPTH    = 0

doc/examples/basic_json__CompatibleType.cpp

@@ -5,6 +5,7 @@
 #include <set>
 #include <unordered_map>
 #include <unordered_set>
+#include <valarray>
 #include "json.hpp"
 
 using json = nlohmann::json;
@@ -67,6 +68,10 @@ int main()
     std::vector<int> c_vector {1, 2, 3, 4};
     json j_vec(c_vector);
 
+    // create an array from std::valarray
+    std::valarray<short> c_valarray {10, 9, 8, 7};
+    json j_valarray(c_valarray);
+
     // create an array from std::deque
     std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
     json j_deque(c_deque);
@@ -102,6 +107,7 @@ int main()
     // serialize the JSON arrays
     std::cout << j_array_t << '\n';
     std::cout << j_vec << '\n';
+    std::cout << j_valarray << '\n';
     std::cout << j_deque << '\n';
     std::cout << j_list << '\n';
     std::cout << j_flist << '\n';

doc/examples/basic_json__CompatibleType.link

-<a target="_blank" href="https://wandbox.org/permlink/chmc1rH7aNZTIVSp"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/s7Ecy7hDYSmUWHyx"><b>online</b></a>
\ No newline at end of file

doc/examples/basic_json__CompatibleType.output

@@ -6,6 +6,7 @@
 
 ["one","two",3,4.5,false]
 [1,2,3,4]
+[10,9,8,7]
 [1.2,2.3,3.4,5.6]
 [true,true,false,true]
 [12345678909876,23456789098765,34567890987654,45678909876543]

doc/examples/dump.cpp

@@ -8,16 +8,24 @@ int main()
     // create JSON values
     json j_object = {{"one", 1}, {"two", 2}};
     json j_array = {1, 2, 4, 8, 16};
+    json j_string = "Hellö 😀!";
 
     // call dump()
-    std::cout << j_object.dump() << "\n\n";
-    std::cout << j_object.dump(-1) << "\n\n";
-    std::cout << j_object.dump(0) << "\n\n";
-    std::cout << j_object.dump(4) << "\n\n";
-    std::cout << j_object.dump(1, '\t') << "\n\n";
-    std::cout << j_array.dump() << "\n\n";
-    std::cout << j_array.dump(-1) << "\n\n";
-    std::cout << j_array.dump(0) << "\n\n";
-    std::cout << j_array.dump(4) << "\n\n";
-    std::cout << j_array.dump(1, '\t') << "\n\n";
+    std::cout << "objects:" << '\n'
+              << j_object.dump() << "\n\n"
+              << j_object.dump(-1) << "\n\n"
+              << j_object.dump(0) << "\n\n"
+              << j_object.dump(4) << "\n\n"
+              << j_object.dump(1, '\t') << "\n\n";
+
+    std::cout << "arrays:" << '\n'
+              << j_array.dump() << "\n\n"
+              << j_array.dump(-1) << "\n\n"
+              << j_array.dump(0) << "\n\n"
+              << j_array.dump(4) << "\n\n"
+              << j_array.dump(1, '\t') << "\n\n";
+
+    std::cout << "strings:" << '\n'
+              << j_string.dump() << '\n'
+              << j_string.dump(-1, ' ', true) << '\n';
 }

doc/examples/dump.link

-<a target="_blank" href="https://wandbox.org/permlink/0rB2LKUCjPlU90XK"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/UnV6etCOZZRZpYyB"><b>online</b></a>
\ No newline at end of file

doc/examples/dump.output

+objects:
 {"one":1,"two":2}
 
 {"one":1,"two":2}
@@ -17,6 +18,7 @@
 	"two": 2
 }
 
+arrays:
 [1,2,4,8,16]
 
 [1,2,4,8,16]
@@ -45,3 +47,6 @@
 	16
 ]
 
+strings:
+"Hellö 😀!"
+"Hell\u00f6 \ud83d\ude00!"

doc/examples/exception.cpp

+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // calling at() for a non-existing key
+        json j = {{"foo", "bar"}};
+        json k = j.at("non-existing");
+    }
+    catch (json::exception& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/exception.link

+<a target="_blank" href="https://wandbox.org/permlink/yHjdsKGTYSRFNzD7"><b>online</b></a>
\ No newline at end of file

doc/examples/exception.output

+message: [json.exception.out_of_range.403] key 'non-existing' not found
+exception id: 403

doc/examples/invalid_iterator.cpp

+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // calling iterator::key() on non-object iterator
+        json j = "string";
+        json::iterator it = j.begin();
+        auto k = it.key();
+    }
+    catch (json::invalid_iterator& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/invalid_iterator.link

+<a target="_blank" href="https://wandbox.org/permlink/PW9dQWFyNaUxzEVY"><b>online</b></a>
\ No newline at end of file

doc/examples/invalid_iterator.output

+message: [json.exception.invalid_iterator.207] cannot use key() for non-object iterators
+exception id: 207

doc/examples/operator__value_t.cpp

@@ -8,7 +8,8 @@ int main()
     // create JSON values
     json j_null;
     json j_boolean = true;
-    json j_number_integer = 17;
+    json j_number_integer = -17;
+    json j_number_unsigned = 42u;
     json j_number_float = 23.42;
     json j_object = {{"one", 1}, {"two", 2}};
     json j_array = {1, 2, 4, 8, 16};
@@ -18,6 +19,7 @@ int main()
     json::value_t t_null = j_null;
     json::value_t t_boolean = j_boolean;
     json::value_t t_number_integer = j_number_integer;
+    json::value_t t_number_unsigned = j_number_unsigned;
     json::value_t t_number_float = j_number_float;
     json::value_t t_object = j_object;
     json::value_t t_array = j_array;
@@ -28,6 +30,7 @@ int main()
     std::cout << (t_null == json::value_t::null) << '\n';
     std::cout << (t_boolean == json::value_t::boolean) << '\n';
     std::cout << (t_number_integer == json::value_t::number_integer) << '\n';
+    std::cout << (t_number_unsigned == json::value_t::number_unsigned) << '\n';
     std::cout << (t_number_float == json::value_t::number_float) << '\n';
     std::cout << (t_object == json::value_t::object) << '\n';
     std::cout << (t_array == json::value_t::array) << '\n';

doc/examples/operator__value_t.link

-<a target="_blank" href="https://wandbox.org/permlink/daNU6Fj8JuV07nBn"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/aUlH5rQeIA002APo"><b>online</b></a>
\ No newline at end of file

doc/examples/operator__value_t.output

@@ -5,3 +5,4 @@ true
 true
 true
 true
+true

doc/examples/other_error.cpp

+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // executing a failing JSON Patch operation
+        json value = R"({
+            "best_biscuit": {
+                "name": "Oreo"
+            }
+        })"_json;
+        json patch = R"([{
+            "op": "test",
+            "path": "/best_biscuit/name",
+            "value": "Choco Leibniz"
+        }])"_json;
+        value.patch(patch);
+    }
+    catch (json::other_error& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/other_error.link

+<a target="_blank" href="https://wandbox.org/permlink/UcADWdVMPA9GZbRP"><b>online</b></a>
\ No newline at end of file

doc/examples/other_error.output

+message: [json.exception.other_error.501] unsuccessful: {"op":"test","path":"/best_biscuit/name","value":"Choco Leibniz"}
+exception id: 501

doc/examples/out_of_range.cpp

+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // calling at() for an invalid index
+        json j = {1, 2, 3, 4};
+        j.at(4) = 10;
+    }
+    catch (json::out_of_range& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/out_of_range.link

+<a target="_blank" href="https://wandbox.org/permlink/VrsKXxX3CuHeqKq7"><b>online</b></a>
\ No newline at end of file

doc/examples/out_of_range.output

+message: [json.exception.out_of_range.401] array index 4 is out of range
+exception id: 401

doc/examples/parse_error.cpp

+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // parsing input with a syntax error
+        json::parse("[1,2,3,]");
+    }
+    catch (json::parse_error& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << '\n'
+                  << "byte position of error: " << e.byte << std::endl;
+    }
+}

doc/examples/parse_error.link

+<a target="_blank" href="https://wandbox.org/permlink/74sQTauZsM8tWyuM"><b>online</b></a>
\ No newline at end of file

doc/examples/parse_error.output

+message: [json.exception.parse_error.101] parse error at 8: syntax error - unexpected ']'; expected '[', '{', or a literal
+exception id: 101
+byte position of error: 8

doc/examples/type.cpp

@@ -8,7 +8,8 @@ int main()
     // create JSON values
     json j_null;
     json j_boolean = true;
-    json j_number_integer = 17;
+    json j_number_integer = -17;
+    json j_number_unsigned = 42u;
     json j_number_float = 23.42;
     json j_object = {{"one", 1}, {"two", 2}};
     json j_array = {1, 2, 4, 8, 16};
@@ -19,6 +20,7 @@ int main()
     std::cout << (j_null.type() == json::value_t::null) << '\n';
     std::cout << (j_boolean.type() == json::value_t::boolean) << '\n';
     std::cout << (j_number_integer.type() == json::value_t::number_integer) << '\n';
+    std::cout << (j_number_unsigned.type() == json::value_t::number_unsigned) << '\n';
     std::cout << (j_number_float.type() == json::value_t::number_float) << '\n';
     std::cout << (j_object.type() == json::value_t::object) << '\n';
     std::cout << (j_array.type() == json::value_t::array) << '\n';

doc/examples/type.link

-<a target="_blank" href="https://wandbox.org/permlink/zlWezYhiRTnLzrSj"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/LqgeAtdIMLSpGzkE"><b>online</b></a>
\ No newline at end of file

doc/examples/type.output

@@ -5,3 +5,4 @@ true
 true
 true
 true
+true

doc/examples/type_error.cpp

+#include <iostream>
+#include "json.hpp"
+
+using json = nlohmann::json;
+
+int main()
+{
+    try
+    {
+        // calling push_back() on a string value
+        json j = "string";
+        j.push_back("another string");
+    }
+    catch (json::type_error& e)
+    {
+        // output exception information
+        std::cout << "message: " << e.what() << '\n'
+                  << "exception id: " << e.id << std::endl;
+    }
+}

doc/examples/type_error.link

+<a target="_blank" href="https://wandbox.org/permlink/HVfmgdIq73ztfCHY"><b>online</b></a>
\ No newline at end of file

doc/examples/type_error.output

+message: [json.exception.type_error.308] cannot use push_back() with string
+exception id: 308

doc/examples/type_name.cpp

@@ -8,18 +8,20 @@ int main()
     // create JSON values
     json j_null;
     json j_boolean = true;
-    json j_number_integer = 17;
+    json j_number_integer = -17;
+    json j_number_unsigned = 42u;
     json j_number_float = 23.42;
     json j_object = {{"one", 1}, {"two", 2}};
     json j_array = {1, 2, 4, 8, 16};
     json j_string = "Hello, world";
 
     // call type_name()
-    std::cout << j_null.type_name() << '\n';
-    std::cout << j_boolean.type_name() << '\n';
-    std::cout << j_number_integer.type_name() << '\n';
-    std::cout << j_number_float.type_name() << '\n';
-    std::cout << j_object.type_name() << '\n';
-    std::cout << j_array.type_name() << '\n';
-    std::cout << j_string.type_name() << '\n';
+    std::cout << j_null << " is a " << j_null.type_name() << '\n';
+    std::cout << j_boolean << " is a " << j_boolean.type_name() << '\n';
+    std::cout << j_number_integer << " is a " << j_number_integer.type_name() << '\n';
+    std::cout << j_number_unsigned << " is a " << j_number_unsigned.type_name() << '\n';
+    std::cout << j_number_float << " is a " << j_number_float.type_name() << '\n';
+    std::cout << j_object << " is an " << j_object.type_name() << '\n';
+    std::cout << j_array << " is an " << j_array.type_name() << '\n';
+    std::cout << j_string << " is a " << j_string.type_name() << '\n';
 }

doc/examples/type_name.link

-<a target="_blank" href="https://wandbox.org/permlink/dKXdftLJYVnkE3Vg"><b>online</b></a>
+<a target="_blank" href="https://wandbox.org/permlink/UqDa9aT5fHaK6dPQ"><b>online</b></a>
\ No newline at end of file

doc/examples/type_name.output

-null
-boolean
-number
-number
-object
-array
-string
+null is a null
+true is a boolean
+-17 is a number
+42 is a number
+23.42 is a number
+{"one":1,"two":2} is an object
+[1,2,4,8,16] is an array
+"Hello, world" is a string

test/src/unit-concepts.cpp

@@ -94,6 +94,7 @@ TEST_CASE("concepts")
 
         SECTION("MoveConstructible")
         {
+            CHECK(std::is_move_constructible<json>::value);
             CHECK(std::is_nothrow_move_constructible<json>::value);
         }
 

test/src/unit-constructor1.cpp

@@ -1181,12 +1181,33 @@ TEST_CASE("constructors")
 
     SECTION("create an array of n copies of a given value")
     {
-        json v = {1, "foo", 34.23, {1, 2, 3}, {{"A", 1}, {"B", 2u}}};
-        json arr(3, v);
-        CHECK(arr.size() == 3);
-        for (auto& x : arr)
+        SECTION("cnt = 0")
         {
-            CHECK(x == v);
+            json v = {1, "foo", 34.23, {1, 2, 3}, {{"A", 1}, {"B", 2u}}};
+            json arr(0, v);
+            CHECK(arr.size() == 0);
+        }
+
+        SECTION("cnt = 1")
+        {
+            json v = {1, "foo", 34.23, {1, 2, 3}, {{"A", 1}, {"B", 2u}}};
+            json arr(1, v);
+            CHECK(arr.size() == 1);
+            for (auto& x : arr)
+            {
+                CHECK(x == v);
+            }
+        }
+
+        SECTION("cnt = 3")
+        {
+            json v = {1, "foo", 34.23, {1, 2, 3}, {{"A", 1}, {"B", 2u}}};
+            json arr(3, v);
+            CHECK(arr.size() == 3);
+            for (auto& x : arr)
+            {
+                CHECK(x == v);
+            }
         }
     }
 

test/src/unit-modifiers.cpp

@@ -38,17 +38,21 @@ TEST_CASE("modifiers")
         SECTION("boolean")
         {
             json j = true;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::boolean));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("string")
         {
             json j = "hello world";
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::string));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("array")
@@ -56,19 +60,23 @@ TEST_CASE("modifiers")
             SECTION("empty array")
             {
                 json j = json::array();
+                json k = j;
 
                 j.clear();
                 CHECK(j.empty());
                 CHECK(j == json(json::value_t::array));
+                CHECK(j == json(k.type()));
             }
 
             SECTION("filled array")
             {
                 json j = {1, 2, 3};
+                json k = j;
 
                 j.clear();
                 CHECK(j.empty());
                 CHECK(j == json(json::value_t::array));
+                CHECK(j == json(k.type()));
             }
         }
 
@@ -77,52 +85,64 @@ TEST_CASE("modifiers")
             SECTION("empty object")
             {
                 json j = json::object();
+                json k = j;
 
                 j.clear();
                 CHECK(j.empty());
                 CHECK(j == json(json::value_t::object));
+                CHECK(j == json(k.type()));
             }
 
             SECTION("filled object")
             {
                 json j = {{"one", 1}, {"two", 2}, {"three", 3}};
+                json k = j;
 
                 j.clear();
                 CHECK(j.empty());
                 CHECK(j == json(json::value_t::object));
+                CHECK(j == json(k.type()));
             }
         }
 
         SECTION("number (integer)")
         {
             json j = 23;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::number_integer));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("number (unsigned)")
         {
             json j = 23u;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::number_integer));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("number (float)")
         {
             json j = 23.42;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::number_float));
+            CHECK(j == json(k.type()));
         }
 
         SECTION("null")
         {
             json j = nullptr;
+            json k = j;
 
             j.clear();
             CHECK(j == json(json::value_t::null));
+            CHECK(j == json(k.type()));
         }
     }
 

test/src/unit-regression.cpp

@@ -1209,9 +1209,9 @@ TEST_CASE("regression tests")
     {
         SECTION("original example")
         {
-        std::valarray<double> v;
-        nlohmann::json j;
-        j["test"] = v;
+            std::valarray<double> v;
+            nlohmann::json j;
+            j["test"] = v;
         }
 
         SECTION("full example")
@@ -1230,7 +1230,7 @@ TEST_CASE("regression tests")
 
             CHECK_THROWS_AS(json().get<std::valarray<double>>(), json::type_error&);
             CHECK_THROWS_WITH(json().get<std::valarray<double>>(),
-                "[json.exception.type_error.302] type must be array, but is null");
+                              "[json.exception.type_error.302] type must be array, but is null");
         }
     }
 }