Skip to content

# basic_json

Defined in header `<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;

## Specializations

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

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

## Iterator invalidation

Todo

## 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
- input_format_t - type to choose the format to parse
- json_sax_t

### 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
- 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: less than or equal
- operator> - comparison: greater than
- operator>= - comparison: greater than or equal

### Serialization / Dumping

- dump - serialization
- to_string - user-defined to_string function for JSON values

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

## Literals

- operator""_json - user-defined string literal for JSON values
- operator""_json_pointer - user-defined string literal for JSON pointers

## Helper classes

- std::hash<nlohmann::json>
- std::less<nlohmann::value_t>
- std::swap<nlohmann::json>