# <small>nlohmann::basic_json::</small>sax_parse

```cpp
// (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,
                      const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);

// (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,
                      const cbor_tag_handler_t tag_handler = cbor_tag_handler_t::error);
```

Read from input and generate SAX events

1. Read from a compatible input.
2. 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`](../json_sax/index.md).

## Template parameters

`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), for instance.

    - a custom sentinel type for C++20 ranges
    - `std::default_sentinel_t`, when `IteratorType` is `std::counted_iterator`

`SAX`
:   a class fulfilling the SAX event listener interface; see [`json_sax`](../json_sax/index.md)

## Parameters

`i` (in)
:   Input to parse from

`sax` (in)
:   SAX event listener (must not be null)

`format` (in)
:    the format to parse (JSON, BJData, BON8, BSON, CBOR, MessagePack, or UBJSON) (optional, `input_format_t::json` by
     default), see
     [`input_format_t`](input_format_t.md) for more information

`strict` (in)
:   whether the input has to be consumed completely (optional, `#!cpp true` by default); when `#!cpp false` and the
    input is a `#!cpp std::istream`, the character that terminates a number is consumed unless
    [`JSON_PRECISE_STREAM_POSITION`](../macros/json_precise_stream_position.md) is defined to `1`; see [`operator>>`](../operator_gtgt.md#notes)

`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)

`tag_handler` (in)
:   how to handle CBOR tags; see [`cbor_tag_handler_t`](cbor_tag_handler_t.md). Ignored for formats other than CBOR
    (optional, `cbor_tag_handler_t::error` 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

return value of the last processed SAX event

## Exception safety

Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

## Exceptions

- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token, or
  empty input like a null `FILE*` or `char*` pointer.

## 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.

## Notes

A UTF-8 byte order mark is silently ignored.

When reading from a `#!c FILE*`, the file is locked while it is parsed. The lock is recursive, so the SAX handler may
use the same file with stdio functions, but it must not wait for another thread that uses the same `FILE` object; see
[`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md).

## Examples

??? example

    The example below demonstrates the `sax_parse()` function reading from string and processing the events with a
    user-defined SAX event consumer.
    
    ```cpp
    #include <iostream>
    #include <iomanip>
    #include <sstream>
    #include <nlohmann/json.hpp>
    
    using json = nlohmann::json;
    
    // a simple event consumer that collects string representations of the passed
    // values; note inheriting from json::json_sax_t is not required, but can
    // help not to forget a required function
    class sax_event_consumer : public json::json_sax_t
    {
      public:
        std::vector<std::string> events;
    
        bool null() override
        {
            events.push_back("null()");
            return true;
        }
    
        bool boolean(bool val) override
        {
            events.push_back("boolean(val=" + std::string(val ? "true" : "false") + ")");
            return true;
        }
    
        bool number_integer(number_integer_t val) override
        {
            events.push_back("number_integer(val=" + std::to_string(val) + ")");
            return true;
        }
    
        bool number_unsigned(number_unsigned_t val) override
        {
            events.push_back("number_unsigned(val=" + std::to_string(val) + ")");
            return true;
        }
    
        bool number_float(number_float_t val, const string_t& s) override
        {
            events.push_back("number_float(val=" + std::to_string(val) + ", s=" + s + ")");
            return true;
        }
    
        bool string(string_t& val) override
        {
            events.push_back("string(val=" + val + ")");
            return true;
        }
    
        bool start_object(std::size_t elements) override
        {
            events.push_back("start_object(elements=" + std::to_string(elements) + ")");
            return true;
        }
    
        bool end_object() override
        {
            events.push_back("end_object()");
            return true;
        }
    
        bool start_array(std::size_t elements) override
        {
            events.push_back("start_array(elements=" + std::to_string(elements) + ")");
            return true;
        }
    
        bool end_array() override
        {
            events.push_back("end_array()");
            return true;
        }
    
        bool key(string_t& val) override
        {
            events.push_back("key(val=" + val + ")");
            return true;
        }
    
        bool binary(json::binary_t& val) override
        {
            events.push_back("binary(val=[...])");
            return true;
        }
    
        bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
        {
            events.push_back("parse_error(position=" + std::to_string(position) + ", last_token=" + last_token + ",\n            ex=" + std::string(ex.what()) + ")");
            return false;
        }
    };
    
    int main()
    {
        // a JSON text
        auto text = R"(
        {
            "Image": {
                "Width":  800,
                "Height": 600,
                "Title":  "View from 15th Floor",
                "Thumbnail": {
                    "Url":    "http://www.example.com/image/481989943",
                    "Height": 125,
                    "Width":  100
                },
                "Animated" : false,
                "IDs": [116, 943, 234, -38793],
                "DeletionDate": null,
                "Distance": 12.723374634
            }
        }]
        )";
    
        // create a SAX event consumer object
        sax_event_consumer sec;
    
        // parse JSON
        bool result = json::sax_parse(text, &sec);
    
        // output the recorded events
        for (auto& event : sec.events)
        {
            std::cout << event << "\n";
        }
    
        // output the result of sax_parse
        std::cout << "\nresult: " << std::boolalpha << result << std::endl;
    }
    
    ```
    
    Output:
    
    ```json
    start_object(elements=18446744073709551615)
    key(val=Image)
    start_object(elements=18446744073709551615)
    key(val=Width)
    number_unsigned(val=800)
    key(val=Height)
    number_unsigned(val=600)
    key(val=Title)
    string(val=View from 15th Floor)
    key(val=Thumbnail)
    start_object(elements=18446744073709551615)
    key(val=Url)
    string(val=http://www.example.com/image/481989943)
    key(val=Height)
    number_unsigned(val=125)
    key(val=Width)
    number_unsigned(val=100)
    end_object()
    key(val=Animated)
    boolean(val=false)
    key(val=IDs)
    start_array(elements=18446744073709551615)
    number_unsigned(val=116)
    number_unsigned(val=943)
    number_unsigned(val=234)
    number_integer(val=-38793)
    end_array()
    key(val=DeletionDate)
    null()
    key(val=Distance)
    number_float(val=12.723375, s=12.723374634)
    end_object()
    end_object()
    parse_error(position=460, last_token=12.723374634<U+000A>        }<U+000A>    }],
                ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
    
    result: false
    
    ```

## See also

- [parse](parse.md) - deserialize from a compatible input
- [accept](accept.md) - check if the input is valid JSON
- [`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md) - read a `std::istream` one character
  at a time
- [`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md) - read a `FILE*` with the locking stdio
  functions

## Version history

- Added in version 3.2.0.
- Ignoring comments via `ignore_comments` added in version 3.9.0.
- Added `ignore_trailing_commas` in version 3.13.0.
- Added `tag_handler` in version 3.13.0.
- Extended container support (1) to include types with lvalue-only ADL `begin`/`end` (matching `std::begin`/`std::end` semantics) in version 3.13.0.
- Extended overload (2) to accept heterogeneous iterator+sentinel pairs (C++20 ranges support) in version 3.13.0.
- `JSON_PRECISE_STREAM_POSITION` added in version 3.13.0 to optionally leave a `#!cpp std::istream` positioned right
  after the parsed value when `strict` is `#!cpp false`.
- Parsing from an `std::istream` scans the characters in its stream buffer in bulk in version 3.13.0
  ([`JSON_DISABLE_STREAM_BULK_SCAN`](../macros/json_disable_stream_bulk_scan.md)).
- Parsing from a `FILE*` locks the file once instead of once per character in version 3.13.0
  ([`JSON_DISABLE_UNLOCKED_FILE_IO`](../macros/json_disable_unlocked_file_io.md)).

!!! 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);`.

    See the [migration guide](../../integration/migration_guide.md#parsing) for how to update existing code.