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 exactly what BasicJsonType::parse() accepts, 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.

Template parameters

InputType

A compatible input, for instance:

• a #!cpp std::string, #!cpp std::string_view, or a C-style array of characters
• a pointer to a null-terminated string of single byte characters
• 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, or anything else BasicJsonType::parse() accepts

IteratorType

a compatible iterator type, for instance a pair of pointers such as ptr and ptr + len, or a pair of #!cpp std::string::iterator

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. Additionally throws out_of_range.416 if the input is 4 GiB 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
rvalue #!cpp std::string	owned, moved in without a copy
rvalue byte container other than #!cpp std::string	owned, copied
stream, wide string, 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.

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.