Zen

Source string Source string

357/10000 · 357

The string is read-only.

English Actions
Instances of <<ref_parser>> and <<ref_stream_parser>> offer functionality beyond what is available when using the <<ref_parse>> free functions:
More control over memory
Streaming API, parse input JSON incrementally
Improved performance when parsing multiple JSON texts
Ignore non-JSON content after the end of a JSON text
The parser implementation uses temporary storage space to accumulate values during parsing. When using the <<ref_parse>> free functions, this storage is allocated and freed in each call. However, by declaring an instance of <<ref_parser>> or <<ref_stream_parser>>, this temporary storage can be reused when parsing more than one JSON text, reducing the total number of dynamic memory allocations.
To use the <<ref_parser>>, declare an instance. Then call <<ref_parser_write>> once with the buffer containing representing the input JSON. Finally, call <<ref_parser_release>> to take ownership of the resulting <<ref_value>> upon success. This example persists the parser instance in a class member to reuse across calls:
Sometimes a protocol may have a JSON text followed by data that is in a different format or specification. The JSON portion can still be parsed by using the function <<ref_parser_write_some>>. Upon success, the return value will indicate the number of characters consumed from the input, which will exclude the non-JSON characters:
The parser instance may be constructed with parse options which allow some non-standard JSON extensions to be recognized:
Streaming Parser
The <<ref_stream_parser>> implements a https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]; it allows incremental processing of large JSON inputs using one or more contiguous character buffers. The entire input JSON does not need to be loaded into memory at once. A network server can use the streaming interface to process incoming JSON in fixed-size amounts, providing these benefits:
CPU consumption per I/O cycle is bounded
Memory consumption per I/O cycle is bounded
Jitter, unfairness, and latency is reduced
Less total memory is required to process the full input
To use the <<ref_stream_parser>>, declare an instance. Then call <<ref_stream_parser_write>> zero or more times with successive buffers representing the input JSON. When there are no more buffers, call <<ref_stream_parser_finish>>. The function <<ref_stream_parser_done>> returns `true` after a successful call to `write` or `finish` if parsing is complete.
In the following example a JSON text is parsed from standard input a line at a time. Error codes are used instead. The function <<ref_stream_parser_finish>> is used to indicate the end of the input:
This example will break, if comments are enabled, because of
`std::getline` use (see the warning in <<non_standard_json>> section).
We can complicate the example further by extracting _several_ JSON values from the sequence of lines.
Controlling Memory
After default construction, or after <<ref_stream_parser_reset>> is called with no arguments, the <<ref_value>> produced after a successful parse operation uses the default memory resource. To use a different memory resource, call `reset` with the resource to use. Here we use a <<ref_monotonic_resource>>, which is optimized for parsing but not subsequent modification:
To achieve performance and memory efficiency, the parser uses a temporary storage area to hold intermediate results. This storage is reused when parsing more than one JSON text, reducing the total number of calls to allocate memory and thus improving performance. Upon construction, the memory resource used to perform allocations for this temporary storage area may be specified. Otherwise, the default memory resource is used. In addition to a memory resource, the parser can make use of a caller-owned buffer for temporary storage. This can help avoid dynamic allocations for small inputs. The following example uses a four kilobyte temporary buffer for the parser, and falls back to the default memory resource if needed:
Avoiding Dynamic Allocations
Through careful specification of buffers and memory resources, it is possible to eliminate all dynamic allocation completely when parsing JSON, for the case where the entire JSON text is available in a single character buffer, as shown here:
Custom Parsers
Users who wish to implement custom parsing strategies may create their own handler to use with an instance of <<ref_basic_parser>>. The handler implements the function signatures required by SAX event interface. In <<examples_validate>> example we define the "null" parser, which throws out the parsed results, to use in the implementation of a function that determines if a JSON text is valid.
Key English Actions
Through careful specification of buffers and memory resources, it is possible to eliminate all dynamic allocation completely when parsing JSON, for the case where the entire JSON text is available in a single character buffer, as shown here:
To achieve performance and memory efficiency, the parser uses a temporary storage area to hold intermediate results. This storage is reused when parsing more than one JSON text, reducing the total number of calls to allocate memory and thus improving performance. Upon construction, the memory resource used to perform allocations for this temporary storage area may be specified. Otherwise, the default memory resource is used. In addition to a memory resource, the parser can make use of a caller-owned buffer for temporary storage. This can help avoid dynamic allocations for small inputs. The following example uses a four kilobyte temporary buffer for the parser, and falls back to the default memory resource if needed:
Avoiding Dynamic Allocations
Instances of <<ref_parser>> and <<ref_stream_parser>> offer functionality beyond what is available when using the <<ref_parse>> free functions:
More control over memory
Streaming API, parse input JSON incrementally
Improved performance when parsing multiple JSON texts
Ignore non-JSON content after the end of a JSON text
The parser implementation uses temporary storage space to accumulate values during parsing. When using the <<ref_parse>> free functions, this storage is allocated and freed in each call. However, by declaring an instance of <<ref_parser>> or <<ref_stream_parser>>, this temporary storage can be reused when parsing more than one JSON text, reducing the total number of dynamic memory allocations.
To use the <<ref_parser>>, declare an instance. Then call <<ref_parser_write>> once with the buffer containing representing the input JSON. Finally, call <<ref_parser_release>> to take ownership of the resulting <<ref_value>> upon success. This example persists the parser instance in a class member to reuse across calls:
Sometimes a protocol may have a JSON text followed by data that is in a different format or specification. The JSON portion can still be parsed by using the function <<ref_parser_write_some>>. Upon success, the return value will indicate the number of characters consumed from the input, which will exclude the non-JSON characters:
The parser instance may be constructed with parse options which allow some non-standard JSON extensions to be recognized:
Streaming Parser
The <<ref_stream_parser>> implements a https://en.wikipedia.org/wiki/Online_algorithm[__streaming algorithm__]; it allows incremental processing of large JSON inputs using one or more contiguous character buffers. The entire input JSON does not need to be loaded into memory at once. A network server can use the streaming interface to process incoming JSON in fixed-size amounts, providing these benefits:
CPU consumption per I/O cycle is bounded
Memory consumption per I/O cycle is bounded
Jitter, unfairness, and latency is reduced
Less total memory is required to process the full input
To use the <<ref_stream_parser>>, declare an instance. Then call <<ref_stream_parser_write>> zero or more times with successive buffers representing the input JSON. When there are no more buffers, call <<ref_stream_parser_finish>>. The function <<ref_stream_parser_done>> returns `true` after a successful call to `write` or `finish` if parsing is complete.
In the following example a JSON text is parsed from standard input a line at a time. Error codes are used instead. The function <<ref_stream_parser_finish>> is used to indicate the end of the input:
This example will break, if comments are enabled, because of
`std::getline` use (see the warning in <<non_standard_json>> section).
We can complicate the example further by extracting _several_ JSON values from the sequence of lines.
Controlling Memory
After default construction, or after <<ref_stream_parser_reset>> is called with no arguments, the <<ref_value>> produced after a successful parse operation uses the default memory resource. To use a different memory resource, call `reset` with the resource to use. Here we use a <<ref_monotonic_resource>>, which is optimized for parsing but not subsequent modification:
:33
A stateful DOM parser object which may be used to efficiently parse a series
:38
A stateful DOM parser object which may be used to efficiently parse a series

Loading…

User avatar admin

String added in the repository
To use the <<ref_stream_parser>>, declare an instance. Then call <<ref_stream_parser_write>> zero or more times with successive buffers representing the input JSON. When there are no more buffers, call <<ref_stream_parser_finish>>. The function <<ref_stream_parser_done>> returns `true` after a successful call to `write` or `finish` if parsing is complete.
To use the <<ref_stream_parser>>, declare an instance. Then call <<ref_stream_parser_write>> zero or more times with successive buffers representing the input JSON. When there are no more buffers, call <<ref_stream_parser_finish>>. The function <<ref_stream_parser_done>> returns `true` after a successful call to `write` or `finish` if parsing is complete.
06/05/2026
Browse all string changes

Glossary

English English
No related strings found in the glossary.

String information

Flags
read-only, safe-html, strict-same
Unit identifier
35933
Source string location
:194
String age
06/05/2026
Last updated
06/05/2026
Source string age
06/05/2026
Translation file AsciiDoc file
doc/pages/io/parsing.adoc, string 50