// (1) template <typename InputType, typename SAX> 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, const bool ignore_trailing_commas = false); // (2) template<class IteratorType, class SAX, class SentinelType = IteratorType> static bool sax_parse(IteratorType first, SentinelType last, SAX* sax, input_format_t format = input_format_t::json, const bool strict = true, const bool ignore_comments = false, const bool ignore_trailing_commas = false);
Read from input and generate SAX events
Read from a compatible input.
Read from a pair of character iterators, or an iterator and a sentinel of a different type (C++20 ranges support)
The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted respectively as UTF-8, UTF-16, and UTF-32. If SentinelType differs from IteratorType, it must be comparable to the iterator type with operator!=.
The SAX event lister must follow the interface of json_sax.
InputType : A compatible input, for instance:
- an `std::istream` object - a `FILE` pointer - a C-style array of characters - a pointer to a null-terminated string of single byte characters - a container `obj` for which `begin(obj)` and `end(obj)` produce a valid pair of iterators (as found via ADL or member functions, with semantics compatible to `std::begin` and `std::end`)
IteratorType : a compatible iterator type for overload (2); a pair of character iterators whose value_type is an integral type with a size of 1, 2, or 4 bytes (interpreted respectively as UTF-8, UTF-16, and UTF-32)
SentinelType : defaults to IteratorType; may be a different type comparable to IteratorType via operator!=, for overload (2)
SAX : a class fulfilling the SAX event listener interface; see json_sax
i (in) : Input to parse from
sax (in) : SAX event listener (must not be null)
format (in) : the format to parse (JSON, CBOR, MessagePack, or UBJSON) (optional, input_format_t::json by default), see input_format_t for more information
strict (in) : whether the input has to be consumed completely (optional, #!cpp true by default)
ignore_comments (in) : whether comments should be ignored and treated like whitespace (#!cpp true) or yield a parse error (#!cpp false); (optional, #!cpp false by default)
ignore_trailing_commas (in) : whether trailing commas in arrays or objects should be ignored and treated like whitespace (#!cpp true) or yield a parse error (#!cpp false); (optional, #!cpp false by default)
first (in) : iterator to the start of a character range
last (in) : iterator to the end of a character range, or a sentinel value that compares equal to the end iterator with operator!=
return value of the last processed SAX event
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
parse_error.101 in case of an unexpected token, or empty input like a null FILE* or char* pointer.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.
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. ```cpp --8<-- "examples/sax_parse.cpp" ``` Output: ```json --8<-- "examples/sax_parse.output" ```
ignore_comments added in version 3.9.0.ignore_trailing_commas in version 3.13.0.begin/end (matching std::begin/std::end semantics) in version 3.13.0.!!! warning “Deprecation”
Overload (2) replaces calls to `sax_parse` with a pair of iterators as their first parameter which has been
deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like
`#!cpp sax_parse({ptr, ptr+len});` with `#!cpp sax_parse(ptr, ptr+len);`.