1# basic_json::sax_parse
2
3```cpp
4// (1)
5template <typename InputType, typename SAX>
6static bool sax_parse(InputType&& i,
7                      SAX* sax,
8                      input_format_t format = input_format_t::json,
9                      const bool strict = true,
10                      const bool ignore_comments = false);
11
12// (2)
13template<class IteratorType, class SAX>
14static bool sax_parse(IteratorType first, IteratorType last,
15                      SAX* sax,
16                      input_format_t format = input_format_t::json,
17                      const bool strict = true,
18                      const bool ignore_comments = false);
19```
20
21Read from input and generate SAX events
22
231. Read from a compatible input.
242. Read from a pair of character iterators
25
26    The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted
27    respectively as UTF-8, UTF-16 and UTF-32.
28
29The SAX event lister must follow the interface of `json_sax`.
30
31## Template parameters
32
33`InputType`
34:   A compatible input, for instance:
35
36    - an `std::istream` object
37    - a `FILE` pointer
38    - a C-style array of characters
39    - a pointer to a null-terminated string of single byte characters
40    - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of
41      iterators.
42
43`IteratorType`
44:   Description
45
46`SAX`
47:   Description
48
49## Parameters
50
51`i` (in)
52:   Input to parse from.
53
54`sax` (in)
55:   SAX event listener
56
57`format` (in)
58:    the format to parse (JSON, CBOR, MessagePack, or UBJSON) (optional, `input_format_t::json` by default), see
59     [`input_format_t`](input_format_t.md) for more information
60
61`strict` (in)
62:   whether the input has to be consumed completely (optional, `#!cpp true` by default)
63
64`ignore_comments` (in)
65:   whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error
66    (`#!cpp false`); (optional, `#!cpp false` by default)
67
68`first` (in)
69:   iterator to start of character range
70
71`last` (in)
72:   iterator to end of character range
73
74## Return value
75
76return value of the last processed SAX event
77
78## Exception safety
79
80## Complexity
81
82Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the SAX
83consumer `sax` has a super-linear complexity.
84
85## Notes
86
87A UTF-8 byte order mark is silently ignored.
88
89## Examples
90
91??? example
92
93    The example below demonstrates the `sax_parse()` function reading from string and processing the events with a
94    user-defined SAX event consumer.
95
96    ```cpp
97    --8<-- "examples/sax_parse.cpp"
98    ```
99
100    Output:
101
102    ```json
103    --8<-- "examples/sax_parse.output"
104    ```
105
106## Version history
107
108- Added in version 3.2.0.
109- Ignoring comments via `ignore_comments` added in version 3.9.0.
110