nlohmann::basic_json¶

Defined in header <nlohmann/json.hpp>

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,
    class BinaryType = std::vector<std::uint8_t>,
    class CustomBaseClass = void
>
class basic_json;

Template parameters¶

Template parameter	Description	Derived type
`ObjectType`	type for JSON objects	`object_t`
`ArrayType`	type for JSON arrays	`array_t`
`StringType`	type for JSON strings and object keys	`string_t`
`BooleanType`	type for JSON booleans	`boolean_t`
`NumberIntegerType`	type for JSON integer numbers	`number_integer_t`
`NumberUnsignedType`	type for JSON unsigned integer numbers	`number_unsigned_t`
`NumberFloatType`	type for JSON floating-point numbers	`number_float_t`
`AllocatorType`	type of the allocator to use
`JSONSerializer`	the serializer to resolve internal calls to `to_json()` and `from_json()`	`json_serializer`
`BinaryType`	type for binary arrays	`binary_t`
`CustomBaseClass`	extension point for user code	`json_base_class_t`

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¶

Type	Definition
`value_type`	`basic_json`
`reference`	`value_type&`
`const_reference`	`const value_type&`
`difference_type`	`std::ptrdiff_t`
`size_type`	`std::size_t`
`allocator_type`	`AllocatorType<basic_json>`
`pointer`	`std::allocator_traits<allocator_type>::pointer`
`const_pointer`	`std::allocator_traits<allocator_type>::const_pointer`
`iterator`	LegacyBidirectionalIterator
`const_iterator`	constant LegacyBidirectionalIterator
`reverse_iterator`	reverse iterator, derived from `iterator`
`const_reverse_iterator`	reverse iterator, derived from `const_iterator`
`iteration_proxy`	helper type for `items` function

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¶

Example

The example shows how the library is used.

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

using json = nlohmann::json;

int main()
{
    // create a JSON object
    json j =
    {
        {"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
    auto s = j.size();
    j["size"] = s;

    // pretty print with indent of 4 spaces
    std::cout << std::setw(4) << j << '\n';
}

Output:

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

Version history¶

Added in version 1.0.0.