JSON for Modern C++ 2.1.1
Loading...
Searching...
No Matches
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 class  parse_event_t : uint8_t {
  object_start , object_end , array_start , array_end ,
  key , 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
 
using value_t = detail::value_t
 

Public Member Functions

std::string type_name () const
 return the type as string
 

Static Public Member Functions

static allocator_type get_allocator ()
 returns the allocator associated with the container
 
static basic_json meta ()
 returns version information on the library
 

Friends

template<detail::value_t >
struct detail::external_constructor
 

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
 
using reference = value_type &
 the type of an element reference
 
using const_reference = const value_type &
 the type of an element const reference
 
using difference_type = std::ptrdiff_t
 a type to represent differences between iterators
 
using size_type = std::size_t
 a type to represent container sizes
 
using allocator_type = AllocatorType< basic_json >
 the allocator type
 
using pointer = typename std::allocator_traits< allocator_type >::pointer
 the type of an element pointer
 
using const_pointer = typename std::allocator_traits< allocator_type >::const_pointer
 the type of an element const pointer
 
using iterator = iter_impl< basic_json >
 an iterator for a basic_json container
 
using const_iterator = iter_impl< const basic_json >
 a const iterator for a basic_json container
 
using reverse_iterator = json_reverse_iterator< typename basic_json::iterator >
 a reverse iterator for a basic_json container
 
using const_reverse_iterator = json_reverse_iterator< typename basic_json::const_iterator >
 a const reverse iterator for a basic_json container
 

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
 
using array_t = ArrayType< basic_json, AllocatorType< basic_json > >
 a type for an array
 
using string_t = StringType
 a type for a string
 
using boolean_t = BooleanType
 a type for a boolean
 
using number_integer_t = NumberIntegerType
 a type for a number (integer)
 
using number_unsigned_t = NumberUnsignedType
 a type for a number (unsigned)
 
using number_float_t = NumberFloatType
 a type for a number (floating-point)
 

lexicographical comparison operators

bool operator== (const_reference lhs, const_reference rhs) noexcept
 comparison: equal
 
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
 
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
 
bool operator!= (const_reference lhs, const_reference rhs) noexcept
 comparison: not equal
 
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
 
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
 
bool operator< (const_reference lhs, const_reference rhs) noexcept
 comparison: less than
 
bool operator<= (const_reference lhs, const_reference rhs) noexcept
 comparison: less than or equal
 
bool operator> (const_reference lhs, const_reference rhs) noexcept
 comparison: greater than
 
bool operator>= (const_reference lhs, const_reference rhs) noexcept
 comparison: greater than or equal
 

serialization

std::ostream & operator<< (std::ostream &o, const basic_json &j)
 serialize to stream
 
std::ostream & operator>> (const basic_json &j, std::ostream &o)
 serialize to stream
 

deserialization

std::istream & operator<< (basic_json &j, std::istream &i)
 deserialize from stream
 
std::istream & operator>> (std::istream &i, basic_json &j)
 deserialize from stream
 
template<class T , std::size_t N>
static basic_json parse (T(&array)[N], const parser_callback_t cb=nullptr)
 deserialize from an array
 
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
 
static basic_json parse (std::istream &i, const parser_callback_t cb=nullptr)
 deserialize from stream
 
static basic_json parse (std::istream &&i, const parser_callback_t cb=nullptr)
 deserialize from stream
 
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
 
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
 

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
 
static basic_json object (std::initializer_list< basic_json > init=std::initializer_list< basic_json >())
 explicitly create an object from an initializer list
 
 basic_json (const value_t value_type)
 create an empty value with a given type
 
 basic_json (std::nullptr_t=nullptr) noexcept
 create a null object
 
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
 
 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
 
 basic_json (size_type cnt, const basic_json &val)
 construct an array with count copies of given value
 
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
 
JSON_DEPRECATED basic_json (std::istream &i, const parser_callback_t cb=nullptr)
 construct a JSON value given an input stream
 
 basic_json (const basic_json &other)
 copy constructor
 
 basic_json (basic_json &&other) noexcept
 move constructor
 
referenceoperator= (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
 
 ~basic_json ()
 destructor
 

iterators

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

binary serialization/deserialization support

static std::vector< uint8_tto_msgpack (const basic_json &j)
 create a MessagePack serialization of a given JSON value
 
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
 
static std::vector< uint8_tto_cbor (const basic_json &j)
 create a MessagePack serialization of a given JSON value
 
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
 

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
 
basic_json patch (const basic_json &json_patch) const
 applies a JSON patch
 

object inspection

Functions to inspect the type of a JSON value.

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

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
 
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)
 
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
 
template<typename PointerType , typename std::enable_if< std::is_pointer< PointerType >::value, int >::type = 0>
PointerType get () noexcept
 get a pointer value (explicit)
 
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)
 
template<typename PointerType , typename std::enable_if< std::is_pointer< PointerType >::value, int >::type = 0>
PointerType get_ptr () noexcept
 get a pointer value (implicit)
 
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)
 
template<typename ReferenceType , typename std::enable_if< std::is_reference< ReferenceType >::value, int >::type = 0>
ReferenceType get_ref ()
 get a reference value (implicit)
 
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)
 
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)
 

element access

Access to the JSON value.

reference at (size_type idx)
 access specified array element with bounds checking
 
const_reference at (size_type idx) const
 access specified array element with bounds checking
 
reference at (const typename object_t::key_type &key)
 access specified object element with bounds checking
 
const_reference at (const typename object_t::key_type &key) const
 access specified object element with bounds checking
 
reference operator[] (size_type idx)
 access specified array element
 
const_reference operator[] (size_type idx) const
 access specified array element
 
reference operator[] (const typename object_t::key_type &key)
 access specified object element
 
const_reference operator[] (const typename object_t::key_type &key) const
 read-only access specified object element
 
template<typename T , std::size_t n>
reference operator[] (T *(&key)[n])
 access specified object element
 
template<typename T , std::size_t n>
const_reference operator[] (T *(&key)[n]) const
 read-only access specified object element
 
template<typename T >
reference operator[] (T *key)
 access specified object element
 
template<typename T >
const_reference operator[] (T *key) const
 read-only access specified object element
 
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
 
string_t value (const typename object_t::key_type &key, const char *default_value) const
 overload for a default value of type const char*
 
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
 
string_t value (const json_pointer &ptr, const char *default_value) const
 overload for a default value of type const char*
 
reference front ()
 access the first element
 
const_reference front () const
 access the first element
 
reference back ()
 access the last element
 
const_reference back () const
 access the last element
 
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
 
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
 
size_type erase (const typename object_t::key_type &key)
 remove element from a JSON object given a key
 
void erase (const size_type idx)
 remove element from a JSON array given an index
 

lookup

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

capacity

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

modifiers

void clear () noexcept
 clears the contents
 
void push_back (basic_json &&val)
 add an object to an array
 
reference operator+= (basic_json &&val)
 add an object to an array
 
void push_back (const basic_json &val)
 add an object to an array
 
reference operator+= (const basic_json &val)
 add an object to an array
 
void push_back (const typename object_t::value_type &val)
 add an object to an object
 
reference operator+= (const typename object_t::value_type &val)
 add an object to an object
 
void push_back (std::initializer_list< basic_json > init)
 add an object to an object
 
reference operator+= (std::initializer_list< basic_json > init)
 add an object to an object
 
template<class... Args>
void emplace_back (Args &&... args)
 add an object to an array
 
template<class... Args>
std::pair< iterator, boolemplace (Args &&... args)
 add an object to an object if key does not exist
 
iterator insert (const_iterator pos, const basic_json &val)
 inserts element
 
iterator insert (const_iterator pos, basic_json &&val)
 inserts element
 
iterator insert (const_iterator pos, size_type cnt, const basic_json &val)
 inserts elements
 
iterator insert (const_iterator pos, const_iterator first, const_iterator last)
 inserts elements
 
iterator insert (const_iterator pos, std::initializer_list< basic_json > ilist)
 inserts elements
 
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
 
void swap (array_t &other)
 exchanges the values
 
void swap (object_t &other)
 exchanges the values
 
void swap (string_t &other)
 exchanges the values
 

JSON Pointer functions

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

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 = 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 nlohmann::basic_json
Template Parameters
ObjectTypetype for JSON objects (std::map by default; will be used in object_t)
ArrayTypetype for JSON arrays (std::vector by default; will be used in array_t)
StringTypetype for JSON strings and object keys (std::string by default; will be used in string_t)
BooleanTypetype for JSON booleans (bool by default; will be used in boolean_t)
NumberIntegerTypetype for JSON integer numbers (int64_t by default; will be used in number_integer_t)
NumberUnsignedTypetype for JSON unsigned integer numbers (uint64_t by default; will be used in number_unsigned_t)
NumberFloatTypetype for JSON floating-point numbers (double by default; will be used in number_float_t)
AllocatorTypetype of the allocator to use (std::allocator by default)
JSONSerializerthe serializer to resolve internal calls to to_json() and from_json() (adl_serializer by default)
Requirements\n The class satisfies the following concept requirements:
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 1039 of file json.hpp.