Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

stream_parser

A DOM parser for JSON contained in multiple buffers.

Synopsis

Defined in header <boost/json/stream_parser.hpp>

class stream_parser
Member Functions

Name

Description

done

Return true if a complete JSON has been parsed.

finish

Indicate the end of JSON input.

operator=

Copy assignment (deleted)

release

Return the parsed JSON as a value.

reset

Reset the parser for a new JSON.

stream_parser [constructor]

Copy constructor (deleted)

Constructor.

write

Parse a buffer containing all or part of a complete JSON.

write_some

Parse a buffer containing all or part of a complete JSON.

~stream_parser [destructor]

Destructor.

Description

This class is used to parse a JSON contained in a series of one or more character buffers, into a value container. It implements a streaming algorithm, allowing these parsing strategies:

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 one or more times to parse a single, complete JSON. Call done to determine if the parse has completed. To indicate there are no more buffers, call finish. If the parse is successful, call release to take ownership of the value:

stream_parser p;                                // construct a parser
p.write( "[1,2" );                              // parse some of a JSON
p.write( ",3,4]" );                             // parse the rest of the JSON
assert( p.done() );                             // we have a complete JSON
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, 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 JSONs or containing different protocol data:

stream_parser p;                                // construct a parser
std::size_t n;                                  // number of characters used
n = p.write_some( "[1,2" );                     // parse some of a JSON
assert( n == 4 );                               // all characters consumed
n = p.write_some( ",3,4] null" );               // parse the remainder of the JSON
assert( n == 6 );                               // only some characters consumed
assert( p.done() );                             // we have a complete JSON
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 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 JSONs 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, parser, parse_options,

Convenience header <boost/json.hpp>


PrevUpHomeNext