// (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);
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.
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.
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
The parsed document. If allow_exceptions is #!cpp false and the input is not valid JSON, the returned document is discarded; see is_discarded.
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.
Linear in the length of the input.
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.
??? example “Example: (1) borrowed vs. owned input, and errors identical to BasicJsonType::parse()”
```cpp
#include <iostream>
#include <string>
#include <nlohmann/json.hpp>
#include <nlohmann/json_view.hpp>
using json_document = nlohmann::json_document;
int main()
{
std::cout << std::boolalpha;
// an lvalue std::string is BORROWED: the document only stores a pointer
// into `text`, so `text` must outlive `borrowed`
std::string text = R"({"count": 3})";
json_document borrowed = json_document::parse(text);
std::cout << borrowed.owns_source() << '\n'; // false
// an rvalue std::string is MOVED into the document -- no copy of the text
json_document owned = json_document::parse(std::string(R"({"count": 3})"));
std::cout << owned.owns_source() << '\n'; // true
// errors are identical to basic_json::parse: same exception id, message,
// and position, because the library parser runs on the same bytes on a
// failing input
try
{
static_cast<void>(json_document::parse(R"({"count": )"));
}
catch (const nlohmann::json::parse_error& e)
{
std::cout << e.id << '\n';
}
}
```
Output:
```json
false
true
101
```
??? example “Example: (2) parse an iterator range (no NUL terminator required)”
```cpp
#include <iostream>
#include <vector>
#include <nlohmann/json_view.hpp>
using json_document = nlohmann::json_document;
int main()
{
std::cout << std::boolalpha;
// a JSON value embedded in a larger, non-null-terminated buffer (e.g. a
// slice received over the network)
std::vector<char> buffer = {'[', '1', ',', '2', ']', 'j', 'u', 'n', 'k'};
// a pointer pair is BORROWED, exactly like a byte container lvalue: the
// document points into the buffer. (From C++20 on, std::vector<char>
// iterators are borrowed as well; before, they are copied.)
const char* first = buffer.data();
json_document doc = json_document::parse(first, first + 5);
std::cout << doc.root().is_array() << ' ' << doc.root().size() << '\n';
std::cout << doc.owns_source() << '\n'; // false: borrowed
}
```
Output:
```json
true 2
false
```
BasicJsonType::parse - the corresponding function of basic_jsonU+10FFFF) is rejected with parse_error.101.