nlohmann::basic_json::parse¶

// (1)
template<typename InputType>
static basic_json parse(InputType&& i,
                        const parser_callback_t cb = nullptr,
                        const bool allow_exceptions = true,
                        const bool ignore_comments = false,
                        const bool ignore_trailing_commas = false);

// (2)
template<typename IteratorType>
static basic_json parse(IteratorType first, IteratorType last,
                        const parser_callback_t cb = nullptr,
                        const bool allow_exceptions = true,
                        const bool ignore_comments = false,
                        const bool ignore_trailing_commas = false);

Deserialize from a compatible input.
Deserialize from a pair of character iterators

The value_type of the iterator must be an integral type with size of 1, 2, or 4 bytes, which will be interpreted respectively as UTF-8, UTF-16, and UTF-32.

Template parameters¶

InputType

A compatible input, for instance:

an std::istream object
a FILE pointer (throws if null)
a C-style array of characters
a pointer to a null-terminated string of single byte characters (throws if null)
a std::string
an object obj for which begin(obj) and end(obj) produces a valid pair of iterators.

IteratorType

a compatible iterator type, for instance.

a pair of std::string::iterator or std::vector<std::uint8_t>::iterator
a pair of pointers such as ptr and ptr + len

Parameters¶

i (in): Input to parse from.
cb (in): a parser callback function of type parser_callback_t which is used to control the deserialization by filtering unwanted values (optional)
allow_exceptions (in): whether to throw exceptions in case of a parse error (optional, true by default)
ignore_comments (in): whether comments should be ignored and treated like whitespace (true) or yield a parse error (false); (optional, false by default)
ignore_trailing_commas (in): whether trailing commas in arrays or objects should be ignored and treated like whitespace (true) or yield a parse error (false); (optional, false by default)
first (in): iterator to the start of a character range
last (in): iterator to the end of a character range

Return value¶

Deserialized JSON value; in case of a parse error and allow_exceptions set to false, the return value will be value_t::discarded. The latter can be checked with is_discarded.

Exception safety¶

Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

Exceptions¶

Throws parse_error.101 in case of an unexpected token, or empty input like a null FILE* or char* pointer.
Throws parse_error.102 if to_unicode fails or surrogate error.
Throws parse_error.103 if 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 (1) the input i or (2) the iterator range [first, last] has a super-linear complexity.

Notes¶

A UTF-8 byte order mark is silently ignored.

Examples¶

Parsing from a character array

The example below demonstrates the parse() function reading from an array.

#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // a JSON text
    char text[] = R"(
    {
        "Image": {
            "Width":  800,
            "Height": 600,
            "Title":  "View from 15th Floor",
            "Thumbnail": {
                "Url":    "http://www.example.com/image/481989943",
                "Height": 125,
                "Width":  100
            },
            "Animated" : false,
            "IDs": [116, 943, 234, 38793]
        }
    }
    )";

    // parse and serialize JSON
    json j_complete = json::parse(text);
    std::cout << std::setw(4) << j_complete << "\n\n";
}

Output:

{
    "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
    }
}

Parsing from a string

The example below demonstrates the parse() function with and without callback function.

#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // a JSON text
    auto text = R"(
    {
        "Image": {
            "Width":  800,
            "Height": 600,
            "Title":  "View from 15th Floor",
            "Thumbnail": {
                "Url":    "http://www.example.com/image/481989943",
                "Height": 125,
                "Width":  100
            },
            "Animated" : false,
            "IDs": [116, 943, 234, 38793]
        }
    }
    )";

    // parse and serialize JSON
    json j_complete = json::parse(text);
    std::cout << std::setw(4) << j_complete << "\n\n";

    // define parser callback
    json::parser_callback_t cb = [](int depth, json::parse_event_t event, json & parsed)
    {
        // skip object elements with key "Thumbnail"
        if (event == json::parse_event_t::key and parsed == json("Thumbnail"))
        {
            return false;
        }
        else
        {
            return true;
        }
    };

    // parse (with callback) and serialize JSON
    json j_filtered = json::parse(text, cb);
    std::cout << std::setw(4) << j_filtered << '\n';
}

Output:

{
    "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
    }
}

Parsing from an input stream

The example below demonstrates the parse() function with and without callback function.

#include <iostream>
#include <iomanip>
#include <sstream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // a JSON text
    auto text = R"(
    {
        "Image": {
            "Width":  800,
            "Height": 600,
            "Title":  "View from 15th Floor",
            "Thumbnail": {
                "Url":    "http://www.example.com/image/481989943",
                "Height": 125,
                "Width":  100
            },
            "Animated" : false,
            "IDs": [116, 943, 234, 38793]
        }
    }
    )";

    // fill a stream with JSON text
    std::stringstream ss;
    ss << text;

    // parse and serialize JSON
    json j_complete = json::parse(ss);
    std::cout << std::setw(4) << j_complete << "\n\n";

    // define parser callback
    json::parser_callback_t cb = [](int depth, json::parse_event_t event, json & parsed)
    {
        // skip object elements with key "Thumbnail"
        if (event == json::parse_event_t::key and parsed == json("Thumbnail"))
        {
            return false;
        }
        else
        {
            return true;
        }
    };

    // fill a stream with JSON text
    ss.clear();
    ss << text;

    // parse (with callback) and serialize JSON
    json j_filtered = json::parse(ss, cb);
    std::cout << std::setw(4) << j_filtered << '\n';
}

Output:

{
    "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
    }
}

Parsing from a contiguous container

The example below demonstrates the parse() function reading from a contiguous container.

#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // a JSON text given as std::vector
    std::vector<std::uint8_t> text = {'[', '1', ',', '2', ',', '3', ']', '\0'};

    // parse and serialize JSON
    json j_complete = json::parse(text);
    std::cout << std::setw(4) << j_complete << "\n\n";
}

Output:

Parsing from a non-null-terminated string

The example below demonstrates the parse() function reading from a string that is not null-terminated.

#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // a JSON text given as string that is not null-terminated
    const char* ptr = "[1,2,3]another value";

    // parse and serialize JSON
    json j_complete = json::parse(ptr, ptr + 7);
    std::cout << std::setw(4) << j_complete << "\n\n";
}

Output:

Parsing from an iterator pair

The example below demonstrates the parse() function reading from an iterator pair.

#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // a JSON text given an input with other values
    std::vector<std::uint8_t> input = {'[', '1', ',', '2', ',', '3', ']', 'o', 't', 'h', 'e', 'r'};

    // parse and serialize JSON
    json j_complete = json::parse(input.begin(), input.begin() + 7);
    std::cout << std::setw(4) << j_complete << "\n\n";
}

Output:

Effect of allow_exceptions parameter

The example below demonstrates the effect of the allow_exceptions parameter in the ´parse()` function.

#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    // an invalid JSON text
    std::string text = R"(
    {
        "key": "value without closing quotes
    }
    )";

    // parse with exceptions
    try
    {
        json j = json::parse(text);
    }
    catch (const json::parse_error& e)
    {
        std::cout << e.what() << std::endl;
    }

    // parse without exceptions
    json j = json::parse(text, nullptr, false);

    if (j.is_discarded())
    {
        std::cout << "the input is invalid JSON" << std::endl;
    }
    else
    {
        std::cout << "the input is valid JSON: " << j << std::endl;
    }
}

Output:

[json.exception.parse_error.101] parse error at line 4, column 0: syntax error while parsing value - invalid string: control character U+000A (LF) must be escaped to \u000A or \n; last read: '"value without closing quotes<U+000A>'
the input is invalid JSON

Effect of ignore_comments parameter

The example below demonstrates the effect of the ignore_comments parameter in the parse() function.

#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    std::string s = R"(
    {
        // update in 2006: removed Pluto
        "planets": ["Mercury", "Venus", "Earth", "Mars",
                    "Jupiter", "Uranus", "Neptune" /*, "Pluto" */]
    }
    )";

    try
    {
        json j = json::parse(s);
    }
    catch (json::exception& e)
    {
        std::cout << e.what() << std::endl;
    }

    json j = json::parse(s,
                         /* callback */ nullptr,
                         /* allow exceptions */ true,
                         /* ignore_comments */ true);
    std::cout << j.dump(2) << '\n';
}

Output:

[json.exception.parse_error.101] parse error at line 3, column 9: syntax error while parsing object key - invalid literal; last read: '<U+000A>    {<U+000A>        /'; expected string literal
{
  "planets": [
    "Mercury",
    "Venus",
    "Earth",
    "Mars",
    "Jupiter",
    "Uranus",
    "Neptune"
  ]
}

Effect of ignore_trailing_commas parameter

The example below demonstrates the effect of the ignore_trailing_commas parameter in the parse() function.

#include <iostream>
#include <nlohmann/json.hpp>

using json = nlohmann::json;

int main()
{
    std::string s = R"(
    {
        "planets": [
            "Mercury",
            "Venus",
            "Earth",
            "Mars",
            "Jupiter",
            "Uranus",
            "Neptune",
        ]
    }
    )";

    try
    {
        json j = json::parse(s);
    }
    catch (json::exception& e)
    {
        std::cout << e.what() << std::endl;
    }

    json j = json::parse(s,
                         /* callback */ nullptr,
                         /* allow exceptions */ true,
                         /* ignore_comments */ false,
                         /* ignore_trailing_commas */ true);
    std::cout << j.dump(2) << '\n';
}

Output:

[json.exception.parse_error.101] parse error at line 11, column 9: syntax error while parsing value - unexpected ']'; expected '[', '{', or a literal
{
  "planets": [
    "Mercury",
    "Venus",
    "Earth",
    "Mars",
    "Jupiter",
    "Uranus",
    "Neptune"
  ]
}

Version history¶

Added in version 1.0.0.
Overload for contiguous containers (1) added in version 2.0.3.
Ignoring comments via ignore_comments added in version 3.9.0.
Changed runtime assertion in case of FILE* null pointers to exception in version 3.12.0.
Added ignore_trailing_commas in version 3.12.1.

Deprecation

Overload (2) replaces calls to parse with a pair of iterators as their first parameter which has been deprecated in version 3.8.0. This overload will be removed in version 4.0.0. Please replace all calls like parse({ptr, ptr+len}, ...); with parse(ptr, ptr+len, ...);.

You should be warned by your compiler with a -Wdeprecated-declarations warning if you are using a deprecated function.

nlohmann::basic_json::parse¶

Template parameters¶

Parameters¶

Return value¶

Exception safety¶

Exceptions¶

Complexity¶

Notes¶

Examples¶

See also¶

Version history¶