218 lines
9.5 KiB
Markdown
218 lines
9.5 KiB
Markdown
# <small>nlohmann::basic_json_document::</small>parse
|
|
|
|
```cpp
|
|
// (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()`](../basic_json/parse.md), with the same
|
|
`ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](index.md) (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, `#!cpp FILE*`, wide characters, non-contiguous
|
|
iterators) are read into a copy that the document owns -- see the Notes. Use [`parse_copy()`](parse_copy.md) to get an
|
|
owned copy of a borrowable input as well.
|
|
|
|
## Template parameters
|
|
|
|
`InputType`
|
|
: A compatible input, for instance:
|
|
|
|
- a `#!cpp std::string`, `#!cpp std::string_view`, 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
|
|
|
|
## 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`](is_discarded.md).
|
|
|
|
## Exceptions
|
|
|
|
Throws the same exception [`BasicJsonType::parse()`](../basic_json/parse.md) 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`](../../home/exceptions.md#jsonexceptionout_of_range416) if the input is 4294967280 bytes (4 GiB
|
|
minus 16 bytes) or larger, a size [`BasicJsonType::parse()`](../basic_json/parse.md) 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`](owns_source.md) to check which happened after a call, and the
|
|
[feature page](../../features/json_view.md) for the reasoning.
|
|
|
|
**Numbers.** As for [`BasicJsonType::parse()`](../basic_json/parse.md), 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`](parse_copy.md), [`accept`](accept.md), and [`read`](read.md).
|
|
|
|
## Examples
|
|
|
|
??? 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
|
|
|
|
```
|
|
|
|
## See also
|
|
|
|
- [parse_copy](parse_copy.md) - deserialize a copy of a compatible input
|
|
- [accept](accept.md) - check whether the input is valid JSON
|
|
- [read](read.md) - (re-)parse into this document, reusing its memory
|
|
- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
|
|
- [load](load.md) - read a document from an image instead of parsing JSON text
|
|
- [`BasicJsonType::parse`](../basic_json/parse.md) - the corresponding function of `basic_json`
|
|
|
|
## Version history
|
|
|
|
- Added in version 3.13.0.
|