...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
A DOM parser for JSON contained in multiple buffers.
Defined in header <boost/json/stream_parser.hpp>
class stream_parser
Name |
Description |
---|---|
Return true if a complete JSON has been parsed. |
|
Indicate the end of JSON input. |
|
Copy assignment (deleted) |
|
Return the parsed JSON as a |
|
Reset the parser for a new JSON. |
|
stream_parser [constructor] |
Copy constructor (deleted) |
Parse a buffer containing all or part of a complete JSON. |
|
Parse a buffer containing all or part of a complete JSON. |
|
~stream_parser [destructor] |
Destructor. |
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:
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
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
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
.
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.
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.
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.
Convenience header <boost/json.hpp>