nlohmann::basic_json¶

Defined in header <nlohmann/json.hpp>

template<
template<typenameU,typenameV,typename...Args>classObjectType=std::map,
template<typenameU,typename...Args>classArrayType=std::vector,
classStringType=std::string,
classBooleanType=bool,
classNumberIntegerType=std::int64_t,
classNumberUnsignedType=std::uint64_t,
classNumberFloatType=double,
template<typenameU>classAllocatorType=std::allocator,
template<typenameT,typenameSFINAE=void>classJSONSerializer=adl_serializer,
classBinaryType=std::vector<std::uint8_t>,
classCustomBaseClass=void
>
classbasic_json;

Template parameters¶

Specializations¶

• json - default specialization
• ordered_json - a specialization that maintains the insertion order of object keys

Iterator invalidation¶

All operations that add values to an array (push_back , operator+=, emplace_back, insert, and operator[] for a non-existing index) can yield a reallocation, in which case all iterators (including the end() iterator) and all references to the elements are invalidated.

For ordered_json, also all operations that add a value to an object (push_back, operator+=, emplace, insert, update, and operator[] for a non-existing key) can yield a reallocation, in which case all iterators (including the end() iterator) and all references to the elements are invalidated.

Requirements¶

The class satisfies the following concept requirements:

Basic¶

• DefaultConstructible: JSON values can be default-constructed. The result will be a JSON null value.
• MoveConstructible: A JSON value can be constructed from an rvalue argument.
• CopyConstructible: A JSON value can be copy-constructed from an lvalue expression.
• MoveAssignable: A JSON value can be assigned from an rvalue argument.
• CopyAssignable: A JSON value can be copy-assigned from an lvalue expression.
• Destructible: JSON values can be destructed.

Layout¶

• StandardLayoutType: JSON values have standard layout: All non-static data members are private and standard layout types, the class has no virtual functions or (virtual) base classes.

Library-wide¶

• EqualityComparable: JSON values can be compared with ==, see operator==.
• LessThanComparable: JSON values can be compared with <, see operator<.
• Swappable: Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of other compatible types, using unqualified function swap.
• NullablePointer: JSON values can be compared against std::nullptr_t objects which are used to model the null value.

Container¶

• Container: JSON values can be used like STL containers and provide iterator access.
• ReversibleContainer: JSON values can be used like STL containers and provide reverse iterator access.

Member types¶

• adl_serializer - the default serializer
• value_t - the JSON type enumeration
• json_pointer - JSON Pointer implementation
• json_serializer - type of the serializer to for conversions from/to JSON
• error_handler_t - type to choose behavior on decoding errors
• cbor_tag_handler_t - type to choose how to handle CBOR tags
• initializer_list_t - type for initializer lists of basic_json values
• input_format_t - type to choose the format to parse
• json_sax_t - type for SAX events

Exceptions¶

• exception - general exception of the basic_json class
  • parse_error - exception indicating a parse error
  • invalid_iterator - exception indicating errors with iterators
  • type_error - exception indicating executing a member function with a wrong type
  • out_of_range - exception indicating access out of the defined range
  • other_error - exception indicating other library errors

Container types¶

JSON value data types¶

• array_t - type for arrays
• binary_t - type for binary arrays
• boolean_t - type for booleans
• default_object_comparator_t - default comparator for objects
• number_float_t - type for numbers (floating-point)
• number_integer_t - type for numbers (integer)
• number_unsigned_t - type for numbers (unsigned)
• object_comparator_t - comparator for objects
• object_t - type for objects
• string_t - type for strings

Parser callback¶

• parse_event_t - parser event types
• parser_callback_t - per-element parser callback type

Member functions¶

• (constructor)
• (destructor)
• operator= - copy assignment
• array (static) - explicitly create an array
• binary (static) - explicitly create a binary array
• object (static) - explicitly create an object

Object inspection¶

Functions to inspect the type of a JSON value.

• type - return the type of the JSON value
• operator value_t - return the type of the JSON value
• type_name - return the type as string
• is_primitive - return whether the type is primitive
• is_structured - return whether the type is structured
• is_null - return whether the value is null
• is_boolean - return whether the value is a boolean
• is_number - return whether the value is a number
• is_number_integer - return whether the value is an integer number
• is_number_unsigned - return whether the value is an unsigned integer number
• is_number_float - return whether the value is a floating-point number
• is_object - return whether the value is an object
• is_array - return whether the value is an array
• is_string - return whether the value is a string
• is_binary - return whether the value is a binary array
• is_discarded - return whether the value is discarded

Optional functions to access the diagnostic positions.

• start_pos - return the start position of the value
• end_pos - return the one past the end position of the value

Value access¶

Direct access to the stored value of a JSON value.

• get - get a value
• get_to - get a value and write it to a destination
• get_ptr - get a pointer value
• get_ref - get a reference value
• operator ValueType - get a value
• get_binary - get a binary value

Element access¶

Access to the JSON value

• at - access specified element with bounds checking
• operator[] - access specified element
• value - access specified object element with default value
• front - access the first element
• back - access the last element

Lookup¶

• find - find an element in a JSON object
• count - returns the number of occurrences of a key in a JSON object
• contains - check the existence of an element in a JSON object

Iterators¶

• begin - returns an iterator to the first element
• cbegin - returns a const iterator to the first element
• end - returns an iterator to one past the last element
• cend - returns a const iterator to one past the last element
• rbegin - returns an iterator to the reverse-beginning
• rend - returns an iterator to the reverse-end
• crbegin - returns a const iterator to the reverse-beginning
• crend - returns a const iterator to the reverse-end
• items - wrapper to access iterator member functions in range-based for

Capacity¶

• empty - checks whether the container is empty
• size - returns the number of elements
• max_size - returns the maximum possible number of elements

Modifiers¶

• clear - clears the contents
• push_back - add a value to an array/object
• operator+= - add a value to an array/object
• emplace_back - add a value to an array
• emplace - add a value to an object if a key does not exist
• erase - remove elements
• insert - inserts elements
• update - updates a JSON object from another object, overwriting existing keys
• swap - exchanges the values

Lexicographical comparison operators¶

• operator== - comparison: equal
• operator!= - comparison: not equal
• operator< - comparison: less than
• operator> - comparison: greater than
• operator<= - comparison: less than or equal
• operator>= - comparison: greater than or equal
• operator<=> - comparison: 3-way

Serialization / Dumping¶

• dump - serialization

Deserialization / Parsing¶

• parse (static) - deserialize from a compatible input
• accept (static) - check if the input is valid JSON
• sax_parse (static) - generate SAX events

JSON Pointer functions¶

• flatten - return flattened JSON value
• unflatten - unflatten a previously flattened JSON value

JSON Patch functions¶

• patch - applies a JSON patch
• patch_inplace - applies a JSON patch in place
• diff (static) - creates a diff as a JSON patch

JSON Merge Patch functions¶

• merge_patch - applies a JSON Merge Patch

Static functions¶

• meta - returns version information on the library
• get_allocator - returns the allocator associated with the container

Binary formats¶

• from_bjdata (static) - create a JSON value from an input in BJData format
• from_bson (static) - create a JSON value from an input in BSON format
• from_cbor (static) - create a JSON value from an input in CBOR format
• from_msgpack (static) - create a JSON value from an input in MessagePack format
• from_ubjson (static) - create a JSON value from an input in UBJSON format
• to_bjdata (static) - create a BJData serialization of a given JSON value
• to_bson (static) - create a BSON serialization of a given JSON value
• to_cbor (static) - create a CBOR serialization of a given JSON value
• to_msgpack (static) - create a MessagePack serialization of a given JSON value
• to_ubjson (static) - create a UBJSON serialization of a given JSON value

Non-member functions¶

• operator<<(std::ostream&) - serialize to stream
• operator>>(std::istream&) - deserialize from stream
• to_string - user-defined to_string function for JSON values

Literals¶

• operator""_json - user-defined string literal for JSON values

Helper classes¶

• std::hash<basic_json> - return a hash value for a JSON object
• std::swap<basic_json> - exchanges the values of two JSON objects

Examples¶

#include<iostream>
#include<iomanip>
#include<nlohmann/json.hpp>
usingjson=nlohmann::json;
intmain()
{
// create a JSON object
jsonj=
{
{"pi",3.141},
{"happy",true},
{"name","Niels"},
{"nothing",nullptr},
{
"answer",{
{"everything",42}
}
},
{"list",{1,0,2}},
{
"object",{
{"currency","USD"},
{"value",42.99}
}
}
};
// add new values
j["new"]["key"]["value"]={"another","list"};
// count elements
autos=j.size();
j["size"]=s;
// pretty print with indent of 4 spaces
std::cout<<std::setw(4)<<j<<'\n';
}

{
"answer":{
"everything":42
},
"happy":true,
"list":[
1,
0,
2
],
"name":"Niels",
"new":{
"key":{
"value":[
"another",
"list"
]
}
},
"nothing":null,
"object":{
"currency":"USD",
"value":42.99
},
"pi":3.141,
"size":8
}

See also¶

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format

Version history¶

• Added in version 1.0.0.