JSON for Modern C++  3.0.1

◆ parse() [1/3]

template<template< typename, typename, typename... > class ObjectType = std::map, template< typename, typename... > 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 > class AllocatorType = std::allocator, template< typename, typename=void > class JSONSerializer = adl_serializer>
static basic_json nlohmann::basic_json::parse ( detail::input_adapter  i,
const parser_callback_t  cb = nullptr,
const bool  allow_exceptions = true 
)
inlinestatic

This function reads from a compatible input. Examples are:

  • an array of 1-byte values
  • strings with character/literal type with size of 1 byte
  • input streams
  • 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
Each element of the container has a size of 1 byte. Violating this precondition yields undefined behavior. This precondition is enforced with a static assertion.
The container storage is contiguous. Violating this precondition yields undefined behavior. This precondition is enforced with an assertion.
Each element of the container 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 a noncompliant container and with assertions switched off, the behavior is undefined and will most likely yield segmentation violation.
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)
Returns
result of the deserialization
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 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 "json.hpp"
3 
4 using json = nlohmann::json;
5 
6 int main()
7 {
8  // a JSON text
9  char text[] = R"(
10  {
11  "Image": {
12  "Width": 800,
13  "Height": 600,
14  "Title": "View from 15th Floor",
15  "Thumbnail": {
16  "Url": "http://www.example.com/image/481989943",
17  "Height": 125,
18  "Width": 100
19  },
20  "Animated" : false,
21  "IDs": [116, 943, 234, 38793]
22  }
23  }
24  )";
25 
26  // parse and serialize JSON
27  json j_complete = json::parse(text);
28  std::cout << std::setw(4) << j_complete << "\n\n";
29 }
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:13045
basic_json<> json
default JSON class
Definition: json.hpp:14379

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 -Isrc 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 "json.hpp"
3 
4 using json = nlohmann::json;
5 
6 int main()
7 {
8  // a JSON text
9  auto text = R"(
10  {
11  "Image": {
12  "Width": 800,
13  "Height": 600,
14  "Title": "View from 15th Floor",
15  "Thumbnail": {
16  "Url": "http://www.example.com/image/481989943",
17  "Height": 125,
18  "Width": 100
19  },
20  "Animated" : false,
21  "IDs": [116, 943, 234, 38793]
22  }
23  }
24  )";
25 
26  // parse and serialize JSON
27  json j_complete = json::parse(text);
28  std::cout << std::setw(4) << j_complete << "\n\n";
29 
30 
31  // define parser callback
32  json::parser_callback_t cb = [](int depth, json::parse_event_t event, json & parsed)
33  {
34  // skip object elements with key "Thumbnail"
35  if (event == json::parse_event_t::key and parsed == json("Thumbnail"))
36  {
37  return false;
38  }
39  else
40  {
41  return true;
42  }
43  };
44 
45  // parse (with callback) and serialize JSON
46  json j_filtered = json::parse(text, cb);
47  std::cout << std::setw(4) << j_filtered << '\n';
48 }
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:13045
basic_json<> json
default JSON class
Definition: json.hpp:14379
typename parser::parser_callback_t parser_callback_t
per-element parser callback type
Definition: json.hpp:8313
typename parser::parse_event_t parse_event_t
parser event types
Definition: json.hpp:8262

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 -Isrc 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 "json.hpp"
3 
4 using json = nlohmann::json;
5 
6 int main()
7 {
8  // a JSON text
9  auto text = R"(
10  {
11  "Image": {
12  "Width": 800,
13  "Height": 600,
14  "Title": "View from 15th Floor",
15  "Thumbnail": {
16  "Url": "http://www.example.com/image/481989943",
17  "Height": 125,
18  "Width": 100
19  },
20  "Animated" : false,
21  "IDs": [116, 943, 234, 38793]
22  }
23  }
24  )";
25 
26  // fill a stream with JSON text
27  std::stringstream ss;
28  ss << text;
29 
30  // parse and serialize JSON
31  json j_complete = json::parse(ss);
32  std::cout << std::setw(4) << j_complete << "\n\n";
33 
34 
35  // define parser callback
36  json::parser_callback_t cb = [](int depth, json::parse_event_t event, json & parsed)
37  {
38  // skip object elements with key "Thumbnail"
39  if (event == json::parse_event_t::key and parsed == json("Thumbnail"))
40  {
41  return false;
42  }
43  else
44  {
45  return true;
46  }
47  };
48 
49  // fill a stream with JSON text
50  ss.clear();
51  ss << text;
52 
53  // parse (with callback) and serialize JSON
54  json j_filtered = json::parse(ss, cb);
55  std::cout << std::setw(4) << j_filtered << '\n';
56 }
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:13045
basic_json<> json
default JSON class
Definition: json.hpp:14379
typename parser::parser_callback_t parser_callback_t
per-element parser callback type
Definition: json.hpp:8313
typename parser::parse_event_t parse_event_t
parser event types
Definition: json.hpp:8262

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 -Isrc 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 "json.hpp"
3 
4 using json = nlohmann::json;
5 
6 int main()
7 {
8  // a JSON text given as std::vector
9  std::vector<uint8_t> text = {'[', '1', ',', '2', ',', '3', ']', '\0'};
10 
11  // parse and serialize JSON
12  json j_complete = json::parse(text);
13  std::cout << std::setw(4) << j_complete << "\n\n";
14 }
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:13045
basic_json<> json
default JSON class
Definition: json.hpp:14379

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


The example code above can be translated with
g++ -std=c++11 -Isrc doc/examples/parse__contiguouscontainer__parser_callback_t.cpp -o parse__contiguouscontainer__parser_callback_t 
Since
version 2.0.3 (contiguous containers)

Definition at line 13045 of file json.hpp.