1   
//
1   
//
2   
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
2   
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3   
//
3   
//
4   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
4   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
5   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
5   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6   
//
6   
//
7   
// Official repository: https://github.com/boostorg/json
7   
// Official repository: https://github.com/boostorg/json
8   
//
8   
//
9  
9  
10   
#ifndef BOOST_JSON_ARRAY_HPP
10   
#ifndef BOOST_JSON_ARRAY_HPP
11   
#define BOOST_JSON_ARRAY_HPP
11   
#define BOOST_JSON_ARRAY_HPP
12  
12  
13   
#include <boost/json/detail/config.hpp>
13   
#include <boost/json/detail/config.hpp>
14   
#include <boost/json/detail/array.hpp>
14   
#include <boost/json/detail/array.hpp>
15   
#include <boost/json/kind.hpp>
15   
#include <boost/json/kind.hpp>
16   
#include <boost/json/pilfer.hpp>
16   
#include <boost/json/pilfer.hpp>
17   
#include <boost/json/storage_ptr.hpp>
17   
#include <boost/json/storage_ptr.hpp>
18   
#include <boost/system/result.hpp>
18   
#include <boost/system/result.hpp>
19   
#include <cstdlib>
19   
#include <cstdlib>
20   
#include <initializer_list>
20   
#include <initializer_list>
21   
#include <iterator>
21   
#include <iterator>
22  
22  
23   
namespace boost {
23   
namespace boost {
24   
namespace json {
24   
namespace json {
25  
25  
26   
#ifndef BOOST_JSON_DOCS
26   
#ifndef BOOST_JSON_DOCS
27   
class value;
27   
class value;
28   
class value_ref;
28   
class value_ref;
29   
#endif
29   
#endif
30  
30  
31   
/** A dynamically sized array of JSON values
31   
/** A dynamically sized array of JSON values
32  
32  
33 - 
    This is the type used to represent a JSON array as a modifiable container.
33 + 
    This is the type used to represent a JSON array as
34 - 
    The interface and performance characteristics are modeled after
34 + 
    a modifiable container. The interface and performance
35 - 
    `std::vector<value>`.
35 + 
    characteristics are modeled after `std::vector<value>`.
36 -
36 + 
\n
37 - 
    Elements are stored contiguously, which means that they can be accessed not
37 + 
    Elements are stored contiguously, which means that
38 - 
    only through iterators, but also using offsets to regular pointers to
38 + 
    they can be accessed not only through iterators, but
39 - 
    elements. A pointer to an element of an `array` may be passed to any
39 + 
    also using offsets to regular pointers to elements. A
40 - 
    function that expects a pointer to @ref value.
40 + 
    pointer to an element of an @ref array may be passed to
41 -
41 + 
    any function that expects a pointer to @ref value.
42 - 
    The storage of the array is handled automatically, being expanded and
42 + 
\n
43 - 
    contracted as needed. Arrays usually occupy more space than array language
43 + 
    The storage of the array is handled automatically, being
44 - 
    constructs, because more memory is allocated to handle future growth. This
44 + 
    expanded and contracted as needed. Arrays usually occupy
45 - 
    way an array does not need to reallocate each time an element is inserted,
45 + 
    more space than array language constructs, because more
46 - 
    but only when the additional memory is used up. The total amount of
46 + 
    memory is allocated to handle future growth. This way an
47 - 
    allocated memory can be queried using the @ref capacity function. Extra
47 + 
    array does not need to reallocate each time an element
48 - 
    memory can be relinquished by calling @ref shrink_to_fit.
48 + 
    is inserted, but only when the additional memory is used
49 -
49 + 
    up. The total amount of allocated memory can be queried
50 -
50 + 
    using the @ref capacity function. Extra memory can be
51 - 
    Reallocations are usually costly operations in terms of performance. The
51 + 
    relinquished by calling @ref shrink_to_fit.
52 - 
    @ref reserve function can be used to eliminate reallocations if the number
52 + 
    \n
53 - 
    of elements is known beforehand.
 
54  
53  
55 - 
    The complexity (efficiency) of common operations on arrays is as follows:
54 + 
    Reallocations are usually costly operations in terms of
 
55 + 
    performance. The @ref reserve function can be used to
 
56 + 
    eliminate reallocations if the number of elements is
 
57 + 
    known beforehand.
 
58 + 
\n
 
59 + 
    The complexity (efficiency) of common operations on
 
60 + 
    arrays is as follows:
56  
61  
57 - 
    @li Random access---constant *O(1)*.
62 + 
    @li Random access - constant *O(1)*.
58 - 
    @li Insertion or removal of elements at the end - amortized
63 + 
    @li Insertion or removal of elements at the
59 - 
        constant *O(1)*.
64 + 
        end - amortized constant *O(1)*.
60 - 
    @li Insertion or removal of elements---linear in the distance to the end of
65 + 
    @li Insertion or removal of elements - linear in
61 - 
        the array *O(n)*.
66 + 
        the distance to the end of the array *O(n)*.
62  
67  
63   
    @par Allocators
68   
    @par Allocators
64  
69  
65 - 
    All elements stored in the container, and their children if any, will use
70 + 
    All elements stored in the container, and their
66 - 
    the same memory resource that was used to construct the container.
71 + 
    children if any, will use the same memory resource
 
72 + 
    that was used to construct the container.
67  
73  
68   
    @par Thread Safety
74   
    @par Thread Safety
69  
75  
70 - 
    Non-const member functions may not be called concurrently with any other
76 + 
    Non-const member functions may not be called
71 - 
    member functions.
77 + 
    concurrently with any other member functions.
72  
78  
73   
    @par Satisfies
79   
    @par Satisfies
74 - 
        [*ContiguousContainer*](https://en.cppreference.com/w/cpp/named_req/ContiguousContainer),
80 + 
        <a href="https://en.cppreference.com/w/cpp/named_req/ContiguousContainer"><em>ContiguousContainer</em></a>,
75 - 
        [*ReversibleContainer*](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer), and
81 + 
        <a href="https://en.cppreference.com/w/cpp/named_req/ReversibleContainer"><em>ReversibleContainer</em></a>, and
76 - 
        {req_SequenceContainer}.
82 + 
        <a href="https://en.cppreference.com/w/cpp/named_req/SequenceContainer"><em>SequenceContainer</em></a>.
77   
*/
83   
*/
78   
class array
84   
class array
79   
{
85   
{
80   
    struct table;
86   
    struct table;
81   
    class revert_construct;
87   
    class revert_construct;
82   
    class revert_insert;
88   
    class revert_insert;
83   
    friend class value;
89   
    friend class value;
84  
90  
85   
    storage_ptr sp_;        // must come first
91   
    storage_ptr sp_;        // must come first
86   
    kind k_ = kind::array;  // must come second
92   
    kind k_ = kind::array;  // must come second
87   
    table* t_;
93   
    table* t_;
88  
94  
89   
    BOOST_JSON_DECL
95   
    BOOST_JSON_DECL
90   
    static table empty_;
96   
    static table empty_;
91  
97  
92   
    inline
98   
    inline
93   
    static
99   
    static
94   
    void
100   
    void
95   
    relocate(
101   
    relocate(
96   
        value* dest,
102   
        value* dest,
97   
        value* src,
103   
        value* src,
98   
        std::size_t n) noexcept;
104   
        std::size_t n) noexcept;
99  
105  
100   
    inline
106   
    inline
101   
    void
107   
    void
102   
    destroy(
108   
    destroy(
103   
        value* first,
109   
        value* first,
104   
        value* last) noexcept;
110   
        value* last) noexcept;
105  
111  
106   
    BOOST_JSON_DECL
112   
    BOOST_JSON_DECL
107   
    void
113   
    void
108   
    destroy() noexcept;
114   
    destroy() noexcept;
109  
115  
110   
    BOOST_JSON_DECL
116   
    BOOST_JSON_DECL
111   
    explicit
117   
    explicit
112   
    array(detail::unchecked_array&& ua);
118   
    array(detail::unchecked_array&& ua);
113  
119  
114   
public:
120   
public:
115   
    /// Associated [Allocator](https://en.cppreference.com/w/cpp/named_req/Allocator)
121   
    /// Associated [Allocator](https://en.cppreference.com/w/cpp/named_req/Allocator)
116   
    using allocator_type = container::pmr::polymorphic_allocator<value>;
122   
    using allocator_type = container::pmr::polymorphic_allocator<value>;
117  
123  
118   
    /// The type used to represent unsigned integers
124   
    /// The type used to represent unsigned integers
119   
    using size_type = std::size_t;
125   
    using size_type = std::size_t;
120  
126  
121   
    /// The type of each element
127   
    /// The type of each element
122   
    using value_type = value;
128   
    using value_type = value;
123  
129  
124   
    /// The type used to represent signed integers
130   
    /// The type used to represent signed integers
125   
    using difference_type = std::ptrdiff_t;
131   
    using difference_type = std::ptrdiff_t;
126  
132  
127   
    /// A reference to an element
133   
    /// A reference to an element
128   
    using reference = value&;
134   
    using reference = value&;
129  
135  
130   
    /// A const reference to an element
136   
    /// A const reference to an element
131   
    using const_reference = value const&;
137   
    using const_reference = value const&;
132  
138  
133   
    /// A pointer to an element
139   
    /// A pointer to an element
134   
    using pointer = value*;
140   
    using pointer = value*;
135  
141  
136   
    /// A const pointer to an element
142   
    /// A const pointer to an element
137   
    using const_pointer = value const*;
143   
    using const_pointer = value const*;
138  
144  
139   
    /// A random access iterator to an element
145   
    /// A random access iterator to an element
140   
    using iterator = value*;
146   
    using iterator = value*;
141  
147  
142   
    /// A random access const iterator to an element
148   
    /// A random access const iterator to an element
143   
    using const_iterator = value const*;
149   
    using const_iterator = value const*;
144  
150  
145   
    /// A reverse random access iterator to an element
151   
    /// A reverse random access iterator to an element
146   
    using reverse_iterator =
152   
    using reverse_iterator =
147   
        std::reverse_iterator<iterator>;
153   
        std::reverse_iterator<iterator>;
148  
154  
149   
    /// A reverse random access const iterator to an element
155   
    /// A reverse random access const iterator to an element
150   
    using const_reverse_iterator =
156   
    using const_reverse_iterator =
151   
        std::reverse_iterator<const_iterator>;
157   
        std::reverse_iterator<const_iterator>;
152  
158  
153   
    //------------------------------------------------------
159   
    //------------------------------------------------------
154  
160  
155   
    /** Destructor.
161   
    /** Destructor.
156  
162  
157 - 
        The destructor for each element is called if needed, any used memory is
163 + 
        The destructor for each element is called if needed,
158 - 
        deallocated, and shared ownership of the
164 + 
        any used memory is deallocated, and shared ownership
159 - 
        @ref boost::container::pmr::memory_resource is released.
165 + 
        of the `boost::container::pmr::memory_resource` is released.
160  
166  
161   
        @par Complexity
167   
        @par Complexity
162 - 
        Linear in @ref size().
168 + 
        Constant, or linear in @ref size().
163  
169  
164   
        @par Exception Safety
170   
        @par Exception Safety
165   
        No-throw guarantee.
171   
        No-throw guarantee.
166   
    */
172   
    */
167   
    BOOST_JSON_DECL
173   
    BOOST_JSON_DECL
168   
    ~array() noexcept;
174   
    ~array() noexcept;
169  
175  
170   
    //------------------------------------------------------
176   
    //------------------------------------------------------
171  
177  
172 - 
    /** Constructors.
178 + 
    /** Constructor.
173 -
 
174 - 
        Constructs an array.
 
175 -
 
176 - 
        @li **(1)**, **(2)**  the array is empty and has zero capacity.
 
177 -
 
178 - 
        @li **(3)** the array is filled with `count` copies of `jv`.
 
179 -
 
180 - 
        @li **(4)** the array is filled with `count` null values.
 
181 -
 
182 - 
        @li **(5)** the array is filled with values in the range
 
183 - 
            `[first, last)`, preserving order.
 
184 -
 
185 - 
        @li **(6)** the array is filled with copies of the values in `init`,
 
186 - 
            preserving order.
 
187 -
 
188 - 
        @li **(7)**, **(8)** the array is filled with copies of the elements of
 
189 - 
            `other`, preserving order.
 
190 -
 
191 - 
        @li **(9)** the array acquires ownership of the contents of `other`.
 
192 -
 
193 - 
        @li **(10)** equivalent to **(9)** if `*sp == *other.storage()`;
 
194 - 
            otherwise equivalent to **(8)**.
 
195 -
 
196 - 
        @li **(11)** the array acquires ownership of the contents of `other`
 
197 - 
            using pilfer semantics. This is more efficient than move
 
198 - 
            construction, when it is known that the moved-from object will be
 
199 - 
            immediately destroyed afterwards.
 
200 -
 
201 - 
        With **(2)**, **(4)**, **(5)**, **(6)**, **(8)**, **(10)** the
 
202 - 
        constructed array uses memory resource of `sp`. With **(7)**, **(9)**,
 
203 - 
        and **(11)** it uses `other`'s memory resource. In either case the
 
204 - 
        array will share the ownership of the memory resource. With **(1)**
 
205 - 
        and **(3)** it uses the
 
206 - 
        \<\<default_memory_resource, default memory resource\>\>.
 
207 -
 
208 - 
        After **(9)** `other` behaves as if newly constructed with its
 
209 - 
        current storage pointer.
 
210 -
 
211 - 
        After **(11)** `other` is not in a usable state and may only be
 
212 - 
        destroyed.
 
213 -
 
214 - 
        @par Constraints
 
215  
179  
216 - 
        @code
180 + 
        The constructed array is empty with zero
217 - 
        std::is_constructible_v<value, std::iterator_traits<InputIt>::reference>
181 + 
        capacity, using the [default memory resource].
218 - 
        @endcode
 
219  
182  
220   
        @par Complexity
183   
        @par Complexity
221 - 
        @li **(1)**, **(2)**, **(9)**, **(11)** constant.
184 + 
        Constant.
222 - 
        @li **(3)**, **(4)** linear in `count`.
 
223 - 
        @li **(5)** linear in `std::distance(first, last)`
 
224 - 
        @li **(6)** linear in `init.size()`.
 
225 - 
        @li **(7)**, **(8)** linear in `other.size()`.
 
226 - 
        @li **(10)** constant if `*sp == *other.storage()`; otherwise linear in
 
227 - 
            `other.size()`.
 
228  
185  
229   
        @par Exception Safety
186   
        @par Exception Safety
230 - 
        @li **(1)**, **(2)**, **(9)**, **(11)** no-throw guarantee.
187 + 
        No-throw guarantee.
231 - 
        @li **(3)**, **(4)**, **(6)**--**(8)**, **(10)** strong
 
232 - 
            guarantee.
 
233 - 
        @li **(5)** strong guarantee if `InputIt` satisfies
 
234 - 
        {req_ForwardIterator}, basic guarantee otherwise.
 
235 -
 
236 - 
        Calls to `memory_resource::allocate` may throw.
 
237  
188  
238 - 
        @see @ref pilfer,
189 + 
        [default memory resource]: json/allocators/storage_ptr.html#json.allocators.storage_ptr.default_memory_resource
239 - 
            [Valueless Variants Considered Harmful](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0308r0.html).
 
240 - 
        @{
 
241   
    */
190   
    */
242   
    array() noexcept
191   
    array() noexcept
243   
        : t_(&empty_)
192   
        : t_(&empty_)
244   
    {
193   
    {
245   
    }
194   
    }
246  
195  
247 - 
    /** Overload
196 + 
    /** Constructor.
248 - 
        @param sp A pointer to the @ref boost::container::pmr::memory_resource
197 +
249 - 
        to use. The container will acquire shared ownership of the memory
198 + 
        The constructed array is empty with zero
250 - 
        resource.
199 + 
        capacity, using the specified memory resource.
 
200 +
 
201 + 
        @par Complexity
 
202 + 
        Constant.
 
203 +
 
204 + 
        @par Exception Safety
 
205 + 
        No-throw guarantee.
 
206 +
 
207 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource`
 
208 + 
        to use. The container will acquire shared
 
209 + 
        ownership of the memory resource.
251   
    */
210   
    */
252   
    explicit
211   
    explicit
253   
    array(storage_ptr sp) noexcept
212   
    array(storage_ptr sp) noexcept
254   
        : sp_(std::move(sp))
213   
        : sp_(std::move(sp))
255   
        , k_(kind::array)
214   
        , k_(kind::array)
256   
        , t_(&empty_)
215   
        , t_(&empty_)
257   
    {
216   
    {
258   
    }
217   
    }
259  
218  
260 - 
    /** Overload
219 + 
    /** Constructor.
 
220 +
 
221 + 
        The array is constructed with `count`
 
222 + 
        copies of the value `v`, using the
 
223 + 
        specified memory resource.
 
224 +
 
225 + 
        @par Complexity
 
226 + 
        Linear in `count`
 
227 +
 
228 + 
        @par Exception Safety
 
229 + 
        Strong guarantee.
 
230 + 
        Calls to `memory_resource::allocate` may throw.
 
231 +
261   
        @param count The number of copies to insert.
232   
        @param count The number of copies to insert.
262 - 
        @param jv The value to be inserted.
233 +
263 - 
        @param sp
234 + 
        @param v The value to be inserted.
 
235 +
 
236 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource`
 
237 + 
        to use. The container will acquire shared
 
238 + 
        ownership of the memory resource.
264   
    */
239   
    */
265   
    BOOST_JSON_DECL
240   
    BOOST_JSON_DECL
266   
    array(
241   
    array(
267   
        std::size_t count,
242   
        std::size_t count,
268 - 
        value const& jv,
243 + 
        value const& v,
269   
        storage_ptr sp = {});
244   
        storage_ptr sp = {});
270  
245  
271 - 
    /// Overload
246 + 
    /** Constructor.
 
247 +
 
248 + 
        The array is constructed with `count` null values,
 
249 + 
        using the specified memory resource.
 
250 +
 
251 + 
        @par Complexity
 
252 + 
        Linear in `count`
 
253 +
 
254 + 
        @par Exception Safety
 
255 + 
        Strong guarantee.
 
256 + 
        Calls to `memory_resource::allocate` may throw.
 
257 +
 
258 + 
        @param count The number of nulls to insert.
 
259 +
 
260 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource`
 
261 + 
        to use. The container will acquire shared
 
262 + 
        ownership of the memory resource.
 
263 + 
    */
272   
    BOOST_JSON_DECL
264   
    BOOST_JSON_DECL
273   
    array(
265   
    array(
274   
        std::size_t count,
266   
        std::size_t count,
275   
        storage_ptr sp = {});
267   
        storage_ptr sp = {});
276  
268  
277 - 
    /** Overload
269 + 
    /** Constructor.
278  
270  
279 - 
        @param first An input iterator pointing to the first element to insert,
271 + 
        The array is constructed with the elements
280 - 
               or pointing to the end of the range.
272 + 
        in the range `{first, last)`, preserving order,
281 - 
        @param last An input iterator pointing to the end of the range.
273 + 
        using the specified memory resource.
282 - 
        @param sp
 
283  
274  
284 - 
        @tparam InputIt a type satisfying the {req_InputIterator} requirement.
275 + 
        @par Constraints
 
276 +
 
277 + 
        @code
 
278 + 
        std::is_constructible_v<value, std::iterator_traits<InputIt>::reference>
 
279 + 
        @endcode
 
280 +
 
281 + 
        @par Complexity
 
282 + 
        Linear in `std::distance(first, last)`
 
283 +
 
284 + 
        @par Exception Safety
 
285 + 
        Strong guarantee.
 
286 + 
        Calls to `memory_resource::allocate` may throw.
 
287 +
 
288 + 
        @param first An input iterator pointing to the
 
289 + 
        first element to insert, or pointing to the end
 
290 + 
        of the range.
 
291 +
 
292 + 
        @param last An input iterator pointing to the end
 
293 + 
        of the range.
 
294 +
 
295 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource`
 
296 + 
        to use. The container will acquire shared
 
297 + 
        ownership of the memory resource.
 
298 +
 
299 + 
        @tparam InputIt a type satisfying the requirements
 
300 + 
        of __InputIterator__.
285   
    */
301   
    */
286   
    template<
302   
    template<
287   
        class InputIt
303   
        class InputIt
288   
    #ifndef BOOST_JSON_DOCS
304   
    #ifndef BOOST_JSON_DOCS
289   
        ,class = typename std::enable_if<
305   
        ,class = typename std::enable_if<
290   
            std::is_constructible<value,
306   
            std::is_constructible<value,
291   
                typename std::iterator_traits<
307   
                typename std::iterator_traits<
292   
                    InputIt>::reference>::value>::type
308   
                    InputIt>::reference>::value>::type
293   
    #endif
309   
    #endif
294   
    >
310   
    >
295   
    array(
311   
    array(
296   
        InputIt first, InputIt last,
312   
        InputIt first, InputIt last,
297   
        storage_ptr sp = {});
313   
        storage_ptr sp = {});
298  
314  
299 - 
    /** Overload
315 + 
    /** Copy constructor.
300 - 
        @param init The initializer list with elements to insert.
 
301 - 
        @param sp
 
302 - 
    */
 
303 - 
    BOOST_JSON_DECL
 
304 - 
    array(
 
305 - 
        std::initializer_list<value_ref> init,
 
306 - 
        storage_ptr sp = {});
 
307  
316  
308 - 
    /** Overload
317 + 
        The array is constructed with a copy of the
309 - 
        @param other Another array.
318 + 
        contents of `other`, using `other`'s memory resource.
 
319 +
 
320 + 
        @par Complexity
 
321 + 
        Linear in `other.size()`.
 
322 +
 
323 + 
        @par Exception Safety
 
324 + 
        Strong guarantee.
 
325 + 
        Calls to `memory_resource::allocate` may throw.
 
326 +
 
327 + 
        @param other The array to copy
310   
    */
328   
    */
311   
    BOOST_JSON_DECL
329   
    BOOST_JSON_DECL
312   
    array(array const& other);
330   
    array(array const& other);
313  
331  
314 - 
    /// Overload
332 + 
    /** Copy constructor.
 
333 +
 
334 + 
        The array is constructed with a copy of the
 
335 + 
        contents of `other`, using the specified memory resource.
 
336 +
 
337 + 
        @par Complexity
 
338 + 
        Linear in `other.size()`.
 
339 +
 
340 + 
        @par Exception Safety
 
341 + 
        Strong guarantee.
 
342 + 
        Calls to `memory_resource::allocate` may throw.
 
343 +
 
344 + 
        @param other The array to copy
 
345 +
 
346 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource`
 
347 + 
        to use. The container will acquire shared
 
348 + 
        ownership of the memory resource.
 
349 + 
    */
315   
    BOOST_JSON_DECL
350   
    BOOST_JSON_DECL
316   
    array(
351   
    array(
317   
        array const& other,
352   
        array const& other,
318   
        storage_ptr sp);
353   
        storage_ptr sp);
319  
354  
320 - 
    /// Overload
355 + 
    /** Pilfer constructor.
 
356 +
 
357 + 
        The array is constructed by acquiring ownership
 
358 + 
        of the contents of `other` using pilfer semantics.
 
359 + 
        This is more efficient than move construction, when
 
360 + 
        it is known that the moved-from object will be
 
361 + 
        immediately destroyed afterwards.
 
362 +
 
363 + 
        @par Complexity
 
364 + 
        Constant.
 
365 +
 
366 + 
        @par Exception Safety
 
367 + 
        No-throw guarantee.
 
368 +
 
369 + 
        @param other The value to pilfer. After pilfer
 
370 + 
        construction, `other` is not in a usable state
 
371 + 
        and may only be destroyed.
 
372 +
 
373 + 
        @see @ref pilfer,
 
374 + 
            <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0308r0.html">
 
375 + 
                Valueless Variants Considered Harmful</a>
 
376 + 
    */
 
377 + 
    array(pilfered<array> other) noexcept
 
378 + 
        : sp_(std::move(other.get().sp_))
 
379 + 
        , t_(detail::exchange(
 
380 + 
            other.get().t_, &empty_))
 
381 + 
    {
 
382 + 
    }
 
383 +
 
384 + 
    /** Move constructor.
 
385 +
 
386 + 
        The array is constructed by acquiring ownership of
 
387 + 
        the contents of `other` and shared ownership of
 
388 + 
        `other`'s memory resource.
 
389 +
 
390 + 
        @note
 
391 +
 
392 + 
        After construction, the moved-from array behaves
 
393 + 
        as if newly constructed with its current storage
 
394 + 
        pointer.
 
395 +
 
396 + 
        @par Complexity
 
397 + 
        Constant.
 
398 +
 
399 + 
        @par Exception Safety
 
400 + 
        No-throw guarantee.
 
401 +
 
402 + 
        @param other The container to move
 
403 + 
    */
321   
    array(array&& other) noexcept
404   
    array(array&& other) noexcept
322   
        : sp_(other.sp_)
405   
        : sp_(other.sp_)
323   
        , t_(detail::exchange(
406   
        , t_(detail::exchange(
324   
            other.t_, &empty_))
407   
            other.t_, &empty_))
325   
    {
408   
    {
326   
    }
409   
    }
327  
410  
328 - 
    /// Overload
411 + 
    /** Move constructor.
 
412 +
 
413 + 
        The array is constructed with the contents of
 
414 + 
        `other` by move semantics, using the specified
 
415 + 
        memory resource:
 
416 +
 
417 + 
        @li If `*other.storage() == *sp`, ownership of
 
418 + 
        the underlying memory is transferred in constant
 
419 + 
        time, with no possibility of exceptions.
 
420 + 
        After construction, the moved-from array behaves
 
421 + 
        as if newly constructed with its current storage
 
422 + 
        pointer.
 
423 +
 
424 + 
        @li If `*other.storage() != *sp`, an
 
425 + 
        element-wise copy is performed, which may throw.
 
426 + 
        In this case, the moved-from array is not
 
427 + 
        changed.
 
428 +
 
429 + 
        @par Complexity
 
430 + 
        At most, linear in `other.size()`.
 
431 +
 
432 + 
        @par Exception Safety
 
433 + 
        Strong guarantee.
 
434 + 
        Calls to `memory_resource::allocate` may throw.
 
435 +
 
436 + 
        @param other The container to move
 
437 +
 
438 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource`
 
439 + 
        to use. The container will acquire shared
 
440 + 
        ownership of the memory resource.
 
441 + 
    */
329   
    BOOST_JSON_DECL
442   
    BOOST_JSON_DECL
330   
    array(
443   
    array(
331   
        array&& other,
444   
        array&& other,
332   
        storage_ptr sp);
445   
        storage_ptr sp);
333  
446  
334 - 
    /// Overload
447 + 
    /** Constructor.
335 - 
    array(pilfered<array> other) noexcept
 
336 - 
        : sp_(std::move(other.get().sp_))
 
337 - 
        , t_(detail::exchange(
 
338 - 
            other.get().t_, &empty_))
 
339 - 
    {
 
340 - 
    }
 
341 - 
    /// @}
 
342  
448  
343 - 
    /** Assignment operators.
449 + 
        The array is constructed with a copy of the values
 
450 + 
        in the initializer-list in order, using the
 
451 + 
        specified memory resource.
344  
452  
345 - 
        Replaces the contents of the array.
453 + 
        @par Complexity
346 - 
        @li **(1)** the contents are replaced with an element-wise copy of
454 + 
        Linear in `init.size()`.
347 - 
            `other`.
 
348 - 
        @li **(2)** takes ownership of `other`'s element storage if
 
349 - 
            `*storage() == *other.storage()`; otherwise equivalent to **(1)**.
 
350 - 
        @li **(3)** the contents are replaced with a copy of the values in
 
351 - 
            `init`.
 
352  
455  
353 - 
        After **(2)**, the moved-from array behaves as if newly constructed
456 + 
        @par Exception Safety
354 - 
        with its current storage pointer.
457 + 
        Strong guarantee.
 
458 + 
        Calls to `memory_resource::allocate` may throw.
 
459 +
 
460 + 
        @param init The initializer list to insert
 
461 +
 
462 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource`
 
463 + 
        to use. The container will acquire shared
 
464 + 
        ownership of the memory resource.
 
465 + 
    */
 
466 + 
    BOOST_JSON_DECL
 
467 + 
    array(
 
468 + 
        std::initializer_list<value_ref> init,
 
469 + 
        storage_ptr sp = {});
 
470 +
 
471 + 
    //------------------------------------------------------
 
472 +
 
473 + 
    /** Copy assignment.
 
474 +
 
475 + 
        The contents of the array are replaced with an
 
476 + 
        element-wise copy of `other`.
355  
477  
356   
        @par Complexity
478   
        @par Complexity
357 - 
        @li **(1)** linear in `size() + other.size()`.
479 + 
        Linear in @ref size() plus `other.size()`.
358 - 
        @li **(2)** constant if `*storage() == *other.storage()`; otherwise
 
359 - 
            linear in `size() + other.size()`.
 
360 - 
        @li **(1)** linear in `size() + init.size()`.
 
361  
480  
362   
        @par Exception Safety
481   
        @par Exception Safety
363 - 
        {sp} **(2)** provides strong guarantee if
482 + 
        Strong guarantee.
364 - 
        `*storage() != *other.storage()` and no-throw guarantee otherwise.
 
365 - 
        Other overloads provide strong guarantee.
 
366   
        Calls to `memory_resource::allocate` may throw.
483   
        Calls to `memory_resource::allocate` may throw.
367  
484  
368 -
 
369 - 
        @return `*this`
 
370 -
 
371 - 
        @{
 
372   
        @param other The array to copy.
485   
        @param other The array to copy.
373   
    */
486   
    */
374   
    BOOST_JSON_DECL
487   
    BOOST_JSON_DECL
375   
    array&
488   
    array&
376   
    operator=(array const& other);
489   
    operator=(array const& other);
377  
490  
378 - 
    /** Overload
491 + 
    /** Move assignment.
 
492 +
 
493 + 
        The contents of the array are replaced with the
 
494 + 
        contents of `other` using move semantics:
 
495 +
 
496 + 
        @li If `*other.storage() == *sp`, ownership of
 
497 + 
        the underlying memory is transferred in constant
 
498 + 
        time, with no possibility of exceptions.
 
499 + 
        After assignment, the moved-from array behaves
 
500 + 
        as if newly constructed with its current storage
 
501 + 
        pointer.
 
502 +
 
503 + 
        @li If `*other.storage() != *sp`, an
 
504 + 
        element-wise copy is performed, which may throw.
 
505 + 
        In this case, the moved-from array is not
 
506 + 
        changed.
 
507 +
 
508 + 
        @par Complexity
 
509 + 
        Constant, or linear in
 
510 + 
        `this->size()` plus `other.size()`.
 
511 +
 
512 + 
        @par Exception Safety
 
513 + 
        Strong guarantee.
 
514 + 
        Calls to `memory_resource::allocate` may throw.
 
515 +
379   
        @param other The array to move.
516   
        @param other The array to move.
380   
    */
517   
    */
381   
    BOOST_JSON_DECL
518   
    BOOST_JSON_DECL
382   
    array&
519   
    array&
383   
    operator=(array&& other);
520   
    operator=(array&& other);
384  
521  
385 - 
    /** Overload
522 + 
    /** Assignment.
 
523 +
 
524 + 
        The contents of the array are replaced with a
 
525 + 
        copy of the values in the initializer-list.
 
526 +
 
527 + 
        @par Complexity
 
528 + 
        Linear in `this->size()` plus `init.size()`.
 
529 +
 
530 + 
        @par Exception Safety
 
531 + 
        Strong guarantee.
 
532 + 
        Calls to `memory_resource::allocate` may throw.
 
533 +
386   
        @param init The initializer list to copy.
534   
        @param init The initializer list to copy.
387   
    */
535   
    */
388   
    BOOST_JSON_DECL
536   
    BOOST_JSON_DECL
389   
    array&
537   
    array&
390   
    operator=(
538   
    operator=(
391   
        std::initializer_list<value_ref> init);
539   
        std::initializer_list<value_ref> init);
392 - 
    /// @}
540 +
 
541 + 
    //------------------------------------------------------
393  
542  
394   
    /** Return the associated memory resource.
543   
    /** Return the associated memory resource.
395  
544  
396 - 
        This function returns a smart pointer to the
545 + 
        This function returns the `boost::container::pmr::memory_resource` used
397 - 
        @ref boost::container::pmr::memory_resource used by the container.
546 + 
        by the container.
398  
547  
399   
        @par Complexity
548   
        @par Complexity
400   
        Constant.
549   
        Constant.
401  
550  
402   
        @par Exception Safety
551   
        @par Exception Safety
403   
        No-throw guarantee.
552   
        No-throw guarantee.
404   
    */
553   
    */
405   
    storage_ptr const&
554   
    storage_ptr const&
406   
    storage() const noexcept
555   
    storage() const noexcept
407   
    {
556   
    {
408   
        return sp_;
557   
        return sp_;
409   
    }
558   
    }
410  
559  
411   
    /** Return the associated allocator.
560   
    /** Return the associated allocator.
412  
561  
413   
        This function returns an instance of @ref allocator_type constructed
562   
        This function returns an instance of @ref allocator_type constructed
414 - 
        from the associated @ref boost::container::pmr::memory_resource.
563 + 
        from the associated `boost::container::pmr::memory_resource`.
415  
564  
416   
        @par Complexity
565   
        @par Complexity
417   
        Constant.
566   
        Constant.
418  
567  
419   
        @par Exception Safety
568   
        @par Exception Safety
420   
        No-throw guarantee.
569   
        No-throw guarantee.
421   
    */
570   
    */
422   
    allocator_type
571   
    allocator_type
423   
    get_allocator() const noexcept
572   
    get_allocator() const noexcept
424   
    {
573   
    {
425   
        return sp_.get();
574   
        return sp_.get();
426   
    }
575   
    }
427  
576  
428   
    //------------------------------------------------------
577   
    //------------------------------------------------------
429   
    //
578   
    //
430   
    // Element access
579   
    // Element access
431   
    //
580   
    //
432   
    //------------------------------------------------------
581   
    //------------------------------------------------------
433  
582  
434   
    /** Access an element, with bounds checking.
583   
    /** Access an element, with bounds checking.
435  
584  
436 - 
        Returns @ref boost::system::result containing a reference to the
585 + 
        Returns `boost::system::result` containing a reference to the element
437 - 
        element specified at location `pos`, if `pos` is within the range of
586 + 
        specified at location `pos`, if `pos` is within the range of the
438 - 
        the container. Otherwise the result contains an `error_code`.
587 + 
        container. Otherwise the result contains an `error_code`.
439  
588  
440   
        @par Exception Safety
589   
        @par Exception Safety
441   
        No-throw guarantee.
590   
        No-throw guarantee.
442  
591  
443   
        @param pos A zero-based index.
592   
        @param pos A zero-based index.
444  
593  
445   
        @par Complexity
594   
        @par Complexity
446 -
 
447 - 
        @{
 
448   
        Constant.
595   
        Constant.
449   
    */
596   
    */
 
597 + 
    /** @{ */
450   
    BOOST_JSON_DECL
598   
    BOOST_JSON_DECL
451   
    system::result<value&>
599   
    system::result<value&>
452   
    try_at(std::size_t pos) noexcept;
600   
    try_at(std::size_t pos) noexcept;
453  
601  
454   
    BOOST_JSON_DECL
602   
    BOOST_JSON_DECL
455   
    system::result<value const&>
603   
    system::result<value const&>
456   
    try_at(std::size_t pos) const noexcept;
604   
    try_at(std::size_t pos) const noexcept;
457 - 
    /// @}
605 + 
    /** @} */
458  
606  
459   
    /** Access an element, with bounds checking.
607   
    /** Access an element, with bounds checking.
460  
608  
461 - 
        Returns a reference to the element specified at location `pos`, with
609 + 
        Returns a reference to the element specified at
462 - 
        bounds checking. If `pos` is not within the range of the container, an
610 + 
        location `pos`, with bounds checking. If `pos` is
463 - 
        exception of type @ref boost::system::system_error is thrown.
611 + 
        not within the range of the container, an exception
 
612 + 
        of type `boost::system::system_error` is thrown.
464  
613  
465   
        @par Complexity
614   
        @par Complexity
466   
        Constant.
615   
        Constant.
467  
616  
468   
        @param pos A zero-based index.
617   
        @param pos A zero-based index.
469  
618  
470   
        @param loc `source_location` to use in thrown exception; the source
619   
        @param loc `source_location` to use in thrown exception; the source
471   
            location of the call site by default.
620   
            location of the call site by default.
472  
621  
473 -
 
474 - 
        @{
 
475   
        @throw `boost::system::system_error` `pos >= size()`.
622   
        @throw `boost::system::system_error` `pos >= size()`.
476   
    */
623   
    */
 
624 + 
    /** @{ */
477   
    inline
625   
    inline
478   
    value&
626   
    value&
479   
    at(
627   
    at(
480   
        std::size_t pos,
628   
        std::size_t pos,
481   
        source_location const& loc = BOOST_CURRENT_LOCATION) &;
629   
        source_location const& loc = BOOST_CURRENT_LOCATION) &;
482  
630  
483   
    inline
631   
    inline
484   
    value&&
632   
    value&&
485   
    at(
633   
    at(
486   
        std::size_t pos,
634   
        std::size_t pos,
487   
        source_location const& loc = BOOST_CURRENT_LOCATION) &&;
635   
        source_location const& loc = BOOST_CURRENT_LOCATION) &&;
488  
636  
489   
    BOOST_JSON_DECL
637   
    BOOST_JSON_DECL
490   
    value const&
638   
    value const&
491   
    at(
639   
    at(
492   
        std::size_t pos,
640   
        std::size_t pos,
493   
        source_location const& loc = BOOST_CURRENT_LOCATION) const&;
641   
        source_location const& loc = BOOST_CURRENT_LOCATION) const&;
494 - 
    /// @}
642 + 
    /** @} */
495  
643  
496   
    /** Access an element.
644   
    /** Access an element.
497  
645  
498   
        Returns a reference to the element specified at
646   
        Returns a reference to the element specified at
499   
        location `pos`. No bounds checking is performed.
647   
        location `pos`. No bounds checking is performed.
500  
648  
501 - 
        @pre `pos < size()`
649 + 
        @par Precondition
 
650 + 
        `pos < size()`
502  
651  
503   
        @par Complexity
652   
        @par Complexity
504   
        Constant.
653   
        Constant.
505  
654  
506 -
 
507 - 
        @{
 
508   
        @param pos A zero-based index
655   
        @param pos A zero-based index
509   
    */
656   
    */
 
657 + 
    /** @{ */
510   
    inline
658   
    inline
511   
    value&
659   
    value&
512   
    operator[](std::size_t pos) & noexcept;
660   
    operator[](std::size_t pos) & noexcept;
513  
661  
514   
    inline
662   
    inline
515   
    value&&
663   
    value&&
516   
    operator[](std::size_t pos) && noexcept;
664   
    operator[](std::size_t pos) && noexcept;
517  
665  
518   
    inline
666   
    inline
519   
    value const&
667   
    value const&
520   
    operator[](std::size_t pos) const& noexcept;
668   
    operator[](std::size_t pos) const& noexcept;
521 - 
    /// @}
669 + 
    /** @} */
522  
670  
523   
    /** Access the first element.
671   
    /** Access the first element.
524  
672  
525   
        Returns a reference to the first element.
673   
        Returns a reference to the first element.
526  
674  
527 - 
        @pre `! empty()`
675 + 
        @par Precondition
 
676 + 
        `not empty()`
528  
677  
529   
        @par Complexity
678   
        @par Complexity
530 -
 
531 - 
        @{
 
532   
        Constant.
679   
        Constant.
533   
    */
680   
    */
 
681 + 
    /** @{ */
534   
    inline
682   
    inline
535   
    value&
683   
    value&
536   
    front() & noexcept;
684   
    front() & noexcept;
537  
685  
538   
    inline
686   
    inline
539   
    value&&
687   
    value&&
540   
    front() && noexcept;
688   
    front() && noexcept;
541  
689  
542   
    inline
690   
    inline
543   
    value const&
691   
    value const&
544   
    front() const& noexcept;
692   
    front() const& noexcept;
545 - 
    /// @}
693 + 
    /** @} */
546  
694  
547   
    /** Access the last element.
695   
    /** Access the last element.
548  
696  
549   
        Returns a reference to the last element.
697   
        Returns a reference to the last element.
550  
698  
551 - 
        @pre `!empty()`
699 + 
        @par Precondition
 
700 + 
        `not empty()`
552  
701  
553   
        @par Complexity
702   
        @par Complexity
554 -
 
555 - 
        @{
 
556   
        Constant.
703   
        Constant.
557   
    */
704   
    */
 
705 + 
    /** @{ */
558   
    inline
706   
    inline
559   
    value&
707   
    value&
560   
    back() & noexcept;
708   
    back() & noexcept;
561  
709  
562   
    inline
710   
    inline
563   
    value&&
711   
    value&&
564   
    back() && noexcept;
712   
    back() && noexcept;
565  
713  
566   
    inline
714   
    inline
567   
    value const&
715   
    value const&
568   
    back() const& noexcept;
716   
    back() const& noexcept;
569 - 
    /// @}
717 + 
    /** @} */
570  
718  
571   
    /** Access the underlying array directly.
719   
    /** Access the underlying array directly.
572  
720  
573 - 
        Returns a pointer to the underlying array serving as element storage.
721 + 
        Returns a pointer to the underlying array serving
574 - 
        The value returned is such that the range `[data(), data() + size())`
722 + 
        as element storage. The value returned is such that
575 - 
        is always a valid range, even if the container is empty.
723 + 
        the range `{data(), data() + size())` is always a
576 -
724 + 
        valid range, even if the container is empty.
577 - 
        @note
 
578 - 
        If `size() == 0`, the function may or may not return
 
579 - 
        a null pointer.
 
580  
725  
581   
        @par Complexity
726   
        @par Complexity
582   
        Constant.
727   
        Constant.
583  
728  
584   
        @par Exception Safety
729   
        @par Exception Safety
585   
        No-throw guarantee.
730   
        No-throw guarantee.
586  
731  
587 - 
        @{
732 + 
        @note
 
733 +
 
734 + 
        If `size() == 0`, the function may or may not return
 
735 + 
        a null pointer.
588   
    */
736   
    */
589   
    inline
737   
    inline
590   
    value*
738   
    value*
591   
    data() noexcept;
739   
    data() noexcept;
592  
740  
 
741 + 
    /** Access the underlying array directly.
 
742 +
 
743 + 
        Returns a pointer to the underlying array serving
 
744 + 
        as element storage. The value returned is such that
 
745 + 
        the range `{data(), data() + size())` is always a
 
746 + 
        valid range, even if the container is empty.
 
747 +
 
748 + 
        @par Complexity
 
749 + 
        Constant.
 
750 +
 
751 + 
        @par Exception Safety
 
752 + 
        No-throw guarantee.
 
753 +
 
754 + 
        @note
 
755 +
 
756 + 
        If `size() == 0`, the function may or may not return
 
757 + 
        a null pointer.
 
758 + 
    */
593   
    inline
759   
    inline
594   
    value const*
760   
    value const*
595 - 
    /// @}
 
596   
    data() const noexcept;
761   
    data() const noexcept;
597  
762  
598 - 
    /** Return a pointer to an element if it exists.
763 + 
    /** Return a pointer to an element, or nullptr if the index is invalid
599  
764  
600 - 
        This function returns a pointer to the element at index `pos` when the
765 + 
        This function returns a pointer to the element
601 - 
        index is less then the size of the container. Otherwise it returns
766 + 
        at index `pos` when the index is less then the size
602 - 
        null.
767 + 
        of the container. Otherwise it returns null.
603  
768  
604   
        @par Example
769   
        @par Example
605   
        @code
770   
        @code
606   
        if( auto p = arr.if_contains( 1 ) )
771   
        if( auto p = arr.if_contains( 1 ) )
607   
            std::cout << *p;
772   
            std::cout << *p;
608   
        @endcode
773   
        @endcode
609  
774  
610   
        @par Complexity
775   
        @par Complexity
611   
        Constant.
776   
        Constant.
612  
777  
613   
        @par Exception Safety
778   
        @par Exception Safety
614   
        No-throw guarantee.
779   
        No-throw guarantee.
615  
780  
616 -
 
617 - 
        @{
 
618   
        @param pos The index of the element to return.
781   
        @param pos The index of the element to return.
619   
    */
782   
    */
620   
    inline
783   
    inline
621   
    value const*
784   
    value const*
622   
    if_contains(std::size_t pos) const noexcept;
785   
    if_contains(std::size_t pos) const noexcept;
623  
786  
 
787 + 
    /** Return a pointer to an element, or nullptr if the index is invalid
 
788 +
 
789 + 
        This function returns a pointer to the element
 
790 + 
        at index `pos` when the index is less then the size
 
791 + 
        of the container. Otherwise it returns null.
 
792 +
 
793 + 
        @par Example
 
794 + 
        @code
 
795 + 
        if( auto p = arr.if_contains( 1 ) )
 
796 + 
            std::cout << *p;
 
797 + 
        @endcode
 
798 +
 
799 + 
        @par Complexity
 
800 + 
        Constant.
 
801 +
 
802 + 
        @par Exception Safety
 
803 + 
        No-throw guarantee.
 
804 +
 
805 + 
        @param pos The index of the element to return.
 
806 + 
    */
624   
    inline
807   
    inline
625   
    value*
808   
    value*
626 - 
    /// @}
 
627   
    if_contains(std::size_t pos) noexcept;
809   
    if_contains(std::size_t pos) noexcept;
628  
810  
629   
    //------------------------------------------------------
811   
    //------------------------------------------------------
630   
    //
812   
    //
631   
    // Iterators
813   
    // Iterators
632   
    //
814   
    //
633   
    //------------------------------------------------------
815   
    //------------------------------------------------------
634  
816  
635   
    /** Return an iterator to the first element.
817   
    /** Return an iterator to the first element.
636  
818  
637   
        If the container is empty, @ref end() is returned.
819   
        If the container is empty, @ref end() is returned.
638  
820  
639   
        @par Complexity
821   
        @par Complexity
640   
        Constant.
822   
        Constant.
641  
823  
642   
        @par Exception Safety
824   
        @par Exception Safety
643 -
 
644 - 
        @{
 
645   
        No-throw guarantee.
825   
        No-throw guarantee.
646   
    */
826   
    */
647   
    inline
827   
    inline
648   
    iterator
828   
    iterator
649   
    begin() noexcept;
829   
    begin() noexcept;
650  
830  
 
831 + 
    /** Return a const iterator to the first element.
 
832 +
 
833 + 
        If the container is empty, @ref end() is returned.
 
834 +
 
835 + 
        @par Complexity
 
836 + 
        Constant.
 
837 +
 
838 + 
        @par Exception Safety
 
839 + 
        No-throw guarantee.
 
840 + 
    */
651   
    inline
841   
    inline
652   
    const_iterator
842   
    const_iterator
653 - 
    /// @}
 
654   
    begin() const noexcept;
843   
    begin() const noexcept;
655  
844  
656   
    /** Return a const iterator to the first element.
845   
    /** Return a const iterator to the first element.
657  
846  
658   
        If the container is empty, @ref cend() is returned.
847   
        If the container is empty, @ref cend() is returned.
659  
848  
660   
        @par Complexity
849   
        @par Complexity
661   
        Constant.
850   
        Constant.
662  
851  
663   
        @par Exception Safety
852   
        @par Exception Safety
664   
        No-throw guarantee.
853   
        No-throw guarantee.
665   
    */
854   
    */
666   
    inline
855   
    inline
667   
    const_iterator
856   
    const_iterator
668   
    cbegin() const noexcept;
857   
    cbegin() const noexcept;
669  
858  
670 - 
    /** Return a const iterator past the last element.
859 + 
    /** Return an iterator to the element following the last element.
671  
860  
672 - 
        The returned iterator only acts as a sentinel. Dereferencing it results
861 + 
        The element acts as a placeholder; attempting
673 - 
        in undefined behavior.
862 + 
        to access it results in undefined behavior.
674  
863  
675   
        @par Complexity
864   
        @par Complexity
676   
        Constant.
865   
        Constant.
677  
866  
678   
        @par Exception Safety
867   
        @par Exception Safety
679 -
 
680 - 
        @{
 
681   
        No-throw guarantee.
868   
        No-throw guarantee.
682   
    */
869   
    */
683   
    inline
870   
    inline
684   
    iterator
871   
    iterator
685   
    end() noexcept;
872   
    end() noexcept;
686  
873  
 
874 + 
    /** Return a const iterator to the element following the last element.
 
875 +
 
876 + 
        The element acts as a placeholder; attempting
 
877 + 
        to access it results in undefined behavior.
 
878 +
 
879 + 
        @par Complexity
 
880 + 
        Constant.
 
881 +
 
882 + 
        @par Exception Safety
 
883 + 
        No-throw guarantee.
 
884 + 
    */
687   
    inline
885   
    inline
688   
    const_iterator
886   
    const_iterator
689 - 
    /// @}
 
690   
    end() const noexcept;
887   
    end() const noexcept;
691  
888  
692 - 
    /** Return a const iterator past the last element.
889 + 
    /** Return a const iterator to the element following the last element.
693  
890  
694 - 
        The returned iterator only acts as a sentinel. Dereferencing it results
891 + 
        The element acts as a placeholder; attempting
695 - 
        in undefined behavior.
892 + 
        to access it results in undefined behavior.
696  
893  
697   
        @par Complexity
894   
        @par Complexity
698   
        Constant.
895   
        Constant.
699  
896  
700   
        @par Exception Safety
897   
        @par Exception Safety
701   
        No-throw guarantee.
898   
        No-throw guarantee.
702   
    */
899   
    */
703   
    inline
900   
    inline
704   
    const_iterator
901   
    const_iterator
705   
    cend() const noexcept;
902   
    cend() const noexcept;
706  
903  
707   
    /** Return a reverse iterator to the first element of the reversed container.
904   
    /** Return a reverse iterator to the first element of the reversed container.
708  
905  
709   
        The pointed-to element corresponds to the
906   
        The pointed-to element corresponds to the
710   
        last element of the non-reversed container.
907   
        last element of the non-reversed container.
711   
        If the container is empty, @ref rend() is returned.
908   
        If the container is empty, @ref rend() is returned.
712  
909  
713   
        @par Complexity
910   
        @par Complexity
714   
        Constant.
911   
        Constant.
715  
912  
716   
        @par Exception Safety
913   
        @par Exception Safety
717 -
 
718 - 
        @{
 
719   
        No-throw guarantee.
914   
        No-throw guarantee.
720   
    */
915   
    */
721   
    inline
916   
    inline
722   
    reverse_iterator
917   
    reverse_iterator
723   
    rbegin() noexcept;
918   
    rbegin() noexcept;
724  
919  
 
920 + 
    /** Return a const reverse iterator to the first element of the reversed container.
 
921 +
 
922 + 
        The pointed-to element corresponds to the
 
923 + 
        last element of the non-reversed container.
 
924 + 
        If the container is empty, @ref rend() is returned.
 
925 +
 
926 + 
        @par Complexity
 
927 + 
        Constant.
 
928 +
 
929 + 
        @par Exception Safety
 
930 + 
        No-throw guarantee.
 
931 + 
    */
725   
    inline
932   
    inline
726   
    const_reverse_iterator
933   
    const_reverse_iterator
727 - 
    /// @}
 
728   
    rbegin() const noexcept;
934   
    rbegin() const noexcept;
729  
935  
730   
    /** Return a const reverse iterator to the first element of the reversed container.
936   
    /** Return a const reverse iterator to the first element of the reversed container.
731  
937  
732   
        The pointed-to element corresponds to the
938   
        The pointed-to element corresponds to the
733   
        last element of the non-reversed container.
939   
        last element of the non-reversed container.
734   
        If the container is empty, @ref crend() is returned.
940   
        If the container is empty, @ref crend() is returned.
735  
941  
736   
        @par Complexity
942   
        @par Complexity
737   
        Constant.
943   
        Constant.
738  
944  
739   
        @par Exception Safety
945   
        @par Exception Safety
740   
        No-throw guarantee.
946   
        No-throw guarantee.
741   
    */
947   
    */
742   
    inline
948   
    inline
743   
    const_reverse_iterator
949   
    const_reverse_iterator
744   
    crbegin() const noexcept;
950   
    crbegin() const noexcept;
745  
951  
746   
    /** Return a reverse iterator to the element following the last element of the reversed container.
952   
    /** Return a reverse iterator to the element following the last element of the reversed container.
747  
953  
748   
        The pointed-to element corresponds to the element
954   
        The pointed-to element corresponds to the element
749   
        preceding the first element of the non-reversed container.
955   
        preceding the first element of the non-reversed container.
750 - 
        The returned iterator only acts as a sentinel. Dereferencing it results
956 + 
        The element acts as a placeholder; attempting
751 - 
        in undefined behavior.
957 + 
        to access it results in undefined behavior.
752  
958  
753   
        @par Complexity
959   
        @par Complexity
754   
        Constant.
960   
        Constant.
755  
961  
756   
        @par Exception Safety
962   
        @par Exception Safety
757 -
 
758 - 
        @{
 
759   
        No-throw guarantee.
963   
        No-throw guarantee.
760   
    */
964   
    */
761   
    inline
965   
    inline
762   
    reverse_iterator
966   
    reverse_iterator
763   
    rend() noexcept;
967   
    rend() noexcept;
764  
968  
 
969 + 
    /** Return a const reverse iterator to the element following the last element of the reversed container.
 
970 +
 
971 + 
        The pointed-to element corresponds to the element
 
972 + 
        preceding the first element of the non-reversed container.
 
973 + 
        The element acts as a placeholder; attempting
 
974 + 
        to access it results in undefined behavior.
 
975 +
 
976 + 
        @par Complexity
 
977 + 
        Constant.
 
978 +
 
979 + 
        @par Exception Safety
 
980 + 
        No-throw guarantee.
 
981 + 
    */
765   
    inline
982   
    inline
766   
    const_reverse_iterator
983   
    const_reverse_iterator
767 - 
    /// @}
 
768   
    rend() const noexcept;
984   
    rend() const noexcept;
769  
985  
770   
    /** Return a const reverse iterator to the element following the last element of the reversed container.
986   
    /** Return a const reverse iterator to the element following the last element of the reversed container.
771  
987  
772 - 
        The pointed-to element corresponds to the element preceding the first
988 + 
        The pointed-to element corresponds to the element
773 - 
        element of the non-reversed container. The returned iterator only acts
989 + 
        preceding the first element of the non-reversed container.
774 - 
        as a sentinel. Dereferencing it results in undefined behavior.
990 + 
        The element acts as a placeholder; attempting
 
991 + 
        to access it results in undefined behavior.
775  
992  
776   
        @par Complexity
993   
        @par Complexity
777   
        Constant.
994   
        Constant.
778  
995  
779   
        @par Exception Safety
996   
        @par Exception Safety
780   
        No-throw guarantee.
997   
        No-throw guarantee.
781   
    */
998   
    */
782   
    inline
999   
    inline
783   
    const_reverse_iterator
1000   
    const_reverse_iterator
784   
    crend() const noexcept;
1001   
    crend() const noexcept;
785  
1002  
786   
    //------------------------------------------------------
1003   
    //------------------------------------------------------
787   
    //
1004   
    //
788   
    // Capacity
1005   
    // Capacity
789   
    //
1006   
    //
790   
    //------------------------------------------------------
1007   
    //------------------------------------------------------
791  
1008  
792   
    /** Return the number of elements in the array.
1009   
    /** Return the number of elements in the array.
793  
1010  
794   
        This returns the number of elements in the array.
1011   
        This returns the number of elements in the array.
795   
        The value returned may be different from the number
1012   
        The value returned may be different from the number
796   
        returned from @ref capacity.
1013   
        returned from @ref capacity.
797  
1014  
798   
        @par Complexity
1015   
        @par Complexity
799   
        Constant.
1016   
        Constant.
800  
1017  
801   
        @par Exception Safety
1018   
        @par Exception Safety
802   
        No-throw guarantee.
1019   
        No-throw guarantee.
803   
    */
1020   
    */
804   
    inline
1021   
    inline
805   
    std::size_t
1022   
    std::size_t
806   
    size() const noexcept;
1023   
    size() const noexcept;
807  
1024  
808 - 
    /** The maximum number of elements an array can hold.
1025 + 
    /** Return the maximum number of elements any array can hold.
809  
1026  
810 - 
        The maximum is an implementation-defined number. This value is
1027 + 
        The maximum is an implementation-defined number.
811 - 
        a theoretical limit; at runtime, the actual maximum size may be less
1028 + 
        This value is a theoretical limit; at runtime,
812 - 
        due to resource limits.
1029 + 
        the actual maximum size may be less due to
 
1030 + 
        resource limits.
813  
1031  
814   
        @par Complexity
1032   
        @par Complexity
815   
        Constant.
1033   
        Constant.
816  
1034  
817   
        @par Exception Safety
1035   
        @par Exception Safety
818   
        No-throw guarantee.
1036   
        No-throw guarantee.
819   
    */
1037   
    */
820   
    static
1038   
    static
821   
    inline
1039   
    inline
822   
    constexpr
1040   
    constexpr
823   
    std::size_t
1041   
    std::size_t
824   
    max_size() noexcept;
1042   
    max_size() noexcept;
825  
1043  
826   
    /** Return the number of elements that can be held in currently allocated memory.
1044   
    /** Return the number of elements that can be held in currently allocated memory.
827  
1045  
828 - 
        Returns the number of elements that the container has currently
1046 + 
        This number may be larger than the value returned
829 - 
        allocated space for. This number is never smaller than the value
1047 + 
        by @ref size().
830 - 
        returned by @ref size().
 
831  
1048  
832   
        @par Complexity
1049   
        @par Complexity
833   
        Constant.
1050   
        Constant.
834  
1051  
835   
        @par Exception Safety
1052   
        @par Exception Safety
836   
        No-throw guarantee.
1053   
        No-throw guarantee.
837   
    */
1054   
    */
838   
    inline
1055   
    inline
839   
    std::size_t
1056   
    std::size_t
840   
    capacity() const noexcept;
1057   
    capacity() const noexcept;
841  
1058  
842   
    /** Check if the array has no elements.
1059   
    /** Check if the array has no elements.
843  
1060  
844   
        Returns `true` if there are no elements in the
1061   
        Returns `true` if there are no elements in the
845   
        array, i.e. @ref size() returns 0.
1062   
        array, i.e. @ref size() returns 0.
846  
1063  
847   
        @par Complexity
1064   
        @par Complexity
848   
        Constant.
1065   
        Constant.
849  
1066  
850   
        @par Exception Safety
1067   
        @par Exception Safety
851   
        No-throw guarantee.
1068   
        No-throw guarantee.
852   
    */
1069   
    */
853   
    inline
1070   
    inline
854   
    bool
1071   
    bool
855   
    empty() const noexcept;
1072   
    empty() const noexcept;
856  
1073  
857   
    /** Increase the capacity to at least a certain amount.
1074   
    /** Increase the capacity to at least a certain amount.
858  
1075  
859 - 
        This increases the @ref capacity() to a value that is greater than or
1076 + 
        This increases the @ref capacity() to a value
860 - 
        equal to `new_capacity`. If `new_capacity > capacity()`, new memory is
1077 + 
        that is greater than or equal to `new_capacity`.
861 - 
        allocated. Otherwise, the call has no effect. The number of elements
1078 + 
        If `new_capacity > capacity()`, new memory is
862 - 
        and therefore the @ref size() of the container is not changed.
1079 + 
        allocated. Otherwise, the call has no effect.
863 -
1080 + 
        The number of elements and therefore the
864 - 
        If new memory is allocated, all iterators including any past-the-end
1081 + 
        @ref size() of the container is not changed.
865 - 
        iterators, and all references to the elements are invalidated.
1082 + 
    \n
866 - 
        Otherwise, no iterators or references are invalidated.
1083 + 
        If new memory is allocated, all iterators
 
1084 + 
        including any past-the-end iterators, and all
 
1085 + 
        references to the elements are invalidated.
 
1086 + 
        Otherwise, no iterators or references are
 
1087 + 
        invalidated.
867  
1088  
868   
        @par Complexity
1089   
        @par Complexity
869   
        At most, linear in @ref size().
1090   
        At most, linear in @ref size().
870  
1091  
871   
        @par Exception Safety
1092   
        @par Exception Safety
872   
        Strong guarantee.
1093   
        Strong guarantee.
873   
        Calls to `memory_resource::allocate` may throw.
1094   
        Calls to `memory_resource::allocate` may throw.
874  
1095  
875   
        @param new_capacity The new capacity of the array.
1096   
        @param new_capacity The new capacity of the array.
876  
1097  
877 - 
        @throw boost::system::system_error `new_capacity >` @ref max_size().
1098 + 
        @throw `boost::system::system_error` `new_capacity > max_size()`.
878   
    */
1099   
    */
879   
    inline
1100   
    inline
880   
    void
1101   
    void
881   
    reserve(std::size_t new_capacity);
1102   
    reserve(std::size_t new_capacity);
882  
1103  
883   
    /** Request the removal of unused capacity.
1104   
    /** Request the removal of unused capacity.
884  
1105  
885   
        This performs a non-binding request to reduce the
1106   
        This performs a non-binding request to reduce the
886   
        capacity to the current size. The request may or
1107   
        capacity to the current size. The request may or
887   
        may not be fulfilled. If reallocation occurs, all
1108   
        may not be fulfilled. If reallocation occurs, all
888   
        iterators including any past-the-end iterators,
1109   
        iterators including any past-the-end iterators,
889   
        and all references to the elements are invalidated.
1110   
        and all references to the elements are invalidated.
890   
        Otherwise, no iterators or references are
1111   
        Otherwise, no iterators or references are
891   
        invalidated.
1112   
        invalidated.
892  
1113  
893   
        @par Complexity
1114   
        @par Complexity
894   
        At most, linear in @ref size().
1115   
        At most, linear in @ref size().
895  
1116  
896   
        @par Exception Safety
1117   
        @par Exception Safety
897   
        No-throw guarantee.
1118   
        No-throw guarantee.
898   
    */
1119   
    */
899   
    BOOST_JSON_DECL
1120   
    BOOST_JSON_DECL
900   
    void
1121   
    void
901   
    shrink_to_fit() noexcept;
1122   
    shrink_to_fit() noexcept;
902  
1123  
903   
    //------------------------------------------------------
1124   
    //------------------------------------------------------
904   
    //
1125   
    //
905   
    // Modifiers
1126   
    // Modifiers
906   
    //
1127   
    //
907   
    //------------------------------------------------------
1128   
    //------------------------------------------------------
908  
1129  
909   
    /** Clear the contents.
1130   
    /** Clear the contents.
910  
1131  
911 - 
        Erases all elements from the container. After this call, @ref size()
1132 + 
        Erases all elements from the container. After this
912 - 
        returns zero but @ref capacity() is unchanged. All references,
1133 + 
        call, @ref size() returns zero but @ref capacity()
913 - 
        pointers, and iterators are invalidated
1134 + 
        is unchanged. All references, pointers, or iterators
 
1135 + 
        referring to contained elements are invalidated. Any
 
1136 + 
        past-the-end iterators are also invalidated.
914  
1137  
915   
        @par Complexity
1138   
        @par Complexity
916   
        Linear in @ref size().
1139   
        Linear in @ref size().
917  
1140  
918   
        @par Exception Safety
1141   
        @par Exception Safety
919   
        No-throw guarantee.
1142   
        No-throw guarantee.
920   
    */
1143   
    */
921   
    BOOST_JSON_DECL
1144   
    BOOST_JSON_DECL
922   
    void
1145   
    void
923   
    clear() noexcept;
1146   
    clear() noexcept;
924  
1147  
925   
    /** Insert elements before the specified location.
1148   
    /** Insert elements before the specified location.
926  
1149  
927 - 
        @li **(1)** and **(2)** insert a single new element before
1150 + 
        This inserts a copy of `v` before `pos`.
928 - 
            `pos`. **(1)** copy-constructs and **(2)** move-constructs the new
1151 + 
        If `capacity() < size() + 1`, a reallocation
929 - 
            element from `jv`.
1152 + 
        occurs first, and all iterators and references
930 - 
        @li **(3)** inserts `count` copies of `jv` before `pos`.
1153 + 
        are invalidated.
931 - 
        @li **(4)** the elements in the range `[first, last)` are inserted in
1154 + 
        Otherwise, only the iterators and references from
932 - 
            order.
1155 + 
        the insertion point forward are invalidated. All
933 - 
        @li **(5)** the elements of the initializer list `init` are inserted in
 
934 - 
            order.
 
935 -
 
936 - 
        Inserted values will be constructed using the container's
 
937 - 
        associated @ref boost::container::pmr::memory_resource.
 
938 -
 
939 - 
        @note Overload **(2)** is equivalent to **(1)** if
 
940 - 
        `*jv.storage() != *this->storage()`.
 
941 -
 
942 - 
        If the size of the array after insertion would have exceeded
 
943 - 
        @ref capacity(), a reallocation occurs first, and all iterators and
 
944 - 
        references are invalidated. Otherwise, only the iterators and
 
945 - 
        references from the insertion point forward are invalidated. All
 
946   
        past-the-end iterators are also invalidated.
1156   
        past-the-end iterators are also invalidated.
947 - 
        @pre
 
948 - 
        `first` and `last` are not iterators into `*this`.
 
949 -
 
950 - 
        @par Constraints
 
951 - 
        @code
 
952 - 
        ! std::is_convertible_v<InputIt, value>
 
953 - 
        std::is_constructible_v<value, std::iterator_traits<InputIt>::reference>
 
954 - 
        @endcode
 
955 -
 
956  
1157  
957   
        @par Complexity
1158   
        @par Complexity
958 - 
        @li **(1)**, **(2)** linear in `std::distance(pos, end())`.
1159 + 
        Constant plus linear in `std::distance(pos, end())`.
959 - 
        @li **(3)** linear in `count + std::distance(pos, end())`.
 
960 - 
        @li **(4)** linear in `std::distance(first, last) +
 
961 - 
            std::distance(pos, end())`.
 
962 - 
        @li **(5)** linear in `init.size() + std::distance(pos, end())`.
 
963  
1160  
964   
        @par Exception Safety
1161   
        @par Exception Safety
965 - 
        {sp}**(4)** provides strong guarantee if `InputIt` satisfies
1162 + 
        Strong guarantee.
966 - 
        {req_ForwardIterator}, and basic guarantee otherwise. Other overloads
 
967 - 
        provide strong guarantee.
 
968   
        Calls to `memory_resource::allocate` may throw.
1163   
        Calls to `memory_resource::allocate` may throw.
969  
1164  
970 - 
        @param pos Iterator before which the new elements will
1165 + 
        @param pos Iterator before which the content will
971   
        be inserted. This may be the @ref end() iterator.
1166   
        be inserted. This may be the @ref end() iterator.
972  
1167  
973 - 
        @param jv The value to insert. A copy will be made
1168 + 
        @param v The value to insert. A copy will be made
974 - 
        using container's associated
1169 + 
        using container's associated `boost::container::pmr::memory_resource`.
975 - 
        @ref boost::container::pmr::memory_resource.
 
976 -
 
977 - 
        @return An iterator to the first inserted value, or `pos` if no values
 
978 - 
                were inserted.
 
979  
1170  
980 - 
        @{
1171 + 
        @return An iterator to the inserted value
981   
    */
1172   
    */
982   
    BOOST_JSON_DECL
1173   
    BOOST_JSON_DECL
983   
    iterator
1174   
    iterator
984   
    insert(
1175   
    insert(
985   
        const_iterator pos,
1176   
        const_iterator pos,
986 - 
        value const& jv);
1177 + 
        value const& v);
987  
1178  
988 - 
    // Overload
1179 + 
    /** Insert elements before the specified location.
 
1180 +
 
1181 + 
        This inserts `v` before `pos` via move-construction.
 
1182 + 
        If `capacity() < size() + 1`, a reallocation occurs
 
1183 + 
        first, and all iterators and references are
 
1184 + 
        invalidated.
 
1185 + 
        Otherwise, only the iterators and references from
 
1186 + 
        the insertion point forward are invalidated. All
 
1187 + 
        past-the-end iterators are also invalidated.
 
1188 +
 
1189 + 
        @par Complexity
 
1190 + 
        Constant plus linear in `std::distance(pos, end())`.
 
1191 +
 
1192 + 
        @par Exception Safety
 
1193 + 
        Strong guarantee.
 
1194 + 
        Calls to `memory_resource::allocate` may throw.
 
1195 +
 
1196 + 
        @param pos Iterator before which the content will
 
1197 + 
        be inserted. This may be the @ref end() iterator.
 
1198 +
 
1199 + 
        @param v The value to insert. Ownership of the
 
1200 + 
        value will be transferred via move construction,
 
1201 + 
        using the container's
 
1202 + 
        associated `boost::container::pmr::memory_resource`.
 
1203 +
 
1204 + 
        @return An iterator to the inserted value
 
1205 + 
    */
989   
    BOOST_JSON_DECL
1206   
    BOOST_JSON_DECL
990   
    iterator
1207   
    iterator
991   
    insert(
1208   
    insert(
992   
        const_iterator pos,
1209   
        const_iterator pos,
993 - 
        value&& jv);
1210 + 
        value&& v);
994  
1211  
 
1212 + 
    /** Insert elements before the specified location.
 
1213 +
 
1214 + 
        This inserts `count` copies of `v` before `pos`.
 
1215 + 
        If `capacity() < size() + count`, a reallocation
 
1216 + 
        occurs first, and all iterators and references are
 
1217 + 
        invalidated.
 
1218 + 
        Otherwise, only the iterators and references from
 
1219 + 
        the insertion point forward are invalidated. All
 
1220 + 
        past-the-end iterators are also invalidated.
 
1221 +
 
1222 + 
        @par Complexity
 
1223 + 
        Linear in `count + std::distance(pos, end())`.
 
1224 +
 
1225 + 
        @par Exception Safety
 
1226 + 
        Strong guarantee.
 
1227 + 
        Calls to `memory_resource::allocate` may throw.
 
1228 +
 
1229 + 
        @param pos Iterator before which the content will
 
1230 + 
        be inserted. This may be the @ref end() iterator.
995 - 
    /** Overload
 
996  
1231  
997   
        @param count The number of copies to insert.
1232   
        @param count The number of copies to insert.
998 - 
        @param pos
1233 +
999 - 
        @param jv
1234 + 
        @param v The value to insert. Copies will be made
 
1235 + 
        using the container's
 
1236 + 
        associated `boost::container::pmr::memory_resource`.
 
1237 +
 
1238 + 
        @return An iterator to the first inserted value,
 
1239 + 
        or `pos` if `count == 0`.
1000   
    */
1240   
    */
1001   
    BOOST_JSON_DECL
1241   
    BOOST_JSON_DECL
1002   
    iterator
1242   
    iterator
1003   
    insert(
1243   
    insert(
1004   
        const_iterator pos,
1244   
        const_iterator pos,
1005   
        std::size_t count,
1245   
        std::size_t count,
1006 - 
        value const& jv);
1246 + 
        value const& v);
1007  
1247  
1008 - 
    /** Overload
1248 + 
    /** Insert elements before the specified location.
1009  
1249  
1010 - 
        @param first An input iterator pointing to the first element to insert,
1250 + 
        The elements in the range `{first, last)` are
1011 - 
               or pointing to the end of the range.
1251 + 
        inserted in order.
1012 - 
        @param last An input iterator pointing to the end of the range.
1252 + 
        If `capacity() < size() + std::distance(first, last)`,
1013 - 
        @param pos
1253 + 
        a reallocation occurs first, and all iterators and
 
1254 + 
        references are invalidated.
 
1255 + 
        Otherwise, only the iterators and references from
 
1256 + 
        the insertion point forward are invalidated. All
 
1257 + 
        past-the-end iterators are also invalidated.
 
1258 +
 
1259 + 
        @par Precondition
 
1260 + 
        `first` and `last` are not iterators into `*this`.
 
1261 +
 
1262 + 
        @par Constraints
 
1263 + 
        @code
 
1264 + 
        not std::is_convertible_v<InputIt, value>
 
1265 + 
        @endcode
 
1266 +
 
1267 + 
        @par Mandates
 
1268 + 
        @code
 
1269 + 
        std::is_constructible_v<value, std::iterator_traits<InputIt>::reference>
 
1270 + 
        @endcode
 
1271 +
 
1272 + 
        @par Complexity
 
1273 + 
        Linear in `std::distance(first, last) + std::distance(pos, end())`.
 
1274 +
 
1275 + 
        @par Exception Safety
 
1276 + 
        Strong guarantee.
 
1277 + 
        Calls to `memory_resource::allocate` may throw.
 
1278 +
 
1279 + 
        @return An iterator to the first inserted value, or
 
1280 + 
        `pos` if `first == last`.
 
1281 +
 
1282 + 
        @param pos Iterator before which the content will
 
1283 + 
        be inserted. This may be the @ref end() iterator.
 
1284 +
 
1285 + 
        @param first An input iterator pointing to the first
 
1286 + 
        element to insert, or pointing to the end of the range.
 
1287 +
 
1288 + 
        @param last An input iterator pointing to the end
 
1289 + 
        of the range.
1014  
1290  
1015   
        @tparam InputIt a type satisfying the requirements
1291   
        @tparam InputIt a type satisfying the requirements
1016 - 
        of {req_InputIterator}.
1292 + 
        of __InputIterator__.
1017   
    */
1293   
    */
1018   
    template<
1294   
    template<
1019   
        class InputIt
1295   
        class InputIt
1020   
    #ifndef BOOST_JSON_DOCS
1296   
    #ifndef BOOST_JSON_DOCS
1021   
        ,class = typename std::enable_if<
1297   
        ,class = typename std::enable_if<
1022   
            std::is_constructible<value,
1298   
            std::is_constructible<value,
1023   
                typename std::iterator_traits<
1299   
                typename std::iterator_traits<
1024   
                    InputIt>::reference>::value>::type
1300   
                    InputIt>::reference>::value>::type
1025   
    #endif
1301   
    #endif
1026   
    >
1302   
    >
1027   
    iterator
1303   
    iterator
1028   
    insert(
1304   
    insert(
1029   
        const_iterator pos,
1305   
        const_iterator pos,
1030   
        InputIt first, InputIt last);
1306   
        InputIt first, InputIt last);
1031  
1307  
1032 - 
    /** Overload
1308 + 
    /** Insert elements before the specified location.
 
1309 +
 
1310 + 
        The elements in the initializer list `init` are
 
1311 + 
        inserted in order.
 
1312 + 
        If `capacity() < size() + init.size()`,
 
1313 + 
        a reallocation occurs first, and all iterators and
 
1314 + 
        references are invalidated.
 
1315 + 
        Otherwise, only the iterators and references from
 
1316 + 
        the insertion point forward are invalidated. All
 
1317 + 
        past-the-end iterators are also invalidated.
 
1318 +
 
1319 + 
        @par Complexity
 
1320 + 
        Linear in `init.size() + std::distance(pos, end())`.
 
1321 +
 
1322 + 
        @par Exception Safety
 
1323 + 
        Strong guarantee.
 
1324 + 
        Calls to `memory_resource::allocate` may throw.
 
1325 +
 
1326 + 
        @param pos Iterator before which the content will
 
1327 + 
        be inserted. This may be the @ref end() iterator.
 
1328 +
1033   
        @param init The initializer list to insert
1329   
        @param init The initializer list to insert
1034 - 
        @param pos
1330 +
 
1331 + 
        @return An iterator to the first inserted value, or
 
1332 + 
        `pos` if `init.size() == 0`.
1035   
    */
1333   
    */
1036   
    BOOST_JSON_DECL
1334   
    BOOST_JSON_DECL
1037   
    iterator
1335   
    iterator
1038   
    insert(
1336   
    insert(
1039   
        const_iterator pos,
1337   
        const_iterator pos,
1040 - 
    /// @}
 
1041   
        std::initializer_list<value_ref> init);
1338   
        std::initializer_list<value_ref> init);
1042  
1339  
1043   
    /** Insert a constructed element in-place.
1340   
    /** Insert a constructed element in-place.
1044  
1341  
1045   
        Inserts a new element into the container directly before
1342   
        Inserts a new element into the container directly before
1046   
        `pos`. The element is constructed using placement-new
1343   
        `pos`. The element is constructed using placement-new
1047   
        with the parameter `std::forward<Arg>(arg)`.
1344   
        with the parameter `std::forward<Arg>(arg)`.
1048   
        If `capacity() < size() + 1`,
1345   
        If `capacity() < size() + 1`,
1049   
        a reallocation occurs first, and all iterators and
1346   
        a reallocation occurs first, and all iterators and
1050   
        references are invalidated.
1347   
        references are invalidated.
1051   
        Otherwise, only the iterators and references from
1348   
        Otherwise, only the iterators and references from
1052   
        the insertion point forward are invalidated. All
1349   
        the insertion point forward are invalidated. All
1053   
        past-the-end iterators are also invalidated.
1350   
        past-the-end iterators are also invalidated.
1054  
1351  
1055   
        @par Complexity
1352   
        @par Complexity
1056 - 
        Linear in `std::distance(pos, end())`.
1353 + 
        Constant plus linear in `std::distance(pos, end())`.
1057  
1354  
1058   
        @par Exception Safety
1355   
        @par Exception Safety
1059   
        Strong guarantee.
1356   
        Strong guarantee.
1060   
        Calls to `memory_resource::allocate` may throw.
1357   
        Calls to `memory_resource::allocate` may throw.
1061  
1358  
1062   
        @param pos Iterator before which the element will
1359   
        @param pos Iterator before which the element will
1063   
        be inserted. This may be the @ref end() iterator.
1360   
        be inserted. This may be the @ref end() iterator.
1064  
1361  
1065   
        @param arg The argument to forward to the @ref value
1362   
        @param arg The argument to forward to the @ref value
1066   
        constructor.
1363   
        constructor.
1067  
1364  
1068   
        @return An iterator to the inserted element
1365   
        @return An iterator to the inserted element
1069   
    */
1366   
    */
1070   
    template<class Arg>
1367   
    template<class Arg>
1071   
    iterator
1368   
    iterator
1072   
    emplace(
1369   
    emplace(
1073   
        const_iterator pos,
1370   
        const_iterator pos,
1074   
        Arg&& arg);
1371   
        Arg&& arg);
1075  
1372  
1076 - 
    /** Remove elements from the array.
1373 + 
    /** Erase elements from the container.
1077  
1374  
1078 - 
        @li **(1)** the element at `pos` is removed.
1375 + 
        The element at `pos` is removed.
1079 - 
        @li **(2)** the elements in the range `[first, last)` are removed.
 
1080  
1376  
1081   
        @par Complexity
1377   
        @par Complexity
1082 - 
        @li **(1)** linear in `std::distance(pos, end())`.
1378 + 
        Constant plus linear in `std::distance(pos, end())`
1083 - 
        @li **(2)** linear in `std::distance(first, end())`.
 
1084  
1379  
1085   
        @par Exception Safety
1380   
        @par Exception Safety
1086   
        No-throw guarantee.
1381   
        No-throw guarantee.
1087  
1382  
1088   
        @param pos Iterator to the element to remove
1383   
        @param pos Iterator to the element to remove
1089  
1384  
1090 - 
        @return Iterator following the last removed element. If that was the
1385 + 
        @return Iterator following the last removed element.
1091 - 
                last element of the array, the @ref end() iterator is returned.
1386 + 
        If the iterator `pos` refers to the last element,
1092 -
1387 + 
        the @ref end() iterator is returned.
1093 - 
        @{
 
1094   
    */
1388   
    */
1095   
    BOOST_JSON_DECL
1389   
    BOOST_JSON_DECL
1096   
    iterator
1390   
    iterator
1097   
    erase(const_iterator pos) noexcept;
1391   
    erase(const_iterator pos) noexcept;
1098  
1392  
1099 - 
    /** Overload
1393 + 
    /** Erase elements from the container.
1100 - 
        @param first An iterator pointing to the first element to erase, or
1394 +
1101 - 
               pointing to the end of the range.
1395 + 
        The elements in the range `{first, last)` are removed.
1102 - 
        @param last An iterator pointing to one past the last element to erase,
1396 +
1103 - 
                    or pointing to the end of the range.
1397 + 
        @par Complexity
 
1398 + 
        Linear in `std::distance(first, end())`
 
1399 +
 
1400 + 
        @par Exception Safety
 
1401 + 
        No-throw guarantee.
 
1402 +
 
1403 + 
        @param first An iterator pointing to the first
 
1404 + 
        element to erase, or pointing to the end of the range.
 
1405 +
 
1406 + 
        @param last An iterator pointing to one past the
 
1407 + 
        last element to erase, or pointing to the end of the
 
1408 + 
        range.
 
1409 +
 
1410 + 
        @return Iterator following the last removed element.
 
1411 + 
        If the iterator `last` refers to the last element,
 
1412 + 
        the @ref end() iterator is returned.
1104   
    */
1413   
    */
1105   
    BOOST_JSON_DECL
1414   
    BOOST_JSON_DECL
1106   
    iterator
1415   
    iterator
1107   
    erase(
1416   
    erase(
1108   
        const_iterator first,
1417   
        const_iterator first,
1109 - 
    /// @}
 
1110   
        const_iterator last) noexcept;
1418   
        const_iterator last) noexcept;
1111  
1419  
1112   
    /** Add an element to the end.
1420   
    /** Add an element to the end.
1113  
1421  
1114 - 
        Insert a new element at the end of the container. **(1)**
1422 + 
        This appends a copy of `v` to the container's
1115 - 
        copy-constructs the new element from `jv`, **(2)** move-constructs from
1423 + 
        elements.
1116 - 
        `jv`.
1424 + 
        If `capacity() < size() + 1`, a reallocation
1117 -
1425 + 
        occurs first, and all iterators and references
1118 - 
        If `capacity() < size() + 1`, a reallocation occurs first, and all
1426 + 
        are invalidated. Any past-the-end iterators are
1119 - 
        iterators and references are invalidated. Any past-the-end iterators
1427 + 
        always invalidated.
1120 - 
        are always invalidated.
 
1121 -
 
1122 - 
        The new element will be constructed using the container's associated
 
1123 - 
        @ref boost::container::pmr::memory_resource.
 
1124  
1428  
1125   
        @par Complexity
1429   
        @par Complexity
1126   
        Amortized constant.
1430   
        Amortized constant.
1127  
1431  
1128   
        @par Exception Safety
1432   
        @par Exception Safety
1129   
        Strong guarantee.
1433   
        Strong guarantee.
1130   
        Calls to `memory_resource::allocate` may throw.
1434   
        Calls to `memory_resource::allocate` may throw.
1131  
1435  
1132 - 
        @param jv The value to insert.
1436 + 
        @param v The value to insert. A copy will be made using the container's
1133 -
1437 + 
        associated `boost::container::pmr::memory_resource`.
1134 - 
        @{
 
1135   
    */
1438   
    */
1136   
    BOOST_JSON_DECL
1439   
    BOOST_JSON_DECL
1137   
    void
1440   
    void
1138 - 
    push_back(value const& jv);
1441 + 
    push_back(value const& v);
 
1442 +
 
1443 + 
    /** Add an element to the end.
1139  
1444  
 
1445 + 
        This appends `v` to the container's elements via
 
1446 + 
        move-construction.
 
1447 + 
        If `capacity() < size() + 1`, a reallocation
 
1448 + 
        occurs first, and all iterators and references
 
1449 + 
        are invalidated. Any past-the-end iterators are
 
1450 + 
        always invalidated.
 
1451 +
 
1452 + 
        @par Complexity
 
1453 + 
        Amortized constant.
 
1454 +
 
1455 + 
        @par Exception Safety
 
1456 + 
        Strong guarantee.
 
1457 + 
        Calls to `memory_resource::allocate` may throw.
 
1458 +
 
1459 + 
        @param v The value to insert. Ownership of the value will be
 
1460 + 
        transferred via move construction, using the container's
 
1461 + 
        associated `boost::container::pmr::memory_resource`.
 
1462 + 
    */
1140   
    BOOST_JSON_DECL
1463   
    BOOST_JSON_DECL
1141   
    void
1464   
    void
1142 - 
    push_back(value&& jv);
1465 + 
    push_back(value&& v);
1143 - 
    /// @}
 
1144  
1466  
1145   
    /** Append a constructed element in-place.
1467   
    /** Append a constructed element in-place.
1146  
1468  
1147   
        Appends a new element to the end of the container's
1469   
        Appends a new element to the end of the container's
1148   
        list of elements.
1470   
        list of elements.
1149   
        The element is constructed using placement-new
1471   
        The element is constructed using placement-new
1150   
        with the parameter `std::forward<Arg>(arg)`.
1472   
        with the parameter `std::forward<Arg>(arg)`.
1151   
        If `capacity() < size() + 1`,
1473   
        If `capacity() < size() + 1`,
1152   
        a reallocation occurs first, and all iterators and
1474   
        a reallocation occurs first, and all iterators and
1153   
        references are invalidated.
1475   
        references are invalidated.
1154   
        Otherwise, only the iterators and references from
1476   
        Otherwise, only the iterators and references from
1155   
        the insertion point forward are invalidated. All
1477   
        the insertion point forward are invalidated. All
1156   
        past-the-end iterators are also invalidated.
1478   
        past-the-end iterators are also invalidated.
1157  
1479  
1158   
        @par Complexity
1480   
        @par Complexity
1159   
        Amortized constant.
1481   
        Amortized constant.
1160  
1482  
1161   
        @par Exception Safety
1483   
        @par Exception Safety
1162   
        Strong guarantee.
1484   
        Strong guarantee.
1163   
        Calls to `memory_resource::allocate` may throw.
1485   
        Calls to `memory_resource::allocate` may throw.
1164  
1486  
1165   
        @param arg The argument to forward to the @ref value
1487   
        @param arg The argument to forward to the @ref value
1166   
        constructor.
1488   
        constructor.
1167  
1489  
1168   
        @return A reference to the inserted element
1490   
        @return A reference to the inserted element
1169   
    */
1491   
    */
1170   
    template<class Arg>
1492   
    template<class Arg>
1171   
    value&
1493   
    value&
1172   
    emplace_back(Arg&& arg);
1494   
    emplace_back(Arg&& arg);
1173  
1495  
1174   
    /** Remove the last element
1496   
    /** Remove the last element
1175  
1497  
1176   
        The last element of the container is erased.
1498   
        The last element of the container is erased.
1177  
1499  
1178 - 
        @pre
1500 + 
        @par Precondition
1179 - 
        `! empty()`
1501 + 
        `not empty()`
1180  
1502  
1181   
        @par Exception Safety
1503   
        @par Exception Safety
1182   
        No-throw guarantee.
1504   
        No-throw guarantee.
1183   
    */
1505   
    */
1184   
    BOOST_JSON_DECL
1506   
    BOOST_JSON_DECL
1185   
    void
1507   
    void
1186   
    pop_back() noexcept;
1508   
    pop_back() noexcept;
1187  
1509  
1188   
    /** Change the number of elements stored.
1510   
    /** Change the number of elements stored.
1189  
1511  
1190   
        Resizes the container to contain `count` elements.
1512   
        Resizes the container to contain `count` elements.
 
1513 + 
        If `capacity() < size() + count`, a reallocation
 
1514 + 
        occurs first, and all iterators and references
 
1515 + 
        are invalidated. Any past-the-end iterators are
 
1516 + 
        always invalidated.
1191  
1517  
1192 - 
        @li If `size() > count`, the container is reduced to its first `count`
1518 + 
        @li If `size() > count`, the container is reduced
1193 - 
            elements.
1519 + 
        to its first `count` elements.
1194 - 
        @li If `size() < count`, additional null values (**(1)**) or copies
 
1195 - 
            of `jv` (**(2)**) are appended.
 
1196  
1520  
1197 - 
        If `capacity() < count`, a reallocation occurs first, and all iterators
1521 + 
        @li If `size() < count`, additional null values
1198 - 
        and references are invalidated. Any past-the-end iterators are always
1522 + 
        are appended.
1199 - 
        invalidated.
 
1200  
1523  
1201   
        @par Complexity
1524   
        @par Complexity
1202 - 
        Linear in `size() + count`.
1525 + 
        Linear in `abs(size() - count)`, plus the cost of
 
1526 + 
        reallocation if @ref capacity() is less than `count`.
1203  
1527  
1204   
        @par Exception Safety
1528   
        @par Exception Safety
1205   
        Strong guarantee.
1529   
        Strong guarantee.
1206   
        Calls to `memory_resource::allocate` may throw.
1530   
        Calls to `memory_resource::allocate` may throw.
1207  
1531  
1208 -
 
1209 - 
        @{
 
1210   
        @param count The new size of the container.
1532   
        @param count The new size of the container.
1211   
    */
1533   
    */
1212   
    BOOST_JSON_DECL
1534   
    BOOST_JSON_DECL
1213   
    void
1535   
    void
1214   
    resize(std::size_t count);
1536   
    resize(std::size_t count);
1215  
1537  
1216 - 
    /** Overload
1538 + 
    /** Change the number of elements stored.
1217 - 
        @param jv The @ref value to copy into the new elements.
1539 +
1218 - 
        @param count
1540 + 
        Resizes the container to contain `count` elements.
 
1541 + 
        If `capacity() < size() + count`, a reallocation
 
1542 + 
        occurs first, and all iterators and references
 
1543 + 
        are invalidated. Any past-the-end iterators are
 
1544 + 
        always invalidated.
 
1545 +
 
1546 + 
        @li If `size() > count`, the container is reduced
 
1547 + 
        to its first `count` elements.
 
1548 +
 
1549 + 
        @li If `size() < count`, additional copies of `v`
 
1550 + 
        are appended.
 
1551 +
 
1552 + 
        @par Complexity
 
1553 + 
        Linear in `abs(size() - count)`, plus the cost of
 
1554 + 
        reallocation if @ref capacity() is less than `count`.
 
1555 +
 
1556 + 
        @par Exception Safety
 
1557 + 
        Strong guarantee.
 
1558 + 
        Calls to `memory_resource::allocate` may throw.
 
1559 +
 
1560 + 
        @param count The new size of the container.
 
1561 +
 
1562 + 
        @param v The @ref value to copy into the new elements.
1219   
    */
1563   
    */
1220   
    BOOST_JSON_DECL
1564   
    BOOST_JSON_DECL
1221   
    void
1565   
    void
1222   
    resize(
1566   
    resize(
1223   
        std::size_t count,
1567   
        std::size_t count,
1224 - 
        value const& jv);
1568 + 
        value const& v);
1225 - 
    /// @}
 
1226  
1569  
1227 - 
    /** Swap two arrays.
1570 + 
    /** Swap the contents.
1228  
1571  
1229 - 
        Exchanges the contents of this array with another array. Ownership of
1572 + 
        Exchanges the contents of this array with another
1230 - 
        the respective @ref boost::container::pmr::memory_resource objects is
1573 + 
        array. Ownership of the respective
1231 - 
        not transferred. If `this == &other`, this function call has no effect.
1574 + 
        `boost::container::pmr::memory_resource` objects is not transferred.
1232  
1575  
1233 - 
        @li If `*storage() == *other.storage()` all iterators and references
1576 + 
        @li If `*other.storage() == *this->storage()`,
1234 - 
        remain valid.
1577 + 
        ownership of the underlying memory is swapped in
 
1578 + 
        constant time, with no possibility of exceptions.
 
1579 + 
        All iterators and references remain valid.
1235  
1580  
1236 - 
        @li Otherwise, the contents are logically swapped by making copies,
1581 + 
        @li If `*other.storage() != *this->storage()`,
1237 - 
        which can throw. In this case all iterators and references are
1582 + 
        the contents are logically swapped by making copies,
1238 - 
        invalidated.
1583 + 
        which can throw. In this case all iterators and
 
1584 + 
        references are invalidated.
1239  
1585  
1240   
        @par Complexity
1586   
        @par Complexity
1241 - 
        If `*storage() == *other.storage()`, then constant; otherwise linear in
1587 + 
        Constant or linear in @ref size() plus `other.size()`.
1242 - 
        `size() + other.size()`.
 
1243  
1588  
1244   
        @par Exception Safety
1589   
        @par Exception Safety
1245 - 
        No-throw guarantee if `*storage() == *other.storage()`. Otherwise
1590 + 
        Strong guarantee.
1246 - 
        strong guarantee. Calls to `memory_resource::allocate` may throw.
1591 + 
        Calls to `memory_resource::allocate` may throw.
1247  
1592  
1248   
        @param other The value to swap with.
1593   
        @param other The value to swap with.
 
1594 + 
        If `this == &other`, this function call has no effect.
1249   
    */
1595   
    */
1250   
    BOOST_JSON_DECL
1596   
    BOOST_JSON_DECL
1251   
    void
1597   
    void
1252   
    swap(array& other);
1598   
    swap(array& other);
1253  
1599  
1254 - 
    /** Swap two arrays.
1600 + 
    /** Exchange the given values.
1255  
1601  
1256   
        Exchanges the contents of the array `lhs` with another array `rhs`.
1602   
        Exchanges the contents of the array `lhs` with another array `rhs`.
1257 - 
        Ownership of the respective @ref boost::container::pmr::memory_resource
1603 + 
        Ownership of the respective `boost::container::pmr::memory_resource`
1258 - 
        objects is not transferred. If `&lhs == &rhs`, this function call has
1604 + 
        objects is not transferred.
1259 - 
        no effect.
 
1260  
1605  
1261 - 
        @li If `*lhs.storage() == *rhs.storage()` all iterators and references
1606 + 
        @li If `*lhs.storage() == *rhs.storage()`,
1262 - 
        remain valid.
1607 + 
        ownership of the underlying memory is swapped in
 
1608 + 
        constant time, with no possibility of exceptions.
 
1609 + 
        All iterators and references remain valid.
1263  
1610  
1264 - 
        @li Otherwise, the contents are logically swapped by making copies,
1611 + 
        @li If `*lhs.storage() != *rhs.storage()`,
1265 - 
        which can throw. In this case all iterators and references are
1612 + 
        the contents are logically swapped by making a copy,
1266 - 
        invalidated.
1613 + 
        which can throw. In this case all iterators and
 
1614 + 
        references are invalidated.
 
1615 +
 
1616 + 
        @par Effects
 
1617 + 
        @code
 
1618 + 
        lhs.swap( rhs );
 
1619 + 
        @endcode
1267  
1620  
1268   
        @par Complexity
1621   
        @par Complexity
1269 - 
        If `*lhs.storage() == *rhs.storage()`, then constant; otherwise linear
1622 + 
        Constant or linear in `lhs.size() + rhs.size()`.
1270 - 
        in `lhs.size() + rhs.size()`.
 
1271  
1623  
1272   
        @par Exception Safety
1624   
        @par Exception Safety
1273 - 
        No-throw guarantee if `*lhs.storage() == *rhs.storage()`. Otherwise
1625 + 
        Strong guarantee.
1274 - 
        strong guarantee. Calls to `memory_resource::allocate` may throw.
1626 + 
        Calls to `memory_resource::allocate` may throw.
1275  
1627  
1276   
        @param lhs The array to exchange.
1628   
        @param lhs The array to exchange.
1277  
1629  
1278   
        @param rhs The array to exchange.
1630   
        @param rhs The array to exchange.
1279   
        If `&lhs == &rhs`, this function call has no effect.
1631   
        If `&lhs == &rhs`, this function call has no effect.
1280  
1632  
1281   
        @see @ref array::swap
1633   
        @see @ref array::swap
1282   
    */
1634   
    */
1283   
    friend
1635   
    friend
1284   
    void
1636   
    void
1285   
    swap(array& lhs, array& rhs)
1637   
    swap(array& lhs, array& rhs)
1286   
    {
1638   
    {
1287   
        lhs.swap(rhs);
1639   
        lhs.swap(rhs);
1288   
    }
1640   
    }
1289  
1641  
1290 - 
    /** Compare two arrays for equality.
1642 + 
    /** Return `true` if two arrays are equal.
1291  
1643  
1292 - 
        Arrays are equal when their sizes are the same, and they are
1644 + 
        Arrays are equal when their sizes are
1293 - 
        element-for-element equal in order.
1645 + 
        the same, and they are element-for-element
 
1646 + 
        equal in order.
 
1647 +
 
1648 + 
        @par Effects
 
1649 + 
        `return std::equal( lhs.begin(), lhs.end(), rhs.begin(), rhs.end() );`
1294  
1650  
1295   
        @par Complexity
1651   
        @par Complexity
1296 - 
        Linear in `lhs.size()`.
1652 + 
        Constant or linear in `lhs.size()`.
1297  
1653  
1298   
        @par Exception Safety
1654   
        @par Exception Safety
1299   
        No-throw guarantee.
1655   
        No-throw guarantee.
1300   
    */
1656   
    */
1301   
    // inline friend speeds up overload resolution
1657   
    // inline friend speeds up overload resolution
1302   
    friend
1658   
    friend
1303   
    bool
1659   
    bool
1304   
    operator==(
1660   
    operator==(
1305   
        array const& lhs,
1661   
        array const& lhs,
1306   
        array const& rhs) noexcept
1662   
        array const& rhs) noexcept
1307   
    {
1663   
    {
1308   
        return lhs.equal(rhs);
1664   
        return lhs.equal(rhs);
1309   
    }
1665   
    }
1310  
1666  
1311 - 
    /** Compare two arrays for inequality.
1667 + 
    /** Return `true` if two arrays are not equal.
1312  
1668  
1313 - 
        Arrays are equal when their sizes are the same, and they are
1669 + 
        Arrays are equal when their sizes are
1314 - 
        element-for-element equal in order.
1670 + 
        the same, and they are element-for-element
 
1671 + 
        equal in order.
 
1672 +
 
1673 + 
        @par Effects
 
1674 + 
        `return ! std::equal( lhs.begin(), lhs.end(), rhs.begin(), rhs.end() );`
1315  
1675  
1316   
        @par Complexity
1676   
        @par Complexity
1317 - 
        Linear in `lhs.size()`.
1677 + 
        Constant or linear in `lhs.size()`.
1318  
1678  
1319   
        @par Exception Safety
1679   
        @par Exception Safety
1320   
        No-throw guarantee.
1680   
        No-throw guarantee.
1321   
    */
1681   
    */
1322   
    // inline friend speeds up overload resolution
1682   
    // inline friend speeds up overload resolution
1323   
    friend
1683   
    friend
1324   
    bool
1684   
    bool
1325   
    operator!=(
1685   
    operator!=(
1326   
        array const& lhs,
1686   
        array const& lhs,
1327   
        array const& rhs) noexcept
1687   
        array const& rhs) noexcept
1328   
    {
1688   
    {
1329   
        return ! (lhs == rhs);
1689   
        return ! (lhs == rhs);
1330   
    }
1690   
    }
1331  
1691  
1332 - 
    /** Serialize to an output stream.
1692 + 
    /** Serialize @ref array to an output stream.
1333  
1693  
1334   
        This function serializes an `array` as JSON into the output stream.
1694   
        This function serializes an `array` as JSON into the output stream.
1335  
1695  
1336   
        @return Reference to `os`.
1696   
        @return Reference to `os`.
1337  
1697  
1338   
        @par Complexity
1698   
        @par Complexity
1339   
        Constant or linear in the size of `arr`.
1699   
        Constant or linear in the size of `arr`.
1340  
1700  
1341   
        @par Exception Safety
1701   
        @par Exception Safety
1342   
        Strong guarantee.
1702   
        Strong guarantee.
1343   
        Calls to `memory_resource::allocate` may throw.
1703   
        Calls to `memory_resource::allocate` may throw.
1344  
1704  
1345   
        @param os The output stream to serialize to.
1705   
        @param os The output stream to serialize to.
1346  
1706  
1347   
        @param arr The value to serialize.
1707   
        @param arr The value to serialize.
1348   
    */
1708   
    */
1349   
    BOOST_JSON_DECL
1709   
    BOOST_JSON_DECL
1350   
    friend
1710   
    friend
1351   
    std::ostream&
1711   
    std::ostream&
1352   
    operator<<(
1712   
    operator<<(
1353   
        std::ostream& os,
1713   
        std::ostream& os,
1354   
        array const& arr);
1714   
        array const& arr);
1355  
1715  
1356   
private:
1716   
private:
1357   
    template<class It>
1717   
    template<class It>
1358   
    using iter_cat = typename
1718   
    using iter_cat = typename
1359   
        std::iterator_traits<It>::iterator_category;
1719   
        std::iterator_traits<It>::iterator_category;
1360  
1720  
1361   
    template<class InputIt>
1721   
    template<class InputIt>
1362   
    array(
1722   
    array(
1363   
        InputIt first, InputIt last,
1723   
        InputIt first, InputIt last,
1364   
        storage_ptr sp,
1724   
        storage_ptr sp,
1365   
        std::input_iterator_tag);
1725   
        std::input_iterator_tag);
1366  
1726  
1367   
    template<class InputIt>
1727   
    template<class InputIt>
1368   
    array(
1728   
    array(
1369   
        InputIt first, InputIt last,
1729   
        InputIt first, InputIt last,
1370   
        storage_ptr sp,
1730   
        storage_ptr sp,
1371   
        std::forward_iterator_tag);
1731   
        std::forward_iterator_tag);
1372  
1732  
1373   
    inline
1733   
    inline
1374   
    std::size_t
1734   
    std::size_t
1375   
    growth(std::size_t new_size) const;
1735   
    growth(std::size_t new_size) const;
1376  
1736  
1377   
    BOOST_JSON_DECL
1737   
    BOOST_JSON_DECL
1378   
    void
1738   
    void
1379   
    reserve_impl(
1739   
    reserve_impl(
1380   
        std::size_t new_capacity);
1740   
        std::size_t new_capacity);
1381  
1741  
1382   
    BOOST_JSON_DECL
1742   
    BOOST_JSON_DECL
1383   
    value&
1743   
    value&
1384   
    push_back(
1744   
    push_back(
1385   
        pilfered<value> pv);
1745   
        pilfered<value> pv);
1386  
1746  
1387   
    BOOST_JSON_DECL
1747   
    BOOST_JSON_DECL
1388   
    iterator
1748   
    iterator
1389   
    insert(
1749   
    insert(
1390   
        const_iterator pos,
1750   
        const_iterator pos,
1391   
        pilfered<value> pv);
1751   
        pilfered<value> pv);
1392  
1752  
1393   
    template<class InputIt>
1753   
    template<class InputIt>
1394   
    iterator
1754   
    iterator
1395   
    insert(
1755   
    insert(
1396   
        const_iterator pos,
1756   
        const_iterator pos,
1397   
        InputIt first, InputIt last,
1757   
        InputIt first, InputIt last,
1398   
        std::input_iterator_tag);
1758   
        std::input_iterator_tag);
1399  
1759  
1400   
    template<class InputIt>
1760   
    template<class InputIt>
1401   
    iterator
1761   
    iterator
1402   
    insert(
1762   
    insert(
1403   
        const_iterator pos,
1763   
        const_iterator pos,
1404   
        InputIt first, InputIt last,
1764   
        InputIt first, InputIt last,
1405   
        std::forward_iterator_tag);
1765   
        std::forward_iterator_tag);
1406  
1766  
1407   
    BOOST_JSON_DECL
1767   
    BOOST_JSON_DECL
1408   
    bool
1768   
    bool
1409   
    equal(array const& other) const noexcept;
1769   
    equal(array const& other) const noexcept;
1410   
};
1770   
};
1411  
1771  
1412   
} // namespace json
1772   
} // namespace json
1413   
} // namespace boost
1773   
} // namespace boost
1414  
1774  
1415   
// std::hash specialization
1775   
// std::hash specialization
1416   
#ifndef BOOST_JSON_DOCS
1776   
#ifndef BOOST_JSON_DOCS
1417   
namespace std {
1777   
namespace std {
1418   
template <>
1778   
template <>
1419   
struct hash< ::boost::json::array > {
1779   
struct hash< ::boost::json::array > {
1420   
    BOOST_JSON_DECL
1780   
    BOOST_JSON_DECL
1421   
    std::size_t
1781   
    std::size_t
1422   
    operator()(::boost::json::array const& ja) const noexcept;
1782   
    operator()(::boost::json::array const& ja) const noexcept;
1423   
};
1783   
};
1424   
} // std
1784   
} // std
1425   
#endif
1785   
#endif
1426  
1786  
1427   
// Must be included here for this file to stand alone
1787   
// Must be included here for this file to stand alone
1428   
#include <boost/json/value.hpp>
1788   
#include <boost/json/value.hpp>
1429  
1789  
1430   
// includes are at the bottom of <boost/json/value.hpp>
1790   
// includes are at the bottom of <boost/json/value.hpp>
1431  
1791  
1432   
#endif
1792   
#endif