📝 added example for sax_parse

doc/examples/sax_parse.cpp

+#include <iostream>
+#include <iomanip>
+#include <sstream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+// a simple event consumer that collects string representations of the passed
+// values; not inheriting from json::json_sax_t is not required, but can
+// help not to forget a required function
+class sax_event_consumer : public json::json_sax_t
+{
+  public:
+    std::vector<std::string> events;
+
+    bool null() override
+    {
+        events.push_back("value: null");
+        return true;
+    }
+
+    bool boolean(bool val) override
+    {
+        events.push_back("value: " + std::string(val ? "true" : "false"));
+        return true;
+    }
+
+    bool number_integer(number_integer_t val) override
+    {
+        events.push_back("value: " + std::to_string(val));
+        return true;
+    }
+
+    bool number_unsigned(number_unsigned_t val) override
+    {
+        events.push_back("value: " + std::to_string(val));
+        return true;
+    }
+
+    bool number_float(number_float_t val, const string_t& s) override
+    {
+        events.push_back("value: " + s);
+        return true;
+    }
+
+    bool string(string_t& val) override
+    {
+        events.push_back("value: " + val);
+        return true;
+    }
+
+    bool start_object(std::size_t elements) override
+    {
+        events.push_back("start: object");
+        return true;
+    }
+
+    bool end_object() override
+    {
+        events.push_back("end: object");
+        return true;
+    }
+
+    bool start_array(std::size_t elements) override
+    {
+        events.push_back("start: array");
+        return true;
+    }
+
+    bool end_array() override
+    {
+        events.push_back("end: array");
+        return true;
+    }
+
+    bool key(string_t& val) override
+    {
+        events.push_back("key: " + val);
+        return true;
+    }
+
+    bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
+    {
+        events.push_back("error: " + std::string(ex.what()));
+        return false;
+    }
+};
+
+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],
+            "Distance": 12.723374634
+        }
+    }
+    )";
+
+    // create a SAX event consumer object
+    sax_event_consumer sec;
+
+    // parse and serialize JSON
+    bool result = json::sax_parse(text, &sec);
+
+    // output the recorded events
+    for (auto& event : sec.events)
+    {
+        std::cout << "(" << event << ") ";
+    }
+
+    // output the result of sax_parse
+    std::cout << "\nresult: " << std::boolalpha << result << std::endl;
+}

doc/examples/sax_parse.link

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

doc/examples/sax_parse.output

+(start: object) (key: Image) (start: object) (key: Width) (value: 800) (key: Height) (value: 600) (key: Title) (value: View from 15th Floor) (key: Thumbnail) (start: object) (key: Url) (value: http://www.example.com/image/481989943) (key: Height) (value: 125) (key: Width) (value: 100) (end: object) (key: Animated) (value: false) (key: IDs) (start: array) (value: 116) (value: 943) (value: 234) (value: 38793) (end: array) (key: Distance) (value: 12.723374634) (end: object) (end: object) 
+result: true

doc/index.md

@@ -39,7 +39,8 @@ These pages contain the API documentation of JSON for Modern C++, a C++11 header
     - @link nlohmann::basic_json::dump dump @endlink serialize to string
     - @link nlohmann::basic_json::operator<<(std::ostream&, const basic_json &) operator<< @endlink serialize to stream
   - deserialization / parsing
-    - @link nlohmann::basic_json::parse parse @endlink parse from string
+    - @link nlohmann::basic_json::parse parse @endlink parse from input (string, file, etc.) and return JSON value
+    - @link nlohmann::basic_json::sax_parse sax_parse @endlink parse from input (string, file, etc.) and generate SAX events
     - @link nlohmann::basic_json::operator>>(std::istream&, basic_json&) operator>> @endlink parse from stream
     - @link nlohmann::basic_json::accept accept @endlink check for syntax errors without parsing
     - @link nlohmann::json_sax SAX interface @endlink define a user-defined SAX event consumer

include/nlohmann/json.hpp

@@ -6064,6 +6064,10 @@ class basic_json
 
     @note A UTF-8 byte order mark is silently ignored.
 
+    @liveexample{The example below demonstrates the `sax_parse()` function
+    reading from string and processing the events with a user-defined SAX
+    event consumer.,sax_parse}
+
     @since version 3.2.0
     */
     template <typename SAX>

single_include/nlohmann/json.hpp

@@ -17157,7 +17157,7 @@ class basic_json
     @param[in] format  the format to parse (JSON, CBOR, MessagePack, or UBJSON)
     @param[in] strict  whether the input has to be consumed completely
 
-    @return result of the deserialization
+    @return return value of the last processed SAX event
 
     @throw parse_error.101 if a parse error occurs; example: `""unexpected end
     of input; expected string literal""`
@@ -17170,6 +17170,9 @@ class basic_json
 
     @note A UTF-8 byte order mark is silently ignored.
 
+    @liveexample{The example below demonstrates the `sax_parse()` function
+    reading from string.,sax_parse}
+
     @since version 3.2.0
     */
     template <typename SAX>