JSON for Modern C++ 2.1.1

Classes | Public Types | Public Member Functions | Static Public Member Functions | Friends | List of all members
nlohmann::basic_json Class Template Reference

a class to store JSON values More...

`#include <json.hpp>`

## Classes
class | iter_impl
| a template for a random access iterator for the basic_json class More...
class | json_pointer
| JSON Pointer. More...
class | json_reverse_iterator
| a template for a reverse iterator class More...

## Public Types
template<typename T , typename SFINAE >
using | json_serializer = JSONSerializer< T, SFINAE >
enum | parse_event_t : uint8_t { parse_event_t::object_start, parse_event_t::object_end, parse_event_t::array_start, parse_event_t::array_end, parse_event_t::key, parse_event_t::value }
| JSON callback events. More...
using | parser_callback_t = std::function< bool(int depth, parse_event_t event, basic_json &parsed)>
| per-element parser callback type More...
using | value_t = detail::value_t

## Public Member Functions
std::string | type_name () const
| return the type as string More...

## Static Public Member Functions
static allocator_type | get_allocator ()
| returns the allocator associated with the container More...
static basic_json | meta ()
| returns version information on the library More...

## Friends
template<detail::value_t >
struct | detail::external_constructor

## exceptions
Classes to implement user-defined exceptions.
using | exception = detail::exception
| general exception of the basic_json class More...
using | parse_error = detail::parse_error
| exception indicating a parse error More...
using | invalid_iterator = detail::invalid_iterator
| exception indicating errors with iterators More...
using | type_error = detail::type_error
| exception indicating executing a member function with a wrong type More...
using | out_of_range = detail::out_of_range
| exception indicating access out of the defined range More...
using | other_error = detail::other_error
| exception indicating other errors More...

## container types
The canonic container types to use basic_json like any other STL container.
using | value_type = basic_json
| the type of elements in a basic_json container More...
using | reference = value_type &
| the type of an element reference More...
using | const_reference = const value_type &
| the type of an element const reference More...
using | difference_type = std::ptrdiff_t
| a type to represent differences between iterators More...
using | size_type = std::size_t
| a type to represent container sizes More...
using | allocator_type = AllocatorType< basic_json >
| the allocator type More...
using | pointer = typename std::allocator_traits< allocator_type >::pointer
| the type of an element pointer More...
using | const_pointer = typename std::allocator_traits< allocator_type >::const_pointer
| the type of an element const pointer More...
using | iterator = iter_impl< basic_json >
| an iterator for a basic_json container More...
using | const_iterator = iter_impl< const basic_json >
| a const iterator for a basic_json container More...
using | reverse_iterator = json_reverse_iterator< typename basic_json::iterator >
| a reverse iterator for a basic_json container More...
using | const_reverse_iterator = json_reverse_iterator< typename basic_json::const_iterator >
| a const reverse iterator for a basic_json container More...

## JSON value data types
The data types to store a JSON value. These types are derived from the template arguments passed to class basic_json.
using | object_t = ObjectType< StringType, basic_json, std::less< StringType >, AllocatorType< std::pair< const StringType, basic_json > >>
| a type for an object More...
using | array_t = ArrayType< basic_json, AllocatorType< basic_json > >
| a type for an array More...
using | string_t = StringType
| a type for a string More...
using | boolean_t = BooleanType
| a type for a boolean More...
using | number_integer_t = NumberIntegerType
| a type for a number (integer) More...
using | number_unsigned_t = NumberUnsignedType
| a type for a number (unsigned) More...
using | number_float_t = NumberFloatType
| a type for a number (floating-point) More...

## constructors and destructors
Constructors of class basic_json, copy/move constructor, copy assignment, static functions creating objects, and the destructor.
static basic_json | array (std::initializer_list< basic_json > init=std::initializer_list< basic_json >())
| explicitly create an array from an initializer list More...
static basic_json | object (std::initializer_list< basic_json > init=std::initializer_list< basic_json >())
| explicitly create an object from an initializer list More...
| basic_json (const value_t value_type)
| create an empty value with a given type More...
| basic_json (std::nullptr_t=nullptr) noexcept
| create a null object More...
template<typename CompatibleType , typename U = detail::uncvref_t<CompatibleType>, detail::enable_if_t< not std::is_base_of< std::istream, U >::value and not std::is_same< U, basic_json_t >::value and not detail::is_basic_json_nested_type< basic_json_t, U >::value and detail::has_to_json< basic_json, U >::value, int > = 0>
| basic_json (CompatibleType &&val) noexcept(noexcept(JSONSerializer< U >::to_json(std::declval< basic_json_t &>(), std::forward< CompatibleType >(val))))
| create a JSON value More...
| basic_json (std::initializer_list< basic_json > init, bool type_deduction=true, value_t manual_type=value_t::array)
| create a container (array or object) from an initializer list More...
| basic_json (size_type cnt, const basic_json &val)
| construct an array with count copies of given value More...
template<class InputIT , typename std::enable_if< std::is_same< InputIT, typename basic_json_t::iterator >::value or std::is_same< InputIT, typename basic_json_t::const_iterator >::value, int >::type = 0>
| basic_json (InputIT first, InputIT last)
| construct a JSON container given an iterator range More...
| basic_json (const basic_json &other)
| copy constructor More...
| basic_json (basic_json &&other) noexcept
| move constructor More...
reference & | operator= (basic_json other) noexcept(std::is_nothrow_move_constructible< value_t >::value and std::is_nothrow_move_assignable< value_t >::value and std::is_nothrow_move_constructible< json_value >::value and std::is_nothrow_move_assignable< json_value >::value)
| copy assignment More...
| ~basic_json ()
| destructor More...

## object inspection
Functions to inspect the type of a JSON value.
string_t | dump (const int indent=-1) const
| serialization More...
constexpr value_t | type () const noexcept
| return the type of the JSON value (explicit) More...
constexpr bool | is_primitive () const noexcept
| return whether type is primitive More...
constexpr bool | is_structured () const noexcept
| return whether type is structured More...
constexpr bool | is_null () const noexcept
| return whether value is null More...
constexpr bool | is_boolean () const noexcept
| return whether value is a boolean More...
constexpr bool | is_number () const noexcept
| return whether value is a number More...
constexpr bool | is_number_integer () const noexcept
| return whether value is an integer number More...
constexpr bool | is_number_unsigned () const noexcept
| return whether value is an unsigned integer number More...
constexpr bool | is_number_float () const noexcept
| return whether value is a floating-point number More...
constexpr bool | is_object () const noexcept
| return whether value is an object More...
constexpr bool | is_array () const noexcept
| return whether value is an array More...
constexpr bool | is_string () const noexcept
| return whether value is a string More...
constexpr bool | is_discarded () const noexcept
| return whether value is discarded More...
constexpr | operator value_t () const noexcept
| return the type of the JSON value (implicit) More...

## value access
Direct access to the stored value of a JSON value.
template<typename BasicJsonType , detail::enable_if_t< std::is_same< typename std::remove_const< BasicJsonType >::type, basic_json_t >::value, int > = 0>
basic_json | get () const
| get special-case overload More...
template<typename ValueTypeCV , typename ValueType = detail::uncvref_t<ValueTypeCV>, detail::enable_if_t< not std::is_same< basic_json_t, ValueType >::value and detail::has_from_json< basic_json_t, ValueType >::value and not detail::has_non_default_from_json< basic_json_t, ValueType >::value, int > = 0>
ValueType | get () const noexcept(noexcept(JSONSerializer< ValueType >::from_json(std::declval< const basic_json_t &>(), std::declval< ValueType &>())))
| get a value (explicit) More...
template<typename ValueTypeCV , typename ValueType = detail::uncvref_t<ValueTypeCV>, detail::enable_if_t< not std::is_same< basic_json_t, ValueType >::value and detail::has_non_default_from_json< basic_json_t, ValueType >::value, int > = 0>
ValueType | get () const noexcept(noexcept(JSONSerializer< ValueTypeCV >::from_json(std::declval< const basic_json_t &>())))
| get a value (explicit); special case More...
template<typename PointerType , typename std::enable_if< std::is_pointer< PointerType >::value, int >::type = 0>
PointerType | get () noexcept
| get a pointer value (explicit) More...
template<typename PointerType , typename std::enable_if< std::is_pointer< PointerType >::value, int >::type = 0>
constexpr const PointerType | get () const noexcept
| get a pointer value (explicit) More...
template<typename PointerType , typename std::enable_if< std::is_pointer< PointerType >::value, int >::type = 0>
PointerType | get_ptr () noexcept
| get a pointer value (implicit) More...
template<typename PointerType , typename std::enable_if< std::is_pointer< PointerType >::value and std::is_const< typename std::remove_pointer< PointerType >::type >::value, int >::type = 0>
constexpr const PointerType | get_ptr () const noexcept
| get a pointer value (implicit) More...
template<typename ReferenceType , typename std::enable_if< std::is_reference< ReferenceType >::value, int >::type = 0>
ReferenceType | get_ref ()
| get a reference value (implicit) More...
template<typename ReferenceType , typename std::enable_if< std::is_reference< ReferenceType >::value and std::is_const< typename std::remove_reference< ReferenceType >::type >::value, int >::type = 0>
ReferenceType | get_ref () const
| get a reference value (implicit) More...
template<typename ValueType , typename std::enable_if< not std::is_pointer< ValueType >::value and not std::is_same< ValueType, typename string_t::value_type >::value and not std::is_same< ValueType, std::initializer_list< typename string_t::value_type >>::value, int >::type = 0>
| operator ValueType () const
| get a value (implicit) More...

## element access
Access to the JSON value.
reference | at (size_type idx)
| access specified array element with bounds checking More...
const_reference | at (size_type idx) const
| access specified array element with bounds checking More...
reference | at (const typename object_t::key_type &key)
| access specified object element with bounds checking More...
const_reference | at (const typename object_t::key_type &key) const
| access specified object element with bounds checking More...
reference | operator[] (size_type idx)
| access specified array element More...
const_reference | operator[] (size_type idx) const
| access specified array element More...
reference | operator[] (const typename object_t::key_type &key)
| access specified object element More...
const_reference | operator[] (const typename object_t::key_type &key) const
| read-only access specified object element More...
template<typename T , std::size_t n>
reference | operator[] (T *(&key)[n])
| access specified object element More...
template<typename T , std::size_t n>
const_reference | operator[] (T *(&key)[n]) const
| read-only access specified object element More...
template<typename T >
reference | operator[] (T *key)
| access specified object element More...
template<typename T >
const_reference | operator[] (T *key) const
| read-only access specified object element More...
template<class ValueType , typename std::enable_if< std::is_convertible< basic_json_t, ValueType >::value, int >::type = 0>
ValueType | value (const typename object_t::key_type &key, ValueType default_value) const
| access specified object element with default value More...
string_t | value (const typename object_t::key_type &key, const char *default_value) const
| overload for a default value of type const char* More...
template<class ValueType , typename std::enable_if< std::is_convertible< basic_json_t, ValueType >::value, int >::type = 0>
ValueType | value (const json_pointer &ptr, ValueType default_value) const
| access specified object element via JSON Pointer with default value More...
string_t | value (const json_pointer &ptr, const char *default_value) const
| overload for a default value of type const char* More...
reference | front ()
| access the first element More...
const_reference | front () const
| access the first element More...
reference | back ()
| access the last element More...
const_reference | back () const
| access the last element More...
template<class IteratorType , typename std::enable_if< std::is_same< IteratorType, typename basic_json_t::iterator >::value or std::is_same< IteratorType, typename basic_json_t::const_iterator >::value, int >::type = 0>
IteratorType | erase (IteratorType pos)
| remove element given an iterator More...
template<class IteratorType , typename std::enable_if< std::is_same< IteratorType, typename basic_json_t::iterator >::value or std::is_same< IteratorType, typename basic_json_t::const_iterator >::value, int >::type = 0>
IteratorType | erase (IteratorType first, IteratorType last)
| remove elements given an iterator range More...
size_type | erase (const typename object_t::key_type &key)
| remove element from a JSON object given a key More...
void | erase (const size_type idx)
| remove element from a JSON array given an index More...

## lookup
iterator | find (typename object_t::key_type key)
| find an element in a JSON object More...
const_iterator | find (typename object_t::key_type key) const
| find an element in a JSON object More...
size_type | count (typename object_t::key_type key) const
| returns the number of occurrences of a key in a JSON object More...

## iterators
static iteration_proxy< iterator > | iterator_wrapper (reference cont)
| wrapper to access iterator member functions in range-based for More...
static iteration_proxy< const_iterator > | iterator_wrapper (const_reference cont)
| wrapper to access iterator member functions in range-based for More...
iterator | begin () noexcept
| returns an iterator to the first element More...
const_iterator | begin () const noexcept
| returns a const iterator to the first element More...
const_iterator | cbegin () const noexcept
| returns a const iterator to the first element More...
iterator | end () noexcept
| returns an iterator to one past the last element More...
const_iterator | end () const noexcept
| returns a const iterator to one past the last element More...
const_iterator | cend () const noexcept
| returns a const iterator to one past the last element More...
reverse_iterator | rbegin () noexcept
| returns an iterator to the reverse-beginning More...
const_reverse_iterator | rbegin () const noexcept
| returns a const reverse iterator to the last element More...
reverse_iterator | rend () noexcept
| returns an iterator to the reverse-end More...
const_reverse_iterator | rend () const noexcept
| returns a const reverse iterator to one before the first More...
const_reverse_iterator | crbegin () const noexcept
| returns a const reverse iterator to the last element More...
const_reverse_iterator | crend () const noexcept
| returns a const reverse iterator to one before the first More...

## capacity
bool | empty () const noexcept
| checks whether the container is empty More...
size_type | size () const noexcept
| returns the number of elements More...
size_type | max_size () const noexcept
| returns the maximum possible number of elements More...

## modifiers
void | clear () noexcept
| clears the contents More...
void | push_back (basic_json &&val)
| add an object to an array More...
reference | operator+= (basic_json &&val)
| add an object to an array More...
void | push_back (const basic_json &val)
| add an object to an array More...
reference | operator+= (const basic_json &val)
| add an object to an array More...
void | push_back (const typename object_t::value_type &val)
| add an object to an object More...
reference | operator+= (const typename object_t::value_type &val)
| add an object to an object More...
void | push_back (std::initializer_list< basic_json > init)
| add an object to an object More...
reference | operator+= (std::initializer_list< basic_json > init)
| add an object to an object More...
template<class... Args>
void | emplace_back (Args &&... args)
| add an object to an array More...
template<class... Args>
std::pair< iterator, bool > | emplace (Args &&... args)
| add an object to an object if key does not exist More...
iterator | insert (const_iterator pos, const basic_json &val)
| inserts element More...
iterator | insert (const_iterator pos, basic_json &&val)
| inserts element More...
iterator | insert (const_iterator pos, size_type cnt, const basic_json &val)
| inserts elements More...
iterator | insert (const_iterator pos, const_iterator first, const_iterator last)
| inserts elements More...
iterator | insert (const_iterator pos, std::initializer_list< basic_json > ilist)
| inserts elements More...
void | insert (const_iterator first, const_iterator last)
| inserts elements More...
void | swap (reference other) noexcept(std::is_nothrow_move_constructible< value_t >::value and std::is_nothrow_move_assignable< value_t >::value and std::is_nothrow_move_constructible< json_value >::value and std::is_nothrow_move_assignable< json_value >::value)
| exchanges the values More...
void | swap (array_t &other)
| exchanges the values More...
void | swap (object_t &other)
| exchanges the values More...
void | swap (string_t &other)
| exchanges the values More...

## lexicographical comparison operators
bool | operator== (const_reference lhs, const_reference rhs) noexcept
| comparison: equal More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator== (const_reference lhs, const ScalarType rhs) noexcept
| comparison: equal More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator== (const ScalarType lhs, const_reference rhs) noexcept
| comparison: equal More...
bool | operator!= (const_reference lhs, const_reference rhs) noexcept
| comparison: not equal More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator!= (const_reference lhs, const ScalarType rhs) noexcept
| comparison: not equal More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator!= (const ScalarType lhs, const_reference rhs) noexcept
| comparison: not equal More...
bool | operator< (const_reference lhs, const_reference rhs) noexcept
| comparison: less than More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator< (const_reference lhs, const ScalarType rhs) noexcept
| comparison: less than More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator< (const ScalarType lhs, const_reference rhs) noexcept
| comparison: less than More...
bool | operator<= (const_reference lhs, const_reference rhs) noexcept
| comparison: less than or equal More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator<= (const_reference lhs, const ScalarType rhs) noexcept
| comparison: less than or equal More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator<= (const ScalarType lhs, const_reference rhs) noexcept
| comparison: less than or equal More...
bool | operator> (const_reference lhs, const_reference rhs) noexcept
| comparison: greater than More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator> (const_reference lhs, const ScalarType rhs) noexcept
| comparison: greater than More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator> (const ScalarType lhs, const_reference rhs) noexcept
| comparison: greater than More...
bool | operator>= (const_reference lhs, const_reference rhs) noexcept
| comparison: greater than or equal More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator>= (const_reference lhs, const ScalarType rhs) noexcept
| comparison: greater than or equal More...
template<typename ScalarType , typename std::enable_if< std::is_scalar< ScalarType >::value, int >::type = 0>
bool | operator>= (const ScalarType lhs, const_reference rhs) noexcept
| comparison: greater than or equal More...

## serialization
std::ostream & | operator<< (std::ostream &o, const basic_json &j)
| serialize to stream More...
JSON_DEPRECATED friend std::ostream & | operator>> (const basic_json &j, std::ostream &o)
| serialize to stream More...

## deserialization
JSON_DEPRECATED friend std::istream & | operator<< (basic_json &j, std::istream &i)
| deserialize from stream More...
std::istream & | operator>> (std::istream &i, basic_json &j)
| deserialize from stream More...
template<class T , std::size_t N>
static basic_json | parse (T(&array)[N], const parser_callback_t cb=nullptr)
| deserialize from an array More...
template<typename CharT , typename std::enable_if< std::is_pointer< CharT >::value and std::is_integral< typename std::remove_pointer< CharT >::type >::value and sizeof(typename std::remove_pointer< CharT >::type)==1, int >::type = 0>
static basic_json | parse (const CharT s, const parser_callback_t cb=nullptr)
| deserialize from string literal More...
static basic_json | parse (std::istream &i, const parser_callback_t cb=nullptr)
| deserialize from stream More...
static basic_json | parse (std::istream &&i, const parser_callback_t cb=nullptr)
| deserialize from stream More...
template<class IteratorType , typename std::enable_if< std::is_base_of< std::random_access_iterator_tag, typename std::iterator_traits< IteratorType >::iterator_category >::value, int >::type = 0>
static basic_json | parse (IteratorType first, IteratorType last, const parser_callback_t cb=nullptr)
| deserialize from an iterator range with contiguous storage More...
template<class ContiguousContainer , typename std::enable_if< not std::is_pointer< ContiguousContainer >::value and std::is_base_of< std::random_access_iterator_tag, typename std::iterator_traits< decltype(std::begin(std::declval< ContiguousContainer const >()))>::iterator_category >::value, int >::type = 0>
static basic_json | parse (const ContiguousContainer &c, const parser_callback_t cb=nullptr)
| deserialize from a container with contiguous storage More...

## binary serialization/deserialization support
static std::vector< uint8_t > | to_msgpack (const basic_json &j)
| create a MessagePack serialization of a given JSON value More...
static basic_json | from_msgpack (const std::vector< uint8_t > &v, const size_t start_index=0)
| create a JSON value from a byte vector in MessagePack format More...
static std::vector< uint8_t > | to_cbor (const basic_json &j)
| create a MessagePack serialization of a given JSON value More...
static basic_json | from_cbor (const std::vector< uint8_t > &v, const size_t start_index=0)
| create a JSON value from a byte vector in CBOR format More...

## JSON Pointer functions
reference | operator[] (const json_pointer &ptr)
| access specified element via JSON Pointer More...
const_reference | operator[] (const json_pointer &ptr) const
| access specified element via JSON Pointer More...
reference | at (const json_pointer &ptr)
| access specified element via JSON Pointer More...
const_reference | at (const json_pointer &ptr) const
| access specified element via JSON Pointer More...
basic_json | flatten () const
| return flattened JSON value More...
basic_json | unflatten () const
| unflatten a previously flattened JSON value More...

## JSON Patch functions
static basic_json | diff (const basic_json &source, const basic_json &target, const std::string &path="")
| creates a diff as a JSON patch More...
basic_json | patch (const basic_json &json_patch) const
| applies a JSON patch More...

## Detailed Description

###
class nlohmann::basic_json

Template Parameters

  ObjectType | type for JSON objects (`std::map` by default; will be used in object_t)
  ArrayType | type for JSON arrays (`std::vector` by default; will be used in array_t)
  StringType | type for JSON strings and object keys (`std::string` by default; will be used in string_t)
  BooleanType | type for JSON booleans (`bool` by default; will be used in boolean_t)
  NumberIntegerType | type for JSON integer numbers (`int64_t` by default; will be used in number_integer_t)
  NumberUnsignedType | type for JSON unsigned integer numbers (``uint64_t`` by default; will be used in number_unsigned_t)
  NumberFloatType | type for JSON floating-point numbers (`double` by default; will be used in number_float_t)
  AllocatorType | type of the allocator to use (`std::allocator` by default)
  JSONSerializer | the serializer to resolve internal calls to `to_json()` and `from_json()` (adl_serializer by default)

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 van 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==(const_reference,const_reference).
    - LessThanComparable: JSON values can be compared with `<`, see operator<(const_reference,const_reference).
    - Swappable: Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of other compatible types, using unqualified function call 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.

Invariant
  The member variables m_value and m_type have the following relationship:
  - If `m_type == value_t::object`, then `m_value.object != nullptr`.
  - If `m_type == value_t::array`, then `m_value.array != nullptr`.
  - If `m_type == value_t::string`, then `m_value.string != nullptr`. The invariants are checked by member function assert_invariant().

See also
  RFC 7159: The JavaScript Object Notation (JSON) Data Interchange Format

Since
  version 1.0.0

Definition at line 1288 of file json.hpp.