Skip to content

# 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 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`

## Specializations

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

## Iterator invalidation

Todo

## 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 type is primitive
- is_structured - return whether type is structured
- is_null - return whether value is null
- is_boolean - return whether value is a boolean
- is_number - return whether value is a number
- is_number_integer - return whether value is an integer number
- is_number_unsigned - return whether value is an unsigned integer number
- is_number_float - return whether value is a floating-point number
- is_object - return whether value is an object
- is_array - return whether value is an array
- is_string - return whether value is a string
- is_binary - return whether value is a binary array
- is_discarded - return whether value is discarded

### 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 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
    }

## See also

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

## Version history

- Added in version 1.0.0.

Last update: July 31, 2022
Back to top