json/doc/mkdocs/docs/api/basic_json/index.md

basic_json

!!! note

This page is under construction.

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()
BinaryType	type for binary arrays	binary_t

Iterator invalidation

Todo

Member types

• value_t - the JSON type enumeration
• json_pointer - JSON Pointer implementation
• json_serializer
• 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	#!cpp basic_json
reference	#!cpp value_type&
const_reference	#!cpp const value_type&
difference_type	#!cpp std::ptrdiff_t
size_type	#!cpp std::size_t
allocator_type	#!cpp AllocatorType<basic_json>
pointer	#!cpp std::allocator_traits<allocator_type>::pointer
const_pointer	#!cpp std::allocator_traits<allocator_type>::const_pointer
iterator	LegacyBidirectionalIterator
const_iterator	constant LegacyBidirectionalIterator
reverse_iterator
const_reverse_iterator
iteration_proxy

JSON value data types

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

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
• 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

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

Deserialization

• 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::hashnlohmann::json\
• std::lessnlohmann::value_t\
• std::swapnlohmann::json\