diff --git a/doc/examples/sax_parse.cpp b/doc/examples/sax_parse.cpp
new file mode 100644
index 00000000..69e8962c
--- /dev/null
+++ b/doc/examples/sax_parse.cpp
@@ -0,0 +1,124 @@
+#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;
+}
diff --git a/doc/examples/sax_parse.link b/doc/examples/sax_parse.link
new file mode 100644
index 00000000..14aa5e38
--- /dev/null
+++ b/doc/examples/sax_parse.link
@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/fGkQLWbQn7enKkIG"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/sax_parse.output b/doc/examples/sax_parse.output
new file mode 100644
index 00000000..e16c2c4d
--- /dev/null
+++ b/doc/examples/sax_parse.output
@@ -0,0 +1,2 @@
+(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
diff --git a/doc/index.md b/doc/index.md
index 830c4463..88054c59 100644
--- a/doc/index.md
+++ b/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
diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp
index 9546520e..aed3a737 100644
--- a/include/nlohmann/json.hpp
+++ b/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>
diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp
index f7ff131d..fd91930c 100644
--- a/single_include/nlohmann/json.hpp
+++ b/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>