2018-01-10 01:30:02 +08:00
/*
__ _____ _____ _____
__ | | __ | | | | JSON for Modern C + +
2021-08-25 02:19:55 +08:00
| | | __ | | | | | | version 3.10 .1
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
2019-03-20 07:19:07 +08:00
Copyright ( c ) 2013 - 2019 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 .
*/
2019-03-15 21:55:13 +08:00
# ifndef INCLUDE_NLOHMANN_JSON_HPP_
# define INCLUDE_NLOHMANN_JSON_HPP_
2018-01-10 01:30:02 +08:00
2018-02-01 05:36:18 +08:00
# define NLOHMANN_JSON_VERSION_MAJOR 3
2021-08-17 21:23:23 +08:00
# define NLOHMANN_JSON_VERSION_MINOR 10
2021-08-25 02:19:55 +08:00
# define NLOHMANN_JSON_VERSION_PATCH 1
2018-02-01 05:36:18 +08:00
2018-01-10 01:30:02 +08:00
# include <algorithm> // all_of, find, for_each
# include <cstddef> // nullptr_t, ptrdiff_t, size_t
# include <functional> // hash, less
# include <initializer_list> // initializer_list
2021-05-31 20:26:45 +08:00
# ifndef JSON_NO_IO
# include <iosfwd> // istream, ostream
# endif // JSON_NO_IO
2018-11-08 02:39:25 +08:00
# include <iterator> // random_access_iterator_tag
2019-03-15 21:55:13 +08:00
# include <memory> // unique_ptr
2018-01-10 01:30:02 +08:00
# include <numeric> // accumulate
# include <string> // string, stoi, to_string
# include <utility> // declval, forward, move, pair, swap
2019-03-15 21:55:13 +08:00
# include <vector> // vector
2018-01-10 01:30:02 +08:00
2019-03-17 19:01:49 +08:00
# include <nlohmann/adl_serializer.hpp>
2020-05-19 19:08:18 +08:00
# include <nlohmann/byte_container_with_subtype.hpp>
2018-01-29 18:21:11 +08:00
# include <nlohmann/detail/conversions/from_json.hpp>
# include <nlohmann/detail/conversions/to_json.hpp>
2019-03-17 19:01:49 +08:00
# include <nlohmann/detail/exceptions.hpp>
2020-07-14 20:31:19 +08:00
# include <nlohmann/detail/hash.hpp>
2019-03-17 19:01:49 +08:00
# include <nlohmann/detail/input/binary_reader.hpp>
2018-01-29 18:21:11 +08:00
# include <nlohmann/detail/input/input_adapters.hpp>
# include <nlohmann/detail/input/lexer.hpp>
# include <nlohmann/detail/input/parser.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>
2019-03-17 19:01:49 +08:00
# include <nlohmann/detail/iterators/primitive_iterator.hpp>
# include <nlohmann/detail/json_pointer.hpp>
# include <nlohmann/detail/json_ref.hpp>
# include <nlohmann/detail/macro_scope.hpp>
2021-03-24 14:15:18 +08:00
# include <nlohmann/detail/string_escape.hpp>
2019-03-17 19:01:49 +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/output/binary_writer.hpp>
2019-03-17 19:01:49 +08:00
# include <nlohmann/detail/output/output_adapters.hpp>
2018-01-29 18:21:11 +08:00
# include <nlohmann/detail/output/serializer.hpp>
2019-03-17 19:01:49 +08:00
# include <nlohmann/detail/value_t.hpp>
# include <nlohmann/json_fwd.hpp>
2020-06-19 21:27:05 +08:00
# include <nlohmann/ordered_map.hpp>
2018-01-10 01:30:02 +08:00
2020-12-20 22:40:36 +08:00
# if defined(JSON_HAS_CPP_17)
# include <string_view>
# endif
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 )
2019-07-05 12:13:25 +08:00
@ tparam BinaryType type for packed binary data for compatibility with binary
serialization formats ( ` std : : vector < std : : uint8_t > ` by default ; will be used in
@ ref binary_t )
2018-01-10 01:30:02 +08:00
@ 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
2020-02-02 17:29:37 +08:00
@ note ObjectType trick from https : //stackoverflow.com/a/9860911
2018-01-10 01:30:02 +08:00
@ endinternal
2021-04-29 02:33:05 +08:00
@ see [ RFC 8259 : The JavaScript Object Notation ( JSON ) Data Interchange
Format ] ( https : //tools.ietf.org/html/rfc8259)
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
@ nosubgrouping
*/
NLOHMANN_BASIC_JSON_TPL_DECLARATION
2021-03-24 14:15:18 +08:00
class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-special-member-functions)
2018-01-10 01:30:02 +08:00
{
private :
template < detail : : value_t > friend struct detail : : external_constructor ;
2018-01-28 22:36:56 +08:00
friend : : nlohmann : : json_pointer < basic_json > ;
2020-02-19 23:32:49 +08:00
template < typename BasicJsonType , typename InputType >
friend class : : nlohmann : : detail : : parser ;
2018-01-10 01:30:02 +08:00
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 ;
2020-02-20 03:59:31 +08:00
template < typename BasicJsonType , typename InputType , 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 ;
2021-01-25 20:47:50 +08:00
friend class : : nlohmann : : detail : : exception ;
2018-01-10 01:30:02 +08:00
/// workaround type for MSVC
using basic_json_t = NLOHMANN_BASIC_JSON_TPL ;
2020-08-12 19:30:06 +08:00
JSON_PRIVATE_UNLESS_TESTED :
2018-01-10 01:30:02 +08:00
// convenience aliases for types residing in namespace detail;
2020-02-19 23:32:49 +08:00
using lexer = : : nlohmann : : detail : : lexer_base < basic_json > ;
template < typename InputAdapterType >
static : : nlohmann : : detail : : parser < basic_json , InputAdapterType > parser (
2020-02-20 03:59:31 +08:00
InputAdapterType adapter ,
2020-02-19 23:32:49 +08:00
detail : : parser_callback_t < basic_json > cb = nullptr ,
2020-06-18 04:03:14 +08:00
const bool allow_exceptions = true ,
const bool ignore_comments = false
2020-02-19 23:32:49 +08:00
)
{
2020-06-18 04:03:14 +08:00
return : : nlohmann : : detail : : parser < basic_json , InputAdapterType > ( std : : move ( adapter ) ,
std : : move ( cb ) , allow_exceptions , ignore_comments ) ;
2020-02-19 23:32:49 +08:00
}
2018-01-10 01:30:02 +08:00
2020-08-12 19:30:06 +08:00
private :
2018-01-10 01:30:02 +08:00
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 > ;
2020-02-20 03:59:31 +08:00
template < typename InputType >
using binary_reader = : : nlohmann : : detail : : binary_reader < basic_json , InputType > ;
2018-01-10 01:30:02 +08:00
template < typename CharType > using binary_writer = : : nlohmann : : detail : : binary_writer < basic_json , CharType > ;
2020-08-12 19:30:06 +08:00
JSON_PRIVATE_UNLESS_TESTED :
2018-01-10 01:30:02 +08:00
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 ;
2020-07-12 22:51:43 +08:00
/// how to treat CBOR tags
using cbor_tag_handler_t = detail : : cbor_tag_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
*/
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2018-01-10 01:30:02 +08:00
static basic_json meta ( )
{
basic_json result ;
2021-01-04 03:28:06 +08:00
result [ " copyright " ] = " (C) 2013-2021 Niels Lohmann " ;
2018-01-10 01:30:02 +08:00
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
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) describes JSON objects as follows:
2018-01-10 01:30:02 +08:00
> 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
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) specifies:
2018-01-10 01:30:02 +08:00
> 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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref array_t - - type for an array value
2018-01-10 01:30:02 +08:00
@ 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
2021-04-29 02:33:05 +08:00
8259 ] ( https : //tools.ietf.org/html/rfc8259), because any order implements the
2018-01-10 01:30:02 +08:00
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
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) describes JSON arrays as follows:
2018-01-10 01:30:02 +08:00
> 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
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) specifies:
2018-01-10 01:30:02 +08:00
> 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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref object_t - - type for an object value
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
using array_t = ArrayType < basic_json , AllocatorType < basic_json > > ;
/*!
@ brief a type for a string
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) describes JSON strings as follows:
2018-01-10 01:30:02 +08:00
> 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
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) states:
2018-01-10 01:30:02 +08:00
> 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
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) implicitly describes a boolean as a
2018-01-10 01:30:02 +08:00
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 )
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) describes numbers as follows:
2018-01-10 01:30:02 +08:00
> 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
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) specifies:
2018-01-10 01:30:02 +08:00
> 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 .
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) further states:
2018-01-10 01:30:02 +08:00
> 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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref number_float_t - - type for number values ( floating - point )
2018-01-10 01:30:02 +08:00
2021-03-24 14:15:18 +08:00
@ sa see @ ref number_unsigned_t - - type for number values ( unsigned integer )
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
using number_integer_t = NumberIntegerType ;
/*!
@ brief a type for a number ( unsigned )
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) describes numbers as follows:
2018-01-10 01:30:02 +08:00
> 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
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) specifies:
2018-01-10 01:30:02 +08:00
> 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 .
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) further states:
2018-01-10 01:30:02 +08:00
> 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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref number_float_t - - type for number values ( floating - point )
@ sa see @ ref number_integer_t - - type for number values ( integer )
2018-01-10 01:30:02 +08:00
@ since version 2.0 .0
*/
using number_unsigned_t = NumberUnsignedType ;
/*!
@ brief a type for a number ( floating - point )
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) describes numbers as follows:
2018-01-10 01:30:02 +08:00
> 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
2021-04-29 02:33:05 +08:00
[ RFC 8259 ] ( https : //tools.ietf.org/html/rfc8259) states:
2018-01-10 01:30:02 +08:00
> 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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref number_integer_t - - type for number values ( integer )
2018-01-10 01:30:02 +08:00
2021-03-24 14:15:18 +08:00
@ sa see @ ref number_unsigned_t - - type for number values ( unsigned integer )
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
using number_float_t = NumberFloatType ;
2019-07-05 12:13:25 +08:00
/*!
@ brief a type for a packed binary type
This type is a type designed to carry binary data that appears in various
serialized formats , such as CBOR ' s Major Type 2 , MessagePack ' s bin , and
2020-05-16 05:21:49 +08:00
BSON ' s generic binary subtype . This type is NOT a part of standard JSON and
2020-05-15 20:12:32 +08:00
exists solely for compatibility with these binary types . As such , it is
2019-07-05 12:13:25 +08:00
simply defined as an ordered sequence of zero or more byte values .
Additionally , as an implementation detail , the subtype of the binary data is
2020-05-16 05:21:49 +08:00
carried around as a ` std : : uint8_t ` , which is compatible with both of the
binary data formats that use binary subtyping , ( though the specific
numbering is incompatible with each other , and it is up to the user to
translate between them ) .
2019-07-05 12:13:25 +08:00
[ CBOR ' s RFC 7049 ] ( https : //tools.ietf.org/html/rfc7049) describes this type
as :
2020-05-15 20:12:32 +08:00
> Major type 2 : a byte string . The string ' s length in bytes is represented
> following the rules for positive integers ( major type 0 ) .
2019-07-05 12:13:25 +08:00
[ MessagePack ' s documentation on the bin type
family ] ( https : //github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family)
describes this type as :
> Bin format family stores an byte array in 2 , 3 , or 5 bytes of extra bytes
> in addition to the size of the byte array .
[ BSON ' s specifications ] ( http : //bsonspec.org/spec.html) describe several
binary types ; however , this type is intended to represent the generic binary
type which has the description :
> Generic binary subtype - This is the most commonly used binary subtype and
> should be the ' default ' for drivers and tools .
None of these impose any limitations on the internal representation other
than the basic unit of storage be some type of array whose parts are
2020-05-15 20:12:32 +08:00
decomposable into bytes .
2019-07-05 12:13:25 +08:00
The default representation of this binary format is a
` std : : vector < std : : uint8_t > ` , which is a very common way to represent a byte
array in modern C + + .
# ### Default type
The default values for @ a BinaryType is ` std : : vector < std : : uint8_t > `
# ### Storage
2020-05-15 20:12:32 +08:00
Binary Arrays are stored as pointers in a @ ref basic_json type . That is ,
2019-07-05 12:13:25 +08:00
for any access to array values , a pointer of the type ` binary_t * ` must be
dereferenced .
2020-05-18 04:50:27 +08:00
# ### Notes on subtypes
2020-05-17 19:51:59 +08:00
- CBOR
2021-08-08 19:24:17 +08:00
- Binary values are represented as byte strings . Subtypes are serialized
as tagged values .
2020-05-17 19:51:59 +08:00
- MessagePack
- If a subtype is given and the binary array contains exactly 1 , 2 , 4 , 8 ,
or 16 elements , the fixext family ( fixext1 , fixext2 , fixext4 , fixext8 )
is used . For other sizes , the ext family ( ext8 , ext16 , ext32 ) is used .
The subtype is then added as singed 8 - bit integer .
- If no subtype is given , the bin family ( bin8 , bin16 , bin32 ) is used .
2020-05-18 04:50:27 +08:00
- BSON
2020-05-17 19:51:59 +08:00
- If a subtype is given , it is used and added as unsigned 8 - bit integer .
- If no subtype is given , the generic binary subtype 0x00 is used .
2021-03-24 14:15:18 +08:00
@ sa see @ ref binary - - create a binary array
2020-05-18 04:50:27 +08:00
@ since version 3.8 .0
2020-05-16 05:21:49 +08:00
*/
2020-05-19 19:08:18 +08:00
using binary_t = nlohmann : : byte_container_with_subtype < BinaryType > ;
2018-01-10 01:30:02 +08:00
/// @}
private :
/// helper for exception-safe object creation
template < typename T , typename . . . Args >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_RETURNS_NON_NULL
2018-01-10 01:30:02 +08:00
static T * create ( Args & & . . . args )
{
AllocatorType < T > alloc ;
using AllocatorTraits = std : : allocator_traits < AllocatorType < T > > ;
2020-12-16 05:15:36 +08:00
auto deleter = [ & ] ( T * obj )
2018-01-10 01:30:02 +08:00
{
2020-12-16 05:15:36 +08:00
AllocatorTraits : : deallocate ( alloc , obj , 1 ) ;
2018-01-10 01:30:02 +08:00
} ;
2020-12-16 05:15:36 +08:00
std : : unique_ptr < T , decltype ( deleter ) > obj ( AllocatorTraits : : allocate ( alloc , 1 ) , deleter ) ;
AllocatorTraits : : construct ( alloc , obj . get ( ) , std : : forward < Args > ( args ) . . . ) ;
JSON_ASSERT ( obj ! = nullptr ) ;
return obj . release ( ) ;
2018-01-10 01:30:02 +08:00
}
////////////////////////
// JSON value storage //
////////////////////////
2020-08-12 19:30:06 +08:00
JSON_PRIVATE_UNLESS_TESTED :
2018-01-10 01:30:02 +08:00
/*!
@ 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
2020-05-19 19:08:18 +08:00
binary | binary | pointer to @ ref binary_t
2018-01-10 01:30:02 +08:00
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 ;
2019-07-05 12:13:25 +08:00
/// binary (stored with pointer to save storage)
2020-05-18 04:50:27 +08:00
binary_t * binary ;
2018-01-10 01:30:02 +08:00
/// 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 ;
}
2019-07-05 12:13:25 +08:00
case value_t : : binary :
{
2020-05-18 04:50:27 +08:00
binary = create < binary_t > ( ) ;
2019-07-05 12:13:25 +08:00
break ;
}
2018-01-10 01:30:02 +08:00
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 ;
}
2021-08-12 22:33:41 +08:00
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
default :
{
object = nullptr ; // silence warning, see #821
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( t = = value_t : : null ) )
2018-01-10 01:30:02 +08:00
{
2021-08-25 02:19:55 +08:00
JSON_THROW ( other_error : : create ( 500 , " 961c151d2e87f2686a955a9be24d316f1362bf21 3.10.1 " , basic_json ( ) ) ) ; // 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
}
2019-07-05 12:13:25 +08:00
/// constructor for binary arrays
2020-05-18 04:50:27 +08:00
json_value ( const typename binary_t : : container_type & value )
2019-07-05 12:13:25 +08:00
{
2020-05-18 04:50:27 +08:00
binary = create < binary_t > ( value ) ;
2019-07-05 12:13:25 +08:00
}
/// constructor for rvalue binary arrays
2020-05-18 04:50:27 +08:00
json_value ( typename binary_t : : container_type & & value )
2019-07-05 12:13:25 +08:00
{
2020-05-18 04:50:27 +08:00
binary = create < binary_t > ( std : : move ( value ) ) ;
2019-07-05 12:13:25 +08:00
}
2020-05-07 03:23:45 +08:00
/// constructor for binary arrays (internal type)
2020-05-18 04:50:27 +08:00
json_value ( const binary_t & value )
2020-05-07 03:23:45 +08:00
{
2020-05-18 04:50:27 +08:00
binary = create < binary_t > ( value ) ;
2020-05-07 03:23:45 +08:00
}
/// constructor for rvalue binary arrays (internal type)
2020-05-18 04:50:27 +08:00
json_value ( binary_t & & value )
2020-05-07 03:23:45 +08:00
{
2020-05-18 04:50:27 +08:00
binary = create < binary_t > ( std : : move ( value ) ) ;
2020-05-07 03:23:45 +08:00
}
2021-07-16 03:49:09 +08:00
void destroy ( value_t t )
2018-01-10 01:30:02 +08:00
{
2021-07-15 18:46:48 +08:00
if ( t = = value_t : : array | | t = = value_t : : object )
2019-01-16 00:58:01 +08:00
{
2021-07-15 18:46:48 +08:00
// flatten the current json_value to a heap-allocated stack
std : : vector < basic_json > stack ;
2019-01-16 00:58:01 +08:00
2021-07-15 18:46:48 +08:00
// move the top-level items to stack
if ( t = = value_t : : array )
2019-01-16 00:58:01 +08:00
{
2021-07-15 18:46:48 +08:00
stack . reserve ( array - > size ( ) ) ;
std : : move ( array - > begin ( ) , array - > end ( ) , std : : back_inserter ( stack ) ) ;
2019-01-16 00:58:01 +08:00
}
2021-07-15 18:46:48 +08:00
else
2019-01-16 00:58:01 +08:00
{
2021-07-15 18:46:48 +08:00
stack . reserve ( object - > size ( ) ) ;
for ( auto & & it : * object )
2019-01-16 00:58:01 +08:00
{
stack . push_back ( std : : move ( it . second ) ) ;
}
}
2021-07-15 18:46:48 +08:00
while ( ! stack . empty ( ) )
{
// move the last item to local variable to be processed
basic_json current_item ( std : : move ( stack . back ( ) ) ) ;
stack . pop_back ( ) ;
// if current_item is array/object, move
// its children to the stack to be processed later
if ( current_item . is_array ( ) )
{
std : : move ( current_item . m_value . array - > begin ( ) , current_item . m_value . array - > end ( ) , std : : back_inserter ( stack ) ) ;
current_item . m_value . array - > clear ( ) ;
}
else if ( current_item . is_object ( ) )
{
for ( auto & & it : * current_item . m_value . object )
{
stack . push_back ( std : : move ( it . second ) ) ;
}
current_item . m_value . object - > clear ( ) ;
}
// it's now safe that current_item get destructed
// since it doesn't have any children
}
2019-01-16 00:58:01 +08:00
}
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 ;
}
2019-07-05 12:13:25 +08:00
case value_t : : binary :
{
2020-05-18 04:50:27 +08:00
AllocatorType < binary_t > alloc ;
2019-07-05 12:13:25 +08:00
std : : allocator_traits < decltype ( alloc ) > : : destroy ( alloc , binary ) ;
std : : allocator_traits < decltype ( alloc ) > : : deallocate ( alloc , binary , 1 ) ;
break ;
}
2021-08-12 22:33:41 +08:00
case value_t : : null :
case value_t : : boolean :
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : number_float :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
default :
{
break ;
}
}
}
} ;
2020-08-12 19:30:06 +08:00
private :
2018-01-10 01:30:02 +08:00
/*!
@ 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 .
2021-01-11 05:40:50 +08:00
Furthermore , the parent relation is checked for arrays and objects : If
@ a check_parents true and the value is an array or object , then the
container ' s elements must have the current value as parent .
@ param [ in ] check_parents whether the parent relation should be checked .
2021-01-15 04:56:19 +08:00
The value is true by default and should only be set to false
2021-01-11 05:40:50 +08:00
during destruction of objects when the invariant does not
need to hold .
2018-01-10 01:30:02 +08:00
*/
2021-01-11 05:40:50 +08:00
void assert_invariant ( bool check_parents = true ) const noexcept
2018-01-10 01:30:02 +08:00
{
2020-07-11 20:04:40 +08:00
JSON_ASSERT ( m_type ! = value_t : : object | | m_value . object ! = nullptr ) ;
JSON_ASSERT ( m_type ! = value_t : : array | | m_value . array ! = nullptr ) ;
JSON_ASSERT ( m_type ! = value_t : : string | | m_value . string ! = nullptr ) ;
JSON_ASSERT ( m_type ! = value_t : : binary | | m_value . binary ! = nullptr ) ;
2021-01-11 05:40:50 +08:00
# if JSON_DIAGNOSTICS
2021-03-24 14:15:18 +08:00
JSON_TRY
2021-01-11 05:40:50 +08:00
{
2021-03-24 14:15:18 +08:00
// cppcheck-suppress assertWithSideEffect
JSON_ASSERT ( ! check_parents | | ! is_structured ( ) | | std : : all_of ( begin ( ) , end ( ) , [ this ] ( const basic_json & j )
{
return j . m_parent = = this ;
} ) ) ;
}
JSON_CATCH ( . . . ) { } // LCOV_EXCL_LINE
2021-01-11 05:40:50 +08:00
# endif
2021-04-13 07:47:02 +08:00
static_cast < void > ( check_parents ) ;
2018-01-10 01:30:02 +08:00
}
2021-01-15 04:55:49 +08:00
void set_parents ( )
2021-01-10 22:04:14 +08:00
{
# if JSON_DIAGNOSTICS
2021-01-15 04:55:49 +08:00
switch ( m_type )
2021-01-10 22:04:14 +08:00
{
2021-01-15 04:55:49 +08:00
case value_t : : array :
2021-01-10 22:04:14 +08:00
{
2021-01-15 04:55:49 +08:00
for ( auto & element : * m_value . array )
2021-01-10 22:04:14 +08:00
{
2021-01-15 04:55:49 +08:00
element . m_parent = this ;
2021-01-10 22:04:14 +08:00
}
2021-01-15 04:55:49 +08:00
break ;
}
2021-01-10 22:04:14 +08:00
2021-01-15 04:55:49 +08:00
case value_t : : object :
{
for ( auto & element : * m_value . object )
2021-01-10 22:04:14 +08:00
{
2021-01-15 04:55:49 +08:00
element . second . m_parent = this ;
2021-01-10 22:04:14 +08:00
}
2021-01-15 04:55:49 +08:00
break ;
2021-01-10 22:04:14 +08:00
}
2021-01-15 04:55:49 +08:00
2021-08-13 19:43:51 +08:00
case value_t : : null :
case value_t : : string :
case value_t : : boolean :
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : number_float :
case value_t : : binary :
case value_t : : discarded :
2021-01-15 04:55:49 +08:00
default :
break ;
2021-01-10 22:04:14 +08:00
}
2021-01-15 04:55:49 +08:00
# endif
}
2021-01-15 05:43:52 +08:00
iterator set_parents ( iterator it , typename iterator : : difference_type count )
{
# if JSON_DIAGNOSTICS
for ( typename iterator : : difference_type i = 0 ; i < count ; + + i )
{
( it + i ) - > m_parent = this ;
}
# else
static_cast < void > ( count ) ;
# endif
return it ;
}
2021-07-13 21:37:57 +08:00
reference set_parent ( reference j , std : : size_t old_capacity = std : : size_t ( - 1 ) )
2021-01-15 04:55:49 +08:00
{
# if JSON_DIAGNOSTICS
2021-07-13 21:37:57 +08:00
if ( old_capacity ! = std : : size_t ( - 1 ) )
2021-07-13 21:27:27 +08:00
{
// see https://github.com/nlohmann/json/issues/2838
JSON_ASSERT ( type ( ) = = value_t : : array ) ;
if ( JSON_HEDLEY_UNLIKELY ( m_value . array - > capacity ( ) ! = old_capacity ) )
{
// capacity has changed: update all parents
set_parents ( ) ;
return j ;
}
}
2021-08-23 02:30:20 +08:00
// ordered_json uses a vector internally, so pointers could have
// been invalidated; see https://github.com/nlohmann/json/issues/2962
# ifdef JSON_HEDLEY_MSVC_VERSION
# pragma warning(push )
# pragma warning(disable : 4127) // ignore warning to replace if with if constexpr
# endif
if ( detail : : is_ordered_map < object_t > : : value )
{
set_parents ( ) ;
return j ;
}
# ifdef JSON_HEDLEY_MSVC_VERSION
# pragma warning( pop )
# endif
2021-01-15 04:55:49 +08:00
j . m_parent = this ;
2021-01-10 22:04:14 +08:00
# else
static_cast < void > ( j ) ;
2021-07-13 21:37:57 +08:00
static_cast < void > ( old_capacity ) ;
2021-01-10 22:04:14 +08:00
# endif
return j ;
2018-01-10 01:30:02 +08:00
}
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 "
2021-03-24 14:15:18 +08:00
@ sa see @ ref parser_callback_t for more information and examples
2018-01-10 01:30:02 +08:00
*/
2020-02-19 23:32:49 +08:00
using parse_event_t = detail : : parse_event_t ;
2018-01-10 01:30:02 +08:00
/*!
@ 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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref parse for examples
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
2020-02-19 23:32:49 +08:00
using parser_callback_t = detail : : parser_callback_t < basic_json > ;
2018-01-10 01:30:02 +08:00
//////////////////
// 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 | ` [ ] `
2019-07-05 12:13:25 +08:00
binary | empty array
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref clear ( ) - - restores the postcondition of this constructor
2018-01-10 01:30:02 +08:00
@ 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 .
2021-08-08 19:24:17 +08:00
- * * binary * * : @ ref binary_t / ` std : : vector < std : : uint8_t > ` may be used ,
2019-07-05 12:13:25 +08:00
unfortunately because string literals cannot be distinguished from binary
character arrays by the C + + type system , all types compatible with ` const
char * ` will be directed to the string constructor instead . This is both
for backwards compatibility , and due to the fact that a binary type is not
a standard JSON type .
2018-01-10 01:30:02 +08:00
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 . . . )
2021-03-24 14:15:18 +08:00
- ` json_serializer < U > ` has a ` to_json ( basic_json_t & , CompatibleType & & ) ` method
2018-01-10 01:30:02 +08:00
@ 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
*/
2020-06-03 20:20:36 +08:00
template < typename CompatibleType ,
typename U = detail : : uncvref_t < CompatibleType > ,
detail : : enable_if_t <
! detail : : is_basic_json < U > : : value & & detail : : is_compatible_type < basic_json_t , U > : : value , int > = 0 >
2021-03-24 14:15:18 +08:00
basic_json ( CompatibleType & & val ) noexcept ( noexcept ( // NOLINT(bugprone-forwarding-reference-overload,bugprone-exception-escape)
2018-01-17 19:17:38 +08:00
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 ) ) ;
2021-01-15 04:55:49 +08:00
set_parents ( ) ;
2018-01-10 01:30:02 +08:00
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
*/
2020-06-03 20:20:36 +08:00
template < typename BasicJsonType ,
detail : : enable_if_t <
detail : : is_basic_json < BasicJsonType > : : value & & ! std : : is_same < basic_json , BasicJsonType > : : value , int > = 0 >
2018-02-27 19:11:04 +08:00
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 ;
2020-05-18 04:50:27 +08:00
using other_binary_t = typename BasicJsonType : : binary_t ;
2018-02-27 19:11:04 +08:00
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 ;
2019-07-05 12:13:25 +08:00
case value_t : : binary :
JSONSerializer < other_binary_t > : : to_json ( * this , val . template get_ref < const other_binary_t & > ( ) ) ;
break ;
2018-02-27 19:11:04 +08:00
case value_t : : null :
* this = nullptr ;
break ;
case value_t : : discarded :
m_type = value_t : : discarded ;
break ;
2019-03-18 20:53:48 +08:00
default : // LCOV_EXCL_LINE
2021-03-24 14:15:18 +08:00
JSON_ASSERT ( false ) ; // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert) LCOV_EXCL_LINE
2018-02-27 19:11:04 +08:00
}
2021-01-15 04:55:49 +08:00
set_parents ( ) ;
2018-02-27 19:11:04 +08:00
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref array ( initializer_list_t ) - - create a JSON array
2018-01-10 01:30:02 +08:00
value from an initializer list
2021-03-24 14:15:18 +08:00
@ sa see @ ref object ( initializer_list_t ) - - create a JSON object
2018-01-10 01:30:02 +08:00
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 )
{
2020-06-03 20:20:36 +08:00
return element_ref - > is_array ( ) & & element_ref - > size ( ) = = 2 & & ( * element_ref ) [ 0 ] . is_string ( ) ;
2018-01-10 01:30:02 +08:00
} ) ;
// adjust type if type deduction is not wanted
2020-06-03 20:20:36 +08:00
if ( ! type_deduction )
2018-01-10 01:30:02 +08:00
{
// 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
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( manual_type = = value_t : : object & & ! is_an_object ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 301 , " cannot create object from initializer list " , basic_json ( ) ) ) ;
2018-01-10 01:30:02 +08:00
}
}
if ( is_an_object )
{
// the initializer list is a list of pairs -> create object
m_type = value_t : : object ;
m_value = value_t : : object ;
2021-01-09 01:00:23 +08:00
for ( auto & element_ref : init )
2018-01-10 01:30:02 +08:00
{
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 ] ) ) ;
2021-01-09 01:00:23 +08:00
}
2018-01-10 01:30:02 +08:00
}
else
{
// the initializer list describes an array -> create array
m_type = value_t : : array ;
m_value . array = create < array_t > ( init . begin ( ) , init . end ( ) ) ;
}
2021-01-15 04:55:49 +08:00
set_parents ( ) ;
2018-01-10 01:30:02 +08:00
assert_invariant ( ) ;
}
2019-07-05 12:13:25 +08:00
/*!
2020-05-19 19:08:18 +08:00
@ brief explicitly create a binary array ( without subtype )
2019-07-05 12:13:25 +08:00
2020-05-19 19:08:18 +08:00
Creates a JSON binary array value from a given binary container . Binary
values are part of various binary formats , such as CBOR , MessagePack , and
BSON . This constructor is used to create a value for serialization to those
formats .
2019-07-05 12:13:25 +08:00
@ note Note , this function exists because of the difficulty in correctly
specifying the correct template overload in the standard value ctor , as both
JSON arrays and JSON binary arrays are backed with some form of a
2020-05-19 19:08:18 +08:00
` std : : vector ` . Because JSON binary arrays are a non - standard extension it
2019-07-05 12:13:25 +08:00
was decided that it would be best to prevent automatic initialization of a
binary array type , for backwards compatibility and so it does not happen on
accident .
2020-05-19 19:08:18 +08:00
@ param [ in ] init container containing bytes to use as binary type
2019-07-05 12:13:25 +08:00
@ return JSON binary 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 .
@ since version 3.8 .0
*/
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-19 19:30:22 +08:00
static basic_json binary ( const typename binary_t : : container_type & init )
2019-07-05 12:13:25 +08:00
{
auto res = basic_json ( ) ;
res . m_type = value_t : : binary ;
res . m_value = init ;
return res ;
}
/*!
2020-05-19 19:08:18 +08:00
@ brief explicitly create a binary array ( with subtype )
2019-07-05 12:13:25 +08:00
2020-05-19 19:08:18 +08:00
Creates a JSON binary array value from a given binary container . Binary
values are part of various binary formats , such as CBOR , MessagePack , and
BSON . This constructor is used to create a value for serialization to those
formats .
2019-07-05 12:13:25 +08:00
@ note Note , this function exists because of the difficulty in correctly
specifying the correct template overload in the standard value ctor , as both
JSON arrays and JSON binary arrays are backed with some form of a
2020-05-19 19:08:18 +08:00
` std : : vector ` . Because JSON binary arrays are a non - standard extension it
2019-07-05 12:13:25 +08:00
was decided that it would be best to prevent automatic initialization of a
2020-05-19 19:08:18 +08:00
binary array type , for backwards compatibility and so it does not happen on
2019-07-05 12:13:25 +08:00
accident .
2020-05-19 19:08:18 +08:00
@ param [ in ] init container containing bytes to use as binary type
@ param [ in ] subtype subtype to use in MessagePack and BSON
2019-07-05 12:13:25 +08:00
@ return JSON binary 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 .
@ since version 3.8 .0
*/
JSON_HEDLEY_WARN_UNUSED_RESULT
2021-08-06 20:36:38 +08:00
static basic_json binary ( const typename binary_t : : container_type & init , typename binary_t : : subtype_type subtype )
2020-05-19 19:08:18 +08:00
{
auto res = basic_json ( ) ;
res . m_type = value_t : : binary ;
res . m_value = binary_t ( init , subtype ) ;
return res ;
}
2020-05-19 19:30:22 +08:00
/// @copydoc binary(const typename binary_t::container_type&)
2020-05-19 19:08:18 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-19 19:30:22 +08:00
static basic_json binary ( typename binary_t : : container_type & & init )
2019-07-05 12:13:25 +08:00
{
auto res = basic_json ( ) ;
res . m_type = value_t : : binary ;
res . m_value = std : : move ( init ) ;
return res ;
}
2021-08-06 20:36:38 +08:00
/// @copydoc binary(const typename binary_t::container_type&, typename binary_t::subtype_type)
2020-05-07 03:23:45 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2021-08-06 20:36:38 +08:00
static basic_json binary ( typename binary_t : : container_type & & init , typename binary_t : : subtype_type subtype )
2020-05-07 03:23:45 +08:00
{
auto res = basic_json ( ) ;
res . m_type = value_t : : binary ;
2020-05-18 04:50:27 +08:00
res . m_value = binary_t ( std : : move ( init ) , subtype ) ;
2020-05-07 03:23:45 +08:00
return res ;
}
2018-01-10 01:30:02 +08:00
/*!
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref basic_json ( initializer_list_t , bool , value_t ) - -
2018-01-10 01:30:02 +08:00
create a JSON value from an initializer list
2021-03-24 14:15:18 +08:00
@ sa see @ ref object ( initializer_list_t ) - - create a JSON object
2018-01-10 01:30:02 +08:00
value from an initializer list
@ since version 1.0 .0
*/
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2018-01-10 01:30:02 +08:00
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref basic_json ( initializer_list_t , bool , value_t ) - -
2018-01-10 01:30:02 +08:00
create a JSON value from an initializer list
2021-03-24 14:15:18 +08:00
@ sa see @ ref array ( initializer_list_t ) - - create a JSON array
2018-01-10 01:30:02 +08:00
value from an initializer list
@ since version 1.0 .0
*/
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2018-01-10 01:30:02 +08:00
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 ) ;
2021-01-15 04:55:49 +08:00
set_parents ( ) ;
2018-01-10 01:30:02 +08:00
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
*/
2020-06-03 20:20:36 +08:00
template < class InputIT , typename std : : enable_if <
std : : is_same < InputIT , typename basic_json_t : : iterator > : : value | |
std : : is_same < InputIT , typename basic_json_t : : const_iterator > : : value , int > : : type = 0 >
2018-01-10 01:30:02 +08:00
basic_json ( InputIT first , InputIT last )
{
2020-07-06 18:22:31 +08:00
JSON_ASSERT ( first . m_object ! = nullptr ) ;
JSON_ASSERT ( last . m_object ! = nullptr ) ;
2018-01-10 01:30:02 +08:00
// make sure iterator fits the current value
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( first . m_object ! = last . m_object ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 201 , " iterators are not compatible " , basic_json ( ) ) ) ;
2018-01-10 01:30:02 +08:00
}
// 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 :
{
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! first . m_it . primitive_iterator . is_begin ( )
| | ! last . m_it . primitive_iterator . is_end ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 204 , " iterators out of range " , * first . m_object ) ) ;
2018-01-10 01:30:02 +08:00
}
break ;
}
2021-08-13 19:43:51 +08:00
case value_t : : null :
case value_t : : object :
case value_t : : array :
case value_t : : binary :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
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 ;
}
2019-07-05 12:13:25 +08:00
case value_t : : binary :
{
2020-05-09 20:16:49 +08:00
m_value = * first . m_object - > m_value . binary ;
2019-07-05 12:13:25 +08:00
break ;
}
2021-08-13 19:43:51 +08:00
case value_t : : null :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
default :
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 206 , " cannot construct with iterators from " + std : : string ( first . m_object - > type_name ( ) ) , * first . m_object ) ) ;
2018-01-10 01:30:02 +08:00
}
2021-01-15 04:55:49 +08:00
set_parents ( ) ;
2018-01-10 01:30:02 +08:00
assert_invariant ( ) ;
}
///////////////////////////////////////
// other constructors and destructor //
///////////////////////////////////////
2020-06-03 20:20:36 +08:00
template < typename JsonRef ,
detail : : enable_if_t < detail : : conjunction < detail : : is_json_ref < JsonRef > ,
std : : is_same < typename JsonRef : : value_type , basic_json > > : : value , int > = 0 >
2020-04-13 03:32:39 +08:00
basic_json ( const JsonRef & ref ) : basic_json ( ref . moved_or_copied ( ) ) { }
2018-01-10 01:30:02 +08:00
/*!
@ 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 ;
}
2019-07-05 12:13:25 +08:00
case value_t : : binary :
{
m_value = * other . m_value . binary ;
break ;
}
2021-08-12 22:33:41 +08:00
case value_t : : null :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
default :
break ;
}
2021-01-15 04:55:49 +08:00
set_parents ( ) ;
2018-01-10 01:30:02 +08:00
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
2021-01-11 05:40:50 +08:00
other . assert_invariant ( false ) ;
2018-01-10 01:30:02 +08:00
// invalidate payload
other . m_type = value_t : : null ;
other . m_value = { } ;
2021-01-15 04:55:49 +08:00
set_parents ( ) ;
2018-01-10 01:30:02 +08:00
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 (
2020-06-03 20:20:36 +08:00
std : : is_nothrow_move_constructible < value_t > : : value & &
std : : is_nothrow_move_assignable < value_t > : : value & &
std : : is_nothrow_move_constructible < json_value > : : value & &
2018-01-10 01:30:02 +08:00
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 ) ;
2021-01-15 04:55:49 +08:00
set_parents ( ) ;
2018-01-10 01:30:02 +08:00
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
{
2021-01-11 05:40:50 +08:00
assert_invariant ( false ) ;
2018-01-10 01:30:02 +08:00
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 ) ,
2020-06-30 19:59:43 +08:00
and ` ignore ` ( ignore invalid UTF - 8 sequences during serialization ; all
bytes are copied to the output unchanged ) .
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
2020-05-18 19:53:20 +08:00
UTF - 8 encoded and @ a error_handler is set to strict
@ note Binary values are serialized as object containing two keys :
- " bytes " : an array of bytes as integers
- " subtype " : the subtype as integer or " null " if the binary has no subtype
2018-01-10 01:30:02 +08:00
@ 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
2020-05-18 19:53:20 +08:00
handlers added in version 3.4 .0 ; serialization of binary values added
in version 3.8 .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 ,
2020-05-18 19:53:20 +08:00
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 )
{
2020-05-18 19:53:20 +08:00
s . dump ( * this , true , ensure_ascii , static_cast < unsigned int > ( indent ) ) ;
2018-01-10 01:30:02 +08:00
}
else
{
2020-05-18 19:53:20 +08:00
s . dump ( * this , false , ensure_ascii , 0 ) ;
2018-01-10 01:30:02 +08:00
}
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
2019-07-05 12:13:25 +08:00
binary | value_t : : binary
2018-01-10 01:30:02 +08:00
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref operator value_t ( ) - - return the type of the JSON value ( implicit )
@ sa see @ ref type_name ( ) - - return the type as string
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_structured ( ) - - returns whether JSON value is structured
@ sa see @ ref is_null ( ) - - returns whether JSON value is ` null `
@ sa see @ ref is_string ( ) - - returns whether JSON value is a string
@ sa see @ ref is_boolean ( ) - - returns whether JSON value is a boolean
@ sa see @ ref is_number ( ) - - returns whether JSON value is a number
@ sa see @ ref is_binary ( ) - - returns whether JSON value is a binary array
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
constexpr bool is_primitive ( ) const noexcept
{
2020-06-03 20:20:36 +08:00
return is_null ( ) | | is_string ( ) | | is_boolean ( ) | | is_number ( ) | | is_binary ( ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_primitive ( ) - - returns whether value is primitive
@ sa see @ ref is_array ( ) - - returns whether value is an array
@ sa see @ ref is_object ( ) - - returns whether value is an object
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
constexpr bool is_structured ( ) const noexcept
{
2020-06-03 20:20:36 +08:00
return is_array ( ) | | is_object ( ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2019-03-18 20:53:48 +08:00
return m_type = = value_t : : null ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2019-03-18 20:53:48 +08:00
return m_type = = value_t : : boolean ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_number_integer ( ) - - check if value is an integer or unsigned
2018-01-10 01:30:02 +08:00
integer number
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_number_unsigned ( ) - - check if value is an unsigned integer
2018-01-10 01:30:02 +08:00
number
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_number_float ( ) - - check if value is a floating - point number
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
constexpr bool is_number ( ) const noexcept
{
2020-06-03 20:20:36 +08:00
return is_number_integer ( ) | | is_number_float ( ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_number ( ) - - check if value is a number
@ sa see @ ref is_number_unsigned ( ) - - check if value is an unsigned integer
2018-01-10 01:30:02 +08:00
number
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_number_float ( ) - - check if value is a floating - point number
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
constexpr bool is_number_integer ( ) const noexcept
{
2020-06-03 20:20:36 +08:00
return m_type = = value_t : : number_integer | | m_type = = value_t : : number_unsigned ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_number ( ) - - check if value is a number
@ sa see @ ref is_number_integer ( ) - - check if value is an integer or unsigned
2018-01-10 01:30:02 +08:00
integer number
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_number_float ( ) - - check if value is a floating - point number
2018-01-10 01:30:02 +08:00
@ since version 2.0 .0
*/
constexpr bool is_number_unsigned ( ) const noexcept
{
2019-03-18 20:53:48 +08:00
return m_type = = value_t : : number_unsigned ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_number ( ) - - check if value is number
@ sa see @ ref is_number_integer ( ) - - check if value is an integer number
@ sa see @ ref is_number_unsigned ( ) - - check if value is an unsigned integer
2018-01-10 01:30:02 +08:00
number
@ since version 1.0 .0
*/
constexpr bool is_number_float ( ) const noexcept
{
2019-03-18 20:53:48 +08:00
return m_type = = value_t : : number_float ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2019-03-18 20:53:48 +08:00
return m_type = = value_t : : object ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2019-03-18 20:53:48 +08:00
return m_type = = value_t : : array ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2019-03-18 20:53:48 +08:00
return m_type = = value_t : : string ;
2018-01-10 01:30:02 +08:00
}
2019-07-05 12:13:25 +08:00
/*!
@ brief return whether value is a binary array
This function returns true if and only if the JSON value is a binary array .
@ return ` true ` if type is binary array , ` false ` otherwise .
@ complexity Constant .
@ exceptionsafety No - throw guarantee : this member function never throws
exceptions .
@ liveexample { The following code exemplifies ` is_binary ( ) ` for all JSON
types . , is_binary }
@ since version 3.8 .0
*/
constexpr bool is_binary ( ) const noexcept
{
return m_type = = value_t : : binary ;
}
2018-01-10 01:30:02 +08:00
/*!
@ 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
{
2019-03-18 20:53:48 +08:00
return m_type = = value_t : : discarded ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref type ( ) - - return the type of the JSON value ( explicit )
@ sa see @ ref type_name ( ) - - return the type as string
2018-01-10 01:30:02 +08:00
@ 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
{
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_boolean ( ) ) )
2018-01-10 01:30:02 +08:00
{
return m_value . boolean ;
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 302 , " type must be boolean, but is " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
/// 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 ;
}
2019-07-05 12:13:25 +08:00
/// get a pointer to the value (binary)
2020-05-18 04:50:27 +08:00
binary_t * get_impl_ptr ( binary_t * /*unused*/ ) noexcept
2020-04-27 20:43:49 +08:00
{
return is_binary ( ) ? m_value . binary : nullptr ;
}
/// get a pointer to the value (binary)
2020-05-18 04:50:27 +08:00
constexpr const binary_t * get_impl_ptr ( const binary_t * /*unused*/ ) const noexcept
2020-04-27 20:43:49 +08:00
{
return is_binary ( ) ? m_value . binary : nullptr ;
}
2018-01-10 01:30:02 +08:00
/*!
@ 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<>()
2021-03-24 14:15:18 +08:00
auto * ptr = obj . template get_ptr < typename std : : add_pointer < ReferenceType > : : type > ( ) ;
2018-01-10 01:30:02 +08:00
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( ptr ! = nullptr ) )
2018-01-10 01:30:02 +08:00
{
return * ptr ;
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 303 , " incompatible ReferenceType for get_ref, actual type is " + std : : string ( obj . type_name ( ) ) , obj ) ) ;
2018-01-10 01:30:02 +08:00
}
public :
/// @name value access
/// Direct access to the stored value of a JSON value.
/// @{
/*!
2021-01-13 01:28:47 +08:00
@ brief get a pointer value ( implicit )
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
Implicit pointer access to the internally stored JSON value . No copies are
made .
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
@ warning Writing data to the pointee of the result yields an undefined
state .
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +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 ,
@ ref number_unsigned_t , or @ ref number_float_t . Enforced by a static
assertion .
@ return pointer to the internally stored JSON value if the requested
pointer type @ a PointerType fits to the JSON value ; ` nullptr ` otherwise
2018-01-10 01:30:02 +08:00
@ complexity Constant .
2021-01-13 01:28:47 +08:00
@ 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
match . , get_ptr }
@ since version 1.0 .0
2018-01-10 01:30:02 +08:00
*/
2021-01-13 01:28:47 +08:00
template < typename PointerType , typename std : : enable_if <
std : : is_pointer < PointerType > : : value , int > : : type = 0 >
auto get_ptr ( ) noexcept - > decltype ( std : : declval < basic_json_t & > ( ) . get_impl_ptr ( std : : declval < PointerType > ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-13 01:28:47 +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-02-27 19:11:04 +08:00
/*!
2021-01-13 01:28:47 +08:00
@ brief get a pointer value ( implicit )
@ copydoc get_ptr ( )
2018-02-27 19:11:04 +08:00
*/
2021-01-13 01:28:47 +08:00
template < typename PointerType , typename std : : enable_if <
std : : is_pointer < PointerType > : : value & &
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-02-27 19:11:04 +08:00
{
2021-01-13 01:28:47 +08:00
// delegate the call to get_impl_ptr<>() const
return get_impl_ptr ( static_cast < PointerType > ( nullptr ) ) ;
2018-02-27 19:11:04 +08:00
}
2021-01-13 01:28:47 +08:00
private :
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 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
*/
2021-01-13 07:12:51 +08:00
template < typename ValueType ,
2020-06-03 20:20:36 +08:00
detail : : enable_if_t <
2021-01-13 07:12:51 +08:00
detail : : is_default_constructible < ValueType > : : value & &
2021-01-13 01:28:47 +08:00
detail : : has_from_json < basic_json_t , ValueType > : : value ,
2020-06-03 20:20:36 +08:00
int > = 0 >
2021-01-13 01:28:47 +08:00
ValueType get_impl ( detail : : priority_tag < 0 > /*unused*/ ) const noexcept ( noexcept (
JSONSerializer < ValueType > : : from_json ( std : : declval < const basic_json_t & > ( ) , std : : declval < ValueType & > ( ) ) ) )
2018-01-10 01:30:02 +08:00
{
2021-03-24 14:15:18 +08:00
ValueType ret { } ;
2018-01-10 01:30:02 +08:00
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 }
2021-01-13 07:12:51 +08:00
return JSONSerializer < ValueType > : : from_json ( * this ) ;
2018-01-10 01:30:02 +08:00
@ 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 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
*/
2021-01-13 07:12:51 +08:00
template < typename ValueType ,
2021-01-13 01:28:47 +08:00
detail : : enable_if_t <
detail : : has_non_default_from_json < basic_json_t , ValueType > : : value ,
int > = 0 >
ValueType get_impl ( detail : : priority_tag < 1 > /*unused*/ ) const noexcept ( noexcept (
JSONSerializer < ValueType > : : from_json ( std : : declval < const basic_json_t & > ( ) ) ) )
2018-01-10 01:30:02 +08:00
{
2019-10-30 21:54:52 +08:00
return JSONSerializer < ValueType > : : from_json ( * this ) ;
2018-01-10 01:30:02 +08:00
}
2018-09-10 18:56:24 +08:00
/*!
2021-01-13 01:28:47 +08:00
@ brief get special - case overload
2018-09-10 18:56:24 +08:00
2021-01-13 01:28:47 +08:00
This overloads converts the current @ ref basic_json in a different
@ ref basic_json type
2018-09-10 18:56:24 +08:00
2021-01-13 01:28:47 +08:00
@ tparam BasicJsonType = = @ ref basic_json
2018-09-10 18:56:24 +08:00
2021-03-24 19:33:57 +08:00
@ return a copy of * this , converted into @ a BasicJsonType
2018-09-10 18:56:24 +08:00
2021-01-13 01:28:47 +08:00
@ complexity Depending on the implementation of the called ` from_json ( ) `
method .
2018-09-10 18:56:24 +08:00
2021-01-13 01:28:47 +08:00
@ since version 3.2 .0
2018-09-10 18:56:24 +08:00
*/
2021-01-13 07:12:51 +08:00
template < typename BasicJsonType ,
2020-06-03 20:20:36 +08:00
detail : : enable_if_t <
2021-01-13 01:28:47 +08:00
detail : : is_basic_json < BasicJsonType > : : value ,
2020-06-03 20:20:36 +08:00
int > = 0 >
2021-01-13 01:28:47 +08:00
BasicJsonType get_impl ( detail : : priority_tag < 2 > /*unused*/ ) const
2018-09-10 18:56:24 +08:00
{
2021-01-13 01:28:47 +08:00
return * this ;
2018-09-10 18:56:24 +08:00
}
2021-01-13 01:28:47 +08:00
/*!
@ 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
*/
2021-01-13 07:12:51 +08:00
template < typename BasicJsonType ,
detail : : enable_if_t <
2021-01-13 01:28:47 +08:00
std : : is_same < BasicJsonType , basic_json_t > : : value ,
2020-06-30 20:26:52 +08:00
int > = 0 >
2021-01-13 01:28:47 +08:00
basic_json get_impl ( detail : : priority_tag < 3 > /*unused*/ ) const
2020-06-30 20:26:52 +08:00
{
2021-01-13 01:28:47 +08:00
return * this ;
2020-06-30 20:26:52 +08:00
}
2021-01-13 01:28:47 +08:00
/*!
@ brief get a pointer value ( explicit )
@ copydoc get ( )
*/
2021-01-13 07:12:51 +08:00
template < typename PointerType ,
detail : : enable_if_t <
std : : is_pointer < PointerType > : : value ,
int > = 0 >
2021-01-13 01:28:47 +08:00
constexpr auto get_impl ( detail : : priority_tag < 4 > /*unused*/ ) const noexcept
- > decltype ( std : : declval < const basic_json_t & > ( ) . template get_ptr < PointerType > ( ) )
2019-04-01 19:32:06 +08:00
{
2021-01-13 01:28:47 +08:00
// delegate the call to get_ptr
return get_ptr < PointerType > ( ) ;
2019-04-01 19:32:06 +08:00
}
2021-01-13 01:28:47 +08:00
public :
2018-01-10 01:30:02 +08:00
/*!
2021-01-13 01:28:47 +08:00
@ brief get a ( pointer ) value ( explicit )
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
Performs explicit type conversion between the JSON value and a compatible value if required .
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
- If the requested type is a pointer to the internally stored JSON value that pointer is returned .
No copies are made .
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
- If the requested type is the current @ ref basic_json , or a different @ ref basic_json convertible
from the current @ ref basic_json .
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
- Otherwise the value is converted by calling the @ ref json_serializer < ValueType > ` from_json ( ) `
method .
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
@ tparam ValueTypeCV the provided value type
@ tparam ValueType the returned value type
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
@ return copy of the JSON value , converted to @ tparam ValueType if necessary
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
@ throw what @ ref json_serializer < ValueType > ` from_json ( ) ` method throws if conversion is required
2018-01-10 01:30:02 +08:00
2021-01-13 01:28:47 +08:00
@ since version 2.1 .0
2018-01-10 01:30:02 +08:00
*/
2021-01-13 01:28:47 +08:00
template < typename ValueTypeCV , typename ValueType = detail : : uncvref_t < ValueTypeCV > >
2021-01-14 19:39:03 +08:00
# if defined(JSON_HAS_CPP_14)
constexpr
# endif
auto get ( ) const noexcept (
2021-01-13 07:12:51 +08:00
noexcept ( std : : declval < const basic_json_t & > ( ) . template get_impl < ValueType > ( detail : : priority_tag < 4 > { } ) ) )
- > decltype ( std : : declval < const basic_json_t & > ( ) . template get_impl < ValueType > ( detail : : priority_tag < 4 > { } ) )
2018-01-10 01:30:02 +08:00
{
2021-01-13 01:28:47 +08:00
// 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 ( ! std : : is_reference < ValueTypeCV > : : value ,
" get() cannot be used with reference types, you might want to use get_ref() " ) ;
return get_impl < ValueType > ( detail : : priority_tag < 4 > { } ) ;
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ 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
}
/*!
2021-01-13 01:28:47 +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
2018-01-10 01:30:02 +08:00
*/
2021-01-13 01:28:47 +08:00
template < typename ValueType ,
detail : : enable_if_t <
! detail : : is_basic_json < ValueType > : : value & &
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 ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-13 01:28:47 +08:00
JSONSerializer < ValueType > : : from_json ( * this , v ) ;
return v ;
}
// specialization to allow to call get_to with a basic_json value
// see https://github.com/nlohmann/json/issues/2175
template < typename ValueType ,
detail : : enable_if_t <
detail : : is_basic_json < ValueType > : : value ,
int > = 0 >
ValueType & get_to ( ValueType & v ) const
{
v = * this ;
return v ;
}
template <
typename T , std : : size_t N ,
2021-03-24 19:33:57 +08:00
typename Array = T ( & ) [ N ] , // NOLINT(cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays)
2021-01-13 01:28:47 +08:00
detail : : enable_if_t <
detail : : has_from_json < basic_json_t , Array > : : value , int > = 0 >
2021-03-24 19:33:57 +08:00
Array get_to ( T ( & v ) [ N ] ) const // NOLINT(cppcoreguidelines-avoid-c-arrays,hicpp-avoid-c-arrays,modernize-avoid-c-arrays)
2021-01-13 01:28:47 +08:00
noexcept ( noexcept ( JSONSerializer < Array > : : from_json (
std : : declval < const basic_json_t & > ( ) , v ) ) )
{
JSONSerializer < Array > : : from_json ( * this , v ) ;
return v ;
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 ( )
*/
2020-06-03 20:20:36 +08:00
template < typename ReferenceType , typename std : : enable_if <
std : : is_reference < ReferenceType > : : value & &
std : : is_const < typename std : : remove_reference < ReferenceType > : : type > : : value , int > : : type = 0 >
2018-01-10 01:30:02 +08:00
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 <
2021-06-18 01:17:43 +08:00
detail : : conjunction <
detail : : negation < std : : is_pointer < ValueType > > ,
detail : : negation < std : : is_same < ValueType , detail : : json_ref < basic_json > > > ,
detail : : negation < std : : is_same < ValueType , typename string_t : : value_type > > ,
detail : : negation < detail : : is_basic_json < ValueType > > ,
detail : : negation < std : : is_same < ValueType , std : : initializer_list < typename string_t : : value_type > > > ,
2020-06-03 20:20:36 +08:00
# if defined(JSON_HAS_CPP_17) && (defined(__GNUC__) || (defined(_MSC_VER) && _MSC_VER >= 1910 && _MSC_VER <= 1914))
2021-06-18 01:17:43 +08:00
detail : : negation < std : : is_same < ValueType , std : : string_view > > ,
2018-01-10 01:30:02 +08:00
# endif
2021-06-18 01:17:43 +08:00
detail : : is_detected_lazy < detail : : get_template_function , const basic_json_t & , ValueType >
> : : value , int > : : type = 0 >
JSON_EXPLICIT operator ValueType ( ) const
2018-01-10 01:30:02 +08:00
{
// delegate the call to get<>() const
return get < ValueType > ( ) ;
}
2020-05-18 04:50:27 +08:00
/*!
@ return reference to the binary value
@ throw type_error .302 if the value is not binary
2021-03-24 14:15:18 +08:00
@ sa see @ ref is_binary ( ) to check if the value is binary
2020-05-18 04:50:27 +08:00
@ since version 3.8 .0
*/
binary_t & get_binary ( )
{
2020-06-03 20:20:36 +08:00
if ( ! is_binary ( ) )
2020-05-18 04:50:27 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 302 , " type must be binary, but is " + std : : string ( type_name ( ) ) , * this ) ) ;
2020-05-18 04:50:27 +08:00
}
return * get_ptr < binary_t * > ( ) ;
}
/// @copydoc get_binary()
const binary_t & get_binary ( ) const
{
2020-06-03 20:20:36 +08:00
if ( ! is_binary ( ) )
2020-05-18 04:50:27 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 302 , " type must be binary, but is " + std : : string ( type_name ( ) ) , * this ) ) ;
2020-05-18 04:50:27 +08:00
}
return * get_ptr < const binary_t * > ( ) ;
}
2018-01-10 01:30:02 +08:00
/// @}
////////////////////
// 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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
JSON_TRY
{
2021-01-15 04:55:49 +08:00
return set_parent ( m_value . array - > at ( idx ) ) ;
2018-01-10 01:30:02 +08:00
}
JSON_CATCH ( std : : out_of_range & )
{
// create better exception explanation
2021-01-25 20:47:50 +08:00
JSON_THROW ( out_of_range : : create ( 401 , " array index " + std : : to_string ( idx ) + " is out of range " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 304 , " cannot use at() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
/*!
@ 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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
JSON_TRY
{
return m_value . array - > at ( idx ) ;
}
JSON_CATCH ( std : : out_of_range & )
{
// create better exception explanation
2021-01-25 20:47:50 +08:00
JSON_THROW ( out_of_range : : create ( 401 , " array index " + std : : to_string ( idx ) + " is out of range " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 304 , " cannot use at() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
/*!
@ 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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref operator [ ] ( const typename object_t : : key_type & ) for unchecked
2018-01-10 01:30:02 +08:00
access by reference
2021-03-24 14:15:18 +08:00
@ sa see @ ref value ( ) for access by value with a default value
2018-01-10 01:30:02 +08:00
@ 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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
JSON_TRY
{
2021-01-15 04:55:49 +08:00
return set_parent ( m_value . object - > at ( key ) ) ;
2018-01-10 01:30:02 +08:00
}
JSON_CATCH ( std : : out_of_range & )
{
// create better exception explanation
2021-01-25 20:47:50 +08:00
JSON_THROW ( out_of_range : : create ( 403 , " key ' " + key + " ' not found " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 304 , " cannot use at() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
/*!
@ 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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref operator [ ] ( const typename object_t : : key_type & ) for unchecked
2018-01-10 01:30:02 +08:00
access by reference
2021-03-24 14:15:18 +08:00
@ sa see @ ref value ( ) for access by value with a default value
2018-01-10 01:30:02 +08:00
@ 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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
JSON_TRY
{
return m_value . object - > at ( key ) ;
}
JSON_CATCH ( std : : out_of_range & )
{
// create better exception explanation
2021-01-25 20:47:50 +08:00
JSON_THROW ( out_of_range : : create ( 403 , " key ' " + key + " ' not found " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 304 , " cannot use at() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
/*!
@ 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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
// fill up array with null values if given idx is outside range
if ( idx > = m_value . array - > size ( ) )
{
2021-01-08 18:21:41 +08:00
# if JSON_DIAGNOSTICS
// remember array size before resizing
const auto previous_size = m_value . array - > size ( ) ;
# endif
m_value . array - > resize ( idx + 1 ) ;
2021-01-15 23:58:05 +08:00
# if JSON_DIAGNOSTICS
2021-01-08 18:10:24 +08:00
// set parent for values added above
2021-01-17 20:32:26 +08:00
set_parents ( begin ( ) + static_cast < typename iterator : : difference_type > ( previous_size ) , static_cast < typename iterator : : difference_type > ( idx + 1 - previous_size ) ) ;
2021-01-15 23:58:05 +08:00
# endif
2018-01-10 01:30:02 +08:00
}
return m_value . array - > operator [ ] ( idx ) ;
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a numeric argument with " + std : : string ( type_name ( ) ) , * this ) ) ;
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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
return m_value . array - > operator [ ] ( idx ) ;
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a numeric argument with " + std : : string ( type_name ( ) ) , * this ) ) ;
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref at ( const typename object_t : : key_type & ) for access by reference
2018-01-10 01:30:02 +08:00
with range checking
2021-03-24 14:15:18 +08:00
@ sa see @ ref value ( ) for access by value with a default value
2018-01-10 01:30:02 +08:00
@ 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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-15 04:55:49 +08:00
return set_parent ( m_value . object - > operator [ ] ( key ) ) ;
2018-01-10 01:30:02 +08:00
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a string argument with " + std : : string ( type_name ( ) ) , * this ) ) ;
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref at ( const typename object_t : : key_type & ) for access by reference
2018-01-10 01:30:02 +08:00
with range checking
2021-03-24 14:15:18 +08:00
@ sa see @ ref value ( ) for access by value with a default value
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0
*/
const_reference operator [ ] ( const typename object_t : : key_type & key ) const
{
// const operator[] only works for objects
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2020-07-06 18:22:31 +08:00
JSON_ASSERT ( m_value . object - > find ( key ) ! = m_value . object - > end ( ) ) ;
2018-01-10 01:30:02 +08:00
return m_value . object - > find ( key ) - > second ;
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a string argument with " + std : : string ( type_name ( ) ) , * this ) ) ;
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref at ( const typename object_t : : key_type & ) for access by reference
2018-01-10 01:30:02 +08:00
with range checking
2021-03-24 14:15:18 +08:00
@ sa see @ ref value ( ) for access by value with a default value
2018-01-10 01:30:02 +08:00
@ since version 1.1 .0
*/
template < typename T >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_NON_NULL ( 2 )
2018-01-10 01:30:02 +08:00
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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-15 04:55:49 +08:00
return set_parent ( m_value . object - > operator [ ] ( key ) ) ;
2018-01-10 01:30:02 +08:00
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a string argument with " + std : : string ( type_name ( ) ) , * this ) ) ;
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref at ( const typename object_t : : key_type & ) for access by reference
2018-01-10 01:30:02 +08:00
with range checking
2021-03-24 14:15:18 +08:00
@ sa see @ ref value ( ) for access by value with a default value
2018-01-10 01:30:02 +08:00
@ since version 1.1 .0
*/
template < typename T >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_NON_NULL ( 2 )
2018-01-10 01:30:02 +08:00
const_reference operator [ ] ( T * key ) const
{
// at only works for objects
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2020-07-06 18:22:31 +08:00
JSON_ASSERT ( m_value . object - > find ( key ) ! = m_value . object - > end ( ) ) ;
2018-01-10 01:30:02 +08:00
return m_value . object - > find ( key ) - > second ;
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 305 , " cannot use operator[] with a string argument with " + std : : string ( type_name ( ) ) , * this ) ) ;
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
2019-06-22 15:44:12 +08:00
@ throw type_error .302 if @ a default_value does not match the type of the
value at @ a key
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref at ( const typename object_t : : key_type & ) for access by reference
2018-01-10 01:30:02 +08:00
with range checking
2021-03-24 14:15:18 +08:00
@ sa see @ ref operator [ ] ( const typename object_t : : key_type & ) for unchecked
2018-01-10 01:30:02 +08:00
access by reference
@ since version 1.0 .0
*/
2020-07-16 17:11:35 +08:00
// using std::is_convertible in a std::enable_if will fail when using explicit conversions
2020-06-03 20:20:36 +08:00
template < class ValueType , typename std : : enable_if <
2020-07-16 17:11:35 +08:00
detail : : is_getable < basic_json_t , ValueType > : : value
2020-06-03 20:20:36 +08:00
& & ! std : : is_same < value_t , ValueType > : : value , int > : : type = 0 >
2020-07-08 20:02:28 +08:00
ValueType value ( const typename object_t : : key_type & key , const ValueType & default_value ) const
2018-01-10 01:30:02 +08:00
{
// at only works for objects
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
// if key is found, return value and given default value otherwise
const auto it = find ( key ) ;
if ( it ! = end ( ) )
{
2020-07-16 17:11:35 +08:00
return it - > template get < ValueType > ( ) ;
2018-01-10 01:30:02 +08:00
}
2020-07-08 20:02:28 +08:00
return default_value ;
2018-01-10 01:30:02 +08:00
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 306 , " cannot use value() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2020-07-08 20:02:28 +08:00
return value ( key , string_t ( default_value ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
2019-06-22 15:44:12 +08:00
@ throw type_error .302 if @ a default_value does not match the type of the
value at @ a ptr
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref operator [ ] ( const json_pointer & ) for unchecked access by reference
2018-01-10 01:30:02 +08:00
@ since version 2.0 .2
*/
template < class ValueType , typename std : : enable_if <
2020-07-16 17:11:35 +08:00
detail : : is_getable < basic_json_t , ValueType > : : value , int > : : type = 0 >
2020-07-08 20:02:28 +08:00
ValueType value ( const json_pointer & ptr , const ValueType & default_value ) const
2018-01-10 01:30:02 +08:00
{
// at only works for objects
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
// if pointer resolves a value, return it or use default value
JSON_TRY
{
2020-07-16 17:11:35 +08:00
return ptr . get_checked ( this ) . template get < ValueType > ( ) ;
2018-01-10 01:30:02 +08:00
}
2018-07-19 14:43:41 +08:00
JSON_INTERNAL_CATCH ( out_of_range & )
2018-01-10 01:30:02 +08:00
{
2020-07-08 20:02:28 +08:00
return default_value ;
2018-01-10 01:30:02 +08:00
}
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 306 , " cannot use value() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief overload for a default value of type const char *
@ copydoc basic_json : : value ( const json_pointer & , ValueType ) const
*/
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_NON_NULL ( 3 )
2018-01-10 01:30:02 +08:00
string_t value ( const json_pointer & ptr , const char * default_value ) const
{
2020-07-08 20:02:28 +08:00
return value ( ptr , string_t ( default_value ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
2019-07-05 12:13:25 +08:00
first element is returned . In case of number , string , boolean , or binary
values , a reference to the value is returned .
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref back ( ) - - access the last element
2018-01-10 01:30:02 +08:00
@ 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
2019-07-05 12:13:25 +08:00
last element is returned . In case of number , string , boolean , or binary
values , a reference to the value is returned .
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref front ( ) - - access the first element
2018-01-10 01:30:02 +08:00
@ 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
2019-07-05 12:13:25 +08:00
- strings and binary : linear in the length of the member
2018-01-10 01:30:02 +08:00
- other types : constant
@ liveexample { The example shows the result of ` erase ( ) ` for different JSON
types . , erase__IteratorType }
2021-03-24 14:15:18 +08:00
@ sa see @ ref erase ( IteratorType , IteratorType ) - - removes the elements in
2018-01-10 01:30:02 +08:00
the given range
2021-03-24 14:15:18 +08:00
@ sa see @ ref erase ( const typename object_t : : key_type & ) - - removes the element
2018-01-10 01:30:02 +08:00
from an object at the given key
2021-03-24 14:15:18 +08:00
@ sa see @ ref erase ( const size_type ) - - removes the element from an array at
2018-01-10 01:30:02 +08:00
the given index
@ since version 1.0 .0
*/
2020-06-03 20:20:36 +08:00
template < class IteratorType , typename std : : enable_if <
std : : is_same < IteratorType , typename basic_json_t : : iterator > : : value | |
std : : is_same < IteratorType , typename basic_json_t : : const_iterator > : : value , int > : : type
= 0 >
2018-01-10 01:30:02 +08:00
IteratorType erase ( IteratorType pos )
{
// make sure iterator fits the current value
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( this ! = pos . m_object ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
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 :
2019-07-05 12:13:25 +08:00
case value_t : : binary :
2018-01-10 01:30:02 +08:00
{
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! pos . m_it . primitive_iterator . is_begin ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 205 , " iterator out of range " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
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 ;
}
2019-07-05 12:13:25 +08:00
else if ( is_binary ( ) )
{
2020-05-18 04:50:27 +08:00
AllocatorType < binary_t > alloc ;
2019-07-05 12:13:25 +08:00
std : : allocator_traits < decltype ( alloc ) > : : destroy ( alloc , m_value . binary ) ;
std : : allocator_traits < decltype ( alloc ) > : : deallocate ( alloc , m_value . binary , 1 ) ;
m_value . binary = nullptr ;
}
2018-01-10 01:30:02 +08:00
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 ;
}
2021-08-12 22:33:41 +08:00
case value_t : : null :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
default :
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 307 , " cannot use erase() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
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
2019-07-05 12:13:25 +08:00
- strings and binary : linear in the length of the member
2018-01-10 01:30:02 +08:00
- other types : constant
@ liveexample { The example shows the result of ` erase ( ) ` for different JSON
types . , erase__IteratorType_IteratorType }
2021-03-24 14:15:18 +08:00
@ sa see @ ref erase ( IteratorType ) - - removes the element at a given position
@ sa see @ ref erase ( const typename object_t : : key_type & ) - - removes the element
2018-01-10 01:30:02 +08:00
from an object at the given key
2021-03-24 14:15:18 +08:00
@ sa see @ ref erase ( const size_type ) - - removes the element from an array at
2018-01-10 01:30:02 +08:00
the given index
@ since version 1.0 .0
*/
2020-06-03 20:20:36 +08:00
template < class IteratorType , typename std : : enable_if <
std : : is_same < IteratorType , typename basic_json_t : : iterator > : : value | |
std : : is_same < IteratorType , typename basic_json_t : : const_iterator > : : value , int > : : type
= 0 >
2018-01-10 01:30:02 +08:00
IteratorType erase ( IteratorType first , IteratorType last )
{
// make sure iterator fits the current value
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( this ! = first . m_object | | this ! = last . m_object ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 203 , " iterators do not fit current value " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
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 :
2019-07-05 12:13:25 +08:00
case value_t : : binary :
2018-01-10 01:30:02 +08:00
{
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_LIKELY ( ! first . m_it . primitive_iterator . is_begin ( )
| | ! last . m_it . primitive_iterator . is_end ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 204 , " iterators out of range " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
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 ;
}
2019-07-05 12:13:25 +08:00
else if ( is_binary ( ) )
{
2020-05-18 04:50:27 +08:00
AllocatorType < binary_t > alloc ;
2019-07-05 12:13:25 +08:00
std : : allocator_traits < decltype ( alloc ) > : : destroy ( alloc , m_value . binary ) ;
std : : allocator_traits < decltype ( alloc ) > : : deallocate ( alloc , m_value . binary , 1 ) ;
m_value . binary = nullptr ;
}
2018-01-10 01:30:02 +08:00
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 ;
}
2021-08-13 19:43:51 +08:00
case value_t : : null :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
default :
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 307 , " cannot use erase() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref erase ( IteratorType ) - - removes the element at a given position
@ sa see @ ref erase ( IteratorType , IteratorType ) - - removes the elements in
2018-01-10 01:30:02 +08:00
the given range
2021-03-24 14:15:18 +08:00
@ sa see @ ref erase ( const size_type ) - - removes the element from an array at
2018-01-10 01:30:02 +08:00
the given index
@ since version 1.0 .0
*/
size_type erase ( const typename object_t : : key_type & key )
{
// this erase only works for objects
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
return m_value . object - > erase ( key ) ;
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 307 , " cannot use erase() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref erase ( IteratorType ) - - removes the element at a given position
@ sa see @ ref erase ( IteratorType , IteratorType ) - - removes the elements in
2018-01-10 01:30:02 +08:00
the given range
2021-03-24 14:15:18 +08:00
@ sa see @ ref erase ( const typename object_t : : key_type & ) - - removes the element
2018-01-10 01:30:02 +08:00
from an object at the given key
@ since version 1.0 .0
*/
void erase ( const size_type idx )
{
// this erase only works for arrays
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( idx > = size ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( out_of_range : : create ( 401 , " array index " + std : : to_string ( idx ) + " is out of range " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
m_value . array - > erase ( m_value . array - > begin ( ) + static_cast < difference_type > ( idx ) ) ;
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 307 , " cannot use erase() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
/// @}
////////////
// 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref contains ( KeyT & & ) const - - checks whether a key exists
2019-03-18 05:25:18 +08:00
2018-01-10 01:30:02 +08:00
@ 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 ;
}
2019-02-10 21:10:30 +08:00
/*!
@ brief check the existence of an element in a JSON object
Check whether an element exists in a JSON object with key equivalent to
@ a key . If the element is not found or the JSON value is not an object ,
false is returned .
@ note This method always returns false when executed on a JSON type
that is not an object .
@ param [ in ] key key value to check its existence .
@ return true if an element with specified @ a key exists . If no such
element with such key is found or the JSON value is not an object ,
false is returned .
@ complexity Logarithmic in the size of the JSON object .
2019-03-18 05:25:18 +08:00
@ liveexample { The following code shows an example for ` contains ( ) ` . , contains }
2021-03-24 14:15:18 +08:00
@ sa see @ ref find ( KeyT & & ) - - returns an iterator to an object element
@ sa see @ ref contains ( const json_pointer & ) const - - checks the existence for a JSON pointer
2019-03-18 05:25:18 +08:00
2019-02-10 21:10:30 +08:00
@ since version 3.6 .0
*/
2020-06-03 20:20:36 +08:00
template < typename KeyT , typename std : : enable_if <
! std : : is_same < typename std : : decay < KeyT > : : type , json_pointer > : : value , int > : : type = 0 >
2019-06-30 16:03:08 +08:00
bool contains ( KeyT & & key ) const
2019-02-10 21:10:30 +08:00
{
2020-06-03 20:20:36 +08:00
return is_object ( ) & & m_value . object - > find ( std : : forward < KeyT > ( key ) ) ! = m_value . object - > end ( ) ;
2019-02-10 21:10:30 +08:00
}
2019-06-30 16:03:08 +08:00
/*!
@ brief check the existence of an element in a JSON object given a JSON pointer
2019-10-19 17:59:46 +08:00
Check whether the given JSON pointer @ a ptr can be resolved in the current
2019-06-30 16:03:08 +08:00
JSON value .
@ note This method can be executed on any JSON value type .
@ param [ in ] ptr JSON pointer to check its existence .
@ return true if the JSON pointer can be resolved to a stored value , false
otherwise .
@ post If ` j . contains ( ptr ) ` returns true , it is safe to call ` j [ ptr ] ` .
@ throw parse_error .106 if an array index begins with ' 0 '
@ throw parse_error .109 if an array index was not a number
@ complexity Logarithmic in the size of the JSON object .
@ liveexample { The following code shows an example for ` contains ( ) ` . , contains_json_pointer }
2021-03-24 14:15:18 +08:00
@ sa see @ ref contains ( KeyT & & ) const - - checks the existence of a key
2019-06-30 16:03:08 +08:00
@ since version 3.7 .0
*/
bool contains ( const json_pointer & ptr ) const
{
return ptr . contains ( this ) ;
}
2018-01-10 01:30:02 +08:00
/// @}
///////////////
// 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref cbegin ( ) - - returns a const iterator to the beginning
@ sa see @ ref end ( ) - - returns an iterator to the end
@ sa see @ ref cend ( ) - - returns a const iterator to the end
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref begin ( ) - - returns an iterator to the beginning
@ sa see @ ref end ( ) - - returns an iterator to the end
@ sa see @ ref cend ( ) - - returns a const iterator to the end
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref cend ( ) - - returns a const iterator to the end
@ sa see @ ref begin ( ) - - returns an iterator to the beginning
@ sa see @ ref cbegin ( ) - - returns a const iterator to the beginning
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref end ( ) - - returns an iterator to the end
@ sa see @ ref begin ( ) - - returns an iterator to the beginning
@ sa see @ ref cbegin ( ) - - returns a const iterator to the beginning
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref crbegin ( ) - - returns a const reverse iterator to the beginning
@ sa see @ ref rend ( ) - - returns a reverse iterator to the end
@ sa see @ ref crend ( ) - - returns a const reverse iterator to the end
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref crend ( ) - - returns a const reverse iterator to the end
@ sa see @ ref rbegin ( ) - - returns a reverse iterator to the beginning
@ sa see @ ref crbegin ( ) - - returns a const reverse iterator to the beginning
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref rbegin ( ) - - returns a reverse iterator to the beginning
@ sa see @ ref rend ( ) - - returns a reverse iterator to the end
@ sa see @ ref crend ( ) - - returns a const reverse iterator to the end
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref rend ( ) - - returns a reverse iterator to the end
@ sa see @ ref rbegin ( ) - - returns a reverse iterator to the beginning
@ sa see @ ref crbegin ( ) - - returns a const reverse iterator to the beginning
2018-01-10 01:30:02 +08:00
@ 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
*/
2020-06-06 20:30:17 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.1 .0 , items ( ) )
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 )
*/
2020-06-06 20:30:17 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.1 .0 , items ( ) )
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
2020-05-15 01:06:48 +08:00
@ warning Using ` items ( ) ` on temporary objects is dangerous . Make sure the
object ' s lifetime exeeds the iteration . See
< https : //github.com/nlohmann/json/issues/2040> for more
information .
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 `
2019-07-05 12:13:25 +08:00
binary | ` false `
2018-01-10 01:30:02 +08:00
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 ( ) ` .
2021-03-24 14:15:18 +08:00
@ sa see @ ref size ( ) - - returns the number of elements
2018-01-10 01:30:02 +08:00
@ 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 ( ) ;
}
2021-08-13 19:43:51 +08:00
case value_t : : string :
case value_t : : boolean :
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : number_float :
case value_t : : binary :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
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 `
2019-07-05 12:13:25 +08:00
binary | ` 1 `
2018-01-10 01:30:02 +08:00
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 ( ) ) ` .
2021-03-24 14:15:18 +08:00
@ sa see @ ref empty ( ) - - checks whether the container is empty
@ sa see @ ref max_size ( ) - - returns the maximal number of elements
2018-01-10 01:30:02 +08:00
@ 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 ( ) ;
}
2021-08-12 22:33:41 +08:00
case value_t : : string :
case value_t : : boolean :
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : number_float :
case value_t : : binary :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
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 ( ) ` )
2019-07-05 12:13:25 +08:00
binary | ` 1 ` ( same as ` size ( ) ` )
2018-01-10 01:30:02 +08:00
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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref size ( ) - - returns the number of elements
2018-01-10 01:30:02 +08:00
@ 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 ( ) ;
}
2021-08-12 22:33:41 +08:00
case value_t : : null :
case value_t : : string :
case value_t : : boolean :
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : number_float :
case value_t : : binary :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
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 `
2019-07-05 12:13:25 +08:00
binary | An empty byte vector
2018-01-10 01:30:02 +08:00
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 .
2021-03-24 14:15:18 +08:00
@ sa see @ ref basic_json ( value_t ) - - constructor that creates an object with the
2018-01-10 01:30:02 +08:00
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 ;
}
2019-07-05 12:13:25 +08:00
case value_t : : binary :
{
m_value . binary - > clear ( ) ;
break ;
}
2018-01-10 01:30:02 +08:00
case value_t : : array :
{
m_value . array - > clear ( ) ;
break ;
}
case value_t : : object :
{
m_value . object - > clear ( ) ;
break ;
}
2021-08-13 19:43:51 +08:00
case value_t : : null :
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
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
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! ( is_null ( ) | | is_array ( ) ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 308 , " cannot use push_back() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// 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)
2021-07-13 21:27:27 +08:00
const auto old_capacity = m_value . array - > capacity ( ) ;
2018-01-10 01:30:02 +08:00
m_value . array - > push_back ( std : : move ( val ) ) ;
2021-07-13 21:27:27 +08:00
set_parent ( m_value . array - > back ( ) , old_capacity ) ;
2020-04-02 20:20:25 +08:00
// if val is moved from, basic_json move constructor marks it null so we do not call the destructor
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! ( is_null ( ) | | is_array ( ) ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 308 , " cannot use push_back() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// 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
2021-07-13 21:27:27 +08:00
const auto old_capacity = m_value . array - > capacity ( ) ;
2018-01-10 01:30:02 +08:00
m_value . array - > push_back ( val ) ;
2021-07-13 21:27:27 +08:00
set_parent ( m_value . array - > back ( ) , old_capacity ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! ( is_null ( ) | | is_object ( ) ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 308 , " cannot use push_back() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// transform null object into an object
if ( is_null ( ) )
{
m_type = value_t : : object ;
m_value = value_t : : object ;
assert_invariant ( ) ;
}
2021-01-02 00:23:10 +08:00
// add element to object
auto res = m_value . object - > insert ( val ) ;
2021-01-15 04:55:49 +08:00
set_parent ( res . first - > second ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 )
{
2020-06-03 20:20:36 +08:00
if ( is_object ( ) & & init . size ( ) = = 2 & & ( * init . begin ( ) ) - > is_string ( ) )
2018-01-10 01:30:02 +08:00
{
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
2019-06-30 18:19:41 +08:00
@ return reference to the inserted element
2018-01-10 01:30:02 +08:00
@ 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 }
2019-06-30 18:19:41 +08:00
@ since version 2.0 .8 , returns reference since 3.7 .0
2018-01-10 01:30:02 +08:00
*/
template < class . . . Args >
2019-06-30 18:19:41 +08:00
reference emplace_back ( Args & & . . . args )
2018-01-10 01:30:02 +08:00
{
// emplace_back only works for null objects or arrays
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! ( is_null ( ) | | is_array ( ) ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 311 , " cannot use emplace_back() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// 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)
2021-07-13 21:27:27 +08:00
const auto old_capacity = m_value . array - > capacity ( ) ;
2018-01-10 01:30:02 +08:00
m_value . array - > emplace_back ( std : : forward < Args > ( args ) . . . ) ;
2021-07-13 21:27:27 +08:00
return set_parent ( m_value . array - > back ( ) , old_capacity ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! ( is_null ( ) | | is_object ( ) ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 311 , " cannot use emplace() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// 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 ) . . . ) ;
2021-01-15 04:55:49 +08:00
set_parent ( res . first - > second ) ;
2021-01-03 04:36:11 +08:00
2018-01-10 01:30:02 +08:00
// 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 >
2021-07-12 21:24:06 +08:00
iterator insert_iterator ( const_iterator pos , Args & & . . . args )
2018-09-20 23:19:33 +08:00
{
iterator result ( this ) ;
2020-07-06 18:22:31 +08:00
JSON_ASSERT ( m_value . array ! = nullptr ) ;
2018-09-20 23:19:33 +08:00
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
2021-07-12 21:24:06 +08:00
set_parents ( ) ;
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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
// check if iterator pos fits to this JSON value
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( pos . m_object ! = this ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// insert to array and return iterator
2021-07-12 21:24:06 +08:00
return insert_iterator ( pos , val ) ;
2018-01-10 01:30:02 +08:00
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
// check if iterator pos fits to this JSON value
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( pos . m_object ! = this ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// insert to array and return iterator
2021-07-12 21:24:06 +08:00
return insert_iterator ( pos , cnt , val ) ;
2018-01-10 01:30:02 +08:00
}
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// check if iterator pos fits to this JSON value
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( pos . m_object ! = this ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// check if range iterators belong to the same JSON object
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( first . m_object ! = last . m_object ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 210 , " iterators do not fit " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( first . m_object = = this ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 211 , " passed iterators may not belong to container " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// insert to array and return iterator
2021-07-12 21:24:06 +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
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// check if iterator pos fits to this JSON value
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( pos . m_object ! = this ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 202 , " iterator does not fit current value " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// insert to array and return iterator
2021-07-12 21:24:06 +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
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 309 , " cannot use insert() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// check if range iterators belong to the same JSON object
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( first . m_object ! = last . m_object ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 210 , " iterators do not fit " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// passed iterators must belong to objects
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! first . m_object - > is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 202 , " iterators first and last must point to objects " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
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 ( ) ;
}
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 312 , " cannot use update() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! j . is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 312 , " cannot use update() with " + std : : string ( j . type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
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 ( ) ;
}
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 312 , " cannot use update() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// check if range iterators belong to the same JSON object
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( first . m_object ! = last . m_object ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 210 , " iterators do not fit " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
// passed iterators must belong to objects
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! first . m_object - > is_object ( )
| | ! last . m_object - > is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( invalid_iterator : : create ( 202 , " iterators first and last must point to objects " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
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 (
2020-06-03 20:20:36 +08:00
std : : is_nothrow_move_constructible < value_t > : : value & &
std : : is_nothrow_move_assignable < value_t > : : value & &
std : : is_nothrow_move_constructible < json_value > : : value & &
2018-01-10 01:30:02 +08:00
std : : is_nothrow_move_assignable < json_value > : : value
)
{
std : : swap ( m_type , other . m_type ) ;
std : : swap ( m_value , other . m_value ) ;
2021-01-11 05:40:50 +08:00
2021-01-15 04:55:49 +08:00
set_parents ( ) ;
2021-01-15 23:54:00 +08:00
other . set_parents ( ) ;
2018-01-10 01:30:02 +08:00
assert_invariant ( ) ;
}
/*!
@ brief exchanges the values
2020-06-06 23:36:39 +08:00
Exchanges the contents of the JSON value from @ a left with those of @ a right . 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 . implemented as a friend function callable via ADL .
@ param [ in , out ] left JSON value to exchange the contents with
@ param [ in , out ] right 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
*/
friend void swap ( reference left , reference right ) noexcept (
2020-07-11 19:51:25 +08:00
std : : is_nothrow_move_constructible < value_t > : : value & &
std : : is_nothrow_move_assignable < value_t > : : value & &
std : : is_nothrow_move_constructible < json_value > : : value & &
2020-06-06 23:36:39 +08:00
std : : is_nothrow_move_assignable < json_value > : : value
)
{
left . swap ( right ) ;
}
/*!
@ brief exchanges the values
2018-01-10 01:30:02 +08:00
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
*/
2021-03-24 14:15:18 +08:00
void swap ( array_t & other ) // NOLINT(bugprone-exception-escape)
2018-01-10 01:30:02 +08:00
{
// swap only works for arrays
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
std : : swap ( * ( m_value . array ) , other ) ;
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 310 , " cannot use swap() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
/*!
@ 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
*/
2021-03-24 14:15:18 +08:00
void swap ( object_t & other ) // NOLINT(bugprone-exception-escape)
2018-01-10 01:30:02 +08:00
{
// swap only works for objects
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
std : : swap ( * ( m_value . object ) , other ) ;
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 310 , " cannot use swap() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
/*!
@ 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
*/
2021-03-24 14:15:18 +08:00
void swap ( string_t & other ) // NOLINT(bugprone-exception-escape)
2018-01-10 01:30:02 +08:00
{
// swap only works for strings
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( is_string ( ) ) )
2018-01-10 01:30:02 +08:00
{
std : : swap ( * ( m_value . string ) , other ) ;
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 310 , " cannot use swap() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
2020-05-05 04:07:36 +08:00
/*!
@ 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 binary 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__binary_t }
@ since version 3.8 .0
*/
2021-03-24 14:15:18 +08:00
void swap ( binary_t & other ) // NOLINT(bugprone-exception-escape)
2020-05-05 04:07:36 +08:00
{
// swap only works for strings
if ( JSON_HEDLEY_LIKELY ( is_binary ( ) ) )
{
std : : swap ( * ( m_value . binary ) , other ) ;
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 310 , " cannot use swap() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2020-05-18 04:50:27 +08:00
}
}
2021-03-24 14:15:18 +08:00
/// @copydoc swap(binary_t&)
void swap ( typename binary_t : : container_type & other ) // NOLINT(bugprone-exception-escape)
2020-05-18 04:50:27 +08:00
{
// swap only works for strings
if ( JSON_HEDLEY_LIKELY ( is_binary ( ) ) )
{
std : : swap ( * ( m_value . binary ) , other ) ;
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( type_error : : create ( 310 , " cannot use swap() with " + std : : string ( type_name ( ) ) , * this ) ) ;
2020-05-05 04:07:36 +08:00
}
}
2018-01-10 01:30:02 +08:00
/// @}
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
2020-03-25 10:12:19 +08:00
comparison . Note that two NaN values are always treated as unequal .
2018-01-10 01:30:02 +08:00
- 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
2020-03-25 10:12:19 +08:00
[ comparison function ] ( https : //github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
2018-01-10 01:30:02 +08:00
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
2020-03-25 10:12:19 +08:00
Or you can self - defined operator equal function like this :
@ code { . cpp }
bool my_equal ( const_reference lhs , const_reference rhs ) {
2020-04-13 19:11:26 +08:00
const auto lhs_type lhs . type ( ) ;
const auto rhs_type rhs . type ( ) ;
if ( lhs_type = = rhs_type ) {
switch ( lhs_type )
// self_defined case
case value_t : : number_float :
return std : : abs ( lhs - rhs ) < = std : : numeric_limits < float > : : epsilon ( ) ;
// other cases remain the same with the original
. . .
}
. . .
2020-03-25 10:12:19 +08:00
}
@ endcode
2018-01-10 01:30:02 +08:00
@ 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
{
2021-08-12 05:55:46 +08:00
# ifdef __GNUC__
2021-08-04 14:34:53 +08:00
# pragma GCC diagnostic push
# pragma GCC diagnostic ignored "-Wfloat-equal"
2021-08-12 05:55:46 +08:00
# endif
2018-01-10 01:30:02 +08:00
const auto lhs_type = lhs . type ( ) ;
const auto rhs_type = rhs . type ( ) ;
if ( lhs_type = = rhs_type )
{
switch ( lhs_type )
{
case value_t : : array :
2019-03-18 20:53:48 +08:00
return * lhs . m_value . array = = * rhs . m_value . array ;
2018-01-10 01:30:02 +08:00
case value_t : : object :
2019-03-18 20:53:48 +08:00
return * lhs . m_value . object = = * rhs . m_value . object ;
2018-01-10 01:30:02 +08:00
case value_t : : null :
return true ;
case value_t : : string :
2019-03-18 20:53:48 +08:00
return * lhs . m_value . string = = * rhs . m_value . string ;
2018-01-10 01:30:02 +08:00
case value_t : : boolean :
2019-03-18 20:53:48 +08:00
return lhs . m_value . boolean = = rhs . m_value . boolean ;
2018-01-10 01:30:02 +08:00
case value_t : : number_integer :
2019-03-18 20:53:48 +08:00
return lhs . m_value . number_integer = = rhs . m_value . number_integer ;
2018-01-10 01:30:02 +08:00
case value_t : : number_unsigned :
2019-03-18 20:53:48 +08:00
return lhs . m_value . number_unsigned = = rhs . m_value . number_unsigned ;
2018-01-10 01:30:02 +08:00
case value_t : : number_float :
2019-03-18 20:53:48 +08:00
return lhs . m_value . number_float = = rhs . m_value . number_float ;
2018-01-10 01:30:02 +08:00
2019-07-05 12:13:25 +08:00
case value_t : : binary :
return * lhs . m_value . binary = = * rhs . m_value . binary ;
2021-08-13 19:43:51 +08:00
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
default :
return false ;
}
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_integer & & rhs_type = = value_t : : number_float )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return static_cast < number_float_t > ( lhs . m_value . number_integer ) = = rhs . m_value . number_float ;
2018-01-10 01:30:02 +08:00
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_float & & rhs_type = = value_t : : number_integer )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return lhs . m_value . number_float = = static_cast < number_float_t > ( rhs . m_value . number_integer ) ;
2018-01-10 01:30:02 +08:00
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_unsigned & & rhs_type = = value_t : : number_float )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return static_cast < number_float_t > ( lhs . m_value . number_unsigned ) = = rhs . m_value . number_float ;
2018-01-10 01:30:02 +08:00
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_float & & rhs_type = = value_t : : number_unsigned )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return lhs . m_value . number_float = = static_cast < number_float_t > ( rhs . m_value . number_unsigned ) ;
2018-01-10 01:30:02 +08:00
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_unsigned & & rhs_type = = value_t : : number_integer )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return static_cast < number_integer_t > ( lhs . m_value . number_unsigned ) = = rhs . m_value . number_integer ;
2018-01-10 01:30:02 +08:00
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_integer & & rhs_type = = value_t : : number_unsigned )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return lhs . m_value . number_integer = = static_cast < number_integer_t > ( rhs . m_value . number_unsigned ) ;
2018-01-10 01:30:02 +08:00
}
return false ;
2021-08-12 05:55:46 +08:00
# ifdef __GNUC__
2021-08-04 14:34:53 +08:00
# pragma GCC diagnostic pop
2021-08-12 05:55:46 +08:00
# endif
2018-01-10 01:30:02 +08:00
}
/*!
@ brief comparison : equal
@ copydoc operator = = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
2021-03-24 14:15:18 +08:00
friend bool operator = = ( const_reference lhs , ScalarType rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return lhs = = basic_json ( rhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ brief comparison : equal
@ copydoc operator = = ( const_reference , const_reference )
*/
template < typename ScalarType , typename std : : enable_if <
std : : is_scalar < ScalarType > : : value , int > : : type = 0 >
2021-03-24 14:15:18 +08:00
friend bool operator = = ( ScalarType lhs , const_reference rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return basic_json ( lhs ) = = rhs ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2020-06-03 20:20:36 +08:00
return ! ( lhs = = rhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 >
2021-03-24 14:15:18 +08:00
friend bool operator ! = ( const_reference lhs , ScalarType rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return lhs ! = basic_json ( rhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 >
2021-03-24 14:15:18 +08:00
friend bool operator ! = ( ScalarType lhs , const_reference rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return basic_json ( lhs ) ! = rhs ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 :
2019-03-20 19:41:08 +08:00
// note parentheses are necessary, see
// https://github.com/nlohmann/json/issues/1530
2018-01-10 01:30:02 +08:00
return ( * lhs . m_value . array ) < ( * rhs . m_value . array ) ;
case value_t : : object :
2019-06-17 06:22:40 +08:00
return ( * lhs . m_value . object ) < ( * rhs . m_value . object ) ;
2018-01-10 01:30:02 +08:00
case value_t : : null :
return false ;
case value_t : : string :
2019-06-17 06:22:40 +08:00
return ( * lhs . m_value . string ) < ( * rhs . m_value . string ) ;
2018-01-10 01:30:02 +08:00
case value_t : : boolean :
2019-06-17 06:22:40 +08:00
return ( lhs . m_value . boolean ) < ( rhs . m_value . boolean ) ;
2018-01-10 01:30:02 +08:00
case value_t : : number_integer :
2019-06-17 06:22:40 +08:00
return ( lhs . m_value . number_integer ) < ( rhs . m_value . number_integer ) ;
2018-01-10 01:30:02 +08:00
case value_t : : number_unsigned :
2019-06-17 06:22:40 +08:00
return ( lhs . m_value . number_unsigned ) < ( rhs . m_value . number_unsigned ) ;
2018-01-10 01:30:02 +08:00
case value_t : : number_float :
2019-06-17 06:22:40 +08:00
return ( lhs . m_value . number_float ) < ( rhs . m_value . number_float ) ;
2018-01-10 01:30:02 +08:00
2019-07-05 12:13:25 +08:00
case value_t : : binary :
2020-05-05 18:40:04 +08:00
return ( * lhs . m_value . binary ) < ( * rhs . m_value . binary ) ;
2019-07-05 12:13:25 +08:00
2021-08-13 19:43:51 +08:00
case value_t : : discarded :
2018-01-10 01:30:02 +08:00
default :
return false ;
}
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_integer & & rhs_type = = value_t : : number_float )
2018-01-10 01:30:02 +08:00
{
return static_cast < number_float_t > ( lhs . m_value . number_integer ) < rhs . m_value . number_float ;
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_float & & rhs_type = = value_t : : number_integer )
2018-01-10 01:30:02 +08:00
{
return lhs . m_value . number_float < static_cast < number_float_t > ( rhs . m_value . number_integer ) ;
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_unsigned & & rhs_type = = value_t : : number_float )
2018-01-10 01:30:02 +08:00
{
return static_cast < number_float_t > ( lhs . m_value . number_unsigned ) < rhs . m_value . number_float ;
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_float & & rhs_type = = value_t : : number_unsigned )
2018-01-10 01:30:02 +08:00
{
return lhs . m_value . number_float < static_cast < number_float_t > ( rhs . m_value . number_unsigned ) ;
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_integer & & rhs_type = = value_t : : number_unsigned )
2018-01-10 01:30:02 +08:00
{
return lhs . m_value . number_integer < static_cast < number_integer_t > ( rhs . m_value . number_unsigned ) ;
}
2020-06-03 20:20:36 +08:00
else if ( lhs_type = = value_t : : number_unsigned & & rhs_type = = value_t : : number_integer )
2018-01-10 01:30:02 +08:00
{
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 >
2021-03-24 14:15:18 +08:00
friend bool operator < ( const_reference lhs , ScalarType rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return lhs < basic_json ( rhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 >
2021-03-24 14:15:18 +08:00
friend bool operator < ( ScalarType lhs , const_reference rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return basic_json ( lhs ) < rhs ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2020-06-03 20:20:36 +08:00
return ! ( rhs < lhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 >
2021-03-24 14:15:18 +08:00
friend bool operator < = ( const_reference lhs , ScalarType rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return lhs < = basic_json ( rhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 >
2021-03-24 14:15:18 +08:00
friend bool operator < = ( ScalarType lhs , const_reference rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return basic_json ( lhs ) < = rhs ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2020-06-03 20:20:36 +08:00
return ! ( lhs < = rhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 >
2021-03-24 14:15:18 +08:00
friend bool operator > ( const_reference lhs , ScalarType rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return lhs > basic_json ( rhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 >
2021-03-24 14:15:18 +08:00
friend bool operator > ( ScalarType lhs , const_reference rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return basic_json ( lhs ) > rhs ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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
{
2020-06-03 20:20:36 +08:00
return ! ( lhs < rhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 >
2021-03-24 14:15:18 +08:00
friend bool operator > = ( const_reference lhs , ScalarType rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return lhs > = basic_json ( rhs ) ;
2018-01-10 01:30:02 +08:00
}
/*!
@ 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 >
2021-03-24 14:15:18 +08:00
friend bool operator > = ( ScalarType lhs , const_reference rhs ) noexcept
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
return basic_json ( lhs ) > = rhs ;
2018-01-10 01:30:02 +08:00
}
/// @}
///////////////////
// serialization //
///////////////////
/// @name serialization
/// @{
2021-04-21 16:24:01 +08:00
# ifndef JSON_NO_IO
2018-01-10 01:30:02 +08:00
/*!
@ 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
2019-03-18 20:53:48 +08:00
const bool pretty_print = o . width ( ) > 0 ;
const auto indentation = pretty_print ? o . width ( ) : 0 ;
2018-01-10 01:30:02 +08:00
// 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
*/
2020-06-06 20:30:17 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.0 .0 , operator < < ( std : : ostream & , const basic_json & ) )
2018-01-10 01:30:02 +08:00
friend std : : ostream & operator > > ( const basic_json & j , std : : ostream & o )
{
return o < < j ;
}
2021-04-21 16:24:01 +08:00
# endif // JSON_NO_IO
2018-01-10 01:30:02 +08:00
/// @}
/////////////////////
// deserialization //
/////////////////////
/// @name deserialization
/// @{
/*!
@ brief deserialize from a compatible input
2020-06-08 02:59:43 +08:00
@ tparam InputType A compatible input , for instance
2020-05-28 14:50:58 +08:00
- an std : : istream object
- a FILE pointer
- a C - style array of characters
- a pointer to a null - terminated string of single byte characters
- an object obj for which begin ( obj ) and end ( obj ) produces a valid pair of
iterators .
2018-01-10 01:30:02 +08:00
@ 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 )
2020-06-22 14:59:03 +08:00
@ param [ in ] ignore_comments whether comments should be ignored and treated
like whitespace ( true ) or yield a parse error ( true ) ; ( optional , false by
default )
2018-01-10 01:30:02 +08:00
2019-01-13 18:46:05 +08:00
@ return deserialized JSON value ; in case of a parse error and
@ a allow_exceptions set to ` false ` , the return value will be
value_t : : discarded .
2018-01-10 01:30:02 +08:00
@ 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
2020-05-28 14:50:58 +08:00
@ a cb or reading from the input @ a i has a super - linear complexity .
2018-01-10 01:30:02 +08:00
@ 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 }
2020-06-18 04:03:14 +08:00
@ since version 2.0 .3 ( contiguous containers ) ; version 3.9 .0 allowed to
ignore comments .
2018-01-10 01:30:02 +08:00
*/
2020-02-19 23:32:49 +08:00
template < typename InputType >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-02-19 23:32:49 +08:00
static basic_json parse ( InputType & & i ,
2018-01-10 01:30:02 +08:00
const parser_callback_t cb = nullptr ,
2020-06-18 04:03:14 +08:00
const bool allow_exceptions = true ,
const bool ignore_comments = false )
2018-01-10 01:30:02 +08:00
{
basic_json result ;
2020-06-18 04:03:14 +08:00
parser ( detail : : input_adapter ( std : : forward < InputType > ( i ) ) , cb , allow_exceptions , ignore_comments ) . parse ( true , result ) ;
2018-01-10 01:30:02 +08:00
return result ;
}
2020-05-28 14:50:58 +08:00
/*!
@ brief deserialize from a pair of character iterators
The value_type of the iterator must be a integral type with size of 1 , 2 or
4 bytes , which will be interpreted respectively as UTF - 8 , UTF - 16 and UTF - 32.
2020-02-19 23:32:49 +08:00
2020-05-28 14:50:58 +08:00
@ param [ in ] first iterator to start of character range
@ param [ in ] last iterator to end of character range
@ 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 )
2020-06-22 14:59:03 +08:00
@ param [ in ] ignore_comments whether comments should be ignored and treated
like whitespace ( true ) or yield a parse error ( true ) ; ( optional , false by
default )
2020-02-19 23:32:49 +08:00
2020-05-28 14:50:58 +08:00
@ return deserialized JSON value ; in case of a parse error and
@ a allow_exceptions set to ` false ` , the return value will be
value_t : : discarded .
@ 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
*/
2020-05-28 00:40:04 +08:00
template < typename IteratorType >
2020-02-19 23:32:49 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-28 14:29:53 +08:00
static basic_json parse ( IteratorType first ,
IteratorType last ,
2020-05-28 00:40:04 +08:00
const parser_callback_t cb = nullptr ,
2020-06-18 04:03:14 +08:00
const bool allow_exceptions = true ,
const bool ignore_comments = false )
2020-05-28 00:40:04 +08:00
{
basic_json result ;
2020-06-18 04:03:14 +08:00
parser ( detail : : input_adapter ( std : : move ( first ) , std : : move ( last ) ) , cb , allow_exceptions , ignore_comments ) . parse ( true , result ) ;
2020-05-28 00:40:04 +08:00
return result ;
}
2020-02-19 23:32:49 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , parse ( ptr , ptr + len ) )
2020-02-19 23:32:49 +08:00
static basic_json parse ( detail : : span_input_adapter & & i ,
const parser_callback_t cb = nullptr ,
2020-06-18 04:03:14 +08:00
const bool allow_exceptions = true ,
const bool ignore_comments = false )
2020-02-19 23:32:49 +08:00
{
basic_json result ;
2020-06-18 04:03:14 +08:00
parser ( i . get ( ) , cb , allow_exceptions , ignore_comments ) . parse ( true , result ) ;
2020-02-19 23:32:49 +08:00
return result ;
}
2020-06-08 02:59:43 +08:00
/*!
@ brief check if the input is valid JSON
Unlike the @ ref parse ( InputType & & , const parser_callback_t , const bool )
function , this function neither throws an exception in case of invalid JSON
input ( i . e . , a parse error ) nor creates diagnostic information .
@ tparam InputType A compatible input , for instance
- an std : : istream object
- a FILE pointer
- a C - style array of characters
- a pointer to a null - terminated string of single byte characters
- an object obj for which begin ( obj ) and end ( obj ) produces a valid pair of
iterators .
@ param [ in ] i input to read from
2020-06-22 14:59:03 +08:00
@ param [ in ] ignore_comments whether comments should be ignored and treated
like whitespace ( true ) or yield a parse error ( true ) ; ( optional , false by
default )
2020-06-08 02:59:43 +08:00
@ return Whether the input read from @ a i is valid JSON .
@ 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 demonstrates the ` accept ( ) ` function reading
from a string . , accept__string }
*/
2020-02-19 23:32:49 +08:00
template < typename InputType >
2020-06-18 04:03:14 +08:00
static bool accept ( InputType & & i ,
const bool ignore_comments = false )
2018-01-10 01:30:02 +08:00
{
2020-06-18 04:03:14 +08:00
return parser ( detail : : input_adapter ( std : : forward < InputType > ( i ) ) , nullptr , false , ignore_comments ) . accept ( true ) ;
2018-01-10 01:30:02 +08:00
}
2020-05-28 00:40:04 +08:00
template < typename IteratorType >
2020-06-18 04:03:14 +08:00
static bool accept ( IteratorType first , IteratorType last ,
const bool ignore_comments = false )
2018-01-10 01:30:02 +08:00
{
2020-06-18 04:03:14 +08:00
return parser ( detail : : input_adapter ( std : : move ( first ) , std : : move ( last ) ) , nullptr , false , ignore_comments ) . accept ( true ) ;
2018-01-10 01:30:02 +08:00
}
2020-05-29 00:13:43 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , accept ( ptr , ptr + len ) )
2020-06-18 04:03:14 +08:00
static bool accept ( detail : : span_input_adapter & & i ,
const bool ignore_comments = false )
2020-02-19 23:32:49 +08:00
{
2020-06-18 04:03:14 +08:00
return parser ( i . get ( ) , nullptr , false , ignore_comments ) . accept ( true ) ;
2020-02-19 23:32:49 +08:00
}
2020-05-28 00:40:04 +08:00
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 :
2020-05-28 14:50:58 +08:00
- an std : : istream object
- a FILE pointer
- a C - style array of characters
- a pointer to a null - terminated string of single byte characters
- an object obj for which begin ( obj ) and end ( obj ) produces a valid pair of
iterators .
2018-08-18 18:00:14 +08:00
@ 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
2020-06-22 14:59:03 +08:00
@ param [ in ] ignore_comments whether comments should be ignored and treated
like whitespace ( true ) or yield a parse error ( true ) ; ( optional , false by
default ) ; only applies to the JSON file format .
2018-08-18 18:00:14 +08:00
@ 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
*/
2020-05-28 00:40:04 +08:00
template < typename InputType , typename SAX >
2020-02-19 23:32:49 +08:00
JSON_HEDLEY_NON_NULL ( 2 )
static bool sax_parse ( InputType & & i , SAX * sax ,
input_format_t format = input_format_t : : json ,
2020-06-18 04:03:14 +08:00
const bool strict = true ,
const bool ignore_comments = false )
2020-02-19 23:32:49 +08:00
{
2020-02-20 03:59:31 +08:00
auto ia = detail : : input_adapter ( std : : forward < InputType > ( i ) ) ;
2020-02-19 23:32:49 +08:00
return format = = input_format_t : : json
2020-06-18 04:03:14 +08:00
? parser ( std : : move ( ia ) , nullptr , true , ignore_comments ) . sax_parse ( sax , strict )
2020-02-20 03:59:31 +08:00
: detail : : binary_reader < basic_json , decltype ( ia ) , SAX > ( std : : move ( ia ) ) . sax_parse ( format , sax , strict ) ;
2020-02-19 23:32:49 +08:00
}
2020-05-28 00:40:04 +08:00
template < class IteratorType , class SAX >
JSON_HEDLEY_NON_NULL ( 3 )
static bool sax_parse ( IteratorType first , IteratorType last , SAX * sax ,
2018-03-21 05:39:08 +08:00
input_format_t format = input_format_t : : json ,
2020-06-18 04:03:14 +08:00
const bool strict = true ,
const bool ignore_comments = false )
2018-01-10 01:30:02 +08:00
{
2020-05-28 00:40:04 +08:00
auto ia = detail : : input_adapter ( std : : move ( first ) , std : : move ( last ) ) ;
2019-03-17 07:27:44 +08:00
return format = = input_format_t : : json
2020-06-18 04:03:14 +08:00
? parser ( std : : move ( ia ) , nullptr , true , ignore_comments ) . sax_parse ( sax , strict )
2020-02-20 03:59:31 +08:00
: detail : : binary_reader < basic_json , decltype ( ia ) , SAX > ( std : : move ( ia ) ) . sax_parse ( format , sax , strict ) ;
2018-02-25 01:04:07 +08:00
}
2018-07-02 16:14:37 +08:00
template < typename SAX >
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , sax_parse ( ptr , ptr + len , . . . ) )
2020-06-06 20:30:17 +08:00
JSON_HEDLEY_NON_NULL ( 2 )
2020-02-19 23:32:49 +08:00
static bool sax_parse ( detail : : span_input_adapter & & i , SAX * sax ,
2018-03-21 05:39:08 +08:00
input_format_t format = input_format_t : : json ,
2020-06-18 04:03:14 +08:00
const bool strict = true ,
const bool ignore_comments = false )
2018-02-25 01:04:07 +08:00
{
2020-02-20 03:59:31 +08:00
auto ia = i . get ( ) ;
2019-03-17 07:27:44 +08:00
return format = = input_format_t : : json
2021-03-24 14:15:18 +08:00
// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
2020-06-18 04:03:14 +08:00
? parser ( std : : move ( ia ) , nullptr , true , ignore_comments ) . sax_parse ( sax , strict )
2021-03-24 14:15:18 +08:00
// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
2020-02-20 03:59:31 +08:00
: detail : : binary_reader < basic_json , decltype ( ia ) , SAX > ( std : : move ( ia ) ) . sax_parse ( format , sax , strict ) ;
2018-02-25 01:04:07 +08:00
}
2021-04-21 16:24:01 +08:00
# ifndef JSON_NO_IO
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
*/
2020-06-06 20:30:17 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.0 .0 , operator > > ( std : : istream & , basic_json & ) )
2018-01-10 01:30:02 +08:00
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 ;
}
2021-05-31 20:26:45 +08:00
# endif // JSON_NO_IO
2018-01-10 01:30:02 +08:00
/// @}
///////////////////////////
// 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 " `
2019-07-05 12:13:25 +08:00
binary | ` " binary " `
2018-01-10 01:30:02 +08:00
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref type ( ) - - return the type of the JSON value
@ sa see @ ref operator value_t ( ) - - return the type of the JSON value ( implicit )
2018-01-10 01:30:02 +08:00
@ since version 1.0 .0 , public since 2.1 .0 , ` const char * ` and ` noexcept `
since 3.0 .0
*/
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_RETURNS_NON_NULL
2018-01-10 01:30:02 +08:00
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 " ;
2019-07-05 12:13:25 +08:00
case value_t : : binary :
return " binary " ;
2018-01-10 01:30:02 +08:00
case value_t : : discarded :
return " discarded " ;
2021-08-12 22:33:41 +08:00
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : number_float :
2018-01-10 01:30:02 +08:00
default :
return " number " ;
}
}
}
2020-08-12 19:30:06 +08:00
JSON_PRIVATE_UNLESS_TESTED :
2018-01-10 01:30:02 +08:00
//////////////////////
// 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 = { } ;
2021-01-02 20:58:05 +08:00
# if JSON_DIAGNOSTICS
2021-01-02 00:23:10 +08:00
/// a pointer to a parent value (for debugging purposes)
basic_json * m_parent = nullptr ;
# endif
2018-01-10 01:30:02 +08:00
//////////////////////////////////////////
// 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
2020-05-19 19:08:18 +08:00
number_float | * any value representable by a float * | Single - Precision Float | 0xFA
number_float | * any value NOT representable by a float * | Double - Precision Float | 0xFB
2018-01-10 01:30:02 +08:00
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
2019-07-05 12:13:25 +08:00
binary | * size * : 0. .23 | byte string | 0x40 . .0 x57
binary | * size * : 23. .255 | byte string ( 1 byte follow ) | 0x58
binary | * size * : 256. .65535 | byte string ( 2 bytes follow ) | 0x59
binary | * size * : 65536. .4294967295 | byte string ( 4 bytes follow ) | 0x5A
binary | * size * : 4294967296. .18446744073709551615 | byte string ( 8 bytes follow ) | 0x5B
2018-01-10 01:30:02 +08:00
2021-08-08 19:24:17 +08:00
Binary values with subtype are mapped to tagged values ( 0xD8 . .0 xDB )
depending on the subtype , followed by a byte string , see " binary " cells
in the table above .
2018-01-10 01:30:02 +08:00
@ 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 :
- UTF - 8 strings terminated by " break " ( 0x7F )
- arrays terminated by " break " ( 0x9F )
- maps terminated by " break " ( 0xBF )
2019-07-05 12:13:25 +08:00
- byte strings terminated by " break " ( 0x5F )
2018-01-10 01:30:02 +08:00
- date / time ( 0xC0 . .0 xC1 )
- bignum ( 0xC2 . .0 xC3 )
- decimal fraction ( 0xC4 )
- bigfloat ( 0xC5 )
- expected conversions ( 0xD5 . .0 xD7 )
- simple values ( 0xE0 . .0 xF3 , 0xF8 )
- undefined ( 0xF7 )
2020-05-19 19:08:18 +08:00
- half - precision floats ( 0xF9 )
2018-01-10 01:30:02 +08:00
- break ( 0xFF )
@ param [ in ] j JSON value to serialize
2020-05-13 20:29:10 +08:00
@ return CBOR serialization as byte vector
2018-01-10 01:30:02 +08:00
@ 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
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_cbor ( InputType & & , const bool , const bool , const cbor_tag_handler_t ) for the
2018-01-10 01:30:02 +08:00
analogous deserialization
2021-03-24 14:15:18 +08:00
@ sa see @ ref to_msgpack ( const basic_json & ) for the related MessagePack format
@ sa see @ ref to_ubjson ( const basic_json & , const bool , const bool ) for the
2018-01-23 06:23:17 +08:00
related UBJSON format
2018-01-10 01:30:02 +08:00
2020-05-19 19:08:18 +08:00
@ since version 2.0 .9 ; compact representation of floating - point numbers
since version 3.8 .0
2018-01-10 01:30:02 +08:00
*/
2021-08-08 19:24:17 +08:00
static std : : vector < std : : uint8_t > to_cbor ( const basic_json & j )
2018-01-10 01:30:02 +08:00
{
2021-08-08 19:24:17 +08:00
std : : vector < std : : uint8_t > result ;
2018-01-10 01:30:02 +08:00
to_cbor ( j , result ) ;
return result ;
}
2021-08-08 19:24:17 +08:00
static void to_cbor ( const basic_json & j , detail : : output_adapter < std : : uint8_t > o )
2018-01-10 01:30:02 +08:00
{
2021-08-08 19:24:17 +08:00
binary_writer < std : : uint8_t > ( o ) . write_cbor ( j ) ;
2018-01-10 01:30:02 +08:00
}
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
2020-06-18 03:14:23 +08:00
number_float | * any value representable by a float * | float 32 | 0xCA
number_float | * any value NOT representable by a float * | float 64 | 0xCB
2018-01-10 01:30:02 +08:00
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
2019-07-05 12:13:25 +08:00
binary | * size * : 0. .255 | bin 8 | 0xC4
binary | * size * : 256. .65535 | bin 16 | 0xC5
binary | * size * : 65536. .4294967295 | bin 32 | 0xC6
2018-01-10 01:30:02 +08:00
@ 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
2019-07-05 12:13:25 +08:00
- byte strings with more than 4294967295 bytes
2018-01-10 01:30:02 +08:00
- arrays with more than 4294967295 elements
- objects with more than 4294967295 elements
@ 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
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_msgpack for the analogous deserialization
@ sa see @ ref to_cbor ( const basic_json & for the related CBOR format
@ sa see @ ref to_ubjson ( const basic_json & , const bool , const bool ) for the
2018-01-23 06:23:17 +08:00
related UBJSON format
2018-01-10 01:30:02 +08:00
@ since version 2.0 .9
*/
2021-08-08 19:24:17 +08:00
static std : : vector < std : : uint8_t > to_msgpack ( const basic_json & j )
2018-01-10 01:30:02 +08:00
{
2021-08-08 19:24:17 +08:00
std : : vector < std : : uint8_t > result ;
2018-01-10 01:30:02 +08:00
to_msgpack ( j , result ) ;
return result ;
}
2021-08-08 19:24:17 +08:00
static void to_msgpack ( const basic_json & j , detail : : output_adapter < std : : uint8_t > o )
2018-01-10 01:30:02 +08:00
{
2021-08-08 19:24:17 +08:00
binary_writer < std : : uint8_t > ( o ) . write_msgpack ( j ) ;
2018-01-10 01:30:02 +08:00
}
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 `
2020-07-20 20:11:43 +08:00
number_unsigned | 2147483649. .18446744073709551615 | high - precision | ` H `
2018-01-23 06:23:17 +08:00
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 )
@ 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 .
2019-07-05 12:13:25 +08:00
@ note If the JSON data contains the binary type , the value stored is a list
of integers , as suggested by the UBJSON documentation . In particular ,
this means that serialization and the deserialization of a JSON
containing binary values into UBJSON and back will result in a
different JSON object .
2018-01-23 06:23:17 +08:00
@ 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
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_ubjson ( InputType & & , const bool , const bool ) for the
2018-01-23 06:23:17 +08:00
analogous deserialization
2021-03-24 14:15:18 +08:00
@ sa see @ ref to_cbor ( const basic_json & for the related CBOR format
@ sa see @ ref to_msgpack ( const basic_json & ) for the related MessagePack format
2018-01-23 06:23:17 +08:00
@ since version 3.1 .0
*/
2021-08-08 19:24:17 +08:00
static std : : vector < std : : uint8_t > to_ubjson ( const basic_json & j ,
const bool use_size = false ,
const bool use_type = false )
2018-01-14 17:27:30 +08:00
{
2021-08-08 19:24:17 +08:00
std : : vector < std : : uint8_t > result ;
2018-01-14 17:27:30 +08:00
to_ubjson ( j , result , use_size , use_type ) ;
return result ;
}
2021-08-08 19:24:17 +08:00
static void to_ubjson ( const basic_json & j , detail : : output_adapter < std : : uint8_t > o ,
2018-01-14 17:27:30 +08:00
const bool use_size = false , const bool use_type = false )
{
2021-08-08 19:24:17 +08:00
binary_writer < std : : uint8_t > ( o ) . write_ubjson ( j , use_size , use_type ) ;
2018-01-14 17:27:30 +08:00
}
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
2019-07-05 12:13:25 +08:00
binary | * any value * | binary | 0x05
2018-10-07 23:57:13 +08:00
@ 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
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_bson ( detail : : input_adapter & & , const bool strict ) for the
2018-10-07 23:57:13 +08:00
analogous deserialization
2021-03-24 14:15:18 +08:00
@ sa see @ ref to_ubjson ( const basic_json & , const bool , const bool ) for the
2018-10-28 16:15:41 +08:00
related UBJSON format
2021-03-24 14:15:18 +08:00
@ sa see @ ref to_cbor ( const basic_json & ) for the related CBOR format
@ sa see @ ref to_msgpack ( const basic_json & ) for the related MessagePack format
2018-10-07 13:52:12 +08:00
*/
2021-08-08 19:24:17 +08:00
static std : : vector < std : : uint8_t > to_bson ( const basic_json & j )
2018-09-15 04:58:22 +08:00
{
2021-08-08 19:24:17 +08:00
std : : vector < std : : uint8_t > result ;
2018-09-15 04:58:22 +08:00
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 `
2021-03-24 14:15:18 +08:00
@ sa see @ ref to_bson ( const basic_json & )
2018-10-07 13:52:12 +08:00
*/
2021-08-08 19:24:17 +08:00
static void to_bson ( const basic_json & j , detail : : output_adapter < std : : uint8_t > o )
2018-09-15 04:58:22 +08:00
{
2021-08-08 19:24:17 +08:00
binary_writer < std : : uint8_t > ( o ) . write_bson ( j ) ;
2018-09-15 04:58:22 +08:00
}
2018-10-07 13:52:12 +08:00
/*!
2021-08-08 19:24:17 +08:00
@ copydoc to_bson ( const basic_json & , detail : : output_adapter < std : : uint8_t > )
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 < 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
2019-07-05 12:13:25 +08:00
Byte string | binary | 0x40 . .0 x57
Byte string | binary | 0x58
Byte string | binary | 0x59
Byte string | binary | 0x5A
Byte string | binary | 0x5B
2018-01-10 01:30:02 +08:00
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 ) :
- date / time ( 0xC0 . .0 xC1 )
- bignum ( 0xC2 . .0 xC3 )
- decimal fraction ( 0xC4 )
- bigfloat ( 0xC5 )
- 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 )
2020-07-12 22:51:43 +08:00
@ param [ in ] tag_handler how to treat CBOR tags ( optional , error by default )
2018-03-20 05:48:13 +08:00
2019-01-13 18:46:05 +08:00
@ return deserialized JSON value ; in case of a parse error and
@ a allow_exceptions set to ` false ` , the return value will be
value_t : : discarded .
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 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
2021-03-24 14:15:18 +08:00
@ sa see @ ref to_cbor ( const basic_json & ) for the analogous serialization
@ sa see @ ref from_msgpack ( InputType & & , const bool , const bool ) for the
2018-01-10 01:30:02 +08:00
related MessagePack format
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_ubjson ( InputType & & , 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
2020-07-12 22:51:43 +08:00
since 3.2 .0 ; added @ a tag_handler parameter since 3.9 .0 .
2018-01-10 01:30:02 +08:00
*/
2020-02-19 23:32:49 +08:00
template < typename InputType >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-02-19 23:32:49 +08:00
static basic_json from_cbor ( InputType & & i ,
2018-03-20 05:48:13 +08:00
const bool strict = true ,
2020-07-12 22:51:43 +08:00
const bool allow_exceptions = true ,
const cbor_tag_handler_t tag_handler = cbor_tag_handler_t : : error )
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 ) ;
2020-02-20 03:59:31 +08:00
auto ia = detail : : input_adapter ( std : : forward < InputType > ( i ) ) ;
2020-07-12 22:51:43 +08:00
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . sax_parse ( input_format_t : : cbor , & sdp , strict , tag_handler ) ;
2018-03-20 05:48:13 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
2018-01-10 01:30:02 +08:00
}
/*!
2021-03-24 14:15:18 +08:00
@ copydoc from_cbor ( InputType & & , const bool , const bool , const cbor_tag_handler_t )
2018-01-10 01:30:02 +08:00
*/
2020-05-28 00:40:04 +08:00
template < typename IteratorType >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-28 00:40:04 +08:00
static basic_json from_cbor ( IteratorType first , IteratorType last ,
2018-03-20 05:48:13 +08:00
const bool strict = true ,
2020-07-12 22:51:43 +08:00
const bool allow_exceptions = true ,
const cbor_tag_handler_t tag_handler = cbor_tag_handler_t : : error )
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 ) ;
2020-05-28 00:40:04 +08:00
auto ia = detail : : input_adapter ( std : : move ( first ) , std : : move ( last ) ) ;
2020-07-12 22:51:43 +08:00
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . sax_parse ( input_format_t : : cbor , & sdp , strict , tag_handler ) ;
2020-02-19 23:32:49 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
}
2020-05-29 00:13:43 +08:00
template < typename T >
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , from_cbor ( ptr , ptr + len ) )
2020-05-29 00:13:43 +08:00
static basic_json from_cbor ( const T * ptr , std : : size_t len ,
const bool strict = true ,
2020-07-12 22:51:43 +08:00
const bool allow_exceptions = true ,
const cbor_tag_handler_t tag_handler = cbor_tag_handler_t : : error )
2020-05-29 00:13:43 +08:00
{
2020-07-21 04:38:00 +08:00
return from_cbor ( ptr , ptr + len , strict , allow_exceptions , tag_handler ) ;
2020-05-29 00:13:43 +08:00
}
2020-02-19 23:32:49 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , from_cbor ( ptr , ptr + len ) )
2020-02-19 23:32:49 +08:00
static basic_json from_cbor ( detail : : span_input_adapter & & i ,
const bool strict = true ,
2020-07-12 22:51:43 +08:00
const bool allow_exceptions = true ,
const cbor_tag_handler_t tag_handler = cbor_tag_handler_t : : error )
2020-02-19 23:32:49 +08:00
{
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
2020-05-28 00:40:04 +08:00
auto ia = i . get ( ) ;
2021-03-24 14:15:18 +08:00
// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
2020-07-12 22:51:43 +08:00
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . sax_parse ( input_format_t : : cbor , & sdp , strict , tag_handler ) ;
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
2019-07-05 12:13:25 +08:00
bin 8 | binary | 0xC4
bin 16 | binary | 0xC5
bin 32 | binary | 0xC6
ext 8 | binary | 0xC7
ext 16 | binary | 0xC8
ext 32 | binary | 0xC9
fixext 1 | binary | 0xD4
fixext 2 | binary | 0xD5
fixext 4 | binary | 0xD6
fixext 8 | binary | 0xD7
fixext 16 | binary | 0xD8
2018-01-10 01:30:02 +08:00
negative fixint | number_integer | 0xE0 - 0xFF
@ 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 )
2019-01-13 18:46:05 +08:00
@ return deserialized JSON value ; in case of a parse error and
@ a allow_exceptions set to ` false ` , the return value will be
value_t : : discarded .
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
2021-03-24 14:15:18 +08:00
@ sa see @ ref to_msgpack ( const basic_json & ) for the analogous serialization
@ sa see @ ref from_cbor ( InputType & & , const bool , const bool , const cbor_tag_handler_t ) for the
2018-03-21 02:22:18 +08:00
related CBOR format
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_ubjson ( InputType & & , const bool , const bool ) for
2018-03-21 02:22:18 +08:00
the related UBJSON format
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_bson ( InputType & & , 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
*/
2020-02-19 23:32:49 +08:00
template < typename InputType >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-02-19 23:32:49 +08:00
static basic_json from_msgpack ( InputType & & 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 ) ;
2020-02-20 03:59:31 +08:00
auto ia = detail : : input_adapter ( std : : forward < InputType > ( i ) ) ;
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . 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
}
/*!
2021-03-24 14:15:18 +08:00
@ copydoc from_msgpack ( InputType & & , const bool , const bool )
2018-01-10 01:30:02 +08:00
*/
2020-05-28 00:40:04 +08:00
template < typename IteratorType >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-28 00:40:04 +08:00
static basic_json from_msgpack ( IteratorType first , IteratorType last ,
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 ) ;
2020-05-28 00:40:04 +08:00
auto ia = detail : : input_adapter ( std : : move ( first ) , std : : move ( last ) ) ;
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . 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
}
2020-02-19 23:32:49 +08:00
2020-05-29 00:13:43 +08:00
template < typename T >
2020-02-19 23:32:49 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , from_msgpack ( ptr , ptr + len ) )
2020-05-29 00:13:43 +08:00
static basic_json from_msgpack ( const T * ptr , std : : size_t len ,
const bool strict = true ,
const bool allow_exceptions = true )
{
return from_msgpack ( ptr , ptr + len , strict , allow_exceptions ) ;
}
2020-02-19 23:32:49 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , from_msgpack ( ptr , ptr + len ) )
2020-02-19 23:32:49 +08:00
static basic_json from_msgpack ( detail : : span_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 ) ;
2020-05-28 00:40:04 +08:00
auto ia = i . get ( ) ;
2021-03-24 14:15:18 +08:00
// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
2020-05-28 00:40:04 +08:00
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . sax_parse ( input_format_t : : msgpack , & sdp , strict ) ;
2020-02-19 23:32:49 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
}
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 `
2020-07-20 19:12:20 +08:00
high - precision number | number_integer , number_unsigned , or number_float - depends on number string | ' H '
2018-01-23 06:23:17 +08:00
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 )
2019-01-13 18:46:05 +08:00
@ return deserialized JSON value ; in case of a parse error and
@ a allow_exceptions set to ` false ` , the return value will be
value_t : : discarded .
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
2021-03-24 14:15:18 +08:00
@ sa see @ ref to_ubjson ( const basic_json & , const bool , const bool ) for the
2018-01-23 06:23:17 +08:00
analogous serialization
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_cbor ( InputType & & , const bool , const bool , const cbor_tag_handler_t ) for the
2018-03-21 02:22:18 +08:00
related CBOR format
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_msgpack ( InputType & & , const bool , const bool ) for
2018-03-21 02:22:18 +08:00
the related MessagePack format
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_bson ( InputType & & , 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
*/
2020-02-19 23:32:49 +08:00
template < typename InputType >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-02-19 23:32:49 +08:00
static basic_json from_ubjson ( InputType & & 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 ) ;
2020-02-20 03:59:31 +08:00
auto ia = detail : : input_adapter ( std : : forward < InputType > ( i ) ) ;
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . 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
/*!
2021-03-24 14:15:18 +08:00
@ copydoc from_ubjson ( InputType & & , const bool , const bool )
2018-03-21 02:22:18 +08:00
*/
2020-05-28 00:40:04 +08:00
template < typename IteratorType >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-28 00:40:04 +08:00
static basic_json from_ubjson ( IteratorType first , IteratorType last ,
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 ) ;
2020-05-28 00:40:04 +08:00
auto ia = detail : : input_adapter ( std : : move ( first ) , std : : move ( last ) ) ;
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . sax_parse ( input_format_t : : ubjson , & sdp , strict ) ;
2020-02-19 23:32:49 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
}
2020-05-29 00:13:43 +08:00
template < typename T >
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , from_ubjson ( ptr , ptr + len ) )
2020-05-29 00:13:43 +08:00
static basic_json from_ubjson ( const T * ptr , std : : size_t len ,
const bool strict = true ,
const bool allow_exceptions = true )
{
return from_ubjson ( ptr , ptr + len , strict , allow_exceptions ) ;
}
2020-02-19 23:32:49 +08:00
2020-05-29 00:13:43 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , from_ubjson ( ptr , ptr + len ) )
2020-02-19 23:32:49 +08:00
static basic_json from_ubjson ( detail : : span_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 ) ;
2020-05-28 00:40:04 +08:00
auto ia = i . get ( ) ;
2021-03-24 14:15:18 +08:00
// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
2020-05-28 00:40:04 +08:00
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . 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
}
2020-02-19 23:32:49 +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
2020-08-10 15:24:11 +08:00
binary | 0x05 | binary
2018-10-07 13:52:12 +08:00
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 )
2019-01-13 18:46:05 +08:00
@ return deserialized JSON value ; in case of a parse error and
@ a allow_exceptions set to ` false ` , the return value will be
value_t : : discarded .
2018-10-07 13:52:12 +08:00
@ 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
2021-03-24 14:15:18 +08:00
@ sa see @ ref to_bson ( const basic_json & ) for the analogous serialization
@ sa see @ ref from_cbor ( InputType & & , const bool , const bool , const cbor_tag_handler_t ) for the
2018-10-07 13:52:12 +08:00
related CBOR format
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_msgpack ( InputType & & , const bool , const bool ) for
2018-10-07 13:52:12 +08:00
the related MessagePack format
2021-03-24 14:15:18 +08:00
@ sa see @ ref from_ubjson ( InputType & & , const bool , const bool ) for the
2018-10-07 13:52:12 +08:00
related UBJSON format
*/
2020-02-19 23:32:49 +08:00
template < typename InputType >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-02-19 23:32:49 +08:00
static basic_json from_bson ( InputType & & i ,
2018-09-15 04:58:22 +08:00
const bool strict = true ,
const bool allow_exceptions = true )
{
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
2020-02-20 03:59:31 +08:00
auto ia = detail : : input_adapter ( std : : forward < InputType > ( i ) ) ;
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . sax_parse ( input_format_t : : bson , & sdp , strict ) ;
2018-09-15 04:58:22 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
}
2018-10-07 13:52:12 +08:00
/*!
2021-03-24 14:15:18 +08:00
@ copydoc from_bson ( InputType & & , const bool , const bool )
2018-10-07 13:52:12 +08:00
*/
2020-05-28 00:40:04 +08:00
template < typename IteratorType >
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-28 00:40:04 +08:00
static basic_json from_bson ( IteratorType first , IteratorType last ,
2018-09-15 04:58:22 +08:00
const bool strict = true ,
const bool allow_exceptions = true )
{
basic_json result ;
detail : : json_sax_dom_parser < basic_json > sdp ( result , allow_exceptions ) ;
2020-05-28 00:40:04 +08:00
auto ia = detail : : input_adapter ( std : : move ( first ) , std : : move ( last ) ) ;
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . sax_parse ( input_format_t : : bson , & sdp , strict ) ;
2018-09-15 04:58:22 +08:00
return res ? result : basic_json ( value_t : : discarded ) ;
}
2020-05-29 00:13:43 +08:00
template < typename T >
2020-02-19 23:32:49 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , from_bson ( ptr , ptr + len ) )
2020-05-29 00:13:43 +08:00
static basic_json from_bson ( const T * ptr , std : : size_t len ,
const bool strict = true ,
const bool allow_exceptions = true )
{
return from_bson ( ptr , ptr + len , strict , allow_exceptions ) ;
}
2020-02-19 23:32:49 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2020-05-29 00:26:29 +08:00
JSON_HEDLEY_DEPRECATED_FOR ( 3.8 .0 , from_bson ( ptr , ptr + len ) )
2020-02-19 23:32:49 +08:00
static basic_json from_bson ( detail : : span_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 ) ;
2020-05-28 00:40:04 +08:00
auto ia = i . get ( ) ;
2021-03-24 14:15:18 +08:00
// NOLINTNEXTLINE(hicpp-move-const-arg,performance-move-const-arg)
2020-05-28 00:40:04 +08:00
const bool res = binary_reader < decltype ( ia ) > ( std : : move ( ia ) ) . sax_parse ( input_format_t : : bson , & sdp , strict ) ;
2020-02-19 23:32:49 +08:00
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
2020-02-02 17:29:37 +08:00
value ; no ` null ` values are created . In particular , the special value
2018-01-10 01:30:02 +08:00
` - ` 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref unflatten ( ) for the reverse function
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref flatten ( ) for the reverse function
2018-01-10 01:30:02 +08:00
@ 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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref diff - - create a JSON patch by comparing two JSON values
2018-01-10 01:30:02 +08:00
@ 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
2019-02-25 16:57:12 +08:00
if ( ptr . empty ( ) )
2018-01-10 01:30:02 +08:00
{
result = val ;
2019-03-18 20:53:48 +08:00
return ;
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +08:00
// make sure the top element of the pointer exists
json_pointer top_pointer = ptr . top ( ) ;
if ( top_pointer ! = ptr )
{
result . at ( top_pointer ) ;
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +08:00
// get reference to parent of JSON pointer ptr
2019-03-19 22:40:23 +08:00
const auto last_path = ptr . back ( ) ;
ptr . pop_back ( ) ;
2019-03-18 20:53:48 +08:00
basic_json & parent = result [ ptr ] ;
switch ( parent . m_type )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
case value_t : : null :
case value_t : : object :
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
// use operator[] to add value
parent [ last_path ] = val ;
break ;
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +08:00
case value_t : : array :
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
if ( last_path = = " - " )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
// special case: append to back
parent . push_back ( val ) ;
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +08:00
else
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
const auto idx = json_pointer : : array_index ( last_path ) ;
2020-06-20 21:36:28 +08:00
if ( JSON_HEDLEY_UNLIKELY ( idx > parent . size ( ) ) )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
// avoid undefined behavior
2021-01-25 20:47:50 +08:00
JSON_THROW ( out_of_range : : create ( 401 , " array index " + std : : to_string ( idx ) + " is out of range " , parent ) ) ;
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +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
}
2019-03-18 20:53:48 +08:00
break ;
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +08:00
// if there exists a parent it cannot be primitive
2021-08-13 21:30:55 +08:00
case value_t : : string : // LCOV_EXCL_LINE
case value_t : : boolean : // LCOV_EXCL_LINE
case value_t : : number_integer : // LCOV_EXCL_LINE
case value_t : : number_unsigned : // LCOV_EXCL_LINE
case value_t : : number_float : // LCOV_EXCL_LINE
case value_t : : binary : // LCOV_EXCL_LINE
case value_t : : discarded : // LCOV_EXCL_LINE
2019-03-18 20:53:48 +08:00
default : // LCOV_EXCL_LINE
2021-03-24 14:15:18 +08:00
JSON_ASSERT ( false ) ; // NOLINT(cert-dcl03-c,hicpp-static-assert,misc-static-assert) LCOV_EXCL_LINE
2018-01-10 01:30:02 +08:00
}
} ;
// wrapper for "remove" operation; remove value at ptr
2021-01-02 23:13:04 +08:00
const auto operation_remove = [ this , & result ] ( json_pointer & ptr )
2018-01-10 01:30:02 +08:00
{
// get reference to parent of JSON pointer ptr
2019-03-19 22:40:23 +08:00
const auto last_path = ptr . back ( ) ;
ptr . pop_back ( ) ;
2018-01-10 01:30:02 +08:00
basic_json & parent = result . at ( ptr ) ;
// remove child
if ( parent . is_object ( ) )
{
// perform range check
auto it = parent . find ( last_path ) ;
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_LIKELY ( it ! = parent . end ( ) ) )
2018-01-10 01:30:02 +08:00
{
parent . erase ( it ) ;
}
else
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( out_of_range : : create ( 403 , " key ' " + last_path + " ' not found " , * this ) ) ;
2018-01-10 01:30:02 +08:00
}
}
else if ( parent . is_array ( ) )
{
// note erase performs range check
2020-06-20 21:36:28 +08:00
parent . erase ( json_pointer : : array_index ( last_path ) ) ;
2018-01-10 01:30:02 +08:00
}
} ;
// type check: top level value must be an array
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! json_patch . is_array ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( parse_error : : create ( 104 , 0 , " JSON patch must be an array of objects " , json_patch ) ) ;
2018-01-10 01:30:02 +08:00
}
// 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
2019-07-02 04:37:30 +08:00
if ( JSON_HEDLEY_UNLIKELY ( it = = val . m_value . object - > end ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-03-24 14:15:18 +08:00
// NOLINTNEXTLINE(performance-inefficient-string-concatenation)
2021-01-25 20:47:50 +08:00
JSON_THROW ( parse_error : : create ( 105 , 0 , error_msg + " must have member ' " + member + " ' " , val ) ) ;
2018-01-10 01:30:02 +08:00
}
// check if result is of type string
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( string_type & & ! it - > second . is_string ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-03-24 14:15:18 +08:00
// NOLINTNEXTLINE(performance-inefficient-string-concatenation)
2021-01-25 20:47:50 +08:00
JSON_THROW ( parse_error : : create ( 105 , 0 , error_msg + " must have string member ' " + member + " ' " , val ) ) ;
2018-01-10 01:30:02 +08:00
}
// no error: return value
return it - > second ;
} ;
// type check: every element of the array must be an object
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! val . is_object ( ) ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( parse_error : : create ( 104 , 0 , " JSON patch must be an array of objects " , val ) ) ;
2018-01-10 01:30:02 +08:00
}
// collect mandatory members
2020-07-16 17:11:35 +08:00
const auto op = get_value ( " op " , " op " , true ) . template get < std : : string > ( ) ;
const auto path = get_value ( op , " path " , true ) . template get < std : : string > ( ) ;
2018-01-10 01:30:02 +08:00
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 :
{
2020-07-16 17:11:35 +08:00
const auto from_path = get_value ( " move " , " from " , true ) . template get < std : : string > ( ) ;
2018-01-10 01:30:02 +08:00
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 :
{
2020-07-16 17:11:35 +08:00
const auto from_path = get_value ( " copy " , " from " , true ) . template get < std : : string > ( ) ;
2018-01-10 01:30:02 +08:00
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
2020-06-03 20:20:36 +08:00
if ( JSON_HEDLEY_UNLIKELY ( ! success ) )
2018-01-10 01:30:02 +08:00
{
2021-01-25 20:47:50 +08:00
JSON_THROW ( other_error : : create ( 501 , " unsuccessful: " + val . dump ( ) , val ) ) ;
2018-01-10 01:30:02 +08:00
}
break ;
}
2021-08-13 19:43:51 +08:00
case patch_operations : : invalid :
2019-03-17 19:01:49 +08:00
default :
2018-01-10 01:30:02 +08:00
{
// op must be "add", "remove", "replace", "move", "copy", or
// "test"
2021-01-25 20:47:50 +08:00
JSON_THROW ( parse_error : : create ( 105 , 0 , " operation value ' " + op + " ' is invalid " , val ) ) ;
2018-01-10 01:30:02 +08:00
}
}
}
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref patch - - apply a JSON patch
@ sa see @ 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
*/
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_WARN_UNUSED_RESULT
2018-01-10 01:30:02 +08:00
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 }
} ) ;
2019-03-18 20:53:48 +08:00
return result ;
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +08:00
switch ( source . type ( ) )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
case value_t : : array :
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
// first pass: traverse common elements
std : : size_t i = 0 ;
2020-06-03 20:20:36 +08:00
while ( i < source . size ( ) & & i < target . size ( ) )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
// 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 ;
}
2018-01-10 01:30:02 +08:00
2019-03-18 20:53:48 +08:00
// i now reached the end of at least one array
// in a second pass, traverse the remaining elements
2018-01-10 01:30:02 +08:00
2019-03-18 20:53:48 +08:00
// 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 (
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
{ " op " , " remove " } ,
{ " path " , path + " / " + std : : to_string ( i ) }
} ) ) ;
+ + i ;
}
2018-01-10 01:30:02 +08:00
2019-03-18 20:53:48 +08:00
// add other remaining elements
while ( i < target . size ( ) )
{
result . push_back (
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
{ " op " , " add " } ,
2020-04-13 20:35:36 +08:00
{ " path " , path + " /- " } ,
2019-03-18 20:53:48 +08:00
{ " value " , target [ i ] }
} ) ;
+ + i ;
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +08:00
break ;
}
case value_t : : object :
{
// first pass: traverse this object's elements
for ( auto it = source . cbegin ( ) ; it ! = source . cend ( ) ; + + it )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
// escape the key name to be used in a JSON patch
2021-03-24 14:15:18 +08:00
const auto path_key = path + " / " + detail : : escape ( it . key ( ) ) ;
2018-01-10 01:30:02 +08:00
2019-03-18 20:53:48 +08:00
if ( target . find ( it . key ( ) ) ! = target . end ( ) )
{
// recursive call to compare object values at key it
2021-03-24 14:15:18 +08:00
auto temp_diff = diff ( it . value ( ) , target [ it . key ( ) ] , path_key ) ;
2019-03-18 20:53:48 +08:00
result . insert ( result . end ( ) , temp_diff . begin ( ) , temp_diff . end ( ) ) ;
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +08:00
else
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
// found a key that is not in o -> remove it
result . push_back ( object (
2018-01-10 01:30:02 +08:00
{
2021-03-24 14:15:18 +08:00
{ " op " , " remove " } , { " path " , path_key }
2019-03-18 20:53:48 +08:00
} ) ) ;
2018-01-10 01:30:02 +08:00
}
}
2019-03-18 20:53:48 +08:00
// second pass: traverse other object's elements
for ( auto it = target . cbegin ( ) ; it ! = target . cend ( ) ; + + it )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
if ( source . find ( it . key ( ) ) = = source . end ( ) )
2018-01-10 01:30:02 +08:00
{
2019-03-18 20:53:48 +08:00
// found a key that is not in this -> add it
2021-03-24 14:15:18 +08:00
const auto path_key = path + " / " + detail : : escape ( it . key ( ) ) ;
2019-03-18 20:53:48 +08:00
result . push_back (
{
2021-03-24 14:15:18 +08:00
{ " op " , " add " } , { " path " , path_key } ,
2019-03-18 20:53:48 +08:00
{ " value " , it . value ( ) }
} ) ;
}
2018-01-10 01:30:02 +08:00
}
2019-03-18 20:53:48 +08:00
break ;
}
2021-08-13 19:43:51 +08:00
case value_t : : null :
case value_t : : string :
case value_t : : boolean :
case value_t : : number_integer :
case value_t : : number_unsigned :
case value_t : : number_float :
case value_t : : binary :
case value_t : : discarded :
2019-03-18 20:53:48 +08:00
default :
{
// both primitive type: replace value
result . push_back (
{
{ " op " , " replace " } , { " path " , path } , { " value " , target }
} ) ;
break ;
2018-01-10 01:30:02 +08:00
}
}
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 }
2021-03-24 14:15:18 +08:00
@ sa see @ ref patch - - apply a JSON patch
2018-01-14 17:34:43 +08:00
@ 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
{
2020-06-03 20:20:36 +08:00
if ( ! is_object ( ) )
2018-01-14 17:34:43 +08:00
{
* 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
} ;
2019-04-26 11:12:15 +08:00
/*!
@ brief user - defined to_string function for JSON values
This function implements a user - defined to_string for JSON objects .
@ param [ in ] j a JSON object
@ return a std : : string object
*/
NLOHMANN_BASIC_JSON_TPL_DECLARATION
std : : string to_string ( const NLOHMANN_BASIC_JSON_TPL & j )
{
return j . dump ( ) ;
}
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
{
2020-07-14 20:31:19 +08:00
return nlohmann : : detail : : hash ( j ) ;
2018-01-10 01:30:02 +08:00
}
} ;
/// specialization for std::less<value_t>
/// @note: do not remove the space after '<',
/// see https://github.com/nlohmann/json/pull/679
template < >
2019-10-30 21:54:52 +08:00
struct less < : : nlohmann : : detail : : value_t >
2018-01-10 01:30:02 +08:00
{
/*!
@ 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 ) ;
}
} ;
2020-06-06 23:36:39 +08:00
// C++20 prohibit function specialization in the std namespace.
# ifndef JSON_HAS_CPP_20
2018-09-19 04:38:59 +08:00
/*!
@ brief exchanges the values of two JSON objects
@ since version 1.0 .0
*/
template < >
2021-03-24 14:15:18 +08:00
inline void swap < nlohmann : : json > ( nlohmann : : json & j1 , nlohmann : : json & j2 ) noexcept ( // NOLINT(readability-inconsistent-declaration-parameter-name)
is_nothrow_move_constructible < nlohmann : : json > : : value & & // NOLINT(misc-redundant-expression)
2018-09-19 04:38:59 +08:00
is_nothrow_move_assignable < nlohmann : : json > : : value
2021-06-18 01:17:43 +08:00
)
2018-09-19 04:38:59 +08:00
{
j1 . swap ( j2 ) ;
}
2020-06-06 23:36:39 +08:00
# endif
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
*/
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_NON_NULL ( 1 )
2018-01-10 01:30:02 +08:00
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
*/
2019-07-02 04:37:30 +08:00
JSON_HEDLEY_NON_NULL ( 1 )
2018-01-10 01:30:02 +08:00
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
2019-03-15 21:55:13 +08:00
# endif // INCLUDE_NLOHMANN_JSON_HPP_