2018-01-10 01:30:02 +08:00
/*
__ _____ _____ _____
__ | | __ | | | | JSON for Modern C + +
2018-10-31 04:30:20 +08:00
| | | __ | | | | | | version 3.4 .0
2018-01-10 01:30:02 +08:00
| _____ | _____ | _____ | _ | ___ | https : //github.com/nlohmann/json
Licensed under the MIT License < http : //opensource.org/licenses/MIT>.
2018-05-03 23:41:45 +08:00
SPDX - License - Identifier : MIT
2018-02-02 05:20:26 +08:00
Copyright ( c ) 2013 - 2018 Niels Lohmann < http : //nlohmann.me>.
2018-01-10 01:30:02 +08:00
Permission is hereby granted , free of charge , to any person obtaining a copy
of this software and associated documentation files ( the " Software " ) , to deal
in the Software without restriction , including without limitation the rights
to use , copy , modify , merge , publish , distribute , sublicense , and / or sell
copies of the Software , and to permit persons to whom the Software is
furnished to do so , subject to the following conditions :
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software .
THE SOFTWARE IS PROVIDED " AS IS " , WITHOUT WARRANTY OF ANY KIND , EXPRESS OR
IMPLIED , INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY ,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT . IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM , DAMAGES OR OTHER
LIABILITY , WHETHER IN AN ACTION OF CONTRACT , TORT OR OTHERWISE , ARISING FROM ,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE .
*/
# ifndef NLOHMANN_JSON_HPP
# define NLOHMANN_JSON_HPP
2018-02-01 05:36:18 +08:00
# define NLOHMANN_JSON_VERSION_MAJOR 3
2018-10-31 04:30:20 +08:00
# define NLOHMANN_JSON_VERSION_MINOR 4
2018-08-19 00:46:15 +08:00
# define NLOHMANN_JSON_VERSION_PATCH 0
2018-02-01 05:36:18 +08:00
2018-01-10 01:30:02 +08:00
# include <algorithm> // all_of, find, for_each
# include <cassert> // assert
# include <ciso646> // and, not, or
# include <cstddef> // nullptr_t, ptrdiff_t, size_t
# include <functional> // hash, less
# include <initializer_list> // initializer_list
# include <iosfwd> // istream, ostream
2018-11-08 02:39:25 +08:00
# include <iterator> // random_access_iterator_tag
2018-01-10 01:30:02 +08:00
# include <numeric> // accumulate
# include <string> // string, stoi, to_string
# include <utility> // declval, forward, move, pair, swap
2018-01-29 18:21:11 +08:00
# include <nlohmann/json_fwd.hpp>
# include <nlohmann/detail/macro_scope.hpp>
2018-07-24 19:22:44 +08:00
# include <nlohmann/detail/meta/cpp_future.hpp>
# include <nlohmann/detail/meta/type_traits.hpp>
2018-01-29 18:21:11 +08:00
# include <nlohmann/detail/exceptions.hpp>
# include <nlohmann/detail/value_t.hpp>
# include <nlohmann/detail/conversions/from_json.hpp>
# include <nlohmann/detail/conversions/to_json.hpp>
# include <nlohmann/detail/input/input_adapters.hpp>
# include <nlohmann/detail/input/lexer.hpp>
# include <nlohmann/detail/input/parser.hpp>
# include <nlohmann/detail/iterators/primitive_iterator.hpp>
# include <nlohmann/detail/iterators/internal_iterator.hpp>
# include <nlohmann/detail/iterators/iter_impl.hpp>
# include <nlohmann/detail/iterators/iteration_proxy.hpp>
# include <nlohmann/detail/iterators/json_reverse_iterator.hpp>
# include <nlohmann/detail/output/output_adapters.hpp>
# include <nlohmann/detail/input/binary_reader.hpp>
# include <nlohmann/detail/output/binary_writer.hpp>
# include <nlohmann/detail/output/serializer.hpp>
# include <nlohmann/detail/json_ref.hpp>
# include <nlohmann/detail/json_pointer.hpp>
# include <nlohmann/adl_serializer.hpp>
2018-01-10 01:30:02 +08:00
/*!
@ brief namespace for Niels Lohmann
@ see https : //github.com/nlohmann
@ since version 1.0 .0
*/
namespace nlohmann
{
/*!
@ brief a class to store JSON values
@ tparam ObjectType type for JSON objects ( ` std : : map ` by default ; will be used
in @ ref object_t )
@ tparam ArrayType type for JSON arrays ( ` std : : vector ` by default ; will be used
in @ ref array_t )
@ tparam StringType type for JSON strings and object keys ( ` std : : string ` by
default ; will be used in @ ref string_t )
@ tparam BooleanType type for JSON booleans ( ` bool ` by default ; will be used
in @ ref boolean_t )
@ tparam NumberIntegerType type for JSON integer numbers ( ` int64_t ` by
default ; will be used in @ ref number_integer_t )
@ tparam NumberUnsignedType type for JSON unsigned integer numbers ( @ c
` uint64_t ` by default ; will be used in @ ref number_unsigned_t )
@ tparam NumberFloatType type for JSON floating - point numbers ( ` double ` by
default ; will be used in @ ref number_float_t )
@ tparam AllocatorType type of the allocator to use ( ` std : : allocator ` by
default )
@ tparam JSONSerializer the serializer to resolve internal calls to ` to_json ( ) `
and ` from_json ( ) ` ( @ ref adl_serializer by default )
@ requirement The class satisfies the following concept requirements :
- Basic
2018-06-25 04:30:37 +08:00
- [ DefaultConstructible ] ( https : //en.cppreference.com/w/cpp/named_req/DefaultConstructible):
2018-01-10 01:30:02 +08:00
JSON values can be default constructed . The result will be a JSON null
value .
2018-06-25 04:30:37 +08:00
- [ MoveConstructible ] ( https : //en.cppreference.com/w/cpp/named_req/MoveConstructible):
2018-01-10 01:30:02 +08:00
A JSON value can be constructed from an rvalue argument .
2018-06-25 04:30:37 +08:00
- [ CopyConstructible ] ( https : //en.cppreference.com/w/cpp/named_req/CopyConstructible):
2018-01-10 01:30:02 +08:00
A JSON value can be copy - constructed from an lvalue expression .
2018-06-25 04:30:37 +08:00
- [ MoveAssignable ] ( https : //en.cppreference.com/w/cpp/named_req/MoveAssignable):
2018-01-10 01:30:02 +08:00
A JSON value van be assigned from an rvalue argument .
2018-06-25 04:30:37 +08:00
- [ CopyAssignable ] ( https : //en.cppreference.com/w/cpp/named_req/CopyAssignable):
2018-01-10 01:30:02 +08:00
A JSON value can be copy - assigned from an lvalue expression .
2018-06-25 04:30:37 +08:00
- [ Destructible ] ( https : //en.cppreference.com/w/cpp/named_req/Destructible):
2018-01-10 01:30:02 +08:00
JSON values can be destructed .
- Layout
2018-06-25 04:30:37 +08:00
- [ StandardLayoutType ] ( https : //en.cppreference.com/w/cpp/named_req/StandardLayoutType):
2018-01-10 01:30:02 +08:00
JSON values have
2018-06-25 04:29:33 +08:00
[ standard layout ] ( https : //en.cppreference.com/w/cpp/language/data_members#Standard_layout):
2018-01-10 01:30:02 +08:00
All non - static data members are private and standard layout types , the
class has no virtual functions or ( virtual ) base classes .
- Library - wide
2018-06-25 04:30:37 +08:00
- [ EqualityComparable ] ( https : //en.cppreference.com/w/cpp/named_req/EqualityComparable):
2018-01-10 01:30:02 +08:00
JSON values can be compared with ` = = ` , see @ ref
operator = = ( const_reference , const_reference ) .
2018-06-25 04:30:37 +08:00
- [ LessThanComparable ] ( https : //en.cppreference.com/w/cpp/named_req/LessThanComparable):
2018-01-10 01:30:02 +08:00
JSON values can be compared with ` < ` , see @ ref
operator < ( const_reference , const_reference ) .
2018-06-25 04:30:37 +08:00
- [ Swappable ] ( https : //en.cppreference.com/w/cpp/named_req/Swappable):
2018-01-10 01:30:02 +08:00
Any JSON lvalue or rvalue of can be swapped with any lvalue or rvalue of
other compatible types , using unqualified function call @ ref swap ( ) .
2018-06-25 04:30:37 +08:00
- [ NullablePointer ] ( https : //en.cppreference.com/w/cpp/named_req/NullablePointer):
2018-01-10 01:30:02 +08:00
JSON values can be compared against ` std : : nullptr_t ` objects which are used
to model the ` null ` value .
- Container
2018-06-25 04:30:37 +08:00
- [ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container):
2018-01-10 01:30:02 +08:00
JSON values can be used like STL containers and provide iterator access .
2018-06-25 04:30:37 +08:00
- [ ReversibleContainer ] ( https : //en.cppreference.com/w/cpp/named_req/ReversibleContainer);
2018-01-10 01:30:02 +08:00
JSON values can be used like STL containers and provide reverse iterator
access .
@ invariant The member variables @ a m_value and @ a 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 ( ) .
@ internal
@ note ObjectType trick from http : //stackoverflow.com/a/9860911
@ endinternal
@ see [ RFC 7159 : The JavaScript Object Notation ( JSON ) Data Interchange
Format ] ( http : //rfc7159.net/rfc7159)
@ since version 1.0 .0
@ nosubgrouping
*/
NLOHMANN_BASIC_JSON_TPL_DECLARATION
class basic_json
{
private :
template < detail : : value_t > friend struct detail : : external_constructor ;
2018-01-28 22:36:56 +08:00
friend : : nlohmann : : json_pointer < basic_json > ;
2018-01-10 01:30:02 +08:00
friend : : nlohmann : : detail : : parser < basic_json > ;
friend : : nlohmann : : detail : : serializer < basic_json > ;
template < typename BasicJsonType >
friend class : : nlohmann : : detail : : iter_impl ;
template < typename BasicJsonType , typename CharType >
friend class : : nlohmann : : detail : : binary_writer ;
2018-07-02 16:14:37 +08:00
template < typename BasicJsonType , typename SAX >
2018-01-10 01:30:02 +08:00
friend class : : nlohmann : : detail : : binary_reader ;
2018-03-06 04:06:00 +08:00
template < typename BasicJsonType >
2018-03-12 01:47:38 +08:00
friend class : : nlohmann : : detail : : json_sax_dom_parser ;
2018-03-18 22:13:53 +08:00
template < typename BasicJsonType >
friend class : : nlohmann : : detail : : json_sax_dom_callback_parser ;
2018-01-10 01:30:02 +08:00
/// workaround type for MSVC
using basic_json_t = NLOHMANN_BASIC_JSON_TPL ;
// convenience aliases for types residing in namespace detail;
using lexer = : : nlohmann : : detail : : lexer < basic_json > ;
using parser = : : nlohmann : : detail : : parser < basic_json > ;
using primitive_iterator_t = : : nlohmann : : detail : : primitive_iterator_t ;
template < typename BasicJsonType >
using internal_iterator = : : nlohmann : : detail : : internal_iterator < BasicJsonType > ;
template < typename BasicJsonType >
using iter_impl = : : nlohmann : : detail : : iter_impl < BasicJsonType > ;
template < typename Iterator >
using iteration_proxy = : : nlohmann : : detail : : iteration_proxy < Iterator > ;
template < typename Base > using json_reverse_iterator = : : nlohmann : : detail : : json_reverse_iterator < Base > ;
template < typename CharType >
using output_adapter_t = : : nlohmann : : detail : : output_adapter_t < CharType > ;
using binary_reader = : : nlohmann : : detail : : binary_reader < basic_json > ;
template < typename CharType > using binary_writer = : : nlohmann : : detail : : binary_writer < basic_json , CharType > ;
using serializer = : : nlohmann : : detail : : serializer < basic_json > ;
public :
using value_t = detail : : value_t ;
2018-08-17 03:53:47 +08:00
/// JSON Pointer, see @ref nlohmann::json_pointer
2018-01-28 22:36:56 +08:00
using json_pointer = : : nlohmann : : json_pointer < basic_json > ;
2018-01-10 01:30:02 +08:00
template < typename T , typename SFINAE >
using json_serializer = JSONSerializer < T , SFINAE > ;
2018-10-21 17:49:37 +08:00
/// how to treat decoding errors
using error_handler_t = detail : : error_handler_t ;
2018-01-10 01:30:02 +08:00
/// helper type for initializer lists of basic_json values
using initializer_list_t = std : : initializer_list < detail : : json_ref < basic_json > > ;
2018-03-21 05:39:08 +08:00
using input_format_t = detail : : input_format_t ;
2018-08-17 03:53:47 +08:00
/// SAX interface type, see @ref nlohmann::json_sax
2018-08-16 16:52:33 +08:00
using json_sax_t = json_sax < basic_json > ;
2018-03-21 05:39:08 +08:00
2018-01-10 01:30:02 +08:00
////////////////
// exceptions //
////////////////
/// @name exceptions
/// Classes to implement user-defined exceptions.
/// @{
/// @copydoc detail::exception
using exception = detail : : exception ;
/// @copydoc detail::parse_error
using parse_error = detail : : parse_error ;
/// @copydoc detail::invalid_iterator
using invalid_iterator = detail : : invalid_iterator ;
/// @copydoc detail::type_error
using type_error = detail : : type_error ;
/// @copydoc detail::out_of_range
using out_of_range = detail : : out_of_range ;
/// @copydoc detail::other_error
using other_error = detail : : other_error ;
/// @}
/////////////////////
// container types //
/////////////////////
/// @name container types
/// The canonic container types to use @ref basic_json like any other STL
/// container.
/// @{
/// the type of elements in a basic_json container
using value_type = basic_json ;
/// the type of an element reference
using reference = value_type & ;
/// the type of an element const reference
using const_reference = const value_type & ;
/// a type to represent differences between iterators
using difference_type = std : : ptrdiff_t ;
/// a type to represent container sizes
using size_type = std : : size_t ;
/// the allocator type
using allocator_type = AllocatorType < basic_json > ;
/// the type of an element pointer
using pointer = typename std : : allocator_traits < allocator_type > : : pointer ;
/// the type of an element const pointer
using const_pointer = typename std : : allocator_traits < allocator_type > : : const_pointer ;
/// an iterator for a basic_json container
using iterator = iter_impl < basic_json > ;
/// a const iterator for a basic_json container
using const_iterator = iter_impl < const basic_json > ;
/// a reverse iterator for a basic_json container
using reverse_iterator = json_reverse_iterator < typename basic_json : : iterator > ;
/// a const reverse iterator for a basic_json container
using const_reverse_iterator = json_reverse_iterator < typename basic_json : : const_iterator > ;
/// @}
/*!
@ brief returns the allocator associated with the container
*/
static allocator_type get_allocator ( )
{
return allocator_type ( ) ;
}
/*!
@ brief returns version information on the library
This function returns a JSON object with information about the library ,
including the version number and information on the platform and compiler .
@ return JSON object holding version information
key | description
- - - - - - - - - - - | - - - - - - - - - - - - - - -
` compiler ` | Information on the used compiler . It is an object with the following keys : ` c + + ` ( the used C + + standard ) , ` family ` ( the compiler family ; possible values are ` clang ` , ` icc ` , ` gcc ` , ` ilecpp ` , ` msvc ` , ` pgcpp ` , ` sunpro ` , and ` unknown ` ) , and ` version ` ( the compiler version ) .
` copyright ` | The copyright line for the library as string .
` name ` | The name of the library as string .
` platform ` | The used platform as string . Possible values are ` win32 ` , ` linux ` , ` apple ` , ` unix ` , and ` unknown ` .
` url ` | The URL of the project as string .
` version ` | The version of the library . It is an object with the following keys : ` major ` , ` minor ` , and ` patch ` as defined by [ Semantic Versioning ] ( http : //semver.org), and `string` (the version string).
@ liveexample { The following code shows an example output of the ` meta ( ) `
function . , meta }
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes to any JSON value .
@ complexity Constant .
@ since 2.1 .0
*/
static basic_json meta ( )
{
basic_json result ;
result [ " copyright " ] = " (C) 2013-2017 Niels Lohmann " ;
result [ " name " ] = " JSON for Modern C++ " ;
result [ " url " ] = " https://github.com/nlohmann/json " ;
2018-02-01 05:36:18 +08:00
result [ " version " ] [ " string " ] =
std : : to_string ( NLOHMANN_JSON_VERSION_MAJOR ) + " . " +
std : : to_string ( NLOHMANN_JSON_VERSION_MINOR ) + " . " +
std : : to_string ( NLOHMANN_JSON_VERSION_PATCH ) ;
result [ " version " ] [ " major " ] = NLOHMANN_JSON_VERSION_MAJOR ;
result [ " version " ] [ " minor " ] = NLOHMANN_JSON_VERSION_MINOR ;
result [ " version " ] [ " patch " ] = NLOHMANN_JSON_VERSION_PATCH ;
2018-01-10 01:30:02 +08:00
# ifdef _WIN32
result [ " platform " ] = " win32 " ;
# elif defined __linux__
result [ " platform " ] = " linux " ;
# elif defined __APPLE__
result [ " platform " ] = " apple " ;
# elif defined __unix__
result [ " platform " ] = " unix " ;
# else
result [ " platform " ] = " unknown " ;
# endif
# if defined(__ICC) || defined(__INTEL_COMPILER)
result [ " compiler " ] = { { " family " , " icc " } , { " version " , __INTEL_COMPILER } } ;
# elif defined(__clang__)
result [ " compiler " ] = { { " family " , " clang " } , { " version " , __clang_version__ } } ;
# elif defined(__GNUC__) || defined(__GNUG__)
result [ " compiler " ] = { { " family " , " gcc " } , { " version " , std : : to_string ( __GNUC__ ) + " . " + std : : to_string ( __GNUC_MINOR__ ) + " . " + std : : to_string ( __GNUC_PATCHLEVEL__ ) } } ;
# elif defined(__HP_cc) || defined(__HP_aCC)
result [ " compiler " ] = " hp "
# elif defined(__IBMCPP__)
result [ " compiler " ] = { { " family " , " ilecpp " } , { " version " , __IBMCPP__ } } ;
# elif defined(_MSC_VER)
result [ " compiler " ] = { { " family " , " msvc " } , { " version " , _MSC_VER } } ;
# elif defined(__PGI)
result [ " compiler " ] = { { " family " , " pgcpp " } , { " version " , __PGI } } ;
# elif defined(__SUNPRO_CC)
result [ " compiler " ] = { { " family " , " sunpro " } , { " version " , __SUNPRO_CC } } ;
# else
result [ " compiler " ] = { { " family " , " unknown " } , { " version " , " unknown " } } ;
# endif
# ifdef __cplusplus
result [ " compiler " ] [ " c++ " ] = std : : to_string ( __cplusplus ) ;
# else
result [ " compiler " ] [ " c++ " ] = " unknown " ;
# endif
return result ;
}
///////////////////////////
// JSON value data types //
///////////////////////////
/// @name JSON value data types
/// The data types to store a JSON value. These types are derived from
/// the template arguments passed to class @ref basic_json.
/// @{
# if defined(JSON_HAS_CPP_14)
// Use transparent comparator if possible, combined with perfect forwarding
// on find() and count() calls prevents unnecessary string construction.
using object_comparator_t = std : : less < > ;
# else
using object_comparator_t = std : : less < StringType > ;
# endif
/*!
@ brief a type for an object
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) describes JSON objects as follows:
> An object is an unordered collection of zero or more name / value pairs ,
> where a name is a string and a value is a string , number , boolean , null ,
> object , or array .
To store objects in C + + , a type is defined by the template parameters
described below .
@ tparam ObjectType the container to store objects ( e . g . , ` std : : map ` or
` std : : unordered_map ` )
@ tparam StringType the type of the keys or names ( e . g . , ` std : : string ` ) .
The comparison function ` std : : less < StringType > ` is used to order elements
inside the container .
@ tparam AllocatorType the allocator to use for objects ( e . g . ,
` std : : allocator ` )
# ### Default type
With the default values for @ a ObjectType ( ` std : : map ` ) , @ a StringType
( ` std : : string ` ) , and @ a AllocatorType ( ` std : : allocator ` ) , the default
value for @ a object_t is :
@ code { . cpp }
std : : map <
std : : string , // key_type
basic_json , // value_type
std : : less < std : : string > , // key_compare
std : : allocator < std : : pair < const std : : string , basic_json > > // allocator_type
>
@ endcode
# ### Behavior
The choice of @ a object_t influences the behavior of the JSON class . With
the default type , objects have the following behavior :
- When all names are unique , objects will be interoperable in the sense
that all software implementations receiving that object will agree on
the name - value mappings .
2018-02-10 06:37:20 +08:00
- When the names within an object are not unique , it is unspecified which
one of the values for a given key will be chosen . For instance ,
` { " key " : 2 , " key " : 1 } ` could be equal to either ` { " key " : 1 } ` or
` { " key " : 2 } ` .
2018-01-10 01:30:02 +08:00
- Internally , name / value pairs are stored in lexicographical order of the
names . Objects will also be serialized ( see @ ref dump ) in this order .
For instance , ` { " b " : 1 , " a " : 2 } ` and ` { " a " : 2 , " b " : 1 } ` will be stored
and serialized as ` { " a " : 2 , " b " : 1 } ` .
- When comparing objects , the order of the name / value pairs is irrelevant .
This makes objects interoperable in the sense that they will not be
affected by these differences . For instance , ` { " b " : 1 , " a " : 2 } ` and
` { " a " : 2 , " b " : 1 } ` will be treated as equal .
# ### Limits
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) specifies:
> An implementation may set limits on the maximum depth of nesting .
In this class , the object ' s limit of nesting is not explicitly constrained .
However , a maximum depth of nesting may be introduced by the compiler or
runtime environment . A theoretical limit can be queried by calling the
@ ref max_size function of a JSON object .
# ### Storage
Objects are stored as pointers in a @ ref basic_json type . That is , for any
access to object values , a pointer of type ` object_t * ` must be
dereferenced .
@ sa @ ref array_t - - type for an array value
@ since version 1.0 .0
@ note The order name / value pairs are added to the object is * not *
preserved by the library . Therefore , iterating an object may return
name / value pairs in a different order than they were originally stored . In
fact , keys will be traversed in alphabetical order as ` std : : map ` with
` std : : less ` is used by default . Please note this behavior conforms to [ RFC
7159 ] ( http : //rfc7159.net/rfc7159), because any order implements the
specified " unordered " nature of JSON objects .
*/
using object_t = ObjectType < StringType ,
basic_json ,
object_comparator_t ,
AllocatorType < std : : pair < const StringType ,
basic_json > > > ;
/*!
@ brief a type for an array
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) describes JSON arrays as follows:
> An array is an ordered sequence of zero or more values .
To store objects in C + + , a type is defined by the template parameters
explained below .
@ tparam ArrayType container type to store arrays ( e . g . , ` std : : vector ` or
` std : : list ` )
@ tparam AllocatorType allocator to use for arrays ( e . g . , ` std : : allocator ` )
# ### Default type
With the default values for @ a ArrayType ( ` std : : vector ` ) and @ a
AllocatorType ( ` std : : allocator ` ) , the default value for @ a array_t is :
@ code { . cpp }
std : : vector <
basic_json , // value_type
std : : allocator < basic_json > // allocator_type
>
@ endcode
# ### Limits
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) specifies:
> An implementation may set limits on the maximum depth of nesting .
In this class , the array ' s limit of nesting is not explicitly constrained .
However , a maximum depth of nesting may be introduced by the compiler or
runtime environment . A theoretical limit can be queried by calling the
@ ref max_size function of a JSON array .
# ### Storage
Arrays are stored as pointers in a @ ref basic_json type . That is , for any
access to array values , a pointer of type ` array_t * ` must be dereferenced .
@ sa @ ref object_t - - type for an object value
@ since version 1.0 .0
*/
using array_t = ArrayType < basic_json , AllocatorType < basic_json > > ;
/*!
@ brief a type for a string
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) describes JSON strings as follows:
> A string is a sequence of zero or more Unicode characters .
To store objects in C + + , a type is defined by the template parameter
described below . Unicode values are split by the JSON class into
byte - sized characters during deserialization .
@ tparam StringType the container to store strings ( e . g . , ` std : : string ` ) .
Note this container is used for keys / names in objects , see @ ref object_t .
# ### Default type
With the default values for @ a StringType ( ` std : : string ` ) , the default
value for @ a string_t is :
@ code { . cpp }
std : : string
@ endcode
# ### Encoding
Strings are stored in UTF - 8 encoding . Therefore , functions like
` std : : string : : size ( ) ` or ` std : : string : : length ( ) ` return the number of
bytes in the string rather than the number of characters or glyphs .
# ### String comparison
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) states:
> Software implementations are typically required to test names of object
> members for equality . Implementations that transform the textual
> representation into sequences of Unicode code units and then perform the
> comparison numerically , code unit by code unit , are interoperable in the
> sense that implementations will agree in all cases on equality or
> inequality of two strings . For example , implementations that compare
> strings with escaped characters unconverted may incorrectly find that
> ` " a \\ b " ` and ` " a \u005C b " ` are not equal .
This implementation is interoperable as it does compare strings code unit
by code unit .
# ### Storage
String values are stored as pointers in a @ ref basic_json type . That is ,
for any access to string values , a pointer of type ` string_t * ` must be
dereferenced .
@ since version 1.0 .0
*/
using string_t = StringType ;
/*!
@ brief a type for a boolean
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) implicitly describes a boolean as a
type which differentiates the two literals ` true ` and ` false ` .
To store objects in C + + , a type is defined by the template parameter @ a
BooleanType which chooses the type to use .
# ### Default type
With the default values for @ a BooleanType ( ` bool ` ) , the default value for
@ a boolean_t is :
@ code { . cpp }
bool
@ endcode
# ### Storage
Boolean values are stored directly inside a @ ref basic_json type .
@ since version 1.0 .0
*/
using boolean_t = BooleanType ;
/*!
@ brief a type for a number ( integer )
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) describes numbers as follows:
> The representation of numbers is similar to that used in most
> programming languages . A number is represented in base 10 using decimal
> digits . It contains an integer component that may be prefixed with an
> optional minus sign , which may be followed by a fraction part and / or an
> exponent part . Leading zeros are not allowed . ( . . . ) Numeric values that
> cannot be represented in the grammar below ( such as Infinity and NaN )
> are not permitted .
This description includes both integer and floating - point numbers .
However , C + + allows more precise storage if it is known whether the number
is a signed integer , an unsigned integer or a floating - point number .
Therefore , three different types , @ ref number_integer_t , @ ref
number_unsigned_t and @ ref number_float_t are used .
To store integer numbers in C + + , a type is defined by the template
parameter @ a NumberIntegerType which chooses the type to use .
# ### Default type
With the default values for @ a NumberIntegerType ( ` int64_t ` ) , the default
value for @ a number_integer_t is :
@ code { . cpp }
int64_t
@ endcode
# ### Default behavior
- The restrictions about leading zeros is not enforced in C + + . Instead ,
leading zeros in integer literals lead to an interpretation as octal
number . Internally , the value will be stored as decimal number . For
instance , the C + + integer literal ` 010 ` will be serialized to ` 8 ` .
During deserialization , leading zeros yield an error .
- Not - a - number ( NaN ) values will be serialized to ` null ` .
# ### Limits
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) specifies:
> An implementation may set limits on the range and precision of numbers .
When the default type is used , the maximal integer number that can be
stored is ` 9223372036854775807 ` ( INT64_MAX ) and the minimal integer number
that can be stored is ` - 9223372036854775808 ` ( INT64_MIN ) . Integer numbers
that are out of range will yield over / underflow when used in a
constructor . During deserialization , too large or small integer numbers
will be automatically be stored as @ ref number_unsigned_t or @ ref
number_float_t .
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) further states:
> Note that when such software is used , numbers that are integers and are
> in the range \ f $ [ - 2 ^ { 53 } + 1 , 2 ^ { 53 } - 1 ] \ f $ are interoperable in the sense
> that implementations will agree exactly on their numeric values .
As this range is a subrange of the exactly supported range [ INT64_MIN ,
INT64_MAX ] , this class ' s integer type is interoperable .
# ### Storage
Integer number values are stored directly inside a @ ref basic_json type .
@ sa @ ref number_float_t - - type for number values ( floating - point )
@ sa @ ref number_unsigned_t - - type for number values ( unsigned integer )
@ since version 1.0 .0
*/
using number_integer_t = NumberIntegerType ;
/*!
@ brief a type for a number ( unsigned )
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) describes numbers as follows:
> The representation of numbers is similar to that used in most
> programming languages . A number is represented in base 10 using decimal
> digits . It contains an integer component that may be prefixed with an
> optional minus sign , which may be followed by a fraction part and / or an
> exponent part . Leading zeros are not allowed . ( . . . ) Numeric values that
> cannot be represented in the grammar below ( such as Infinity and NaN )
> are not permitted .
This description includes both integer and floating - point numbers .
However , C + + allows more precise storage if it is known whether the number
is a signed integer , an unsigned integer or a floating - point number .
Therefore , three different types , @ ref number_integer_t , @ ref
number_unsigned_t and @ ref number_float_t are used .
To store unsigned integer numbers in C + + , a type is defined by the
template parameter @ a NumberUnsignedType which chooses the type to use .
# ### Default type
With the default values for @ a NumberUnsignedType ( ` uint64_t ` ) , the
default value for @ a number_unsigned_t is :
@ code { . cpp }
uint64_t
@ endcode
# ### Default behavior
- The restrictions about leading zeros is not enforced in C + + . Instead ,
leading zeros in integer literals lead to an interpretation as octal
number . Internally , the value will be stored as decimal number . For
instance , the C + + integer literal ` 010 ` will be serialized to ` 8 ` .
During deserialization , leading zeros yield an error .
- Not - a - number ( NaN ) values will be serialized to ` null ` .
# ### Limits
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) specifies:
> An implementation may set limits on the range and precision of numbers .
When the default type is used , the maximal integer number that can be
stored is ` 18446744073709551615 ` ( UINT64_MAX ) and the minimal integer
number that can be stored is ` 0 ` . Integer numbers that are out of range
will yield over / underflow when used in a constructor . During
deserialization , too large or small integer numbers will be automatically
be stored as @ ref number_integer_t or @ ref number_float_t .
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) further states:
> Note that when such software is used , numbers that are integers and are
> in the range \ f $ [ - 2 ^ { 53 } + 1 , 2 ^ { 53 } - 1 ] \ f $ are interoperable in the sense
> that implementations will agree exactly on their numeric values .
As this range is a subrange ( when considered in conjunction with the
number_integer_t type ) of the exactly supported range [ 0 , UINT64_MAX ] ,
this class ' s integer type is interoperable .
# ### Storage
Integer number values are stored directly inside a @ ref basic_json type .
@ sa @ ref number_float_t - - type for number values ( floating - point )
@ sa @ ref number_integer_t - - type for number values ( integer )
@ since version 2.0 .0
*/
using number_unsigned_t = NumberUnsignedType ;
/*!
@ brief a type for a number ( floating - point )
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) describes numbers as follows:
> The representation of numbers is similar to that used in most
> programming languages . A number is represented in base 10 using decimal
> digits . It contains an integer component that may be prefixed with an
> optional minus sign , which may be followed by a fraction part and / or an
> exponent part . Leading zeros are not allowed . ( . . . ) Numeric values that
> cannot be represented in the grammar below ( such as Infinity and NaN )
> are not permitted .
This description includes both integer and floating - point numbers .
However , C + + allows more precise storage if it is known whether the number
is a signed integer , an unsigned integer or a floating - point number .
Therefore , three different types , @ ref number_integer_t , @ ref
number_unsigned_t and @ ref number_float_t are used .
To store floating - point numbers in C + + , a type is defined by the template
parameter @ a NumberFloatType which chooses the type to use .
# ### Default type
With the default values for @ a NumberFloatType ( ` double ` ) , the default
value for @ a number_float_t is :
@ code { . cpp }
double
@ endcode
# ### Default behavior
- The restrictions about leading zeros is not enforced in C + + . Instead ,
leading zeros in floating - point literals will be ignored . Internally ,
the value will be stored as decimal number . For instance , the C + +
floating - point literal ` 01.2 ` will be serialized to ` 1.2 ` . During
deserialization , leading zeros yield an error .
- Not - a - number ( NaN ) values will be serialized to ` null ` .
# ### Limits
[ RFC 7159 ] ( http : //rfc7159.net/rfc7159) states:
> This specification allows implementations to set limits on the range and
> precision of numbers accepted . Since software that implements IEEE
> 754 - 2008 binary64 ( double precision ) numbers is generally available and
> widely used , good interoperability can be achieved by implementations
> that expect no more precision or range than these provide , in the sense
> that implementations will approximate JSON numbers within the expected
> precision .
This implementation does exactly follow this approach , as it uses double
precision floating - point numbers . Note values smaller than
` - 1.79769313486232e+308 ` and values greater than ` 1.79769313486232e+308 `
will be stored as NaN internally and be serialized to ` null ` .
# ### Storage
Floating - point number values are stored directly inside a @ ref basic_json
type .
@ sa @ ref number_integer_t - - type for number values ( integer )
@ sa @ ref number_unsigned_t - - type for number values ( unsigned integer )
@ since version 1.0 .0
*/
using number_float_t = NumberFloatType ;
/// @}
private :
/// helper for exception-safe object creation
template < typename T , typename . . . Args >
static T * create ( Args & & . . . args )
{
AllocatorType < T > alloc ;
using AllocatorTraits = std : : allocator_traits < AllocatorType < T > > ;
auto deleter = [ & ] ( T * object )
{
AllocatorTraits : : deallocate ( alloc , object , 1 ) ;
} ;
std : : unique_ptr < T , decltype ( deleter ) > object ( AllocatorTraits : : allocate ( alloc , 1 ) , deleter ) ;
AllocatorTraits : : construct ( alloc , object . get ( ) , std : : forward < Args > ( args ) . . . ) ;
assert ( object ! = nullptr ) ;
return object . release ( ) ;
}
////////////////////////
// JSON value storage //
////////////////////////
/*!
@ brief a JSON value
The actual storage for a JSON value of the @ ref basic_json class . This
union combines the different storage types for the JSON value types
defined in @ ref value_t .
JSON type | value_t type | used type
- - - - - - - - - | - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - -
object | object | pointer to @ ref object_t
array | array | pointer to @ ref array_t
string | string | pointer to @ ref string_t
boolean | boolean | @ ref boolean_t
number | number_integer | @ ref number_integer_t
number | number_unsigned | @ ref number_unsigned_t
number | number_float | @ ref number_float_t
null | null | * no value is stored *
@ note Variable - length types ( objects , arrays , and strings ) are stored as
pointers . The size of the union should not exceed 64 bits if the default
value types are used .
@ since version 1.0 .0
*/
union json_value
{
/// object (stored with pointer to save storage)
object_t * object ;
/// array (stored with pointer to save storage)
array_t * array ;
/// string (stored with pointer to save storage)
string_t * string ;
/// boolean
boolean_t boolean ;
/// number (integer)
number_integer_t number_integer ;
/// number (unsigned integer)
number_unsigned_t number_unsigned ;
/// number (floating-point)
number_float_t number_float ;
/// default constructor (for null values)
json_value ( ) = default ;
/// constructor for booleans
json_value ( boolean_t v ) noexcept : boolean ( v ) { }
/// constructor for numbers (integer)
json_value ( number_integer_t v ) noexcept : number_integer ( v ) { }
/// constructor for numbers (unsigned)
json_value ( number_unsigned_t v ) noexcept : number_unsigned ( v ) { }
/// constructor for numbers (floating-point)
json_value ( number_float_t v ) noexcept : number_float ( v ) { }
/// constructor for empty values of a given type
json_value ( value_t t )
{
switch ( t )
{
case value_t : : object :
{
object = create < object_t > ( ) ;
break ;
}
case value_t : : array :
{
array = create < array_t > ( ) ;
break ;
}
case value_t : : string :
{
string = create < string_t > ( " " ) ;
break ;
}
case value_t : : boolean :
{
boolean = boolean_t ( false ) ;
break ;
}
case value_t : : number_integer :
{
number_integer = number_integer_t ( 0 ) ;
break ;
}
case value_t : : number_unsigned :
{
number_unsigned = number_unsigned_t ( 0 ) ;
break ;
}
case value_t : : number_float :
{
number_float = number_float_t ( 0.0 ) ;
break ;
}
case value_t : : null :
{
object = nullptr ; // silence warning, see #821
break ;
}
default :
{
object = nullptr ; // silence warning, see #821
if ( JSON_UNLIKELY ( t = = value_t : : null ) )
{
2018-10-31 04:30:20 +08:00
JSON_THROW ( other_error : : create ( 500 , " 961c151d2e87f2686a955a9be24d316f1362bf21 3.4.0 " ) ) ; // LCOV_EXCL_LINE
2018-01-10 01:30:02 +08:00
}
break ;
}
}
}
/// constructor for strings
json_value ( const string_t & value )
{
string = create < string_t > ( value ) ;
}
/// constructor for rvalue strings
json_value ( string_t & & value )
{
2018-03-10 18:02:58 +08:00
string = create < string_t > ( std : : move ( value ) ) ;
2018-01-10 01:30:02 +08:00
}
/// constructor for objects
json_value ( const object_t & value )
{
object = create < object_t > ( value ) ;
}
/// constructor for rvalue objects
json_value ( object_t & & value )
{
2018-03-10 18:02:58 +08:00
object = create < object_t > ( std : : move ( value ) ) ;
2018-01-10 01:30:02 +08:00
}
/// constructor for arrays
json_value ( const array_t & value )
{
array = create < array_t > ( value ) ;
}
/// constructor for rvalue arrays
json_value ( array_t & & value )
{
2018-03-10 18:02:58 +08:00
array = create < array_t > ( std : : move ( value ) ) ;
2018-01-10 01:30:02 +08:00
}
2018-01-17 03:41:04 +08:00
void destroy ( value_t t ) noexcept
2018-01-10 01:30:02 +08:00
{
switch ( t )
{
case value_t : : object :
{
AllocatorType < object_t > alloc ;
std : : allocator_traits < decltype ( alloc ) > : : destroy ( alloc , object ) ;
std : : allocator_traits < decltype ( alloc ) > : : deallocate ( alloc , object , 1 ) ;
break ;
}
case value_t : : array :
{
AllocatorType < array_t > alloc ;
std : : allocator_traits < decltype ( alloc ) > : : destroy ( alloc , array ) ;
std : : allocator_traits < decltype ( alloc ) > : : deallocate ( alloc , array , 1 ) ;
break ;
}
case value_t : : string :
{
AllocatorType < string_t > alloc ;
std : : allocator_traits < decltype ( alloc ) > : : destroy ( alloc , string ) ;
std : : allocator_traits < decltype ( alloc ) > : : deallocate ( alloc , string , 1 ) ;
break ;
}
default :
{
break ;
}
}
}
} ;
/*!
@ brief checks the class invariants
This function asserts the class invariants . It needs to be called at the
end of every constructor to make sure that created objects respect the
invariant . Furthermore , it has to be called each time the type of a JSON
value is changed , because the invariant expresses a relationship between
@ a m_type and @ a m_value .
*/
2018-01-17 03:41:04 +08:00
void assert_invariant ( ) const noexcept
2018-01-10 01:30:02 +08:00
{
assert ( m_type ! = value_t : : object or m_value . object ! = nullptr ) ;
assert ( m_type ! = value_t : : array or m_value . array ! = nullptr ) ;
assert ( m_type ! = value_t : : string or m_value . string ! = nullptr ) ;
}
public :
//////////////////////////
// JSON parser callback //
//////////////////////////
/*!
@ brief parser event types
The parser callback distinguishes the following events :
- ` object_start ` : the parser read ` { ` and started to process a JSON object
- ` key ` : the parser read a key of a value in an object
- ` object_end ` : the parser read ` } ` and finished processing a JSON object
- ` array_start ` : the parser read ` [ ` and started to process a JSON array
- ` array_end ` : the parser read ` ] ` and finished processing a JSON array
- ` value ` : the parser finished reading a JSON value
@ image html callback_events . png " Example when certain parse events are triggered "
@ sa @ ref parser_callback_t for more information and examples
*/
using parse_event_t = typename parser : : parse_event_t ;
/*!
@ brief per - element parser callback type
With a parser callback function , the result of parsing a JSON text can be
influenced . When passed to @ ref parse , it is called on certain events
( passed as @ ref parse_event_t via parameter @ a event ) with a set recursion
depth @ a depth and context JSON value @ a parsed . The return value of the
callback function is a boolean indicating whether the element that emitted
the callback shall be kept or not .
We distinguish six scenarios ( determined by the event type ) in which the
callback function can be called . The following table describes the values
of the parameters @ a depth , @ a event , and @ a parsed .
parameter @ a event | description | parameter @ a depth | parameter @ a parsed
- - - - - - - - - - - - - - - - - - | - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - -
parse_event_t : : object_start | the parser read ` { ` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
parse_event_t : : key | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
parse_event_t : : object_end | the parser read ` } ` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
parse_event_t : : array_start | the parser read ` [ ` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
parse_event_t : : array_end | the parser read ` ] ` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
parse_event_t : : value | the parser finished reading a JSON value | depth of the value | the parsed JSON value
@ image html callback_events . png " Example when certain parse events are triggered "
Discarding a value ( i . e . , returning ` false ` ) has different effects
depending on the context in which function was called :
- Discarded values in structured types are skipped . That is , the parser
will behave as if the discarded value was never read .
- In case a value outside a structured type is skipped , it is replaced
with ` null ` . This case happens if the top - level element is skipped .
@ param [ in ] depth the depth of the recursion during parsing
@ param [ in ] event an event of type parse_event_t indicating the context in
the callback function has been called
@ param [ in , out ] parsed the current intermediate parse result ; note that
writing to this value has no effect for parse_event_t : : key events
@ return Whether the JSON value which called the function during parsing
should be kept ( ` true ` ) or not ( ` false ` ) . In the latter case , it is either
skipped completely or replaced by an empty discarded object .
@ sa @ ref parse for examples
@ since version 1.0 .0
*/
using parser_callback_t = typename parser : : parser_callback_t ;
//////////////////
// constructors //
//////////////////
/// @name constructors and destructors
/// Constructors of class @ref basic_json, copy/move constructor, copy
/// assignment, static functions creating objects, and the destructor.
/// @{
/*!
@ brief create an empty value with a given type
Create an empty JSON value with a given type . The value will be default
initialized with an empty value which depends on the type :
Value type | initial value
- - - - - - - - - - - | - - - - - - - - - - - - -
null | ` null `
boolean | ` false `
string | ` " " `
number | ` 0 `
object | ` { } `
array | ` [ ] `
@ param [ in ] v the type of the value to create
@ complexity Constant .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes to any JSON value .
@ liveexample { The following code shows the constructor for different @ ref
value_t values , basic_json__value_t }
@ sa @ ref clear ( ) - - restores the postcondition of this constructor
@ since version 1.0 .0
*/
basic_json ( const value_t v )
: m_type ( v ) , m_value ( v )
{
assert_invariant ( ) ;
}
/*!
@ brief create a null object
Create a ` null ` JSON value . It either takes a null pointer as parameter
( explicitly creating ` null ` ) or no parameter ( implicitly creating ` null ` ) .
The passed null pointer itself is not read - - it is only used to choose
the right constructor .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this constructor never throws
exceptions .
@ liveexample { The following code shows the constructor with and without a
null pointer parameter . , basic_json__nullptr_t }
@ since version 1.0 .0
*/
basic_json ( std : : nullptr_t = nullptr ) noexcept
: basic_json ( value_t : : null )
{
assert_invariant ( ) ;
}
/*!
@ brief create a JSON value
This is a " catch all " constructor for all compatible JSON types ; that is ,
types for which a ` to_json ( ) ` method exists . The constructor forwards the
parameter @ a val to that method ( to ` json_serializer < U > : : to_json ` method
with ` U = uncvref_t < CompatibleType > ` , to be exact ) .
Template type @ a CompatibleType includes , but is not limited to , the
following types :
- * * arrays * * : @ ref array_t and all kinds of compatible containers such as
` std : : vector ` , ` std : : deque ` , ` std : : list ` , ` std : : forward_list ` ,
` std : : array ` , ` std : : valarray ` , ` std : : set ` , ` std : : unordered_set ` ,
` std : : multiset ` , and ` std : : unordered_multiset ` with a ` value_type ` from
which a @ ref basic_json value can be constructed .
- * * objects * * : @ ref object_t and all kinds of compatible associative
containers such as ` std : : map ` , ` std : : unordered_map ` , ` std : : multimap ` ,
and ` std : : unordered_multimap ` with a ` key_type ` compatible to
@ ref string_t and a ` value_type ` from which a @ ref basic_json value can
be constructed .
- * * strings * * : @ ref string_t , string literals , and all compatible string
containers can be used .
- * * numbers * * : @ ref number_integer_t , @ ref number_unsigned_t ,
@ ref number_float_t , and all convertible number types such as ` int ` ,
` size_t ` , ` int64_t ` , ` float ` or ` double ` can be used .
- * * boolean * * : @ ref boolean_t / ` bool ` can be used .
See the examples below .
@ tparam CompatibleType a type such that :
- @ a CompatibleType is not derived from ` std : : istream ` ,
- @ a CompatibleType is not @ ref basic_json ( to avoid hijacking copy / move
constructors ) ,
2018-02-27 19:11:04 +08:00
- @ a CompatibleType is not a different @ ref basic_json type ( i . e . with different template arguments )
2018-01-10 01:30:02 +08:00
- @ a CompatibleType is not a @ ref basic_json nested type ( e . g . ,
@ ref json_pointer , @ ref iterator , etc . . . )
- @ ref @ ref json_serializer < U > has a
` to_json ( basic_json_t & , CompatibleType & & ) ` method
@ tparam U = ` uncvref_t < CompatibleType > `
@ param [ in ] val the value to be forwarded to the respective constructor
@ complexity Usually linear in the size of the passed @ a val , also
depending on the implementation of the called ` to_json ( ) `
method .
@ exceptionsafety Depends on the called constructor . For types directly
supported by the library ( i . e . , all types for which no ` to_json ( ) ` function
was provided ) , strong guarantee holds : if an exception is thrown , there are
no changes to any JSON value .
@ liveexample { The following code shows the constructor with several
compatible types . , basic_json__CompatibleType }
@ since version 2.1 .0
*/
2018-01-17 19:17:38 +08:00
template < typename CompatibleType ,
typename U = detail : : uncvref_t < CompatibleType > ,
detail : : enable_if_t <
2018-09-07 18:42:49 +08:00
not detail : : is_basic_json < U > : : value and detail : : is_compatible_type < basic_json_t , U > : : value , int > = 0 >
2018-01-17 19:17:38 +08:00
basic_json ( CompatibleType & & val ) noexcept ( noexcept (
JSONSerializer < U > : : to_json ( std : : declval < basic_json_t & > ( ) ,
std : : forward < CompatibleType > ( val ) ) ) )
2018-01-10 01:30:02 +08:00
{
JSONSerializer < U > : : to_json ( * this , std : : forward < CompatibleType > ( val ) ) ;
assert_invariant ( ) ;
}
2018-02-27 19:11:04 +08:00
/*!
@ brief create a JSON value from an existing one
This is a constructor for existing @ ref basic_json types .
2018-03-07 03:13:31 +08:00
It does not hijack copy / move constructors , since the parameter has different
template arguments than the current ones .
2018-02-27 19:11:04 +08:00
The constructor tries to convert the internal @ ref m_value of the parameter .
@ tparam BasicJsonType a type such that :
- @ a BasicJsonType is a @ ref basic_json type .
- @ a BasicJsonType has different template arguments than @ ref basic_json_t .
@ param [ in ] val the @ ref basic_json value to be converted .
@ complexity Usually linear in the size of the passed @ a val , also
depending on the implementation of the called ` to_json ( ) `
method .
@ exceptionsafety Depends on the called constructor . For types directly
supported by the library ( i . e . , all types for which no ` to_json ( ) ` function
was provided ) , strong guarantee holds : if an exception is thrown , there are
no changes to any JSON value .
2018-08-18 18:00:14 +08:00
@ since version 3.2 .0
2018-02-27 19:11:04 +08:00
*/
template < typename BasicJsonType ,
detail : : enable_if_t <
detail : : is_basic_json < BasicJsonType > : : value and not std : : is_same < basic_json , BasicJsonType > : : value , int > = 0 >
basic_json ( const BasicJsonType & val )
{
using other_boolean_t = typename BasicJsonType : : boolean_t ;
using other_number_float_t = typename BasicJsonType : : number_float_t ;
using other_number_integer_t = typename BasicJsonType : : number_integer_t ;
using other_number_unsigned_t = typename BasicJsonType : : number_unsigned_t ;
using other_string_t = typename BasicJsonType : : string_t ;
using other_object_t = typename BasicJsonType : : object_t ;
using other_array_t = typename BasicJsonType : : array_t ;
switch ( val . type ( ) )
{
case value_t : : boolean :
JSONSerializer < other_boolean_t > : : to_json ( * this , val . template get < other_boolean_t > ( ) ) ;
break ;
case value_t : : number_float :
JSONSerializer < other_number_float_t > : : to_json ( * this , val . template get < other_number_float_t > ( ) ) ;
break ;
case value_t : : number_integer :
JSONSerializer < other_number_integer_t > : : to_json ( * this , val . template get < other_number_integer_t > ( ) ) ;
break ;
case value_t : : number_unsigned :
JSONSerializer < other_number_unsigned_t > : : to_json ( * this , val . template get < other_number_unsigned_t > ( ) ) ;
break ;
case value_t : : string :
JSONSerializer < other_string_t > : : to_json ( * this , val . template get_ref < const other_string_t & > ( ) ) ;
break ;
case value_t : : object :
JSONSerializer < other_object_t > : : to_json ( * this , val . template get_ref < const other_object_t & > ( ) ) ;
break ;
case value_t : : array :
JSONSerializer < other_array_t > : : to_json ( * this , val . template get_ref < const other_array_t & > ( ) ) ;
break ;
case value_t : : null :
* this = nullptr ;
break ;
case value_t : : discarded :
m_type = value_t : : discarded ;
break ;
}
assert_invariant ( ) ;
}
2018-01-10 01:30:02 +08:00
/*!
@ brief create a container ( array or object ) from an initializer list
Creates a JSON value of type array or object from the passed initializer
list @ a init . In case @ a type_deduction is ` true ` ( default ) , the type of
the JSON value to be created is deducted from the initializer list @ a init
according to the following rules :
1. If the list is empty , an empty JSON object value ` { } ` is created .
2. If the list consists of pairs whose first element is a string , a JSON
object value is created where the first elements of the pairs are
treated as keys and the second elements are as values .
3. In all other cases , an array is created .
The rules aim to create the best fit between a C + + initializer list and
JSON values . The rationale is as follows :
1. The empty initializer list is written as ` { } ` which is exactly an empty
JSON object .
2. C + + has no way of describing mapped types other than to list a list of
pairs . As JSON requires that keys must be of type string , rule 2 is the
weakest constraint one can pose on initializer lists to interpret them
as an object .
3. In all other cases , the initializer list could not be interpreted as
JSON object type , so interpreting it as JSON array type is safe .
With the rules described above , the following JSON values cannot be
expressed by an initializer list :
- the empty array ( ` [ ] ` ) : use @ ref array ( initializer_list_t )
with an empty initializer list in this case
- arrays whose elements satisfy rule 2 : use @ ref
array ( initializer_list_t ) with the same initializer list
in this case
@ note When used without parentheses around an empty initializer list , @ ref
basic_json ( ) is called instead of this function , yielding the JSON null
value .
@ param [ in ] init initializer list with JSON values
@ param [ in ] type_deduction internal parameter ; when set to ` true ` , the type
of the JSON value is deducted from the initializer list @ a init ; when set
to ` false ` , the type provided via @ a manual_type is forced . This mode is
used by the functions @ ref array ( initializer_list_t ) and
@ ref object ( initializer_list_t ) .
@ param [ in ] manual_type internal parameter ; when @ a type_deduction is set
to ` false ` , the created JSON value will use the provided type ( only @ ref
value_t : : array and @ ref value_t : : object are valid ) ; when @ a type_deduction
is set to ` true ` , this parameter has no effect
@ throw type_error .301 if @ a type_deduction is ` false ` , @ a manual_type is
` value_t : : object ` , but @ a init contains an element which is not a pair
whose first element is a string . In this case , the constructor could not
create an object . If @ a type_deduction would have be ` true ` , an array
would have been created . See @ ref object ( initializer_list_t )
for an example .
@ complexity Linear in the size of the initializer list @ a init .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes to any JSON value .
@ liveexample { The example below shows how JSON values are created from
initializer lists . , basic_json__list_init_t }
@ sa @ ref array ( initializer_list_t ) - - create a JSON array
value from an initializer list
@ sa @ ref object ( initializer_list_t ) - - create a JSON object
value from an initializer list
@ since version 1.0 .0
*/
basic_json ( initializer_list_t init ,
bool type_deduction = true ,
value_t manual_type = value_t : : array )
{
// check if each element is an array with two elements whose first
// element is a string
bool is_an_object = std : : all_of ( init . begin ( ) , init . end ( ) ,
[ ] ( const detail : : json_ref < basic_json > & element_ref )
{
return ( element_ref - > is_array ( ) and element_ref - > size ( ) = = 2 and ( * element_ref ) [ 0 ] . is_string ( ) ) ;
} ) ;
// adjust type if type deduction is not wanted
if ( not type_deduction )
{
// if array is wanted, do not create an object though possible
if ( manual_type = = value_t : : array )
{
is_an_object = false ;
}
// if object is wanted but impossible, throw an exception
if ( JSON_UNLIKELY ( manual_type = = value_t : : object and not is_an_object ) )
{
JSON_THROW ( type_error : : create ( 301 , " cannot create object from initializer list " ) ) ;
}
}
if ( is_an_object )
{
// the initializer list is a list of pairs -> create object
m_type = value_t : : object ;
m_value = value_t : : object ;
std : : for_each ( init . begin ( ) , init . end ( ) , [ this ] ( const detail : : json_ref < basic_json > & element_ref )
{
auto element = element_ref . moved_or_copied ( ) ;
m_value . object - > emplace (
std : : move ( * ( ( * element . m_value . array ) [ 0 ] . m_value . string ) ) ,
std : : move ( ( * element . m_value . array ) [ 1 ] ) ) ;
} ) ;
}
else
{
// the initializer list describes an array -> create array
m_type = value_t : : array ;
m_value . array = create < array_t > ( init . begin ( ) , init . end ( ) ) ;
}
assert_invariant ( ) ;
}
/*!
@ brief explicitly create an array from an initializer list
Creates a JSON array value from a given initializer list . That is , given a
list of values ` a , b , c ` , creates the JSON value ` [ a , b , c ] ` . If the
initializer list is empty , the empty array ` [ ] ` is created .
@ note This function is only needed to express two edge cases that cannot
be realized with the initializer list constructor ( @ ref
basic_json ( initializer_list_t , bool , value_t ) ) . These cases
are :
1. creating an array whose elements are all pairs whose first element is a
string - - in this case , the initializer list constructor would create an
object , taking the first elements as keys
2. creating an empty array - - passing the empty initializer list to the
initializer list constructor yields an empty object
@ param [ in ] init initializer list with JSON values to create an array from
( optional )
@ return JSON array value
@ complexity Linear in the size of @ a init .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes to any JSON value .
@ liveexample { The following code shows an example for the ` array `
function . , array }
@ sa @ ref basic_json ( initializer_list_t , bool , value_t ) - -
create a JSON value from an initializer list
@ sa @ ref object ( initializer_list_t ) - - create a JSON object
value from an initializer list
@ since version 1.0 .0
*/
static basic_json array ( initializer_list_t init = { } )
{
return basic_json ( init , false , value_t : : array ) ;
}
/*!
@ brief explicitly create an object from an initializer list
Creates a JSON object value from a given initializer list . The initializer
lists elements must be pairs , and their first elements must be strings . If
the initializer list is empty , the empty object ` { } ` is created .
@ note This function is only added for symmetry reasons . In contrast to the
related function @ ref array ( initializer_list_t ) , there are
no cases which can only be expressed by this function . That is , any
initializer list @ a init can also be passed to the initializer list
constructor @ ref basic_json ( initializer_list_t , bool , value_t ) .
@ param [ in ] init initializer list to create an object from ( optional )
@ return JSON object value
@ throw type_error .301 if @ a init is not a list of pairs whose first
elements are strings . In this case , no object can be created . When such a
value is passed to @ ref basic_json ( initializer_list_t , bool , value_t ) ,
an array would have been created from the passed initializer list @ a init .
See example below .
@ complexity Linear in the size of @ a init .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes to any JSON value .
@ liveexample { The following code shows an example for the ` object `
function . , object }
@ sa @ ref basic_json ( initializer_list_t , bool , value_t ) - -
create a JSON value from an initializer list
@ sa @ ref array ( initializer_list_t ) - - create a JSON array
value from an initializer list
@ since version 1.0 .0
*/
static basic_json object ( initializer_list_t init = { } )
{
return basic_json ( init , false , value_t : : object ) ;
}
/*!
@ brief construct an array with count copies of given value
Constructs a JSON array value by creating @ a cnt copies of a passed value .
In case @ a cnt is ` 0 ` , an empty array is created .
@ param [ in ] cnt the number of JSON copies of @ a val to create
@ param [ in ] val the JSON value to copy
@ post ` std : : distance ( begin ( ) , end ( ) ) = = cnt ` holds .
@ complexity Linear in @ a cnt .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes to any JSON value .
@ liveexample { The following code shows examples for the @ ref
basic_json ( size_type \ , const basic_json & )
constructor . , basic_json__size_type_basic_json }
@ since version 1.0 .0
*/
basic_json ( size_type cnt , const basic_json & val )
: m_type ( value_t : : array )
{
m_value . array = create < array_t > ( cnt , val ) ;
assert_invariant ( ) ;
}
/*!
@ brief construct a JSON container given an iterator range
Constructs the JSON value with the contents of the range ` [ first , last ) ` .
The semantics depends on the different types a JSON value can have :
- In case of a null type , invalid_iterator .206 is thrown .
- In case of other primitive types ( number , boolean , or string ) , @ a first
must be ` begin ( ) ` and @ a last must be ` end ( ) ` . In this case , the value is
copied . Otherwise , invalid_iterator .204 is thrown .
- In case of structured types ( array , object ) , the constructor behaves as
similar versions for ` std : : vector ` or ` std : : map ` ; that is , a JSON array
or object is constructed from the values in the range .
@ tparam InputIT an input iterator type ( @ ref iterator or @ ref
const_iterator )
@ param [ in ] first begin of the range to copy from ( included )
@ param [ in ] last end of the range to copy from ( excluded )
@ pre Iterators @ a first and @ a last must be initialized . * * This
precondition is enforced with an assertion ( see warning ) . * * If
assertions are switched off , a violation of this precondition yields
undefined behavior .
@ pre Range ` [ first , last ) ` is valid . Usually , this precondition cannot be
checked efficiently . Only certain edge cases are detected ; see the
description of the exceptions below . A violation of this precondition
yields undefined behavior .
@ warning A precondition is enforced with a runtime assertion that will
result in calling ` std : : abort ` if this precondition is not met .
Assertions can be disabled by defining ` NDEBUG ` at compile time .
2018-06-25 04:29:33 +08:00
See https : //en.cppreference.com/w/cpp/error/assert for more
2018-01-10 01:30:02 +08:00
information .
@ throw invalid_iterator .201 if iterators @ a first and @ a last are not
compatible ( i . e . , do not belong to the same JSON value ) . In this case ,
the range ` [ first , last ) ` is undefined .
@ throw invalid_iterator .204 if iterators @ a first and @ a last belong to a
primitive type ( number , boolean , or string ) , but @ a first does not point
to the first element any more . In this case , the range ` [ first , last ) ` is
undefined . See example code below .
@ throw invalid_iterator .206 if iterators @ a first and @ a last belong to a
null value . In this case , the range ` [ first , last ) ` is undefined .
@ complexity Linear in distance between @ a first and @ a last .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes to any JSON value .
@ liveexample { The example below shows several ways to create JSON values by
specifying a subrange with iterators . , basic_json__InputIt_InputIt }
@ since version 1.0 .0
*/
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 )
{
assert ( first . m_object ! = nullptr ) ;
assert ( last . m_object ! = nullptr ) ;
// make sure iterator fits the current value
if ( JSON_UNLIKELY ( first . m_object ! = last . m_object ) )
{
JSON_THROW ( invalid_iterator : : create ( 201 , " iterators are not compatible " ) ) ;
}
// copy type from first iterator
m_type = first . m_object - > m_type ;
// check if iterator range is complete for primitive values
switch ( m_type )
{
case value_t : : boolean :
case value_t : : number_float :
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : string :
{
if ( JSON_UNLIKELY ( not first . m_it . primitive_iterator . is_begin ( )
or not last . m_it . primitive_iterator . is_end ( ) ) )
{
JSON_THROW ( invalid_iterator : : create ( 204 , " iterators out of range " ) ) ;
}
break ;
}
default :
break ;
}
switch ( m_type )
{
case value_t : : number_integer :
{
m_value . number_integer = first . m_object - > m_value . number_integer ;
break ;
}
case value_t : : number_unsigned :
{
m_value . number_unsigned = first . m_object - > m_value . number_unsigned ;
break ;
}
case value_t : : number_float :
{
m_value . number_float = first . m_object - > m_value . number_float ;
break ;
}
case value_t : : boolean :
{
m_value . boolean = first . m_object - > m_value . boolean ;
break ;
}
case value_t : : string :
{
m_value = * first . m_object - > m_value . string ;
break ;
}
case value_t : : object :
{
m_value . object = create < object_t > ( first . m_it . object_iterator ,
last . m_it . object_iterator ) ;
break ;
}
case value_t : : array :
{
m_value . array = create < array_t > ( first . m_it . array_iterator ,
last . m_it . array_iterator ) ;
break ;
}
default :
JSON_THROW ( invalid_iterator : : create ( 206 , " cannot construct with iterators from " +
std : : string ( first . m_object - > type_name ( ) ) ) ) ;
}
assert_invariant ( ) ;
}
///////////////////////////////////////
// other constructors and destructor //
///////////////////////////////////////
/// @private
basic_json ( const detail : : json_ref < basic_json > & ref )
: basic_json ( ref . moved_or_copied ( ) )
{ }
/*!
@ brief copy constructor
Creates a copy of a given JSON value .
@ param [ in ] other the JSON value to copy
@ post ` * this = = other `
@ complexity Linear in the size of @ a other .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes to any JSON value .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is linear .
- As postcondition , it holds : ` other = = basic_json ( other ) ` .
@ liveexample { The following code shows an example for the copy
constructor . , basic_json__basic_json }
@ since version 1.0 .0
*/
basic_json ( const basic_json & other )
: m_type ( other . m_type )
{
// check of passed value is valid
other . assert_invariant ( ) ;
switch ( m_type )
{
case value_t : : object :
{
m_value = * other . m_value . object ;
break ;
}
case value_t : : array :
{
m_value = * other . m_value . array ;
break ;
}
case value_t : : string :
{
m_value = * other . m_value . string ;
break ;
}
case value_t : : boolean :
{
m_value = other . m_value . boolean ;
break ;
}
case value_t : : number_integer :
{
m_value = other . m_value . number_integer ;
break ;
}
case value_t : : number_unsigned :
{
m_value = other . m_value . number_unsigned ;
break ;
}
case value_t : : number_float :
{
m_value = other . m_value . number_float ;
break ;
}
default :
break ;
}
assert_invariant ( ) ;
}
/*!
@ brief move constructor
Move constructor . Constructs a JSON value with the contents of the given
value @ a other using move semantics . It " steals " the resources from @ a
other and leaves it as JSON null value .
@ param [ in , out ] other value to move to this object
@ post ` * this ` has the same value as @ a other before the call .
@ post @ a other is a JSON null value .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this constructor never throws
exceptions .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ MoveConstructible ] ( https : //en.cppreference.com/w/cpp/named_req/MoveConstructible)
2018-01-10 01:30:02 +08:00
requirements .
@ liveexample { The code below shows the move constructor explicitly called
via std : : move . , basic_json__moveconstructor }
@ since version 1.0 .0
*/
basic_json ( basic_json & & other ) noexcept
: m_type ( std : : move ( other . m_type ) ) ,
m_value ( std : : move ( other . m_value ) )
{
// check that passed value is valid
other . assert_invariant ( ) ;
// invalidate payload
other . m_type = value_t : : null ;
other . m_value = { } ;
assert_invariant ( ) ;
}
/*!
@ brief copy assignment
Copy assignment operator . Copies a JSON value via the " copy and swap "
strategy : It is expressed in terms of the copy constructor , destructor ,
and the ` swap ( ) ` member function .
@ param [ in ] other value to copy from
@ complexity Linear .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is linear .
@ liveexample { The code below shows and example for the copy assignment . It
creates a copy of value ` a ` which is then swapped with ` b ` . Finally \ , the
copy of ` a ` ( which is the null value after the swap ) is
destroyed . , basic_json__copyassignment }
@ since version 1.0 .0
*/
2018-10-08 00:39:18 +08:00
basic_json & operator = ( basic_json other ) noexcept (
2018-01-10 01:30:02 +08:00
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
)
{
// check that passed value is valid
other . assert_invariant ( ) ;
using std : : swap ;
swap ( m_type , other . m_type ) ;
swap ( m_value , other . m_value ) ;
assert_invariant ( ) ;
return * this ;
}
/*!
@ brief destructor
Destroys the JSON value and frees all allocated memory .
@ complexity Linear .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is linear .
- All stored elements are destroyed and all memory is freed .
@ since version 1.0 .0
*/
2018-01-17 03:41:04 +08:00
~ basic_json ( ) noexcept
2018-01-10 01:30:02 +08:00
{
assert_invariant ( ) ;
m_value . destroy ( m_type ) ;
}
/// @}
public :
///////////////////////
// object inspection //
///////////////////////
/// @name object inspection
/// Functions to inspect the type of a JSON value.
/// @{
/*!
@ brief serialization
Serialization function for JSON values . The function tries to mimic
Python ' s ` json . dumps ( ) ` function , and currently supports its @ a indent
and @ a ensure_ascii parameters .
@ param [ in ] indent If indent is nonnegative , then array elements and object
members will be pretty - printed with that indent level . An indent level of
` 0 ` will only insert newlines . ` - 1 ` ( the default ) selects the most compact
representation .
@ param [ in ] indent_char The character to use for indentation if @ a indent is
greater than ` 0 ` . The default is ` ` ( space ) .
@ param [ in ] ensure_ascii If @ a ensure_ascii is true , all non - ASCII characters
in the output are escaped with ` \ uXXXX ` sequences , and the result consists
of ASCII characters only .
2018-10-21 17:49:37 +08:00
@ param [ in ] error_handler how to react on decoding errors ; there are three
possible values : ` strict ` ( throws and exception in case a decoding error
occurs ; default ) , ` replace ` ( replace invalid UTF - 8 sequences with U + FFFD ) ,
and ` ignore ` ( ignore invalid UTF - 8 sequences during serialization ) .
2018-01-10 01:30:02 +08:00
@ return string containing the serialization of the JSON value
@ throw type_error .316 if a string stored inside the JSON value is not
UTF - 8 encoded
@ complexity Linear .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes in the JSON value .
@ liveexample { The following example shows the effect of different @ a indent \ ,
@ a indent_char \ , and @ a ensure_ascii parameters to the result of the
serialization . , dump }
@ see https : //docs.python.org/2/library/json.html#json.dump
@ since version 1.0 .0 ; indentation character @ a indent_char , option
2018-10-21 17:49:37 +08:00
@ a ensure_ascii and exceptions added in version 3.0 .0 ; error
handlers added in version 3.4 .0 .
2018-01-10 01:30:02 +08:00
*/
2018-10-21 17:49:37 +08:00
string_t dump ( const int indent = - 1 ,
const char indent_char = ' ' ,
const bool ensure_ascii = false ,
const error_handler_t error_handler = error_handler_t : : strict ) const
2018-01-10 01:30:02 +08:00
{
string_t result ;
2018-10-21 17:49:37 +08:00
serializer s ( detail : : output_adapter < char , string_t > ( result ) , indent_char , error_handler ) ;
2018-01-10 01:30:02 +08:00
if ( indent > = 0 )
{
s . dump ( * this , true , ensure_ascii , static_cast < unsigned int > ( indent ) ) ;
}
else
{
s . dump ( * this , false , ensure_ascii , 0 ) ;
}
return result ;
}
/*!
@ brief return the type of the JSON value ( explicit )
Return the type of the JSON value as a value from the @ ref value_t
enumeration .
@ return the type of the JSON value
Value type | return value
- - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - -
null | value_t : : null
boolean | value_t : : boolean
string | value_t : : string
number ( integer ) | value_t : : number_integer
number ( unsigned integer ) | value_t : : number_unsigned
number ( floating - point ) | value_t : : number_float
object | value_t : : object
array | value_t : : array
discarded | value_t : : discarded
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` type ( ) ` for all JSON
types . , type }
@ sa @ ref operator value_t ( ) - - return the type of the JSON value ( implicit )
@ sa @ ref type_name ( ) - - return the type as string
@ since version 1.0 .0
*/
constexpr value_t type ( ) const noexcept
{
return m_type ;
}
/*!
@ brief return whether type is primitive
This function returns true if and only if the JSON type is primitive
( string , number , boolean , or null ) .
@ return ` true ` if type is primitive ( string , number , boolean , or null ) ,
` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_primitive ( ) ` for all JSON
types . , is_primitive }
@ sa @ ref is_structured ( ) - - returns whether JSON value is structured
@ sa @ ref is_null ( ) - - returns whether JSON value is ` null `
@ sa @ ref is_string ( ) - - returns whether JSON value is a string
@ sa @ ref is_boolean ( ) - - returns whether JSON value is a boolean
@ sa @ ref is_number ( ) - - returns whether JSON value is a number
@ since version 1.0 .0
*/
constexpr bool is_primitive ( ) const noexcept
{
return is_null ( ) or is_string ( ) or is_boolean ( ) or is_number ( ) ;
}
/*!
@ brief return whether type is structured
This function returns true if and only if the JSON type is structured
( array or object ) .
@ return ` true ` if type is structured ( array or object ) , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_structured ( ) ` for all JSON
types . , is_structured }
@ sa @ ref is_primitive ( ) - - returns whether value is primitive
@ sa @ ref is_array ( ) - - returns whether value is an array
@ sa @ ref is_object ( ) - - returns whether value is an object
@ since version 1.0 .0
*/
constexpr bool is_structured ( ) const noexcept
{
return is_array ( ) or is_object ( ) ;
}
/*!
@ brief return whether value is null
This function returns true if and only if the JSON value is null .
@ return ` true ` if type is null , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_null ( ) ` for all JSON
types . , is_null }
@ since version 1.0 .0
*/
constexpr bool is_null ( ) const noexcept
{
return ( m_type = = value_t : : null ) ;
}
/*!
@ brief return whether value is a boolean
This function returns true if and only if the JSON value is a boolean .
@ return ` true ` if type is boolean , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_boolean ( ) ` for all JSON
types . , is_boolean }
@ since version 1.0 .0
*/
constexpr bool is_boolean ( ) const noexcept
{
return ( m_type = = value_t : : boolean ) ;
}
/*!
@ brief return whether value is a number
This function returns true if and only if the JSON value is a number . This
includes both integer ( signed and unsigned ) and floating - point values .
@ return ` true ` if type is number ( regardless whether integer , unsigned
integer or floating - type ) , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_number ( ) ` for all JSON
types . , is_number }
@ sa @ ref is_number_integer ( ) - - check if value is an integer or unsigned
integer number
@ sa @ ref is_number_unsigned ( ) - - check if value is an unsigned integer
number
@ sa @ ref is_number_float ( ) - - check if value is a floating - point number
@ since version 1.0 .0
*/
constexpr bool is_number ( ) const noexcept
{
return is_number_integer ( ) or is_number_float ( ) ;
}
/*!
@ brief return whether value is an integer number
This function returns true if and only if the JSON value is a signed or
unsigned integer number . This excludes floating - point values .
@ return ` true ` if type is an integer or unsigned integer number , ` false `
otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_number_integer ( ) ` for all
JSON types . , is_number_integer }
@ sa @ ref is_number ( ) - - check if value is a number
@ sa @ ref is_number_unsigned ( ) - - check if value is an unsigned integer
number
@ sa @ ref is_number_float ( ) - - check if value is a floating - point number
@ since version 1.0 .0
*/
constexpr bool is_number_integer ( ) const noexcept
{
return ( m_type = = value_t : : number_integer or m_type = = value_t : : number_unsigned ) ;
}
/*!
@ brief return whether value is an unsigned integer number
This function returns true if and only if the JSON value is an unsigned
integer number . This excludes floating - point and signed integer values .
@ return ` true ` if type is an unsigned integer number , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_number_unsigned ( ) ` for all
JSON types . , is_number_unsigned }
@ sa @ ref is_number ( ) - - check if value is a number
@ sa @ ref is_number_integer ( ) - - check if value is an integer or unsigned
integer number
@ sa @ ref is_number_float ( ) - - check if value is a floating - point number
@ since version 2.0 .0
*/
constexpr bool is_number_unsigned ( ) const noexcept
{
return ( m_type = = value_t : : number_unsigned ) ;
}
/*!
@ brief return whether value is a floating - point number
This function returns true if and only if the JSON value is a
floating - point number . This excludes signed and unsigned integer values .
@ return ` true ` if type is a floating - point number , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_number_float ( ) ` for all
JSON types . , is_number_float }
@ sa @ ref is_number ( ) - - check if value is number
@ sa @ ref is_number_integer ( ) - - check if value is an integer number
@ sa @ ref is_number_unsigned ( ) - - check if value is an unsigned integer
number
@ since version 1.0 .0
*/
constexpr bool is_number_float ( ) const noexcept
{
return ( m_type = = value_t : : number_float ) ;
}
/*!
@ brief return whether value is an object
This function returns true if and only if the JSON value is an object .
@ return ` true ` if type is object , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_object ( ) ` for all JSON
types . , is_object }
@ since version 1.0 .0
*/
constexpr bool is_object ( ) const noexcept
{
return ( m_type = = value_t : : object ) ;
}
/*!
@ brief return whether value is an array
This function returns true if and only if the JSON value is an array .
@ return ` true ` if type is array , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_array ( ) ` for all JSON
types . , is_array }
@ since version 1.0 .0
*/
constexpr bool is_array ( ) const noexcept
{
return ( m_type = = value_t : : array ) ;
}
/*!
@ brief return whether value is a string
This function returns true if and only if the JSON value is a string .
@ return ` true ` if type is string , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_string ( ) ` for all JSON
types . , is_string }
@ since version 1.0 .0
*/
constexpr bool is_string ( ) const noexcept
{
return ( m_type = = value_t : : string ) ;
}
/*!
@ brief return whether value is discarded
This function returns true if and only if the JSON value was discarded
during parsing with a callback function ( see @ ref parser_callback_t ) .
@ note This function will always be ` false ` for JSON values after parsing .
That is , discarded values can only occur during parsing , but will be
removed when inside a structured value or replaced by null in other cases .
@ return ` true ` if type is discarded , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_discarded ( ) ` for all JSON
types . , is_discarded }
@ since version 1.0 .0
*/
constexpr bool is_discarded ( ) const noexcept
{
return ( m_type = = value_t : : discarded ) ;
}
/*!
@ brief return the type of the JSON value ( implicit )
Implicitly return the type of the JSON value as a value from the @ ref
value_t enumeration .
@ return the type of the JSON value
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies the @ ref value_t operator for
all JSON types . , operator__value_t }
@ sa @ ref type ( ) - - return the type of the JSON value ( explicit )
@ sa @ ref type_name ( ) - - return the type as string
@ since version 1.0 .0
*/
constexpr operator value_t ( ) const noexcept
{
return m_type ;
}
/// @}
private :
//////////////////
// value access //
//////////////////
/// get a boolean (explicit)
boolean_t get_impl ( boolean_t * /*unused*/ ) const
{
if ( JSON_LIKELY ( is_boolean ( ) ) )
{
return m_value . boolean ;
}
JSON_THROW ( type_error : : create ( 302 , " type must be boolean, but is " + std : : string ( type_name ( ) ) ) ) ;
}
/// get a pointer to the value (object)
object_t * get_impl_ptr ( object_t * /*unused*/ ) noexcept
{
return is_object ( ) ? m_value . object : nullptr ;
}
/// get a pointer to the value (object)
constexpr const object_t * get_impl_ptr ( const object_t * /*unused*/ ) const noexcept
{
return is_object ( ) ? m_value . object : nullptr ;
}
/// get a pointer to the value (array)
array_t * get_impl_ptr ( array_t * /*unused*/ ) noexcept
{
return is_array ( ) ? m_value . array : nullptr ;
}
/// get a pointer to the value (array)
constexpr const array_t * get_impl_ptr ( const array_t * /*unused*/ ) const noexcept
{
return is_array ( ) ? m_value . array : nullptr ;
}
/// get a pointer to the value (string)
string_t * get_impl_ptr ( string_t * /*unused*/ ) noexcept
{
return is_string ( ) ? m_value . string : nullptr ;
}
/// get a pointer to the value (string)
constexpr const string_t * get_impl_ptr ( const string_t * /*unused*/ ) const noexcept
{
return is_string ( ) ? m_value . string : nullptr ;
}
/// get a pointer to the value (boolean)
boolean_t * get_impl_ptr ( boolean_t * /*unused*/ ) noexcept
{
return is_boolean ( ) ? & m_value . boolean : nullptr ;
}
/// get a pointer to the value (boolean)
constexpr const boolean_t * get_impl_ptr ( const boolean_t * /*unused*/ ) const noexcept
{
return is_boolean ( ) ? & m_value . boolean : nullptr ;
}
/// get a pointer to the value (integer number)
number_integer_t * get_impl_ptr ( number_integer_t * /*unused*/ ) noexcept
{
return is_number_integer ( ) ? & m_value . number_integer : nullptr ;
}
/// get a pointer to the value (integer number)
constexpr const number_integer_t * get_impl_ptr ( const number_integer_t * /*unused*/ ) const noexcept
{
return is_number_integer ( ) ? & m_value . number_integer : nullptr ;
}
/// get a pointer to the value (unsigned number)
number_unsigned_t * get_impl_ptr ( number_unsigned_t * /*unused*/ ) noexcept
{
return is_number_unsigned ( ) ? & m_value . number_unsigned : nullptr ;
}
/// get a pointer to the value (unsigned number)
constexpr const number_unsigned_t * get_impl_ptr ( const number_unsigned_t * /*unused*/ ) const noexcept
{
return is_number_unsigned ( ) ? & m_value . number_unsigned : nullptr ;
}
/// get a pointer to the value (floating-point number)
number_float_t * get_impl_ptr ( number_float_t * /*unused*/ ) noexcept
{
return is_number_float ( ) ? & m_value . number_float : nullptr ;
}
/// get a pointer to the value (floating-point number)
constexpr const number_float_t * get_impl_ptr ( const number_float_t * /*unused*/ ) const noexcept
{
return is_number_float ( ) ? & m_value . number_float : nullptr ;
}
/*!
@ brief helper function to implement get_ref ( )
This function helps to implement get_ref ( ) without code duplication for
const and non - const overloads
@ tparam ThisType will be deduced as ` basic_json ` or ` const basic_json `
@ throw type_error .303 if ReferenceType does not match underlying value
type of the current JSON
*/
template < typename ReferenceType , typename ThisType >
static ReferenceType get_ref_impl ( ThisType & obj )
{
// delegate the call to get_ptr<>()
auto ptr = obj . template get_ptr < typename std : : add_pointer < ReferenceType > : : type > ( ) ;
if ( JSON_LIKELY ( ptr ! = nullptr ) )
{
return * ptr ;
}
JSON_THROW ( type_error : : create ( 303 , " incompatible ReferenceType for get_ref, actual type is " + std : : string ( obj . type_name ( ) ) ) ) ;
}
public :
/// @name value access
/// Direct access to the stored value of a JSON value.
/// @{
/*!
@ brief get special - case overload
This overloads avoids a lot of template boilerplate , it can be seen as the
identity method
@ tparam BasicJsonType = = @ ref basic_json
@ return a copy of * this
@ complexity Constant .
@ since version 2.1 .0
*/
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
{
return * this ;
}
2018-02-27 19:11:04 +08:00
/*!
@ brief get special - case overload
2018-03-07 03:13:31 +08:00
This overloads converts the current @ ref basic_json in a different
@ ref basic_json type
2018-02-27 19:11:04 +08:00
@ tparam BasicJsonType = = @ ref basic_json
@ return a copy of * this , converted into @ tparam BasicJsonType
@ complexity Depending on the implementation of the called ` from_json ( ) `
method .
2018-08-18 18:00:14 +08:00
@ since version 3.2 .0
2018-02-27 19:11:04 +08:00
*/
template < typename BasicJsonType , detail : : enable_if_t <
not std : : is_same < BasicJsonType , basic_json > : : value and
2018-03-07 03:13:31 +08:00
detail : : is_basic_json < BasicJsonType > : : value , int > = 0 >
2018-02-27 19:11:04 +08:00
BasicJsonType get ( ) const
{
return * this ;
}
2018-01-10 01:30:02 +08:00
/*!
@ brief get a value ( explicit )
Explicit type conversion between the JSON value and a compatible value
2018-06-25 04:30:37 +08:00
which is [ CopyConstructible ] ( https : //en.cppreference.com/w/cpp/named_req/CopyConstructible)
and [ DefaultConstructible ] ( https : //en.cppreference.com/w/cpp/named_req/DefaultConstructible).
2018-01-10 01:30:02 +08:00
The value is converted by calling the @ ref json_serializer < ValueType >
` from_json ( ) ` method .
The function is equivalent to executing
@ code { . cpp }
ValueType ret ;
JSONSerializer < ValueType > : : from_json ( * this , ret ) ;
return ret ;
@ endcode
This overloads is chosen if :
- @ a ValueType is not @ ref basic_json ,
- @ ref json_serializer < ValueType > has a ` from_json ( ) ` method of the form
` void from_json ( const basic_json & , ValueType & ) ` , and
- @ ref json_serializer < ValueType > does not have a ` from_json ( ) ` method of
the form ` ValueType from_json ( const basic_json & ) `
@ tparam ValueTypeCV the provided value type
@ tparam ValueType the returned value type
@ return copy of the JSON value , converted to @ a ValueType
@ throw what @ ref json_serializer < ValueType > ` from_json ( ) ` method throws
@ liveexample { The example below shows several conversions from JSON values
to other types . There a few things to note : ( 1 ) Floating - point numbers can
be converted to integers \ , ( 2 ) A JSON array can be converted to a standard
` std : : vector < short > ` \ , ( 3 ) A JSON object can be converted to C + +
associative containers such as ` std : : unordered_map < std : : string \ ,
json > ` . , get__ValueType_const }
@ since version 2.1 .0
*/
template < typename ValueTypeCV , typename ValueType = detail : : uncvref_t < ValueTypeCV > ,
detail : : enable_if_t <
2018-02-27 19:11:04 +08:00
not detail : : is_basic_json < ValueType > : : value and
2018-01-10 01:30:02 +08:00
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 & > ( ) ) ) )
{
// we cannot static_assert on ValueTypeCV being non-const, because
// there is support for get<const basic_json_t>(), which is why we
// still need the uncvref
static_assert ( not std : : is_reference < ValueTypeCV > : : value ,
" get() cannot be used with reference types, you might want to use get_ref() " ) ;
static_assert ( std : : is_default_constructible < ValueType > : : value ,
" types must be DefaultConstructible when used with get() " ) ;
ValueType ret ;
JSONSerializer < ValueType > : : from_json ( * this , ret ) ;
return ret ;
}
/*!
@ brief get a value ( explicit ) ; special case
Explicit type conversion between the JSON value and a compatible value
2018-06-25 04:30:37 +08:00
which is * * not * * [ CopyConstructible ] ( https : //en.cppreference.com/w/cpp/named_req/CopyConstructible)
and * * not * * [ DefaultConstructible ] ( https : //en.cppreference.com/w/cpp/named_req/DefaultConstructible).
2018-01-10 01:30:02 +08:00
The value is converted by calling the @ ref json_serializer < ValueType >
` from_json ( ) ` method .
The function is equivalent to executing
@ code { . cpp }
return JSONSerializer < ValueTypeCV > : : from_json ( * this ) ;
@ endcode
This overloads is chosen if :
- @ a ValueType is not @ ref basic_json and
- @ ref json_serializer < ValueType > has a ` from_json ( ) ` method of the form
` ValueType from_json ( const basic_json & ) `
@ note If @ ref json_serializer < ValueType > has both overloads of
` from_json ( ) ` , this one is chosen .
@ tparam ValueTypeCV the provided value type
@ tparam ValueType the returned value type
@ return copy of the JSON value , converted to @ a ValueType
@ throw what @ ref json_serializer < ValueType > ` from_json ( ) ` method throws
@ since version 2.1 .0
*/
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 & > ( ) ) ) )
{
static_assert ( not std : : is_reference < ValueTypeCV > : : value ,
" get() cannot be used with reference types, you might want to use get_ref() " ) ;
return JSONSerializer < ValueTypeCV > : : from_json ( * this ) ;
}
2018-09-10 18:56:24 +08:00
/*!
@ brief get a value ( explicit )
Explicit type conversion between the JSON value and a compatible value .
The value is filled into the input parameter by calling the @ ref json_serializer < ValueType >
` from_json ( ) ` method .
The function is equivalent to executing
@ code { . cpp }
ValueType v ;
JSONSerializer < ValueType > : : from_json ( * this , v ) ;
@ endcode
This overloads is chosen if :
- @ a ValueType is not @ ref basic_json ,
- @ ref json_serializer < ValueType > has a ` from_json ( ) ` method of the form
` void from_json ( const basic_json & , ValueType & ) ` , and
@ tparam ValueType the input parameter type .
@ return the input parameter , allowing chaining calls .
@ throw what @ ref json_serializer < ValueType > ` from_json ( ) ` method throws
@ liveexample { The example below shows several conversions from JSON values
to other types . There a few things to note : ( 1 ) Floating - point numbers can
be converted to integers \ , ( 2 ) A JSON array can be converted to a standard
` std : : vector < short > ` \ , ( 3 ) A JSON object can be converted to C + +
associative containers such as ` std : : unordered_map < std : : string \ ,
json > ` . , get_to }
@ since version 3.3 .0
*/
template < typename ValueType ,
detail : : enable_if_t <
not detail : : is_basic_json < ValueType > : : value and
detail : : has_from_json < basic_json_t , ValueType > : : value ,
int > = 0 >
ValueType & get_to ( ValueType & v ) const noexcept ( noexcept (
JSONSerializer < ValueType > : : from_json ( std : : declval < const basic_json_t & > ( ) , v ) ) )
{
JSONSerializer < ValueType > : : from_json ( * this , v ) ;
return v ;
}
2018-01-10 01:30:02 +08:00
/*!
2018-09-12 23:01:27 +08:00
@ brief get a pointer value ( implicit )
2018-01-10 01:30:02 +08:00
2018-09-12 23:01:27 +08:00
Implicit pointer access to the internally stored JSON value . No copies are
2018-01-10 01:30:02 +08:00
made .
2018-09-12 23:01:27 +08:00
@ warning Writing data to the pointee of the result yields an undefined
state .
2018-01-10 01:30:02 +08:00
@ tparam PointerType pointer type ; must be a pointer to @ ref array_t , @ ref
object_t , @ ref string_t , @ ref boolean_t , @ ref number_integer_t ,
2018-09-12 23:01:27 +08:00
@ ref number_unsigned_t , or @ ref number_float_t . Enforced by a static
assertion .
2018-01-10 01:30:02 +08:00
@ return pointer to the internally stored JSON value if the requested
pointer type @ a PointerType fits to the JSON value ; ` nullptr ` otherwise
@ complexity Constant .
@ liveexample { The example below shows how pointers to internal values of a
JSON value can be requested . Note that no type conversions are made and a
` nullptr ` is returned if the value and the requested pointer type does not
2018-09-12 23:01:27 +08:00
match . , get_ptr }
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
template < typename PointerType , typename std : : enable_if <
std : : is_pointer < PointerType > : : value , int > : : type = 0 >
2018-09-12 23:01:27 +08:00
auto get_ptr ( ) noexcept - > decltype ( std : : declval < basic_json_t & > ( ) . get_impl_ptr ( std : : declval < PointerType > ( ) ) )
2018-01-10 01:30:02 +08:00
{
2018-09-12 23:01:27 +08:00
// delegate the call to get_impl_ptr<>()
return get_impl_ptr ( static_cast < PointerType > ( nullptr ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
2018-09-12 23:01:27 +08:00
@ brief get a pointer value ( implicit )
@ copydoc get_ptr ( )
2018-01-10 01:30:02 +08:00
*/
template < typename PointerType , typename std : : enable_if <
2018-09-12 23:01:27 +08:00
std : : is_pointer < PointerType > : : value and
std : : is_const < typename std : : remove_pointer < PointerType > : : type > : : value , int > : : type = 0 >
constexpr auto get_ptr ( ) const noexcept - > decltype ( std : : declval < const basic_json_t & > ( ) . get_impl_ptr ( std : : declval < PointerType > ( ) ) )
2018-01-10 01:30:02 +08:00
{
2018-09-12 23:01:27 +08:00
// delegate the call to get_impl_ptr<>() const
return get_impl_ptr ( static_cast < PointerType > ( nullptr ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
2018-09-12 23:01:27 +08:00
@ brief get a pointer value ( explicit )
2018-01-10 01:30:02 +08:00
2018-09-12 23:01:27 +08:00
Explicit pointer access to the internally stored JSON value . No copies are
2018-01-10 01:30:02 +08:00
made .
2018-09-12 23:01:27 +08:00
@ warning The pointer becomes invalid if the underlying JSON object
changes .
2018-01-10 01:30:02 +08:00
@ tparam PointerType pointer type ; must be a pointer to @ ref array_t , @ ref
object_t , @ ref string_t , @ ref boolean_t , @ ref number_integer_t ,
2018-09-12 23:01:27 +08:00
@ ref number_unsigned_t , or @ ref number_float_t .
2018-01-10 01:30:02 +08:00
@ return pointer to the internally stored JSON value if the requested
pointer type @ a PointerType fits to the JSON value ; ` nullptr ` otherwise
@ complexity Constant .
@ liveexample { The example below shows how pointers to internal values of a
JSON value can be requested . Note that no type conversions are made and a
` nullptr ` is returned if the value and the requested pointer type does not
2018-09-12 23:01:27 +08:00
match . , get__PointerType }
@ sa @ ref get_ptr ( ) for explicit pointer - member access
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
template < typename PointerType , typename std : : enable_if <
std : : is_pointer < PointerType > : : value , int > : : type = 0 >
2018-09-12 23:01:27 +08:00
auto get ( ) noexcept - > decltype ( std : : declval < basic_json_t & > ( ) . template get_ptr < PointerType > ( ) )
2018-01-10 01:30:02 +08:00
{
2018-09-12 23:01:27 +08:00
// delegate the call to get_ptr
return get_ptr < PointerType > ( ) ;
2018-01-10 01:30:02 +08:00
}
/*!
2018-09-12 23:01:27 +08:00
@ brief get a pointer value ( explicit )
@ copydoc get ( )
2018-01-10 01:30:02 +08:00
*/
template < typename PointerType , typename std : : enable_if <
2018-09-12 23:01:27 +08:00
std : : is_pointer < PointerType > : : value , int > : : type = 0 >
constexpr auto get ( ) const noexcept - > decltype ( std : : declval < const basic_json_t & > ( ) . template get_ptr < PointerType > ( ) )
2018-01-10 01:30:02 +08:00
{
2018-09-12 23:01:27 +08:00
// delegate the call to get_ptr
return get_ptr < PointerType > ( ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief get a reference value ( implicit )
Implicit reference access to the internally stored JSON value . No copies
are made .
@ warning Writing data to the referee of the result yields an undefined
state .
@ tparam ReferenceType reference type ; must be a reference to @ ref array_t ,
@ ref object_t , @ ref string_t , @ ref boolean_t , @ ref number_integer_t , or
@ ref number_float_t . Enforced by static assertion .
@ return reference to the internally stored JSON value if the requested
reference type @ a ReferenceType fits to the JSON value ; throws
type_error .303 otherwise
@ throw type_error .303 in case passed type @ a ReferenceType is incompatible
with the stored JSON value ; see example below
@ complexity Constant .
@ liveexample { The example shows several calls to ` get_ref ( ) ` . , get_ref }
@ since version 1.1 .0
*/
template < typename ReferenceType , typename std : : enable_if <
std : : is_reference < ReferenceType > : : value , int > : : type = 0 >
ReferenceType get_ref ( )
{
// delegate call to get_ref_impl
return get_ref_impl < ReferenceType > ( * this ) ;
}
/*!
@ brief get a reference value ( implicit )
@ copydoc get_ref ( )
*/
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
{
// delegate call to get_ref_impl
return get_ref_impl < ReferenceType > ( * this ) ;
}
/*!
@ brief get a value ( implicit )
Implicit type conversion between the JSON value and a compatible value .
The call is realized by calling @ ref get ( ) const .
@ tparam ValueType non - pointer type compatible to the JSON value , for
instance ` int ` for JSON integer numbers , ` bool ` for JSON booleans , or
` std : : vector ` types for JSON arrays . The character type of @ ref string_t
as well as an initializer list of this type is excluded to avoid
ambiguities as these types implicitly convert to ` std : : string ` .
@ return copy of the JSON value , converted to type @ a ValueType
@ throw type_error .302 in case passed type @ a ValueType is incompatible
to the JSON value type ( e . g . , the JSON value is of type boolean , but a
string is requested ) ; see example below
@ complexity Linear in the size of the JSON value .
@ liveexample { The example below shows several conversions from JSON values
to other types . There a few things to note : ( 1 ) Floating - point numbers can
be converted to integers \ , ( 2 ) A JSON array can be converted to a standard
` std : : vector < short > ` \ , ( 3 ) A JSON object can be converted to C + +
associative containers such as ` std : : unordered_map < std : : string \ ,
json > ` . , operator__ValueType }
@ since version 1.0 .0
*/
template < typename ValueType , typename std : : enable_if <
not std : : is_pointer < ValueType > : : value and
not std : : is_same < ValueType , detail : : json_ref < basic_json > > : : value and
2018-02-27 19:11:04 +08:00
not std : : is_same < ValueType , typename string_t : : value_type > : : value and
not detail : : is_basic_json < ValueType > : : value
2018-09-12 23:01:27 +08:00
2018-01-10 01:30:02 +08:00
# ifndef _MSC_VER // fix for issue #167 operator<< ambiguity under VS2015
and not std : : is_same < ValueType , std : : initializer_list < typename string_t : : value_type > > : : value
2018-08-15 04:13:56 +08:00
# if defined(JSON_HAS_CPP_17) && defined(_MSC_VER) and _MSC_VER <= 1914
2018-01-10 01:30:02 +08:00
and not std : : is_same < ValueType , typename std : : string_view > : : value
2018-06-02 02:22:57 +08:00
# endif
2018-01-10 01:30:02 +08:00
# endif
2018-09-12 23:01:27 +08:00
and detail : : is_detected < detail : : get_template_function , const basic_json_t & , ValueType > : : value
2018-01-10 01:30:02 +08:00
, int > : : type = 0 >
operator ValueType ( ) const
{
// delegate the call to get<>() const
return get < ValueType > ( ) ;
}
/// @}
////////////////////
// element access //
////////////////////
/// @name element access
/// Access to the JSON value.
/// @{
/*!
@ brief access specified array element with bounds checking
Returns a reference to the element at specified location @ a idx , with
bounds checking .
@ param [ in ] idx index of the element to access
@ return reference to the element at index @ a idx
@ throw type_error .304 if the JSON value is not an array ; in this case ,
calling ` at ` with an index makes no sense . See example below .
@ throw out_of_range .401 if the index @ a idx is out of range of the array ;
that is , ` idx > = size ( ) ` . See example below .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes in the JSON value .
@ complexity Constant .
@ since version 1.0 .0
@ liveexample { The example below shows how array elements can be read and
written using ` at ( ) ` . It also demonstrates the different exceptions that
can be thrown . , at__size_type }
*/
reference at ( size_type idx )
{
// at only works for arrays
if ( JSON_LIKELY ( is_array ( ) ) )
{
JSON_TRY
{
return m_value . array - > at ( idx ) ;
}
JSON_CATCH ( std : : out_of_range & )
{
// create better exception explanation
JSON_THROW ( out_of_range : : create ( 401 , " array index " + std : : to_string ( idx ) + " is out of range " ) ) ;
}
}
else
{
JSON_THROW ( type_error : : create ( 304 , " cannot use at() with " + std : : string ( type_name ( ) ) ) ) ;
}
}
/*!
@ brief access specified array element with bounds checking
Returns a const reference to the element at specified location @ a idx ,
with bounds checking .
@ param [ in ] idx index of the element to access
@ return const reference to the element at index @ a idx
@ throw type_error .304 if the JSON value is not an array ; in this case ,
calling ` at ` with an index makes no sense . See example below .
@ throw out_of_range .401 if the index @ a idx is out of range of the array ;
that is , ` idx > = size ( ) ` . See example below .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes in the JSON value .
@ complexity Constant .
@ since version 1.0 .0
@ liveexample { The example below shows how array elements can be read using
` at ( ) ` . It also demonstrates the different exceptions that can be thrown . ,
at__size_type_const }
*/
const_reference at ( size_type idx ) const
{
// at only works for arrays
if ( JSON_LIKELY ( is_array ( ) ) )
{
JSON_TRY
{
return m_value . array - > at ( idx ) ;
}
JSON_CATCH ( std : : out_of_range & )
{
// create better exception explanation
JSON_THROW ( out_of_range : : create ( 401 , " array index " + std : : to_string ( idx ) + " is out of range " ) ) ;
}
}
else
{
JSON_THROW ( type_error : : create ( 304 , " cannot use at() with " + std : : string ( type_name ( ) ) ) ) ;
}
}
/*!
@ brief access specified object element with bounds checking
Returns a reference to the element at with specified key @ a key , with
bounds checking .
@ param [ in ] key key of the element to access
@ return reference to the element at key @ a key
@ throw type_error .304 if the JSON value is not an object ; in this case ,
calling ` at ` with a key makes no sense . See example below .
@ throw out_of_range .403 if the key @ a key is is not stored in the object ;
that is , ` find ( key ) = = end ( ) ` . See example below .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes in the JSON value .
@ complexity Logarithmic in the size of the container .
@ sa @ ref operator [ ] ( const typename object_t : : key_type & ) for unchecked
access by reference
@ sa @ ref value ( ) for access by value with a default value
@ since version 1.0 .0
@ liveexample { The example below shows how object elements can be read and
written using ` at ( ) ` . It also demonstrates the different exceptions that
can be thrown . , at__object_t_key_type }
*/
reference at ( const typename object_t : : key_type & key )
{
// at only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
JSON_TRY
{
return m_value . object - > at ( key ) ;
}
JSON_CATCH ( std : : out_of_range & )
{
// create better exception explanation
JSON_THROW ( out_of_range : : create ( 403 , " key ' " + key + " ' not found " ) ) ;
}
}
else
{
JSON_THROW ( type_error : : create ( 304 , " cannot use at() with " + std : : string ( type_name ( ) ) ) ) ;
}
}
/*!
@ brief access specified object element with bounds checking
Returns a const reference to the element at with specified key @ a key ,
with bounds checking .
@ param [ in ] key key of the element to access
@ return const reference to the element at key @ a key
@ throw type_error .304 if the JSON value is not an object ; in this case ,
calling ` at ` with a key makes no sense . See example below .
@ throw out_of_range .403 if the key @ a key is is not stored in the object ;
that is , ` find ( key ) = = end ( ) ` . See example below .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes in the JSON value .
@ complexity Logarithmic in the size of the container .
@ sa @ ref operator [ ] ( const typename object_t : : key_type & ) for unchecked
access by reference
@ sa @ ref value ( ) for access by value with a default value
@ since version 1.0 .0
@ liveexample { The example below shows how object elements can be read using
` at ( ) ` . It also demonstrates the different exceptions that can be thrown . ,
at__object_t_key_type_const }
*/
const_reference at ( const typename object_t : : key_type & key ) const
{
// at only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
JSON_TRY
{
return m_value . object - > at ( key ) ;
}
JSON_CATCH ( std : : out_of_range & )
{
// create better exception explanation
JSON_THROW ( out_of_range : : create ( 403 , " key ' " + key + " ' not found " ) ) ;
}
}
else
{
JSON_THROW ( type_error : : create ( 304 , " cannot use at() with " + std : : string ( type_name ( ) ) ) ) ;
}
}
/*!
@ brief access specified array element
Returns a reference to the element at specified location @ a idx .
@ note If @ a idx is beyond the range of the array ( i . e . , ` idx > = size ( ) ` ) ,
then the array is silently filled up with ` null ` values to make ` idx ` a
valid reference to the last stored element .
@ param [ in ] idx index of the element to access
@ return reference to the element at index @ a idx
@ throw type_error .305 if the JSON value is not an array or null ; in that
cases , using the [ ] operator with an index makes no sense .
@ complexity Constant if @ a idx is in the range of the array . Otherwise
linear in ` idx - size ( ) ` .
@ liveexample { The example below shows how array elements can be read and
written using ` [ ] ` operator . Note the addition of ` null `
values . , operatorarray__size_type }
@ since version 1.0 .0
*/
reference operator [ ] ( size_type idx )
{
// implicitly convert null value to an empty array
if ( is_null ( ) )
{
m_type = value_t : : array ;
m_value . array = create < array_t > ( ) ;
assert_invariant ( ) ;
}
// operator[] only works for arrays
if ( JSON_LIKELY ( is_array ( ) ) )
{
// fill up array with null values if given idx is outside range
if ( idx > = m_value . array - > size ( ) )
{
m_value . array - > insert ( m_value . array - > end ( ) ,
idx - m_value . array - > size ( ) + 1 ,
basic_json ( ) ) ;
}
return m_value . array - > operator [ ] ( idx ) ;
}
2018-08-31 00:35:51 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a numeric argument with " + std : : string ( type_name ( ) ) ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief access specified array element
Returns a const reference to the element at specified location @ a idx .
@ param [ in ] idx index of the element to access
@ return const reference to the element at index @ a idx
@ throw type_error .305 if the JSON value is not an array ; in that case ,
using the [ ] operator with an index makes no sense .
@ complexity Constant .
@ liveexample { The example below shows how array elements can be read using
the ` [ ] ` operator . , operatorarray__size_type_const }
@ since version 1.0 .0
*/
const_reference operator [ ] ( size_type idx ) const
{
// const operator[] only works for arrays
if ( JSON_LIKELY ( is_array ( ) ) )
{
return m_value . array - > operator [ ] ( idx ) ;
}
2018-08-31 00:35:51 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a numeric argument with " + std : : string ( type_name ( ) ) ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief access specified object element
Returns a reference to the element at with specified key @ a key .
@ note If @ a key is not found in the object , then it is silently added to
the object and filled with a ` null ` value to make ` key ` a valid reference .
In case the value was ` null ` before , it is converted to an object .
@ param [ in ] key key of the element to access
@ return reference to the element at key @ a key
@ throw type_error .305 if the JSON value is not an object or null ; in that
cases , using the [ ] operator with a key makes no sense .
@ complexity Logarithmic in the size of the container .
@ liveexample { The example below shows how object elements can be read and
written using the ` [ ] ` operator . , operatorarray__key_type }
@ sa @ ref at ( const typename object_t : : key_type & ) for access by reference
with range checking
@ sa @ ref value ( ) for access by value with a default value
@ since version 1.0 .0
*/
reference operator [ ] ( const typename object_t : : key_type & key )
{
// implicitly convert null value to an empty object
if ( is_null ( ) )
{
m_type = value_t : : object ;
m_value . object = create < object_t > ( ) ;
assert_invariant ( ) ;
}
// operator[] only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
return m_value . object - > operator [ ] ( key ) ;
}
2018-09-18 03:36:38 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a string argument with " + std : : string ( type_name ( ) ) ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief read - only access specified object element
Returns a const reference to the element at with specified key @ a key . No
bounds checking is performed .
@ warning If the element with key @ a key does not exist , the behavior is
undefined .
@ param [ in ] key key of the element to access
@ return const reference to the element at key @ a key
@ pre The element with key @ a key must exist . * * This precondition is
enforced with an assertion . * *
@ throw type_error .305 if the JSON value is not an object ; in that case ,
using the [ ] operator with a key makes no sense .
@ complexity Logarithmic in the size of the container .
@ liveexample { The example below shows how object elements can be read using
the ` [ ] ` operator . , operatorarray__key_type_const }
@ sa @ ref at ( const typename object_t : : key_type & ) for access by reference
with range checking
@ sa @ ref value ( ) for access by value with a default value
@ since version 1.0 .0
*/
const_reference operator [ ] ( const typename object_t : : key_type & key ) const
{
// const operator[] only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
assert ( m_value . object - > find ( key ) ! = m_value . object - > end ( ) ) ;
return m_value . object - > find ( key ) - > second ;
}
2018-09-18 03:36:38 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a string argument with " + std : : string ( type_name ( ) ) ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief access specified object element
Returns a reference to the element at with specified key @ a key .
@ note If @ a key is not found in the object , then it is silently added to
the object and filled with a ` null ` value to make ` key ` a valid reference .
In case the value was ` null ` before , it is converted to an object .
@ param [ in ] key key of the element to access
@ return reference to the element at key @ a key
@ throw type_error .305 if the JSON value is not an object or null ; in that
cases , using the [ ] operator with a key makes no sense .
@ complexity Logarithmic in the size of the container .
@ liveexample { The example below shows how object elements can be read and
written using the ` [ ] ` operator . , operatorarray__key_type }
@ sa @ ref at ( const typename object_t : : key_type & ) for access by reference
with range checking
@ sa @ ref value ( ) for access by value with a default value
@ since version 1.1 .0
*/
template < typename T >
reference operator [ ] ( T * key )
{
// implicitly convert null to object
if ( is_null ( ) )
{
m_type = value_t : : object ;
m_value = value_t : : object ;
assert_invariant ( ) ;
}
// at only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
return m_value . object - > operator [ ] ( key ) ;
}
2018-09-18 03:36:38 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a string argument with " + std : : string ( type_name ( ) ) ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief read - only access specified object element
Returns a const reference to the element at with specified key @ a key . No
bounds checking is performed .
@ warning If the element with key @ a key does not exist , the behavior is
undefined .
@ param [ in ] key key of the element to access
@ return const reference to the element at key @ a key
@ pre The element with key @ a key must exist . * * This precondition is
enforced with an assertion . * *
@ throw type_error .305 if the JSON value is not an object ; in that case ,
using the [ ] operator with a key makes no sense .
@ complexity Logarithmic in the size of the container .
@ liveexample { The example below shows how object elements can be read using
the ` [ ] ` operator . , operatorarray__key_type_const }
@ sa @ ref at ( const typename object_t : : key_type & ) for access by reference
with range checking
@ sa @ ref value ( ) for access by value with a default value
@ since version 1.1 .0
*/
template < typename T >
const_reference operator [ ] ( T * key ) const
{
// at only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
assert ( m_value . object - > find ( key ) ! = m_value . object - > end ( ) ) ;
return m_value . object - > find ( key ) - > second ;
}
2018-09-18 03:36:38 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a string argument with " + std : : string ( type_name ( ) ) ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief access specified object element with default value
Returns either a copy of an object ' s element at the specified key @ a key
or a given default value if no element with key @ a key exists .
The function is basically equivalent to executing
@ code { . cpp }
try {
return at ( key ) ;
} catch ( out_of_range ) {
return default_value ;
}
@ endcode
@ note Unlike @ ref at ( const typename object_t : : key_type & ) , this function
does not throw if the given key @ a key was not found .
@ note Unlike @ ref operator [ ] ( const typename object_t : : key_type & key ) , this
function does not implicitly add an element to the position defined by @ a
key . This function is furthermore also applicable to const objects .
@ param [ in ] key key of the element to access
@ param [ in ] default_value the value to return if @ a key is not found
@ tparam ValueType type compatible to JSON values , for instance ` int ` for
JSON integer numbers , ` bool ` for JSON booleans , or ` std : : vector ` types for
JSON arrays . Note the type of the expected value at @ a key and the default
value @ a default_value must be compatible .
@ return copy of the element at key @ a key or @ a default_value if @ a key
is not found
@ throw type_error .306 if the JSON value is not an object ; in that case ,
using ` value ( ) ` with a key makes no sense .
@ complexity Logarithmic in the size of the container .
@ liveexample { The example below shows how object elements can be queried
with a default value . , basic_json__value }
@ sa @ ref at ( const typename object_t : : key_type & ) for access by reference
with range checking
@ sa @ ref operator [ ] ( const typename object_t : : key_type & ) for unchecked
access by reference
@ since version 1.0 .0
*/
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 , const ValueType & default_value ) const
{
// at only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
// if key is found, return value and given default value otherwise
const auto it = find ( key ) ;
if ( it ! = end ( ) )
{
return * it ;
}
return default_value ;
}
JSON_THROW ( type_error : : create ( 306 , " cannot use value() with " + std : : string ( type_name ( ) ) ) ) ;
}
/*!
@ brief overload for a default value of type const char *
2018-10-28 16:15:41 +08:00
@ copydoc basic_json : : value ( const typename object_t : : key_type & , const ValueType & ) const
2018-01-10 01:30:02 +08:00
*/
string_t value ( const typename object_t : : key_type & key , const char * default_value ) const
{
return value ( key , string_t ( default_value ) ) ;
}
/*!
@ brief access specified object element via JSON Pointer with default value
Returns either a copy of an object ' s element at the specified key @ a key
or a given default value if no element with key @ a key exists .
The function is basically equivalent to executing
@ code { . cpp }
try {
return at ( ptr ) ;
} catch ( out_of_range ) {
return default_value ;
}
@ endcode
@ note Unlike @ ref at ( const json_pointer & ) , this function does not throw
if the given key @ a key was not found .
@ param [ in ] ptr a JSON pointer to the element to access
@ param [ in ] default_value the value to return if @ a ptr found no value
@ tparam ValueType type compatible to JSON values , for instance ` int ` for
JSON integer numbers , ` bool ` for JSON booleans , or ` std : : vector ` types for
JSON arrays . Note the type of the expected value at @ a key and the default
value @ a default_value must be compatible .
@ return copy of the element at key @ a key or @ a default_value if @ a key
is not found
2018-04-17 18:08:44 +08:00
@ throw type_error .306 if the JSON value is not an object ; in that case ,
2018-01-10 01:30:02 +08:00
using ` value ( ) ` with a key makes no sense .
@ complexity Logarithmic in the size of the container .
@ liveexample { The example below shows how object elements can be queried
with a default value . , basic_json__value_ptr }
@ sa @ ref operator [ ] ( const json_pointer & ) for unchecked access by reference
@ since version 2.0 .2
*/
template < class ValueType , typename std : : enable_if <
std : : is_convertible < basic_json_t , ValueType > : : value , int > : : type = 0 >
ValueType value ( const json_pointer & ptr , const ValueType & default_value ) const
{
// at only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
// if pointer resolves a value, return it or use default value
JSON_TRY
{
return ptr . get_checked ( this ) ;
}
2018-07-19 14:43:41 +08:00
JSON_INTERNAL_CATCH ( out_of_range & )
2018-01-10 01:30:02 +08:00
{
return default_value ;
}
}
JSON_THROW ( type_error : : create ( 306 , " cannot use value() with " + std : : string ( type_name ( ) ) ) ) ;
}
/*!
@ brief overload for a default value of type const char *
@ copydoc basic_json : : value ( const json_pointer & , ValueType ) const
*/
string_t value ( const json_pointer & ptr , const char * default_value ) const
{
return value ( ptr , string_t ( default_value ) ) ;
}
/*!
@ brief access the first element
Returns a reference to the first element in the container . For a JSON
container ` c ` , the expression ` c . front ( ) ` is equivalent to ` * c . begin ( ) ` .
@ return In case of a structured type ( array or object ) , a reference to the
first element is returned . In case of number , string , or boolean values , a
reference to the value is returned .
@ complexity Constant .
@ pre The JSON value must not be ` null ` ( would throw ` std : : out_of_range ` )
or an empty array or object ( undefined behavior , * * guarded by
assertions * * ) .
@ post The JSON value remains unchanged .
@ throw invalid_iterator .214 when called on ` null ` value
@ liveexample { The following code shows an example for ` front ( ) ` . , front }
@ sa @ ref back ( ) - - access the last element
@ since version 1.0 .0
*/
reference front ( )
{
return * begin ( ) ;
}
/*!
@ copydoc basic_json : : front ( )
*/
const_reference front ( ) const
{
return * cbegin ( ) ;
}
/*!
@ brief access the last element
Returns a reference to the last element in the container . For a JSON
container ` c ` , the expression ` c . back ( ) ` is equivalent to
@ code { . cpp }
auto tmp = c . end ( ) ;
- - tmp ;
return * tmp ;
@ endcode
@ return In case of a structured type ( array or object ) , a reference to the
last element is returned . In case of number , string , or boolean values , a
reference to the value is returned .
@ complexity Constant .
@ pre The JSON value must not be ` null ` ( would throw ` std : : out_of_range ` )
or an empty array or object ( undefined behavior , * * guarded by
assertions * * ) .
@ post The JSON value remains unchanged .
@ throw invalid_iterator .214 when called on a ` null ` value . See example
below .
@ liveexample { The following code shows an example for ` back ( ) ` . , back }
@ sa @ ref front ( ) - - access the first element
@ since version 1.0 .0
*/
reference back ( )
{
auto tmp = end ( ) ;
- - tmp ;
return * tmp ;
}
/*!
@ copydoc basic_json : : back ( )
*/
const_reference back ( ) const
{
auto tmp = cend ( ) ;
- - tmp ;
return * tmp ;
}
/*!
@ brief remove element given an iterator
Removes the element specified by iterator @ a pos . The iterator @ a pos must
be valid and dereferenceable . Thus the ` end ( ) ` iterator ( which is valid ,
but is not dereferenceable ) cannot be used as a value for @ a pos .
If called on a primitive type other than ` null ` , the resulting JSON value
will be ` null ` .
@ param [ in ] pos iterator to the element to remove
@ return Iterator following the last removed element . If the iterator @ a
pos refers to the last element , the ` end ( ) ` iterator is returned .
@ tparam IteratorType an @ ref iterator or @ ref const_iterator
@ post Invalidates iterators and references at or after the point of the
erase , including the ` end ( ) ` iterator .
@ throw type_error .307 if called on a ` null ` value ; example : ` " cannot use
erase ( ) with null " `
@ throw invalid_iterator .202 if called on an iterator which does not belong
to the current JSON value ; example : ` " iterator does not fit current
value " `
@ throw invalid_iterator .205 if called on a primitive type with invalid
iterator ( i . e . , any iterator which is not ` begin ( ) ` ) ; example : ` " iterator
out of range " `
@ complexity The complexity depends on the type :
- objects : amortized constant
- arrays : linear in distance between @ a pos and the end of the container
- strings : linear in the length of the string
- other types : constant
@ liveexample { The example shows the result of ` erase ( ) ` for different JSON
types . , erase__IteratorType }
@ sa @ ref erase ( IteratorType , IteratorType ) - - removes the elements in
the given range
@ sa @ ref erase ( const typename object_t : : key_type & ) - - removes the element
from an object at the given key
@ sa @ ref erase ( const size_type ) - - removes the element from an array at
the given index
@ since version 1.0 .0
*/
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 )
{
// make sure iterator fits the current value
if ( JSON_UNLIKELY ( this ! = pos . m_object ) )
{
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " ) ) ;
}
IteratorType result = end ( ) ;
switch ( m_type )
{
case value_t : : boolean :
case value_t : : number_float :
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : string :
{
if ( JSON_UNLIKELY ( not pos . m_it . primitive_iterator . is_begin ( ) ) )
{
JSON_THROW ( invalid_iterator : : create ( 205 , " iterator out of range " ) ) ;
}
if ( is_string ( ) )
{
AllocatorType < string_t > alloc ;
std : : allocator_traits < decltype ( alloc ) > : : destroy ( alloc , m_value . string ) ;
std : : allocator_traits < decltype ( alloc ) > : : deallocate ( alloc , m_value . string , 1 ) ;
m_value . string = nullptr ;
}
m_type = value_t : : null ;
assert_invariant ( ) ;
break ;
}
case value_t : : object :
{
result . m_it . object_iterator = m_value . object - > erase ( pos . m_it . object_iterator ) ;
break ;
}
case value_t : : array :
{
result . m_it . array_iterator = m_value . array - > erase ( pos . m_it . array_iterator ) ;
break ;
}
default :
JSON_THROW ( type_error : : create ( 307 , " cannot use erase() with " + std : : string ( type_name ( ) ) ) ) ;
}
return result ;
}
/*!
@ brief remove elements given an iterator range
Removes the element specified by the range ` [ first ; last ) ` . The iterator
@ a first does not need to be dereferenceable if ` first = = last ` : erasing
an empty range is a no - op .
If called on a primitive type other than ` null ` , the resulting JSON value
will be ` null ` .
@ param [ in ] first iterator to the beginning of the range to remove
@ param [ in ] last iterator past the end of the range to remove
@ return Iterator following the last removed element . If the iterator @ a
second refers to the last element , the ` end ( ) ` iterator is returned .
@ tparam IteratorType an @ ref iterator or @ ref const_iterator
@ post Invalidates iterators and references at or after the point of the
erase , including the ` end ( ) ` iterator .
@ throw type_error .307 if called on a ` null ` value ; example : ` " cannot use
erase ( ) with null " `
@ throw invalid_iterator .203 if called on iterators which does not belong
to the current JSON value ; example : ` " iterators do not fit current value " `
@ throw invalid_iterator .204 if called on a primitive type with invalid
iterators ( i . e . , if ` first ! = begin ( ) ` and ` last ! = end ( ) ` ) ; example :
` " iterators out of range " `
@ complexity The complexity depends on the type :
- objects : ` log ( size ( ) ) + std : : distance ( first , last ) `
- arrays : linear in the distance between @ a first and @ a last , plus linear
in the distance between @ a last and end of the container
- strings : linear in the length of the string
- other types : constant
@ liveexample { The example shows the result of ` erase ( ) ` for different JSON
types . , erase__IteratorType_IteratorType }
@ sa @ ref erase ( IteratorType ) - - removes the element at a given position
@ sa @ ref erase ( const typename object_t : : key_type & ) - - removes the element
from an object at the given key
@ sa @ ref erase ( const size_type ) - - removes the element from an array at
the given index
@ since version 1.0 .0
*/
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 )
{
// make sure iterator fits the current value
if ( JSON_UNLIKELY ( this ! = first . m_object or this ! = last . m_object ) )
{
JSON_THROW ( invalid_iterator : : create ( 203 , " iterators do not fit current value " ) ) ;
}
IteratorType result = end ( ) ;
switch ( m_type )
{
case value_t : : boolean :
case value_t : : number_float :
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : string :
{
if ( JSON_LIKELY ( not first . m_it . primitive_iterator . is_begin ( )
or not last . m_it . primitive_iterator . is_end ( ) ) )
{
JSON_THROW ( invalid_iterator : : create ( 204 , " iterators out of range " ) ) ;
}
if ( is_string ( ) )
{
AllocatorType < string_t > alloc ;
std : : allocator_traits < decltype ( alloc ) > : : destroy ( alloc , m_value . string ) ;
std : : allocator_traits < decltype ( alloc ) > : : deallocate ( alloc , m_value . string , 1 ) ;
m_value . string = nullptr ;
}
m_type = value_t : : null ;
assert_invariant ( ) ;
break ;
}
case value_t : : object :
{
result . m_it . object_iterator = m_value . object - > erase ( first . m_it . object_iterator ,
last . m_it . object_iterator ) ;
break ;
}
case value_t : : array :
{
result . m_it . array_iterator = m_value . array - > erase ( first . m_it . array_iterator ,
last . m_it . array_iterator ) ;
break ;
}
default :
JSON_THROW ( type_error : : create ( 307 , " cannot use erase() with " + std : : string ( type_name ( ) ) ) ) ;
}
return result ;
}
/*!
@ brief remove element from a JSON object given a key
Removes elements from a JSON object with the key value @ a key .
@ param [ in ] key value of the elements to remove
@ return Number of elements removed . If @ a ObjectType is the default
` std : : map ` type , the return value will always be ` 0 ` ( @ a key was not
found ) or ` 1 ` ( @ a key was found ) .
@ post References and iterators to the erased elements are invalidated .
Other references and iterators are not affected .
@ throw type_error .307 when called on a type other than JSON object ;
example : ` " cannot use erase() with null " `
@ complexity ` log ( size ( ) ) + count ( key ) `
@ liveexample { The example shows the effect of ` erase ( ) ` . , erase__key_type }
@ sa @ ref erase ( IteratorType ) - - removes the element at a given position
@ sa @ ref erase ( IteratorType , IteratorType ) - - removes the elements in
the given range
@ sa @ ref erase ( const size_type ) - - removes the element from an array at
the given index
@ since version 1.0 .0
*/
size_type erase ( const typename object_t : : key_type & key )
{
// this erase only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
return m_value . object - > erase ( key ) ;
}
JSON_THROW ( type_error : : create ( 307 , " cannot use erase() with " + std : : string ( type_name ( ) ) ) ) ;
}
/*!
@ brief remove element from a JSON array given an index
Removes element from a JSON array at the index @ a idx .
@ param [ in ] idx index of the element to remove
@ throw type_error .307 when called on a type other than JSON object ;
example : ` " cannot use erase() with null " `
@ throw out_of_range .401 when ` idx > = size ( ) ` ; example : ` " array index 17
is out of range " `
@ complexity Linear in distance between @ a idx and the end of the container .
@ liveexample { The example shows the effect of ` erase ( ) ` . , erase__size_type }
@ sa @ ref erase ( IteratorType ) - - removes the element at a given position
@ sa @ ref erase ( IteratorType , IteratorType ) - - removes the elements in
the given range
@ sa @ ref erase ( const typename object_t : : key_type & ) - - removes the element
from an object at the given key
@ since version 1.0 .0
*/
void erase ( const size_type idx )
{
// this erase only works for arrays
if ( JSON_LIKELY ( is_array ( ) ) )
{
if ( JSON_UNLIKELY ( idx > = size ( ) ) )
{
JSON_THROW ( out_of_range : : create ( 401 , " array index " + std : : to_string ( idx ) + " is out of range " ) ) ;
}
m_value . array - > erase ( m_value . array - > begin ( ) + static_cast < difference_type > ( idx ) ) ;
}
else
{
JSON_THROW ( type_error : : create ( 307 , " cannot use erase() with " + std : : string ( type_name ( ) ) ) ) ;
}
}
/// @}
////////////
// lookup //
////////////
/// @name lookup
/// @{
/*!
@ brief find an element in a JSON object
Finds an element in a JSON object with key equivalent to @ a key . If the
element is not found or the JSON value is not an object , end ( ) is
returned .
@ note This method always returns @ ref end ( ) when executed on a JSON type
that is not an object .
@ param [ in ] key key value of the element to search for .
@ return Iterator to an element with key equivalent to @ a key . If no such
element is found or the JSON value is not an object , past - the - end ( see
@ ref end ( ) ) iterator is returned .
@ complexity Logarithmic in the size of the JSON object .
@ liveexample { The example shows how ` find ( ) ` is used . , find__key_type }
@ since version 1.0 .0
*/
template < typename KeyT >
iterator find ( KeyT & & key )
{
auto result = end ( ) ;
if ( is_object ( ) )
{
result . m_it . object_iterator = m_value . object - > find ( std : : forward < KeyT > ( key ) ) ;
}
return result ;
}
/*!
@ brief find an element in a JSON object
@ copydoc find ( KeyT & & )
*/
template < typename KeyT >
const_iterator find ( KeyT & & key ) const
{
auto result = cend ( ) ;
if ( is_object ( ) )
{
result . m_it . object_iterator = m_value . object - > find ( std : : forward < KeyT > ( key ) ) ;
}
return result ;
}
/*!
@ brief returns the number of occurrences of a key in a JSON object
Returns the number of elements with key @ a key . If ObjectType is the
default ` std : : map ` type , the return value will always be ` 0 ` ( @ a key was
not found ) or ` 1 ` ( @ a key was found ) .
@ note This method always returns ` 0 ` when executed on a JSON type that is
not an object .
@ param [ in ] key key value of the element to count
@ return Number of elements with key @ a key . If the JSON value is not an
object , the return value will be ` 0 ` .
@ complexity Logarithmic in the size of the JSON object .
@ liveexample { The example shows how ` count ( ) ` is used . , count }
@ since version 1.0 .0
*/
template < typename KeyT >
size_type count ( KeyT & & key ) const
{
// return 0 for all nonobject types
return is_object ( ) ? m_value . object - > count ( std : : forward < KeyT > ( key ) ) : 0 ;
}
/// @}
///////////////
// iterators //
///////////////
/// @name iterators
/// @{
/*!
@ brief returns an iterator to the first element
Returns an iterator to the first element .
@ image html range - begin - end . svg " Illustration from cppreference.com "
@ return iterator to the first element
@ complexity Constant .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
@ liveexample { The following code shows an example for ` begin ( ) ` . , begin }
@ sa @ ref cbegin ( ) - - returns a const iterator to the beginning
@ sa @ ref end ( ) - - returns an iterator to the end
@ sa @ ref cend ( ) - - returns a const iterator to the end
@ since version 1.0 .0
*/
iterator begin ( ) noexcept
{
iterator result ( this ) ;
result . set_begin ( ) ;
return result ;
}
/*!
@ copydoc basic_json : : cbegin ( )
*/
const_iterator begin ( ) const noexcept
{
return cbegin ( ) ;
}
/*!
@ brief returns a const iterator to the first element
Returns a const iterator to the first element .
@ image html range - begin - end . svg " Illustration from cppreference.com "
@ return const iterator to the first element
@ complexity Constant .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
- Has the semantics of ` const_cast < const basic_json & > ( * this ) . begin ( ) ` .
@ liveexample { The following code shows an example for ` cbegin ( ) ` . , cbegin }
@ sa @ ref begin ( ) - - returns an iterator to the beginning
@ sa @ ref end ( ) - - returns an iterator to the end
@ sa @ ref cend ( ) - - returns a const iterator to the end
@ since version 1.0 .0
*/
const_iterator cbegin ( ) const noexcept
{
const_iterator result ( this ) ;
result . set_begin ( ) ;
return result ;
}
/*!
@ brief returns an iterator to one past the last element
Returns an iterator to one past the last element .
@ image html range - begin - end . svg " Illustration from cppreference.com "
@ return iterator one past the last element
@ complexity Constant .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
@ liveexample { The following code shows an example for ` end ( ) ` . , end }
@ sa @ ref cend ( ) - - returns a const iterator to the end
@ sa @ ref begin ( ) - - returns an iterator to the beginning
@ sa @ ref cbegin ( ) - - returns a const iterator to the beginning
@ since version 1.0 .0
*/
iterator end ( ) noexcept
{
iterator result ( this ) ;
result . set_end ( ) ;
return result ;
}
/*!
@ copydoc basic_json : : cend ( )
*/
const_iterator end ( ) const noexcept
{
return cend ( ) ;
}
/*!
@ brief returns a const iterator to one past the last element
Returns a const iterator to one past the last element .
@ image html range - begin - end . svg " Illustration from cppreference.com "
@ return const iterator one past the last element
@ complexity Constant .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
- Has the semantics of ` const_cast < const basic_json & > ( * this ) . end ( ) ` .
@ liveexample { The following code shows an example for ` cend ( ) ` . , cend }
@ sa @ ref end ( ) - - returns an iterator to the end
@ sa @ ref begin ( ) - - returns an iterator to the beginning
@ sa @ ref cbegin ( ) - - returns a const iterator to the beginning
@ since version 1.0 .0
*/
const_iterator cend ( ) const noexcept
{
const_iterator result ( this ) ;
result . set_end ( ) ;
return result ;
}
/*!
@ brief returns an iterator to the reverse - beginning
Returns an iterator to the reverse - beginning ; that is , the last element .
@ image html range - rbegin - rend . svg " Illustration from cppreference.com "
@ complexity Constant .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ ReversibleContainer ] ( https : //en.cppreference.com/w/cpp/named_req/ReversibleContainer)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
- Has the semantics of ` reverse_iterator ( end ( ) ) ` .
@ liveexample { The following code shows an example for ` rbegin ( ) ` . , rbegin }
@ sa @ ref crbegin ( ) - - returns a const reverse iterator to the beginning
@ sa @ ref rend ( ) - - returns a reverse iterator to the end
@ sa @ ref crend ( ) - - returns a const reverse iterator to the end
@ since version 1.0 .0
*/
reverse_iterator rbegin ( ) noexcept
{
return reverse_iterator ( end ( ) ) ;
}
/*!
@ copydoc basic_json : : crbegin ( )
*/
const_reverse_iterator rbegin ( ) const noexcept
{
return crbegin ( ) ;
}
/*!
@ brief returns an iterator to the reverse - end
Returns an iterator to the reverse - end ; that is , one before the first
element .
@ image html range - rbegin - rend . svg " Illustration from cppreference.com "
@ complexity Constant .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ ReversibleContainer ] ( https : //en.cppreference.com/w/cpp/named_req/ReversibleContainer)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
- Has the semantics of ` reverse_iterator ( begin ( ) ) ` .
@ liveexample { The following code shows an example for ` rend ( ) ` . , rend }
@ sa @ ref crend ( ) - - returns a const reverse iterator to the end
@ sa @ ref rbegin ( ) - - returns a reverse iterator to the beginning
@ sa @ ref crbegin ( ) - - returns a const reverse iterator to the beginning
@ since version 1.0 .0
*/
reverse_iterator rend ( ) noexcept
{
return reverse_iterator ( begin ( ) ) ;
}
/*!
@ copydoc basic_json : : crend ( )
*/
const_reverse_iterator rend ( ) const noexcept
{
return crend ( ) ;
}
/*!
@ brief returns a const reverse iterator to the last element
Returns a const iterator to the reverse - beginning ; that is , the last
element .
@ image html range - rbegin - rend . svg " Illustration from cppreference.com "
@ complexity Constant .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ ReversibleContainer ] ( https : //en.cppreference.com/w/cpp/named_req/ReversibleContainer)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
- Has the semantics of ` const_cast < const basic_json & > ( * this ) . rbegin ( ) ` .
@ liveexample { The following code shows an example for ` crbegin ( ) ` . , crbegin }
@ sa @ ref rbegin ( ) - - returns a reverse iterator to the beginning
@ sa @ ref rend ( ) - - returns a reverse iterator to the end
@ sa @ ref crend ( ) - - returns a const reverse iterator to the end
@ since version 1.0 .0
*/
const_reverse_iterator crbegin ( ) const noexcept
{
return const_reverse_iterator ( cend ( ) ) ;
}
/*!
@ brief returns a const reverse iterator to one before the first
Returns a const reverse iterator to the reverse - end ; that is , one before
the first element .
@ image html range - rbegin - rend . svg " Illustration from cppreference.com "
@ complexity Constant .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ ReversibleContainer ] ( https : //en.cppreference.com/w/cpp/named_req/ReversibleContainer)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
- Has the semantics of ` const_cast < const basic_json & > ( * this ) . rend ( ) ` .
@ liveexample { The following code shows an example for ` crend ( ) ` . , crend }
@ sa @ ref rend ( ) - - returns a reverse iterator to the end
@ sa @ ref rbegin ( ) - - returns a reverse iterator to the beginning
@ sa @ ref crbegin ( ) - - returns a const reverse iterator to the beginning
@ since version 1.0 .0
*/
const_reverse_iterator crend ( ) const noexcept
{
return const_reverse_iterator ( cbegin ( ) ) ;
}
public :
/*!
@ brief wrapper to access iterator member functions in range - based for
This function allows to access @ ref iterator : : key ( ) and @ ref
iterator : : value ( ) during range - based for loops . In these loops , a
reference to the JSON values is returned , so there is no access to the
underlying iterator .
For loop without iterator_wrapper :
@ code { cpp }
for ( auto it = j_object . begin ( ) ; it ! = j_object . end ( ) ; + + it )
{
std : : cout < < " key: " < < it . key ( ) < < " , value: " < < it . value ( ) < < ' \n ' ;
}
@ endcode
Range - based for loop without iterator proxy :
@ code { cpp }
for ( auto it : j_object )
{
// "it" is of type json::reference and has no key() member
std : : cout < < " value: " < < it < < ' \n ' ;
}
@ endcode
Range - based for loop with iterator proxy :
@ code { cpp }
for ( auto it : json : : iterator_wrapper ( j_object ) )
{
std : : cout < < " key: " < < it . key ( ) < < " , value: " < < it . value ( ) < < ' \n ' ;
}
@ endcode
@ note When iterating over an array , ` key ( ) ` will return the index of the
element as string ( see example ) .
@ param [ in ] ref reference to a JSON value
@ return iteration proxy object wrapping @ a ref with an interface to use in
range - based for loops
@ liveexample { The following code shows how the wrapper is used , iterator_wrapper }
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes in the JSON value .
@ complexity Constant .
@ note The name of this function is not yet final and may change in the
future .
2018-01-23 23:33:08 +08:00
@ deprecated This stream operator is deprecated and will be removed in
future 4.0 .0 of the library . Please use @ ref items ( ) instead ;
that is , replace ` json : : iterator_wrapper ( j ) ` with ` j . items ( ) ` .
2018-01-10 01:30:02 +08:00
*/
2018-01-23 23:33:08 +08:00
JSON_DEPRECATED
2018-01-17 03:41:04 +08:00
static iteration_proxy < iterator > iterator_wrapper ( reference ref ) noexcept
2018-01-10 01:30:02 +08:00
{
2018-01-23 23:33:08 +08:00
return ref . items ( ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ copydoc iterator_wrapper ( reference )
*/
2018-01-23 23:33:08 +08:00
JSON_DEPRECATED
2018-01-17 03:41:04 +08:00
static iteration_proxy < const_iterator > iterator_wrapper ( const_reference ref ) noexcept
2018-01-10 01:30:02 +08:00
{
2018-01-23 23:33:08 +08:00
return ref . items ( ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief helper to access iterator member functions in range - based for
This function allows to access @ ref iterator : : key ( ) and @ ref
iterator : : value ( ) during range - based for loops . In these loops , a
reference to the JSON values is returned , so there is no access to the
underlying iterator .
For loop without ` items ( ) ` function :
@ code { cpp }
for ( auto it = j_object . begin ( ) ; it ! = j_object . end ( ) ; + + it )
{
std : : cout < < " key: " < < it . key ( ) < < " , value: " < < it . value ( ) < < ' \n ' ;
}
@ endcode
Range - based for loop without ` items ( ) ` function :
@ code { cpp }
for ( auto it : j_object )
{
// "it" is of type json::reference and has no key() member
std : : cout < < " value: " < < it < < ' \n ' ;
}
@ endcode
Range - based for loop with ` items ( ) ` function :
@ code { cpp }
2018-12-22 05:51:12 +08:00
for ( auto & el : j_object . items ( ) )
2018-01-10 01:30:02 +08:00
{
2018-12-22 05:51:12 +08:00
std : : cout < < " key: " < < el . key ( ) < < " , value: " < < el . value ( ) < < ' \n ' ;
}
@ endcode
The ` items ( ) ` function also allows to use
[ structured bindings ] ( https : //en.cppreference.com/w/cpp/language/structured_binding)
( C + + 17 ) :
@ code { cpp }
for ( auto & [ key , val ] : j_object . items ( ) )
{
std : : cout < < " key: " < < key < < " , value: " < < val < < ' \n ' ;
2018-01-10 01:30:02 +08:00
}
@ endcode
@ note When iterating over an array , ` key ( ) ` will return the index of the
2018-01-17 03:41:04 +08:00
element as string ( see example ) . For primitive types ( e . g . , numbers ) ,
` key ( ) ` returns an empty string .
2018-01-10 01:30:02 +08:00
@ return iteration proxy object wrapping @ a ref with an interface to use in
range - based for loops
@ liveexample { The following code shows how the function is used . , items }
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes in the JSON value .
@ complexity Constant .
2018-01-17 03:41:04 +08:00
2018-12-22 05:51:12 +08:00
@ since version 3.1 .0 , structured bindings support since 3.5 .0 .
2018-01-10 01:30:02 +08:00
*/
2018-01-17 03:41:04 +08:00
iteration_proxy < iterator > items ( ) noexcept
2018-01-10 01:30:02 +08:00
{
return iteration_proxy < iterator > ( * this ) ;
}
/*!
@ copydoc items ( )
*/
2018-01-17 03:41:04 +08:00
iteration_proxy < const_iterator > items ( ) const noexcept
2018-01-10 01:30:02 +08:00
{
return iteration_proxy < const_iterator > ( * this ) ;
}
/// @}
//////////////
// capacity //
//////////////
/// @name capacity
/// @{
/*!
@ brief checks whether the container is empty .
Checks if a JSON value has no elements ( i . e . whether its @ ref size is ` 0 ` ) .
@ return The return value depends on the different types and is
defined as follows :
Value type | return value
- - - - - - - - - - - | - - - - - - - - - - - - -
null | ` true `
boolean | ` false `
string | ` false `
number | ` false `
object | result of function ` object_t : : empty ( ) `
array | result of function ` array_t : : empty ( ) `
@ liveexample { The following code uses ` empty ( ) ` to check if a JSON
object contains any elements . , empty }
@ complexity Constant , as long as @ ref array_t and @ ref object_t satisfy
the Container concept ; that is , their ` empty ( ) ` functions have constant
complexity .
@ iterators No changes .
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ note This function does not return whether a string stored as JSON value
is empty - it returns whether the JSON container itself is empty which is
false in the case of a string .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
- Has the semantics of ` begin ( ) = = end ( ) ` .
@ sa @ ref size ( ) - - returns the number of elements
@ since version 1.0 .0
*/
bool empty ( ) const noexcept
{
switch ( m_type )
{
case value_t : : null :
{
// null values are empty
return true ;
}
case value_t : : array :
{
// delegate call to array_t::empty()
return m_value . array - > empty ( ) ;
}
case value_t : : object :
{
// delegate call to object_t::empty()
return m_value . object - > empty ( ) ;
}
default :
{
// all other types are nonempty
return false ;
}
}
}
/*!
@ brief returns the number of elements
Returns the number of elements in a JSON value .
@ return The return value depends on the different types and is
defined as follows :
Value type | return value
- - - - - - - - - - - | - - - - - - - - - - - - -
null | ` 0 `
boolean | ` 1 `
string | ` 1 `
number | ` 1 `
object | result of function object_t : : size ( )
array | result of function array_t : : size ( )
@ liveexample { The following code calls ` size ( ) ` on the different value
types . , size }
@ complexity Constant , as long as @ ref array_t and @ ref object_t satisfy
the Container concept ; that is , their size ( ) functions have constant
complexity .
@ iterators No changes .
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ note This function does not return the length of a string stored as JSON
value - it returns the number of elements in the JSON value which is 1 in
the case of a string .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
- Has the semantics of ` std : : distance ( begin ( ) , end ( ) ) ` .
@ sa @ ref empty ( ) - - checks whether the container is empty
@ sa @ ref max_size ( ) - - returns the maximal number of elements
@ since version 1.0 .0
*/
size_type size ( ) const noexcept
{
switch ( m_type )
{
case value_t : : null :
{
// null values are empty
return 0 ;
}
case value_t : : array :
{
// delegate call to array_t::size()
return m_value . array - > size ( ) ;
}
case value_t : : object :
{
// delegate call to object_t::size()
return m_value . object - > size ( ) ;
}
default :
{
// all other types have size 1
return 1 ;
}
}
}
/*!
@ brief returns the maximum possible number of elements
Returns the maximum number of elements a JSON value is able to hold due to
system or library implementation limitations , i . e . ` std : : distance ( begin ( ) ,
end ( ) ) ` for the JSON value .
@ return The return value depends on the different types and is
defined as follows :
Value type | return value
- - - - - - - - - - - | - - - - - - - - - - - - -
null | ` 0 ` ( same as ` size ( ) ` )
boolean | ` 1 ` ( same as ` size ( ) ` )
string | ` 1 ` ( same as ` size ( ) ` )
number | ` 1 ` ( same as ` size ( ) ` )
object | result of function ` object_t : : max_size ( ) `
array | result of function ` array_t : : max_size ( ) `
@ liveexample { The following code calls ` max_size ( ) ` on the different value
types . Note the output is implementation specific . , max_size }
@ complexity Constant , as long as @ ref array_t and @ ref object_t satisfy
the Container concept ; that is , their ` max_size ( ) ` functions have constant
complexity .
@ iterators No changes .
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ requirement This function helps ` basic_json ` satisfying the
2018-06-25 04:30:37 +08:00
[ Container ] ( https : //en.cppreference.com/w/cpp/named_req/Container)
2018-01-10 01:30:02 +08:00
requirements :
- The complexity is constant .
- Has the semantics of returning ` b . size ( ) ` where ` b ` is the largest
possible JSON value .
@ sa @ ref size ( ) - - returns the number of elements
@ since version 1.0 .0
*/
size_type max_size ( ) const noexcept
{
switch ( m_type )
{
case value_t : : array :
{
// delegate call to array_t::max_size()
return m_value . array - > max_size ( ) ;
}
case value_t : : object :
{
// delegate call to object_t::max_size()
return m_value . object - > max_size ( ) ;
}
default :
{
// all other types have max_size() == size()
return size ( ) ;
}
}
}
/// @}
///////////////
// modifiers //
///////////////
/// @name modifiers
/// @{
/*!
@ brief clears the contents
Clears the content of a JSON value and resets it to the default value as
if @ ref basic_json ( value_t ) would have been called with the current value
type from @ ref type ( ) :
Value type | initial value
- - - - - - - - - - - | - - - - - - - - - - - - -
null | ` null `
boolean | ` false `
string | ` " " `
number | ` 0 `
object | ` { } `
array | ` [ ] `
@ post Has the same effect as calling
@ code { . cpp }
* this = basic_json ( type ( ) ) ;
@ endcode
@ liveexample { The example below shows the effect of ` clear ( ) ` to different
JSON types . , clear }
@ complexity Linear in the size of the JSON value .
@ iterators All iterators , pointers and references related to this container
are invalidated .
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ sa @ ref basic_json ( value_t ) - - constructor that creates an object with the
same value than calling ` clear ( ) `
@ since version 1.0 .0
*/
void clear ( ) noexcept
{
switch ( m_type )
{
case value_t : : number_integer :
{
m_value . number_integer = 0 ;
break ;
}
case value_t : : number_unsigned :
{
m_value . number_unsigned = 0 ;
break ;
}
case value_t : : number_float :
{
m_value . number_float = 0.0 ;
break ;
}
case value_t : : boolean :
{
m_value . boolean = false ;
break ;
}
case value_t : : string :
{
m_value . string - > clear ( ) ;
break ;
}
case value_t : : array :
{
m_value . array - > clear ( ) ;
break ;
}
case value_t : : object :
{
m_value . object - > clear ( ) ;
break ;
}
default :
break ;
}
}
/*!
@ brief add an object to an array
Appends the given element @ a val to the end of the JSON value . If the
function is called on a JSON null value , an empty array is created before
appending @ a val .
@ param [ in ] val the value to add to the JSON array
@ throw type_error .308 when called on a type other than JSON array or
null ; example : ` " cannot use push_back() with number " `
@ complexity Amortized constant .
@ liveexample { The example shows how ` push_back ( ) ` and ` + = ` can be used to
add elements to a JSON array . Note how the ` null ` value was silently
converted to a JSON array . , push_back }
@ since version 1.0 .0
*/
void push_back ( basic_json & & val )
{
// push_back only works for null objects or arrays
if ( JSON_UNLIKELY ( not ( is_null ( ) or is_array ( ) ) ) )
{
JSON_THROW ( type_error : : create ( 308 , " cannot use push_back() with " + std : : string ( type_name ( ) ) ) ) ;
}
// transform null object into an array
if ( is_null ( ) )
{
m_type = value_t : : array ;
m_value = value_t : : array ;
assert_invariant ( ) ;
}
// add element to array (move semantics)
m_value . array - > push_back ( std : : move ( val ) ) ;
// invalidate object
val . m_type = value_t : : null ;
}
/*!
@ brief add an object to an array
@ copydoc push_back ( basic_json & & )
*/
reference operator + = ( basic_json & & val )
{
push_back ( std : : move ( val ) ) ;
return * this ;
}
/*!
@ brief add an object to an array
@ copydoc push_back ( basic_json & & )
*/
void push_back ( const basic_json & val )
{
// push_back only works for null objects or arrays
if ( JSON_UNLIKELY ( not ( is_null ( ) or is_array ( ) ) ) )
{
JSON_THROW ( type_error : : create ( 308 , " cannot use push_back() with " + std : : string ( type_name ( ) ) ) ) ;
}
// transform null object into an array
if ( is_null ( ) )
{
m_type = value_t : : array ;
m_value = value_t : : array ;
assert_invariant ( ) ;
}
// add element to array
m_value . array - > push_back ( val ) ;
}
/*!
@ brief add an object to an array
@ copydoc push_back ( basic_json & & )
*/
reference operator + = ( const basic_json & val )
{
push_back ( val ) ;
return * this ;
}
/*!
@ brief add an object to an object
Inserts the given element @ a val to the JSON object . If the function is
called on a JSON null value , an empty object is created before inserting
@ a val .
@ param [ in ] val the value to add to the JSON object
@ throw type_error .308 when called on a type other than JSON object or
null ; example : ` " cannot use push_back() with number " `
@ complexity Logarithmic in the size of the container , O ( log ( ` size ( ) ` ) ) .
@ liveexample { The example shows how ` push_back ( ) ` and ` + = ` can be used to
add elements to a JSON object . Note how the ` null ` value was silently
converted to a JSON object . , push_back__object_t__value }
@ since version 1.0 .0
*/
void push_back ( const typename object_t : : value_type & val )
{
// push_back only works for null objects or objects
if ( JSON_UNLIKELY ( not ( is_null ( ) or is_object ( ) ) ) )
{
JSON_THROW ( type_error : : create ( 308 , " cannot use push_back() with " + std : : string ( type_name ( ) ) ) ) ;
}
// transform null object into an object
if ( is_null ( ) )
{
m_type = value_t : : object ;
m_value = value_t : : object ;
assert_invariant ( ) ;
}
// add element to array
m_value . object - > insert ( val ) ;
}
/*!
@ brief add an object to an object
@ copydoc push_back ( const typename object_t : : value_type & )
*/
reference operator + = ( const typename object_t : : value_type & val )
{
push_back ( val ) ;
return * this ;
}
/*!
@ brief add an object to an object
This function allows to use ` push_back ` with an initializer list . In case
1. the current value is an object ,
2. the initializer list @ a init contains only two elements , and
3. the first element of @ a init is a string ,
@ a init is converted into an object element and added using
@ ref push_back ( const typename object_t : : value_type & ) . Otherwise , @ a init
is converted to a JSON value and added using @ ref push_back ( basic_json & & ) .
@ param [ in ] init an initializer list
@ complexity Linear in the size of the initializer list @ a init .
@ note This function is required to resolve an ambiguous overload error ,
because pairs like ` { " key " , " value " } ` can be both interpreted as
` object_t : : value_type ` or ` std : : initializer_list < basic_json > ` , see
https : //github.com/nlohmann/json/issues/235 for more information.
@ liveexample { The example shows how initializer lists are treated as
objects when possible . , push_back__initializer_list }
*/
void push_back ( initializer_list_t init )
{
if ( is_object ( ) and init . size ( ) = = 2 and ( * init . begin ( ) ) - > is_string ( ) )
{
basic_json & & key = init . begin ( ) - > moved_or_copied ( ) ;
push_back ( typename object_t : : value_type (
std : : move ( key . get_ref < string_t & > ( ) ) , ( init . begin ( ) + 1 ) - > moved_or_copied ( ) ) ) ;
}
else
{
push_back ( basic_json ( init ) ) ;
}
}
/*!
@ brief add an object to an object
@ copydoc push_back ( initializer_list_t )
*/
reference operator + = ( initializer_list_t init )
{
push_back ( init ) ;
return * this ;
}
/*!
@ brief add an object to an array
Creates a JSON value from the passed parameters @ a args to the end of the
JSON value . If the function is called on a JSON null value , an empty array
is created before appending the value created from @ a args .
@ param [ in ] args arguments to forward to a constructor of @ ref basic_json
@ tparam Args compatible types to create a @ ref basic_json object
@ throw type_error .311 when called on a type other than JSON array or
null ; example : ` " cannot use emplace_back() with number " `
@ complexity Amortized constant .
@ liveexample { The example shows how ` push_back ( ) ` can be used to add
elements to a JSON array . Note how the ` null ` value was silently converted
to a JSON array . , emplace_back }
@ since version 2.0 .8
*/
template < class . . . Args >
void emplace_back ( Args & & . . . args )
{
// emplace_back only works for null objects or arrays
if ( JSON_UNLIKELY ( not ( is_null ( ) or is_array ( ) ) ) )
{
JSON_THROW ( type_error : : create ( 311 , " cannot use emplace_back() with " + std : : string ( type_name ( ) ) ) ) ;
}
// transform null object into an array
if ( is_null ( ) )
{
m_type = value_t : : array ;
m_value = value_t : : array ;
assert_invariant ( ) ;
}
// add element to array (perfect forwarding)
m_value . array - > emplace_back ( std : : forward < Args > ( args ) . . . ) ;
}
/*!
@ brief add an object to an object if key does not exist
Inserts a new element into a JSON object constructed in - place with the
given @ a args if there is no element with the key in the container . If the
function is called on a JSON null value , an empty object is created before
appending the value created from @ a args .
@ param [ in ] args arguments to forward to a constructor of @ ref basic_json
@ tparam Args compatible types to create a @ ref basic_json object
@ return a pair consisting of an iterator to the inserted element , or the
already - existing element if no insertion happened , and a bool
denoting whether the insertion took place .
@ throw type_error .311 when called on a type other than JSON object or
null ; example : ` " cannot use emplace() with number " `
@ complexity Logarithmic in the size of the container , O ( log ( ` size ( ) ` ) ) .
@ liveexample { The example shows how ` emplace ( ) ` can be used to add elements
to a JSON object . Note how the ` null ` value was silently converted to a
JSON object . Further note how no value is added if there was already one
value stored with the same key . , emplace }
@ since version 2.0 .8
*/
template < class . . . Args >
std : : pair < iterator , bool > emplace ( Args & & . . . args )
{
// emplace only works for null objects or arrays
if ( JSON_UNLIKELY ( not ( is_null ( ) or is_object ( ) ) ) )
{
JSON_THROW ( type_error : : create ( 311 , " cannot use emplace() with " + std : : string ( type_name ( ) ) ) ) ;
}
// transform null object into an object
if ( is_null ( ) )
{
m_type = value_t : : object ;
m_value = value_t : : object ;
assert_invariant ( ) ;
}
// add element to array (perfect forwarding)
auto res = m_value . object - > emplace ( std : : forward < Args > ( args ) . . . ) ;
// create result iterator and set iterator to the result of emplace
auto it = begin ( ) ;
it . m_it . object_iterator = res . first ;
// return pair of iterator and boolean
return { it , res . second } ;
}
2018-09-26 00:15:29 +08:00
/// Helper for insertion of an iterator
/// @note: This uses std::distance to support GCC 4.8,
/// see https://github.com/nlohmann/json/pull/1257
2018-09-20 23:19:33 +08:00
template < typename . . . Args >
iterator insert_iterator ( const_iterator pos , Args & & . . . args )
{
iterator result ( this ) ;
assert ( m_value . array ! = nullptr ) ;
auto insert_pos = std : : distance ( m_value . array - > begin ( ) , pos . m_it . array_iterator ) ;
m_value . array - > insert ( pos . m_it . array_iterator , std : : forward < Args > ( args ) . . . ) ;
result . m_it . array_iterator = m_value . array - > begin ( ) + insert_pos ;
2018-09-26 00:15:29 +08:00
// This could have been written as:
2018-09-20 23:19:33 +08:00
// result.m_it.array_iterator = m_value.array->insert(pos.m_it.array_iterator, cnt, val);
2018-09-26 00:15:29 +08:00
// but the return value of insert is missing in GCC 4.8, so it is written this way instead.
2018-09-20 23:19:33 +08:00
return result ;
}
2018-01-10 01:30:02 +08:00
/*!
@ brief inserts element
Inserts element @ a val before iterator @ a pos .
@ param [ in ] pos iterator before which the content will be inserted ; may be
the end ( ) iterator
@ param [ in ] val element to insert
@ return iterator pointing to the inserted @ a val .
@ throw type_error .309 if called on JSON values other than arrays ;
example : ` " cannot use insert() with string " `
@ throw invalid_iterator .202 if @ a pos is not an iterator of * this ;
example : ` " iterator does not fit current value " `
@ complexity Constant plus linear in the distance between @ a pos and end of
the container .
@ liveexample { The example shows how ` insert ( ) ` is used . , insert }
@ since version 1.0 .0
*/
iterator insert ( const_iterator pos , const basic_json & val )
{
// insert only works for arrays
if ( JSON_LIKELY ( is_array ( ) ) )
{
// check if iterator pos fits to this JSON value
if ( JSON_UNLIKELY ( pos . m_object ! = this ) )
{
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " ) ) ;
}
// insert to array and return iterator
2018-09-20 23:19:33 +08:00
return insert_iterator ( pos , val ) ;
2018-01-10 01:30:02 +08:00
}
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) ) ) ;
}
/*!
@ brief inserts element
@ copydoc insert ( const_iterator , const basic_json & )
*/
iterator insert ( const_iterator pos , basic_json & & val )
{
return insert ( pos , val ) ;
}
/*!
@ brief inserts elements
Inserts @ a cnt copies of @ a val before iterator @ a pos .
@ param [ in ] pos iterator before which the content will be inserted ; may be
the end ( ) iterator
@ param [ in ] cnt number of copies of @ a val to insert
@ param [ in ] val element to insert
@ return iterator pointing to the first element inserted , or @ a pos if
` cnt = = 0 `
@ throw type_error .309 if called on JSON values other than arrays ; example :
` " cannot use insert() with string " `
@ throw invalid_iterator .202 if @ a pos is not an iterator of * this ;
example : ` " iterator does not fit current value " `
@ complexity Linear in @ a cnt plus linear in the distance between @ a pos
and end of the container .
@ liveexample { The example shows how ` insert ( ) ` is used . , insert__count }
@ since version 1.0 .0
*/
iterator insert ( const_iterator pos , size_type cnt , const basic_json & val )
{
// insert only works for arrays
if ( JSON_LIKELY ( is_array ( ) ) )
{
// check if iterator pos fits to this JSON value
if ( JSON_UNLIKELY ( pos . m_object ! = this ) )
{
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " ) ) ;
}
// insert to array and return iterator
2018-09-20 23:19:33 +08:00
return insert_iterator ( pos , cnt , val ) ;
2018-01-10 01:30:02 +08:00
}
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) ) ) ;
}
/*!
@ brief inserts elements
Inserts elements from range ` [ first , last ) ` before iterator @ a pos .
@ param [ in ] pos iterator before which the content will be inserted ; may be
the end ( ) iterator
@ param [ in ] first begin of the range of elements to insert
@ param [ in ] last end of the range of elements to insert
@ throw type_error .309 if called on JSON values other than arrays ; example :
` " cannot use insert() with string " `
@ throw invalid_iterator .202 if @ a pos is not an iterator of * this ;
example : ` " iterator does not fit current value " `
@ throw invalid_iterator .210 if @ a first and @ a last do not belong to the
same JSON value ; example : ` " iterators do not fit " `
@ throw invalid_iterator .211 if @ a first or @ a last are iterators into
container for which insert is called ; example : ` " passed iterators may not
belong to container " `
@ return iterator pointing to the first element inserted , or @ a pos if
` first = = last `
@ complexity Linear in ` std : : distance ( first , last ) ` plus linear in the
distance between @ a pos and end of the container .
@ liveexample { The example shows how ` insert ( ) ` is used . , insert__range }
@ since version 1.0 .0
*/
iterator insert ( const_iterator pos , const_iterator first , const_iterator last )
{
// insert only works for arrays
if ( JSON_UNLIKELY ( not is_array ( ) ) )
{
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) ) ) ;
}
// check if iterator pos fits to this JSON value
if ( JSON_UNLIKELY ( pos . m_object ! = this ) )
{
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " ) ) ;
}
// check if range iterators belong to the same JSON object
if ( JSON_UNLIKELY ( first . m_object ! = last . m_object ) )
{
JSON_THROW ( invalid_iterator : : create ( 210 , " iterators do not fit " ) ) ;
}
if ( JSON_UNLIKELY ( first . m_object = = this ) )
{
JSON_THROW ( invalid_iterator : : create ( 211 , " passed iterators may not belong to container " ) ) ;
}
// insert to array and return iterator
2018-09-20 23:19:33 +08:00
return insert_iterator ( pos , first . m_it . array_iterator , last . m_it . array_iterator ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief inserts elements
Inserts elements from initializer list @ a ilist before iterator @ a pos .
@ param [ in ] pos iterator before which the content will be inserted ; may be
the end ( ) iterator
@ param [ in ] ilist initializer list to insert the values from
@ throw type_error .309 if called on JSON values other than arrays ; example :
` " cannot use insert() with string " `
@ throw invalid_iterator .202 if @ a pos is not an iterator of * this ;
example : ` " iterator does not fit current value " `
@ return iterator pointing to the first element inserted , or @ a pos if
` ilist ` is empty
@ complexity Linear in ` ilist . size ( ) ` plus linear in the distance between
@ a pos and end of the container .
@ liveexample { The example shows how ` insert ( ) ` is used . , insert__ilist }
@ since version 1.0 .0
*/
iterator insert ( const_iterator pos , initializer_list_t ilist )
{
// insert only works for arrays
if ( JSON_UNLIKELY ( not is_array ( ) ) )
{
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) ) ) ;
}
// check if iterator pos fits to this JSON value
if ( JSON_UNLIKELY ( pos . m_object ! = this ) )
{
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " ) ) ;
}
// insert to array and return iterator
2018-09-20 23:19:33 +08:00
return insert_iterator ( pos , ilist . begin ( ) , ilist . end ( ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief inserts elements
Inserts elements from range ` [ first , last ) ` .
@ param [ in ] first begin of the range of elements to insert
@ param [ in ] last end of the range of elements to insert
@ throw type_error .309 if called on JSON values other than objects ; example :
` " cannot use insert() with string " `
@ throw invalid_iterator .202 if iterator @ a first or @ a last does does not
point to an object ; example : ` " iterators first and last must point to
objects " `
@ throw invalid_iterator .210 if @ a first and @ a last do not belong to the
same JSON value ; example : ` " iterators do not fit " `
@ complexity Logarithmic : ` O ( N * log ( size ( ) + N ) ) ` , where ` N ` is the number
of elements to insert .
@ liveexample { The example shows how ` insert ( ) ` is used . , insert__range_object }
@ since version 3.0 .0
*/
void insert ( const_iterator first , const_iterator last )
{
// insert only works for objects
if ( JSON_UNLIKELY ( not is_object ( ) ) )
{
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) ) ) ;
}
// check if range iterators belong to the same JSON object
if ( JSON_UNLIKELY ( first . m_object ! = last . m_object ) )
{
JSON_THROW ( invalid_iterator : : create ( 210 , " iterators do not fit " ) ) ;
}
// passed iterators must belong to objects
if ( JSON_UNLIKELY ( not first . m_object - > is_object ( ) ) )
{
JSON_THROW ( invalid_iterator : : create ( 202 , " iterators first and last must point to objects " ) ) ;
}
m_value . object - > insert ( first . m_it . object_iterator , last . m_it . object_iterator ) ;
}
/*!
@ brief updates a JSON object from another object , overwriting existing keys
Inserts all values from JSON object @ a j and overwrites existing keys .
@ param [ in ] j JSON object to read values from
@ throw type_error .312 if called on JSON values other than objects ; example :
` " cannot use update() with string " `
@ complexity O ( N * log ( size ( ) + N ) ) , where N is the number of elements to
insert .
@ liveexample { The example shows how ` update ( ) ` is used . , update }
@ sa https : //docs.python.org/3.6/library/stdtypes.html#dict.update
@ since version 3.0 .0
*/
void update ( const_reference j )
{
// implicitly convert null value to an empty object
if ( is_null ( ) )
{
m_type = value_t : : object ;
m_value . object = create < object_t > ( ) ;
assert_invariant ( ) ;
}
if ( JSON_UNLIKELY ( not is_object ( ) ) )
{
JSON_THROW ( type_error : : create ( 312 , " cannot use update() with " + std : : string ( type_name ( ) ) ) ) ;
}
if ( JSON_UNLIKELY ( not j . is_object ( ) ) )
{
JSON_THROW ( type_error : : create ( 312 , " cannot use update() with " + std : : string ( j . type_name ( ) ) ) ) ;
}
for ( auto it = j . cbegin ( ) ; it ! = j . cend ( ) ; + + it )
{
m_value . object - > operator [ ] ( it . key ( ) ) = it . value ( ) ;
}
}
/*!
@ brief updates a JSON object from another object , overwriting existing keys
Inserts all values from from range ` [ first , last ) ` and overwrites existing
keys .
@ param [ in ] first begin of the range of elements to insert
@ param [ in ] last end of the range of elements to insert
@ throw type_error .312 if called on JSON values other than objects ; example :
` " cannot use update() with string " `
@ throw invalid_iterator .202 if iterator @ a first or @ a last does does not
point to an object ; example : ` " iterators first and last must point to
objects " `
@ throw invalid_iterator .210 if @ a first and @ a last do not belong to the
same JSON value ; example : ` " iterators do not fit " `
@ complexity O ( N * log ( size ( ) + N ) ) , where N is the number of elements to
insert .
@ liveexample { The example shows how ` update ( ) ` is used__range . , update }
@ sa https : //docs.python.org/3.6/library/stdtypes.html#dict.update
@ since version 3.0 .0
*/
void update ( const_iterator first , const_iterator last )
{
// implicitly convert null value to an empty object
if ( is_null ( ) )
{
m_type = value_t : : object ;
m_value . object = create < object_t > ( ) ;
assert_invariant ( ) ;
}
if ( JSON_UNLIKELY ( not is_object ( ) ) )
{
JSON_THROW ( type_error : : create ( 312 , " cannot use update() with " + std : : string ( type_name ( ) ) ) ) ;
}
// check if range iterators belong to the same JSON object
if ( JSON_UNLIKELY ( first . m_object ! = last . m_object ) )
{
JSON_THROW ( invalid_iterator : : create ( 210 , " iterators do not fit " ) ) ;
}
// passed iterators must belong to objects
if ( JSON_UNLIKELY ( not first . m_object - > is_object ( )
2018-03-02 16:12:44 +08:00
or not last . m_object - > is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
JSON_THROW ( invalid_iterator : : create ( 202 , " iterators first and last must point to objects " ) ) ;
}
for ( auto it = first ; it ! = last ; + + it )
{
m_value . object - > operator [ ] ( it . key ( ) ) = it . value ( ) ;
}
}
/*!
@ brief exchanges the values
Exchanges the contents of the JSON value with those of @ a other . Does not
invoke any move , copy , or swap operations on individual elements . All
iterators and references remain valid . The past - the - end iterator is
invalidated .
@ param [ in , out ] other JSON value to exchange the contents with
@ complexity Constant .
@ liveexample { The example below shows how JSON values can be swapped with
` swap ( ) ` . , swap__reference }
@ since version 1.0 .0
*/
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
)
{
std : : swap ( m_type , other . m_type ) ;
std : : swap ( m_value , other . m_value ) ;
assert_invariant ( ) ;
}
/*!
@ brief exchanges the values
Exchanges the contents of a JSON array with those of @ a other . Does not
invoke any move , copy , or swap operations on individual elements . All
iterators and references remain valid . The past - the - end iterator is
invalidated .
@ param [ in , out ] other array to exchange the contents with
@ throw type_error .310 when JSON value is not an array ; example : ` " cannot
use swap ( ) with string " `
@ complexity Constant .
@ liveexample { The example below shows how arrays can be swapped with
` swap ( ) ` . , swap__array_t }
@ since version 1.0 .0
*/
void swap ( array_t & other )
{
// swap only works for arrays
if ( JSON_LIKELY ( is_array ( ) ) )
{
std : : swap ( * ( m_value . array ) , other ) ;
}
else
{
JSON_THROW ( type_error : : create ( 310 , " cannot use swap() with " + std : : string ( type_name ( ) ) ) ) ;
}
}
/*!
@ brief exchanges the values
Exchanges the contents of a JSON object with those of @ a other . Does not
invoke any move , copy , or swap operations on individual elements . All
iterators and references remain valid . The past - the - end iterator is
invalidated .
@ param [ in , out ] other object to exchange the contents with
@ throw type_error .310 when JSON value is not an object ; example :
` " cannot use swap() with string " `
@ complexity Constant .
@ liveexample { The example below shows how objects can be swapped with
` swap ( ) ` . , swap__object_t }
@ since version 1.0 .0
*/
void swap ( object_t & other )
{
// swap only works for objects
if ( JSON_LIKELY ( is_object ( ) ) )
{
std : : swap ( * ( m_value . object ) , other ) ;
}
else
{
JSON_THROW ( type_error : : create ( 310 , " cannot use swap() with " + std : : string ( type_name ( ) ) ) ) ;
}
}
/*!
@ brief exchanges the values
Exchanges the contents of a JSON string with those of @ a other . Does not
invoke any move , copy , or swap operations on individual elements . All
iterators and references remain valid . The past - the - end iterator is
invalidated .
@ param [ in , out ] other string to exchange the contents with
@ throw type_error .310 when JSON value is not a string ; example : ` " cannot
use swap ( ) with boolean " `
@ complexity Constant .
@ liveexample { The example below shows how strings can be swapped with
` swap ( ) ` . , swap__string_t }
@ since version 1.0 .0
*/
void swap ( string_t & other )
{
// swap only works for strings
if ( JSON_LIKELY ( is_string ( ) ) )
{
std : : swap ( * ( m_value . string ) , other ) ;
}
else
{
JSON_THROW ( type_error : : create ( 310 , " cannot use swap() with " + std : : string ( type_name ( ) ) ) ) ;
}
}
/// @}
public :
//////////////////////////////////////////
// lexicographical comparison operators //
//////////////////////////////////////////
/// @name lexicographical comparison operators
/// @{
/*!
@ brief comparison : equal
Compares two JSON values for equality according to the following rules :
- Two JSON values are equal if ( 1 ) they are from the same type and ( 2 )
their stored values are the same according to their respective
` operator = = ` .
- Integer and floating - point numbers are automatically converted before
comparison . Note than two NaN values are always treated as unequal .
- Two JSON null values are equal .
@ note Floating - point inside JSON values numbers are compared with
` json : : number_float_t : : operator = = ` which is ` double : : operator = = ` by
default . To compare floating - point while respecting an epsilon , an alternative
[ comparison function ] ( https : //github.com/mariokonrad/marnav/blob/master/src/marnav/math/floatingpoint.hpp#L34-#L39)
could be used , for instance
@ code { . cpp }
template < typename T , typename = typename std : : enable_if < std : : is_floating_point < T > : : value , T > : : type >
inline bool is_same ( T a , T b , T epsilon = std : : numeric_limits < T > : : epsilon ( ) ) noexcept
{
return std : : abs ( a - b ) < = epsilon ;
}
@ endcode
@ note NaN values never compare equal to themselves or to other NaN values .
@ param [ in ] lhs first JSON value to consider
@ param [ in ] rhs second JSON value to consider
@ return whether the values @ a lhs and @ a rhs are equal
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ complexity Linear .
@ liveexample { The example demonstrates comparing several JSON
types . , operator__equal }
@ since version 1.0 .0
*/
friend bool operator = = ( const_reference lhs , const_reference rhs ) noexcept
{
const auto lhs_type = lhs . type ( ) ;
const auto rhs_type = rhs . type ( ) ;
if ( lhs_type = = rhs_type )
{
switch ( lhs_type )
{
case value_t : : array :
return ( * lhs . m_value . array = = * rhs . m_value . array ) ;
case value_t : : object :
return ( * lhs . m_value . object = = * rhs . m_value . object ) ;
case value_t : : null :
return true ;
case value_t : : string :
return ( * lhs . m_value . string = = * rhs . m_value . string ) ;
case value_t : : boolean :
return ( lhs . m_value . boolean = = rhs . m_value . boolean ) ;
case value_t : : number_integer :
return ( lhs . m_value . number_integer = = rhs . m_value . number_integer ) ;
case value_t : : number_unsigned :
return ( lhs . m_value . number_unsigned = = rhs . m_value . number_unsigned ) ;
case value_t : : number_float :
return ( lhs . m_value . number_float = = rhs . m_value . number_float ) ;
default :
return false ;
}
}
else if ( lhs_type = = value_t : : number_integer and rhs_type = = value_t : : number_float )
{
return ( static_cast < number_float_t > ( lhs . m_value . number_integer ) = = rhs . m_value . number_float ) ;
}
else if ( lhs_type = = value_t : : number_float and rhs_type = = value_t : : number_integer )
{
return ( lhs . m_value . number_float = = static_cast < number_float_t > ( rhs . m_value . number_integer ) ) ;
}
else if ( lhs_type = = value_t : : number_unsigned and rhs_type = = value_t : : number_float )
{
return ( static_cast < number_float_t > ( lhs . m_value . number_unsigned ) = = rhs . m_value . number_float ) ;
}
else if ( lhs_type = = value_t : : number_float and rhs_type = = value_t : : number_unsigned )
{
return ( lhs . m_value . number_float = = static_cast < number_float_t > ( rhs . m_value . number_unsigned ) ) ;
}
else if ( lhs_type = = value_t : : number_unsigned and rhs_type = = value_t : : number_integer )
{
return ( static_cast < number_integer_t > ( lhs . m_value . number_unsigned ) = = rhs . m_value . number_integer ) ;
}
else if ( lhs_type = = value_t : : number_integer and rhs_type = = value_t : : number_unsigned )
{
return ( lhs . m_value . number_integer = = static_cast < number_integer_t > ( rhs . m_value . number_unsigned ) ) ;
}
return false ;
}
/*!
@ brief comparison : equal
@ copydoc operator = = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator = = ( const_reference lhs , const ScalarType rhs ) noexcept
{
return ( lhs = = basic_json ( rhs ) ) ;
}
/*!
@ brief comparison : equal
@ copydoc operator = = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator = = ( const ScalarType lhs , const_reference rhs ) noexcept
{
return ( basic_json ( lhs ) = = rhs ) ;
}
/*!
@ brief comparison : not equal
Compares two JSON values for inequality by calculating ` not ( lhs = = rhs ) ` .
@ param [ in ] lhs first JSON value to consider
@ param [ in ] rhs second JSON value to consider
@ return whether the values @ a lhs and @ a rhs are not equal
@ complexity Linear .
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ liveexample { The example demonstrates comparing several JSON
types . , operator__notequal }
@ since version 1.0 .0
*/
friend bool operator ! = ( const_reference lhs , const_reference rhs ) noexcept
{
return not ( lhs = = rhs ) ;
}
/*!
@ brief comparison : not equal
@ copydoc operator ! = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator ! = ( const_reference lhs , const ScalarType rhs ) noexcept
{
return ( lhs ! = basic_json ( rhs ) ) ;
}
/*!
@ brief comparison : not equal
@ copydoc operator ! = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator ! = ( const ScalarType lhs , const_reference rhs ) noexcept
{
return ( basic_json ( lhs ) ! = rhs ) ;
}
/*!
@ brief comparison : less than
Compares whether one JSON value @ a lhs is less than another JSON value @ a
rhs according to the following rules :
- If @ a lhs and @ a rhs have the same type , the values are compared using
the default ` < ` operator .
- Integer and floating - point numbers are automatically converted before
comparison
- In case @ a lhs and @ a rhs have different types , the values are ignored
and the order of the types is considered , see
@ ref operator < ( const value_t , const value_t ) .
@ param [ in ] lhs first JSON value to consider
@ param [ in ] rhs second JSON value to consider
@ return whether @ a lhs is less than @ a rhs
@ complexity Linear .
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ liveexample { The example demonstrates comparing several JSON
types . , operator__less }
@ since version 1.0 .0
*/
friend bool operator < ( const_reference lhs , const_reference rhs ) noexcept
{
const auto lhs_type = lhs . type ( ) ;
const auto rhs_type = rhs . type ( ) ;
if ( lhs_type = = rhs_type )
{
switch ( lhs_type )
{
case value_t : : array :
return ( * lhs . m_value . array ) < ( * rhs . m_value . array ) ;
case value_t : : object :
return * lhs . m_value . object < * rhs . m_value . object ;
case value_t : : null :
return false ;
case value_t : : string :
return * lhs . m_value . string < * rhs . m_value . string ;
case value_t : : boolean :
return lhs . m_value . boolean < rhs . m_value . boolean ;
case value_t : : number_integer :
return lhs . m_value . number_integer < rhs . m_value . number_integer ;
case value_t : : number_unsigned :
return lhs . m_value . number_unsigned < rhs . m_value . number_unsigned ;
case value_t : : number_float :
return lhs . m_value . number_float < rhs . m_value . number_float ;
default :
return false ;
}
}
else if ( lhs_type = = value_t : : number_integer and rhs_type = = value_t : : number_float )
{
return static_cast < number_float_t > ( lhs . m_value . number_integer ) < rhs . m_value . number_float ;
}
else if ( lhs_type = = value_t : : number_float and rhs_type = = value_t : : number_integer )
{
return lhs . m_value . number_float < static_cast < number_float_t > ( rhs . m_value . number_integer ) ;
}
else if ( lhs_type = = value_t : : number_unsigned and rhs_type = = value_t : : number_float )
{
return static_cast < number_float_t > ( lhs . m_value . number_unsigned ) < rhs . m_value . number_float ;
}
else if ( lhs_type = = value_t : : number_float and rhs_type = = value_t : : number_unsigned )
{
return lhs . m_value . number_float < static_cast < number_float_t > ( rhs . m_value . number_unsigned ) ;
}
else if ( lhs_type = = value_t : : number_integer and rhs_type = = value_t : : number_unsigned )
{
return lhs . m_value . number_integer < static_cast < number_integer_t > ( rhs . m_value . number_unsigned ) ;
}
else if ( lhs_type = = value_t : : number_unsigned and rhs_type = = value_t : : number_integer )
{
return static_cast < number_integer_t > ( lhs . m_value . number_unsigned ) < rhs . m_value . number_integer ;
}
// We only reach this line if we cannot compare values. In that case,
// we compare types. Note we have to call the operator explicitly,
// because MSVC has problems otherwise.
return operator < ( lhs_type , rhs_type ) ;
}
/*!
@ brief comparison : less than
@ copydoc operator < ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator < ( const_reference lhs , const ScalarType rhs ) noexcept
{
return ( lhs < basic_json ( rhs ) ) ;
}
/*!
@ brief comparison : less than
@ copydoc operator < ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator < ( const ScalarType lhs , const_reference rhs ) noexcept
{
return ( basic_json ( lhs ) < rhs ) ;
}
/*!
@ brief comparison : less than or equal
Compares whether one JSON value @ a lhs is less than or equal to another
JSON value by calculating ` not ( rhs < lhs ) ` .
@ param [ in ] lhs first JSON value to consider
@ param [ in ] rhs second JSON value to consider
@ return whether @ a lhs is less than or equal to @ a rhs
@ complexity Linear .
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ liveexample { The example demonstrates comparing several JSON
types . , operator__greater }
@ since version 1.0 .0
*/
friend bool operator < = ( const_reference lhs , const_reference rhs ) noexcept
{
return not ( rhs < lhs ) ;
}
/*!
@ brief comparison : less than or equal
@ copydoc operator < = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator < = ( const_reference lhs , const ScalarType rhs ) noexcept
{
return ( lhs < = basic_json ( rhs ) ) ;
}
/*!
@ brief comparison : less than or equal
@ copydoc operator < = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator < = ( const ScalarType lhs , const_reference rhs ) noexcept
{
return ( basic_json ( lhs ) < = rhs ) ;
}
/*!
@ brief comparison : greater than
Compares whether one JSON value @ a lhs is greater than another
JSON value by calculating ` not ( lhs < = rhs ) ` .
@ param [ in ] lhs first JSON value to consider
@ param [ in ] rhs second JSON value to consider
@ return whether @ a lhs is greater than to @ a rhs
@ complexity Linear .
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ liveexample { The example demonstrates comparing several JSON
types . , operator__lessequal }
@ since version 1.0 .0
*/
friend bool operator > ( const_reference lhs , const_reference rhs ) noexcept
{
return not ( lhs < = rhs ) ;
}
/*!
@ brief comparison : greater than
@ copydoc operator > ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator > ( const_reference lhs , const ScalarType rhs ) noexcept
{
return ( lhs > basic_json ( rhs ) ) ;
}
/*!
@ brief comparison : greater than
@ copydoc operator > ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator > ( const ScalarType lhs , const_reference rhs ) noexcept
{
return ( basic_json ( lhs ) > rhs ) ;
}
/*!
@ brief comparison : greater than or equal
Compares whether one JSON value @ a lhs is greater than or equal to another
JSON value by calculating ` not ( lhs < rhs ) ` .
@ param [ in ] lhs first JSON value to consider
@ param [ in ] rhs second JSON value to consider
@ return whether @ a lhs is greater than or equal to @ a rhs
@ complexity Linear .
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ liveexample { The example demonstrates comparing several JSON
types . , operator__greaterequal }
@ since version 1.0 .0
*/
friend bool operator > = ( const_reference lhs , const_reference rhs ) noexcept
{
return not ( lhs < rhs ) ;
}
/*!
@ brief comparison : greater than or equal
@ copydoc operator > = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator > = ( const_reference lhs , const ScalarType rhs ) noexcept
{
return ( lhs > = basic_json ( rhs ) ) ;
}
/*!
@ brief comparison : greater than or equal
@ copydoc operator > = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
friend bool operator > = ( const ScalarType lhs , const_reference rhs ) noexcept
{
return ( basic_json ( lhs ) > = rhs ) ;
}
/// @}
///////////////////
// serialization //
///////////////////
/// @name serialization
/// @{
/*!
@ brief serialize to stream
Serialize the given JSON value @ a j to the output stream @ a o . The JSON
value will be serialized using the @ ref dump member function .
- The indentation of the output can be controlled with the member variable
` width ` of the output stream @ a o . For instance , using the manipulator
` std : : setw ( 4 ) ` on @ a o sets the indentation level to ` 4 ` and the
serialization result is the same as calling ` dump ( 4 ) ` .
- The indentation character can be controlled with the member variable
` fill ` of the output stream @ a o . For instance , the manipulator
` std : : setfill ( ' \ \ t ' ) ` sets indentation to use a tab character rather than
the default space character .
@ param [ in , out ] o stream to serialize to
@ param [ in ] j JSON value to serialize
@ return the stream @ a o
@ throw type_error .316 if a string stored inside the JSON value is not
UTF - 8 encoded
@ complexity Linear .
@ liveexample { The example below shows the serialization with different
parameters to ` width ` to adjust the indentation level . , operator_serialize }
@ since version 1.0 .0 ; indentation character added in version 3.0 .0
*/
friend std : : ostream & operator < < ( std : : ostream & o , const basic_json & j )
{
// read width member and use it as indentation parameter if nonzero
const bool pretty_print = ( o . width ( ) > 0 ) ;
const auto indentation = ( pretty_print ? o . width ( ) : 0 ) ;
// reset width to 0 for subsequent calls to this stream
o . width ( 0 ) ;
// do the actual serialization
serializer s ( detail : : output_adapter < char > ( o ) , o . fill ( ) ) ;
s . dump ( j , pretty_print , false , static_cast < unsigned int > ( indentation ) ) ;
return o ;
}
/*!
@ brief serialize to stream
2018-01-23 23:33:08 +08:00
@ deprecated This stream operator is deprecated and will be removed in
future 4.0 .0 of the library . Please use
2018-01-10 01:30:02 +08:00
@ ref operator < < ( std : : ostream & , const basic_json & )
instead ; that is , replace calls like ` j > > o ; ` with ` o < < j ; ` .
@ since version 1.0 .0 ; deprecated since version 3.0 .0
*/
JSON_DEPRECATED
friend std : : ostream & operator > > ( const basic_json & j , std : : ostream & o )
{
return o < < j ;
}
/// @}
/////////////////////
// deserialization //
/////////////////////
/// @name deserialization
/// @{
/*!
@ brief deserialize from a compatible input
This function reads from a compatible input . Examples are :
- an array of 1 - byte values
- strings with character / literal type with size of 1 byte
- input streams
- container with contiguous storage of 1 - byte values . Compatible container
types include ` std : : vector ` , ` std : : string ` , ` std : : array ` ,
` std : : valarray ` , and ` std : : initializer_list ` . Furthermore , C - style
arrays can be used with ` std : : begin ( ) ` / ` std : : end ( ) ` . User - defined
containers can be used as long as they implement random - access iterators
and a contiguous storage .
@ pre Each element of the container has a size of 1 byte . Violating this
precondition yields undefined behavior . * * This precondition is enforced
with a static assertion . * *
@ pre The container storage is contiguous . Violating this precondition
yields undefined behavior . * * This precondition is enforced with an
assertion . * *
@ pre Each element of the container has a size of 1 byte . Violating this
precondition yields undefined behavior . * * This precondition is enforced
with a static assertion . * *
@ warning There is no way to enforce all preconditions at compile - time . If
the function is called with a noncompliant container and with
assertions switched off , the behavior is undefined and will most
likely yield segmentation violation .
@ param [ in ] i input to read from
@ param [ in ] cb a parser callback function of type @ ref parser_callback_t
which is used to control the deserialization by filtering unwanted values
( optional )
2018-10-08 03:30:58 +08:00
@ param [ in ] allow_exceptions whether to throw exceptions in case of a
parse error ( optional , true by default )
2018-01-10 01:30:02 +08:00
@ return result of the deserialization
@ throw parse_error .101 if a parse error occurs ; example : ` " " unexpected end
of input ; expected string literal " " `
@ throw parse_error .102 if to_unicode fails or surrogate error
@ throw parse_error .103 if to_unicode fails
@ complexity Linear in the length of the input . The parser is a predictive
LL ( 1 ) parser . The complexity can be higher if the parser callback function
@ a cb has a super - linear complexity .
@ note A UTF - 8 byte order mark is silently ignored .
@ liveexample { The example below demonstrates the ` parse ( ) ` function reading
from an array . , parse__array__parser_callback_t }
@ liveexample { The example below demonstrates the ` parse ( ) ` function with
and without callback function . , parse__string__parser_callback_t }
@ liveexample { The example below demonstrates the ` parse ( ) ` function with
and without callback function . , parse__istream__parser_callback_t }
@ liveexample { The example below demonstrates the ` parse ( ) ` function reading
from a contiguous container . , parse__contiguouscontainer__parser_callback_t }
@ since version 2.0 .3 ( contiguous containers )
*/
2018-03-21 05:39:08 +08:00
static basic_json parse ( detail : : input_adapter & & i ,
2018-01-10 01:30:02 +08:00
const parser_callback_t cb = nullptr ,
const bool allow_exceptions = true )
{
basic_json result ;
parser ( i , cb , allow_exceptions ) . parse ( true , result ) ;
return result ;
}
2018-03-21 05:39:08 +08:00
static bool accept ( detail : : input_adapter & & i )
2018-01-10 01:30:02 +08:00
{
return parser ( i ) . accept ( true ) ;
}
2018-08-18 18:00:14 +08:00
/*!
@ brief generate SAX events
The SAX event lister must follow the interface of @ ref json_sax .
This function reads from a compatible input . Examples are :
- an array of 1 - byte values
- strings with character / literal type with size of 1 byte
- input streams
- container with contiguous storage of 1 - byte values . Compatible container
types include ` std : : vector ` , ` std : : string ` , ` std : : array ` ,
` std : : valarray ` , and ` std : : initializer_list ` . Furthermore , C - style
arrays can be used with ` std : : begin ( ) ` / ` std : : end ( ) ` . User - defined
containers can be used as long as they implement random - access iterators
and a contiguous storage .
@ pre Each element of the container has a size of 1 byte . Violating this
precondition yields undefined behavior . * * This precondition is enforced
with a static assertion . * *
@ pre The container storage is contiguous . Violating this precondition
yields undefined behavior . * * This precondition is enforced with an
assertion . * *
@ pre Each element of the container has a size of 1 byte . Violating this
precondition yields undefined behavior . * * This precondition is enforced
with a static assertion . * *
@ warning There is no way to enforce all preconditions at compile - time . If
the function is called with a noncompliant container and with
assertions switched off , the behavior is undefined and will most
likely yield segmentation violation .
@ param [ in ] i input to read from
@ param [ in , out ] sax SAX event listener
@ param [ in ] format the format to parse ( JSON , CBOR , MessagePack , or UBJSON )
@ param [ in ] strict whether the input has to be consumed completely
@ return return value of the last processed SAX event
@ throw parse_error .101 if a parse error occurs ; example : ` " " unexpected end
of input ; expected string literal " " `
@ throw parse_error .102 if to_unicode fails or surrogate error
@ throw parse_error .103 if to_unicode fails
@ complexity Linear in the length of the input . The parser is a predictive
LL ( 1 ) parser . The complexity can be higher if the SAX consumer @ a sax has
a super - linear complexity .
@ note A UTF - 8 byte order mark is silently ignored .
2018-08-18 21:42:18 +08:00
@ liveexample { The example below demonstrates the ` sax_parse ( ) ` function
reading from string and processing the events with a user - defined SAX
event consumer . , sax_parse }
2018-08-18 18:00:14 +08:00
@ since version 3.2 .0
*/
2018-07-02 16:14:37 +08:00
template < typename SAX >
static bool sax_parse ( detail : : input_adapter & & i , SAX * sax ,
2018-03-21 05:39:08 +08:00
input_format_t format = input_format_t : : json ,
const bool strict = true )
2018-01-10 01:30:02 +08:00
{
2018-03-21 05:39:08 +08:00
assert ( sax ) ;
switch ( format )
{
case input_format_t : : json :
return parser ( std : : move ( i ) ) . sax_parse ( sax , strict ) ;
default :
2018-07-02 16:14:37 +08:00
return detail : : binary_reader < basic_json , SAX > ( std : : move ( i ) ) . sax_parse ( format , sax , strict ) ;
2018-03-21 05:39:08 +08:00
}
2018-02-25 01:04:07 +08:00
}
2018-01-10 01:30:02 +08:00
/*!
@ brief deserialize from an iterator range with contiguous storage
This function reads from an iterator range of a container with contiguous
storage of 1 - byte values . Compatible container types include
` std : : vector ` , ` std : : string ` , ` std : : array ` , ` std : : valarray ` , and
` std : : initializer_list ` . Furthermore , C - style arrays can be used with
` std : : begin ( ) ` / ` std : : end ( ) ` . User - defined containers can be used as long
as they implement random - access iterators and a contiguous storage .
@ pre The iterator range is contiguous . Violating this precondition yields
undefined behavior . * * This precondition is enforced with an assertion . * *
@ pre Each element in the range has a size of 1 byte . Violating this
precondition yields undefined behavior . * * This precondition is enforced
with a static assertion . * *
@ warning There is no way to enforce all preconditions at compile - time . If
the function is called with noncompliant iterators and with
assertions switched off , the behavior is undefined and will most
likely yield segmentation violation .
@ tparam IteratorType iterator of container with contiguous storage
@ param [ in ] first begin of the range to parse ( included )
@ param [ in ] last end of the range to parse ( excluded )
@ param [ in ] cb a parser callback function of type @ ref parser_callback_t
which is used to control the deserialization by filtering unwanted values
( optional )
@ param [ in ] allow_exceptions whether to throw exceptions in case of a
parse error ( optional , true by default )
@ return result of the deserialization
@ throw parse_error .101 in case of an unexpected token
@ throw parse_error .102 if to_unicode fails or surrogate error
@ throw parse_error .103 if to_unicode fails
@ complexity Linear in the length of the input . The parser is a predictive
LL ( 1 ) parser . The complexity can be higher if the parser callback function
@ a cb has a super - linear complexity .
@ note A UTF - 8 byte order mark is silently ignored .
@ liveexample { The example below demonstrates the ` parse ( ) ` function reading
from an iterator range . , parse__iteratortype__parser_callback_t }
@ since version 2.0 .3
*/
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 ,
const bool allow_exceptions = true )
{
basic_json result ;
parser ( detail : : input_adapter ( first , last ) , cb , allow_exceptions ) . parse ( true , result ) ;
return result ;
}
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 bool accept ( IteratorType first , IteratorType last )
{
return parser ( detail : : input_adapter ( first , last ) ) . accept ( true ) ;
}
2018-07-02 16:14:37 +08:00
template < class IteratorType , class SAX , typename std : : enable_if <
2018-02-25 01:04:07 +08:00
std : : is_base_of <
std : : random_access_iterator_tag ,
typename std : : iterator_traits < IteratorType > : : iterator_category > : : value , int > : : type = 0 >
2018-07-02 16:14:37 +08:00
static bool sax_parse ( IteratorType first , IteratorType last , SAX * sax )
2018-02-25 01:04:07 +08:00
{
2018-03-07 01:17:07 +08:00
return parser ( detail : : input_adapter ( first , last ) ) . sax_parse ( sax ) ;
2018-02-25 01:04:07 +08:00
}
2018-01-10 01:30:02 +08:00
/*!
@ brief deserialize from stream
2018-01-23 23:33:08 +08:00
@ deprecated This stream operator is deprecated and will be removed in
version 4.0 .0 of the library . Please use
2018-01-10 01:30:02 +08:00
@ ref operator > > ( std : : istream & , basic_json & )
instead ; that is , replace calls like ` j < < i ; ` with ` i > > j ; ` .
@ since version 1.0 .0 ; deprecated since version 3.0 .0
*/
JSON_DEPRECATED
friend std : : istream & operator < < ( basic_json & j , std : : istream & i )
{
return operator > > ( i , j ) ;
}
/*!
@ brief deserialize from stream
Deserializes an input stream to a JSON value .
@ param [ in , out ] i input stream to read a serialized JSON value from
@ param [ in , out ] j JSON value to write the deserialized input to
@ throw parse_error .101 in case of an unexpected token
@ throw parse_error .102 if to_unicode fails or surrogate error
@ throw parse_error .103 if to_unicode fails
@ complexity Linear in the length of the input . The parser is a predictive
LL ( 1 ) parser .
@ note A UTF - 8 byte order mark is silently ignored .
@ liveexample { The example below shows how a JSON value is constructed by
reading a serialization from a stream . , operator_deserialize }
@ sa parse ( std : : istream & , const parser_callback_t ) for a variant with a
parser callback function to filter values while parsing
@ since version 1.0 .0
*/
friend std : : istream & operator > > ( std : : istream & i , basic_json & j )
{
parser ( detail : : input_adapter ( i ) ) . parse ( false , j ) ;
return i ;
}
/// @}
///////////////////////////
// convenience functions //
///////////////////////////
/*!
@ brief return the type as string
Returns the type name as string to be used in error messages - usually to
indicate that a function was called on a wrong JSON type .
@ return a string representation of a the @ a m_type member :
Value type | return value
- - - - - - - - - - - | - - - - - - - - - - - - -
null | ` " null " `
boolean | ` " boolean " `
string | ` " string " `
number | ` " number " ` ( for all number types )
object | ` " object " `
array | ` " array " `
discarded | ` " discarded " `
@ exceptionsafety No - throw guarantee : this function never throws exceptions .
@ complexity Constant .
@ liveexample { The following code exemplifies ` type_name ( ) ` for all JSON
types . , type_name }
@ sa @ ref type ( ) - - return the type of the JSON value
@ sa @ ref operator value_t ( ) - - return the type of the JSON value ( implicit )
@ since version 1.0 .0 , public since 2.1 .0 , ` const char * ` and ` noexcept `
since 3.0 .0
*/
const char * type_name ( ) const noexcept
{
{
switch ( m_type )
{
case value_t : : null :
return " null " ;
case value_t : : object :
return " object " ;
case value_t : : array :
return " array " ;
case value_t : : string :
return " string " ;
case value_t : : boolean :
return " boolean " ;
case value_t : : discarded :
return " discarded " ;
default :
return " number " ;
}
}
}
private :
//////////////////////
// member variables //
//////////////////////
/// the type of the current element
value_t m_type = value_t : : null ;
/// the value of the current element
json_value m_value = { } ;
//////////////////////////////////////////
// binary serialization/deserialization //
//////////////////////////////////////////
/// @name binary serialization/deserialization support
/// @{
public :
/*!
@ brief create a CBOR serialization of a given JSON value
Serializes a given JSON value @ a j to a byte vector using the CBOR ( Concise
Binary Object Representation ) serialization format . CBOR is a binary
serialization format which aims to be more compact than JSON itself , yet
more efficient to parse .
The library uses the following mapping from JSON values types to
CBOR types according to the CBOR specification ( RFC 7049 ) :
JSON value type | value / range | CBOR type | first byte
- - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - -
null | ` null ` | Null | 0xF6
boolean | ` true ` | True | 0xF5
boolean | ` false ` | False | 0xF4
number_integer | - 9223372036854775808. . - 2147483649 | Negative integer ( 8 bytes follow ) | 0x3B
number_integer | - 2147483648. . - 32769 | Negative integer ( 4 bytes follow ) | 0x3A
number_integer | - 32768. . - 129 | Negative integer ( 2 bytes follow ) | 0x39
number_integer | - 128. . - 25 | Negative integer ( 1 byte follow ) | 0x38
number_integer | - 24. . - 1 | Negative integer | 0x20 . .0 x37
number_integer | 0. .23 | Integer | 0x00 . .0 x17
number_integer | 24. .255 | Unsigned integer ( 1 byte follow ) | 0x18
number_integer | 256. .65535 | Unsigned integer ( 2 bytes follow ) | 0x19
number_integer | 65536. .4294967295 | Unsigned integer ( 4 bytes follow ) | 0x1A
number_integer | 4294967296. .18446744073709551615 | Unsigned integer ( 8 bytes follow ) | 0x1B
number_unsigned | 0. .23 | Integer | 0x00 . .0 x17
number_unsigned | 24. .255 | Unsigned integer ( 1 byte follow ) | 0x18
number_unsigned | 256. .65535 | Unsigned integer ( 2 bytes follow ) | 0x19
number_unsigned | 65536. .4294967295 | Unsigned integer ( 4 bytes follow ) | 0x1A
number_unsigned | 4294967296. .18446744073709551615 | Unsigned integer ( 8 bytes follow ) | 0x1B
number_float | * any value * | Double - Precision Float | 0xFB
string | * length * : 0. .23 | UTF - 8 string | 0x60 . .0 x77
string | * length * : 23. .255 | UTF - 8 string ( 1 byte follow ) | 0x78
string | * length * : 256. .65535 | UTF - 8 string ( 2 bytes follow ) | 0x79
string | * length * : 65536. .4294967295 | UTF - 8 string ( 4 bytes follow ) | 0x7A
string | * length * : 4294967296. .18446744073709551615 | UTF - 8 string ( 8 bytes follow ) | 0x7B
array | * size * : 0. .23 | array | 0x80 . .0 x97
array | * size * : 23. .255 | array ( 1 byte follow ) | 0x98
array | * size * : 256. .65535 | array ( 2 bytes follow ) | 0x99
array | * size * : 65536. .4294967295 | array ( 4 bytes follow ) | 0x9A
array | * size * : 4294967296. .18446744073709551615 | array ( 8 bytes follow ) | 0x9B
object | * size * : 0. .23 | map | 0xA0 . .0 xB7
object | * size * : 23. .255 | map ( 1 byte follow ) | 0xB8
object | * size * : 256. .65535 | map ( 2 bytes follow ) | 0xB9
object | * size * : 65536. .4294967295 | map ( 4 bytes follow ) | 0xBA
object | * size * : 4294967296. .18446744073709551615 | map ( 8 bytes follow ) | 0xBB
@ note The mapping is * * complete * * in the sense that any JSON value type
can be converted to a CBOR value .
@ note If NaN or Infinity are stored inside a JSON number , they are
serialized properly . This behavior differs from the @ ref dump ( )
function which serializes NaN or Infinity to ` null ` .
@ note The following CBOR types are not used in the conversion :
- byte strings ( 0x40 . .0 x5F )
- UTF - 8 strings terminated by " break " ( 0x7F )
- arrays terminated by " break " ( 0x9F )
- maps terminated by " break " ( 0xBF )
- date / time ( 0xC0 . .0 xC1 )
- bignum ( 0xC2 . .0 xC3 )
- decimal fraction ( 0xC4 )
- bigfloat ( 0xC5 )
- tagged items ( 0xC6 . .0 xD4 , 0xD8 . .0 xDB )
- expected conversions ( 0xD5 . .0 xD7 )
- simple values ( 0xE0 . .0 xF3 , 0xF8 )
- undefined ( 0xF7 )
- half and single - precision floats ( 0xF9 - 0xFA )
- break ( 0xFF )
@ param [ in ] j JSON value to serialize
@ return MessagePack serialization as byte vector
@ complexity Linear in the size of the JSON value @ a j .
@ liveexample { The example shows the serialization of a JSON value to a byte
vector in CBOR format . , to_cbor }
@ sa http : //cbor.io
2018-10-08 03:30:58 +08:00
@ sa @ ref from_cbor ( detail : : input_adapter & & , const bool , const bool ) for the
2018-01-10 01:30:02 +08:00
analogous deserialization
@ sa @ ref to_msgpack ( const basic_json & ) for the related MessagePack format
2018-01-23 06:23:17 +08:00
@ sa @ ref to_ubjson ( const basic_json & , const bool , const bool ) for the
related UBJSON format
2018-01-10 01:30:02 +08:00
@ since version 2.0 .9
*/
static std : : vector < uint8_t > to_cbor ( const basic_json & j )
{
std : : vector < uint8_t > result ;
to_cbor ( j , result ) ;
return result ;
}
static void to_cbor ( const basic_json & j , detail : : output_adapter < uint8_t > o )
{
binary_writer < uint8_t > ( o ) . write_cbor ( j ) ;
}
static void to_cbor ( const basic_json & j , detail : : output_adapter < char > o )
{
binary_writer < char > ( o ) . write_cbor ( j ) ;
}
/*!
@ brief create a MessagePack serialization of a given JSON value
Serializes a given JSON value @ a j to a byte vector using the MessagePack
serialization format . MessagePack is a binary serialization format which
aims to be more compact than JSON itself , yet more efficient to parse .
The library uses the following mapping from JSON values types to
MessagePack types according to the MessagePack specification :
JSON value type | value / range | MessagePack type | first byte
- - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - | - - - - - - - - - -
null | ` null ` | nil | 0xC0
boolean | ` true ` | true | 0xC3
boolean | ` false ` | false | 0xC2
number_integer | - 9223372036854775808. . - 2147483649 | int64 | 0xD3
number_integer | - 2147483648. . - 32769 | int32 | 0xD2
number_integer | - 32768. . - 129 | int16 | 0xD1
number_integer | - 128. . - 33 | int8 | 0xD0
number_integer | - 32. . - 1 | negative fixint | 0xE0 . .0 xFF
number_integer | 0. .127 | positive fixint | 0x00 . .0 x7F
number_integer | 128. .255 | uint 8 | 0xCC
number_integer | 256. .65535 | uint 16 | 0xCD
number_integer | 65536. .4294967295 | uint 32 | 0xCE
number_integer | 4294967296. .18446744073709551615 | uint 64 | 0xCF
number_unsigned | 0. .127 | positive fixint | 0x00 . .0 x7F
number_unsigned | 128. .255 | uint 8 | 0xCC
number_unsigned | 256. .65535 | uint 16 | 0xCD
number_unsigned | 65536. .4294967295 | uint 32 | 0xCE
number_unsigned | 4294967296. .18446744073709551615 | uint 64 | 0xCF
number_float | * any value * | float 64 | 0xCB
string | * length * : 0. .31 | fixstr | 0xA0 . .0 xBF
string | * length * : 32. .255 | str 8 | 0xD9
string | * length * : 256. .65535 | str 16 | 0xDA
string | * length * : 65536. .4294967295 | str 32 | 0xDB
array | * size * : 0. .15 | fixarray | 0x90 . .0 x9F
array | * size * : 16. .65535 | array 16 | 0xDC
array | * size * : 65536. .4294967295 | array 32 | 0xDD
object | * size * : 0. .15 | fix map | 0x80 . .0 x8F
object | * size * : 16. .65535 | map 16 | 0xDE
object | * size * : 65536. .4294967295 | map 32 | 0xDF
@ note The mapping is * * complete * * in the sense that any JSON value type
can be converted to a MessagePack value .
@ note The following values can * * not * * be converted to a MessagePack value :
- strings with more than 4294967295 bytes
- arrays with more than 4294967295 elements
- objects with more than 4294967295 elements
@ note The following MessagePack types are not used in the conversion :
- bin 8 - bin 32 ( 0xC4 . .0 xC6 )
- ext 8 - ext 32 ( 0xC7 . .0 xC9 )
- float 32 ( 0xCA )
- fixext 1 - fixext 16 ( 0xD4 . .0 xD8 )
@ note Any MessagePack output created @ ref to_msgpack can be successfully
parsed by @ ref from_msgpack .
@ note If NaN or Infinity are stored inside a JSON number , they are
serialized properly . This behavior differs from the @ ref dump ( )
function which serializes NaN or Infinity to ` null ` .
@ param [ in ] j JSON value to serialize
@ return MessagePack serialization as byte vector
@ complexity Linear in the size of the JSON value @ a j .
@ liveexample { The example shows the serialization of a JSON value to a byte
vector in MessagePack format . , to_msgpack }
@ sa http : //msgpack.org
2018-10-08 03:30:58 +08:00
@ sa @ ref from_msgpack for the analogous deserialization
2018-01-10 01:30:02 +08:00
@ sa @ ref to_cbor ( const basic_json & for the related CBOR format
2018-01-23 06:23:17 +08:00
@ sa @ ref to_ubjson ( const basic_json & , const bool , const bool ) for the
related UBJSON format
2018-01-10 01:30:02 +08:00
@ since version 2.0 .9
*/
static std : : vector < uint8_t > to_msgpack ( const basic_json & j )
{
std : : vector < uint8_t > result ;
to_msgpack ( j , result ) ;
return result ;
}
static void to_msgpack ( const basic_json & j , detail : : output_adapter < uint8_t > o )
{
binary_writer < uint8_t > ( o ) . write_msgpack ( j ) ;
}
static void to_msgpack ( const basic_json & j , detail : : output_adapter < char > o )
{
binary_writer < char > ( o ) . write_msgpack ( j ) ;
}
2018-01-23 06:23:17 +08:00
/*!
@ brief create a UBJSON serialization of a given JSON value
Serializes a given JSON value @ a j to a byte vector using the UBJSON
( Universal Binary JSON ) serialization format . UBJSON aims to be more compact
than JSON itself , yet more efficient to parse .
The library uses the following mapping from JSON values types to
UBJSON types according to the UBJSON specification :
JSON value type | value / range | UBJSON type | marker
- - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - | - - - - - -
null | ` null ` | null | ` Z `
boolean | ` true ` | true | ` T `
boolean | ` false ` | false | ` F `
number_integer | - 9223372036854775808. . - 2147483649 | int64 | ` L `
number_integer | - 2147483648. . - 32769 | int32 | ` l `
number_integer | - 32768. . - 129 | int16 | ` I `
number_integer | - 128. .127 | int8 | ` i `
number_integer | 128. .255 | uint8 | ` U `
number_integer | 256. .32767 | int16 | ` I `
number_integer | 32768. .2147483647 | int32 | ` l `
number_integer | 2147483648. .9223372036854775807 | int64 | ` L `
number_unsigned | 0. .127 | int8 | ` i `
number_unsigned | 128. .255 | uint8 | ` U `
number_unsigned | 256. .32767 | int16 | ` I `
number_unsigned | 32768. .2147483647 | int32 | ` l `
number_unsigned | 2147483648. .9223372036854775807 | int64 | ` L `
number_float | * any value * | float64 | ` D `
string | * with shortest length indicator * | string | ` S `
array | * see notes on optimized format * | array | ` [ `
object | * see notes on optimized format * | map | ` { `
@ note The mapping is * * complete * * in the sense that any JSON value type
can be converted to a UBJSON value .
@ note The following values can * * not * * be converted to a UBJSON value :
- strings with more than 9223372036854775807 bytes ( theoretical )
- unsigned integer numbers above 9223372036854775807
@ note The following markers are not used in the conversion :
- ` Z ` : no - op values are not created .
- ` C ` : single - byte strings are serialized with ` S ` markers .
@ note Any UBJSON output created @ ref to_ubjson can be successfully parsed
by @ ref from_ubjson .
@ note If NaN or Infinity are stored inside a JSON number , they are
serialized properly . This behavior differs from the @ ref dump ( )
function which serializes NaN or Infinity to ` null ` .
@ note The optimized formats for containers are supported : Parameter
@ a use_size adds size information to the beginning of a container and
removes the closing marker . Parameter @ a use_type further checks
whether all elements of a container have the same type and adds the
type marker to the beginning of the container . The @ a use_type
parameter must only be used together with @ a use_size = true . Note
that @ a use_size = true alone may result in larger representations -
the benefit of this parameter is that the receiving side is
immediately informed on the number of elements of the container .
@ param [ in ] j JSON value to serialize
@ param [ in ] use_size whether to add size annotations to container types
@ param [ in ] use_type whether to add type annotations to container types
( must be combined with @ a use_size = true )
@ return UBJSON serialization as byte vector
@ complexity Linear in the size of the JSON value @ a j .
@ liveexample { The example shows the serialization of a JSON value to a byte
vector in UBJSON format . , to_ubjson }
@ sa http : //ubjson.org
2018-10-08 03:30:58 +08:00
@ sa @ ref from_ubjson ( detail : : input_adapter & & , const bool , const bool ) for the
2018-01-23 06:23:17 +08:00
analogous deserialization
@ sa @ ref to_cbor ( const basic_json & for the related CBOR format
@ sa @ ref to_msgpack ( const basic_json & ) for the related MessagePack format
@ since version 3.1 .0
*/
2018-01-14 17:27:30 +08:00
static std : : vector < uint8_t > to_ubjson ( const basic_json & j ,
2018-01-23 06:23:17 +08:00
const bool use_size = false ,
const bool use_type = false )
2018-01-14 17:27:30 +08:00
{
std : : vector < uint8_t > result ;
to_ubjson ( j , result , use_size , use_type ) ;
return result ;
}
static void to_ubjson ( const basic_json & j , detail : : output_adapter < uint8_t > o ,
const bool use_size = false , const bool use_type = false )
{
binary_writer < uint8_t > ( o ) . write_ubjson ( j , use_size , use_type ) ;
}
static void to_ubjson ( const basic_json & j , detail : : output_adapter < char > o ,
const bool use_size = false , const bool use_type = false )
{
binary_writer < char > ( o ) . write_ubjson ( j , use_size , use_type ) ;
}
2018-09-15 04:58:22 +08:00
2018-10-07 13:52:12 +08:00
/*!
@ brief Serializes the given JSON object ` j ` to BSON and returns a vector
containing the corresponding BSON - representation .
2018-10-07 23:57:13 +08:00
BSON ( Binary JSON ) is a binary format in which zero or more ordered key / value pairs are
stored as a single entity ( a so - called document ) .
The library uses the following mapping from JSON values types to BSON types :
JSON value type | value / range | BSON type | marker
- - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - | - - - - - -
null | ` null ` | null | 0x0A
boolean | ` true ` , ` false ` | boolean | 0x08
number_integer | - 9223372036854775808. . - 2147483649 | int64 | 0x12
number_integer | - 2147483648. .2147483647 | int32 | 0x10
number_integer | 2147483648. .9223372036854775807 | int64 | 0x12
number_unsigned | 0. .2147483647 | int32 | 0x10
number_unsigned | 2147483648. .9223372036854775807 | int64 | 0x12
2018-10-17 01:29:42 +08:00
number_unsigned | 9223372036854775808. .18446744073709551615 | - - | - -
2018-10-07 23:57:13 +08:00
number_float | * any value * | double | 0x01
string | * any value * | string | 0x02
array | * any value * | document | 0x04
object | * any value * | document | 0x03
@ warning The mapping is * * incomplete * * , since only JSON - objects ( and things
contained therein ) can be serialized to BSON .
2018-10-17 02:42:00 +08:00
Also , integers larger than 9223372036854775807 cannot be serialized to BSON ,
and the keys may not contain U + 0000 , since they are serialized a
zero - terminated c - strings .
2018-10-07 23:57:13 +08:00
2018-10-17 01:29:42 +08:00
@ throw out_of_range .407 if ` j . is_number_unsigned ( ) & & j . get < std : : uint64_t > ( ) > 9223372036854775807 `
2018-10-17 02:42:00 +08:00
@ throw out_of_range .409 if a key in ` j ` contains a NULL ( U + 0000 )
2018-10-17 01:29:42 +08:00
@ throw type_error .317 if ` ! j . is_object ( ) `
@ pre The input ` j ` is required to be an object : ` j . is_object ( ) = = true ` .
2018-10-07 23:57:13 +08:00
@ note Any BSON output created via @ ref to_bson can be successfully parsed
by @ ref from_bson .
@ param [ in ] j JSON value to serialize
@ return BSON serialization as byte vector
@ complexity Linear in the size of the JSON value @ a j .
2018-10-28 22:09:26 +08:00
@ liveexample { The example shows the serialization of a JSON value to a byte
vector in BSON format . , to_bson }
2018-10-07 23:57:13 +08:00
@ sa http : //bsonspec.org/spec.html
2018-10-28 16:15:41 +08:00
@ sa @ ref from_bson ( detail : : input_adapter & & , const bool strict ) for the
2018-10-07 23:57:13 +08:00
analogous deserialization
2018-10-28 16:15:41 +08:00
@ sa @ ref to_ubjson ( const basic_json & , const bool , const bool ) for the
related UBJSON format
2018-10-07 23:57:13 +08:00
@ sa @ ref to_cbor ( const basic_json & ) for the related CBOR format
@ sa @ ref to_msgpack ( const basic_json & ) for the related MessagePack format
2018-10-07 13:52:12 +08:00
*/
2018-09-15 04:58:22 +08:00
static std : : vector < uint8_t > to_bson ( const basic_json & j )
{
std : : vector < uint8_t > result ;
to_bson ( j , result ) ;
return result ;
}
2018-10-07 13:52:12 +08:00
/*!
@ brief Serializes the given JSON object ` j ` to BSON and forwards the
corresponding BSON - representation to the given output_adapter ` o ` .
@ param j The JSON object to convert to BSON .
@ param o The output adapter that receives the binary BSON representation .
@ pre The input ` j ` shall be an object : ` j . is_object ( ) = = true `
2018-10-07 23:57:13 +08:00
@ sa @ ref to_bson ( const basic_json & )
2018-10-07 13:52:12 +08:00
*/
2018-09-15 04:58:22 +08:00
static void to_bson ( const basic_json & j , detail : : output_adapter < uint8_t > o )
{
binary_writer < uint8_t > ( o ) . write_bson ( j ) ;
}
2018-10-07 13:52:12 +08:00
/*!
@ copydoc to_bson ( const basic_json & , detail : : output_adapter < uint8_t > )
*/
2018-09-15 04:58:22 +08:00
static void to_bson ( const basic_json & j , detail : : output_adapter < char > o )
{
binary_writer < char > ( o ) . write_bson ( j ) ;
}
2018-01-10 01:30:02 +08:00
/*!
@ brief create a JSON value from an input in CBOR format
Deserializes a given input @ a i to a JSON value using the CBOR ( Concise
Binary Object Representation ) serialization format .
The library maps CBOR types to JSON value types as follows :
CBOR type | JSON value type | first byte
- - - - - - - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - | - - - - - - - - - -
Integer | number_unsigned | 0x00 . .0 x17
Unsigned integer | number_unsigned | 0x18
Unsigned integer | number_unsigned | 0x19
Unsigned integer | number_unsigned | 0x1A
Unsigned integer | number_unsigned | 0x1B
Negative integer | number_integer | 0x20 . .0 x37
Negative integer | number_integer | 0x38
Negative integer | number_integer | 0x39
Negative integer | number_integer | 0x3A
Negative integer | number_integer | 0x3B
Negative integer | number_integer | 0x40 . .0 x57
UTF - 8 string | string | 0x60 . .0 x77
UTF - 8 string | string | 0x78
UTF - 8 string | string | 0x79
UTF - 8 string | string | 0x7A
UTF - 8 string | string | 0x7B
UTF - 8 string | string | 0x7F
array | array | 0x80 . .0 x97
array | array | 0x98
array | array | 0x99
array | array | 0x9A
array | array | 0x9B
array | array | 0x9F
map | object | 0xA0 . .0 xB7
map | object | 0xB8
map | object | 0xB9
map | object | 0xBA
map | object | 0xBB
map | object | 0xBF
False | ` false ` | 0xF4
True | ` true ` | 0xF5
2018-10-28 21:20:20 +08:00
Null | ` null ` | 0xF6
2018-01-10 01:30:02 +08:00
Half - Precision Float | number_float | 0xF9
Single - Precision Float | number_float | 0xFA
Double - Precision Float | number_float | 0xFB
@ warning The mapping is * * incomplete * * in the sense that not all CBOR
types can be converted to a JSON value . The following CBOR types
are not supported and will yield parse errors ( parse_error .112 ) :
- byte strings ( 0x40 . .0 x5F )
- date / time ( 0xC0 . .0 xC1 )
- bignum ( 0xC2 . .0 xC3 )
- decimal fraction ( 0xC4 )
- bigfloat ( 0xC5 )
- tagged items ( 0xC6 . .0 xD4 , 0xD8 . .0 xDB )
- expected conversions ( 0xD5 . .0 xD7 )
- simple values ( 0xE0 . .0 xF3 , 0xF8 )
- undefined ( 0xF7 )
@ warning CBOR allows map keys of any type , whereas JSON only allows
strings as keys in object values . Therefore , CBOR maps with keys
other than UTF - 8 strings are rejected ( parse_error .113 ) .
@ note Any CBOR output created @ ref to_cbor can be successfully parsed by
@ ref from_cbor .
@ param [ in ] i an input in CBOR format convertible to an input adapter
@ param [ in ] strict whether to expect the input to be consumed until EOF
( true by default )
2018-03-20 05:48:13 +08:00
@ param [ in ] allow_exceptions whether to throw exceptions in case of a
parse error ( optional , true by default )
2018-01-10 01:30:02 +08:00
@ return deserialized JSON value
@ throw parse_error .110 if the given input ends prematurely or the end of
file was not reached when @ a strict was set to true
@ throw parse_error .112 if unsupported features from CBOR were
used in the given input @ a v or if the input is not valid CBOR
@ throw parse_error .113 if a string was expected as map key , but not found
@ complexity Linear in the size of the input @ a i .
@ liveexample { The example shows the deserialization of a byte vector in CBOR
format to a JSON value . , from_cbor }
@ sa http : //cbor.io
@ sa @ ref to_cbor ( const basic_json & ) for the analogous serialization
2018-10-08 03:30:58 +08:00
@ sa @ ref from_msgpack ( detail : : input_adapter & & , const bool , const bool ) for the
2018-01-10 01:30:02 +08:00
related MessagePack format
2018-10-08 03:30:58 +08:00
@ sa @ ref from_ubjson ( detail : : input_adapter & & , const bool , const bool ) for the
2018-03-21 02:22:18 +08:00
related UBJSON format
2018-01-10 01:30:02 +08:00
@ since version 2.0 .9 ; parameter @ a start_index since 2.1 .1 ; changed to
consume input adapters , removed start_index parameter , and added
2018-10-08 03:30:58 +08:00
@ a strict parameter since 3.0 .0 ; added @ a allow_exceptions parameter
2018-03-21 02:22:18 +08:00
since 3.2 .0
2018-01-10 01:30:02 +08:00
*/
2018-03-21 05:39:08 +08:00
static basic_json from_cbor ( detail : : input_adapter & & i ,
2018-03-20 05:48:13 +08:00
const bool strict = true ,
const bool allow_exceptions = true )
2018-01-10 01:30:02 +08:00
{
2018-03-20 05:48:13 +08:00
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
2018-03-21 05:39:08 +08:00
const bool res = binary_reader ( detail : : input_adapter ( i ) ) . sax_parse ( input_format_t : : cbor , & sdp , strict ) ;
2018-03-20 05:48:13 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
2018-01-10 01:30:02 +08:00
}
/*!
2018-10-08 03:30:58 +08:00
@ copydoc from_cbor ( detail : : input_adapter & & , const bool , const bool )
2018-01-10 01:30:02 +08:00
*/
template < typename A1 , typename A2 ,
detail : : enable_if_t < std : : is_constructible < detail : : input_adapter , A1 , A2 > : : value , int > = 0 >
2018-03-20 05:48:13 +08:00
static basic_json from_cbor ( A1 & & a1 , A2 & & a2 ,
const bool strict = true ,
const bool allow_exceptions = true )
2018-01-10 01:30:02 +08:00
{
2018-03-20 05:48:13 +08:00
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
2018-03-21 05:39:08 +08:00
const bool res = binary_reader ( detail : : input_adapter ( std : : forward < A1 > ( a1 ) , std : : forward < A2 > ( a2 ) ) ) . sax_parse ( input_format_t : : cbor , & sdp , strict ) ;
2018-03-20 05:48:13 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief create a JSON value from an input in MessagePack format
Deserializes a given input @ a i to a JSON value using the MessagePack
serialization format .
The library maps MessagePack types to JSON value types as follows :
MessagePack type | JSON value type | first byte
- - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - | - - - - - - - - - -
positive fixint | number_unsigned | 0x00 . .0 x7F
fixmap | object | 0x80 . .0 x8F
fixarray | array | 0x90 . .0 x9F
fixstr | string | 0xA0 . .0 xBF
nil | ` null ` | 0xC0
false | ` false ` | 0xC2
true | ` true ` | 0xC3
float 32 | number_float | 0xCA
float 64 | number_float | 0xCB
uint 8 | number_unsigned | 0xCC
uint 16 | number_unsigned | 0xCD
uint 32 | number_unsigned | 0xCE
uint 64 | number_unsigned | 0xCF
int 8 | number_integer | 0xD0
int 16 | number_integer | 0xD1
int 32 | number_integer | 0xD2
int 64 | number_integer | 0xD3
str 8 | string | 0xD9
str 16 | string | 0xDA
str 32 | string | 0xDB
array 16 | array | 0xDC
array 32 | array | 0xDD
map 16 | object | 0xDE
map 32 | object | 0xDF
negative fixint | number_integer | 0xE0 - 0xFF
@ warning The mapping is * * incomplete * * in the sense that not all
MessagePack types can be converted to a JSON value . The following
MessagePack types are not supported and will yield parse errors :
- bin 8 - bin 32 ( 0xC4 . .0 xC6 )
- ext 8 - ext 32 ( 0xC7 . .0 xC9 )
- fixext 1 - fixext 16 ( 0xD4 . .0 xD8 )
@ note Any MessagePack output created @ ref to_msgpack can be successfully
parsed by @ ref from_msgpack .
@ param [ in ] i an input in MessagePack format convertible to an input
adapter
@ param [ in ] strict whether to expect the input to be consumed until EOF
( true by default )
2018-03-20 05:48:13 +08:00
@ param [ in ] allow_exceptions whether to throw exceptions in case of a
parse error ( optional , true by default )
@ return deserialized JSON value
2018-01-10 01:30:02 +08:00
@ throw parse_error .110 if the given input ends prematurely or the end of
file was not reached when @ a strict was set to true
@ throw parse_error .112 if unsupported features from MessagePack were
used in the given input @ a i or if the input is not valid MessagePack
@ throw parse_error .113 if a string was expected as map key , but not found
@ complexity Linear in the size of the input @ a i .
@ liveexample { The example shows the deserialization of a byte vector in
MessagePack format to a JSON value . , from_msgpack }
@ sa http : //msgpack.org
@ sa @ ref to_msgpack ( const basic_json & ) for the analogous serialization
2018-10-08 03:30:58 +08:00
@ sa @ ref from_cbor ( detail : : input_adapter & & , const bool , const bool ) for the
2018-03-21 02:22:18 +08:00
related CBOR format
2018-10-08 03:30:58 +08:00
@ sa @ ref from_ubjson ( detail : : input_adapter & & , const bool , const bool ) for
2018-03-21 02:22:18 +08:00
the related UBJSON format
2018-10-28 16:15:41 +08:00
@ sa @ ref from_bson ( detail : : input_adapter & & , const bool , const bool ) for
2018-10-07 13:52:12 +08:00
the related BSON format
2018-01-10 01:30:02 +08:00
@ since version 2.0 .9 ; parameter @ a start_index since 2.1 .1 ; changed to
consume input adapters , removed start_index parameter , and added
2018-10-08 03:30:58 +08:00
@ a strict parameter since 3.0 .0 ; added @ a allow_exceptions parameter
2018-03-21 02:22:18 +08:00
since 3.2 .0
2018-01-10 01:30:02 +08:00
*/
2018-03-21 05:39:08 +08:00
static basic_json from_msgpack ( detail : : input_adapter & & i ,
2018-03-20 05:48:13 +08:00
const bool strict = true ,
const bool allow_exceptions = true )
2018-01-10 01:30:02 +08:00
{
2018-03-20 05:48:13 +08:00
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
2018-03-21 05:39:08 +08:00
const bool res = binary_reader ( detail : : input_adapter ( i ) ) . sax_parse ( input_format_t : : msgpack , & sdp , strict ) ;
2018-03-20 05:48:13 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
2018-01-10 01:30:02 +08:00
}
/*!
2018-10-08 03:30:58 +08:00
@ copydoc from_msgpack ( detail : : input_adapter & & , const bool , const bool )
2018-01-10 01:30:02 +08:00
*/
template < typename A1 , typename A2 ,
detail : : enable_if_t < std : : is_constructible < detail : : input_adapter , A1 , A2 > : : value , int > = 0 >
2018-03-20 05:48:13 +08:00
static basic_json from_msgpack ( A1 & & a1 , A2 & & a2 ,
const bool strict = true ,
const bool allow_exceptions = true )
2018-01-10 01:30:02 +08:00
{
2018-03-20 05:48:13 +08:00
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
2018-03-21 05:39:08 +08:00
const bool res = binary_reader ( detail : : input_adapter ( std : : forward < A1 > ( a1 ) , std : : forward < A2 > ( a2 ) ) ) . sax_parse ( input_format_t : : msgpack , & sdp , strict ) ;
2018-03-20 05:48:13 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
2018-01-10 01:30:02 +08:00
}
2018-01-23 06:23:17 +08:00
/*!
@ brief create a JSON value from an input in UBJSON format
Deserializes a given input @ a i to a JSON value using the UBJSON ( Universal
Binary JSON ) serialization format .
The library maps UBJSON types to JSON value types as follows :
UBJSON type | JSON value type | marker
- - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | - - - - - -
no - op | * no value , next value is read * | ` N `
null | ` null ` | ` Z `
false | ` false ` | ` F `
true | ` true ` | ` T `
float32 | number_float | ` d `
float64 | number_float | ` D `
uint8 | number_unsigned | ` U `
int8 | number_integer | ` i `
int16 | number_integer | ` I `
int32 | number_integer | ` l `
int64 | number_integer | ` L `
string | string | ` S `
char | string | ` C `
array | array ( optimized values are supported ) | ` [ `
object | object ( optimized values are supported ) | ` { `
@ note The mapping is * * complete * * in the sense that any UBJSON value can
be converted to a JSON value .
@ param [ in ] i an input in UBJSON format convertible to an input adapter
@ param [ in ] strict whether to expect the input to be consumed until EOF
( true by default )
2018-03-20 05:48:13 +08:00
@ param [ in ] allow_exceptions whether to throw exceptions in case of a
parse error ( optional , true by default )
@ return deserialized JSON value
2018-01-23 06:23:17 +08:00
@ throw parse_error .110 if the given input ends prematurely or the end of
file was not reached when @ a strict was set to true
@ throw parse_error .112 if a parse error occurs
@ throw parse_error .113 if a string could not be parsed successfully
@ complexity Linear in the size of the input @ a i .
@ liveexample { The example shows the deserialization of a byte vector in
UBJSON format to a JSON value . , from_ubjson }
@ sa http : //ubjson.org
@ sa @ ref to_ubjson ( const basic_json & , const bool , const bool ) for the
analogous serialization
2018-10-08 03:30:58 +08:00
@ sa @ ref from_cbor ( detail : : input_adapter & & , const bool , const bool ) for the
2018-03-21 02:22:18 +08:00
related CBOR format
2018-10-08 03:30:58 +08:00
@ sa @ ref from_msgpack ( detail : : input_adapter & & , const bool , const bool ) for
2018-03-21 02:22:18 +08:00
the related MessagePack format
2018-10-28 16:15:41 +08:00
@ sa @ ref from_bson ( detail : : input_adapter & & , const bool , const bool ) for
2018-10-07 13:52:12 +08:00
the related BSON format
2018-01-23 06:23:17 +08:00
2018-10-08 03:30:58 +08:00
@ since version 3.1 .0 ; added @ a allow_exceptions parameter since 3.2 .0
2018-01-23 06:23:17 +08:00
*/
2018-03-21 05:39:08 +08:00
static basic_json from_ubjson ( detail : : input_adapter & & i ,
2018-03-20 05:48:13 +08:00
const bool strict = true ,
const bool allow_exceptions = true )
2018-01-14 17:27:30 +08:00
{
2018-03-20 05:48:13 +08:00
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
2018-03-21 05:39:08 +08:00
const bool res = binary_reader ( detail : : input_adapter ( i ) ) . sax_parse ( input_format_t : : ubjson , & sdp , strict ) ;
2018-03-20 05:48:13 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
2018-01-14 17:27:30 +08:00
}
2018-03-21 02:22:18 +08:00
/*!
2018-10-08 03:30:58 +08:00
@ copydoc from_ubjson ( detail : : input_adapter & & , const bool , const bool )
2018-03-21 02:22:18 +08:00
*/
2018-01-14 17:27:30 +08:00
template < typename A1 , typename A2 ,
detail : : enable_if_t < std : : is_constructible < detail : : input_adapter , A1 , A2 > : : value , int > = 0 >
2018-03-20 05:48:13 +08:00
static basic_json from_ubjson ( A1 & & a1 , A2 & & a2 ,
const bool strict = true ,
const bool allow_exceptions = true )
2018-01-14 17:27:30 +08:00
{
2018-03-20 05:48:13 +08:00
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
2018-03-21 05:39:08 +08:00
const bool res = binary_reader ( detail : : input_adapter ( std : : forward < A1 > ( a1 ) , std : : forward < A2 > ( a2 ) ) ) . sax_parse ( input_format_t : : ubjson , & sdp , strict ) ;
2018-03-20 05:48:13 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
2018-01-14 17:27:30 +08:00
}
2018-10-07 13:52:12 +08:00
/*!
@ brief Create a JSON value from an input in BSON format
Deserializes a given input @ a i to a JSON value using the BSON ( Binary JSON )
serialization format .
The library maps BSON record types to JSON value types as follows :
BSON type | BSON marker byte | JSON value type
- - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - | - - - - - - - - - - - - - - - - - - - - - - - - - - -
double | 0x01 | number_float
string | 0x02 | string
document | 0x03 | object
array | 0x04 | array
binary | 0x05 | still unsupported
undefined | 0x06 | still unsupported
ObjectId | 0x07 | still unsupported
boolean | 0x08 | boolean
UTC Date - Time | 0x09 | still unsupported
null | 0x0A | null
Regular Expr . | 0x0B | still unsupported
DB Pointer | 0x0C | still unsupported
JavaScript Code | 0x0D | still unsupported
Symbol | 0x0E | still unsupported
JavaScript Code | 0x0F | still unsupported
int32 | 0x10 | number_integer
Timestamp | 0x11 | still unsupported
128 - bit decimal float | 0x13 | still unsupported
Max Key | 0x7F | still unsupported
Min Key | 0xFF | still unsupported
@ warning The mapping is * * incomplete * * . The unsupported mappings
are indicated in the table above .
@ param [ in ] i an input in BSON format convertible to an input adapter
@ param [ in ] strict whether to expect the input to be consumed until EOF
( true by default )
@ param [ in ] allow_exceptions whether to throw exceptions in case of a
parse error ( optional , true by default )
@ return deserialized JSON value
@ throw parse_error .114 if an unsupported BSON record type is encountered
2018-09-15 04:58:22 +08:00
2018-10-28 22:09:26 +08:00
@ complexity Linear in the size of the input @ a i .
@ liveexample { The example shows the deserialization of a byte vector in
BSON format to a JSON value . , from_bson }
2018-10-07 13:52:12 +08:00
@ sa http : //bsonspec.org/spec.html
2018-10-28 16:15:41 +08:00
@ sa @ ref to_bson ( const basic_json & ) for the analogous serialization
@ sa @ ref from_cbor ( detail : : input_adapter & & , const bool , const bool ) for the
2018-10-07 13:52:12 +08:00
related CBOR format
2018-10-28 16:15:41 +08:00
@ sa @ ref from_msgpack ( detail : : input_adapter & & , const bool , const bool ) for
2018-10-07 13:52:12 +08:00
the related MessagePack format
2018-10-28 16:15:41 +08:00
@ sa @ ref from_ubjson ( detail : : input_adapter & & , const bool , const bool ) for the
2018-10-07 13:52:12 +08:00
related UBJSON format
*/
2018-09-15 04:58:22 +08:00
static basic_json from_bson ( detail : : input_adapter & & i ,
const bool strict = true ,
const bool allow_exceptions = true )
{
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
const bool res = binary_reader ( detail : : input_adapter ( i ) ) . sax_parse ( input_format_t : : bson , & sdp , strict ) ;
return res ? result : basic_json ( value_t : : discarded ) ;
}
2018-10-07 13:52:12 +08:00
/*!
@ copydoc from_bson ( detail : : input_adapter & & , const bool , const bool )
*/
2018-09-15 04:58:22 +08:00
template < typename A1 , typename A2 ,
detail : : enable_if_t < std : : is_constructible < detail : : input_adapter , A1 , A2 > : : value , int > = 0 >
static basic_json from_bson ( A1 & & a1 , A2 & & a2 ,
const bool strict = true ,
const bool allow_exceptions = true )
{
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
const bool res = binary_reader ( detail : : input_adapter ( std : : forward < A1 > ( a1 ) , std : : forward < A2 > ( a2 ) ) ) . sax_parse ( input_format_t : : bson , & sdp , strict ) ;
return res ? result : basic_json ( value_t : : discarded ) ;
}
2018-01-10 01:30:02 +08:00
/// @}
//////////////////////////
// JSON Pointer support //
//////////////////////////
/// @name JSON Pointer functions
/// @{
/*!
@ brief access specified element via JSON Pointer
Uses a JSON pointer to retrieve a reference to the respective JSON value .
No bound checking is performed . Similar to @ ref operator [ ] ( const typename
object_t : : key_type & ) , ` null ` values are created in arrays and objects if
necessary .
In particular :
- If the JSON pointer points to an object key that does not exist , it
is created an filled with a ` null ` value before a reference to it
is returned .
- If the JSON pointer points to an array index that does not exist , it
is created an filled with a ` null ` value before a reference to it
is returned . All indices between the current maximum and the given
index are also filled with ` null ` .
- The special value ` - ` is treated as a synonym for the index past the
end .
@ param [ in ] ptr a JSON pointer
@ return reference to the element pointed to by @ a ptr
@ complexity Constant .
@ throw parse_error .106 if an array index begins with ' 0 '
@ throw parse_error .109 if an array index was not a number
@ throw out_of_range .404 if the JSON pointer can not be resolved
@ liveexample { The behavior is shown in the example . , operatorjson_pointer }
@ since version 2.0 .0
*/
reference operator [ ] ( const json_pointer & ptr )
{
return ptr . get_unchecked ( this ) ;
}
/*!
@ brief access specified element via JSON Pointer
Uses a JSON pointer to retrieve a reference to the respective JSON value .
No bound checking is performed . The function does not change the JSON
value ; no ` null ` values are created . In particular , the the special value
` - ` yields an exception .
@ param [ in ] ptr JSON pointer to the desired element
@ return const reference to the element pointed to by @ a ptr
@ complexity Constant .
@ throw parse_error .106 if an array index begins with ' 0 '
@ throw parse_error .109 if an array index was not a number
@ throw out_of_range .402 if the array index ' - ' is used
@ throw out_of_range .404 if the JSON pointer can not be resolved
@ liveexample { The behavior is shown in the example . , operatorjson_pointer_const }
@ since version 2.0 .0
*/
const_reference operator [ ] ( const json_pointer & ptr ) const
{
return ptr . get_unchecked ( this ) ;
}
/*!
@ brief access specified element via JSON Pointer
Returns a reference to the element at with specified JSON pointer @ a ptr ,
with bounds checking .
@ param [ in ] ptr JSON pointer to the desired element
@ return reference to the element pointed to by @ a ptr
@ throw parse_error .106 if an array index in the passed JSON pointer @ a ptr
begins with ' 0 ' . See example below .
@ throw parse_error .109 if an array index in the passed JSON pointer @ a ptr
is not a number . See example below .
@ throw out_of_range .401 if an array index in the passed JSON pointer @ a ptr
is out of range . See example below .
@ throw out_of_range .402 if the array index ' - ' is used in the passed JSON
pointer @ a ptr . As ` at ` provides checked access ( and no elements are
implicitly inserted ) , the index ' - ' is always invalid . See example below .
@ throw out_of_range .403 if the JSON pointer describes a key of an object
which cannot be found . See example below .
@ throw out_of_range .404 if the JSON pointer @ a ptr can not be resolved .
See example below .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes in the JSON value .
@ complexity Constant .
@ since version 2.0 .0
@ liveexample { The behavior is shown in the example . , at_json_pointer }
*/
reference at ( const json_pointer & ptr )
{
return ptr . get_checked ( this ) ;
}
/*!
@ brief access specified element via JSON Pointer
Returns a const reference to the element at with specified JSON pointer @ a
ptr , with bounds checking .
@ param [ in ] ptr JSON pointer to the desired element
@ return reference to the element pointed to by @ a ptr
@ throw parse_error .106 if an array index in the passed JSON pointer @ a ptr
begins with ' 0 ' . See example below .
@ throw parse_error .109 if an array index in the passed JSON pointer @ a ptr
is not a number . See example below .
@ throw out_of_range .401 if an array index in the passed JSON pointer @ a ptr
is out of range . See example below .
@ throw out_of_range .402 if the array index ' - ' is used in the passed JSON
pointer @ a ptr . As ` at ` provides checked access ( and no elements are
implicitly inserted ) , the index ' - ' is always invalid . See example below .
@ throw out_of_range .403 if the JSON pointer describes a key of an object
which cannot be found . See example below .
@ throw out_of_range .404 if the JSON pointer @ a ptr can not be resolved .
See example below .
@ exceptionsafety Strong guarantee : if an exception is thrown , there are no
changes in the JSON value .
@ complexity Constant .
@ since version 2.0 .0
@ liveexample { The behavior is shown in the example . , at_json_pointer_const }
*/
const_reference at ( const json_pointer & ptr ) const
{
return ptr . get_checked ( this ) ;
}
/*!
@ brief return flattened JSON value
The function creates a JSON object whose keys are JSON pointers ( see [ RFC
6901 ] ( https : //tools.ietf.org/html/rfc6901)) and whose values are all
primitive . The original JSON value can be restored using the @ ref
unflatten ( ) function .
@ return an object that maps JSON pointers to primitive values
@ note Empty objects and arrays are flattened to ` null ` and will not be
reconstructed correctly by the @ ref unflatten ( ) function .
@ complexity Linear in the size the JSON value .
@ liveexample { The following code shows how a JSON object is flattened to an
object whose keys consist of JSON pointers . , flatten }
@ sa @ ref unflatten ( ) for the reverse function
@ since version 2.0 .0
*/
basic_json flatten ( ) const
{
basic_json result ( value_t : : object ) ;
json_pointer : : flatten ( " " , * this , result ) ;
return result ;
}
/*!
@ brief unflatten a previously flattened JSON value
The function restores the arbitrary nesting of a JSON value that has been
flattened before using the @ ref flatten ( ) function . The JSON value must
meet certain constraints :
1. The value must be an object .
2. The keys must be JSON pointers ( see
[ RFC 6901 ] ( https : //tools.ietf.org/html/rfc6901))
3. The mapped values must be primitive JSON types .
@ return the original JSON from a flattened version
@ note Empty objects and arrays are flattened by @ ref flatten ( ) to ` null `
values and can not unflattened to their original type . Apart from
this example , for a JSON value ` j ` , the following is always true :
` j = = j . flatten ( ) . unflatten ( ) ` .
@ complexity Linear in the size the JSON value .
@ throw type_error .314 if value is not an object
@ throw type_error .315 if object values are not primitive
@ liveexample { The following code shows how a flattened JSON object is
unflattened into the original nested JSON object . , unflatten }
@ sa @ ref flatten ( ) for the reverse function
@ since version 2.0 .0
*/
basic_json unflatten ( ) const
{
return json_pointer : : unflatten ( * this ) ;
}
/// @}
//////////////////////////
// JSON Patch functions //
//////////////////////////
/// @name JSON Patch functions
/// @{
/*!
@ brief applies a JSON patch
[ JSON Patch ] ( http : //jsonpatch.com) defines a JSON document structure for
expressing a sequence of operations to apply to a JSON ) document . With
this function , a JSON Patch is applied to the current JSON value by
executing all operations from the patch .
@ param [ in ] json_patch JSON patch document
@ return patched document
@ note The application of a patch is atomic : Either all operations succeed
and the patched document is returned or an exception is thrown . In
any case , the original value is not changed : the patch is applied
to a copy of the value .
@ throw parse_error .104 if the JSON patch does not consist of an array of
objects
@ throw parse_error .105 if the JSON patch is malformed ( e . g . , mandatory
attributes are missing ) ; example : ` " operation add must have member path " `
@ throw out_of_range .401 if an array index is out of range .
@ throw out_of_range .403 if a JSON pointer inside the patch could not be
resolved successfully in the current JSON value ; example : ` " key baz not
found " `
@ throw out_of_range .405 if JSON pointer has no parent ( " add " , " remove " ,
" move " )
@ throw other_error .501 if " test " operation was unsuccessful
@ complexity Linear in the size of the JSON value and the length of the
JSON patch . As usually only a fraction of the JSON value is affected by
the patch , the complexity can usually be neglected .
@ liveexample { The following code shows how a JSON patch is applied to a
value . , patch }
@ sa @ ref diff - - create a JSON patch by comparing two JSON values
@ sa [ RFC 6902 ( JSON Patch ) ] ( https : //tools.ietf.org/html/rfc6902)
@ sa [ RFC 6901 ( JSON Pointer ) ] ( https : //tools.ietf.org/html/rfc6901)
@ since version 2.0 .0
*/
basic_json patch ( const basic_json & json_patch ) const
{
// make a working copy to apply the patch to
basic_json result = * this ;
// the valid JSON Patch operations
enum class patch_operations { add , remove , replace , move , copy , test , invalid } ;
const auto get_op = [ ] ( const std : : string & op )
{
if ( op = = " add " )
{
return patch_operations : : add ;
}
if ( op = = " remove " )
{
return patch_operations : : remove ;
}
if ( op = = " replace " )
{
return patch_operations : : replace ;
}
if ( op = = " move " )
{
return patch_operations : : move ;
}
if ( op = = " copy " )
{
return patch_operations : : copy ;
}
if ( op = = " test " )
{
return patch_operations : : test ;
}
return patch_operations : : invalid ;
} ;
// wrapper for "add" operation; add value at ptr
const auto operation_add = [ & result ] ( json_pointer & ptr , basic_json val )
{
// adding to the root of the target document means replacing it
if ( ptr . is_root ( ) )
{
result = val ;
}
else
{
// make sure the top element of the pointer exists
json_pointer top_pointer = ptr . top ( ) ;
if ( top_pointer ! = ptr )
{
result . at ( top_pointer ) ;
}
// get reference to parent of JSON pointer ptr
const auto last_path = ptr . pop_back ( ) ;
basic_json & parent = result [ ptr ] ;
switch ( parent . m_type )
{
case value_t : : null :
case value_t : : object :
{
// use operator[] to add value
parent [ last_path ] = val ;
break ;
}
case value_t : : array :
{
if ( last_path = = " - " )
{
// special case: append to back
parent . push_back ( val ) ;
}
else
{
const auto idx = json_pointer : : array_index ( last_path ) ;
if ( JSON_UNLIKELY ( static_cast < size_type > ( idx ) > parent . size ( ) ) )
{
// avoid undefined behavior
JSON_THROW ( out_of_range : : create ( 401 , " array index " + std : : to_string ( idx ) + " is out of range " ) ) ;
}
2018-10-08 01:07:58 +08:00
// default case: insert add offset
parent . insert ( parent . begin ( ) + static_cast < difference_type > ( idx ) , val ) ;
2018-01-10 01:30:02 +08:00
}
break ;
}
2018-08-18 18:00:14 +08:00
// LCOV_EXCL_START
2018-01-10 01:30:02 +08:00
default :
{
// if there exists a parent it cannot be primitive
2018-08-18 18:00:14 +08:00
assert ( false ) ;
2018-01-10 01:30:02 +08:00
}
2018-08-18 18:00:14 +08:00
// LCOV_EXCL_STOP
2018-01-10 01:30:02 +08:00
}
}
} ;
// wrapper for "remove" operation; remove value at ptr
const auto operation_remove = [ & result ] ( json_pointer & ptr )
{
// get reference to parent of JSON pointer ptr
const auto last_path = ptr . pop_back ( ) ;
basic_json & parent = result . at ( ptr ) ;
// remove child
if ( parent . is_object ( ) )
{
// perform range check
auto it = parent . find ( last_path ) ;
if ( JSON_LIKELY ( it ! = parent . end ( ) ) )
{
parent . erase ( it ) ;
}
else
{
JSON_THROW ( out_of_range : : create ( 403 , " key ' " + last_path + " ' not found " ) ) ;
}
}
else if ( parent . is_array ( ) )
{
// note erase performs range check
parent . erase ( static_cast < size_type > ( json_pointer : : array_index ( last_path ) ) ) ;
}
} ;
// type check: top level value must be an array
if ( JSON_UNLIKELY ( not json_patch . is_array ( ) ) )
{
JSON_THROW ( parse_error : : create ( 104 , 0 , " JSON patch must be an array of objects " ) ) ;
}
// iterate and apply the operations
for ( const auto & val : json_patch )
{
// wrapper to get a value for an operation
const auto get_value = [ & val ] ( const std : : string & op ,
const std : : string & member ,
2018-01-19 04:57:21 +08:00
bool string_type ) - > basic_json &
2018-01-10 01:30:02 +08:00
{
// find value
auto it = val . m_value . object - > find ( member ) ;
// context-sensitive error message
const auto error_msg = ( op = = " op " ) ? " operation " : " operation ' " + op + " ' " ;
// check if desired value is present
if ( JSON_UNLIKELY ( it = = val . m_value . object - > end ( ) ) )
{
JSON_THROW ( parse_error : : create ( 105 , 0 , error_msg + " must have member ' " + member + " ' " ) ) ;
}
// check if result is of type string
if ( JSON_UNLIKELY ( string_type and not it - > second . is_string ( ) ) )
{
JSON_THROW ( parse_error : : create ( 105 , 0 , error_msg + " must have string member ' " + member + " ' " ) ) ;
}
// no error: return value
return it - > second ;
} ;
// type check: every element of the array must be an object
if ( JSON_UNLIKELY ( not val . is_object ( ) ) )
{
JSON_THROW ( parse_error : : create ( 104 , 0 , " JSON patch must be an array of objects " ) ) ;
}
// collect mandatory members
const std : : string op = get_value ( " op " , " op " , true ) ;
const std : : string path = get_value ( op , " path " , true ) ;
json_pointer ptr ( path ) ;
switch ( get_op ( op ) )
{
case patch_operations : : add :
{
operation_add ( ptr , get_value ( " add " , " value " , false ) ) ;
break ;
}
case patch_operations : : remove :
{
operation_remove ( ptr ) ;
break ;
}
case patch_operations : : replace :
{
// the "path" location must exist - use at()
result . at ( ptr ) = get_value ( " replace " , " value " , false ) ;
break ;
}
case patch_operations : : move :
{
const std : : string from_path = get_value ( " move " , " from " , true ) ;
json_pointer from_ptr ( from_path ) ;
// the "from" location must exist - use at()
basic_json v = result . at ( from_ptr ) ;
// The move operation is functionally identical to a
// "remove" operation on the "from" location, followed
// immediately by an "add" operation at the target
// location with the value that was just removed.
operation_remove ( from_ptr ) ;
operation_add ( ptr , v ) ;
break ;
}
case patch_operations : : copy :
{
const std : : string from_path = get_value ( " copy " , " from " , true ) ;
const json_pointer from_ptr ( from_path ) ;
// the "from" location must exist - use at()
basic_json v = result . at ( from_ptr ) ;
// The copy is functionally identical to an "add"
// operation at the target location using the value
// specified in the "from" member.
operation_add ( ptr , v ) ;
break ;
}
case patch_operations : : test :
{
bool success = false ;
JSON_TRY
{
// check if "value" matches the one at "path"
// the "path" location must exist - use at()
success = ( result . at ( ptr ) = = get_value ( " test " , " value " , false ) ) ;
}
2018-07-19 14:43:41 +08:00
JSON_INTERNAL_CATCH ( out_of_range & )
2018-01-10 01:30:02 +08:00
{
// ignore out of range errors: success remains false
}
// throw an exception if test fails
if ( JSON_UNLIKELY ( not success ) )
{
JSON_THROW ( other_error : : create ( 501 , " unsuccessful: " + val . dump ( ) ) ) ;
}
break ;
}
case patch_operations : : invalid :
{
// op must be "add", "remove", "replace", "move", "copy", or
// "test"
JSON_THROW ( parse_error : : create ( 105 , 0 , " operation value ' " + op + " ' is invalid " ) ) ;
}
}
}
return result ;
}
/*!
@ brief creates a diff as a JSON patch
Creates a [ JSON Patch ] ( http : //jsonpatch.com) so that value @a source can
be changed into the value @ a target by calling @ ref patch function .
@ invariant For two JSON values @ a source and @ a target , the following code
yields always ` true ` :
@ code { . cpp }
source . patch ( diff ( source , target ) ) = = target ;
@ endcode
@ note Currently , only ` remove ` , ` add ` , and ` replace ` operations are
generated .
@ param [ in ] source JSON value to compare from
@ param [ in ] target JSON value to compare against
@ param [ in ] path helper value to create JSON pointers
@ return a JSON patch to convert the @ a source to @ a target
@ complexity Linear in the lengths of @ a source and @ a target .
@ liveexample { The following code shows how a JSON patch is created as a
diff for two JSON values . , diff }
@ sa @ ref patch - - apply a JSON patch
2018-01-14 17:34:43 +08:00
@ sa @ ref merge_patch - - apply a JSON Merge Patch
2018-01-10 01:30:02 +08:00
@ sa [ RFC 6902 ( JSON Patch ) ] ( https : //tools.ietf.org/html/rfc6902)
@ since version 2.0 .0
*/
static basic_json diff ( const basic_json & source , const basic_json & target ,
const std : : string & path = " " )
{
// the patch
basic_json result ( value_t : : array ) ;
// if the values are the same, return empty patch
if ( source = = target )
{
return result ;
}
if ( source . type ( ) ! = target . type ( ) )
{
// different types: replace value
result . push_back (
{
{ " op " , " replace " } , { " path " , path } , { " value " , target }
} ) ;
}
else
{
switch ( source . type ( ) )
{
case value_t : : array :
{
// first pass: traverse common elements
std : : size_t i = 0 ;
while ( i < source . size ( ) and i < target . size ( ) )
{
// recursive call to compare array values at index i
auto temp_diff = diff ( source [ i ] , target [ i ] , path + " / " + std : : to_string ( i ) ) ;
result . insert ( result . end ( ) , temp_diff . begin ( ) , temp_diff . end ( ) ) ;
+ + i ;
}
// i now reached the end of at least one array
// in a second pass, traverse the remaining elements
// remove my remaining elements
const auto end_index = static_cast < difference_type > ( result . size ( ) ) ;
while ( i < source . size ( ) )
{
// add operations in reverse order to avoid invalid
// indices
result . insert ( result . begin ( ) + end_index , object (
{
{ " op " , " remove " } ,
{ " path " , path + " / " + std : : to_string ( i ) }
} ) ) ;
+ + i ;
}
// add other remaining elements
while ( i < target . size ( ) )
{
result . push_back (
{
{ " op " , " add " } ,
{ " path " , path + " / " + std : : to_string ( i ) } ,
{ " value " , target [ i ] }
} ) ;
+ + i ;
}
break ;
}
case value_t : : object :
{
// first pass: traverse this object's elements
for ( auto it = source . cbegin ( ) ; it ! = source . cend ( ) ; + + it )
{
// escape the key name to be used in a JSON patch
const auto key = json_pointer : : escape ( it . key ( ) ) ;
if ( target . find ( it . key ( ) ) ! = target . end ( ) )
{
// recursive call to compare object values at key it
auto temp_diff = diff ( it . value ( ) , target [ it . key ( ) ] , path + " / " + key ) ;
result . insert ( result . end ( ) , temp_diff . begin ( ) , temp_diff . end ( ) ) ;
}
else
{
// found a key that is not in o -> remove it
result . push_back ( object (
{
{ " op " , " remove " } , { " path " , path + " / " + key }
} ) ) ;
}
}
// second pass: traverse other object's elements
for ( auto it = target . cbegin ( ) ; it ! = target . cend ( ) ; + + it )
{
if ( source . find ( it . key ( ) ) = = source . end ( ) )
{
// found a key that is not in this -> add it
const auto key = json_pointer : : escape ( it . key ( ) ) ;
result . push_back (
{
{ " op " , " add " } , { " path " , path + " / " + key } ,
{ " value " , it . value ( ) }
} ) ;
}
}
break ;
}
default :
{
// both primitive type: replace value
result . push_back (
{
{ " op " , " replace " } , { " path " , path } , { " value " , target }
} ) ;
break ;
}
}
}
return result ;
}
/// @}
2018-01-14 17:34:43 +08:00
////////////////////////////////
// JSON Merge Patch functions //
////////////////////////////////
/// @name JSON Merge Patch functions
/// @{
/*!
@ brief applies a JSON Merge Patch
The merge patch format is primarily intended for use with the HTTP PATCH
method as a means of describing a set of modifications to a target
resource ' s content . This function applies a merge patch to the current
JSON value .
The function implements the following algorithm from Section 2 of
[ RFC 7396 ( JSON Merge Patch ) ] ( https : //tools.ietf.org/html/rfc7396):
` ` `
define MergePatch ( Target , Patch ) :
if Patch is an Object :
if Target is not an Object :
Target = { } // Ignore the contents and set it to an empty Object
for each Name / Value pair in Patch :
if Value is null :
if Name exists in Target :
remove the Name / Value pair from Target
else :
Target [ Name ] = MergePatch ( Target [ Name ] , Value )
return Target
else :
return Patch
` ` `
Thereby , ` Target ` is the current object ; that is , the patch is applied to
the current value .
2018-11-08 17:31:47 +08:00
@ param [ in ] apply_patch the patch to apply
2018-01-14 17:34:43 +08:00
@ complexity Linear in the lengths of @ a patch .
@ liveexample { The following code shows how a JSON Merge Patch is applied to
a JSON document . , merge_patch }
@ sa @ ref patch - - apply a JSON patch
@ sa [ RFC 7396 ( JSON Merge Patch ) ] ( https : //tools.ietf.org/html/rfc7396)
@ since version 3.0 .0
*/
2018-11-08 17:31:47 +08:00
void merge_patch ( const basic_json & apply_patch )
2018-01-14 17:34:43 +08:00
{
2018-11-08 17:31:47 +08:00
if ( apply_patch . is_object ( ) )
2018-01-14 17:34:43 +08:00
{
if ( not is_object ( ) )
{
* this = object ( ) ;
}
2018-11-08 17:31:47 +08:00
for ( auto it = apply_patch . begin ( ) ; it ! = apply_patch . end ( ) ; + + it )
2018-01-14 17:34:43 +08:00
{
if ( it . value ( ) . is_null ( ) )
{
erase ( it . key ( ) ) ;
}
else
{
operator [ ] ( it . key ( ) ) . merge_patch ( it . value ( ) ) ;
}
}
}
else
{
2018-11-08 17:31:47 +08:00
* this = apply_patch ;
2018-01-14 17:34:43 +08:00
}
}
/// @}
2018-01-10 01:30:02 +08:00
} ;
} // namespace nlohmann
///////////////////////
// nonmember support //
///////////////////////
// specialization of std::swap, and std::hash
namespace std
{
/// hash value for JSON objects
template < >
struct hash < nlohmann : : json >
{
/*!
@ brief return a hash value for a JSON object
@ since version 1.0 .0
*/
std : : size_t operator ( ) ( const nlohmann : : json & j ) const
{
// a naive hashing via the string representation
const auto & h = hash < nlohmann : : json : : string_t > ( ) ;
return h ( j . dump ( ) ) ;
}
} ;
/// specialization for std::less<value_t>
/// @note: do not remove the space after '<',
/// see https://github.com/nlohmann/json/pull/679
template < >
struct less < : : nlohmann : : detail : : value_t >
{
/*!
@ brief compare two value_t enum values
@ since version 3.0 .0
*/
bool operator ( ) ( nlohmann : : detail : : value_t lhs ,
nlohmann : : detail : : value_t rhs ) const noexcept
{
return nlohmann : : detail : : operator < ( lhs , rhs ) ;
}
} ;
2018-09-19 04:38:59 +08:00
/*!
@ brief exchanges the values of two JSON objects
@ since version 1.0 .0
*/
template < >
inline void swap < nlohmann : : json > ( nlohmann : : json & j1 , nlohmann : : json & j2 ) noexcept (
is_nothrow_move_constructible < nlohmann : : json > : : value and
is_nothrow_move_assignable < nlohmann : : json > : : value
)
{
j1 . swap ( j2 ) ;
}
2018-01-10 01:30:02 +08:00
} // namespace std
/*!
@ brief user - defined string literal for JSON values
This operator implements a user - defined string literal for JSON objects . It
can be used by adding ` " _json " ` to a string literal and returns a JSON object
if no parse error occurred .
@ param [ in ] s a string representation of a JSON object
@ param [ in ] n the length of string @ a s
@ return a JSON object
@ since version 1.0 .0
*/
inline nlohmann : : json operator " " _json ( const char * s , std : : size_t n )
{
return nlohmann : : json : : parse ( s , s + n ) ;
}
/*!
@ brief user - defined string literal for JSON pointer
This operator implements a user - defined string literal for JSON Pointers . It
can be used by adding ` " _json_pointer " ` to a string literal and returns a JSON pointer
object if no parse error occurred .
@ param [ in ] s a string representation of a JSON Pointer
@ param [ in ] n the length of string @ a s
@ return a JSON pointer object
@ since version 2.0 .0
*/
inline nlohmann : : json : : json_pointer operator " " _json_pointer ( const char * s , std : : size_t n )
{
return nlohmann : : json : : json_pointer ( std : : string ( s , n ) ) ;
}
2018-01-29 18:21:11 +08:00
# include <nlohmann/detail/macro_unscope.hpp>
2018-01-10 01:30:02 +08:00
# endif
