📝 improved documentation

doc/Doxyfile

@@ -1,12 +1,12 @@
-# Doxyfile 1.8.9.1
+# Doxyfile 1.8.14
 
 #---------------------------------------------------------------------------
 # Project related configuration options
 #---------------------------------------------------------------------------
 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,23 +27,25 @@ 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
 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

@@ -1 +1 @@
-<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>

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

@@ -1 +1 @@
-<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>

doc/examples/dump.output

@@ -1,3 +1,4 @@
+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

@@ -0,0 +1,20 @@
+#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

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

doc/examples/exception.output

@@ -0,0 +1,2 @@
+message: [json.exception.out_of_range.403] key 'non-existing' not found
+exception id: 403

doc/examples/invalid_iterator.cpp

@@ -0,0 +1,21 @@
+#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

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

doc/examples/invalid_iterator.output

@@ -0,0 +1,2 @@
+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

@@ -1 +1 @@
-<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>

doc/examples/operator__value_t.output

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

doc/examples/other_error.cpp

@@ -0,0 +1,29 @@
+#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

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

doc/examples/other_error.output

@@ -0,0 +1,2 @@
+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

@@ -0,0 +1,20 @@
+#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

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

doc/examples/out_of_range.output

@@ -0,0 +1,2 @@
+message: [json.exception.out_of_range.401] array index 4 is out of range
+exception id: 401

doc/examples/parse_error.cpp

@@ -0,0 +1,20 @@
+#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

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/74sQTauZsM8tWyuM"><b>online</b></a>

doc/examples/parse_error.output

@@ -0,0 +1,3 @@
+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