json/docs/mkdocs/docs/api/basic_json_document/parse.md

nlohmann::basic_json_document::parse

// (1)
template<typename InputType>
static basic_json_document parse(InputType&& input,
                                 const bool allow_exceptions = true,
                                 const bool ignore_comments = false,
                                 const bool ignore_trailing_commas = false);

// (2)
template<typename IteratorType>
static basic_json_document parse(IteratorType first, IteratorType last,
                                 const bool allow_exceptions = true,
                                 const bool ignore_comments = false,
                                 const bool ignore_trailing_commas = false);

1. Deserialize from a compatible input, borrowing or owning it depending on its value category and type (see Notes).
2. Deserialize from a pair of input iterators.

Both overloads accept the same JSON text as BasicJsonType::parse(), with the same ignore_comments/ignore_trailing_commas options, but build a basic_json_document (a flat index into the input) instead of a tree of BasicJsonType values. They accept every input BasicJsonType::parse() takes, and in addition a pointer to a null-terminated wide string (which BasicJsonType::parse() rejects). Contiguous inputs of single-byte characters that stay alive can be borrowed; all others (streams, #!cpp FILE*, wide characters, which must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns — see the Notes. Use parse_copy() to get an owned copy of a borrowable input as well.

Template parameters

InputType

A compatible input, for instance:

• a #!cpp std::string, a #!cpp std::string_view (C++17), or a C-style array of single-byte characters
• a pointer to a null-terminated string of single-byte characters (#!cpp char, #!cpp signed char, #!cpp unsigned char, #!cpp std::uint8_t)
• a container for which #!cpp obj.data() and #!cpp obj.size() give contiguous single-byte access, e.g. #!cpp std::vector<char> or #!cpp std::vector<std::uint8_t>
• an #!cpp std::istream object
• a #!cpp FILE* pointer
• wide characters (#!cpp wchar_t, #!cpp char16_t, #!cpp char32_t), which are converted to UTF-8: a wide string object (#!cpp std::wstring, #!cpp std::u16string, #!cpp std::u32string), an array (e.g. a wide string literal), or a pointer to a null-terminated wide string

IteratorType

an input iterator type, for instance a pair of pointers such as ptr and ptr + len, or a pair of #!cpp std::string::iterator; the iterators of single-byte characters are borrowed or read like the byte inputs above, those of wide characters are converted to UTF-8

Ill-formed UTF-16 and UTF-32 sequences are rejected: a lone surrogate, a high surrogate that is not followed by its low surrogate, and a code point above U+10FFFF all yield a parse_error.101.

Parameters

input (in)

Input to parse from.

allow_exceptions (in)

whether to throw exceptions in case of a parse error (optional, #!cpp true by default)

ignore_comments (in)

whether comments should be ignored and treated like whitespace (#!cpp true) or yield a parse error (#!cpp false); (optional, #!cpp false by default)

ignore_trailing_commas (in)

whether trailing commas in arrays or objects should be ignored and treated like whitespace (#!cpp true) or yield a parse error (#!cpp false); (optional, #!cpp false by default)

first (in)

iterator to the start of a character range

last (in)

iterator to the end of a character range

Return value

The parsed document. If allow_exceptions is #!cpp false and the input is not valid JSON, the returned document is discarded; see is_discarded.

Exceptions

Throws the same exception BasicJsonType::parse() throws for the same input and options — the same exception id, message, and position — because on a failing input the library's own parser is run on the same bytes to produce the diagnostic. This replay runs only for a failing input, and costs about a lexing pass up to the error (its SAX handler builds no values); with allow_exceptions set to #!cpp false, it is skipped and a discarded document is returned instead. Additionally throws out_of_range.416 if the input is 4294967280 bytes (4 GiB minus 16 bytes) or larger, a size BasicJsonType::parse() does not reject.

Complexity

Linear in the length of the input.

Notes

Ownership. Whether the document borrows input or owns a copy of it depends on its value category and type:

input	ownership
lvalue byte container (std::string, std::vector<char>, ...), std::string_view, C string, character array	borrowed — input must outlive the document
non-const rvalue #!cpp std::string	owned, moved in without a copy
other rvalue byte container (including a #!cpp const rvalue #!cpp std::string)	owned, copied
stream, #!cpp FILE*, wide characters, or anything else read through the general input adapter	owned, read into a buffer (a stream is read to its end)

For overload (2), a pair of pointers to single-byte integers (e.g. #!cpp const char*, #!cpp std::uint8_t*) is borrowed. From C++20 on, so is any other contiguous iterator over single bytes, such as #!cpp std::vector<char>::iterator or #!cpp std::string::const_iterator. Before C++20 these iterators cannot be told apart from other class-type iterators, so their range is read into an owned buffer, as is any non-contiguous range (e.g. of a #!cpp std::list<char>).

See owns_source to check which happened after a call, and the feature page for the reasoning.

Numbers. As for BasicJsonType::parse(), an integer literal too large for the 64-bit integer type becomes a floating-point value.

No lengths. An integer argument that is not a #!cpp bool where the flags are expected — for example #!cpp parse(ptr, len) — does not compile (the overload is deleted). Such a call would convert len to allow_exceptions and read ptr as a null-terminated string, past the end of a buffer that has none. To parse a buffer of a given length, pass a pair of pointers: #!cpp parse(ptr, ptr + len). The same holds for parse_copy, accept, and read.

Examples

??? example "Example: (1) borrowed vs. owned input, and errors identical to BasicJsonType::parse()"

```cpp
--8<-- "examples/basic_json_document__parse.cpp"
```

Output:

```json
--8<-- "examples/basic_json_document__parse.output"
```

??? example "Example: (2) parse an iterator range (no NUL terminator required)"

```cpp
--8<-- "examples/basic_json_document__parse_iterator_pair.cpp"
```

Output:

```json
--8<-- "examples/basic_json_document__parse_iterator_pair.output"
```

See also

• parse_copy - deserialize a copy of a compatible input
• accept - check whether the input is valid JSON
• read - (re-)parse into this document, reusing its memory
• owns_source - return whether the document holds its own copy of the text
• load - read a document from an image instead of parsing JSON text
• BasicJsonType::parse - the corresponding function of basic_json

Version history

• Added in version 3.13.0.
• Ill-formed UTF-16 and UTF-32 input (a lone surrogate, a high surrogate that is not followed by its low surrogate, or a code point above U+10FFFF) is rejected with parse_error.101.