JSON for Modern C++  3.5.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.
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.
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:13201
basic_json<> json
default JSON class
Definition: json.hpp:110
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:18518
NumberIntegerType number_integer_t
a type for a number (integer)
Definition: json.hpp:13062
NumberUnsignedType number_unsigned_t
a type for a number (unsigned)
Definition: json.hpp:13133
detail::parse_error parse_error
exception indicating a parse error
Definition: json.hpp:12616
StringType string_t
a type for a string
Definition: json.hpp:12964
json_sax< basic_json > json_sax_t
SAX interface type, see nlohmann::json_sax.
Definition: json.hpp:12603
detail::exception exception
general exception of the basic_json class
Definition: json.hpp:12614
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 18518 of file json.hpp.