Zen

Source string Source string

234/10000 · 234

The string is read-only.

Key English Actions
:33
A stateful DOM parser object which may be used to efficiently parse a series
of JSON texts each contained in a single contiguous character buffer, returning each result as a <<ref_value>>.
<<ref_stream_parser>>
:38
A stateful DOM parser object which may be used to efficiently parse a series
of JSON texts incrementally, returning each result as a <<ref_value>>.
<<ref_value_stack>>
A low level building block used for efficiently building a <<ref_value>>. The
parsers use this internally, and users may use it to adapt foreign parsers to produce this library's containers. |===
The <<ref_parse>> function offers a simple interface for converting a serialized JSON text to a <<ref_value>> in a single function call. This overload uses exceptions to indicate errors:
Alternatively, an {ref_error_code} can be used:
Even when using error codes, exceptions thrown from the underlying {ref_memory_resource} are still possible:
The <<ref_value>> returned in the preceding examples use the <<default_memory_resource,default memory resource>>. The following code uses a <<ref_monotonic_resource>>, which results in faster parsing. `jv` is marked `const` to prevent subsequent modification, because containers using a monotonic resource waste memory when mutated.
Non-Standard JSON
Unless otherwise specified, the parser in this library is strict. It recognizes only valid, standard JSON. The parser can be configured to allow certain non-standard extensions by filling in a <<ref_parse_options>> structure and passing it by value. By default all extensions are disabled:
When building with {cpp}20 or later, the use of https://en.cppreference.com/w/cpp/language/aggregate_initialization#Designated_initializers[designated initializers] with <<ref_parse_options>> is possible:
When `allow_invalid_utf16` is enabled, the parser will not throw an error in the case of illegal leading, trailing, or half a surrogate. Instead, it will replace the invalid UTF-16 code point(s) with the Unicode replacement character.
When enabling comment support take extra care not to drop whitespace
when reading the input. For example, `std::getline` removes the endline characters from the string it produces.
Full Precision Number Parsing
The default algorithm that the library uses to parse numbers is fast, but may result in slight precision loss. This may not be suitable for some applications, so there is an option to enable an alternative algorithm that doesn't have that flaw, but is somewhat slower. To do this, you also need to use <<ref_parse_options>> structure.
Note that full precision number parsing requires the algorithm to see the full number. This means, that when used with <<ref_stream_parser>>, additional memory allocations may be necessary to store the number parts which were so far accepted by the parser. The library does try its best to avoid such allocations.
Parser
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:
English Actions
= Parsing Parsing is the process where a serialized JSON text is validated and decomposed into elements. The library provides these functions and types to assist with parsing:
of JSON texts each contained in a single contiguous character buffer, returning each result as a <<ref_value>>.
<<ref_stream_parser>>
of JSON texts incrementally, returning each result as a <<ref_value>>.
<<ref_value_stack>>
A low level building block used for efficiently building a <<ref_value>>. The
parsers use this internally, and users may use it to adapt foreign parsers to produce this library's containers. |===
The <<ref_parse>> function offers a simple interface for converting a serialized JSON text to a <<ref_value>> in a single function call. This overload uses exceptions to indicate errors:
Alternatively, an {ref_error_code} can be used:
Even when using error codes, exceptions thrown from the underlying {ref_memory_resource} are still possible:
The <<ref_value>> returned in the preceding examples use the <<default_memory_resource,default memory resource>>. The following code uses a <<ref_monotonic_resource>>, which results in faster parsing. `jv` is marked `const` to prevent subsequent modification, because containers using a monotonic resource waste memory when mutated.
Non-Standard JSON
Unless otherwise specified, the parser in this library is strict. It recognizes only valid, standard JSON. The parser can be configured to allow certain non-standard extensions by filling in a <<ref_parse_options>> structure and passing it by value. By default all extensions are disabled:
When building with {cpp}20 or later, the use of https://en.cppreference.com/w/cpp/language/aggregate_initialization#Designated_initializers[designated initializers] with <<ref_parse_options>> is possible:
When `allow_invalid_utf16` is enabled, the parser will not throw an error in the case of illegal leading, trailing, or half a surrogate. Instead, it will replace the invalid UTF-16 code point(s) with the Unicode replacement character.
When enabling comment support take extra care not to drop whitespace
when reading the input. For example, `std::getline` removes the endline characters from the string it produces.
Full Precision Number Parsing
The default algorithm that the library uses to parse numbers is fast, but may result in slight precision loss. This may not be suitable for some applications, so there is an option to enable an alternative algorithm that doesn't have that flaw, but is somewhat slower. To do this, you also need to use <<ref_parse_options>> structure.
Note that full precision number parsing requires the algorithm to see the full number. This means, that when used with <<ref_stream_parser>>, additional memory allocations may be necessary to store the number parts which were so far accepted by the parser. The library does try its best to avoid such allocations.
Parser
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:
Custom Parsers

Loading…

User avatar admin

String added in the repository
When `allow_invalid_utf16` is enabled, the parser will not throw an error in the case of illegal leading, trailing, or half a surrogate. Instead, it will replace the invalid UTF-16 code point(s) with the Unicode replacement character.
When `allow_invalid_utf16` is enabled, the parser will not throw an error in the case of illegal leading, trailing, or half a surrogate. Instead, it will replace the invalid UTF-16 code point(s) with the Unicode replacement character.
06/05/2026
Browse all string changes

Things to check

Unpluralised

The string is used as plural, but not using plural forms.

Reset

Glossary

English English
No related strings found in the glossary.

String information

Flags
read-only, safe-html, strict-same
Unit identifier
35911
Source string location
:103
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 28