JSON for Modern C++ 3.10.4

◆ sax_parse() [2/3]

template<template< typename U, typename V, typename... Args > class ObjectType = std::map, template< typename U, typename... Args > class ArrayType = std::vector, class StringType = std::string, class BooleanType = bool, class NumberIntegerType = std::int64_t, class NumberUnsignedType = std::uint64_t, class NumberFloatType = double, template< typename U > class AllocatorType = std::allocator, template< typename T, typename SFINAE=void > class JSONSerializer = adl_serializer, class BinaryType = std::vector<std::uint8_t>>
template<typename InputType , typename SAX >
static bool nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::sax_parse ( InputType &&  i,
SAX *  sax,
input_format_t  format = input_format_t::json,
const bool  strict = true,
const bool  ignore_comments = false 
)
inlinestatic

The SAX event lister must follow the interface of json_sax.

This function reads from a compatible input. Examples are:

  • an std::istream object
  • a FILE pointer
  • a C-style array of characters
  • a pointer to a null-terminated string of single byte characters
  • an object obj for which begin(obj) and end(obj) produces a valid pair of iterators.
Parameters
[in]iinput to read from
[in,out]saxSAX event listener
[in]formatthe format to parse (JSON, CBOR, MessagePack, or UBJSON)
[in]strictwhether the input has to be consumed completely
[in]ignore_commentswhether comments should be ignored and treated like whitespace (true) or yield a parse error (true); (optional, false by default); only applies to the JSON file format.
Returns
return value of the last processed SAX event
Exceptions
parse_error.101if a parse error occurs; example: ""unexpected end of input; expected string literal""
parse_error.102if to_unicode fails or surrogate error
parse_error.103if to_unicode fails
Complexity
Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the SAX consumer sax has a super-linear complexity.
Note
A UTF-8 byte order mark is silently ignored.
Example
The example below demonstrates the sax_parse() function reading from string and processing the events with a user-defined SAX event consumer.
1#include <iostream>
2#include <iomanip>
3#include <sstream>
4#include <nlohmann/json.hpp>
5
6using json = nlohmann::json;
7
8// a simple event consumer that collects string representations of the passed
9// values; not inheriting from json::json_sax_t is not required, but can
10// help not to forget a required function
11class sax_event_consumer : public json::json_sax_t
12{
13 public:
14 std::vector<std::string> events;
15
16 bool null() override
17 {
18 events.push_back("value: null");
19 return true;
20 }
21
22 bool boolean(bool val) override
23 {
24 events.push_back("value: " + std::string(val ? "true" : "false"));
25 return true;
26 }
27
28 bool number_integer(number_integer_t val) override
29 {
30 events.push_back("value: " + std::to_string(val));
31 return true;
32 }
33
34 bool number_unsigned(number_unsigned_t val) override
35 {
36 events.push_back("value: " + std::to_string(val));
37 return true;
38 }
39
40 bool number_float(number_float_t val, const string_t& s) override
41 {
42 events.push_back("value: " + s);
43 return true;
44 }
45
46 bool string(string_t& val) override
47 {
48 events.push_back("value: " + val);
49 return true;
50 }
51
52 bool start_object(std::size_t elements) override
53 {
54 events.push_back("start: object");
55 return true;
56 }
57
58 bool end_object() override
59 {
60 events.push_back("end: object");
61 return true;
62 }
63
64 bool start_array(std::size_t elements) override
65 {
66 events.push_back("start: array");
67 return true;
68 }
69
70 bool end_array() override
71 {
72 events.push_back("end: array");
73 return true;
74 }
75
76 bool key(string_t& val) override
77 {
78 events.push_back("key: " + val);
79 return true;
80 }
81
82 bool binary(json::binary_t& val) override
83 {
84 events.push_back("binary");
85 return true;
86 }
87
88 bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
89 {
90 events.push_back("error: " + std::string(ex.what()));
91 return false;
92 }
93};
94
95int main()
96{
97 // a JSON text
98 auto text = R"(
99 {
100 "Image": {
101 "Width": 800,
102 "Height": 600,
103 "Title": "View from 15th Floor",
104 "Thumbnail": {
105 "Url": "http://www.example.com/image/481989943",
106 "Height": 125,
107 "Width": 100
108 },
109 "Animated" : false,
110 "IDs": [116, 943, 234, 38793],
111 "Distance": 12.723374634
112 }
113 }
114 )";
115
116 // create a SAX event consumer object
117 sax_event_consumer sec;
118
119 // parse and serialize JSON
120 bool result = json::sax_parse(text, &sec);
121
122 // output the recorded events
123 for (auto& event : sec.events)
124 {
125 std::cout << "(" << event << ") ";
126 }
127
128 // output the result of sax_parse
129 std::cout << "\nresult: " << std::boolalpha << result << std::endl;
130}
NumberIntegerType number_integer_t
a type for a number (integer)
Definition: json.hpp:18212
static bool sax_parse(InputType &&i, SAX *sax, input_format_t format=input_format_t::json, const bool strict=true, const bool ignore_comments=false)
generate SAX events
Definition: json.hpp:24563
detail::exception exception
general exception of the basic_json class
Definition: json.hpp:17763
json_sax< basic_json > json_sax_t
SAX interface type, see nlohmann::json_sax.
Definition: json.hpp:17752
StringType string_t
a type for a string
Definition: json.hpp:18114
detail::parse_error parse_error
exception indicating a parse error
Definition: json.hpp:17765
NumberFloatType number_float_t
a type for a number (floating-point)
Definition: json.hpp:18351
nlohmann::byte_container_with_subtype< BinaryType > binary_t
a type for a packed binary type
Definition: json.hpp:18422
NumberUnsignedType number_unsigned_t
a type for a number (unsigned)
Definition: json.hpp:18283
basic_json<> json
default JSON class
Definition: json.hpp:3472

Output (play with this example online):
(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
The example code above can be translated with
g++ -std=c++11 -Isingle_include doc/examples/sax_parse.cpp -o sax_parse 
Since
version 3.2.0

Definition at line 24563 of file json.hpp.