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