JSON for Modern C++ 3.10.4

◆ parse() [2/3]

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, class BinaryType = std::vector<std::uint8_t>>
template<typename InputType >
static basic_json nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::parse ( InputType &&  i,
const parser_callback_t  cb = nullptr,
const bool  allow_exceptions = true,
const bool  ignore_comments = false 
)
inlinestatic
Template Parameters
InputTypeA compatible input, for instance
  • an std::istream object
  • a FILE pointer
  • a C-style array of characters
  • a pointer to a null-terminated string of single byte characters
  • an object obj for which begin(obj) and end(obj) produces a valid pair of iterators.
Parameters
[in]iinput to read from
[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)
[in]ignore_commentswhether comments should be ignored and treated like whitespace (true) or yield a parse error (true); (optional, false 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.101if a parse error occurs; example: ""unexpected end of input; expected string literal""
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 or reading from the input i 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 array.
1#include <iostream>
2#include <iomanip>
3#include <nlohmann/json.hpp>
4
5using json = nlohmann::json;
6
7int main()
8{
9 // a JSON text
10 char text[] = R"(
11 {
12 "Image": {
13 "Width": 800,
14 "Height": 600,
15 "Title": "View from 15th Floor",
16 "Thumbnail": {
17 "Url": "http://www.example.com/image/481989943",
18 "Height": 125,
19 "Width": 100
20 },
21 "Animated" : false,
22 "IDs": [116, 943, 234, 38793]
23 }
24 }
25 )";
26
27 // parse and serialize JSON
28 json j_complete = json::parse(text);
29 std::cout << std::setw(4) << j_complete << "\n\n";
30}
static basic_json parse(InputType &&i, const parser_callback_t cb=nullptr, const bool allow_exceptions=true, const bool ignore_comments=false)
deserialize from a compatible input
Definition: json.hpp:24408
basic_json<> json
default JSON class
Definition: json.hpp:3472

Output (play with this example online):
{
    "Image": {
        "Animated": false,
        "Height": 600,
        "IDs": [
            116,
            943,
            234,
            38793
        ],
        "Thumbnail": {
            "Height": 125,
            "Url": "http://www.example.com/image/481989943",
            "Width": 100
        },
        "Title": "View from 15th Floor",
        "Width": 800
    }
}

The example code above can be translated with
g++ -std=c++11 -Isingle_include doc/examples/parse__array__parser_callback_t.cpp -o parse__array__parser_callback_t 
Example
The example below demonstrates the parse() function with and without callback function.
1#include <iostream>
2#include <iomanip>
3#include <nlohmann/json.hpp>
4
5using json = nlohmann::json;
6
7int main()
8{
9 // a JSON text
10 auto text = R"(
11 {
12 "Image": {
13 "Width": 800,
14 "Height": 600,
15 "Title": "View from 15th Floor",
16 "Thumbnail": {
17 "Url": "http://www.example.com/image/481989943",
18 "Height": 125,
19 "Width": 100
20 },
21 "Animated" : false,
22 "IDs": [116, 943, 234, 38793]
23 }
24 }
25 )";
26
27 // parse and serialize JSON
28 json j_complete = json::parse(text);
29 std::cout << std::setw(4) << j_complete << "\n\n";
30
31
32 // define parser callback
33 json::parser_callback_t cb = [](int depth, json::parse_event_t event, json & parsed)
34 {
35 // skip object elements with key "Thumbnail"
36 if (event == json::parse_event_t::key and parsed == json("Thumbnail"))
37 {
38 return false;
39 }
40 else
41 {
42 return true;
43 }
44 };
45
46 // parse (with callback) and serialize JSON
47 json j_filtered = json::parse(text, cb);
48 std::cout << std::setw(4) << j_filtered << '\n';
49}
detail::parser_callback_t< basic_json > parser_callback_t
per-element parser callback type
Definition: json.hpp:18934
detail::parse_event_t parse_event_t
parser event types
Definition: json.hpp:18883

Output (play with this example online):
{
    "Image": {
        "Animated": false,
        "Height": 600,
        "IDs": [
            116,
            943,
            234,
            38793
        ],
        "Thumbnail": {
            "Height": 125,
            "Url": "http://www.example.com/image/481989943",
            "Width": 100
        },
        "Title": "View from 15th Floor",
        "Width": 800
    }
}

{
    "Image": {
        "Animated": false,
        "Height": 600,
        "IDs": [
            116,
            943,
            234,
            38793
        ],
        "Title": "View from 15th Floor",
        "Width": 800
    }
}
The example code above can be translated with
g++ -std=c++11 -Isingle_include doc/examples/parse__string__parser_callback_t.cpp -o parse__string__parser_callback_t 
Example
The example below demonstrates the parse() function with and without callback function.
1#include <iostream>
2#include <iomanip>
3#include <sstream>
4#include <nlohmann/json.hpp>
5
6using json = nlohmann::json;
7
8int main()
9{
10 // a JSON text
11 auto text = R"(
12 {
13 "Image": {
14 "Width": 800,
15 "Height": 600,
16 "Title": "View from 15th Floor",
17 "Thumbnail": {
18 "Url": "http://www.example.com/image/481989943",
19 "Height": 125,
20 "Width": 100
21 },
22 "Animated" : false,
23 "IDs": [116, 943, 234, 38793]
24 }
25 }
26 )";
27
28 // fill a stream with JSON text
29 std::stringstream ss;
30 ss << text;
31
32 // parse and serialize JSON
33 json j_complete = json::parse(ss);
34 std::cout << std::setw(4) << j_complete << "\n\n";
35
36
37 // define parser callback
38 json::parser_callback_t cb = [](int depth, json::parse_event_t event, json & parsed)
39 {
40 // skip object elements with key "Thumbnail"
41 if (event == json::parse_event_t::key and parsed == json("Thumbnail"))
42 {
43 return false;
44 }
45 else
46 {
47 return true;
48 }
49 };
50
51 // fill a stream with JSON text
52 ss.clear();
53 ss << text;
54
55 // parse (with callback) and serialize JSON
56 json j_filtered = json::parse(ss, cb);
57 std::cout << std::setw(4) << j_filtered << '\n';
58}

Output (play with this example online):
{
    "Image": {
        "Animated": false,
        "Height": 600,
        "IDs": [
            116,
            943,
            234,
            38793
        ],
        "Thumbnail": {
            "Height": 125,
            "Url": "http://www.example.com/image/481989943",
            "Width": 100
        },
        "Title": "View from 15th Floor",
        "Width": 800
    }
}

{
    "Image": {
        "Animated": false,
        "Height": 600,
        "IDs": [
            116,
            943,
            234,
            38793
        ],
        "Title": "View from 15th Floor",
        "Width": 800
    }
}
The example code above can be translated with
g++ -std=c++11 -Isingle_include doc/examples/parse__istream__parser_callback_t.cpp -o parse__istream__parser_callback_t 
Example
The example below demonstrates the parse() function reading from a contiguous container.
1#include <iostream>
2#include <iomanip>
3#include <nlohmann/json.hpp>
4
5using json = nlohmann::json;
6
7int 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);
14 std::cout << std::setw(4) << j_complete << "\n\n";
15}

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__contiguouscontainer__parser_callback_t.cpp -o parse__contiguouscontainer__parser_callback_t 
Since
version 2.0.3 (contiguous containers); version 3.9.0 allowed to ignore comments.

Definition at line 24408 of file json.hpp.