nlohmann::basic_json Class Template Reference

a class to store JSON values More...

`#include <json.hpp>`

## Classes

class | const_iterator
| a const random access iterator for the basic_json class More...
class | iterator
| a mutable random access iterator for the basic_json class More...
class | json_reverse_iterator
| a template for a reverse iterator class More...

## Public Types

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...
enum | value_t : uint8_t { value_t::null, value_t::object, value_t::array, value_t::string, value_t::boolean, value_t::number_integer, value_t::number_float, value_t::discarded }
| the JSON type enumeration More...

## Static Public Member Functions

static allocator_type | get_allocator ()
| returns the allocator associated with the container More...

## container types

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

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_float_t = NumberFloatType
| a type for a number (floating-point) More...

## constructors and destructors

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 () noexcept=default
| create a null object (implicitly) More...
| basic_json (std::nullptr_t) noexcept
| create a null object (explicitly) More...
| basic_json (const object_t &val)
| create an object (explicit) More...
template<class CompatibleObjectType , typename std::enable_if< std::is_constructible< typename object_t::key_type, typename CompatibleObjectType::key_type >::value and std::is_constructible< basic_json, typename CompatibleObjectType::mapped_type >::value, int >::type = 0>
| basic_json (const CompatibleObjectType &val)
| create an object (implicit) More...
| basic_json (const array_t &val)
| create an array (explicit) More...

template<class CompatibleArrayType , typename std::enable_if< not std::is_same< CompatibleArrayType, typename basic_json_t::iterator >::value and not std::is_same< CompatibleArrayType, typename basic_json_t::const_iterator >::value and not std::is_same< CompatibleArrayType, typename basic_json_t::reverse_iterator >::value and not std::is_same< CompatibleArrayType, typename basic_json_t::const_reverse_iterator >::value and not std::is_same< CompatibleArrayType, typename array_t::iterator >::value and not std::is_same< CompatibleArrayType, typename array_t::const_iterator >::value and std::is_constructible< basic_json, typename CompatibleArrayType::value_type >::value, int >::type = 0>

| basic_json (const CompatibleArrayType &val)
| create an array (implicit) More...
| basic_json (const string_t &val)
| create a string (explicit) More...
| basic_json (const typename string_t::value_type *val)
| create a string (explicit) More...
template<class CompatibleStringType , typename std::enable_if< std::is_constructible< string_t, CompatibleStringType >::value, int >::type = 0>
| basic_json (const CompatibleStringType &val)
| create a string (implicit) More...
| basic_json (boolean_t val)
| create a boolean (explicit) More...
template<typename T , typename std::enable_if< not(std::is_same< T, int >::value) and std::is_same< T, number_integer_t >::value , int >::type = 0>
| basic_json (const number_integer_t val)
| create an integer number (explicit) More...
| basic_json (const int val)
| create an integer number from an enum type (explicit) More...
template<typename CompatibleNumberIntegerType , typename std::enable_if< std::is_constructible< number_integer_t, CompatibleNumberIntegerType >::value and std::numeric_limits< CompatibleNumberIntegerType >::is_integer, CompatibleNumberIntegerType >::type = 0>
| basic_json (const CompatibleNumberIntegerType val) noexcept
| create an integer number (implicit) More...
| basic_json (const number_float_t val)
| create a floating-point number (explicit) More...
template<typename CompatibleNumberFloatType , typename = typename std::enable_if< std::is_constructible<number_float_t, CompatibleNumberFloatType>::value and std::is_floating_point<CompatibleNumberFloatType>::value>::type>
| basic_json (const CompatibleNumberFloatType val) noexcept
| create an floating-point number (implicit) 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

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

## value access

template<typename ValueType , typename std::enable_if< not std::is_pointer< ValueType >::value , int >::type = 0>
ValueType | get () const
| get a value (explicit) 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>
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>
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

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...
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 InteratorType , typename std::enable_if< std::is_same< InteratorType, typename basic_json_t::iterator >::value or std::is_same< InteratorType, typename basic_json_t::const_iterator >::value , int >::type = 0>
InteratorType | erase (InteratorType pos)
| remove element given an iterator More...
template<class InteratorType , typename std::enable_if< std::is_same< InteratorType, typename basic_json_t::iterator >::value or std::is_same< InteratorType, typename basic_json_t::const_iterator >::value , int >::type = 0>
InteratorType | erase (InteratorType first, InteratorType 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...
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 ()
| returns an iterator to the first element More...
const_iterator | begin () const
| returns a const iterator to the first element More...
const_iterator | cbegin () const
| returns a const iterator to the first element More...
iterator | end ()
| returns an iterator to one past the last element More...
const_iterator | end () const
| returns a const iterator to one past the last element More...
const_iterator | cend () const
| returns a const iterator to one past the last element More...
reverse_iterator | rbegin ()
| returns an iterator to the reverse-beginning More...
const_reverse_iterator | rbegin () const
| returns a const reverse iterator to the last element More...
reverse_iterator | rend ()
| returns an iterator to the reverse-end More...
const_reverse_iterator | rend () const
| returns a const reverse iterator to one before the first More...
const_reverse_iterator | crbegin () const
| returns a const reverse iterator to the last element More...
const_reverse_iterator | crend () const
| 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...
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 | 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 value_t lhs, const value_t rhs)
| comparison operator for JSON types More...
bool | operator== (const_reference lhs, const_reference rhs) noexcept
| comparison: equal More...
bool | operator== (const_reference v, std::nullptr_t) noexcept
| comparison: equal More...
bool | operator== (std::nullptr_t, const_reference v) noexcept
| comparison: equal More...
bool | operator!= (const_reference lhs, const_reference rhs) noexcept
| comparison: not equal More...
bool | operator!= (const_reference v, std::nullptr_t) noexcept
| comparison: not equal More...
bool | operator!= (std::nullptr_t, const_reference v) noexcept
| comparison: not equal More...
bool | operator< (const_reference lhs, const_reference rhs) noexcept
| comparison: less than More...
bool | operator<= (const_reference lhs, const_reference rhs) noexcept
| comparison: less than or equal More...
bool | operator> (const_reference lhs, const_reference rhs) noexcept
| comparison: greater than More...
bool | operator>= (const_reference 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...
std::ostream & | operator>> (const basic_json &j, std::ostream &o)
| serialize to stream More...

## deserialization

static basic_json | parse (const string_t &s, parser_callback_t cb=nullptr)
| deserialize from string More...
static basic_json | parse (std::istream &i, parser_callback_t cb=nullptr)
| deserialize from stream More...
static basic_json | parse (std::istream &&i, parser_callback_t cb=nullptr)
| deserialize from stream More...
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...

## Detailed Description

### 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 = int64_t, class NumberFloatType = double, template< typename U > class AllocatorType = std::allocator>
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)
  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)

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.

See also
  RFC 7159 http://rfc7159.net/rfc7159

Since
  version 1.0.0

Definition at line 191 of file json.hpp.