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/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';
+}