more documentation

In this commit, also the semantics for values skipped via the parser
callback has changed. Now, the top-level value is returned as “null”
instead of “discarded”.

doc/Doxyfile

@@ -163,7 +163,7 @@ CHM_FILE               =
 HHC_LOCATION           =
 GENERATE_CHI           = NO
 CHM_INDEX_ENCODING     =
-BINARY_TOC             = YES
+BINARY_TOC             = NO
 TOC_EXPAND             = NO
 GENERATE_QHP           = NO
 QCH_FILE               =
@@ -176,7 +176,7 @@ QHG_LOCATION           =
 GENERATE_ECLIPSEHELP   = NO
 ECLIPSE_DOC_ID         = org.doxygen.Project
 DISABLE_INDEX          = NO
-GENERATE_TREEVIEW      = YES
+GENERATE_TREEVIEW      = NO
 ENUM_VALUES_PER_LINE   = 4
 TREEVIEW_WIDTH         = 250
 EXT_LINKS_IN_WINDOW    = NO

doc/Makefile

@@ -56,8 +56,6 @@ docset: create_output
 	cp Doxyfile Doxyfile_docset
 	gsed -i 's/DISABLE_INDEX          = NO/DISABLE_INDEX          = YES/' Doxyfile_docset
 	gsed -i 's/SEARCHENGINE           = YES/SEARCHENGINE           = NO/' Doxyfile_docset
-	gsed -i 's/GENERATE_TREEVIEW      = YES/GENERATE_TREEVIEW      = NO/' Doxyfile_docset
-	gsed -i 's/BINARY_TOC             = YES/BINARY_TOC             = NO/' Doxyfile_docset
 	gsed -i 's@HTML_EXTRA_STYLESHEET  = css/mylayout.css@HTML_EXTRA_STYLESHEET  = css/mylayout_docset.css@' Doxyfile_docset
 	rm -fr html *.docset
 	doxygen Doxyfile_docset

doc/examples/at__object_t_key_type.cpp

@@ -0,0 +1,33 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON object
+    json object =
+    {
+        {"the good", "il buono"},
+        {"the bad", "il cativo"},
+        {"the ugly", "il brutto"}
+    };
+
+    // output element with key "the ugly"
+    std::cout << object.at("the ugly") << '\n';
+
+    // change element with key "the bad"
+    object.at("the bad") = "il cattivo";
+
+    // output changed array
+    std::cout << object << '\n';
+
+    // try to write at a nonexisting key
+    try
+    {
+        object.at("the fast") = "il rapido";
+    }
+    catch (std::out_of_range)
+    {
+        std::cout << "out of range" << '\n';
+    }
+}

doc/examples/at__object_t_key_type.output

@@ -0,0 +1,3 @@
+"il brutto"
+{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
+out of range

doc/examples/at__object_t_key_type_const.cpp

@@ -0,0 +1,27 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON object
+    json object =
+    {
+        {"the good", "il buono"},
+        {"the bad", "il cativo"},
+        {"the ugly", "il brutto"}
+    };
+
+    // output element with key "the ugly"
+    std::cout << object.at("the ugly") << '\n';
+
+    // try to read from a nonexisting key
+    try
+    {
+        std::cout << object.at("the fast") << '\n';
+    }
+    catch (std::out_of_range)
+    {
+        std::cout << "out of range" << '\n';
+    }
+}

doc/examples/at__object_t_key_type_const.output

@@ -0,0 +1,2 @@
+"il brutto"
+out of range

doc/examples/at__size_type.cpp

@@ -0,0 +1,28 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON array
+    json array = {"first", "2nd", "third", "fourth"};
+
+    // output element at index 2 (third element)
+    std::cout << array.at(2) << '\n';
+
+    // change element at index 1 (second element) to "second"
+    array.at(1) = "second";
+
+    // output changed array
+    std::cout << array << '\n';
+
+    // try to write beyond the array limit
+    try
+    {
+        array.at(5) = "sixth";
+    }
+    catch (std::out_of_range)
+    {
+        std::cout << "out of range" << '\n';
+    }
+}

doc/examples/at__size_type.output

@@ -0,0 +1,3 @@
+"third"
+["first","second","third","fourth"]
+out of range

doc/examples/at__size_type_const.cpp

@@ -0,0 +1,22 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON array
+    json array = {"first", "2nd", "third", "fourth"};
+
+    // output element at index 2 (third element)
+    std::cout << array.at(2) << '\n';
+
+    // try to read beyond the array limit
+    try
+    {
+        std::cout << array.at(5) << '\n';
+    }
+    catch (std::out_of_range)
+    {
+        std::cout << "out of range" << '\n';
+    }
+}

doc/examples/at__size_type_const.output

@@ -0,0 +1,2 @@
+"third"
+out of range

doc/examples/operatorarray__size_type.cpp

@@ -0,0 +1,24 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create a JSON array
+    json array = {1, 2, 3, 4, 5};
+
+    // output element at index 3 (fourth element)
+    std::cout << array[3] << '\n';
+
+    // change last element to 6
+    array[array.size() - 1] = 6;
+
+    // output changed array
+    std::cout << array << '\n';
+
+    // write beyond array limit
+    array[10] = 11;
+
+    // output changed array
+    std::cout << array << '\n';
+}

doc/examples/operatorarray__size_type.output

@@ -0,0 +1,3 @@
+4
+[1,2,3,4,6]
+[1,2,3,4,6,null,null,null,null,null,11]

doc/examples/operatorarray__size_type_const.cpp

@@ -0,0 +1,12 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create JSON array
+    json array = {"first", "2nd", "third", "fourth"};
+
+    // output element at index 2 (third element)
+    std::cout << array.at(2) << '\n';
+}

doc/examples/operatorarray__size_type_const.output

@@ -0,0 +1 @@
+"third"

doc/examples/parse__istream__parser_callback_t.cpp

@@ -0,0 +1,55 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // a JSON text
+    auto text = R"(
+    {
+        "Image": {
+            "Width":  800,
+            "Height": 600,
+            "Title":  "View from 15th Floor",
+            "Thumbnail": {
+                "Url":    "http://www.example.com/image/481989943",
+                "Height": 125,
+                "Width":  100
+            },
+            "Animated" : false,
+            "IDs": [116, 943, 234, 38793]
+        }
+    }
+    )";
+
+    // fill a stream with JSON text
+    std::stringstream ss;
+    ss << text;
+
+    // parse and serialize JSON
+    json j_complete = json::parse(ss);
+    std::cout << std::setw(4) << j_complete << "\n\n";
+
+
+    // define parser callback
+    json::parser_callback_t cb = [](int depth, json::parse_event_t event, json & parsed)
+    {
+        // skip object elements with key "Thumbnail"
+        if (event == json::parse_event_t::key and parsed == json("Thumbnail"))
+        {
+            return false;
+        }
+        else
+        {
+            return true;
+        }
+    };
+
+    // fill a stream with JSON text
+    ss.clear();
+    ss << text;
+
+    // parse (with callback) and serialize JSON
+    json j_filtered = json::parse(ss, cb);
+    std::cout << std::setw(4) << j_filtered << '\n';
+}

doc/examples/parse__istream__parser_callback_t.output

@@ -0,0 +1,34 @@
+{
+    "Image": {
+        "Animated": false,
+        "Height": 600,
+        "IDs": [
+            116,
+            943,
+            234,
+            38793
+        ],
+        "Thumbnail": {
+            "Height": 125,
+            "Url": "http://www.example.com/image/481989943",
+            "Width": 100
+        },
+        "Title": "View from 15th Floor",
+        "Width": 800
+    }
+}
+
+{
+    "Image": {
+        "Animated": false,
+        "Height": 600,
+        "IDs": [
+            116,
+            943,
+            234,
+            38793
+        ],
+        "Title": "View from 15th Floor",
+        "Width": 800
+    }
+}

doc/examples/parse__string__parser_callback_t.cpp

@@ -0,0 +1,47 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // a JSON text
+    std::string text = R"(
+    {
+        "Image": {
+            "Width":  800,
+            "Height": 600,
+            "Title":  "View from 15th Floor",
+            "Thumbnail": {
+                "Url":    "http://www.example.com/image/481989943",
+                "Height": 125,
+                "Width":  100
+            },
+            "Animated" : false,
+            "IDs": [116, 943, 234, 38793]
+        }
+    }
+    )";
+
+    // parse and serialize JSON
+    json j_complete = json::parse(text);
+    std::cout << std::setw(4) << j_complete << "\n\n";
+
+
+    // define parser callback
+    json::parser_callback_t cb = [](int depth, json::parse_event_t event, json & parsed)
+    {
+        // skip object elements with key "Thumbnail"
+        if (event == json::parse_event_t::key and parsed == json("Thumbnail"))
+        {
+            return false;
+        }
+        else
+        {
+            return true;
+        }
+    };
+
+    // parse (with callback) and serialize JSON
+    json j_filtered = json::parse(text, cb);
+    std::cout << std::setw(4) << j_filtered << '\n';
+}

doc/examples/parse__string__parser_callback_t.output

@@ -0,0 +1,34 @@
+{
+    "Image": {
+        "Animated": false,
+        "Height": 600,
+        "IDs": [
+            116,
+            943,
+            234,
+            38793
+        ],
+        "Thumbnail": {
+            "Height": 125,
+            "Url": "http://www.example.com/image/481989943",
+            "Width": 100
+        },
+        "Title": "View from 15th Floor",
+        "Width": 800
+    }
+}
+
+{
+    "Image": {
+        "Animated": false,
+        "Height": 600,
+        "IDs": [
+            116,
+            943,
+            234,
+            38793
+        ],
+        "Title": "View from 15th Floor",
+        "Width": 800
+    }
+}

doc/examples/swap__array_t.cpp

@@ -0,0 +1,19 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create a JSON value
+    json value = {{"array", {1, 2, 3, 4}}};
+
+    // create an array_t
+    json::array_t array = {"Snap", "Crackle", "Pop"};
+
+    // swap the array stored in the JSON value
+    value["array"].swap(array);
+
+    // output the values
+    std::cout << "value = " << value << '\n';
+    std::cout << "array = " << array << '\n';
+}

doc/examples/swap__array_t.output

@@ -0,0 +1,2 @@
+value = {"array":["Snap","Crackle","Pop"]}
+array = [1,2,3,4]

doc/examples/swap__reference.cpp

@@ -0,0 +1,17 @@
+#include <json.hpp>
+
+using namespace nlohmann;
+
+int main()
+{
+    // create two JSON values
+    json j1 = {1, 2, 3, 4, 5};
+    json j2 = {{"pi", 3.141592653589793}, {"e", 2.718281828459045}};
+
+    // swap the values
+    j1.swap(j2);
+
+    // output the values
+    std::cout << "j1 = " << j1 << '\n';
+    std::cout << "j2 = " << j2 << '\n';
+}

doc/examples/swap__reference.output

@@ -0,0 +1,2 @@
+j1 = {"e":2.71828182845905,"pi":3.14159265358979}
+j2 = [1,2,3,4,5]