JSON for Modern C++  3.7.0

◆ sax_parse() [1/2]

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>
template<typename SAX >
static bool nlohmann::basic_json::sax_parse ( detail::input_adapter &&  i,
SAX *  sax,
input_format_t  format = input_format_t::json,
const bool  strict = true 
)
inlinestatic

The SAX event lister must follow the interface of json_sax.

This function reads from a compatible input. Examples are:

  • an array of 1-byte values
  • strings with character/literal type with size of 1 byte
  • input streams
  • container with contiguous storage of 1-byte values. Compatible container types include std::vector, std::string, std::array, std::valarray, and std::initializer_list. Furthermore, C-style arrays can be used with std::begin()/std::end(). User-defined containers can be used as long as they implement random-access iterators and a contiguous storage.
Precondition
Each element of the container has a size of 1 byte. Violating this precondition yields undefined behavior. This precondition is enforced with a static assertion.
The container storage is contiguous. Violating this precondition yields undefined behavior. This precondition is enforced with an assertion.
Warning
There is no way to enforce all preconditions at compile-time. If the function is called with a noncompliant container and with assertions switched off, the behavior is undefined and will most likely yield segmentation violation.
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
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 
6 using 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
11 class 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 parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
83  {
84  events.push_back("error: " + std::string(ex.what()));
85  return false;
86  }
87 };
88 
89 int main()
90 {
91  // a JSON text
92  auto text = R"(
93  {
94  "Image": {
95  "Width": 800,
96  "Height": 600,
97  "Title": "View from 15th Floor",
98  "Thumbnail": {
99  "Url": "http://www.example.com/image/481989943",
100  "Height": 125,
101  "Width": 100
102  },
103  "Animated" : false,
104  "IDs": [116, 943, 234, 38793],
105  "Distance": 12.723374634
106  }
107  }
108  )";
109 
110  // create a SAX event consumer object
111  sax_event_consumer sec;
112 
113  // parse and serialize JSON
114  bool result = json::sax_parse(text, &sec);
115 
116  // output the recorded events
117  for (auto& event : sec.events)
118  {
119  std::cout << "(" << event << ") ";
120  }
121 
122  // output the result of sax_parse
123  std::cout << "\nresult: " << std::boolalpha << result << std::endl;
124 }
NumberFloatType number_float_t
a type for a number (floating-point)
Definition: json.hpp:15225
basic_json<> json
default JSON class
Definition: json.hpp:2355
static bool sax_parse(detail::input_adapter &&i, SAX *sax, input_format_t format=input_format_t::json, const bool strict=true)
generate SAX events
Definition: json.hpp:20640
NumberIntegerType number_integer_t
a type for a number (integer)
Definition: json.hpp:15086
NumberUnsignedType number_unsigned_t
a type for a number (unsigned)
Definition: json.hpp:15157
detail::parse_error parse_error
exception indicating a parse error
Definition: json.hpp:14639
StringType string_t
a type for a string
Definition: json.hpp:14988
json_sax< basic_json > json_sax_t
SAX interface type, see nlohmann::json_sax.
Definition: json.hpp:14626
detail::exception exception
general exception of the basic_json class
Definition: json.hpp:14637

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 20640 of file json.hpp.