| Home | Libraries | People | FAQ | More

#### parser

A DOM parser for JSON contained in a single buffer.

##### Synopsis

Defined in header `<boost/json/parser.hpp>`

    class parser

##### Member Functions

Name | Description
--- | ---
operator= | Copy assignment (deleted)
parser [constructor] | Copy constructor (deleted) — Constructor.
release | Return the parsed JSON text as a `value`.
reset | Reset the parser for a new JSON text.
write | Parse a buffer containing a complete JSON text.
write_some | Parse a buffer containing a complete JSON text.
~parser [destructor] | Destructor.

##### Description

This class is used to parse a JSON text contained in a single character buffer, into a `value` container.

##### Usage

To use the parser first construct it, then optionally call `reset` to specify a `storage_ptr` to use for the resulting `value`. Then call `write` to parse a character buffer containing a complete JSON text. If the parse is successful, call `release` to take ownership of the value:

    parser p;                                       // construct a parser
    size_t n = p.write( "[1,2,3]" );                // parse a complete JSON text
    assert( n == 7 );                               // all characters consumed
    value jv = p.release();                         // take ownership of the value

##### Extra Data

When the character buffer provided as input contains additional data that is not part of the complete JSON text, an error is returned. The `write_some` function is an alternative which allows the parse to finish early, without consuming all the characters in the buffer. This allows parsing of a buffer containing multiple individual JSON texts or containing different protocol data:

    parser p;                                       // construct a parser
    size_t n = p.write_some( "[1,2,3] null" );      // parse a complete JSON text
    assert( n == 8 );                               // only some characters consumed
    value jv = p.release();                         // take ownership of the value

##### Temporary Storage

The parser may dynamically allocate temporary storage as needed to accommodate the nesting level of the JSON text being parsed. Temporary storage is first obtained from an optional, caller-owned buffer specified upon construction. When that is exhausted, the next allocation uses the `memory_resource` passed to the constructor; if no such argument is specified, the default memory resource is used. Temporary storage is freed only when the parser is destroyed; The performance of parsing multiple JSON texts may be improved by reusing the same parser instance.

It is important to note that the `memory_resource` supplied upon construction is used for temporary storage only, and not for allocating the elements which make up the parsed value. That other memory resource is optionally supplied in each call to `reset`.

##### Duplicate Keys

If there are object elements with duplicate keys; that is, if multiple elements in an object have keys that compare equal, only the last equivalent element will be inserted.

##### Non-Standard JSON

The `parse_options` structure optionally provided upon construction is used to customize some parameters of the parser, including which non-standard JSON extensions should be allowed. A default-constructed parse options allows only standard JSON.

##### Thread Safety

Distinct instances may be accessed concurrently. Non-const member functions of a shared instance may not be called concurrently with any other member functions of that instance.

##### See Also

`parse`, `parse_options`, `stream_parser`.

Convenience header `<boost/json.hpp>`