JSON for Modern C++  3.7.0

◆ parse() [2/2]

template<template< typename U, typename V, typename... Args > class ObjectType = std::map, template< typename U, typename... Args > class ArrayType = std::vector, class StringType = std::string, class BooleanType = bool, class NumberIntegerType = std::int64_t, class NumberUnsignedType = std::uint64_t, class NumberFloatType = double, template< typename U > class AllocatorType = std::allocator, template< typename T, typename SFINAE=void > class JSONSerializer = adl_serializer>
template<class IteratorType , typename std::enable_if< std::is_base_of< std::random_access_iterator_tag, typename std::iterator_traits< IteratorType >::iterator_category >::value, int >::type = 0>
static basic_json nlohmann::basic_json::parse ( IteratorType  first,
IteratorType  last,
const parser_callback_t  cb = nullptr,
const bool  allow_exceptions = true 
)
inlinestatic

This function reads from an iterator range of a container with contiguous storage of 1-byte values. Compatible container types include std::vector, std::string, std::array, std::valarray, and std::initializer_list. Furthermore, C-style arrays can be used with std::begin()/std::end(). User-defined containers can be used as long as they implement random-access iterators and a contiguous storage.

Precondition
The iterator range is contiguous. Violating this precondition yields undefined behavior. This precondition is enforced with an assertion.
Each element in the range has a size of 1 byte. Violating this precondition yields undefined behavior. This precondition is enforced with a static assertion.
Warning
There is no way to enforce all preconditions at compile-time. If the function is called with noncompliant iterators and with assertions switched off, the behavior is undefined and will most likely yield segmentation violation.
Template Parameters
IteratorTypeiterator of container with contiguous storage
Parameters
[in]firstbegin of the range to parse (included)
[in]lastend of the range to parse (excluded)
[in]cba parser callback function of type parser_callback_t which is used to control the deserialization by filtering unwanted values (optional)
[in]allow_exceptionswhether to throw exceptions in case of a parse error (optional, true by default)
Returns
deserialized JSON value; in case of a parse error and allow_exceptions set to false, the return value will be value_t::discarded.
Exceptions
parse_error.101in case of an unexpected token
parse_error.102if to_unicode fails or surrogate error
parse_error.103if to_unicode fails
Complexity
Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the parser callback function cb has a super-linear complexity.
Note
A UTF-8 byte order mark is silently ignored.
Example
The example below demonstrates the parse() function reading from an iterator range.
1 #include <iostream>
2 #include <iomanip>
3 #include <nlohmann/json.hpp>
4 
5 using json = nlohmann::json;
6 
7 int main()
8 {
9  // a JSON text given as std::vector
10  std::vector<uint8_t> text = {'[', '1', ',', '2', ',', '3', ']', '\0'};
11 
12  // parse and serialize JSON
13  json j_complete = json::parse(text.begin(), text.end());
14  std::cout << std::setw(4) << j_complete << "\n\n";
15 }
basic_json<> json
default JSON class
Definition: json.hpp:2355
static basic_json parse(detail::input_adapter &&i, const parser_callback_t cb=nullptr, const bool allow_exceptions=true)
deserialize from a compatible input
Definition: json.hpp:20571

Output (play with this example online):
[
    1,
    2,
    3
]

The example code above can be translated with
g++ -std=c++11 -Isingle_include doc/examples/parse__iteratortype__parser_callback_t.cpp -o parse__iteratortype__parser_callback_t 
Since
version 2.0.3

Definition at line 20703 of file json.hpp.