JSON for Modern C++  3.6.1

◆ parse() [1/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>
static JSON_NODISCARD 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.
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)
[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.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 <iomanip>
3 #include <nlohmann/json.hpp>
4 
5 using json = nlohmann::json;
6 
7 int 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 }
basic_json<> json
default JSON class
Definition: json.hpp:871
static JSON_NODISCARD 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:18869

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 
5 using json = nlohmann::json;
6 
7 int 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 }
basic_json<> json
default JSON class
Definition: json.hpp:871
typename parser::parser_callback_t parser_callback_t
per-element parser callback type
Definition: json.hpp:13886
static JSON_NODISCARD 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:18869
typename parser::parse_event_t parse_event_t
parser event types
Definition: json.hpp:13835

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 
6 using json = nlohmann::json;
7 
8 int 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 }
basic_json<> json
default JSON class
Definition: json.hpp:871
typename parser::parser_callback_t parser_callback_t
per-element parser callback type
Definition: json.hpp:13886
static JSON_NODISCARD 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:18869
typename parser::parse_event_t parse_event_t
parser event types
Definition: json.hpp:13835

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 
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);
14  std::cout << std::setw(4) << j_complete << "\n\n";
15 }
basic_json<> json
default JSON class
Definition: json.hpp:871
static JSON_NODISCARD 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:18869

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)

Definition at line 18869 of file json.hpp.