JSON for Modern C++  3.5.0

◆ 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 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)
[in]allow_exceptionswhether to throw exceptions in case of a parse error (optional, true by default)
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 <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:110
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:18447
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:110
typename parser::parser_callback_t parser_callback_t
per-element parser callback type
Definition: json.hpp:13503
typename parser::parse_event_t parse_event_t
parser event types
Definition: json.hpp:13452
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:18447
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:110
typename parser::parser_callback_t parser_callback_t
per-element parser callback type
Definition: json.hpp:13503
typename parser::parse_event_t parse_event_t
parser event types
Definition: json.hpp:13452
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:18447
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:110
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:18447
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 18447 of file json.hpp.