nlohmann::basic_json::parse¶

// (1)
template<typenameInputType>
staticbasic_jsonparse(InputType&&i,
constparser_callback_tcb=nullptr,
constboolallow_exceptions=true,
constboolignore_comments=false,
constboolignore_trailing_commas=false);
// (2)
template<typenameIteratorType>
staticbasic_jsonparse(IteratorTypefirst,IteratorTypelast,
constparser_callback_tcb=nullptr,
constboolallow_exceptions=true,
constboolignore_comments=false,
constboolignore_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.

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.

Invalid Unicode escapes and unpaired surrogates in the input are reported as parse_error.101 with a detailed message.

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>
usingjson=nlohmann::json;
intmain()
{
// a JSON text
chartext[]=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
jsonj_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>
usingjson=nlohmann::json;
intmain()
{
// a JSON text
autotext=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
jsonj_complete=json::parse(text);
std::cout<<std::setw(4)<<j_complete<<"\n\n";
// define parser callback
json::parser_callback_tcb=[](intdepth,json::parse_event_tevent,json&parsed)
{
// skip object elements with key "Thumbnail"
if(event==json::parse_event_t::keyandparsed==json("Thumbnail"))
{
returnfalse;
}
else
{
returntrue;
}
};
// parse (with callback) and serialize JSON
jsonj_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>
usingjson=nlohmann::json;
intmain()
{
// a JSON text
autotext=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::stringstreamss;
ss<<text;
// parse and serialize JSON
jsonj_complete=json::parse(ss);
std::cout<<std::setw(4)<<j_complete<<"\n\n";
// define parser callback
json::parser_callback_tcb=[](intdepth,json::parse_event_tevent,json&parsed)
{
// skip object elements with key "Thumbnail"
if(event==json::parse_event_t::keyandparsed==json("Thumbnail"))
{
returnfalse;
}
else
{
returntrue;
}
};
// fill a stream with JSON text
ss.clear();
ss<<text;
// parse (with callback) and serialize JSON
jsonj_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>
usingjson=nlohmann::json;
intmain()
{
// a JSON text given as std::vector
std::vector<std::uint8_t>text={'[','1',',','2',',','3',']','0円'};
// parse and serialize JSON
jsonj_complete=json::parse(text);
std::cout<<std::setw(4)<<j_complete<<"\n\n";
}

Output:

[
1,
2,
3
]

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>
usingjson=nlohmann::json;
intmain()
{
// a JSON text given as string that is not null-terminated
constchar*ptr="[1,2,3]another value";
// parse and serialize JSON
jsonj_complete=json::parse(ptr,ptr+7);
std::cout<<std::setw(4)<<j_complete<<"\n\n";
}

Output:

[
1,
2,
3
]

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>
usingjson=nlohmann::json;
intmain()
{
// 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
jsonj_complete=json::parse(input.begin(),input.begin()+7);
std::cout<<std::setw(4)<<j_complete<<"\n\n";
}

Output:

[
1,
2,
3
]

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>
usingjson=nlohmann::json;
intmain()
{
// an invalid JSON text
std::stringtext=R"(
 {
 "key": "value without closing quotes
 }
)";
// parse with exceptions
try
{
jsonj=json::parse(text);
}
catch(constjson::parse_error&e)
{
std::cout<<e.what()<<std::endl;
}
// parse without exceptions
jsonj=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]parseerroratline4,column0:syntaxerrorwhileparsingvalue-invalidstring:controlcharacterU+000A(LF)mustbeescapedto\u000Aor\n;lastread:'"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>
usingjson=nlohmann::json;
intmain()
{
std::strings=R"(
 {
 // update in 2006: removed Pluto
 "planets": ["Mercury", "Venus", "Earth", "Mars",
 "Jupiter", "Uranus", "Neptune" /*, "Pluto" */]
 }
)";
try
{
jsonj=json::parse(s);
}
catch(json::exception&e)
{
std::cout<<e.what()<<std::endl;
}
jsonj=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>
usingjson=nlohmann::json;
intmain()
{
std::strings=R"(
 {
 "planets": [
 "Mercury",
 "Venus",
 "Earth",
 "Mars",
 "Jupiter",
 "Uranus",
 "Neptune",
 ]
 }
)";
try
{
jsonj=json::parse(s);
}
catch(json::exception&e)
{
std::cout<<e.what()<<std::endl;
}
jsonj=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.x.

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¶