//
|
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
|
//
|
// Distributed under the Boost Software License, Version 1.0. (See accompanying
|
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
|
//
|
// Official repository: https://github.com/boostorg/json
|
//
|
|
#ifndef BOOST_JSON_OBJECT_HPP
|
#define BOOST_JSON_OBJECT_HPP
|
|
#include <boost/json/detail/config.hpp>
|
#include <boost/json/kind.hpp>
|
#include <boost/json/pilfer.hpp>
|
#include <boost/json/storage_ptr.hpp>
|
#include <boost/json/string_view.hpp>
|
#include <boost/json/detail/object.hpp>
|
#include <boost/json/detail/value.hpp>
|
#include <cstdlib>
|
#include <initializer_list>
|
#include <iterator>
|
#include <type_traits>
|
#include <utility>
|
|
BOOST_JSON_NS_BEGIN
|
|
class value;
|
class value_ref;
|
class key_value_pair;
|
|
/** A dynamically sized associative container of JSON key/value pairs.
|
|
This is an associative container whose elements
|
are key/value pairs with unique keys.
|
\n
|
The elements are stored contiguously; iterators are
|
ordinary pointers, allowing random access pointer
|
arithmetic for retrieving elements.
|
In addition, the container maintains an internal
|
index to speed up find operations, reducing the
|
average complexity for most lookups and insertions.
|
\n
|
Reallocations are usually costly operations in terms of
|
performance, as elements are copied and the internal
|
index must be rebuilt. The @ref reserve function can
|
be used to eliminate reallocations if the number of
|
elements is known beforehand.
|
|
@par Allocators
|
|
All elements stored in the container, and their
|
children if any, will use the same memory resource that
|
was used to construct the container.
|
|
@par Thread Safety
|
|
Non-const member functions may not be called
|
concurrently with any other member functions.
|
|
@par Satisfies
|
<a href="https://en.cppreference.com/w/cpp/named_req/ContiguousContainer"><em>ContiguousContainer</em></a>,
|
<a href="https://en.cppreference.com/w/cpp/named_req/ReversibleContainer"><em>ReversibleContainer</em></a>, and
|
<a href="https://en.cppreference.com/w/cpp/named_req/SequenceContainer"><em>SequenceContainer</em></a>.
|
*/
|
class object
|
{
|
struct table;
|
class revert_construct;
|
class revert_insert;
|
friend class value;
|
friend class object_test;
|
using access = detail::access;
|
using index_t = std::uint32_t;
|
static index_t constexpr null_index_ =
|
std::uint32_t(-1);
|
|
storage_ptr sp_; // must come first
|
kind k_ = kind::object; // must come second
|
table* t_;
|
|
BOOST_JSON_DECL
|
static table empty_;
|
|
template<class T>
|
using is_inputit = typename std::enable_if<
|
std::is_constructible<key_value_pair,
|
typename std::iterator_traits<T>::value_type
|
>::value>::type;
|
|
BOOST_JSON_DECL
|
explicit
|
object(detail::unchecked_object&& uo);
|
|
public:
|
/** The type of _Allocator_ returned by @ref get_allocator
|
|
This type is a @ref polymorphic_allocator.
|
*/
|
#ifdef BOOST_JSON_DOCS
|
// VFALCO doc toolchain renders this incorrectly
|
using allocator_type = __see_below__;
|
#else
|
using allocator_type = polymorphic_allocator<value>;
|
#endif
|
|
/** The type of keys.
|
|
The function @ref string::max_size returns the
|
maximum allowed size of strings used as keys.
|
*/
|
using key_type = string_view;
|
|
/// The type of mapped values
|
using mapped_type = value;
|
|
/// The element type
|
using value_type = key_value_pair;
|
|
/// The type used to represent unsigned integers
|
using size_type = std::size_t;
|
|
/// The type used to represent signed integers
|
using difference_type = std::ptrdiff_t;
|
|
/// A reference to an element
|
using reference = value_type&;
|
|
/// A const reference to an element
|
using const_reference = value_type const&;
|
|
/// A pointer to an element
|
using pointer = value_type*;
|
|
/// A const pointer to an element
|
using const_pointer = value_type const*;
|
|
/// A random access iterator to an element
|
using iterator = value_type*;
|
|
/// A const random access iterator to an element
|
using const_iterator = value_type const*;
|
|
/// A reverse random access iterator to an element
|
using reverse_iterator =
|
std::reverse_iterator<iterator>;
|
|
/// A const reverse random access iterator to an element
|
using const_reverse_iterator =
|
std::reverse_iterator<const_iterator>;
|
|
//------------------------------------------------------
|
|
/** Destructor.
|
|
The destructor for each element is called if needed,
|
any used memory is deallocated, and shared ownership
|
of the @ref memory_resource is released.
|
|
@par Complexity
|
Constant, or linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
BOOST_JSON_DECL
|
~object();
|
|
//------------------------------------------------------
|
|
/** Default constructor.
|
|
The constructed object is empty with zero
|
capacity, using the default memory resource.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
object() noexcept
|
: t_(&empty_)
|
{
|
}
|
|
/** Constructor.
|
|
The constructed object is empty with zero
|
capacity, using the specified memory resource.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@param sp A pointer to the @ref memory_resource
|
to use. The container will acquire shared
|
ownership of the memory resource.
|
*/
|
explicit
|
object(storage_ptr sp) noexcept
|
: sp_(std::move(sp))
|
, t_(&empty_)
|
{
|
}
|
|
/** Constructor.
|
|
The constructed object is empty with capacity
|
equal to the specified minimum capacity,
|
using the specified memory resource.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param min_capacity The minimum number
|
of elements for which capacity is guaranteed
|
without a subsequent reallocation.
|
|
@param sp A pointer to the @ref memory_resource
|
to use. The container will acquire shared
|
ownership of the memory resource.
|
*/
|
BOOST_JSON_DECL
|
object(
|
std::size_t min_capacity,
|
storage_ptr sp = {});
|
|
/** Constructor.
|
|
The object is constructed with the elements
|
in the range `{first, last)`, preserving order,
|
using the specified memory resource.
|
If there are elements with duplicate keys; that
|
is, if multiple elements in the range have keys
|
that compare equal, only the first equivalent
|
element will be inserted.
|
|
@par Constraints
|
@code
|
std::is_constructible_v<
|
key_value_pair,
|
std::iterator_traits<InputIt>::value_type>
|
@endcode
|
|
@par Complexity
|
Linear in `std::distance(first, last)`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param first An input iterator pointing to the
|
first element to insert, or pointing to the end
|
of the range.
|
|
@param last An input iterator pointing to the end
|
of the range.
|
|
@param min_capacity The minimum number
|
of elements for which capacity is guaranteed
|
without a subsequent reallocation.
|
Upon construction, @ref capacity() will be greater
|
than or equal to this number.
|
|
@param sp A pointer to the @ref memory_resource
|
to use. The container will acquire shared
|
ownership of the memory resource.
|
|
@tparam InputIt a type satisfying the requirements
|
of __InputIterator__.
|
*/
|
template<
|
class InputIt
|
#ifndef BOOST_JSON_DOCS
|
,class = is_inputit<InputIt>
|
#endif
|
>
|
object(
|
InputIt first,
|
InputIt last,
|
std::size_t min_capacity = 0,
|
storage_ptr sp = {})
|
: sp_(std::move(sp))
|
, t_(&empty_)
|
{
|
construct(
|
first, last,
|
min_capacity,
|
typename std::iterator_traits<
|
InputIt>::iterator_category{});
|
}
|
|
/** Move constructor.
|
|
The object is constructed by acquiring ownership of
|
the contents of `other` and shared ownership
|
of `other`'s memory resource.
|
|
@note
|
|
After construction, the moved-from object behaves
|
as if newly constructed with its current memory resource.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@param other The object to move.
|
*/
|
BOOST_JSON_DECL
|
object(object&& other) noexcept;
|
|
/** Move constructor.
|
|
The object is constructed with the contents of
|
`other` by move semantics, using the specified
|
memory resource:
|
|
@li If `*other.storage() == *sp`, ownership of
|
the underlying memory is transferred in constant
|
time, with no possibility of exceptions.
|
After construction, the moved-from object behaves
|
as if newly constructed with its current storage
|
pointer.
|
|
@li If `*other.storage() != *sp`, an
|
element-wise copy is performed, which may throw.
|
In this case, the moved-from object is not
|
changed.
|
|
@par Complexity
|
Constant or linear in `other.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param other The object to move.
|
|
@param sp A pointer to the @ref memory_resource
|
to use. The container will acquire shared
|
ownership of the memory resource.
|
*/
|
BOOST_JSON_DECL
|
object(
|
object&& other,
|
storage_ptr sp);
|
|
/** Pilfer constructor.
|
|
The object is constructed by acquiring ownership
|
of the contents of `other` using pilfer semantics.
|
This is more efficient than move construction, when
|
it is known that the moved-from object will be
|
immediately destroyed afterwards.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@param other The value to pilfer. After pilfer
|
construction, `other` is not in a usable state
|
and may only be destroyed.
|
|
@see @ref pilfer,
|
<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0308r0.html">
|
Valueless Variants Considered Harmful</a>
|
*/
|
object(pilfered<object> other) noexcept
|
: sp_(std::move(other.get().sp_))
|
, t_(detail::exchange(
|
other.get().t_, &empty_))
|
{
|
}
|
|
/** Copy constructor.
|
|
The object is constructed with a copy of the
|
contents of `other`, using `other`'s memory resource.
|
|
@par Complexity
|
Linear in `other.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param other The object to copy.
|
*/
|
object(
|
object const& other)
|
: object(other, other.sp_)
|
{
|
}
|
|
/** Copy constructor.
|
|
The object is constructed with a copy of the
|
contents of `other`, using the specified memory resource.
|
|
@par Complexity
|
Linear in `other.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param other The object to copy.
|
|
@param sp A pointer to the @ref memory_resource
|
to use. The container will acquire shared
|
ownership of the memory resource.
|
*/
|
BOOST_JSON_DECL
|
object(
|
object const& other,
|
storage_ptr sp);
|
|
/** Construct from initializer-list.
|
|
The object is constructed with a copy of the values
|
in the initializer-list in order, using the
|
specified memory resource.
|
If there are elements with duplicate keys; that
|
is, if multiple elements in the range have keys
|
that compare equal, only the first equivalent
|
element will be inserted.
|
|
@par Complexity
|
Linear in `init.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param init The initializer list to insert.
|
|
@param sp A pointer to the @ref memory_resource
|
to use. The container will acquire shared
|
ownership of the memory resource.
|
*/
|
object(
|
std::initializer_list<
|
std::pair<string_view, value_ref>> init,
|
storage_ptr sp = {})
|
: object(init, 0, std::move(sp))
|
{
|
}
|
|
/** Construct from initializer-list.
|
|
Storage for at least `min_capacity` elements is
|
reserved, and then
|
the object is constructed with a copy of the values
|
in the initializer-list in order, using the
|
specified memory resource.
|
If there are elements with duplicate keys; that
|
is, if multiple elements in the range have keys
|
that compare equal, only the first equivalent
|
element will be inserted.
|
|
@par Complexity
|
Linear in `init.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param init The initializer list to insert.
|
|
@param min_capacity The minimum number
|
of elements for which capacity is guaranteed
|
without a subsequent reallocation.
|
Upon construction, @ref capacity() will be greater
|
than or equal to this number.
|
|
@param sp A pointer to the @ref memory_resource
|
to use. The container will acquire shared
|
ownership of the memory resource.
|
*/
|
BOOST_JSON_DECL
|
object(
|
std::initializer_list<
|
std::pair<string_view, value_ref>> init,
|
std::size_t min_capacity,
|
storage_ptr sp = {});
|
|
//------------------------------------------------------
|
//
|
// Assignment
|
//
|
//------------------------------------------------------
|
|
/** Copy assignment.
|
|
The contents of the object are replaced with an
|
element-wise copy of `other`.
|
|
@par Complexity
|
Linear in @ref size() plus `other.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param other The object to copy.
|
*/
|
BOOST_JSON_DECL
|
object&
|
operator=(object const& other);
|
|
/** Move assignment.
|
|
The contents of the object are replaced with the
|
contents of `other` using move semantics:
|
|
@li If `*other.storage() == *sp`, ownership of
|
the underlying memory is transferred in constant
|
time, with no possibility of exceptions.
|
After assignment, the moved-from object behaves
|
as if newly constructed with its current storage
|
pointer.
|
|
@li If `*other.storage() != *sp`, an
|
element-wise copy is performed, which may throw.
|
In this case, the moved-from object is not
|
changed.
|
|
@par Complexity
|
Constant or linear in @ref size() plus `other.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param other The object to move.
|
*/
|
BOOST_JSON_DECL
|
object&
|
operator=(object&& other);
|
|
/** Assignment.
|
|
Replaces the contents with the contents of an
|
initializer list.
|
|
@par Complexity
|
Linear in @ref size() plus
|
average case linear in `init.size()`,
|
worst case quadratic in `init.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param init The initializer list to copy.
|
*/
|
BOOST_JSON_DECL
|
object&
|
operator=(std::initializer_list<
|
std::pair<string_view, value_ref>> init);
|
|
//------------------------------------------------------
|
|
/** Return the associated @ref memory_resource
|
|
This returns the @ref memory_resource used by
|
the container.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
storage_ptr const&
|
storage() const noexcept
|
{
|
return sp_;
|
}
|
|
/** Return the associated @ref memory_resource
|
|
This function returns an instance of
|
@ref polymorphic_allocator constructed from the
|
associated @ref memory_resource.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
allocator_type
|
get_allocator() const noexcept
|
{
|
return sp_.get();
|
}
|
|
//------------------------------------------------------
|
//
|
// Iterators
|
//
|
//------------------------------------------------------
|
|
/** Return an iterator to the first element.
|
|
If the container is empty, @ref end() is returned.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
iterator
|
begin() noexcept;
|
|
/** Return a const iterator to the first element.
|
|
If the container is empty, @ref end() is returned.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
const_iterator
|
begin() const noexcept;
|
|
/** Return a const iterator to the first element.
|
|
If the container is empty, @ref cend() is returned.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
const_iterator
|
cbegin() const noexcept;
|
|
/** Return an iterator to the element following the last element.
|
|
The element acts as a placeholder; attempting
|
to access it results in undefined behavior.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
iterator
|
end() noexcept;
|
|
/** Return a const iterator to the element following the last element.
|
|
The element acts as a placeholder; attempting
|
to access it results in undefined behavior.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
const_iterator
|
end() const noexcept;
|
|
/** Return a const iterator to the element following the last element.
|
|
The element acts as a placeholder; attempting
|
to access it results in undefined behavior.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
const_iterator
|
cend() const noexcept;
|
|
/** Return a reverse iterator to the first element of the reversed container.
|
|
The pointed-to element corresponds to the
|
last element of the non-reversed container.
|
If the container is empty, @ref rend() is returned.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
reverse_iterator
|
rbegin() noexcept;
|
|
/** Return a const reverse iterator to the first element of the reversed container.
|
|
The pointed-to element corresponds to the
|
last element of the non-reversed container.
|
If the container is empty, @ref rend() is returned.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
const_reverse_iterator
|
rbegin() const noexcept;
|
|
/** Return a const reverse iterator to the first element of the reversed container.
|
|
The pointed-to element corresponds to the
|
last element of the non-reversed container.
|
If the container is empty, @ref crend() is returned.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
const_reverse_iterator
|
crbegin() const noexcept;
|
|
/** Return a reverse iterator to the element following the last element of the reversed container.
|
|
The pointed-to element corresponds to the element
|
preceding the first element of the non-reversed container.
|
This element acts as a placeholder, attempting
|
to access it results in undefined behavior.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
reverse_iterator
|
rend() noexcept;
|
|
/** Return a const reverse iterator to the element following the last element of the reversed container.
|
|
The pointed-to element corresponds to the element
|
preceding the first element of the non-reversed container.
|
This element acts as a placeholder, attempting
|
to access it results in undefined behavior.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
const_reverse_iterator
|
rend() const noexcept;
|
|
/** Return a const reverse iterator to the element following the last element of the reversed container.
|
|
The pointed-to element corresponds to the element
|
preceding the first element of the non-reversed container.
|
This element acts as a placeholder, attempting
|
to access it results in undefined behavior.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
const_reverse_iterator
|
crend() const noexcept;
|
|
//------------------------------------------------------
|
//
|
// Capacity
|
//
|
//------------------------------------------------------
|
|
/** Return whether there are no elements.
|
|
Returns `true` if there are no elements in
|
the container, i.e. @ref size() returns 0.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
bool
|
empty() const noexcept;
|
|
/** Return the number of elements.
|
|
This returns the number of elements in the container.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
std::size_t
|
size() const noexcept;
|
|
/** Return the maximum number of elements any object can hold
|
|
The maximum is an implementation-defined number dependent
|
on system or library implementation. This value is a
|
theoretical limit; at runtime, the actual maximum size
|
may be less due to resource limits.
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
static
|
constexpr
|
std::size_t
|
max_size() noexcept;
|
|
/** Return the number of elements that can be held in currently allocated memory
|
|
This number may be larger than the value returned
|
by @ref size().
|
|
@par Complexity
|
Constant.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
inline
|
std::size_t
|
capacity() const noexcept;
|
|
/** Increase the capacity to at least a certain amount.
|
|
This increases the @ref capacity() to a value
|
that is greater than or equal to `new_capacity`.
|
If `new_capacity > capacity()`, new memory is
|
allocated. Otherwise, the call has no effect.
|
The number of elements and therefore the
|
@ref size() of the container is not changed.
|
\n
|
If new memory is allocated, all iterators
|
including any past-the-end iterators, and all
|
references to the elements are invalidated.
|
Otherwise, no iterators or references are
|
invalidated.
|
|
@par Complexity
|
Constant or average case linear in
|
@ref size(), worst case quadratic.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param new_capacity The new minimum capacity.
|
|
@throw std::length_error `new_capacity > max_size()`
|
*/
|
void
|
reserve(std::size_t new_capacity)
|
{
|
if(new_capacity <= capacity())
|
return;
|
rehash(new_capacity);
|
}
|
|
//------------------------------------------------------
|
//
|
// Modifiers
|
//
|
//------------------------------------------------------
|
|
/** Erase all elements.
|
|
Erases all elements from the container without
|
changing the capacity.
|
After this call, @ref size() returns zero.
|
All references, pointers, and iterators are
|
invalidated.
|
|
@par Complexity
|
Linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
BOOST_JSON_DECL
|
void
|
clear() noexcept;
|
|
/** Insert elements.
|
|
Inserts `p`, from which @ref value_type must
|
be constructible.
|
|
@par Constraints
|
@code
|
std::is_constructible_v<value_type, P>
|
@endcode
|
|
@par Complexity
|
Average case amortized constant,
|
worst case linear in @ref size().
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param p The value to insert.
|
|
@throw std::length_error key is too long.
|
|
@throw std::length_error @ref size() >= max_size().
|
|
@return A pair where `first` is an iterator
|
to the existing or inserted element, and `second`
|
is `true` if the insertion took place or `false` if
|
the assignment took place.
|
*/
|
template<class P
|
#ifndef BOOST_JSON_DOCS
|
,class = typename std::enable_if<
|
std::is_constructible<key_value_pair,
|
P, storage_ptr>::value>::type
|
#endif
|
>
|
std::pair<iterator, bool>
|
insert(P&& p);
|
|
/** Insert elements.
|
|
The elements in the range `{first, last)` whose
|
keys are unique are inserted one at a time, in order.
|
If there are elements with duplicate keys; that
|
is, if multiple elements in the range have keys
|
that compare equal, only the first equivalent
|
element will be inserted.
|
|
@par Precondition
|
`first` and `last` are not iterators into `*this`.
|
|
@par Constraints
|
@code
|
std::is_constructible_v<value_type, std::iterator_traits<InputIt>::value_type>
|
@endcode
|
|
@par Complexity
|
Linear in `std::distance(first, last)`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param first An input iterator pointing to the first
|
element to insert, or pointing to the end of the range.
|
|
@param last An input iterator pointing to the end
|
of the range.
|
|
@tparam InputIt a type satisfying the requirements
|
of __InputIterator__.
|
*/
|
template<
|
class InputIt
|
#ifndef BOOST_JSON_DOCS
|
,class = is_inputit<InputIt>
|
#endif
|
>
|
void
|
insert(InputIt first, InputIt last)
|
{
|
insert(first, last, typename
|
std::iterator_traits<InputIt
|
>::iterator_category{});
|
}
|
|
/** Insert elements.
|
|
The elements in the initializer list whose
|
keys are unique are inserted one at a time, in order.
|
If there are elements with duplicate keys; that
|
is, if multiple elements in the range have keys
|
that compare equal, only the first equivalent
|
element will be inserted.
|
|
@par Complexity
|
Linear in `init.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param init The initializer list to insert
|
*/
|
BOOST_JSON_DECL
|
void
|
insert(std::initializer_list<
|
std::pair<string_view, value_ref>> init);
|
|
/** Insert an element or assign to the current element if the key already exists.
|
|
If the key equivalent to `key` already exists in the
|
container. assigns `std::forward<M>(obj)` to the
|
`mapped type` corresponding to the key. Otherwise,
|
inserts the new value at the end as if by insert,
|
constructing it from
|
`value_type(key, std::forward<M>(obj))`.
|
|
If the insertion occurs and results in a rehashing
|
of the container, all iterators are invalidated.
|
Otherwise, iterators are not affected.
|
References are not invalidated.
|
Rehashing occurs only if the new number of elements
|
is greater than @ref capacity().
|
|
@par Complexity
|
Amortized constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@return A `std::pair` where `first` is an iterator
|
to the existing or inserted element, and `second`
|
is `true` if the insertion took place or `false` if
|
the assignment took place.
|
|
@param key The key used for lookup and insertion
|
|
@param m The value to insert or assign
|
|
@throw std::length_error if key is too long
|
*/
|
template<class M>
|
std::pair<iterator, bool>
|
insert_or_assign(
|
string_view key, M&& m);
|
|
/** Construct an element in-place.
|
|
Inserts a new element into the container constructed
|
in-place with the given argument if there is no
|
element with the key in the container.
|
The element is inserted after all the existing
|
elements.
|
|
If the insertion occurs and results in a rehashing
|
of the container, all iterators are invalidated.
|
Otherwise, iterators are not affected.
|
References are not invalidated.
|
Rehashing occurs only if the new number of elements
|
is greater than @ref capacity().
|
|
@par Complexity
|
Amortized constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@return A `std::pair` where `first` is an iterator
|
to the existing or inserted element, and `second`
|
is `true` if the insertion took place or `false` if
|
the assignment took place.
|
|
@param key The key used for lookup and insertion
|
|
@param arg The argument used to construct the value.
|
This will be passed as `std::forward<Arg>(arg)` to
|
the @ref value constructor.
|
|
@throw std::length_error if key is too long
|
*/
|
template<class Arg>
|
std::pair<iterator, bool>
|
emplace(string_view key, Arg&& arg);
|
|
/** Erase an element
|
|
Remove the element pointed to by `pos`, which must
|
be valid and dereferenceable. Thus the @ref end()
|
iterator (which is valid but cannot be dereferenced)
|
cannot be used as a value for `pos`.
|
References and iterators to the erased element are
|
invalidated. Other iterators and references are not
|
invalidated.
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@return An iterator following the last removed element.
|
|
@param pos An iterator pointing to the element to be
|
removed.
|
*/
|
BOOST_JSON_DECL
|
iterator
|
erase(const_iterator pos) noexcept;
|
|
/** Erase an element
|
|
Remove the element which matches `key`, if it exists.
|
References and iterators to the erased element are
|
invalidated. Other iterators and references are not
|
invalidated.
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@return The number of elements removed, which will
|
be either 0 or 1.
|
|
@param key The key to match.
|
*/
|
BOOST_JSON_DECL
|
std::size_t
|
erase(string_view key) noexcept;
|
|
/** Swap two objects.
|
|
Exchanges the contents of this object with another
|
object. Ownership of the respective @ref memory_resource
|
objects is not transferred.
|
|
@li If `*other.storage() == *this->storage()`,
|
ownership of the underlying memory is swapped in
|
constant time, with no possibility of exceptions.
|
All iterators and references remain valid.
|
|
@li If `*other.storage() != *this->storage()`,
|
the contents are logically swapped by making copies,
|
which can throw. In this case all iterators and
|
references are invalidated.
|
|
@par Complexity
|
Constant or linear in @ref size() plus `other.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param other The object to swap with.
|
If `this == &other`, this function call has no effect.
|
*/
|
BOOST_JSON_DECL
|
void
|
swap(object& other);
|
|
/** Swap two objects.
|
|
Exchanges the contents of the object `lhs` with
|
another object `rhs`. Ownership of the respective
|
@ref memory_resource objects is not transferred.
|
|
@li If `*lhs.storage() == *rhs.storage()`,
|
ownership of the underlying memory is swapped in
|
constant time, with no possibility of exceptions.
|
All iterators and references remain valid.
|
|
@li If `*lhs.storage() != *rhs.storage()`,
|
the contents are logically swapped by making a copy,
|
which can throw. In this case all iterators and
|
references are invalidated.
|
|
@par Effects
|
@code
|
lhs.swap( rhs );
|
@endcode
|
|
@par Complexity
|
Constant or linear in `lhs.size() + rhs.size()`.
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@param lhs The object to exchange.
|
|
@param rhs The object to exchange.
|
If `&lhs == &rhs`, this function call has no effect.
|
|
@see @ref object::swap
|
*/
|
friend
|
void
|
swap(object& lhs, object& rhs)
|
{
|
lhs.swap(rhs);
|
}
|
|
//------------------------------------------------------
|
//
|
// Lookup
|
//
|
//------------------------------------------------------
|
|
/** Access the specified element, with bounds checking.
|
|
Returns a reference to the mapped value of the element
|
that matches `key`, otherwise throws.
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
Strong guarantee.
|
|
@return A reference to the mapped value.
|
|
@param key The key of the element to find.
|
|
@throw std::out_of_range if no such element exists.
|
*/
|
inline
|
value&
|
at(string_view key);
|
|
/** Access the specified element, with bounds checking.
|
|
Returns a constant reference to the mapped value of
|
the element that matches `key`, otherwise throws.
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
Strong guarantee.
|
|
@return A reference to the mapped value.
|
|
@param key The key of the element to find.
|
|
@throw std::out_of_range if no such element exists.
|
*/
|
inline
|
value const&
|
at(string_view key) const;
|
|
/** Access or insert the specified element
|
|
Returns a reference to the value that is mapped
|
to a key equivalent to key, performing an insertion
|
of a null value if such key does not already exist.
|
\n
|
If an insertion occurs and results in a rehashing of
|
the container, all iterators are invalidated. Otherwise
|
iterators are not affected. References are not
|
invalidated. Rehashing occurs only if the new
|
number of elements is greater than @ref capacity().
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
Strong guarantee.
|
Calls to `memory_resource::allocate` may throw.
|
|
@return A reference to the mapped value.
|
|
@param key The key of the element to find.
|
*/
|
BOOST_JSON_DECL
|
value&
|
operator[](string_view key);
|
|
/** Count the number of elements with a specific key
|
|
This function returns the count of the number of
|
elements match `key`. The only possible return values
|
are 0 and 1.
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@param key The key of the element to find.
|
*/
|
BOOST_JSON_DECL
|
std::size_t
|
count(string_view key) const noexcept;
|
|
/** Find an element with a specific key
|
|
This function returns an iterator to the element
|
matching `key` if it exists, otherwise returns
|
@ref end().
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@param key The key of the element to find.
|
*/
|
BOOST_JSON_DECL
|
iterator
|
find(string_view key) noexcept;
|
|
/** Find an element with a specific key
|
|
This function returns a constant iterator to
|
the element matching `key` if it exists,
|
otherwise returns @ref end().
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@param key The key of the element to find.
|
*/
|
BOOST_JSON_DECL
|
const_iterator
|
find(string_view key) const noexcept;
|
|
/** Return `true` if the key is found
|
|
This function returns `true` if a key with the
|
specified string is found.
|
|
@par Effects
|
@code
|
return this->find(key) != this->end();
|
@endcode
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@param key The key of the element to find.
|
|
@see @ref find
|
*/
|
BOOST_JSON_DECL
|
bool
|
contains(string_view key) const noexcept;
|
|
/** Return a pointer to the value if the key is found, or null
|
|
This function searches for a value with the given
|
key, and returns a pointer to it if found. Otherwise
|
it returns null.
|
|
@par Example
|
@code
|
if( auto p = obj.if_contains( "key" ) )
|
std::cout << *p;
|
@endcode
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@param key The key of the element to find.
|
|
@see @ref find
|
*/
|
BOOST_JSON_DECL
|
value const*
|
if_contains(string_view key) const noexcept;
|
|
/** Return a pointer to the value if the key is found, or null
|
|
This function searches for a value with the given
|
key, and returns a pointer to it if found. Otherwise
|
it returns null.
|
|
@par Example
|
@code
|
if( auto p = obj.if_contains( "key" ) )
|
std::cout << *p;
|
@endcode
|
|
@par Complexity
|
Constant on average, worst case linear in @ref size().
|
|
@par Exception Safety
|
No-throw guarantee.
|
|
@param key The key of the element to find.
|
|
@see @ref find
|
*/
|
BOOST_JSON_DECL
|
value*
|
if_contains(string_view key) noexcept;
|
|
/** Return `true` if two objects are equal.
|
|
Objects are equal when their sizes are the same,
|
and when for each key in `lhs` there is a matching
|
key in `rhs` with the same value.
|
|
@par Complexity
|
Constant, or linear (worst case quadratic) in `lhs.size()`.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
// inline friend speeds up overload resolution
|
friend
|
bool
|
operator==(
|
object const& lhs,
|
object const& rhs) noexcept
|
{
|
return lhs.equal(rhs);
|
}
|
|
/** Return `true` if two objects are not equal.
|
|
Objects are equal when their sizes are the same,
|
and when for each key in `lhs` there is a matching
|
key in `rhs` with the same value.
|
|
@par Complexity
|
Constant, or linear (worst case quadratic) in `lhs.size()`.
|
|
@par Exception Safety
|
No-throw guarantee.
|
*/
|
// inline friend speeds up overload resolution
|
friend
|
bool
|
operator!=(
|
object const& lhs,
|
object const& rhs) noexcept
|
{
|
return ! (lhs == rhs);
|
}
|
|
private:
|
template<class InputIt>
|
void
|
construct(
|
InputIt first,
|
InputIt last,
|
std::size_t min_capacity,
|
std::input_iterator_tag);
|
|
template<class InputIt>
|
void
|
construct(
|
InputIt first,
|
InputIt last,
|
std::size_t min_capacity,
|
std::forward_iterator_tag);
|
|
template<class InputIt>
|
void
|
insert(
|
InputIt first,
|
InputIt last,
|
std::input_iterator_tag);
|
|
template<class InputIt>
|
void
|
insert(
|
InputIt first,
|
InputIt last,
|
std::forward_iterator_tag);
|
|
BOOST_JSON_DECL
|
std::pair<key_value_pair*, std::size_t>
|
find_impl(string_view key) const noexcept;
|
|
BOOST_JSON_DECL
|
std::pair<iterator, bool>
|
insert_impl(
|
pilfered<key_value_pair> p);
|
|
BOOST_JSON_DECL
|
key_value_pair*
|
insert_impl(
|
pilfered<key_value_pair> p,
|
std::size_t hash);
|
|
BOOST_JSON_DECL
|
void
|
rehash(std::size_t new_capacity);
|
|
BOOST_JSON_DECL
|
bool
|
equal(object const& other) const noexcept;
|
|
inline
|
std::size_t
|
growth(
|
std::size_t new_size) const;
|
|
inline
|
void
|
remove(
|
index_t& head,
|
key_value_pair& p) noexcept;
|
|
inline
|
void
|
destroy() noexcept;
|
|
inline
|
void
|
destroy(
|
key_value_pair* first,
|
key_value_pair* last) noexcept;
|
};
|
|
BOOST_JSON_NS_END
|
|
// Must be included here for this file to stand alone
|
#include <boost/json/value.hpp>
|
|
// includes are at the bottom of <boost/json/value.hpp>
|
|
#endif
|
