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);

Deserialize from a compatible input, borrowing or owning it depending on its value category and type (see Notes).
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 take the same inputs as BasicJsonType::parse(). Byte inputs that stay alive can be borrowed; all others (streams, FILE*, wide characters, 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 std::string, std::string_view, or a C-style array of single-byte characters
a pointer to a null-terminated string of single-byte characters (char, signed char, unsigned char, std::uint8_t)
a container for which obj.data() and obj.size() give contiguous single-byte access, e.g. std::vector<char> or std::vector<std::uint8_t>
an std::istream object
a FILE* pointer
wide characters (wchar_t, char16_t, char32_t), which are converted to UTF-8: a wide string object (std::wstring, std::u16string, 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 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

Parameters¶

input (in): Input to parse from.
allow_exceptions (in): whether to throw exceptions in case of a parse error (optional, true by default)
ignore_comments (in): whether comments should be ignored and treated like whitespace (true) or yield a parse error (false); (optional, false by default)
ignore_trailing_commas (in): whether trailing commas in arrays or objects should be ignored and treated like whitespace (true) or yield a parse error (false); (optional, 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 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 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 `std::string`	owned, moved in without a copy
other rvalue byte container (including a `const` rvalue `std::string`)	owned, copied
stream, `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. const char*, std::uint8_t*) is borrowed. From C++20 on, so is any other contiguous iterator over single bytes, such as std::vector<char>::iterator or 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 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 bool where the flags are expected -- for example 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: parse(ptr, ptr + len). The same holds for parse_copy, accept, and read.

Examples¶

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

#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:

false
true
101

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

#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
}