1   
//
1   
//
2   
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
2   
// Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
3   
// Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
3   
// Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)
4   
//
4   
//
5   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
5   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
6   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7   
//
7   
//
8   
// Official repository: https://github.com/boostorg/json
8   
// Official repository: https://github.com/boostorg/json
9   
//
9   
//
10  
10  
11   
#ifndef BOOST_JSON_VALUE_HPP
11   
#ifndef BOOST_JSON_VALUE_HPP
12   
#define BOOST_JSON_VALUE_HPP
12   
#define BOOST_JSON_VALUE_HPP
13 - 
#include <boost/core/detail/static_assert.hpp>
 
14  
13  
15   
#include <boost/json/detail/config.hpp>
14   
#include <boost/json/detail/config.hpp>
16   
#include <boost/json/array.hpp>
15   
#include <boost/json/array.hpp>
17   
#include <boost/json/kind.hpp>
16   
#include <boost/json/kind.hpp>
18   
#include <boost/json/object.hpp>
17   
#include <boost/json/object.hpp>
19   
#include <boost/json/pilfer.hpp>
18   
#include <boost/json/pilfer.hpp>
20   
#include <boost/json/set_pointer_options.hpp>
19   
#include <boost/json/set_pointer_options.hpp>
21   
#include <boost/json/storage_ptr.hpp>
20   
#include <boost/json/storage_ptr.hpp>
22   
#include <boost/json/string.hpp>
21   
#include <boost/json/string.hpp>
23   
#include <boost/json/string_view.hpp>
22   
#include <boost/json/string_view.hpp>
24   
#include <boost/json/value_ref.hpp>
23   
#include <boost/json/value_ref.hpp>
25   
#include <boost/json/detail/except.hpp>
24   
#include <boost/json/detail/except.hpp>
26   
#include <boost/json/detail/value.hpp>
25   
#include <boost/json/detail/value.hpp>
27   
#include <cstdlib>
26   
#include <cstdlib>
28   
#include <cstring>
27   
#include <cstring>
29   
#include <initializer_list>
28   
#include <initializer_list>
30   
#include <iosfwd>
29   
#include <iosfwd>
31   
#include <limits>
30   
#include <limits>
32   
#include <new>
31   
#include <new>
33   
#include <type_traits>
32   
#include <type_traits>
34   
#include <utility>
33   
#include <utility>
35  
34  
36   
namespace boost {
35   
namespace boost {
37   
namespace json {
36   
namespace json {
38  
37  
39   
//----------------------------------------------------------
38   
//----------------------------------------------------------
40  
39  
41   
/** The type used to represent any JSON value
40   
/** The type used to represent any JSON value
42  
41  
43 - 
    This is a [Regular](https://en.cppreference.com/w/cpp/concepts/regular)
42 + 
    This is a
44 - 
    type which works like a variant of the basic JSON data types: array,
43 + 
    <a href="https://en.cppreference.com/w/cpp/concepts/regular"><em>Regular</em></a>
 
44 + 
    type which works like
 
45 + 
    a variant of the basic JSON data types: array,
45   
    object, string, number, boolean, and null.
46   
    object, string, number, boolean, and null.
46  
47  
47   
    @par Thread Safety
48   
    @par Thread Safety
48 - 
    Distinct instances may be accessed concurrently. Non-const member
49 +
49 - 
    functions of a shared instance may not be called concurrently with any
50 + 
    Distinct instances may be accessed concurrently.
50 - 
    other member functions of that instance.
51 + 
    Non-const member functions of a shared instance
 
52 + 
    may not be called concurrently with any other
 
53 + 
    member functions of that instance.
51   
*/
54   
*/
52   
class value
55   
class value
53   
{
56   
{
54   
#ifndef BOOST_JSON_DOCS
57   
#ifndef BOOST_JSON_DOCS
55   
    using scalar = detail::scalar;
58   
    using scalar = detail::scalar;
56  
59  
57   
    union
60   
    union
58   
    {
61   
    {
59   
        storage_ptr sp_; // must come first
62   
        storage_ptr sp_; // must come first
60   
        array       arr_;
63   
        array       arr_;
61   
        object      obj_;
64   
        object      obj_;
62   
        string      str_;
65   
        string      str_;
63   
        scalar      sca_;
66   
        scalar      sca_;
64   
    };
67   
    };
65   
#endif
68   
#endif
66  
69  
67   
    struct init_iter;
70   
    struct init_iter;
68  
71  
69   
#ifndef BOOST_JSON_DOCS
72   
#ifndef BOOST_JSON_DOCS
70   
    // VFALCO doc toolchain incorrectly treats this as public
73   
    // VFALCO doc toolchain incorrectly treats this as public
71   
    friend struct detail::access;
74   
    friend struct detail::access;
72   
#endif
75   
#endif
73  
76  
74   
    explicit
77   
    explicit
75   
    value(
78   
    value(
76   
        detail::unchecked_array&& ua)
79   
        detail::unchecked_array&& ua)
77   
        : arr_(std::move(ua))
80   
        : arr_(std::move(ua))
78   
    {
81   
    {
79   
    }
82   
    }
80  
83  
81   
    explicit
84   
    explicit
82   
    value(
85   
    value(
83   
        detail::unchecked_object&& uo)
86   
        detail::unchecked_object&& uo)
84   
        : obj_(std::move(uo))
87   
        : obj_(std::move(uo))
85   
    {
88   
    {
86   
    }
89   
    }
87  
90  
88   
    value(
91   
    value(
89   
        detail::key_t const&,
92   
        detail::key_t const&,
90   
        string_view s,
93   
        string_view s,
91   
        storage_ptr sp)
94   
        storage_ptr sp)
92   
        : str_(detail::key_t{}, s, std::move(sp))
95   
        : str_(detail::key_t{}, s, std::move(sp))
93   
    {
96   
    {
94   
    }
97   
    }
95  
98  
96   
    value(
99   
    value(
97   
        detail::key_t const&,
100   
        detail::key_t const&,
98   
        string_view s1,
101   
        string_view s1,
99   
        string_view s2,
102   
        string_view s2,
100   
        storage_ptr sp)
103   
        storage_ptr sp)
101   
        : str_(detail::key_t{}, s1, s2, std::move(sp))
104   
        : str_(detail::key_t{}, s1, s2, std::move(sp))
102   
    {
105   
    {
103   
    }
106   
    }
104  
107  
105   
    inline bool is_scalar() const noexcept
108   
    inline bool is_scalar() const noexcept
106   
    {
109   
    {
107   
        return sca_.k < json::kind::string;
110   
        return sca_.k < json::kind::string;
108   
    }
111   
    }
109  
112  
110   
public:
113   
public:
111   
    /// Associated [Allocator](https://en.cppreference.com/w/cpp/named_req/Allocator)
114   
    /// Associated [Allocator](https://en.cppreference.com/w/cpp/named_req/Allocator)
112   
    using allocator_type = container::pmr::polymorphic_allocator<value>;
115   
    using allocator_type = container::pmr::polymorphic_allocator<value>;
113  
116  
114   
    /** Destructor.
117   
    /** Destructor.
115  
118  
116 - 
        The value and all of its contents are destroyed. Any dynamically
119 + 
        The value and all of its contents are destroyed.
117 - 
        allocated memory that was allocated internally is freed.
120 + 
        Any dynamically allocated memory that was allocated
 
121 + 
        internally is freed.
118  
122  
119   
        @par Complexity
123   
        @par Complexity
120   
        Constant, or linear in size for array or object.
124   
        Constant, or linear in size for array or object.
121  
125  
122   
        @par Exception Safety
126   
        @par Exception Safety
123   
        No-throw guarantee.
127   
        No-throw guarantee.
124   
    */
128   
    */
125   
    BOOST_JSON_DECL
129   
    BOOST_JSON_DECL
126   
    ~value() noexcept;
130   
    ~value() noexcept;
127  
131  
128 - 
    /** Constructors.
132 + 
    /** Default constructor.
129  
133  
130 - 
        Construct a new `value`.
134 + 
        The constructed value is null,
 
135 + 
        using the [default memory resource].
131  
136  
132 - 
        @li **(1)**--**(3)** the constructed value is null.
137 + 
        @par Complexity
133 - 
        @li **(4)** the constructed value contains a copy of `b`.
138 + 
        Constant.
134 - 
        @li **(5)**--**(9)** the constructed value contains a copy of `i`.
 
135 - 
        @li **(10)**--**(14)** the constructed value contains a copy of `u`.
 
136 - 
        @li **(15)** the constructed value contains a copy of `d`.
 
137 - 
        @li **(16)**, **(19)** the constructed value contains a copy of the
 
138 - 
            string `s`.
 
139 - 
        @li **(17)** the constructed value contains a copy of the
 
140 - 
            null-terminated string `s`.
 
141 - 
        @li **(18)** the constructed value takes ownership of `s`'s storage.
 
142 - 
        @li **(20)** if `*s.storage() == *sp` equivalent to **(18)**, otherwise
 
143 - 
            equivalent to **(19)**.
 
144 - 
        @li **(21)** the constructed value contains an empty string.
 
145 - 
        @li **(22)** the constructed value takes ownership of `arr`'s storage.
 
146 - 
        @li **(23)** the constructed value contains an element-wise copy of the
 
147 - 
            array `arr`.
 
148 - 
        @li **(24)** if `*arr.storage() == *sp` equivalent to **(22)**,
 
149 - 
            otherwise equivalent to **(23)**.
 
150 - 
        @li **(25)** the constructed value contains an empty array.
 
151 - 
        @li **(26)** the constructed value takes ownership of `obj`'s storage.
 
152 - 
        @li **(27)** the constructed value contains an element-wise copy of the
 
153 - 
            object `obj`.
 
154 - 
        @li **(28)** if `*obj.storage() == *sp` equivalent to **(26)**,
 
155 - 
            otherwise equivalent to **(27)**.
 
156 - 
        @li **(29)** the constructed value contains an empty object.
 
157 - 
        @li **(30)** the constructed value's contents are formed by
 
158 - 
            constructing from `init` and `sp` (see \<\<initializer_lists\>\>).
 
159 - 
        @li **(31)**, **(32)** the constructed value contains a copy of the
 
160 - 
            contents of `other`.
 
161 - 
        @li **(33)** the constructed value acquires ownership of the contents
 
162 - 
            of `other`.
 
163 - 
        @li **(34)** equivalent to **(33)** if `*sp == *other.storage()`;
 
164 - 
            otherwise equivalent to **(32)**.
 
165 - 
        @li **(35)** the constructed value acquires ownership of the contents
 
166 - 
            of `other` using pilfer semantics. This is more efficient than move
 
167 - 
            construction, when it is known that the moved-from object will be
 
168 - 
            immediately destroyed afterwards.
 
169  
139  
170 - 
        With **(2)**--**(17)**, **(19)**--**(21)**, **(23)**--**(25)**,
140 + 
        @par Exception Safety
171 - 
        {sp} **(27)**--**(30)**, **(32)**, and **(34)** the constructed value
141 + 
        No-throw guarantee.
172 - 
        uses memory resource of `sp`. With **(18)**, **(22)**, **(26)**,
 
173 - 
        {sp} **(31)**, **(33)**, and **(35)** it uses the memory resource of
 
174 - 
        the argument (`s`, `arr`, obj`, or `value`). In either case the value
 
175 - 
        will share the ownership of the memory resource. With **(1)**
 
176 - 
        it uses the \<\<default_memory_resource, default memory resource\>\>.
 
177  
142  
178 - 
        After **(18)**, **(22)**, **(26)**, and **(33)** the argument behaves
143 + 
        [default memory resource]: json/allocators/storage_ptr.html#json.allocators.storage_ptr.default_memory_resource
179 - 
        as if newly constructed with its current storage pointer (i.e. becomes
144 + 
    */
180 - 
        an empty string, array, object, or null value).
145 + 
    value() noexcept
 
146 + 
        : sca_()
 
147 + 
    {
 
148 + 
    }
181  
149  
182 - 
        After **(35)** `other` is not in a usable state and may only be
150 + 
    /** Constructor.
183 - 
        destroyed.
151 +
 
152 + 
        The constructed value is null, using the
 
153 + 
        specified `boost::container::pmr::memory_resource`.
184  
154  
185   
        @par Complexity
155   
        @par Complexity
186 - 
        @li **(1)**--**(15)**, **(18)**, **(21)**, **(22)**, **(25)**,
156 + 
        Constant.
187 - 
            {sp} **(26)**, **(29)**, **(33)**, **(35)** constant.
 
188 - 
        @li **(16)**, **(19)** linear in `s.size()`.
 
189 - 
        @li **(17)** linear in `std::strlen(s)`.
 
190 - 
        @li **(20)** if `*s.storage() == *sp` constant, otherwise linear
 
191 - 
            in `s.size()`.
 
192 - 
        @li **(23)** linear in `arr.size()`.
 
193 - 
        @li **(24)** if `*arr.storage() == *sp` constant, otherwise linear
 
194 - 
            in `arr.size()`.
 
195 - 
        @li **(27)** linear in `obj.size()`.
 
196 - 
        @li **(28)** if `*obj.storage() == *sp` constant, otherwise linear
 
197 - 
            in `obj.size()`.
 
198 - 
        @li **(30)** linear in `init.size()`.
 
199 - 
        @li **(31)**, **(32)** linear in the size of `other`.
 
200 - 
        @li **(34)** constant if `*sp == *other.storage()`; otherwise linear in
 
201 - 
            the size of `other`.
 
202  
157  
203 - 
        The size of `other` is either the size of the underlying container
158 + 
        @par Exception Safety
204 - 
        (if there is one), or can be considered to be 1.
159 + 
        No-throw guarantee.
 
160 +
 
161 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
162 + 
        use. The container will acquire shared ownership of the memory
 
163 + 
        resource.
 
164 + 
    */
 
165 + 
    explicit
 
166 + 
    value(storage_ptr sp) noexcept
 
167 + 
        : sca_(std::move(sp))
 
168 + 
    {
 
169 + 
    }
 
170 +
 
171 + 
    /** Pilfer constructor.
 
172 +
 
173 + 
        The value is constructed by acquiring ownership
 
174 + 
        of the contents of `other` using pilfer semantics.
 
175 + 
        This is more efficient than move construction, when
 
176 + 
        it is known that the moved-from object will be
 
177 + 
        immediately destroyed afterwards.
 
178 +
 
179 + 
        @par Complexity
 
180 + 
        Constant.
205  
181  
206   
        @par Exception Safety
182   
        @par Exception Safety
207 - 
        @li **(1)**--**(15)**, **(18)**, **(21)**, **(22)**, **(25)**,
183 + 
        No-throw guarantee.
208 - 
            **(26)**, **(29)**, **(33)**, **(35)** no-throw guarantee.
 
209 - 
        @li **(16)**, **(17)**, **(19)**, **(23)**, **(27)**,
 
210 - 
            **(30)**--**(32)** strong guarantee.
 
211 - 
        @li **(20)** if `*s.storage() == *sp` no-throw guarantee, otherwise
 
212 - 
            strong guarantee.
 
213 - 
        @li **(24)** if `*arr.storage() == *sp` no-throw guarantee, otherwise
 
214 - 
            strong guarantee.
 
215 - 
        @li **(28)** if `*obj.storage() == *sp` no-throw guarantee, otherwise
 
216 - 
            strong guarantee.
 
217 - 
        @li **(33)** if `*other.storage() == *sp` no-throw guarantee, otherwise
 
218 - 
            strong guarantee.
 
219  
184  
220 - 
        Calls to `memory_resource::allocate` may throw.
185 + 
        @param other The value to pilfer. After pilfer
 
186 + 
        construction, `other` is not in a usable state
 
187 + 
        and may only be destroyed.
221  
188  
222   
        @see @ref pilfer,
189   
        @see @ref pilfer,
223 - 
            [Valueless Variants Considered Harmful](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0308r0.html).
190 + 
            <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0308r0.html">
224 - 
                                                         //
191 + 
                Valueless Variants Considered Harmful</a>
225 - 
        @{
 
226   
    */
192   
    */
227 - 
    value() noexcept
193 + 
    value(pilfered<value> other) noexcept
228 - 
        : sca_()
 
229   
    {
194   
    {
 
195 + 
        relocate(this, other.get());
 
196 + 
        ::new(&other.get().sca_) scalar();
230   
    }
197   
    }
231  
198  
232 - 
    /** Overload
199 + 
    /** Copy constructor.
233  
200  
234 - 
        @param sp A pointer to the @ref boost::container::pmr::memory_resource
201 + 
        The value is constructed with a copy of the
235 - 
               to use.
202 + 
        contents of `other`, using the same
 
203 + 
        memory resource as `other`.
 
204 +
 
205 + 
        @par Complexity
 
206 + 
        Linear in the size of `other`.
 
207 +
 
208 + 
        @par Exception Safety
 
209 + 
        Strong guarantee.
 
210 + 
        Calls to `memory_resource::allocate` may throw.
 
211 +
 
212 + 
        @param other The value to copy.
236   
    */
213   
    */
237 - 
    explicit
214 + 
    value(value const& other)
238 - 
    value(storage_ptr sp) noexcept
215 + 
        : value(other, other.storage())
239 - 
        : sca_(std::move(sp))
 
240   
    {
216   
    {
241   
    }
217   
    }
242  
218  
243 - 
    /// Overload
219 + 
    /** Copy constructor
 
220 +
 
221 + 
        The value is constructed with a copy of the
 
222 + 
        contents of `other`, using the
 
223 + 
        specified memory resource.
 
224 +
 
225 + 
        @par Complexity
 
226 + 
        Linear in the size of `other`.
 
227 +
 
228 + 
        @par Exception Safety
 
229 + 
        Strong guarantee.
 
230 + 
        Calls to `memory_resource::allocate` may throw.
 
231 +
 
232 + 
        @param other The value to copy.
 
233 +
 
234 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
235 + 
        use. The container will acquire shared ownership of the memory
 
236 + 
        resource.
 
237 + 
    */
 
238 + 
    BOOST_JSON_DECL
 
239 + 
    value(
 
240 + 
        value const& other,
 
241 + 
        storage_ptr sp);
 
242 +
 
243 + 
    /** Move constructor
 
244 +
 
245 + 
        The value is constructed by acquiring ownership of
 
246 + 
        the contents of `other` and shared ownership of
 
247 + 
        `other`'s memory resource.
 
248 +
 
249 + 
        @note
 
250 +
 
251 + 
        After construction, the moved-from value becomes a
 
252 + 
        null value with its current storage pointer.
 
253 +
 
254 + 
        @par Complexity
 
255 + 
        Constant.
 
256 +
 
257 + 
        @par Exception Safety
 
258 + 
        No-throw guarantee.
 
259 +
 
260 + 
        @param other The value to move.
 
261 + 
    */
 
262 + 
    BOOST_JSON_DECL
 
263 + 
    value(value&& other) noexcept;
 
264 +
 
265 + 
    /** Move constructor
 
266 +
 
267 + 
        The value is constructed with the contents of
 
268 + 
        `other` by move semantics, using the specified
 
269 + 
        memory resource:
 
270 +
 
271 + 
        @li If `*other.storage() == *sp`, ownership of
 
272 + 
        the underlying memory is transferred in constant
 
273 + 
        time, with no possibility of exceptions.
 
274 + 
        After construction, the moved-from value becomes
 
275 + 
        a null value with its current storage pointer.
 
276 +
 
277 + 
        @li If `*other.storage() != *sp`, an
 
278 + 
        element-wise copy is performed if
 
279 + 
        `other.is_structured() == true`, which may throw.
 
280 + 
        In this case, the moved-from value is not
 
281 + 
        changed.
 
282 +
 
283 + 
        @par Complexity
 
284 + 
        Constant or linear in the size of `other`.
 
285 +
 
286 + 
        @par Exception Safety
 
287 + 
        Strong guarantee.
 
288 + 
        Calls to `memory_resource::allocate` may throw.
 
289 +
 
290 + 
        @param other The value to move.
 
291 +
 
292 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
293 + 
        use. The container will acquire shared ownership of the memory
 
294 + 
        resource.
 
295 + 
    */
 
296 + 
    BOOST_JSON_DECL
 
297 + 
    value(
 
298 + 
        value&& other,
 
299 + 
        storage_ptr sp);
 
300 +
 
301 + 
    //------------------------------------------------------
 
302 + 
    //
 
303 + 
    // Conversion
 
304 + 
    //
 
305 + 
    //------------------------------------------------------
 
306 +
 
307 + 
    /** Construct a null.
 
308 +
 
309 + 
        A null value is a monostate.
 
310 +
 
311 + 
        @par Complexity
 
312 + 
        Constant.
 
313 +
 
314 + 
        @par Exception Safety
 
315 + 
        No-throw guarantee.
 
316 +
 
317 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
318 + 
        use. The container will acquire shared ownership of the memory
 
319 + 
        resource.
 
320 + 
    */
244   
    value(
321   
    value(
245   
        std::nullptr_t,
322   
        std::nullptr_t,
246   
        storage_ptr sp = {}) noexcept
323   
        storage_ptr sp = {}) noexcept
247   
        : sca_(std::move(sp))
324   
        : sca_(std::move(sp))
248   
    {
325   
    {
249   
    }
326   
    }
250  
327  
251 - 
    /** Overload
328 + 
    /** Construct a bool.
252  
329  
253 - 
        @param b The boolean to construct with.
330 + 
        This constructs a `bool` value using
254 - 
        @param sp
331 + 
        the specified memory resource.
 
332 +
 
333 + 
        @par Complexity
 
334 + 
        Constant.
 
335 +
 
336 + 
        @par Exception Safety
 
337 + 
        No-throw guarantee.
 
338 +
 
339 + 
        @param b The initial value.
 
340 +
 
341 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
342 + 
        use. The container will acquire shared ownership of the memory
 
343 + 
        resource.
255   
    */
344   
    */
256   
#ifdef BOOST_JSON_DOCS
345   
#ifdef BOOST_JSON_DOCS
257   
    value(
346   
    value(
258   
        bool b,
347   
        bool b,
259   
        storage_ptr sp = {}) noexcept;
348   
        storage_ptr sp = {}) noexcept;
260   
#else
349   
#else
261   
    template<class T
350   
    template<class T
262   
        ,class = typename std::enable_if<
351   
        ,class = typename std::enable_if<
263   
            std::is_same<T, bool>::value>::type
352   
            std::is_same<T, bool>::value>::type
264   
    >
353   
    >
265   
    value(
354   
    value(
266   
        T b,
355   
        T b,
267   
        storage_ptr sp = {}) noexcept
356   
        storage_ptr sp = {}) noexcept
268   
        : sca_(b, std::move(sp))
357   
        : sca_(b, std::move(sp))
269   
    {
358   
    {
270   
    }
359   
    }
271   
#endif
360   
#endif
272  
361  
273 - 
    /** Overload
362 + 
    /** Construct a `std::int64_t`.
274  
363  
275 - 
        @param i The number to construct with.
364 + 
        @par Complexity
276 - 
        @param sp
365 + 
        Constant.
 
366 +
 
367 + 
        @par Exception Safety
 
368 + 
        No-throw guarantee.
 
369 +
 
370 + 
        @param i The initial value.
 
371 +
 
372 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
373 + 
        use. The container will acquire shared ownership of the memory
 
374 + 
        resource.
277   
    */
375   
    */
278   
    value(
376   
    value(
279   
        signed char i,
377   
        signed char i,
280   
        storage_ptr sp = {}) noexcept
378   
        storage_ptr sp = {}) noexcept
281   
        : sca_(static_cast<std::int64_t>(
379   
        : sca_(static_cast<std::int64_t>(
282   
            i), std::move(sp))
380   
            i), std::move(sp))
283   
    {
381   
    {
284   
    }
382   
    }
285  
383  
286 - 
    /// Overload
384 + 
    /** Construct a `std::int64_t`.
 
385 +
 
386 + 
        @par Complexity
 
387 + 
        Constant.
 
388 +
 
389 + 
        @par Exception Safety
 
390 + 
        No-throw guarantee.
 
391 +
 
392 + 
        @param i The initial value.
 
393 +
 
394 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
395 + 
        use. The container will acquire shared ownership of the memory
 
396 + 
        resource.
 
397 + 
    */
287   
    value(
398   
    value(
288   
        short i,
399   
        short i,
289   
        storage_ptr sp = {}) noexcept
400   
        storage_ptr sp = {}) noexcept
290   
        : sca_(static_cast<std::int64_t>(
401   
        : sca_(static_cast<std::int64_t>(
291   
            i), std::move(sp))
402   
            i), std::move(sp))
292   
    {
403   
    {
293   
    }
404   
    }
294  
405  
295 - 
    /// Overload
406 + 
    /** Construct a `std::int64_t`.
 
407 +
 
408 + 
        @par Complexity
 
409 + 
        Constant.
 
410 +
 
411 + 
        @par Exception Safety
 
412 + 
        No-throw guarantee.
 
413 +
 
414 + 
        @param i The initial value.
 
415 +
 
416 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
417 + 
        use. The container will acquire shared ownership of the memory
 
418 + 
        resource.
 
419 + 
    */
296   
    value(
420   
    value(
297   
        int i,
421   
        int i,
298   
        storage_ptr sp = {}) noexcept
422   
        storage_ptr sp = {}) noexcept
299   
        : sca_(static_cast<std::int64_t>(i),
423   
        : sca_(static_cast<std::int64_t>(i),
300   
            std::move(sp))
424   
            std::move(sp))
301   
    {
425   
    {
302   
    }
426   
    }
303  
427  
304 - 
    /// Overload
428 + 
    /** Construct a `std::int64_t`.
 
429 +
 
430 + 
        @par Complexity
 
431 + 
        Constant.
 
432 +
 
433 + 
        @par Exception Safety
 
434 + 
        No-throw guarantee.
 
435 +
 
436 + 
        @param i The initial value.
 
437 +
 
438 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
439 + 
        use. The container will acquire shared ownership of the memory
 
440 + 
        resource.
 
441 + 
    */
305   
    value(
442   
    value(
306   
        long i,
443   
        long i,
307   
        storage_ptr sp = {}) noexcept
444   
        storage_ptr sp = {}) noexcept
308   
        : sca_(static_cast<std::int64_t>(i),
445   
        : sca_(static_cast<std::int64_t>(i),
309   
            std::move(sp))
446   
            std::move(sp))
310   
    {
447   
    {
311   
    }
448   
    }
312  
449  
313 - 
    /// Overload
450 + 
    /** Construct a `std::int64_t`.
 
451 +
 
452 + 
        @par Complexity
 
453 + 
        Constant.
 
454 +
 
455 + 
        @par Exception Safety
 
456 + 
        No-throw guarantee.
 
457 +
 
458 + 
        @param i The initial value.
 
459 +
 
460 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
461 + 
        use. The container will acquire shared ownership of the memory
 
462 + 
        resource.
 
463 + 
    */
314   
    value(
464   
    value(
315   
        long long i,
465   
        long long i,
316   
        storage_ptr sp = {}) noexcept
466   
        storage_ptr sp = {}) noexcept
317   
        : sca_(static_cast<std::int64_t>(i),
467   
        : sca_(static_cast<std::int64_t>(i),
318   
            std::move(sp))
468   
            std::move(sp))
319   
    {
469   
    {
320   
    }
470   
    }
321  
471  
322 - 
    /** Overload
472 + 
    /** Construct a `std::uint64_t`.
323  
473  
324 - 
        @param u The number to construct with.
474 + 
        @par Complexity
325 - 
        @param sp
475 + 
        Constant.
 
476 +
 
477 + 
        @par Exception Safety
 
478 + 
        No-throw guarantee.
 
479 +
 
480 + 
        @param u The initial value.
 
481 +
 
482 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
483 + 
        use. The container will acquire shared ownership of the memory
 
484 + 
        resource.
326   
    */
485   
    */
327   
    value(
486   
    value(
328   
        unsigned char u,
487   
        unsigned char u,
329   
        storage_ptr sp = {}) noexcept
488   
        storage_ptr sp = {}) noexcept
330   
        : sca_(static_cast<std::uint64_t>(
489   
        : sca_(static_cast<std::uint64_t>(
331   
            u), std::move(sp))
490   
            u), std::move(sp))
332   
    {
491   
    {
333   
    }
492   
    }
334  
493  
335 - 
    /// Overload
494 + 
    /** Construct a `std::uint64_t`.
 
495 +
 
496 + 
        @par Complexity
 
497 + 
        Constant.
 
498 +
 
499 + 
        @par Exception Safety
 
500 + 
        No-throw guarantee.
 
501 +
 
502 + 
        @param u The initial value.
 
503 +
 
504 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
505 + 
        use. The container will acquire shared ownership of the memory
 
506 + 
        resource.
 
507 + 
    */
336   
    value(
508   
    value(
337   
        unsigned short u,
509   
        unsigned short u,
338   
        storage_ptr sp = {}) noexcept
510   
        storage_ptr sp = {}) noexcept
339   
        : sca_(static_cast<std::uint64_t>(u),
511   
        : sca_(static_cast<std::uint64_t>(u),
340   
            std::move(sp))
512   
            std::move(sp))
341   
    {
513   
    {
342   
    }
514   
    }
343  
515  
344 - 
    /// Overload
516 + 
    /** Construct a `std::uint64_t`.
 
517 +
 
518 + 
        @par Complexity
 
519 + 
        Constant.
 
520 +
 
521 + 
        @par Exception Safety
 
522 + 
        No-throw guarantee.
 
523 +
 
524 + 
        @param u The initial value.
 
525 +
 
526 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
527 + 
        use. The container will acquire shared ownership of the memory
 
528 + 
        resource.
 
529 + 
    */
345   
    value(
530   
    value(
346   
        unsigned int u,
531   
        unsigned int u,
347   
        storage_ptr sp = {}) noexcept
532   
        storage_ptr sp = {}) noexcept
348   
        : sca_(static_cast<std::uint64_t>(u),
533   
        : sca_(static_cast<std::uint64_t>(u),
349   
            std::move(sp))
534   
            std::move(sp))
350   
    {
535   
    {
351   
    }
536   
    }
352  
537  
353 - 
    /// Overload
538 + 
    /** Construct a `std::uint64_t`.
 
539 +
 
540 + 
        @par Complexity
 
541 + 
        Constant.
 
542 +
 
543 + 
        @par Exception Safety
 
544 + 
        No-throw guarantee.
 
545 +
 
546 + 
        @param u The initial value.
 
547 +
 
548 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
549 + 
        use. The container will acquire shared ownership of the memory
 
550 + 
        resource.
 
551 + 
    */
354   
    value(
552   
    value(
355   
        unsigned long u,
553   
        unsigned long u,
356   
        storage_ptr sp = {}) noexcept
554   
        storage_ptr sp = {}) noexcept
357   
        : sca_(static_cast<std::uint64_t>(u),
555   
        : sca_(static_cast<std::uint64_t>(u),
358   
            std::move(sp))
556   
            std::move(sp))
359   
    {
557   
    {
360   
    }
558   
    }
361  
559  
362 - 
    /// Overload
560 + 
    /** Construct a `std::uint64_t`.
 
561 +
 
562 + 
        @par Complexity
 
563 + 
        Constant.
 
564 +
 
565 + 
        @par Exception Safety
 
566 + 
        No-throw guarantee.
 
567 +
 
568 + 
        @param u The initial value.
 
569 +
 
570 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
571 + 
        use. The container will acquire shared ownership of the memory
 
572 + 
        resource.
 
573 + 
    */
363   
    value(
574   
    value(
364   
        unsigned long long u,
575   
        unsigned long long u,
365   
        storage_ptr sp = {}) noexcept
576   
        storage_ptr sp = {}) noexcept
366   
        : sca_(static_cast<std::uint64_t>(u),
577   
        : sca_(static_cast<std::uint64_t>(u),
367   
            std::move(sp))
578   
            std::move(sp))
368   
    {
579   
    {
369   
    }
580   
    }
370  
581  
371 - 
    /** Overload
582 + 
    /** Construct a `double`.
372  
583  
373 - 
        @param d The number to construct with.
584 + 
        @par Complexity
374 - 
        @param sp
585 + 
        Constant.
 
586 +
 
587 + 
        @par Exception Safety
 
588 + 
        No-throw guarantee.
 
589 +
 
590 + 
        @param d The initial value.
 
591 +
 
592 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
593 + 
        use. The container will acquire shared ownership of the memory
 
594 + 
        resource.
375   
    */
595   
    */
376   
    value(
596   
    value(
377   
        double d,
597   
        double d,
378   
        storage_ptr sp = {}) noexcept
598   
        storage_ptr sp = {}) noexcept
379   
        : sca_(d, std::move(sp))
599   
        : sca_(d, std::move(sp))
380   
    {
600   
    {
381   
    }
601   
    }
382  
602  
383 - 
    /** Overload
603 + 
    /** Construct a @ref string.
384  
604  
385 - 
        @param s The string to construct with.
605 + 
        The string is constructed with a copy of the
386 - 
        @param sp
606 + 
        string view `s`, using the specified memory resource.
 
607 +
 
608 + 
        @par Complexity
 
609 + 
        Linear in `s.size()`.
 
610 +
 
611 + 
        @par Exception Safety
 
612 + 
        Strong guarantee.
 
613 + 
        Calls to `memory_resource::allocate` may throw.
 
614 +
 
615 + 
        @param s The string view to construct with.
 
616 +
 
617 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
618 + 
        use. The container will acquire shared ownership of the memory
 
619 + 
        resource.
387   
    */
620   
    */
388   
    value(
621   
    value(
389   
        string_view s,
622   
        string_view s,
390   
        storage_ptr sp = {})
623   
        storage_ptr sp = {})
391   
        : str_(s, std::move(sp))
624   
        : str_(s, std::move(sp))
392   
    {
625   
    {
393   
    }
626   
    }
394  
627  
395 - 
    /// Overload
628 + 
    /** Construct a @ref string.
 
629 +
 
630 + 
        The string is constructed with a copy of the
 
631 + 
        null-terminated string `s`, using the specified
 
632 + 
        memory resource.
 
633 +
 
634 + 
        @par Complexity
 
635 + 
        Linear in `std::strlen(s)`.
 
636 +
 
637 + 
        @par Exception Safety
 
638 + 
        Strong guarantee.
 
639 + 
        Calls to `memory_resource::allocate` may throw.
 
640 +
 
641 + 
        @param s The null-terminated string to construct
 
642 + 
        with.
 
643 +
 
644 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
645 + 
        use. The container will acquire shared ownership of the memory
 
646 + 
        resource.
 
647 + 
    */
396   
    value(
648   
    value(
397   
        char const* s,
649   
        char const* s,
398   
        storage_ptr sp = {})
650   
        storage_ptr sp = {})
399   
        : str_(s, std::move(sp))
651   
        : str_(s, std::move(sp))
400   
    {
652   
    {
401   
    }
653   
    }
402  
654  
403 - 
    /// Overload
655 + 
    /** Construct a @ref string.
 
656 +
 
657 + 
        The value is constructed from `other`, using the
 
658 + 
        same memory resource. To transfer ownership, use `std::move`:
 
659 +
 
660 + 
        @par Example
 
661 + 
        @code
 
662 + 
        string str = "The Boost C++ Library Collection";
 
663 +
 
664 + 
        // transfer ownership
 
665 + 
        value jv( std::move(str) );
 
666 +
 
667 + 
        assert( str.empty() );
 
668 + 
        assert( *str.storage() == *jv.storage() );
 
669 + 
        @endcode
 
670 +
 
671 + 
        @par Complexity
 
672 + 
        Constant.
 
673 +
 
674 + 
        @par Exception Safety
 
675 + 
        No-throw guarantee.
 
676 +
 
677 + 
        @param other The string to construct with.
 
678 + 
    */
404   
    value(
679   
    value(
405 - 
        string s) noexcept
680 + 
        string other) noexcept
406 - 
        : str_(std::move(s))
681 + 
        : str_(std::move(other))
407   
    {
682   
    {
408   
    }
683   
    }
409  
684  
410 - 
    /// Overload
685 + 
    /** Construct a @ref string.
 
686 +
 
687 + 
        The value is copy constructed from `other`,
 
688 + 
        using the specified memory resource.
 
689 +
 
690 + 
        @par Complexity
 
691 + 
        Linear in `other.size()`.
 
692 +
 
693 + 
        @par Exception Safety
 
694 + 
        Strong guarantee.
 
695 + 
        Calls to `memory_resource::allocate` may throw.
 
696 +
 
697 + 
        @param other The string to construct with.
 
698 +
 
699 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
700 + 
        use. The container will acquire shared ownership of the memory
 
701 + 
        resource.
 
702 + 
    */
411   
    value(
703   
    value(
412 - 
        string const& s,
704 + 
        string const& other,
413   
        storage_ptr sp)
705   
        storage_ptr sp)
414   
        : str_(
706   
        : str_(
415 - 
            s,
707 + 
            other,
416   
            std::move(sp))
708   
            std::move(sp))
417   
    {
709   
    {
418   
    }
710   
    }
419  
711  
420 - 
    /// Overload
712 + 
    /** Construct a @ref string.
 
713 +
 
714 + 
        The value is move constructed from `other`,
 
715 + 
        using the specified memory resource.
 
716 +
 
717 + 
        @par Complexity
 
718 + 
        Constant or linear in `other.size()`.
 
719 +
 
720 + 
        @par Exception Safety
 
721 + 
        Strong guarantee.
 
722 + 
        Calls to `memory_resource::allocate` may throw.
 
723 +
 
724 + 
        @param other The string to construct with.
 
725 +
 
726 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
727 + 
        use. The container will acquire shared ownership of the memory
 
728 + 
        resource.
 
729 + 
    */
421   
    value(
730   
    value(
422 - 
        string&& s,
731 + 
        string&& other,
423   
        storage_ptr sp)
732   
        storage_ptr sp)
424   
        : str_(
733   
        : str_(
425 - 
            std::move(s),
734 + 
            std::move(other),
426   
            std::move(sp))
735   
            std::move(sp))
427   
    {
736   
    {
428   
    }
737   
    }
429  
738  
430 - 
    /// Overload
739 + 
    /** Construct a @ref string.
 
740 +
 
741 + 
        This is the fastest way to construct
 
742 + 
        an empty string, using the specified
 
743 + 
        memory resource. The variable @ref string_kind
 
744 + 
        may be passed as the first parameter
 
745 + 
        to select this overload:
 
746 +
 
747 + 
        @par Example
 
748 + 
        @code
 
749 + 
        // Construct an empty string
 
750 +
 
751 + 
        value jv( string_kind );
 
752 + 
        @endcode
 
753 +
 
754 + 
        @par Complexity
 
755 + 
        Constant.
 
756 +
 
757 + 
        @par Exception Safety
 
758 + 
        No-throw guarantee.
 
759 +
 
760 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
761 + 
        use. The container will acquire shared ownership of the memory
 
762 + 
        resource.
 
763 +
 
764 + 
        @see @ref string_kind
 
765 + 
    */
431   
    value(
766   
    value(
432   
        string_kind_t,
767   
        string_kind_t,
433   
        storage_ptr sp = {}) noexcept
768   
        storage_ptr sp = {}) noexcept
434   
        : str_(std::move(sp))
769   
        : str_(std::move(sp))
435   
    {
770   
    {
436   
    }
771   
    }
437  
772  
438 - 
    /** Overload
773 + 
    /** Construct an @ref array.
439  
774  
440 - 
        @param arr The array to construct with.
775 + 
        The value is constructed from `other`, using the
 
776 + 
        same memory resource. To transfer ownership, use `std::move`:
 
777 +
 
778 + 
        @par Example
 
779 + 
        @code
 
780 + 
        array arr( {1, 2, 3, 4, 5} );
 
781 +
 
782 + 
        // transfer ownership
 
783 + 
        value jv( std::move(arr) );
 
784 +
 
785 + 
        assert( arr.empty() );
 
786 + 
        assert( *arr.storage() == *jv.storage() );
 
787 + 
        @endcode
 
788 +
 
789 + 
        @par Complexity
 
790 + 
        Constant.
 
791 +
 
792 + 
        @par Exception Safety
 
793 + 
        No-throw guarantee.
 
794 +
 
795 + 
        @param other The array to construct with.
441   
    */
796   
    */
442 - 
    value(array arr) noexcept
797 + 
    value(array other) noexcept
443 - 
        : arr_(std::move(arr))
798 + 
        : arr_(std::move(other))
444   
    {
799   
    {
445   
    }
800   
    }
446  
801  
447 - 
    /// Overload
802 + 
    /** Construct an @ref array.
 
803 +
 
804 + 
        The value is copy constructed from `other`,
 
805 + 
        using the specified memory resource.
 
806 +
 
807 + 
        @par Complexity
 
808 + 
        Linear in `other.size()`.
 
809 +
 
810 + 
        @par Exception Safety
 
811 + 
        Strong guarantee.
 
812 + 
        Calls to `memory_resource::allocate` may throw.
 
813 +
 
814 + 
        @param other The array to construct with.
 
815 +
 
816 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
817 + 
        use. The container will acquire shared ownership of the memory
 
818 + 
        resource.
 
819 + 
    */
448   
    value(
820   
    value(
449 - 
        array const& arr,
821 + 
        array const& other,
450   
        storage_ptr sp)
822   
        storage_ptr sp)
451   
        : arr_(
823   
        : arr_(
452 - 
            arr,
824 + 
            other,
453   
            std::move(sp))
825   
            std::move(sp))
454   
    {
826   
    {
455   
    }
827   
    }
456  
828  
457 - 
    /// Overload
829 + 
    /** Construct an @ref array.
 
830 +
 
831 + 
        The value is move-constructed from `other`,
 
832 + 
        using the specified memory resource.
 
833 +
 
834 + 
        @par Complexity
 
835 + 
        Constant or linear in `other.size()`.
 
836 +
 
837 + 
        @par Exception Safety
 
838 + 
        Strong guarantee.
 
839 + 
        Calls to `memory_resource::allocate` may throw.
 
840 +
 
841 + 
        @param other The array to construct with.
 
842 +
 
843 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
844 + 
        use. The container will acquire shared ownership of the memory
 
845 + 
        resource.
 
846 + 
    */
458   
    value(
847   
    value(
459 - 
        array&& arr,
848 + 
        array&& other,
460   
        storage_ptr sp)
849   
        storage_ptr sp)
461   
        : arr_(
850   
        : arr_(
462 - 
            std::move(arr),
851 + 
            std::move(other),
463   
            std::move(sp))
852   
            std::move(sp))
464   
    {
853   
    {
465   
    }
854   
    }
466  
855  
467 - 
    /// Overload
856 + 
    /** Construct an @ref array.
 
857 +
 
858 + 
        This is the fastest way to construct
 
859 + 
        an empty array, using the specified
 
860 + 
        memory resource. The variable @ref array_kind
 
861 + 
        may be passed as the first parameter
 
862 + 
        to select this overload:
 
863 +
 
864 + 
        @par Example
 
865 + 
        @code
 
866 + 
        // Construct an empty array
 
867 +
 
868 + 
        value jv( array_kind );
 
869 + 
        @endcode
 
870 +
 
871 + 
        @par Complexity
 
872 + 
        Constant.
 
873 +
 
874 + 
        @par Exception Safety
 
875 + 
        No-throw guarantee.
 
876 +
 
877 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
878 + 
        use. The container will acquire shared ownership of the memory
 
879 + 
        resource.
 
880 +
 
881 + 
        @see @ref array_kind
 
882 + 
    */
468   
    value(
883   
    value(
469   
        array_kind_t,
884   
        array_kind_t,
470   
        storage_ptr sp = {}) noexcept
885   
        storage_ptr sp = {}) noexcept
471   
        : arr_(std::move(sp))
886   
        : arr_(std::move(sp))
472   
    {
887   
    {
473   
    }
888   
    }
474  
889  
475 - 
    /** Overload
890 + 
    /** Construct an @ref object.
476  
891  
477 - 
        @param obj The object to construct with.
892 + 
        The value is constructed from `other`, using the
 
893 + 
        same memory resource. To transfer ownership, use `std::move`:
 
894 +
 
895 + 
        @par Example
 
896 + 
        @code
 
897 + 
        object obj( {{"a",1}, {"b",2}, {"c"},3}} );
 
898 +
 
899 + 
        // transfer ownership
 
900 + 
        value jv( std::move(obj) );
 
901 +
 
902 + 
        assert( obj.empty() );
 
903 + 
        assert( *obj.storage() == *jv.storage() );
 
904 + 
        @endcode
 
905 +
 
906 + 
        @par Complexity
 
907 + 
        Constant.
 
908 +
 
909 + 
        @par Exception Safety
 
910 + 
        No-throw guarantee.
 
911 +
 
912 + 
        @param other The object to construct with.
478   
    */
913   
    */
479 - 
    value(object obj) noexcept
914 + 
    value(object other) noexcept
480 - 
        : obj_(std::move(obj))
915 + 
        : obj_(std::move(other))
481   
    {
916   
    {
482   
    }
917   
    }
483  
918  
484 - 
    /// Overload
919 + 
    /** Construct an @ref object.
 
920 +
 
921 + 
        The value is copy constructed from `other`,
 
922 + 
        using the specified memory resource.
 
923 +
 
924 + 
        @par Complexity
 
925 + 
        Linear in `other.size()`.
 
926 +
 
927 + 
        @par Exception Safety
 
928 + 
        Strong guarantee.
 
929 + 
        Calls to `memory_resource::allocate` may throw.
 
930 +
 
931 + 
        @param other The object to construct with.
 
932 +
 
933 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
934 + 
        use. The container will acquire shared ownership of the memory
 
935 + 
        resource.
 
936 + 
    */
485   
    value(
937   
    value(
486 - 
        object const& obj,
938 + 
        object const& other,
487   
        storage_ptr sp)
939   
        storage_ptr sp)
488 - 
        : obj_( obj, std::move(sp) )
940 + 
        : obj_(
 
941 + 
            other,
 
942 + 
            std::move(sp))
489   
    {
943   
    {
490   
    }
944   
    }
491  
945  
492 - 
    /// Overload
946 + 
    /** Construct an @ref object.
 
947 +
 
948 + 
        The value is move constructed from `other`,
 
949 + 
        using the specified memory resource.
 
950 +
 
951 + 
        @par Complexity
 
952 + 
        Constant or linear in `other.size()`.
 
953 +
 
954 + 
        @par Exception Safety
 
955 + 
        Strong guarantee.
 
956 + 
        Calls to `memory_resource::allocate` may throw.
 
957 +
 
958 + 
        @param other The object to construct with.
 
959 +
 
960 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
961 + 
        use. The container will acquire shared ownership of the memory
 
962 + 
        resource.
 
963 + 
    */
493   
    value(
964   
    value(
494 - 
        object&& obj,
965 + 
        object&& other,
495   
        storage_ptr sp)
966   
        storage_ptr sp)
496 - 
        : obj_( std::move(obj), std::move(sp) )
967 + 
        : obj_(
 
968 + 
            std::move(other),
 
969 + 
            std::move(sp))
497   
    {
970   
    {
498   
    }
971   
    }
499  
972  
500 - 
    /// Overload
973 + 
    /** Construct an @ref object.
 
974 +
 
975 + 
        This is the fastest way to construct
 
976 + 
        an empty object, using the specified
 
977 + 
        memory resource. The variable @ref object_kind
 
978 + 
        may be passed as the first parameter
 
979 + 
        to select this overload:
 
980 +
 
981 + 
        @par Example
 
982 + 
        @code
 
983 + 
        // Construct an empty object
 
984 +
 
985 + 
        value jv( object_kind );
 
986 + 
        @endcode
 
987 +
 
988 + 
        @par Complexity
 
989 + 
        Constant.
 
990 +
 
991 + 
        @par Exception Safety
 
992 + 
        No-throw guarantee.
 
993 +
 
994 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
995 + 
        use. The container will acquire shared ownership of the memory
 
996 + 
        resource.
 
997 +
 
998 + 
        @see @ref object_kind
 
999 + 
    */
501   
    value(
1000   
    value(
502   
        object_kind_t,
1001   
        object_kind_t,
503   
        storage_ptr sp = {}) noexcept
1002   
        storage_ptr sp = {}) noexcept
504   
        : obj_(std::move(sp))
1003   
        : obj_(std::move(sp))
505   
    {
1004   
    {
506   
    }
1005   
    }
507  
1006  
508 - 
    /** Overload
1007 + 
    /** Construct from an initializer-list
509  
1008  
510 - 
        @param init The initializer list to construct from.
1009 + 
        @li If the initializer list consists of key/value
511 - 
        @param sp
1010 + 
        pairs, an @ref object is created; otherwise,
512 - 
    */
 
513 - 
    BOOST_JSON_DECL
 
514 - 
    value(
 
515 - 
        std::initializer_list<value_ref> init,
 
516 - 
        storage_ptr sp = {});
 
517  
1011  
518 - 
    /** Overload
1012 + 
        @li if the size of the initializer list is exactly 1, the object is
 
1013 + 
        constructed directly from that sole element; otherwise,
519  
1014  
520 - 
        @param other Another `value`.
1015 + 
        @li an @ref array is created.
521 - 
    */
 
522 - 
    value(value const& other)
 
523 - 
        : value(other, other.storage())
 
524 - 
    {
 
525 - 
    }
 
526  
1016  
527 - 
    /// Overload
1017 + 
        The contents of the initializer list are copied to the newly
528 - 
    BOOST_JSON_DECL
1018 + 
        constructed value using the specified memory resource.
529 - 
    value(
 
530 - 
        value const& other,
 
531 - 
        storage_ptr sp);
 
532  
1019  
533 - 
    /// Overload
1020 + 
        @par Complexity
534 - 
    BOOST_JSON_DECL
1021 + 
        Linear in `init.size()`.
535 - 
    value(value&& other) noexcept;
 
536  
1022  
537 - 
    /// Overload
1023 + 
        @par Exception Safety
 
1024 + 
        Strong guarantee.
 
1025 + 
        Calls to `memory_resource::allocate` may throw.
 
1026 +
 
1027 + 
        @param init The initializer list to construct from.
 
1028 +
 
1029 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
1030 + 
        use. The container will acquire shared ownership of the memory
 
1031 + 
        resource.
 
1032 + 
    */
538   
    BOOST_JSON_DECL
1033   
    BOOST_JSON_DECL
539   
    value(
1034   
    value(
540 - 
        value&& other,
1035 + 
        std::initializer_list<value_ref> init,
541 - 
        storage_ptr sp);
1036 + 
        storage_ptr sp = {});
542 -
 
543 - 
    /// Overload
 
544 - 
    value(pilfered<value> other) noexcept
 
545 - 
    {
 
546 - 
        relocate(this, other.get());
 
547 - 
        ::new(&other.get().sca_) scalar();
 
548 - 
    }
 
549 - 
    /// @}
 
550  
1037  
551   
    //------------------------------------------------------
1038   
    //------------------------------------------------------
552   
    //
1039   
    //
553   
    // Assignment
1040   
    // Assignment
554   
    //
1041   
    //
555   
    //------------------------------------------------------
1042   
    //------------------------------------------------------
556  
1043  
557 - 
    /** Assignment.
1044 + 
    /** Copy assignment.
558 -
 
559 - 
        Replaces the contents of this value.
 
560 -
 
561 - 
        @li **(1)** replaces with an element-wise copy of the contents of
 
562 - 
            `other`.
 
563 - 
        @li **(2)** replaces with the contents `other` using move semantics
 
564 - 
            (see below).
 
565 - 
        @li **(3)** replaces with the value formed by constructing from `init`
 
566 - 
            and `this->storage()` (see \<\<initializer_lists\>\>).
 
567 - 
        @li **(4)** replaces with null.
 
568 - 
        @li **(5)** replaces with the boolean value `b`.
 
569 - 
        @li **(6)**--**(10)** replaces with the signed integer `i`.
 
570 - 
        @li **(11)**--**(15)** replaces with the unsigned integer `u`.
 
571 - 
        @li **(16)** replaces with the number `d`.
 
572 - 
        @li **(17)**, **(19)** replaces with a copy of the string `s`.
 
573 - 
        @li **(18)**, equivalent to `*this = string_view(s)`.
 
574 - 
        @li **(20)** replaces with the string `s` using move semantics
 
575 - 
            see below.
 
576 - 
        @li **(21)** replaces with a copy of the array `arr`.
 
577 - 
        @li **(22)** replaces with the array `arr` using move semantics
 
578 - 
            (see below).
 
579 - 
        @li **(23)** replaces with a copy of the object `obj`.
 
580 - 
        @li **(24)** replaces with the object `obj` using move semantics
 
581 - 
            (see below).
 
582  
1045  
583 - 
        Move assignment for `value` never changes the associated memory
1046 + 
        The contents of the value are replaced with an
584 - 
        resource. Because of this if the memory resource of the assigned value
1047 + 
        element-wise copy of the contents of `other`.
585 - 
        differs from that of `*this`, the operation is equivalent to a copy.
 
586 - 
        Otherwise, it replaces the underlying storage in constant time without
 
587 - 
        the possibility of exceptions.
 
588  
1048  
589   
        @par Complexity
1049   
        @par Complexity
590 - 
        @li **(1)** linear in the sizes of `*this` and `other`.
1050 + 
        Linear in the size of `*this` plus `other`.
591 - 
        @li **(2)** constant if `*this->storage() == *other.storage()`,
 
592 - 
            otherwise linear in the sizes of `*this` and `other`.
 
593 - 
        @li **(3)** linear in the sizes of `*this` and `init`.
 
594 - 
        @li **(4)**--**(16)** linear in the size of `*this`.
 
595 - 
        @li **(17)**, **(19)** linear in the size of `*this` and `s.size()`.
 
596 - 
        @li **(18)** linear in the size of `*this` and `std::strlen(s)`.
 
597 - 
        @li **(22)** constant if `*this->storage() == *s.storage()`,
 
598 - 
            otherwise linear in the size of `*this` and `s.size()`.
 
599 - 
        @li **(21)** linear in the size of `*this` and `arr.size()`.
 
600 - 
        @li **(22)** constant if `*this->storage() == *arr.storage()`,
 
601 - 
            otherwise linear in the size of `*this` and `arr.size()`.
 
602 - 
        @li **(23)** linear in the size of `*this` and `obj.size()`.
 
603 - 
        @li **(24)** constant if `*this->storage() == *obj.storage()`,
 
604 - 
            otherwise linear in the size of `*this` and `obj.size()`.
 
605 -
 
606 - 
        The size of `*this` is either the size of the underlying container
 
607 - 
        (if there is one), or can be considered to be 1.
 
608  
1051  
609   
        @par Exception Safety
1052   
        @par Exception Safety
610 - 
        @li **(1)**--**(3)**, **(17)**--**(24)** strong guarantee.
1053 + 
        Strong guarantee.
611 - 
        @li **(4)**--**(16)** no-throw guarantee.
 
612 -
 
613   
        Calls to `memory_resource::allocate` may throw.
1054   
        Calls to `memory_resource::allocate` may throw.
614  
1055  
615 - 
        @param other The source value.
1056 + 
        @param other The value to copy.
616 -
 
617 - 
        @{
 
618   
    */
1057   
    */
619   
    BOOST_JSON_DECL
1058   
    BOOST_JSON_DECL
620   
    value&
1059   
    value&
621   
    operator=(value const& other);
1060   
    operator=(value const& other);
622  
1061  
623 - 
    /** Overload
1062 + 
    /** Move assignment.
624  
1063  
625   
        The contents of the value are replaced with the
1064   
        The contents of the value are replaced with the
626   
        contents of `other` using move semantics:
1065   
        contents of `other` using move semantics:
627  
1066  
628   
        @li If `*other.storage() == *sp`, ownership of
1067   
        @li If `*other.storage() == *sp`, ownership of
629   
        the underlying memory is transferred in constant
1068   
        the underlying memory is transferred in constant
630   
        time, with no possibility of exceptions.
1069   
        time, with no possibility of exceptions.
631   
        After assignment, the moved-from value becomes
1070   
        After assignment, the moved-from value becomes
632   
        a null with its current storage pointer.
1071   
        a null with its current storage pointer.
633  
1072  
634   
        @li If `*other.storage() != *sp`, an
1073   
        @li If `*other.storage() != *sp`, an
635   
        element-wise copy is performed if
1074   
        element-wise copy is performed if
636   
        `other.is_structured() == true`, which may throw.
1075   
        `other.is_structured() == true`, which may throw.
637   
        In this case, the moved-from value is not
1076   
        In this case, the moved-from value is not
638   
        changed.
1077   
        changed.
 
1078 +
 
1079 + 
        @par Complexity
 
1080 + 
        Constant, or linear in
 
1081 + 
        `this->size()` plus `other.size()`.
 
1082 +
 
1083 + 
        @par Exception Safety
 
1084 + 
        Strong guarantee.
 
1085 + 
        Calls to `memory_resource::allocate` may throw.
 
1086 +
 
1087 + 
        @param other The value to assign from.
639   
    */
1088   
    */
640   
    BOOST_JSON_DECL
1089   
    BOOST_JSON_DECL
641   
    value&
1090   
    value&
642   
    operator=(value&& other);
1091   
    operator=(value&& other);
643  
1092  
644 - 
    /** Overload
1093 + 
    /** Assignment.
 
1094 +
 
1095 + 
        Replace `*this` with the value formed by
 
1096 + 
        constructing from `init` and `this->storage()`.
 
1097 + 
        If the initializer list consists of key/value
 
1098 + 
        pairs, the resulting @ref object is assigned.
 
1099 + 
        Otherwise an @ref array is assigned. The contents
 
1100 + 
        of the initializer list are moved to `*this`
 
1101 + 
        using the existing memory resource.
 
1102 +
 
1103 + 
        @par Complexity
 
1104 + 
        Linear in `init.size()`.
 
1105 +
 
1106 + 
        @par Exception Safety
 
1107 + 
        Strong guarantee.
 
1108 + 
        Calls to `memory_resource::allocate` may throw.
645  
1109  
646   
        @param init The initializer list to assign from.
1110   
        @param init The initializer list to assign from.
647   
    */
1111   
    */
648   
    BOOST_JSON_DECL
1112   
    BOOST_JSON_DECL
649   
    value&
1113   
    value&
650   
    operator=(
1114   
    operator=(
651   
        std::initializer_list<value_ref> init);
1115   
        std::initializer_list<value_ref> init);
652  
1116  
653 - 
    /// Overload
1117 + 
    /** Assignment.
 
1118 +
 
1119 + 
        Replace `*this` with null.
 
1120 +
 
1121 + 
        @par Exception Safety
 
1122 + 
        No-throw guarantee.
 
1123 +
 
1124 + 
        @par Complexity
 
1125 + 
        Linear in the size of `*this`.
 
1126 + 
    */
654   
    value&
1127   
    value&
655   
    operator=(std::nullptr_t) noexcept
1128   
    operator=(std::nullptr_t) noexcept
656   
    {
1129   
    {
657   
        if(is_scalar())
1130   
        if(is_scalar())
658   
        {
1131   
        {
659   
            sca_.k = json::kind::null;
1132   
            sca_.k = json::kind::null;
660   
        }
1133   
        }
661   
        else
1134   
        else
662   
        {
1135   
        {
663   
            ::new(&sca_) scalar(
1136   
            ::new(&sca_) scalar(
664   
                destroy());
1137   
                destroy());
665   
        }
1138   
        }
666   
        return *this;
1139   
        return *this;
667   
    }
1140   
    }
668  
1141  
669 - 
    /** Overload
1142 + 
    /** Assignment.
 
1143 +
 
1144 + 
        Replace `*this` with `b`.
 
1145 +
 
1146 + 
        @par Exception Safety
 
1147 + 
        No-throw guarantee.
 
1148 +
 
1149 + 
        @par Complexity
 
1150 + 
        Linear in the size of `*this`.
670  
1151  
671   
        @param b The new value.
1152   
        @param b The new value.
672   
    */
1153   
    */
673   
#ifdef BOOST_JSON_DOCS
1154   
#ifdef BOOST_JSON_DOCS
674   
    value& operator=(bool b) noexcept;
1155   
    value& operator=(bool b) noexcept;
675   
#else
1156   
#else
676   
    template<class T
1157   
    template<class T
677   
        ,class = typename std::enable_if<
1158   
        ,class = typename std::enable_if<
678   
            std::is_same<T, bool>::value>::type
1159   
            std::is_same<T, bool>::value>::type
679   
    >
1160   
    >
680   
    value& operator=(T b) noexcept
1161   
    value& operator=(T b) noexcept
681   
    {
1162   
    {
682   
        if(is_scalar())
1163   
        if(is_scalar())
683   
        {
1164   
        {
684   
            sca_.b = b;
1165   
            sca_.b = b;
685   
            sca_.k = json::kind::bool_;
1166   
            sca_.k = json::kind::bool_;
686   
        }
1167   
        }
687   
        else
1168   
        else
688   
        {
1169   
        {
689   
            ::new(&sca_) scalar(
1170   
            ::new(&sca_) scalar(
690   
                b, destroy());
1171   
                b, destroy());
691   
        }
1172   
        }
692   
        return *this;
1173   
        return *this;
693   
    }
1174   
    }
694   
#endif
1175   
#endif
695  
1176  
696 - 
    /** Overload
1177 + 
    /** Assignment.
 
1178 +
 
1179 + 
        Replace `*this` with `i`.
 
1180 +
 
1181 + 
        @par Exception Safety
 
1182 + 
        No-throw guarantee.
 
1183 +
 
1184 + 
        @par Complexity
 
1185 + 
        Linear in the size of `*this`.
697  
1186  
698   
        @param i The new value.
1187   
        @param i The new value.
699   
    */
1188   
    */
 
1189 + 
    /** @{ */
700   
    value& operator=(signed char i) noexcept
1190   
    value& operator=(signed char i) noexcept
701   
    {
1191   
    {
702   
        return operator=(
1192   
        return operator=(
703   
            static_cast<long long>(i));
1193   
            static_cast<long long>(i));
704   
    }
1194   
    }
705 - 
    /// Overload
 
706  
1195  
707   
    value& operator=(short i) noexcept
1196   
    value& operator=(short i) noexcept
708   
    {
1197   
    {
709   
        return operator=(
1198   
        return operator=(
710   
            static_cast<long long>(i));
1199   
            static_cast<long long>(i));
711   
    }
1200   
    }
712 - 
    /// Overload
 
713  
1201  
714   
    value& operator=(int i) noexcept
1202   
    value& operator=(int i) noexcept
715   
    {
1203   
    {
716   
        return operator=(
1204   
        return operator=(
717   
            static_cast<long long>(i));
1205   
            static_cast<long long>(i));
718   
    }
1206   
    }
719 - 
    /// Overload
 
720  
1207  
721   
    value& operator=(long i) noexcept
1208   
    value& operator=(long i) noexcept
722   
    {
1209   
    {
723   
        return operator=(
1210   
        return operator=(
724   
            static_cast<long long>(i));
1211   
            static_cast<long long>(i));
725   
    }
1212   
    }
726 - 
    /// Overload
 
727  
1213  
728   
    value& operator=(long long i) noexcept
1214   
    value& operator=(long long i) noexcept
729   
    {
1215   
    {
730   
        if(is_scalar())
1216   
        if(is_scalar())
731   
        {
1217   
        {
732   
            sca_.i = i;
1218   
            sca_.i = i;
733   
            sca_.k = json::kind::int64;
1219   
            sca_.k = json::kind::int64;
734   
        }
1220   
        }
735   
        else
1221   
        else
736   
        {
1222   
        {
737   
            ::new(&sca_) scalar(static_cast<
1223   
            ::new(&sca_) scalar(static_cast<
738   
                std::int64_t>(i), destroy());
1224   
                std::int64_t>(i), destroy());
739   
        }
1225   
        }
740   
        return *this;
1226   
        return *this;
741   
    }
1227   
    }
 
1228 + 
    /** @} */
742  
1229  
743 - 
    /** Overload
1230 + 
    /** Assignment.
 
1231 +
 
1232 + 
        Replace `*this` with `i`.
 
1233 +
 
1234 + 
        @par Exception Safety
 
1235 + 
        No-throw guarantee.
 
1236 +
 
1237 + 
        @par Complexity
 
1238 + 
        Linear in the size of `*this`.
744  
1239  
745   
        @param u The new value.
1240   
        @param u The new value.
746   
    */
1241   
    */
 
1242 + 
    /** @{ */
747   
    value& operator=(unsigned char u) noexcept
1243   
    value& operator=(unsigned char u) noexcept
748   
    {
1244   
    {
749   
        return operator=(static_cast<
1245   
        return operator=(static_cast<
750   
            unsigned long long>(u));
1246   
            unsigned long long>(u));
751   
    }
1247   
    }
752 - 
    /// Overload
 
753  
1248  
754   
    value& operator=(unsigned short u) noexcept
1249   
    value& operator=(unsigned short u) noexcept
755   
    {
1250   
    {
756   
        return operator=(static_cast<
1251   
        return operator=(static_cast<
757   
            unsigned long long>(u));
1252   
            unsigned long long>(u));
758   
    }
1253   
    }
759 - 
    /// Overload
 
760  
1254  
761   
    value& operator=(unsigned int u) noexcept
1255   
    value& operator=(unsigned int u) noexcept
762   
    {
1256   
    {
763   
        return operator=(static_cast<
1257   
        return operator=(static_cast<
764   
            unsigned long long>(u));
1258   
            unsigned long long>(u));
765   
    }
1259   
    }
766 - 
    /// Overload
 
767  
1260  
768   
    value& operator=(unsigned long u) noexcept
1261   
    value& operator=(unsigned long u) noexcept
769   
    {
1262   
    {
770   
        return operator=(static_cast<
1263   
        return operator=(static_cast<
771   
            unsigned long long>(u));
1264   
            unsigned long long>(u));
772   
    }
1265   
    }
773 - 
    /// Overload
 
774  
1266  
775   
    value& operator=(unsigned long long u) noexcept
1267   
    value& operator=(unsigned long long u) noexcept
776   
    {
1268   
    {
777   
        if(is_scalar())
1269   
        if(is_scalar())
778   
        {
1270   
        {
779   
            sca_.u = u;
1271   
            sca_.u = u;
780   
            sca_.k = json::kind::uint64;
1272   
            sca_.k = json::kind::uint64;
781   
        }
1273   
        }
782   
        else
1274   
        else
783   
        {
1275   
        {
784   
            ::new(&sca_) scalar(static_cast<
1276   
            ::new(&sca_) scalar(static_cast<
785   
                std::uint64_t>(u), destroy());
1277   
                std::uint64_t>(u), destroy());
786   
        }
1278   
        }
787   
        return *this;
1279   
        return *this;
788   
    }
1280   
    }
 
1281 + 
    /** @} */
789  
1282  
790 - 
    /** Overload
1283 + 
    /** Assignment.
 
1284 +
 
1285 + 
        Replace `*this` with `d`.
 
1286 +
 
1287 + 
        @par Exception Safety
 
1288 + 
        No-throw guarantee.
 
1289 +
 
1290 + 
        @par Complexity
 
1291 + 
        Linear in the size of `*this`.
791  
1292  
792   
        @param d The new value.
1293   
        @param d The new value.
793   
    */
1294   
    */
794   
    value& operator=(double d) noexcept
1295   
    value& operator=(double d) noexcept
795   
    {
1296   
    {
796   
        if(is_scalar())
1297   
        if(is_scalar())
797   
        {
1298   
        {
798   
            sca_.d = d;
1299   
            sca_.d = d;
799   
            sca_.k = json::kind::double_;
1300   
            sca_.k = json::kind::double_;
800   
        }
1301   
        }
801   
        else
1302   
        else
802   
        {
1303   
        {
803   
            ::new(&sca_) scalar(
1304   
            ::new(&sca_) scalar(
804   
                d, destroy());
1305   
                d, destroy());
805   
        }
1306   
        }
806   
        return *this;
1307   
        return *this;
807   
    }
1308   
    }
808  
1309  
809 - 
    /** Overload
1310 + 
    /** Assignment.
810  
1311  
811 - 
        @param s The new string.
1312 + 
        Replace `*this` with a copy of the string `s`.
812 - 
    */
 
813 - 
    BOOST_JSON_DECL
 
814 - 
    value& operator=(string_view s);
 
815  
1313  
816 - 
    /// Overload
1314 + 
        @par Exception Safety
817 - 
    BOOST_JSON_DECL
1315 + 
        Strong guarantee.
818 - 
    value& operator=(char const* s);
1316 + 
        Calls to `memory_resource::allocate` may throw.
819  
1317  
820 - 
    /// Overload
1318 + 
        @par Complexity
821 - 
    BOOST_JSON_DECL
1319 + 
        Linear in the sum of sizes of `*this` and `s`
822 - 
    value& operator=(string const& s);
 
823  
1320  
824 - 
    /** Overload
1321 + 
        @param s The new string.
 
1322 + 
    */
 
1323 + 
    /** @{ */
 
1324 + 
    BOOST_JSON_DECL value& operator=(string_view s);
 
1325 + 
    BOOST_JSON_DECL value& operator=(char const* s);
 
1326 + 
    BOOST_JSON_DECL value& operator=(string const& s);
 
1327 + 
    /** @} */
 
1328 +
 
1329 + 
    /** Assignment.
825  
1330  
826   
        The contents of the value are replaced with the
1331   
        The contents of the value are replaced with the
827   
        contents of `s` using move semantics:
1332   
        contents of `s` using move semantics:
828  
1333  
829   
        @li If `*other.storage() == *this->storage()`,
1334   
        @li If `*other.storage() == *this->storage()`,
830   
        ownership of the underlying memory is transferred
1335   
        ownership of the underlying memory is transferred
831   
        in constant time, with no possibility of exceptions.
1336   
        in constant time, with no possibility of exceptions.
832   
        After assignment, the moved-from string becomes
1337   
        After assignment, the moved-from string becomes
833   
        empty with its current storage pointer.
1338   
        empty with its current storage pointer.
834  
1339  
835   
        @li If `*other.storage() != *this->storage()`, an
1340   
        @li If `*other.storage() != *this->storage()`, an
836   
        element-wise copy is performed, which may throw.
1341   
        element-wise copy is performed, which may throw.
837   
        In this case, the moved-from string is not
1342   
        In this case, the moved-from string is not
838   
        changed.
1343   
        changed.
839  
1344  
 
1345 + 
        @par Complexity
 
1346 + 
        Constant, or linear in the size of `*this` plus `s.size()`.
 
1347 +
 
1348 + 
        @par Exception Safety
 
1349 + 
        Strong guarantee.
 
1350 + 
        Calls to `memory_resource::allocate` may throw.
 
1351 +
840   
        @param s The string to move-assign from.
1352   
        @param s The string to move-assign from.
841   
    */
1353   
    */
842 - 
    BOOST_JSON_DECL
1354 + 
    BOOST_JSON_DECL value& operator=(string&& s);
843 - 
    value& operator=(string&& s);
 
844  
1355  
845 - 
    /** Overload
1356 + 
    /** Assignment.
846  
1357  
847   
        Replace `*this` with a copy of the array `arr`.
1358   
        Replace `*this` with a copy of the array `arr`.
848  
1359  
849   
        @par Exception Safety
1360   
        @par Exception Safety
850   
        Strong guarantee.
1361   
        Strong guarantee.
851   
        Calls to `memory_resource::allocate` may throw.
1362   
        Calls to `memory_resource::allocate` may throw.
852  
1363  
853   
        @par Complexity
1364   
        @par Complexity
854   
        Linear in the sum of sizes of `*this` and `arr`
1365   
        Linear in the sum of sizes of `*this` and `arr`
855  
1366  
856   
        @param arr The new array.
1367   
        @param arr The new array.
857   
    */
1368   
    */
858 - 
    BOOST_JSON_DECL
1369 + 
    BOOST_JSON_DECL value& operator=(array const& arr);
859 - 
    value& operator=(array const& arr);
 
860  
1370  
861 - 
    /** Overload
1371 + 
    /** Assignment.
862  
1372  
863   
        The contents of the value are replaced with the
1373   
        The contents of the value are replaced with the
864   
        contents of `arr` using move semantics:
1374   
        contents of `arr` using move semantics:
865  
1375  
866   
        @li If `*arr.storage() == *this->storage()`,
1376   
        @li If `*arr.storage() == *this->storage()`,
867   
        ownership of the underlying memory is transferred
1377   
        ownership of the underlying memory is transferred
868   
        in constant time, with no possibility of exceptions.
1378   
        in constant time, with no possibility of exceptions.
869   
        After assignment, the moved-from array becomes
1379   
        After assignment, the moved-from array becomes
870   
        empty with its current storage pointer.
1380   
        empty with its current storage pointer.
871  
1381  
872   
        @li If `*arr.storage() != *this->storage()`, an
1382   
        @li If `*arr.storage() != *this->storage()`, an
873   
        element-wise copy is performed, which may throw.
1383   
        element-wise copy is performed, which may throw.
874   
        In this case, the moved-from array is not
1384   
        In this case, the moved-from array is not
875   
        changed.
1385   
        changed.
876  
1386  
877   
        @par Complexity
1387   
        @par Complexity
878   
        Constant, or linear in the size of `*this` plus `arr.size()`.
1388   
        Constant, or linear in the size of `*this` plus `arr.size()`.
879  
1389  
880   
        @par Exception Safety
1390   
        @par Exception Safety
881   
        Strong guarantee.
1391   
        Strong guarantee.
882   
        Calls to `memory_resource::allocate` may throw.
1392   
        Calls to `memory_resource::allocate` may throw.
883  
1393  
884   
        @param arr The array to move-assign from.
1394   
        @param arr The array to move-assign from.
885   
    */
1395   
    */
886 - 
    BOOST_JSON_DECL
1396 + 
    BOOST_JSON_DECL value& operator=(array&& arr);
887 - 
    value& operator=(array&& arr);
 
888  
1397  
889 - 
    /** Overload
1398 + 
    /** Assignment.
890  
1399  
891   
        Replace `*this` with a copy of the obect `obj`.
1400   
        Replace `*this` with a copy of the obect `obj`.
892  
1401  
893   
        @par Exception Safety
1402   
        @par Exception Safety
894   
        Strong guarantee.
1403   
        Strong guarantee.
895   
        Calls to `memory_resource::allocate` may throw.
1404   
        Calls to `memory_resource::allocate` may throw.
896  
1405  
897   
        @par Complexity
1406   
        @par Complexity
898   
        Linear in the sum of sizes of `*this` and `obj`
1407   
        Linear in the sum of sizes of `*this` and `obj`
899  
1408  
900   
        @param obj The new object.
1409   
        @param obj The new object.
901   
    */
1410   
    */
902 - 
    BOOST_JSON_DECL
1411 + 
    BOOST_JSON_DECL value& operator=(object const& obj);
903 - 
    value& operator=(object const& obj);
 
904  
1412  
905 - 
    /** Overload
1413 + 
    /** Assignment.
906  
1414  
907   
        The contents of the value are replaced with the
1415   
        The contents of the value are replaced with the
908   
        contents of `obj` using move semantics:
1416   
        contents of `obj` using move semantics:
909  
1417  
910   
        @li If `*obj.storage() == *this->storage()`,
1418   
        @li If `*obj.storage() == *this->storage()`,
911   
        ownership of the underlying memory is transferred
1419   
        ownership of the underlying memory is transferred
912   
        in constant time, with no possibility of exceptions.
1420   
        in constant time, with no possibility of exceptions.
913   
        After assignment, the moved-from object becomes
1421   
        After assignment, the moved-from object becomes
914   
        empty with its current storage pointer.
1422   
        empty with its current storage pointer.
915  
1423  
916   
        @li If `*obj.storage() != *this->storage()`, an
1424   
        @li If `*obj.storage() != *this->storage()`, an
917   
        element-wise copy is performed, which may throw.
1425   
        element-wise copy is performed, which may throw.
918   
        In this case, the moved-from object is not
1426   
        In this case, the moved-from object is not
919   
        changed.
1427   
        changed.
920  
1428  
921   
        @par Complexity
1429   
        @par Complexity
922   
        Constant, or linear in the size of `*this` plus `obj.size()`.
1430   
        Constant, or linear in the size of `*this` plus `obj.size()`.
923  
1431  
924   
        @par Exception Safety
1432   
        @par Exception Safety
925   
        Strong guarantee.
1433   
        Strong guarantee.
926   
        Calls to `memory_resource::allocate` may throw.
1434   
        Calls to `memory_resource::allocate` may throw.
927  
1435  
928   
        @param obj The object to move-assign from.
1436   
        @param obj The object to move-assign from.
929   
    */
1437   
    */
930 - 
    BOOST_JSON_DECL
1438 + 
    BOOST_JSON_DECL value& operator=(object&& obj);
931 - 
    value& operator=(object&& obj);
 
932 - 
    /// @}
 
933  
1439  
934   
    //------------------------------------------------------
1440   
    //------------------------------------------------------
935   
    //
1441   
    //
936   
    // Modifiers
1442   
    // Modifiers
937   
    //
1443   
    //
938   
    //------------------------------------------------------
1444   
    //------------------------------------------------------
939  
1445  
940 - 
    /** Replace with a null value.
1446 + 
    /** Change the kind to null, discarding the previous contents.
941  
1447  
942 - 
        The current value is destroyed and the kind is changed to kind::null.
1448 + 
        The value is replaced with a null,
943 - 
        The associated memeory resource is kept unchanged.
1449 + 
        destroying the previous contents.
944  
1450  
945   
        @par Complexity
1451   
        @par Complexity
946   
        Linear in the size of `*this`.
1452   
        Linear in the size of `*this`.
947  
1453  
948   
        @par Exception Safety
1454   
        @par Exception Safety
949   
        No-throw guarantee.
1455   
        No-throw guarantee.
950   
    */
1456   
    */
951   
    void
1457   
    void
952   
    emplace_null() noexcept
1458   
    emplace_null() noexcept
953   
    {
1459   
    {
954   
        *this = nullptr;
1460   
        *this = nullptr;
955   
    }
1461   
    }
956  
1462  
957 - 
    /** Replace with a `bool` value.
1463 + 
    /** Return a reference to a `bool`, changing the kind and replacing the contents.
958  
1464  
959 - 
        The value is replaced with a `bool` initialized to `false`, destroying
1465 + 
        The value is replaced with a `bool`
960 - 
        the previous contents, but keeping the memeory resource.
1466 + 
        initialized to `false`, destroying the
 
1467 + 
        previous contents.
961  
1468  
962   
        @par Complexity
1469   
        @par Complexity
963   
        Linear in the size of `*this`.
1470   
        Linear in the size of `*this`.
964  
1471  
965   
        @par Exception Safety
1472   
        @par Exception Safety
966 -
 
967 - 
        @return `this->get_bool()`.
 
968   
        No-throw guarantee.
1473   
        No-throw guarantee.
969   
    */
1474   
    */
970   
    bool&
1475   
    bool&
971   
    emplace_bool() noexcept
1476   
    emplace_bool() noexcept
972   
    {
1477   
    {
973   
        *this = false;
1478   
        *this = false;
974   
        return sca_.b;
1479   
        return sca_.b;
975   
    }
1480   
    }
976  
1481  
977 - 
    /** Replace with a `std::int64_t` value.
1482 + 
    /** Return a reference to a `std::int64_t`, changing the kind and replacing the contents.
978  
1483  
979 - 
        The value is replaced with a `std::int64_t` initialized to zero,
1484 + 
        The value is replaced with a `std::int64_t`
980 - 
        destroying the previous contents, but keeping the memeory resource.
1485 + 
        initialized to zero, destroying the
 
1486 + 
        previous contents.
981  
1487  
982   
        @par Complexity
1488   
        @par Complexity
983   
        Linear in the size of `*this`.
1489   
        Linear in the size of `*this`.
984  
1490  
985   
        @par Exception Safety
1491   
        @par Exception Safety
986 -
 
987 - 
        @return `this->get_int64()`.
 
988   
        No-throw guarantee.
1492   
        No-throw guarantee.
989   
    */
1493   
    */
990   
    std::int64_t&
1494   
    std::int64_t&
991   
    emplace_int64() noexcept
1495   
    emplace_int64() noexcept
992   
    {
1496   
    {
993   
        *this = std::int64_t{};
1497   
        *this = std::int64_t{};
994   
        return sca_.i;
1498   
        return sca_.i;
995   
    }
1499   
    }
996  
1500  
997 - 
    /** Replace with a `std::uint64_t` value.
1501 + 
    /** Return a reference to a `std::uint64_t`, changing the kind and replacing the contents.
998  
1502  
999 - 
        The value is replaced with a `std::uint64_t` initialized to zero,
1503 + 
        The value is replaced with a `std::uint64_t`
1000 - 
        destroying the the previous contents, but keeping the memeory resource.
1504 + 
        initialized to zero, destroying the
 
1505 + 
        previous contents.
1001  
1506  
1002   
        @par Complexity
1507   
        @par Complexity
1003   
        Linear in the size of `*this`.
1508   
        Linear in the size of `*this`.
1004  
1509  
1005   
        @par Exception Safety
1510   
        @par Exception Safety
1006 -
 
1007 - 
        @return `this->get_uint64()`.
 
1008   
        No-throw guarantee.
1511   
        No-throw guarantee.
1009   
    */
1512   
    */
1010   
    std::uint64_t&
1513   
    std::uint64_t&
1011   
    emplace_uint64() noexcept
1514   
    emplace_uint64() noexcept
1012   
    {
1515   
    {
1013   
        *this = std::uint64_t{};
1516   
        *this = std::uint64_t{};
1014   
        return sca_.u;
1517   
        return sca_.u;
1015   
    }
1518   
    }
1016  
1519  
1017 - 
    /** Replace with a `double` value.
1520 + 
    /** Return a reference to a `double`, changing the kind and replacing the contents.
1018  
1521  
1019 - 
        The value is replaced with a `double` initialized to zero, destroying
1522 + 
        The value is replaced with a `double`
1020 - 
        the previous contents, but keeping the memeory resource.
1523 + 
        initialized to zero, destroying the
 
1524 + 
        previous contents.
1021  
1525  
1022   
        @par Complexity
1526   
        @par Complexity
1023   
        Linear in the size of `*this`.
1527   
        Linear in the size of `*this`.
1024  
1528  
1025   
        @par Exception Safety
1529   
        @par Exception Safety
1026 -
 
1027 - 
        @return `this->get_double()`.
 
1028   
        No-throw guarantee.
1530   
        No-throw guarantee.
1029   
    */
1531   
    */
1030   
    double&
1532   
    double&
1031   
    emplace_double() noexcept
1533   
    emplace_double() noexcept
1032   
    {
1534   
    {
1033   
        *this = double{};
1535   
        *this = double{};
1034   
        return sca_.d;
1536   
        return sca_.d;
1035   
    }
1537   
    }
1036  
1538  
1037 - 
    /** Replace with an empty @ref string.
1539 + 
    /** Return a reference to a @ref string, changing the kind and replacing the contents.
1038  
1540  
1039 - 
        The value is replaced with an empty @ref string using the current
1541 + 
        The value is replaced with an empty @ref string
1040 - 
        memory resource, destroying the previous contents. All previously
1542 + 
        using the current memory resource, destroying the
1041 - 
        obtained iterators and references obtained beforehand are invalidated.
1543 + 
        previous contents.
1042  
1544  
1043   
        @par Complexity
1545   
        @par Complexity
1044   
        Linear in the size of `*this`.
1546   
        Linear in the size of `*this`.
1045  
1547  
1046   
        @par Exception Safety
1548   
        @par Exception Safety
1047 -
 
1048 - 
        @return `this->get_string()`.
 
1049   
        No-throw guarantee.
1549   
        No-throw guarantee.
1050   
    */
1550   
    */
1051   
    BOOST_JSON_DECL
1551   
    BOOST_JSON_DECL
1052   
    string&
1552   
    string&
1053   
    emplace_string() noexcept;
1553   
    emplace_string() noexcept;
1054  
1554  
1055 - 
    /** Replace with an empty array.
1555 + 
    /** Return a reference to an @ref array, changing the kind and replacing the contents.
1056  
1556  
1057 - 
        The value is replaced with an empty @ref array using the current memory
1557 + 
        The value is replaced with an empty @ref array
1058 - 
        resource, destroying the previous contents. All previously obtained
1558 + 
        using the current memory resource, destroying the
1059 - 
        iterators and references obtained beforehand are invalidated.
1559 + 
        previous contents.
1060  
1560  
1061   
        @par Complexity
1561   
        @par Complexity
1062   
        Linear in the size of `*this`.
1562   
        Linear in the size of `*this`.
1063  
1563  
1064   
        @par Exception Safety
1564   
        @par Exception Safety
1065 -
 
1066 - 
        @return `this->get_array()`.
 
1067   
        No-throw guarantee.
1565   
        No-throw guarantee.
1068   
    */
1566   
    */
1069   
    BOOST_JSON_DECL
1567   
    BOOST_JSON_DECL
1070   
    array&
1568   
    array&
1071   
    emplace_array() noexcept;
1569   
    emplace_array() noexcept;
1072  
1570  
1073 - 
    /** Replace with an empty @ref object.
1571 + 
    /** Return a reference to an @ref object, changing the kind and replacing the contents.
1074  
1572  
1075 - 
        The value is replaced with an empty @ref array using the current memory
1573 + 
        The contents are replaced with an empty @ref object using the current
1076 - 
        resource, destroying the previous contents. All previously obtained
1574 + 
        `boost::container::pmr::memory_resource`. All previously obtained
1077   
        iterators and references obtained beforehand are invalidated.
1575   
        iterators and references obtained beforehand are invalidated.
1078  
1576  
1079   
        @par Complexity
1577   
        @par Complexity
1080   
        Linear in the size of `*this`.
1578   
        Linear in the size of `*this`.
1081  
1579  
1082   
        @par Exception Safety
1580   
        @par Exception Safety
1083 -
 
1084 - 
        @return `this->get_object()`.
 
1085   
        No-throw guarantee.
1581   
        No-throw guarantee.
1086   
    */
1582   
    */
1087   
    BOOST_JSON_DECL
1583   
    BOOST_JSON_DECL
1088   
    object&
1584   
    object&
1089   
    emplace_object() noexcept;
1585   
    emplace_object() noexcept;
1090  
1586  
1091   
    /** Swap the given values.
1587   
    /** Swap the given values.
1092  
1588  
1093   
        Exchanges the contents of this value with another value. Ownership of
1589   
        Exchanges the contents of this value with another value. Ownership of
1094 - 
        the respective @ref boost::container::pmr::memory_resource objects is
1590 + 
        the respective `boost::container::pmr::memory_resource` objects is not
1095 - 
        not transferred:
1591 + 
        transferred:
1096  
1592  
1097 - 
        @li If `this == &other`, this function has no effect.
1593 + 
        @li If `*other.storage() == *this->storage()`,
1098 - 
        @li If `*other.storage() == *this->storage()`, ownership of the
1594 + 
        ownership of the underlying memory is swapped in
1099 - 
            underlying memory is swapped in constant time, with no possibility
1595 + 
        constant time, with no possibility of exceptions.
1100 - 
            of exceptions. All iterators and references remain valid.
1596 + 
        All iterators and references remain valid.
1101 - 
        @li If `*other.storage() != *this->storage()`, the contents are
1597 +
1102 - 
            logically swapped by making copies, which can throw. In this case
1598 + 
        @li If `*other.storage() != *this->storage()`,
1103 - 
            all iterators and references are invalidated.
1599 + 
        the contents are logically swapped by making copies,
 
1600 + 
        which can throw. In this case all iterators and
 
1601 + 
        references are invalidated.
1104  
1602  
1105   
        @par Complexity
1603   
        @par Complexity
1106 - 
        Constant or linear in the sum of the sizes of the values.
1604 + 
        Constant or linear in the sum of the sizes of
 
1605 + 
        the values.
1107  
1606  
1108   
        @par Exception Safety
1607   
        @par Exception Safety
1109 - 
        Strong guarantee. Calls to `memory_resource::allocate` may throw.
1608 + 
        Strong guarantee.
 
1609 + 
        Calls to `memory_resource::allocate` may throw.
1110  
1610  
1111   
        @param other The value to swap with.
1611   
        @param other The value to swap with.
 
1612 + 
        If `this == &other`, this function call has no effect.
1112   
    */
1613   
    */
1113   
    BOOST_JSON_DECL
1614   
    BOOST_JSON_DECL
1114   
    void
1615   
    void
1115   
    swap(value& other);
1616   
    swap(value& other);
1116  
1617  
1117   
    /** Swap the given values.
1618   
    /** Swap the given values.
1118  
1619  
1119   
        Exchanges the contents of value `lhs` with another value `rhs`.
1620   
        Exchanges the contents of value `lhs` with another value `rhs`.
1120 - 
        Ownership of the respective @ref boost::container::pmr::memory_resource
1621 + 
        Ownership of the respective `boost::container::pmr::memory_resource`
1121   
        objects is not transferred.
1622   
        objects is not transferred.
1122  
1623  
1123 - 
        @li If `&lhs == &rhs`, this function call has no effect.
1624 + 
        @li If `*lhs.storage() == *rhs.storage()`,
1124 - 
        @li If `*lhs.storage() == *rhs.storage()`, ownership of the underlying
1625 + 
        ownership of the underlying memory is swapped in
1125 - 
            memory is swapped in constant time, with no possibility of
1626 + 
        constant time, with no possibility of exceptions.
1126 - 
            exceptions. All iterators and references remain valid.
1627 + 
        All iterators and references remain valid.
1127 - 
        @li If `*lhs.storage() != *rhs.storage`, the contents are logically
1628 +
1128 - 
            swapped by a copy, which can throw. In this case all iterators and
1629 + 
        @li If `*lhs.storage() != *rhs.storage`,
1129 - 
            references are invalidated.
1630 + 
        the contents are logically swapped by a copy,
 
1631 + 
        which can throw. In this case all iterators and
 
1632 + 
        references are invalidated.
 
1633 +
 
1634 + 
        @par Effects
 
1635 + 
        @code
 
1636 + 
        lhs.swap( rhs );
 
1637 + 
        @endcode
1130  
1638  
1131   
        @par Complexity
1639   
        @par Complexity
1132 - 
        Constant or linear in the sum of the sizes of the values.
1640 + 
        Constant or linear in the sum of the sizes of
 
1641 + 
        the values.
1133  
1642  
1134   
        @par Exception Safety
1643   
        @par Exception Safety
1135 - 
        Strong guarantee. Calls to `memory_resource::allocate` may throw.
1644 + 
        Strong guarantee.
 
1645 + 
        Calls to `memory_resource::allocate` may throw.
1136  
1646  
1137   
        @param lhs The value to exchange.
1647   
        @param lhs The value to exchange.
 
1648 +
1138   
        @param rhs The value to exchange.
1649   
        @param rhs The value to exchange.
 
1650 + 
        If `&lhs == &rhs`, this function call has no effect.
1139  
1651  
1140   
        @see @ref value::swap
1652   
        @see @ref value::swap
1141   
    */
1653   
    */
1142   
    friend
1654   
    friend
1143   
    void
1655   
    void
1144   
    swap(value& lhs, value& rhs)
1656   
    swap(value& lhs, value& rhs)
1145   
    {
1657   
    {
1146   
        lhs.swap(rhs);
1658   
        lhs.swap(rhs);
1147   
    }
1659   
    }
1148  
1660  
1149   
    //------------------------------------------------------
1661   
    //------------------------------------------------------
1150   
    //
1662   
    //
1151   
    // Observers
1663   
    // Observers
1152   
    //
1664   
    //
1153   
    //------------------------------------------------------
1665   
    //------------------------------------------------------
1154  
1666  
1155   
    /** Returns the kind of this JSON value.
1667   
    /** Returns the kind of this JSON value.
1156  
1668  
1157 - 
        This function returns the discriminating enumeration constant of type
1669 + 
        This function returns the discriminating
1158 - 
        @ref json::kind corresponding to the underlying representation stored
1670 + 
        enumeration constant of type @ref json::kind
1159 - 
        in the container.
1671 + 
        corresponding to the underlying representation
 
1672 + 
        stored in the container.
1160  
1673  
1161   
        @par Complexity
1674   
        @par Complexity
1162   
        Constant.
1675   
        Constant.
1163  
1676  
1164   
        @par Exception Safety
1677   
        @par Exception Safety
1165   
        No-throw guarantee.
1678   
        No-throw guarantee.
1166   
    */
1679   
    */
1167   
    json::kind
1680   
    json::kind
1168   
    kind() const noexcept
1681   
    kind() const noexcept
1169   
    {
1682   
    {
1170   
        return static_cast<json::kind>(
1683   
        return static_cast<json::kind>(
1171   
            static_cast<unsigned char>(
1684   
            static_cast<unsigned char>(
1172   
                sca_.k) & 0x3f);
1685   
                sca_.k) & 0x3f);
1173   
    }
1686   
    }
1174  
1687  
1175 - 
    /** Check if this is an @ref array.
1688 + 
    /** Return `true` if this is an array
1176  
1689  
1177 - 
        Returns `true` if the value's @ref kind() is `kind::array`.
1690 + 
        This function is used to determine if the underlying
 
1691 + 
        representation is a certain kind.
1178  
1692  
1179 - 
        @returns `this->kind() == kind::array`.
1693 + 
        @par Effects
 
1694 + 
        @code
 
1695 + 
        return this->kind() == kind::array;
 
1696 + 
        @endcode
1180  
1697  
1181   
        @par Complexity
1698   
        @par Complexity
1182   
        Constant.
1699   
        Constant.
1183  
1700  
1184   
        @par Exception Safety
1701   
        @par Exception Safety
1185   
        No-throw guarantee.
1702   
        No-throw guarantee.
1186   
    */
1703   
    */
1187   
    bool
1704   
    bool
1188   
    is_array() const noexcept
1705   
    is_array() const noexcept
1189   
    {
1706   
    {
1190   
        return kind() == json::kind::array;
1707   
        return kind() == json::kind::array;
1191   
    }
1708   
    }
1192  
1709  
1193 - 
    /** Check if this is an @ref object.
1710 + 
    /** Return `true` if this is an object
1194  
1711  
1195 - 
        Returns `true` if the value's @ref kind() is `kind::object`.
1712 + 
        This function is used to determine if the underlying
 
1713 + 
        representation is a certain kind.
1196  
1714  
1197 - 
        @returns `this->kind() == kind::object`.
1715 + 
        @par Effects
 
1716 + 
        @code
 
1717 + 
        return this->kind() == kind::object;
 
1718 + 
        @endcode
1198  
1719  
1199   
        @par Complexity
1720   
        @par Complexity
1200   
        Constant.
1721   
        Constant.
1201  
1722  
1202   
        @par Exception Safety
1723   
        @par Exception Safety
1203   
        No-throw guarantee.
1724   
        No-throw guarantee.
1204   
    */
1725   
    */
1205   
    bool
1726   
    bool
1206   
    is_object() const noexcept
1727   
    is_object() const noexcept
1207   
    {
1728   
    {
1208   
        return kind() == json::kind::object;
1729   
        return kind() == json::kind::object;
1209   
    }
1730   
    }
1210  
1731  
1211 - 
    /** Check if this is a @ref string.
1732 + 
    /** Return `true` if this is a string
1212  
1733  
1213 - 
        Returns `true` if the value's @ref kind() is `kind::string`.
1734 + 
        This function is used to determine if the underlying
 
1735 + 
        representation is a certain kind.
1214  
1736  
1215 - 
        @returns `this->kind() == kind::string`.
1737 + 
        @par Effects
 
1738 + 
        @code
 
1739 + 
        return this->kind() == kind::string;
 
1740 + 
        @endcode
1216  
1741  
1217   
        @par Complexity
1742   
        @par Complexity
1218   
        Constant.
1743   
        Constant.
1219  
1744  
1220   
        @par Exception Safety
1745   
        @par Exception Safety
1221   
        No-throw guarantee.
1746   
        No-throw guarantee.
1222   
    */
1747   
    */
1223   
    bool
1748   
    bool
1224   
    is_string() const noexcept
1749   
    is_string() const noexcept
1225   
    {
1750   
    {
1226   
        return kind() == json::kind::string;
1751   
        return kind() == json::kind::string;
1227   
    }
1752   
    }
1228  
1753  
1229 - 
    /** Check if this is a `std::int64_t`.
1754 + 
    /** Return `true` if this is a signed integer
1230  
1755  
1231 - 
        Returns `true` if the value's @ref kind() is `kind::int64`.
1756 + 
        This function is used to determine if the underlying
 
1757 + 
        representation is a certain kind.
1232  
1758  
1233 - 
        @returns `this->kind() == kind::int64`.
1759 + 
        @par Effects
 
1760 + 
        @code
 
1761 + 
        return this->kind() == kind::int64;
 
1762 + 
        @endcode
1234  
1763  
1235   
        @par Complexity
1764   
        @par Complexity
1236   
        Constant.
1765   
        Constant.
1237  
1766  
1238   
        @par Exception Safety
1767   
        @par Exception Safety
1239   
        No-throw guarantee.
1768   
        No-throw guarantee.
1240   
    */
1769   
    */
1241   
    bool
1770   
    bool
1242   
    is_int64() const noexcept
1771   
    is_int64() const noexcept
1243   
    {
1772   
    {
1244   
        return kind() == json::kind::int64;
1773   
        return kind() == json::kind::int64;
1245   
    }
1774   
    }
1246  
1775  
1247 - 
    /** Checks if this is a `std::uint64_t`.
1776 + 
    /** Return `true` if this is a unsigned integer
1248  
1777  
1249 - 
        Returns `true` if the value's @ref kind() is `kind::uint64`.
1778 + 
        This function is used to determine if the underlying
 
1779 + 
        representation is a certain kind.
1250  
1780  
1251 - 
        @returns `this->kind() == kind::uint64`.
1781 + 
        @par Effects
 
1782 + 
        @code
 
1783 + 
        return this->kind() == kind::uint64;
 
1784 + 
        @endcode
1252  
1785  
1253   
        @par Complexity
1786   
        @par Complexity
1254   
        Constant.
1787   
        Constant.
1255  
1788  
1256   
        @par Exception Safety
1789   
        @par Exception Safety
1257   
        No-throw guarantee.
1790   
        No-throw guarantee.
1258   
    */
1791   
    */
1259   
    bool
1792   
    bool
1260   
    is_uint64() const noexcept
1793   
    is_uint64() const noexcept
1261   
    {
1794   
    {
1262   
        return kind() == json::kind::uint64;
1795   
        return kind() == json::kind::uint64;
1263   
    }
1796   
    }
1264  
1797  
1265 - 
    /** Check if this is a `double`.
1798 + 
    /** Return `true` if this is a double
1266  
1799  
1267 - 
        Returns `true` if the value's @ref kind() is `kind::double_`.
1800 + 
        This function is used to determine if the underlying
 
1801 + 
        representation is a certain kind.
1268  
1802  
1269 - 
        @returns `this->kind() == kind::double_`.
1803 + 
        @par Effects
 
1804 + 
        @code
 
1805 + 
        return this->kind() == kind::double_;
 
1806 + 
        @endcode
1270  
1807  
1271   
        @par Complexity
1808   
        @par Complexity
1272   
        Constant.
1809   
        Constant.
1273  
1810  
1274   
        @par Exception Safety
1811   
        @par Exception Safety
1275   
        No-throw guarantee.
1812   
        No-throw guarantee.
1276   
    */
1813   
    */
1277   
    bool
1814   
    bool
1278   
    is_double() const noexcept
1815   
    is_double() const noexcept
1279   
    {
1816   
    {
1280   
        return kind() == json::kind::double_;
1817   
        return kind() == json::kind::double_;
1281   
    }
1818   
    }
1282  
1819  
1283 - 
    /** Check if this is a `bool`.
1820 + 
    /** Return `true` if this is a bool
1284  
1821  
1285 - 
        Returns `true` if the value's @ref kind() is `kind::bool_`.
1822 + 
        This function is used to determine if the underlying
 
1823 + 
        representation is a certain kind.
1286  
1824  
1287 - 
        @returns `this->kind() == kind::bool_`.
1825 + 
        @par Effects
 
1826 + 
        @code
 
1827 + 
        return this->kind() == kind::bool_;
 
1828 + 
        @endcode
1288  
1829  
1289   
        @par Complexity
1830   
        @par Complexity
1290   
        Constant.
1831   
        Constant.
1291  
1832  
1292   
        @par Exception Safety
1833   
        @par Exception Safety
1293   
        No-throw guarantee.
1834   
        No-throw guarantee.
1294   
    */
1835   
    */
1295   
    bool
1836   
    bool
1296   
    is_bool() const noexcept
1837   
    is_bool() const noexcept
1297   
    {
1838   
    {
1298   
        return kind() == json::kind::bool_;
1839   
        return kind() == json::kind::bool_;
1299   
    }
1840   
    }
1300  
1841  
1301 - 
    /** Check if this is a null value.
1842 + 
    /** Returns true if this is a null.
1302  
1843  
1303 - 
        Returns `true` if the value's @ref kind() is `kind::null`.
1844 + 
        This function is used to determine if the underlying
 
1845 + 
        representation is a certain kind.
1304  
1846  
1305 - 
        @returns `this->kind() == kind::null`.
1847 + 
        @par Effects
 
1848 + 
        @code
 
1849 + 
        return this->kind() == kind::null;
 
1850 + 
        @endcode
1306  
1851  
1307   
        @par Complexity
1852   
        @par Complexity
1308   
        Constant.
1853   
        Constant.
1309  
1854  
1310   
        @par Exception Safety
1855   
        @par Exception Safety
1311   
        No-throw guarantee.
1856   
        No-throw guarantee.
1312   
    */
1857   
    */
1313   
    bool
1858   
    bool
1314   
    is_null() const noexcept
1859   
    is_null() const noexcept
1315   
    {
1860   
    {
1316   
        return kind() == json::kind::null;
1861   
        return kind() == json::kind::null;
1317   
    }
1862   
    }
1318  
1863  
1319 - 
    /** Checks if this is an @ref array or an @ref object.
1864 + 
    /** Returns true if this is an array or object.
1320  
1865  
1321 - 
        This function returns `true` if @ref kind() is either `kind::object` or
1866 + 
        This function returns `true` if
 
1867 + 
        @ref kind() is either `kind::object` or
1322   
        `kind::array`.
1868   
        `kind::array`.
1323  
1869  
1324   
        @par Complexity
1870   
        @par Complexity
1325   
        Constant.
1871   
        Constant.
1326  
1872  
1327   
        @par Exception Safety
1873   
        @par Exception Safety
1328   
        No-throw guarantee.
1874   
        No-throw guarantee.
1329   
    */
1875   
    */
1330   
    bool
1876   
    bool
1331   
    is_structured() const noexcept
1877   
    is_structured() const noexcept
1332   
    {
1878   
    {
1333   
        // VFALCO Could use bit 0x20 for this
1879   
        // VFALCO Could use bit 0x20 for this
1334   
        return
1880   
        return
1335   
           kind() == json::kind::object ||
1881   
           kind() == json::kind::object ||
1336   
           kind() == json::kind::array;
1882   
           kind() == json::kind::array;
1337   
    }
1883   
    }
1338  
1884  
1339 - 
    /** Check if this is not an @ref array or @ref object.
1885 + 
    /** Returns true if this is not an array or object.
1340  
1886  
1341 - 
        This function returns `true` if @ref kind() is neither `kind::object`
1887 + 
        This function returns `true` if
1342 - 
        nor `kind::array`.
1888 + 
        @ref kind() is neither `kind::object` nor
 
1889 + 
        `kind::array`.
1343  
1890  
1344   
        @par Complexity
1891   
        @par Complexity
1345   
        Constant.
1892   
        Constant.
1346  
1893  
1347   
        @par Exception Safety
1894   
        @par Exception Safety
1348   
        No-throw guarantee.
1895   
        No-throw guarantee.
1349   
    */
1896   
    */
1350   
    bool
1897   
    bool
1351   
    is_primitive() const noexcept
1898   
    is_primitive() const noexcept
1352   
    {
1899   
    {
1353   
        // VFALCO Could use bit 0x20 for this
1900   
        // VFALCO Could use bit 0x20 for this
1354   
        return
1901   
        return
1355   
           sca_.k != json::kind::object &&
1902   
           sca_.k != json::kind::object &&
1356   
           sca_.k != json::kind::array;
1903   
           sca_.k != json::kind::array;
1357   
    }
1904   
    }
1358  
1905  
1359 - 
    /** Check if this is a number.
1906 + 
    /** Returns true if this is a number.
1360  
1907  
1361 - 
        This function returns `true` when @ref kind() is one of `kind::int64`,
1908 + 
        This function returns `true` when
1362 - 
        `kind::uint64`, or `kind::double_`.
1909 + 
        @ref kind() is one of the following values:
 
1910 + 
        `kind::int64`, `kind::uint64`, or
 
1911 + 
        `kind::double_`.
1363  
1912  
1364   
        @par Complexity
1913   
        @par Complexity
1365   
        Constant.
1914   
        Constant.
1366  
1915  
1367   
        @par Exception Safety
1916   
        @par Exception Safety
1368   
        No-throw guarantee.
1917   
        No-throw guarantee.
1369   
    */
1918   
    */
1370   
    bool
1919   
    bool
1371   
    is_number() const noexcept
1920   
    is_number() const noexcept
1372   
    {
1921   
    {
1373   
        // VFALCO Could use bit 0x40 for this
1922   
        // VFALCO Could use bit 0x40 for this
1374   
        return
1923   
        return
1375   
            kind() == json::kind::int64 ||
1924   
            kind() == json::kind::int64 ||
1376   
            kind() == json::kind::uint64 ||
1925   
            kind() == json::kind::uint64 ||
1377   
            kind() == json::kind::double_;
1926   
            kind() == json::kind::double_;
1378   
    }
1927   
    }
1379  
1928  
1380   
    //------------------------------------------------------
1929   
    //------------------------------------------------------
1381  
1930  
1382 - 
    /** Return a pointer to the underlying @ref array.
1931 + 
    /** Return an @ref array pointer if this is an array, else return `nullptr`
1383  
1932  
1384 - 
        If `this->kind() == kind::array`, returns a pointer to the underlying
1933 + 
        If `this->kind() == kind::array`, returns a pointer
1385 - 
        array. Otherwise, returns `nullptr`.
1934 + 
        to the underlying array. Otherwise, returns `nullptr`.
1386  
1935  
1387   
        @par Example
1936   
        @par Example
1388   
        The return value is used in both a boolean context and
1937   
        The return value is used in both a boolean context and
1389   
        to assign a variable:
1938   
        to assign a variable:
1390   
        @code
1939   
        @code
1391   
        if( auto p = jv.if_array() )
1940   
        if( auto p = jv.if_array() )
1392   
            return *p;
1941   
            return *p;
1393   
        @endcode
1942   
        @endcode
1394  
1943  
1395   
        @par Complexity
1944   
        @par Complexity
1396   
        Constant.
1945   
        Constant.
1397  
1946  
1398   
        @par Exception Safety
1947   
        @par Exception Safety
1399 -
 
1400 - 
        @{
 
1401   
        No-throw guarantee.
1948   
        No-throw guarantee.
1402   
    */
1949   
    */
1403   
    array const*
1950   
    array const*
1404   
    if_array() const noexcept
1951   
    if_array() const noexcept
1405   
    {
1952   
    {
1406   
        if(kind() == json::kind::array)
1953   
        if(kind() == json::kind::array)
1407   
            return &arr_;
1954   
            return &arr_;
1408   
        return nullptr;
1955   
        return nullptr;
1409   
    }
1956   
    }
1410  
1957  
 
1958 + 
    /** Return an @ref array pointer if this is an array, else return `nullptr`
 
1959 +
 
1960 + 
        If `this->kind() == kind::array`, returns a pointer
 
1961 + 
        to the underlying array. Otherwise, returns `nullptr`.
 
1962 +
 
1963 + 
        @par Example
 
1964 + 
        The return value is used in both a boolean context and
 
1965 + 
        to assign a variable:
 
1966 + 
        @code
 
1967 + 
        if( auto p = jv.if_array() )
 
1968 + 
            return *p;
 
1969 + 
        @endcode
 
1970 +
 
1971 + 
        @par Complexity
 
1972 + 
        Constant.
 
1973 +
 
1974 + 
        @par Exception Safety
 
1975 + 
        No-throw guarantee.
 
1976 + 
    */
1411   
    array*
1977   
    array*
1412   
    if_array() noexcept
1978   
    if_array() noexcept
1413   
    {
1979   
    {
1414   
        if(kind() == json::kind::array)
1980   
        if(kind() == json::kind::array)
1415   
            return &arr_;
1981   
            return &arr_;
1416   
        return nullptr;
1982   
        return nullptr;
1417 - 
    /// @}
 
1418   
    }
1983   
    }
1419  
1984  
1420 - 
    /** Return a pointer to the underlying @ref object.
1985 + 
    /** Return an @ref object pointer if this is an object, else return `nullptr`
1421  
1986  
1422 - 
        If `this->kind() == kind::object`, returns a pointer to the underlying
1987 + 
        If `this->kind() == kind::object`, returns a pointer
1423 - 
        object. Otherwise, returns `nullptr`.
1988 + 
        to the underlying object. Otherwise, returns `nullptr`.
1424  
1989  
1425   
        @par Example
1990   
        @par Example
1426   
        The return value is used in both a boolean context and
1991   
        The return value is used in both a boolean context and
1427   
        to assign a variable:
1992   
        to assign a variable:
1428   
        @code
1993   
        @code
1429   
        if( auto p = jv.if_object() )
1994   
        if( auto p = jv.if_object() )
1430   
            return *p;
1995   
            return *p;
1431   
        @endcode
1996   
        @endcode
1432  
1997  
1433   
        @par Complexity
1998   
        @par Complexity
1434   
        Constant.
1999   
        Constant.
1435  
2000  
1436   
        @par Exception Safety
2001   
        @par Exception Safety
1437 -
 
1438 - 
        @{
 
1439   
        No-throw guarantee.
2002   
        No-throw guarantee.
1440   
    */
2003   
    */
1441   
    object const*
2004   
    object const*
1442   
    if_object() const noexcept
2005   
    if_object() const noexcept
1443   
    {
2006   
    {
1444   
        if(kind() == json::kind::object)
2007   
        if(kind() == json::kind::object)
1445   
            return &obj_;
2008   
            return &obj_;
1446   
        return nullptr;
2009   
        return nullptr;
1447   
    }
2010   
    }
1448  
2011  
 
2012 + 
    /** Return an @ref object pointer if this is an object, else return `nullptr`
 
2013 +
 
2014 + 
        If `this->kind() == kind::object`, returns a pointer
 
2015 + 
        to the underlying object. Otherwise, returns `nullptr`.
 
2016 +
 
2017 + 
        @par Example
 
2018 + 
        The return value is used in both a boolean context and
 
2019 + 
        to assign a variable:
 
2020 + 
        @code
 
2021 + 
        if( auto p = jv.if_object() )
 
2022 + 
            return *p;
 
2023 + 
        @endcode
 
2024 +
 
2025 + 
        @par Complexity
 
2026 + 
        Constant.
 
2027 +
 
2028 + 
        @par Exception Safety
 
2029 + 
        No-throw guarantee.
 
2030 + 
    */
1449   
    object*
2031   
    object*
1450   
    if_object() noexcept
2032   
    if_object() noexcept
1451   
    {
2033   
    {
1452   
        if(kind() == json::kind::object)
2034   
        if(kind() == json::kind::object)
1453   
            return &obj_;
2035   
            return &obj_;
1454   
        return nullptr;
2036   
        return nullptr;
1455 - 
    /// @}
 
1456   
    }
2037   
    }
1457  
2038  
1458 - 
    /** Return a pointer to the underlying @ref string.
2039 + 
    /** Return a @ref string pointer if this is a string, else return `nullptr`
1459  
2040  
1460 - 
        If `this->kind() == kind::string`, returns a pointer to the underlying
2041 + 
        If `this->kind() == kind::string`, returns a pointer
1461 - 
        object. Otherwise, returns `nullptr`.
2042 + 
        to the underlying object. Otherwise, returns `nullptr`.
1462  
2043  
1463   
        @par Example
2044   
        @par Example
1464   
        The return value is used in both a boolean context and
2045   
        The return value is used in both a boolean context and
1465   
        to assign a variable:
2046   
        to assign a variable:
1466   
        @code
2047   
        @code
1467   
        if( auto p = jv.if_string() )
2048   
        if( auto p = jv.if_string() )
1468   
            return *p;
2049   
            return *p;
1469   
        @endcode
2050   
        @endcode
1470  
2051  
1471   
        @par Complexity
2052   
        @par Complexity
1472   
        Constant.
2053   
        Constant.
1473  
2054  
1474   
        @par Exception Safety
2055   
        @par Exception Safety
1475 -
 
1476 - 
        @{
 
1477   
        No-throw guarantee.
2056   
        No-throw guarantee.
1478   
    */
2057   
    */
1479   
    string const*
2058   
    string const*
1480   
    if_string() const noexcept
2059   
    if_string() const noexcept
1481   
    {
2060   
    {
1482   
        if(kind() == json::kind::string)
2061   
        if(kind() == json::kind::string)
1483   
            return &str_;
2062   
            return &str_;
1484   
        return nullptr;
2063   
        return nullptr;
1485   
    }
2064   
    }
1486  
2065  
 
2066 + 
    /** Return a @ref string pointer if this is a string, else return `nullptr`
 
2067 +
 
2068 + 
        If `this->kind() == kind::string`, returns a pointer
 
2069 + 
        to the underlying object. Otherwise, returns `nullptr`.
 
2070 +
 
2071 + 
        @par Example
 
2072 + 
        The return value is used in both a boolean context and
 
2073 + 
        to assign a variable:
 
2074 + 
        @code
 
2075 + 
        if( auto p = jv.if_string() )
 
2076 + 
            return *p;
 
2077 + 
        @endcode
 
2078 +
 
2079 + 
        @par Complexity
 
2080 + 
        Constant.
 
2081 +
 
2082 + 
        @par Exception Safety
 
2083 + 
        No-throw guarantee.
 
2084 + 
    */
1487   
    string*
2085   
    string*
1488   
    if_string() noexcept
2086   
    if_string() noexcept
1489   
    {
2087   
    {
1490   
        if(kind() == json::kind::string)
2088   
        if(kind() == json::kind::string)
1491   
            return &str_;
2089   
            return &str_;
1492   
        return nullptr;
2090   
        return nullptr;
1493 - 
    /// @}
 
1494   
    }
2091   
    }
1495  
2092  
1496 - 
    /** Return a pointer to the underlying `std::int64_t`.
2093 + 
    /** Return an `int64_t` pointer if this is a signed integer, else return `nullptr`
1497  
2094  
1498 - 
        If `this->kind() == kind::int64`, returns a pointer to the underlying
2095 + 
        If `this->kind() == kind::int64`, returns a pointer
1499 - 
        integer. Otherwise, returns `nullptr`.
2096 + 
        to the underlying integer. Otherwise, returns `nullptr`.
1500  
2097  
1501   
        @par Example
2098   
        @par Example
1502   
        The return value is used in both a boolean context and
2099   
        The return value is used in both a boolean context and
1503   
        to assign a variable:
2100   
        to assign a variable:
1504   
        @code
2101   
        @code
1505   
        if( auto p = jv.if_int64() )
2102   
        if( auto p = jv.if_int64() )
1506   
            return *p;
2103   
            return *p;
1507   
        @endcode
2104   
        @endcode
1508  
2105  
1509   
        @par Complexity
2106   
        @par Complexity
1510   
        Constant.
2107   
        Constant.
1511  
2108  
1512   
        @par Exception Safety
2109   
        @par Exception Safety
1513 -
 
1514 - 
        @{
 
1515   
        No-throw guarantee.
2110   
        No-throw guarantee.
1516   
    */
2111   
    */
1517   
    std::int64_t const*
2112   
    std::int64_t const*
1518   
    if_int64() const noexcept
2113   
    if_int64() const noexcept
1519   
    {
2114   
    {
1520   
        if(kind() == json::kind::int64)
2115   
        if(kind() == json::kind::int64)
1521   
            return &sca_.i;
2116   
            return &sca_.i;
1522   
        return nullptr;
2117   
        return nullptr;
1523   
    }
2118   
    }
1524  
2119  
 
2120 + 
    /** Return an `int64_t` pointer if this is a signed integer, else return `nullptr`
 
2121 +
 
2122 + 
        If `this->kind() == kind::int64`, returns a pointer
 
2123 + 
        to the underlying integer. Otherwise, returns `nullptr`.
 
2124 +
 
2125 + 
        @par Example
 
2126 + 
        The return value is used in both a boolean context and
 
2127 + 
        to assign a variable:
 
2128 + 
        @code
 
2129 + 
        if( auto p = jv.if_int64() )
 
2130 + 
            return *p;
 
2131 + 
        @endcode
 
2132 +
 
2133 + 
        @par Complexity
 
2134 + 
        Constant.
 
2135 +
 
2136 + 
        @par Exception Safety
 
2137 + 
        No-throw guarantee.
 
2138 + 
    */
1525   
    std::int64_t*
2139   
    std::int64_t*
1526   
    if_int64() noexcept
2140   
    if_int64() noexcept
1527   
    {
2141   
    {
1528   
        if(kind() == json::kind::int64)
2142   
        if(kind() == json::kind::int64)
1529   
            return &sca_.i;
2143   
            return &sca_.i;
1530   
        return nullptr;
2144   
        return nullptr;
1531 - 
    /// @}
 
1532   
    }
2145   
    }
1533  
2146  
1534 - 
    /** Return a pointer to the underlying `std::uint64_t`.
2147 + 
    /** Return a `uint64_t` pointer if this is an unsigned integer, else return `nullptr`
1535  
2148  
1536 - 
        If `this->kind() == kind::uint64`, returns a pointer to the underlying
2149 + 
        If `this->kind() == kind::uint64`, returns a pointer
1537 - 
        unsigned integer. Otherwise, returns `nullptr`.
2150 + 
        to the underlying unsigned integer. Otherwise, returns
 
2151 + 
        `nullptr`.
1538  
2152  
1539   
        @par Example
2153   
        @par Example
1540   
        The return value is used in both a boolean context and
2154   
        The return value is used in both a boolean context and
1541   
        to assign a variable:
2155   
        to assign a variable:
1542   
        @code
2156   
        @code
1543   
        if( auto p = jv.if_uint64() )
2157   
        if( auto p = jv.if_uint64() )
1544   
            return *p;
2158   
            return *p;
1545   
        @endcode
2159   
        @endcode
1546  
2160  
1547   
        @par Complexity
2161   
        @par Complexity
1548   
        Constant.
2162   
        Constant.
1549  
2163  
1550   
        @par Exception Safety
2164   
        @par Exception Safety
1551 -
 
1552 - 
        @{
 
1553   
        No-throw guarantee.
2165   
        No-throw guarantee.
1554   
    */
2166   
    */
1555   
    std::uint64_t const*
2167   
    std::uint64_t const*
1556   
    if_uint64() const noexcept
2168   
    if_uint64() const noexcept
1557   
    {
2169   
    {
1558   
        if(kind() == json::kind::uint64)
2170   
        if(kind() == json::kind::uint64)
1559   
            return &sca_.u;
2171   
            return &sca_.u;
1560   
        return nullptr;
2172   
        return nullptr;
1561   
    }
2173   
    }
1562  
2174  
 
2175 + 
    /** Return a `uint64_t` pointer if this is an unsigned integer, else return `nullptr`
 
2176 +
 
2177 + 
        If `this->kind() == kind::uint64`, returns a pointer
 
2178 + 
        to the underlying unsigned integer. Otherwise, returns
 
2179 + 
        `nullptr`.
 
2180 +
 
2181 + 
        @par Example
 
2182 + 
        The return value is used in both a boolean context and
 
2183 + 
        to assign a variable:
 
2184 + 
        @code
 
2185 + 
        if( auto p = jv.if_uint64() )
 
2186 + 
            return *p;
 
2187 + 
        @endcode
 
2188 +
 
2189 + 
        @par Complexity
 
2190 + 
        Constant.
 
2191 +
 
2192 + 
        @par Exception Safety
 
2193 + 
        No-throw guarantee.
 
2194 + 
    */
1563   
    std::uint64_t*
2195   
    std::uint64_t*
1564   
    if_uint64() noexcept
2196   
    if_uint64() noexcept
1565   
    {
2197   
    {
1566   
        if(kind() == json::kind::uint64)
2198   
        if(kind() == json::kind::uint64)
1567   
            return &sca_.u;
2199   
            return &sca_.u;
1568   
        return nullptr;
2200   
        return nullptr;
1569 - 
    /// @}
 
1570   
    }
2201   
    }
1571  
2202  
1572 - 
    /** Return a pointer to the underlying `double`.
2203 + 
    /** Return a `double` pointer if this is a double, else return `nullptr`
1573  
2204  
1574 - 
        If `this->kind() == kind::double_`, returns a pointer to the underlying
2205 + 
        If `this->kind() == kind::double_`, returns a pointer
1575 - 
        double. Otherwise, returns `nullptr`.
2206 + 
        to the underlying double. Otherwise, returns
 
2207 + 
        `nullptr`.
1576  
2208  
1577   
        @par Example
2209   
        @par Example
1578   
        The return value is used in both a boolean context and
2210   
        The return value is used in both a boolean context and
1579   
        to assign a variable:
2211   
        to assign a variable:
1580   
        @code
2212   
        @code
1581   
        if( auto p = jv.if_double() )
2213   
        if( auto p = jv.if_double() )
1582   
            return *p;
2214   
            return *p;
1583   
        @endcode
2215   
        @endcode
1584  
2216  
1585   
        @par Complexity
2217   
        @par Complexity
1586   
        Constant.
2218   
        Constant.
1587  
2219  
1588   
        @par Exception Safety
2220   
        @par Exception Safety
1589 -
 
1590 - 
        @{
 
1591   
        No-throw guarantee.
2221   
        No-throw guarantee.
1592   
    */
2222   
    */
1593   
    double const*
2223   
    double const*
1594   
    if_double() const noexcept
2224   
    if_double() const noexcept
1595   
    {
2225   
    {
1596   
        if(kind() == json::kind::double_)
2226   
        if(kind() == json::kind::double_)
1597   
            return &sca_.d;
2227   
            return &sca_.d;
1598   
        return nullptr;
2228   
        return nullptr;
1599   
    }
2229   
    }
1600  
2230  
 
2231 + 
    /** Return a `double` pointer if this is a double, else return `nullptr`
 
2232 +
 
2233 + 
        If `this->kind() == kind::double_`, returns a pointer
 
2234 + 
        to the underlying double. Otherwise, returns
 
2235 + 
        `nullptr`.
 
2236 +
 
2237 + 
        @par Example
 
2238 + 
        The return value is used in both a boolean context and
 
2239 + 
        to assign a variable:
 
2240 + 
        @code
 
2241 + 
        if( auto p = jv.if_double() )
 
2242 + 
            return *p;
 
2243 + 
        @endcode
 
2244 +
 
2245 + 
        @par Complexity
 
2246 + 
        Constant.
 
2247 +
 
2248 + 
        @par Exception Safety
 
2249 + 
        No-throw guarantee.
 
2250 + 
    */
1601   
    double*
2251   
    double*
1602   
    if_double() noexcept
2252   
    if_double() noexcept
1603   
    {
2253   
    {
1604   
        if(kind() == json::kind::double_)
2254   
        if(kind() == json::kind::double_)
1605   
            return &sca_.d;
2255   
            return &sca_.d;
1606   
        return nullptr;
2256   
        return nullptr;
1607 - 
    /// @}
 
1608   
    }
2257   
    }
1609  
2258  
1610 - 
    /** Return a pointer to the underlying `bool` .
2259 + 
    /** Return a `bool` pointer if this is a boolean, else return `nullptr`
1611  
2260  
1612 - 
        If `this->kind() == kind::bool_`, returns a pointer to the underlying
2261 + 
        If `this->kind() == kind::bool_`, returns a pointer
1613 - 
        boolean. Otherwise, returns `nullptr`.
2262 + 
        to the underlying boolean. Otherwise, returns
 
2263 + 
        `nullptr`.
1614  
2264  
1615   
        @par Example
2265   
        @par Example
1616   
        The return value is used in both a boolean context and
2266   
        The return value is used in both a boolean context and
1617   
        to assign a variable:
2267   
        to assign a variable:
1618   
        @code
2268   
        @code
1619   
        if( auto p = jv.if_bool() )
2269   
        if( auto p = jv.if_bool() )
1620   
            return *p;
2270   
            return *p;
1621   
        @endcode
2271   
        @endcode
1622  
2272  
1623   
        @par Complexity
2273   
        @par Complexity
1624   
        Constant.
2274   
        Constant.
1625  
2275  
1626   
        @par Exception Safety
2276   
        @par Exception Safety
1627 -
 
1628 - 
        @{
 
1629   
        No-throw guarantee.
2277   
        No-throw guarantee.
1630   
    */
2278   
    */
1631   
    bool const*
2279   
    bool const*
1632   
    if_bool() const noexcept
2280   
    if_bool() const noexcept
1633   
    {
2281   
    {
1634   
        if(kind() == json::kind::bool_)
2282   
        if(kind() == json::kind::bool_)
1635   
            return &sca_.b;
2283   
            return &sca_.b;
1636   
        return nullptr;
2284   
        return nullptr;
1637   
    }
2285   
    }
1638  
2286  
 
2287 + 
    /** Return a `bool` pointer if this is a boolean, else return `nullptr`
 
2288 +
 
2289 + 
        If `this->kind() == kind::bool_`, returns a pointer
 
2290 + 
        to the underlying boolean. Otherwise, returns
 
2291 + 
        `nullptr`.
 
2292 +
 
2293 + 
        @par Example
 
2294 + 
        The return value is used in both a boolean context and
 
2295 + 
        to assign a variable:
 
2296 + 
        @code
 
2297 + 
        if( auto p = jv.if_bool() )
 
2298 + 
            return *p;
 
2299 + 
        @endcode
 
2300 +
 
2301 + 
        @par Complexity
 
2302 + 
        Constant.
 
2303 +
 
2304 + 
        @par Exception Safety
 
2305 + 
        No-throw guarantee.
 
2306 + 
    */
1639   
    bool*
2307   
    bool*
1640   
    if_bool() noexcept
2308   
    if_bool() noexcept
1641   
    {
2309   
    {
1642   
        if(kind() == json::kind::bool_)
2310   
        if(kind() == json::kind::bool_)
1643   
            return &sca_.b;
2311   
            return &sca_.b;
1644   
        return nullptr;
2312   
        return nullptr;
1645 - 
    /// @}
 
1646   
    }
2313   
    }
1647  
2314  
1648   
    //------------------------------------------------------
2315   
    //------------------------------------------------------
1649  
2316  
1650   
    /** Return the stored number cast to an arithmetic type.
2317   
    /** Return the stored number cast to an arithmetic type.
1651  
2318  
1652 - 
        This function attempts to return the stored value converted to the
2319 + 
        This function attempts to return the stored value
1653 - 
        arithmetic type `T` which may not be `bool`:
2320 + 
        converted to the arithmetic type `T` which may not
 
2321 + 
        be `bool`:
1654  
2322  
1655 - 
        @li If `T` is an integral type and the stored value is a number which
2323 + 
        @li If `T` is an integral type and the stored
1656 - 
            can be losslessly converted, the conversion is performed without
2324 + 
        value is a number which can be losslessly converted,
1657 - 
            error and the converted number is returned.
2325 + 
        the conversion is performed without error and the
1658 - 
        @li If `T` is an integral type and the stored value is a number which
2326 + 
        converted number is returned.
1659 - 
            cannot be losslessly converted, then the operation fails with
2327 +
1660 - 
            an error.
2328 + 
        @li If `T` is an integral type and the stored value
1661 - 
        @li If `T` is a floating point type and the stored value is a number,
2329 + 
        is a number which cannot be losslessly converted,
1662 - 
            the conversion is performed without error. The converted number is
2330 + 
        then the operation fails with an error.
1663 - 
            returned, with a possible loss of precision.
2331 +
1664 - 
        @li Otherwise, if the stored value is not a number; that is, if
2332 + 
        @li If `T` is a floating point type and the stored
1665 - 
            @ref is_number() returns `false`, then the operation fails with
2333 + 
        value is a number, the conversion is performed
1666 - 
            an error.
2334 + 
        without error. The converted number is returned,
 
2335 + 
        with a possible loss of precision.
 
2336 +
 
2337 + 
        @li Otherwise, if the stored value is not a number;
 
2338 + 
        that is, if `this->is_number()` returns `false`, then
 
2339 + 
        the operation fails with an error.
1667  
2340  
1668   
        @par Constraints
2341   
        @par Constraints
1669   
        @code
2342   
        @code
1670   
        std::is_arithmetic< T >::value && ! std::is_same< T, bool >::value
2343   
        std::is_arithmetic< T >::value && ! std::is_same< T, bool >::value
1671   
        @endcode
2344   
        @endcode
1672  
2345  
1673   
        @par Complexity
2346   
        @par Complexity
1674   
        Constant.
2347   
        Constant.
1675  
2348  
1676   
        @par Exception Safety
2349   
        @par Exception Safety
1677 - 
        @li **(1)**, **(2)** no-throw guarantee.
2350 + 
        No-throw guarantee.
1678 - 
        @li **(3)** strong guarantee.
 
1679  
2351  
1680   
        @return The converted number.
2352   
        @return The converted number.
1681  
2353  
1682 -
 
1683 - 
        @return The converted number.
 
1684 -
 
1685 - 
        @{
 
1686   
        @param ec Set to the error, if any occurred.
2354   
        @param ec Set to the error, if any occurred.
1687   
    */
2355   
    */
 
2356 + 
/** @{ */
1688   
    template<class T>
2357   
    template<class T>
1689   
#ifdef BOOST_JSON_DOCS
2358   
#ifdef BOOST_JSON_DOCS
1690   
    T
2359   
    T
1691   
#else
2360   
#else
1692   
    typename std::enable_if<
2361   
    typename std::enable_if<
1693   
        std::is_arithmetic<T>::value &&
2362   
        std::is_arithmetic<T>::value &&
1694   
        ! std::is_same<T, bool>::value,
2363   
        ! std::is_same<T, bool>::value,
1695   
            T>::type
2364   
            T>::type
1696   
#endif
2365   
#endif
1697   
    to_number(system::error_code& ec) const noexcept
2366   
    to_number(system::error_code& ec) const noexcept
1698   
    {
2367   
    {
1699   
        error e;
2368   
        error e;
1700   
        auto result = to_number<T>(e);
2369   
        auto result = to_number<T>(e);
1701   
        BOOST_JSON_FAIL(ec, e);
2370   
        BOOST_JSON_FAIL(ec, e);
1702   
        return result;
2371   
        return result;
1703   
    }
2372   
    }
1704  
2373  
1705   
    template<class T>
2374   
    template<class T>
1706   
#ifdef BOOST_JSON_DOCS
2375   
#ifdef BOOST_JSON_DOCS
1707   
    T
2376   
    T
1708   
#else
2377   
#else
1709   
    typename std::enable_if<
2378   
    typename std::enable_if<
1710   
        std::is_arithmetic<T>::value &&
2379   
        std::is_arithmetic<T>::value &&
1711   
        ! std::is_same<T, bool>::value,
2380   
        ! std::is_same<T, bool>::value,
1712   
            T>::type
2381   
            T>::type
1713   
#endif
2382   
#endif
1714   
    to_number(std::error_code& ec) const noexcept
2383   
    to_number(std::error_code& ec) const noexcept
1715   
    {
2384   
    {
1716   
        system::error_code jec;
2385   
        system::error_code jec;
1717   
        auto result = to_number<T>(jec);
2386   
        auto result = to_number<T>(jec);
1718   
        ec = jec;
2387   
        ec = jec;
1719   
        return result;
2388   
        return result;
1720   
    }
2389   
    }
 
2390 + 
/** @} */
1721  
2391  
1722 - 
    /** Overload
2392 + 
    /** Return the stored number as `boost::system::result<T>`.
1723 -
 
1724 - 
        @throws boost::system::system_error Overload **(3)** reports errors by
 
1725 - 
                throwing an exception.
 
1726 - 
    */
 
1727 - 
    template<class T>
 
1728 - 
#ifdef BOOST_JSON_DOCS
 
1729 - 
    T
 
1730 - 
#else
 
1731 - 
    typename std::enable_if<
 
1732 - 
        std::is_arithmetic<T>::value &&
 
1733 - 
        ! std::is_same<T, bool>::value,
 
1734 - 
            T>::type
 
1735 - 
#endif
 
1736 - 
    to_number() const
 
1737 - 
    {
 
1738 - 
        return try_to_number<T>().value();
 
1739 - 
    }
 
1740 - 
    /// @}
 
1741 -
 
1742 - 
    /** Return the stored number as @ref boost::system::result.
 
1743  
2393  
1744   
        This function attempts to return the stored value converted to the
2394   
        This function attempts to return the stored value converted to the
1745   
        arithmetic type `T` which may not be `bool`:
2395   
        arithmetic type `T` which may not be `bool`:
1746  
2396  
1747   
        @li If `T` is an integral type and the stored value is a number which
2397   
        @li If `T` is an integral type and the stored value is a number which
1748   
            can be losslessly converted, the conversion is performed without
2398   
            can be losslessly converted, the conversion is performed without
1749   
            error and `result<T>` containing the converted number is returned.
2399   
            error and `result<T>` containing the converted number is returned.
 
2400 +
1750   
        @li If `T` is an integral type and the stored value is a number which
2401   
        @li If `T` is an integral type and the stored value is a number which
1751   
            cannot be losslessly converted, then `result<T>` containing the
2402   
            cannot be losslessly converted, then `result<T>` containing the
1752   
            corresponding `error_code` is returned.
2403   
            corresponding `error_code` is returned.
 
2404 +
1753   
        @li If `T` is a floating point type and the stored value is a number,
2405   
        @li If `T` is a floating point type and the stored value is a number,
1754   
            the conversion is performed without error. `result<T>` containing
2406   
            the conversion is performed without error. `result<T>` containing
1755   
            the converted number, with a possible loss of precision, is
2407   
            the converted number, with a possible loss of precision, is
1756   
            returned.
2408   
            returned.
 
2409 +
1757   
        @li Otherwise, if the stored value is not a number; that is, if
2410   
        @li Otherwise, if the stored value is not a number; that is, if
1758   
            `this->is_number()` returns `false`, then `result<T>` containing
2411   
            `this->is_number()` returns `false`, then `result<T>` containing
1759   
            the corresponding `error_code` is returned.
2412   
            the corresponding `error_code` is returned.
1760  
2413  
1761   
        @par Constraints
2414   
        @par Constraints
1762   
        @code
2415   
        @code
1763   
        std::is_arithmetic< T >::value && ! std::is_same< T, bool >::value
2416   
        std::is_arithmetic< T >::value && ! std::is_same< T, bool >::value
1764   
        @endcode
2417   
        @endcode
1765  
2418  
1766   
        @par Complexity
2419   
        @par Complexity
1767   
        Constant.
2420   
        Constant.
1768  
2421  
1769   
        @par Exception Safety
2422   
        @par Exception Safety
1770   
        No-throw guarantee.
2423   
        No-throw guarantee.
1771  
2424  
1772   
        @return `boost::system::result<T>` with either the converted number or
2425   
        @return `boost::system::result<T>` with either the converted number or
1773 - 
                an `error_code`.
2426 + 
            an `error_code`.
1774   
    */
2427   
    */
1775   
    template<class T>
2428   
    template<class T>
1776   
#ifdef BOOST_JSON_DOCS
2429   
#ifdef BOOST_JSON_DOCS
1777   
    system::result<T>
2430   
    system::result<T>
1778   
#else
2431   
#else
1779   
    typename std::enable_if<
2432   
    typename std::enable_if<
1780   
        std::is_arithmetic<T>::value && ! std::is_same<T, bool>::value,
2433   
        std::is_arithmetic<T>::value && ! std::is_same<T, bool>::value,
1781   
        system::result<T>
2434   
        system::result<T>
1782   
    >::type
2435   
    >::type
1783   
#endif
2436   
#endif
1784   
    try_to_number() const noexcept
2437   
    try_to_number() const noexcept
1785   
    {
2438   
    {
1786   
        system::error_code ec;
2439   
        system::error_code ec;
1787   
        T result = to_number<T>(ec);
2440   
        T result = to_number<T>(ec);
1788   
        if( ec )
2441   
        if( ec )
1789   
            return {system::in_place_error, ec};
2442   
            return {system::in_place_error, ec};
1790  
2443  
1791   
        return {system::in_place_value, result};
2444   
        return {system::in_place_value, result};
1792   
    }
2445   
    }
1793  
2446  
 
2447 + 
    /** Return the stored number cast to an arithmetic type.
 
2448 +
 
2449 + 
        This function attempts to return the stored value
 
2450 + 
        converted to the arithmetic type `T` which may not
 
2451 + 
        be `bool`:
 
2452 +
 
2453 + 
        @li If `T` is an integral type and the stored
 
2454 + 
        value is a number which can be losslessly converted,
 
2455 + 
        the conversion is performed without error and the
 
2456 + 
        converted number is returned.
 
2457 +
 
2458 + 
        @li If `T` is an integral type and the stored value
 
2459 + 
        is a number which cannot be losslessly converted,
 
2460 + 
        then the operation fails with an error.
 
2461 +
 
2462 + 
        @li If `T` is a floating point type and the stored
 
2463 + 
        value is a number, the conversion is performed
 
2464 + 
        without error. The converted number is returned,
 
2465 + 
        with a possible loss of precision.
 
2466 +
 
2467 + 
        @li Otherwise, if the stored value is not a number;
 
2468 + 
        that is, if `this->is_number()` returns `false`, then
 
2469 + 
        the operation fails with an error.
 
2470 +
 
2471 + 
        @par Constraints
 
2472 + 
        @code
 
2473 + 
        std::is_arithmetic< T >::value && ! std::is_same< T, bool >::value
 
2474 + 
        @endcode
 
2475 +
 
2476 + 
        @par Complexity
 
2477 + 
        Constant.
 
2478 +
 
2479 + 
        @return The converted number.
 
2480 +
 
2481 + 
        @throw `boost::system::system_error` Thrown on error.
 
2482 + 
    */
 
2483 + 
    template<class T>
 
2484 + 
#ifdef BOOST_JSON_DOCS
 
2485 + 
    T
 
2486 + 
#else
 
2487 + 
    typename std::enable_if<
 
2488 + 
        std::is_arithmetic<T>::value &&
 
2489 + 
        ! std::is_same<T, bool>::value,
 
2490 + 
            T>::type
 
2491 + 
#endif
 
2492 + 
    to_number() const
 
2493 + 
    {
 
2494 + 
        return try_to_number<T>().value();
 
2495 + 
    }
 
2496 +
1794   
    //------------------------------------------------------
2497   
    //------------------------------------------------------
1795   
    //
2498   
    //
1796   
    // Accessors
2499   
    // Accessors
1797   
    //
2500   
    //
1798   
    //------------------------------------------------------
2501   
    //------------------------------------------------------
1799  
2502  
1800   
    /** Return the associated memory resource.
2503   
    /** Return the associated memory resource.
1801  
2504  
1802 - 
        This function returns a smart pointer to the
2505 + 
        This function returns the `boost::container::pmr::memory_resource` used
1803 - 
        @ref boost::container::pmr::memory_resource used by the container.
2506 + 
        by the container.
1804  
2507  
1805   
        @par Complexity
2508   
        @par Complexity
1806   
        Constant.
2509   
        Constant.
1807  
2510  
1808   
        @par Exception Safety
2511   
        @par Exception Safety
1809   
        No-throw guarantee.
2512   
        No-throw guarantee.
1810   
    */
2513   
    */
1811   
    storage_ptr const&
2514   
    storage_ptr const&
1812   
    storage() const noexcept
2515   
    storage() const noexcept
1813   
    {
2516   
    {
1814   
        return sp_;
2517   
        return sp_;
1815   
    }
2518   
    }
1816  
2519  
1817   
    /** Return the associated allocator.
2520   
    /** Return the associated allocator.
1818  
2521  
1819   
        This function returns an instance of @ref allocator_type constructed
2522   
        This function returns an instance of @ref allocator_type constructed
1820 - 
        from the associated @ref boost::container::pmr::memory_resource.
2523 + 
        from the associated `boost::container::pmr::memory_resource`.
1821  
2524  
1822   
        @par Complexity
2525   
        @par Complexity
1823   
        Constant.
2526   
        Constant.
1824  
2527  
1825   
        @par Exception Safety
2528   
        @par Exception Safety
1826   
        No-throw guarantee.
2529   
        No-throw guarantee.
1827   
    */
2530   
    */
1828   
    allocator_type
2531   
    allocator_type
1829   
    get_allocator() const noexcept
2532   
    get_allocator() const noexcept
1830   
    {
2533   
    {
1831   
        return sp_.get();
2534   
        return sp_.get();
1832   
    }
2535   
    }
1833  
2536  
1834   
    //------------------------------------------------------
2537   
    //------------------------------------------------------
1835  
2538  
1836   
    /** Return `result` with a reference to the underlying @ref array
2539   
    /** Return `result` with a reference to the underlying @ref array
1837  
2540  
1838   
        If @ref is_array() is `true`, the result contains a reference to the
2541   
        If @ref is_array() is `true`, the result contains a reference to the
1839   
        underlying @ref array, otherwise it contains an `error_code`.
2542   
        underlying @ref array, otherwise it contains an `error_code`.
1840  
2543  
1841   
        @par Example
2544   
        @par Example
1842   
        The return value can be used in both a boolean context and
2545   
        The return value can be used in both a boolean context and
1843   
        to assign a variable:
2546   
        to assign a variable:
1844   
        @code
2547   
        @code
1845   
        if( auto r = jv.try_as_array() )
2548   
        if( auto r = jv.try_as_array() )
1846   
            return *r;
2549   
            return *r;
1847   
        @endcode
2550   
        @endcode
1848  
2551  
1849   
        But can also be used to throw an exception on error:
2552   
        But can also be used to throw an exception on error:
1850   
        @code
2553   
        @code
1851   
        return jv.try_as_array().value();
2554   
        return jv.try_as_array().value();
1852   
        @endcode
2555   
        @endcode
1853  
2556  
1854   
        @par Complexity
2557   
        @par Complexity
1855   
        Constant.
2558   
        Constant.
1856  
2559  
1857   
        @par Exception Safety
2560   
        @par Exception Safety
1858 -
 
1859 - 
        @{
 
1860   
        No-throw guarantee.
2561   
        No-throw guarantee.
1861   
    */
2562   
    */
 
2563 + 
    /** @{ */
1862   
    BOOST_JSON_DECL
2564   
    BOOST_JSON_DECL
1863   
    system::result<array&>
2565   
    system::result<array&>
1864   
    try_as_array() noexcept;
2566   
    try_as_array() noexcept;
1865  
2567  
1866   
    BOOST_JSON_DECL
2568   
    BOOST_JSON_DECL
1867   
    system::result<array const&>
2569   
    system::result<array const&>
1868   
    try_as_array() const noexcept;
2570   
    try_as_array() const noexcept;
1869 - 
    /// @}
2571 + 
    /** @} */
1870  
2572  
1871 - 
    /** Return `result` with a reference to the underlying @ref object.
2573 + 
    /** Return `result` with a reference to the underlying @ref object
1872  
2574  
1873   
        If @ref is_object() is `true`, the result contains a reference to the
2575   
        If @ref is_object() is `true`, the result contains a reference to the
1874   
        underlying @ref object, otherwise it contains an `error_code`.
2576   
        underlying @ref object, otherwise it contains an `error_code`.
1875  
2577  
1876   
        @par Example
2578   
        @par Example
1877   
        The return value can be used in both a boolean context and
2579   
        The return value can be used in both a boolean context and
1878   
        to assign a variable:
2580   
        to assign a variable:
1879   
        @code
2581   
        @code
1880   
        if( auto r = jv.try_as_object() )
2582   
        if( auto r = jv.try_as_object() )
1881   
            return *r;
2583   
            return *r;
1882   
        @endcode
2584   
        @endcode
1883  
2585  
1884   
        But can also be used to throw an exception on error:
2586   
        But can also be used to throw an exception on error:
1885   
        @code
2587   
        @code
1886   
        return jv.try_as_object().value();
2588   
        return jv.try_as_object().value();
1887   
        @endcode
2589   
        @endcode
1888  
2590  
1889   
        @par Complexity
2591   
        @par Complexity
1890   
        Constant.
2592   
        Constant.
1891  
2593  
1892   
        @par Exception Safety
2594   
        @par Exception Safety
1893 -
 
1894 - 
        @{
 
1895   
        No-throw guarantee.
2595   
        No-throw guarantee.
1896   
    */
2596   
    */
 
2597 + 
    /** @{ */
1897   
    BOOST_JSON_DECL
2598   
    BOOST_JSON_DECL
1898   
    system::result<object&>
2599   
    system::result<object&>
1899   
    try_as_object() noexcept;
2600   
    try_as_object() noexcept;
1900  
2601  
1901   
    BOOST_JSON_DECL
2602   
    BOOST_JSON_DECL
1902   
    system::result<object const&>
2603   
    system::result<object const&>
1903   
    try_as_object() const noexcept;
2604   
    try_as_object() const noexcept;
1904 - 
    /// @}
2605 + 
    /** @} */
1905  
2606  
1906 - 
    /** Return `result` with a reference to the underlying @ref string.
2607 + 
    /** Return `result` with a reference to the underlying @ref string
1907  
2608  
1908   
        If @ref is_string() is `true`, the result contains a reference to the
2609   
        If @ref is_string() is `true`, the result contains a reference to the
1909   
        underlying @ref string, otherwise it contains an `error_code`.
2610   
        underlying @ref string, otherwise it contains an `error_code`.
1910  
2611  
1911   
        @par Example
2612   
        @par Example
1912   
        The return value can be used in both a boolean context and
2613   
        The return value can be used in both a boolean context and
1913   
        to assign a variable:
2614   
        to assign a variable:
1914   
        @code
2615   
        @code
1915   
        if( auto r = jv.try_as_string() )
2616   
        if( auto r = jv.try_as_string() )
1916   
            return *r;
2617   
            return *r;
1917   
        @endcode
2618   
        @endcode
1918  
2619  
1919   
        But can also be used to throw an exception on error:
2620   
        But can also be used to throw an exception on error:
1920   
        @code
2621   
        @code
1921   
        return jv.try_as_string().value();
2622   
        return jv.try_as_string().value();
1922   
        @endcode
2623   
        @endcode
1923  
2624  
1924   
        @par Complexity
2625   
        @par Complexity
1925   
        Constant.
2626   
        Constant.
1926  
2627  
1927   
        @par Exception Safety
2628   
        @par Exception Safety
1928 -
 
1929 - 
        @{
 
1930   
        No-throw guarantee.
2629   
        No-throw guarantee.
1931   
    */
2630   
    */
 
2631 + 
    /** @{ */
1932   
    BOOST_JSON_DECL
2632   
    BOOST_JSON_DECL
1933   
    system::result<string&>
2633   
    system::result<string&>
1934   
    try_as_string() noexcept;
2634   
    try_as_string() noexcept;
1935  
2635  
1936   
    BOOST_JSON_DECL
2636   
    BOOST_JSON_DECL
1937   
    system::result<string const&>
2637   
    system::result<string const&>
1938   
    try_as_string() const noexcept;
2638   
    try_as_string() const noexcept;
1939 - 
    /// @}
2639 + 
    /** @} */
1940  
2640  
1941 - 
    /** Return `result` with the underlying `std::int64_t`
2641 + 
    /** Return `result` with a reference to the underlying `std::int64_t`
1942  
2642  
1943 - 
        If @ref is_int64() is `true`, the result contains a reference to **(1)**
2643 + 
        If @ref is_int64() is `true`, the result contains a reference to the
1944 - 
        or a copy of **(2)** the underlying `std::int64_t`, otherwise it
2644 + 
        underlying `std::int64_t`, otherwise it contains an `error_code`.
1945 - 
        contains an `error_code`.
 
1946  
2645  
1947   
        @par Example
2646   
        @par Example
1948   
        The return value can be used in both a boolean context and
2647   
        The return value can be used in both a boolean context and
1949   
        to assign a variable:
2648   
        to assign a variable:
1950   
        @code
2649   
        @code
1951   
        if( auto r = jv.try_as_int64() )
2650   
        if( auto r = jv.try_as_int64() )
1952   
            return *r;
2651   
            return *r;
1953   
        @endcode
2652   
        @endcode
1954  
2653  
1955   
        But can also be used to throw an exception on error:
2654   
        But can also be used to throw an exception on error:
1956   
        @code
2655   
        @code
1957   
        return jv.try_as_int64().value();
2656   
        return jv.try_as_int64().value();
1958   
        @endcode
2657   
        @endcode
1959  
2658  
1960   
        @par Complexity
2659   
        @par Complexity
1961   
        Constant.
2660   
        Constant.
1962  
2661  
1963   
        @par Exception Safety
2662   
        @par Exception Safety
1964 -
 
1965 - 
        @{
 
1966   
        No-throw guarantee.
2663   
        No-throw guarantee.
1967   
    */
2664   
    */
1968   
    BOOST_JSON_DECL
2665   
    BOOST_JSON_DECL
1969   
    system::result<std::int64_t&>
2666   
    system::result<std::int64_t&>
1970   
    try_as_int64() noexcept;
2667   
    try_as_int64() noexcept;
1971  
2668  
 
2669 + 
    /** Return `result` with the underlying `std::int64_t`
 
2670 +
 
2671 + 
        If @ref is_int64() is `true`, the result contains a copy of the
 
2672 + 
        underlying `std::int64_t`, otherwise it contains an `error_code`.
 
2673 +
 
2674 + 
        @par Example
 
2675 + 
        The return value can be used in both a boolean context and
 
2676 + 
        to assign a variable:
 
2677 + 
        @code
 
2678 + 
        if( auto r = jv.try_as_int64() )
 
2679 + 
            return *r;
 
2680 + 
        @endcode
 
2681 +
 
2682 + 
        But can also be used to throw an exception on error:
 
2683 + 
        @code
 
2684 + 
        return jv.try_as_int64().value();
 
2685 + 
        @endcode
 
2686 +
 
2687 + 
        @par Complexity
 
2688 + 
        Constant.
 
2689 +
 
2690 + 
        @par Exception Safety
 
2691 + 
        No-throw guarantee.
 
2692 + 
    */
1972   
    BOOST_JSON_DECL
2693   
    BOOST_JSON_DECL
1973   
    system::result<std::int64_t>
2694   
    system::result<std::int64_t>
1974 - 
    /// @}
 
1975   
    try_as_int64() const noexcept;
2695   
    try_as_int64() const noexcept;
1976  
2696  
1977 - 
    /** Return `result` with the underlying `std::uint64_t`.
2697 + 
    /** Return `result` with a reference to the underlying `std::uint64_t`
1978  
2698  
1979 - 
        If @ref is_uint64() is `true`, the result contains a reference to **(1)**
2699 + 
        If @ref is_uint64() is `true`, the result contains a reference to the
1980 - 
        or a copy of **(2)** the underlying `std::uint64_t`, otherwise it
2700 + 
        underlying `std::uint64_t`, otherwise it contains an `error_code`.
1981 - 
        contains an `error_code`.
 
1982  
2701  
1983   
        @par Example
2702   
        @par Example
1984   
        The return value can be used in both a boolean context and
2703   
        The return value can be used in both a boolean context and
1985   
        to assign a variable:
2704   
        to assign a variable:
1986   
        @code
2705   
        @code
1987   
        if( auto r = jv.try_as_uint64() )
2706   
        if( auto r = jv.try_as_uint64() )
1988   
            return *r;
2707   
            return *r;
1989   
        @endcode
2708   
        @endcode
1990  
2709  
1991   
        But can also be used to throw an exception on error:
2710   
        But can also be used to throw an exception on error:
1992   
        @code
2711   
        @code
1993   
        return jv.try_as_uint64().value();
2712   
        return jv.try_as_uint64().value();
1994   
        @endcode
2713   
        @endcode
1995  
2714  
1996   
        @par Complexity
2715   
        @par Complexity
1997   
        Constant.
2716   
        Constant.
1998  
2717  
1999   
        @par Exception Safety
2718   
        @par Exception Safety
2000 -
 
2001 - 
        @{
 
2002   
        No-throw guarantee.
2719   
        No-throw guarantee.
2003   
    */
2720   
    */
2004   
    BOOST_JSON_DECL
2721   
    BOOST_JSON_DECL
2005   
    system::result<std::uint64_t&>
2722   
    system::result<std::uint64_t&>
2006   
    try_as_uint64() noexcept;
2723   
    try_as_uint64() noexcept;
2007  
2724  
 
2725 + 
    /** Return `result` with the underlying `std::uint64_t`
 
2726 +
 
2727 + 
        If @ref is_uint64() is `true`, the result contains a copy of the
 
2728 + 
        underlying `std::uint64_t`, otherwise it contains an `error_code`.
 
2729 +
 
2730 + 
        @par Example
 
2731 + 
        The return value can be used in both a boolean context and
 
2732 + 
        to assign a variable:
 
2733 + 
        @code
 
2734 + 
        if( auto r = jv.try_as_uint64() )
 
2735 + 
            return *r;
 
2736 + 
        @endcode
 
2737 +
 
2738 + 
        But can also be used to throw an exception on error:
 
2739 + 
        @code
 
2740 + 
        return jv.try_as_uint64().value();
 
2741 + 
        @endcode
 
2742 +
 
2743 + 
        @par Complexity
 
2744 + 
        Constant.
 
2745 +
 
2746 + 
        @par Exception Safety
 
2747 + 
        No-throw guarantee.
 
2748 + 
    */
2008   
    BOOST_JSON_DECL
2749   
    BOOST_JSON_DECL
2009   
    system::result<std::uint64_t>
2750   
    system::result<std::uint64_t>
2010 - 
    /// @}
 
2011   
    try_as_uint64() const noexcept;
2751   
    try_as_uint64() const noexcept;
2012  
2752  
2013 - 
    /** Return `result` with the underlying `double`
2753 + 
    /** Return `result` with a reference to the underlying `double`
2014  
2754  
2015 - 
        If @ref is_double() is `true`, the result contains a reference to **(1)**
2755 + 
        If @ref is_double() is `true`, the result contains a reference to the
2016 - 
        or a copy of **(2)** the underlying `double`, otherwise it
2756 + 
        underlying `double`, otherwise it contains an `error_code`.
2017 - 
        contains an `error_code`.
 
2018  
2757  
2019   
        @par Example
2758   
        @par Example
2020   
        The return value can be used in both a boolean context and
2759   
        The return value can be used in both a boolean context and
2021   
        to assign a variable:
2760   
        to assign a variable:
2022   
        @code
2761   
        @code
2023   
        if( auto r = jv.try_as_double() )
2762   
        if( auto r = jv.try_as_double() )
2024   
            return *r;
2763   
            return *r;
2025   
        @endcode
2764   
        @endcode
2026  
2765  
2027   
        But can also be used to throw an exception on error:
2766   
        But can also be used to throw an exception on error:
2028   
        @code
2767   
        @code
2029   
        return jv.try_as_double().value();
2768   
        return jv.try_as_double().value();
2030   
        @endcode
2769   
        @endcode
2031  
2770  
2032   
        @par Complexity
2771   
        @par Complexity
2033   
        Constant.
2772   
        Constant.
2034  
2773  
2035   
        @par Exception Safety
2774   
        @par Exception Safety
2036 -
 
2037 - 
        @{
 
2038   
        No-throw guarantee.
2775   
        No-throw guarantee.
2039   
    */
2776   
    */
2040   
    BOOST_JSON_DECL
2777   
    BOOST_JSON_DECL
2041   
    system::result<double&>
2778   
    system::result<double&>
2042   
    try_as_double() noexcept;
2779   
    try_as_double() noexcept;
2043  
2780  
 
2781 + 
    /** Return `result` with the underlying `double`
 
2782 +
 
2783 + 
        If @ref is_double() is `true`, the result contains a copy of the
 
2784 + 
        underlying `double`, otherwise it contains an `error_code`.
 
2785 +
 
2786 + 
        @par Example
 
2787 + 
        The return value can be used in both a boolean context and
 
2788 + 
        to assign a variable:
 
2789 + 
        @code
 
2790 + 
        if( auto r = jv.try_as_double() )
 
2791 + 
            return *r;
 
2792 + 
        @endcode
 
2793 +
 
2794 + 
        But can also be used to throw an exception on error:
 
2795 + 
        @code
 
2796 + 
        return jv.try_as_double().value();
 
2797 + 
        @endcode
 
2798 +
 
2799 + 
        @par Complexity
 
2800 + 
        Constant.
 
2801 +
 
2802 + 
        @par Exception Safety
 
2803 + 
        No-throw guarantee.
 
2804 + 
    */
2044   
    BOOST_JSON_DECL
2805   
    BOOST_JSON_DECL
2045   
    system::result<double>
2806   
    system::result<double>
2046 - 
    /// @}
 
2047   
    try_as_double() const noexcept;
2807   
    try_as_double() const noexcept;
2048  
2808  
2049 - 
    /** Return `result` with the underlying `bool`
2809 + 
    /** Return `result` with a reference to the underlying `bool`
2050  
2810  
2051 - 
        If @ref is_bool() is `true`, the result contains a reference to **(1)**
2811 + 
        If @ref is_bool() is `true`, the result contains a reference to the
2052 - 
        or a copy to **(2)** the underlying `bool`, otherwise it contains an
2812 + 
        underlying `bool`, otherwise it contains an `error_code`.
2053 - 
        `error_code`.
 
2054  
2813  
2055   
        @par Example
2814   
        @par Example
2056   
        The return value can be used in both a boolean context and
2815   
        The return value can be used in both a boolean context and
2057   
        to assign a variable:
2816   
        to assign a variable:
2058   
        @code
2817   
        @code
2059   
        if( auto r = jv.try_as_bool() )
2818   
        if( auto r = jv.try_as_bool() )
2060   
            return *r;
2819   
            return *r;
2061   
        @endcode
2820   
        @endcode
2062  
2821  
2063   
        But can also be used to throw an exception on error:
2822   
        But can also be used to throw an exception on error:
2064   
        @code
2823   
        @code
2065   
        return jv.try_as_bool().value();
2824   
        return jv.try_as_bool().value();
2066   
        @endcode
2825   
        @endcode
2067  
2826  
2068   
        @par Complexity
2827   
        @par Complexity
2069   
        Constant.
2828   
        Constant.
2070  
2829  
2071   
        @par Exception Safety
2830   
        @par Exception Safety
2072 -
 
2073 - 
        @{
 
2074   
        No-throw guarantee.
2831   
        No-throw guarantee.
2075   
    */
2832   
    */
2076   
    BOOST_JSON_DECL
2833   
    BOOST_JSON_DECL
2077   
    system::result<bool&>
2834   
    system::result<bool&>
2078   
    try_as_bool() noexcept;
2835   
    try_as_bool() noexcept;
2079  
2836  
 
2837 + 
    /** Return `result` with the underlying `bool`
 
2838 +
 
2839 + 
        If @ref is_bool() is `true`, the result contains a copy of the
 
2840 + 
        underlying `bool`, otherwise it contains an `error_code`.
 
2841 +
 
2842 + 
        @par Example
 
2843 + 
        The return value can be used in both a boolean context and
 
2844 + 
        to assign a variable:
 
2845 + 
        @code
 
2846 + 
        if( auto r = jv.try_as_bool() )
 
2847 + 
            return *r;
 
2848 + 
        @endcode
 
2849 +
 
2850 + 
        But can also be used to throw an exception on error:
 
2851 + 
        @code
 
2852 + 
        return jv.try_as_bool().value();
 
2853 + 
        @endcode
 
2854 +
 
2855 + 
        @par Complexity
 
2856 + 
        Constant.
 
2857 +
 
2858 + 
        @par Exception Safety
 
2859 + 
        No-throw guarantee.
 
2860 + 
    */
2080   
    BOOST_JSON_DECL
2861   
    BOOST_JSON_DECL
2081   
    system::result<bool>
2862   
    system::result<bool>
2082 - 
    /// @}
 
2083   
    try_as_bool() const noexcept;
2863   
    try_as_bool() const noexcept;
2084  
2864  
2085 - 
    /** Return engaged `result` if the `value` is null.
2865 + 
    /** Return engaged `result` if the `value` is null
2086  
2866  
2087   
        If @ref is_null() is `true`, the result is engaged, otherwise it
2867   
        If @ref is_null() is `true`, the result is engaged, otherwise it
2088   
        contains an `error_code`.
2868   
        contains an `error_code`.
2089  
2869  
2090   
        @par Example
2870   
        @par Example
2091   
        The return value can be used in both a boolean context and
2871   
        The return value can be used in both a boolean context and
2092   
        to assign a variable:
2872   
        to assign a variable:
2093   
        @code
2873   
        @code
2094   
        if( auto r = jv.try_as_null() )
2874   
        if( auto r = jv.try_as_null() )
2095   
            return *r;
2875   
            return *r;
2096   
        @endcode
2876   
        @endcode
2097  
2877  
2098   
        But can also be used to throw an exception on error:
2878   
        But can also be used to throw an exception on error:
2099   
        @code
2879   
        @code
2100   
        return jv.try_as_null().value();
2880   
        return jv.try_as_null().value();
2101   
        @endcode
2881   
        @endcode
2102  
2882  
2103   
        @par Complexity
2883   
        @par Complexity
2104   
        Constant.
2884   
        Constant.
2105  
2885  
2106   
        @par Exception Safety
2886   
        @par Exception Safety
2107   
        No-throw guarantee.
2887   
        No-throw guarantee.
2108   
    */
2888   
    */
2109   
    BOOST_JSON_DECL
2889   
    BOOST_JSON_DECL
2110   
    system::result<std::nullptr_t>
2890   
    system::result<std::nullptr_t>
2111   
    try_as_null() const noexcept;
2891   
    try_as_null() const noexcept;
2112  
2892  
2113   
    //------------------------------------------------------
2893   
    //------------------------------------------------------
2114  
2894  
2115 - 
    /** Return the underlying @ref object, or throw an exception.
2895 + 
    /** Return a reference to the underlying `object`, or throw an exception.
2116  
2896  
2117 - 
        If @ref is_object() is `true`, returns a reference to the underlying
2897 + 
        If @ref is_object() is `true`, returns
2118 - 
        @ref object, otherwise throws an exception.
2898 + 
        a reference to the underlying @ref object,
 
2899 + 
        otherwise throws an exception.
2119  
2900  
2120   
        @par Exception Safety
2901   
        @par Exception Safety
2121   
        Strong guarantee.
2902   
        Strong guarantee.
2122  
2903  
2123 - 
        @throw boost::system::system_error `! this->is_object()`.
2904 + 
        @throw `boost::system::system_error` `! this->is_object()`.
2124  
2905  
2125 - 
        @param loc @ref boost::source_location to use in thrown exception; the
2906 + 
        @param loc `source_location` to use in thrown exception; the source
2126 - 
               source location of the call site by default.
2907 + 
            location of the call site by default.
2127  
2908  
2128   
        @par Complexity
2909   
        @par Complexity
2129 -
 
2130 - 
        @{
 
2131   
        Constant.
2910   
        Constant.
2132   
    */
2911   
    */
 
2912 + 
    /** @{ */
2133   
    object&
2913   
    object&
2134   
    as_object(source_location const& loc = BOOST_CURRENT_LOCATION) &
2914   
    as_object(source_location const& loc = BOOST_CURRENT_LOCATION) &
2135   
    {
2915   
    {
2136   
        auto& self = const_cast<value const&>(*this);
2916   
        auto& self = const_cast<value const&>(*this);
2137   
        return const_cast<object&>( self.as_object(loc) );
2917   
        return const_cast<object&>( self.as_object(loc) );
2138   
    }
2918   
    }
2139 - 
    /// Overload
 
2140  
2919  
2141   
    object&&
2920   
    object&&
2142   
    as_object(source_location const& loc = BOOST_CURRENT_LOCATION) &&
2921   
    as_object(source_location const& loc = BOOST_CURRENT_LOCATION) &&
2143   
    {
2922   
    {
2144   
        return std::move( as_object(loc) );
2923   
        return std::move( as_object(loc) );
2145   
    }
2924   
    }
2146 - 
    /// Overload
 
2147  
2925  
2148   
    BOOST_JSON_DECL
2926   
    BOOST_JSON_DECL
2149   
    object const&
2927   
    object const&
2150   
    as_object(source_location const& loc = BOOST_CURRENT_LOCATION) const&;
2928   
    as_object(source_location const& loc = BOOST_CURRENT_LOCATION) const&;
2151 - 
    /// @}
2929 + 
    /** @} */
2152  
2930  
2153 - 
    /** Return the underlying @ref array, or throw an exception.
2931 + 
    /** Return a reference to the underlying @ref array, or throw an exception.
2154  
2932  
2155 - 
        If @ref is_array() is `true`, returns a reference to the underlying
2933 + 
        If @ref is_array() is `true`, returns
2156 - 
        @ref array, otherwise throws an exception.
2934 + 
        a reference to the underlying @ref array,
 
2935 + 
        otherwise throws an exception.
2157  
2936  
2158   
        @par Exception Safety
2937   
        @par Exception Safety
2159   
        Strong guarantee.
2938   
        Strong guarantee.
2160  
2939  
2161 - 
        @throw boost::system::system_error `! this->is_array()`.
2940 + 
        @throw `boost::system::system_error` `! this->is_array()`.
2162  
2941  
2163 - 
        @param loc @ref boost::source_location to use in thrown exception; the
2942 + 
        @param loc `source_location` to use in thrown exception; the source
2164 - 
               source location of the call site by default.
2943 + 
            location of the call site by default.
2165  
2944  
2166   
        @par Complexity
2945   
        @par Complexity
2167 -
 
2168 - 
        @{
 
2169   
        Constant.
2946   
        Constant.
2170   
    */
2947   
    */
 
2948 + 
    /** @{ */
2171   
    array&
2949   
    array&
2172   
    as_array(source_location const& loc = BOOST_CURRENT_LOCATION) &
2950   
    as_array(source_location const& loc = BOOST_CURRENT_LOCATION) &
2173   
    {
2951   
    {
2174   
        auto& self = const_cast<value const&>(*this);
2952   
        auto& self = const_cast<value const&>(*this);
2175   
        return const_cast<array&>( self.as_array(loc) );
2953   
        return const_cast<array&>( self.as_array(loc) );
2176   
    }
2954   
    }
2177 - 
    /// Overload
 
2178  
2955  
2179   
    array&&
2956   
    array&&
2180   
    as_array(source_location const& loc = BOOST_CURRENT_LOCATION) &&
2957   
    as_array(source_location const& loc = BOOST_CURRENT_LOCATION) &&
2181   
    {
2958   
    {
2182   
        return std::move( as_array(loc) );
2959   
        return std::move( as_array(loc) );
2183   
    }
2960   
    }
2184 - 
    /// Overload
 
2185  
2961  
2186   
    BOOST_JSON_DECL
2962   
    BOOST_JSON_DECL
2187   
    array const&
2963   
    array const&
2188   
    as_array(source_location const& loc = BOOST_CURRENT_LOCATION) const&;
2964   
    as_array(source_location const& loc = BOOST_CURRENT_LOCATION) const&;
2189 - 
    /// @}
2965 + 
    /** @} */
2190  
2966  
2191 - 
    /** Return the underlying @ref string, or throw an exception.
2967 + 
    /** Return a reference to the underlying `string`, or throw an exception.
2192  
2968  
2193 - 
        If @ref is_string() is `true`, returns a reference to the underlying
2969 + 
        If @ref is_string() is `true`, returns
2194 - 
        @ref string, otherwise throws an exception.
2970 + 
        a reference to the underlying @ref string,
 
2971 + 
        otherwise throws an exception.
2195  
2972  
2196   
        @par Exception Safety
2973   
        @par Exception Safety
2197   
        Strong guarantee.
2974   
        Strong guarantee.
2198  
2975  
2199 - 
        @throw boost::system::system_error `! this->is_string()`.
2976 + 
        @throw `boost::system::system_error` `! this->is_string()`.
2200  
2977  
2201 - 
        @param loc @ref boost::source_location to use in thrown exception; the
2978 + 
        @param loc `source_location` to use in thrown exception; the source
2202 - 
               source location of the call site by default.
2979 + 
            location of the call site by default.
2203  
2980  
2204   
        @par Complexity
2981   
        @par Complexity
2205 -
 
2206 - 
        @{
 
2207   
        Constant.
2982   
        Constant.
2208   
    */
2983   
    */
2209   
    string&
2984   
    string&
2210   
    as_string(source_location const& loc = BOOST_CURRENT_LOCATION) &
2985   
    as_string(source_location const& loc = BOOST_CURRENT_LOCATION) &
2211   
    {
2986   
    {
2212   
        auto& self = const_cast<value const&>(*this);
2987   
        auto& self = const_cast<value const&>(*this);
2213   
        return const_cast<string&>( self.as_string(loc) );
2988   
        return const_cast<string&>( self.as_string(loc) );
2214   
    }
2989   
    }
2215  
2990  
2216 - 
    /// Overload
2991 + 
    /** Return a reference to the underlying `string`, or throw an exception.
 
2992 +
 
2993 + 
        If @ref is_string() is `true`, returns
 
2994 + 
        a reference to the underlying @ref string,
 
2995 + 
        otherwise throws an exception.
 
2996 +
 
2997 + 
        @par Exception Safety
 
2998 + 
        Strong guarantee.
 
2999 +
 
3000 + 
        @throw `boost::system::system_error` `! this->is_string()`.
 
3001 +
 
3002 + 
        @param loc `source_location` to use in thrown exception; the source
 
3003 + 
            location of the call site by default.
 
3004 +
 
3005 + 
        @par Complexity
 
3006 + 
        Constant.
 
3007 + 
    */
 
3008 + 
    /** @{ */
2217   
    string&&
3009   
    string&&
2218   
    as_string(source_location const& loc = BOOST_CURRENT_LOCATION) &&
3010   
    as_string(source_location const& loc = BOOST_CURRENT_LOCATION) &&
2219   
    {
3011   
    {
2220   
        return std::move( as_string(loc) );
3012   
        return std::move( as_string(loc) );
2221   
    }
3013   
    }
2222 - 
    /// Overload
 
2223  
3014  
2224   
    BOOST_JSON_DECL
3015   
    BOOST_JSON_DECL
2225   
    string const&
3016   
    string const&
2226 - 
    /// @}
 
2227   
    as_string(source_location const& loc = BOOST_CURRENT_LOCATION) const&;
3017   
    as_string(source_location const& loc = BOOST_CURRENT_LOCATION) const&;
2228  
3018  
2229 - 
    /** Return the underlying `std::int64_t`, or throw an exception.
3019 + 
    BOOST_JSON_DECL
 
3020 + 
    std::int64_t&
 
3021 + 
    as_int64(source_location const& loc = BOOST_CURRENT_LOCATION);
 
3022 + 
    /** @} */
2230  
3023  
2231 - 
        If @ref is_int64() is `true`, returns a reference to **(1)** or a copy
3024 + 
    /** Return the underlying `std::int64_t`, or throw an exception.
2232 - 
        of **(2)** the underlying `std::int64_t`, otherwise throws an
 
2233 - 
        exception.
 
2234  
3025  
2235 - 
        @note This function is the intended for direct access to the underlying
3026 + 
        If @ref is_int64() is `true`, returns
2236 - 
        object, __if__ it has the type `std::int64_t`. It does not convert the
3027 + 
        the underlying `std::int64_t`,
2237 - 
        underlying object to the type `std::int64_t` even if a lossless
3028 + 
        otherwise throws an exception.
2238 - 
        conversion is possible. If you are not sure which kind your `value`
 
2239 - 
        has, and you only care about getting a `std::int64_t` number, consider
 
2240 - 
        using @ref to_number instead.
 
2241  
3029  
2242   
        @par Exception Safety
3030   
        @par Exception Safety
2243   
        Strong guarantee.
3031   
        Strong guarantee.
2244  
3032  
2245 - 
        @throw boost::system::system_error `! this->is_int64()`.
3033 + 
        @throw `boost::system::system_error` `! this->is_int64()`.
2246  
3034  
2247 - 
        @param loc @ref boost::source_location to use in thrown exception; the
3035 + 
        @param loc `source_location` to use in thrown exception; the source
2248 - 
               source location of the call site by default.
3036 + 
            location of the call site by default.
2249  
3037  
2250   
        @par Complexity
3038   
        @par Complexity
2251   
        Constant.
3039   
        Constant.
2252  
3040  
2253 - 
        @{
3041 + 
        @par Note
 
3042 + 
        This function is the const-qualified overload of @ref as_int64, which
 
3043 + 
        is intended for direct access to the underlying object, __if__ it has
 
3044 + 
        the type `std::int64_t`. It does not convert the underlying object to
 
3045 + 
        type `std::int64_t` even if a lossless conversion is possible. If you
 
3046 + 
        are not sure which kind your `value` has, and you only care about
 
3047 + 
        getting a `std::int64_t` number, consider using @ref to_number instead.
2254   
    */
3048   
    */
2255 - 
    std::int64_t&
 
2256 - 
    as_int64(source_location const& loc = BOOST_CURRENT_LOCATION);
 
2257 -
 
2258 - 
    /// Overload
 
2259 - 
    BOOST_JSON_DECL
 
2260   
    BOOST_JSON_DECL
3049   
    BOOST_JSON_DECL
2261   
    std::int64_t
3050   
    std::int64_t
2262 - 
    /// @}
 
2263 -
 
2264 - 
    /** Return the underlying `std::uint64_t`, or throw an exception.
 
2265   
    as_int64(source_location const& loc = BOOST_CURRENT_LOCATION) const;
3051   
    as_int64(source_location const& loc = BOOST_CURRENT_LOCATION) const;
2266  
3052  
2267 - 
        If @ref is_uint64() is `true`, returns a reference to **(1)** or a
3053 + 
    /** Return a reference to the underlying `std::uint64_t`, or throw an exception.
2268 - 
        copy of **(2)** the underlying `std::uint64_t`, otherwise throws an
 
2269 - 
        exception.
 
2270  
3054  
2271 - 
        @note This function is intended for direct access to the underlying
3055 + 
        If @ref is_uint64() is `true`, returns
2272 - 
        object, __if__ it has the type `std::uint64_t`. It does not convert the
3056 + 
        a reference to the underlying `std::uint64_t`,
2273 - 
        underlying object to the type `std::uint64_t` even if a lossless
3057 + 
        otherwise throws an exception.
2274 - 
        conversion is possible. If you are not sure which kind your `value`
 
2275 - 
        has, and you only care about getting a `std::uint64_t` number, consider
 
2276 - 
        using @ref to_number instead.
 
2277  
3058  
2278   
        @par Exception Safety
3059   
        @par Exception Safety
2279   
        Strong guarantee.
3060   
        Strong guarantee.
2280  
3061  
2281 - 
        @throw boost::system::system_error `! this->is_uint64()`.
3062 + 
        @throw `boost::system::system_error` `! this->is_uint64()`.
2282  
3063  
2283 - 
        @param loc @ref boost::source_location to use in thrown exception; the
3064 + 
        @param loc `source_location` to use in thrown exception; the source
2284 - 
               source location of the call site by default.
3065 + 
            location of the call site by default.
2285  
3066  
2286   
        @par Complexity
3067   
        @par Complexity
2287   
        Constant.
3068   
        Constant.
2288  
3069  
2289 - 
        @{
3070 + 
        @par Note
 
3071 + 
        This function is intended for direct access to the underlying object,
 
3072 + 
        __if__ it has the type `std::uint64_t`. It does not convert the
 
3073 + 
        underlying object to type `std::uint64_t` even if a lossless conversion
 
3074 + 
        is possible. If you are not sure which kind your `value` has, and you
 
3075 + 
        only care about getting a `std::uint64_t` number, consider using
 
3076 + 
        @ref to_number instead.
2290   
    */
3077   
    */
2291   
    BOOST_JSON_DECL
3078   
    BOOST_JSON_DECL
2292   
    std::uint64_t&
3079   
    std::uint64_t&
2293   
    as_uint64(source_location const& loc = BOOST_CURRENT_LOCATION);
3080   
    as_uint64(source_location const& loc = BOOST_CURRENT_LOCATION);
2294  
3081  
2295 - 
    /// Overload
3082 + 
    /** Return the underlying `std::uint64_t`, or throw an exception.
 
3083 +
 
3084 + 
        If @ref is_uint64() is `true`, returns
 
3085 + 
        the underlying `std::uint64_t`,
 
3086 + 
        otherwise throws an exception.
 
3087 +
 
3088 + 
        @par Exception Safety
 
3089 + 
        Strong guarantee.
 
3090 +
 
3091 + 
        @throw `boost::system::system_error` `! this->is_uint64()`.
 
3092 +
 
3093 + 
        @param loc `source_location` to use in thrown exception; the source
 
3094 + 
            location of the call site by default.
 
3095 +
 
3096 + 
        @par Complexity
 
3097 + 
        Constant.
 
3098 +
 
3099 + 
        @par Note
 
3100 + 
        This function is the const-qualified overload of @ref as_uint64, which
 
3101 + 
        is intended for direct access to the underlying object, __if__ it has
 
3102 + 
        the type `std::uint64_t`. It does not convert the underlying object to
 
3103 + 
        type `std::uint64_t` even if a lossless conversion is possible. If you
 
3104 + 
        are not sure which kind your `value` has, and you only care about
 
3105 + 
        getting a `std::uint64_t` number, consider using
 
3106 + 
        @ref to_number instead.
 
3107 + 
    */
2296   
    BOOST_JSON_DECL
3108   
    BOOST_JSON_DECL
2297   
    std::uint64_t
3109   
    std::uint64_t
2298 - 
    /// @}
 
2299   
    as_uint64(source_location const& loc = BOOST_CURRENT_LOCATION) const;
3110   
    as_uint64(source_location const& loc = BOOST_CURRENT_LOCATION) const;
2300  
3111  
2301 - 
    /** Return the underlying `double`, or throw an exception.
3112 + 
    /** Return a reference to the underlying `double`, or throw an exception.
2302 -
 
2303 - 
        If @ref is_double() is `true`, returns a reference to **(1)** or a copy
 
2304 - 
        of **(2)** the underlying `double`, otherwise throws an exception.
 
2305  
3113  
2306 - 
        @note This function is intended for direct access to the underlying
3114 + 
        If @ref is_double() is `true`, returns
2307 - 
        object, __if__ it has the type `double`. It does not convert the
3115 + 
        a reference to the underlying `double`,
2308 - 
        underlying object to type `double` even if a lossless conversion is
3116 + 
        otherwise throws an exception.
2309 - 
        possible. If you are not sure which kind your `value` has, and you only
 
2310 - 
        care about getting a `double` number, consider using @ref to_number
 
2311 - 
        instead.
 
2312  
3117  
2313   
        @par Exception Safety
3118   
        @par Exception Safety
2314   
        Strong guarantee.
3119   
        Strong guarantee.
2315  
3120  
2316 - 
        @throw boost::system::system_error `! this->is_double()`.
3121 + 
        @throw `boost::system::system_error` `! this->is_double()`.
2317  
3122  
2318 - 
        @param loc @ref boost::source_location to use in thrown exception; the
3123 + 
        @param loc `source_location` to use in thrown exception; the source
2319 - 
               source location of the call site by default.
3124 + 
            location of the call site by default.
2320  
3125  
2321   
        @par Complexity
3126   
        @par Complexity
2322   
        Constant.
3127   
        Constant.
2323  
3128  
2324 - 
        @{
3129 + 
        @par Note
 
3130 + 
        This function is intended for direct access to the underlying object,
 
3131 + 
        __if__ it has the type `double`. It does not convert the underlying
 
3132 + 
        object to type `double` even if a lossless conversion is possible. If
 
3133 + 
        you are not sure which kind your `value` has, and you only care about
 
3134 + 
        getting a `double` number, consider using @ref to_number instead.
2325   
    */
3135   
    */
2326   
    BOOST_JSON_DECL
3136   
    BOOST_JSON_DECL
2327   
    double&
3137   
    double&
2328   
    as_double(source_location const& loc = BOOST_CURRENT_LOCATION);
3138   
    as_double(source_location const& loc = BOOST_CURRENT_LOCATION);
2329  
3139  
2330 - 
    /// Overload
3140 + 
    /** Return the underlying `double`, or throw an exception.
 
3141 +
 
3142 + 
        If @ref is_double() is `true`, returns
 
3143 + 
        the underlying `double`,
 
3144 + 
        otherwise throws an exception.
 
3145 +
 
3146 + 
        @par Exception Safety
 
3147 + 
        Strong guarantee.
 
3148 +
 
3149 + 
        @throw `boost::system::system_error` `! this->is_double()`.
 
3150 +
 
3151 + 
        @param loc `source_location` to use in thrown exception; the source
 
3152 + 
            location of the call site by default.
 
3153 +
 
3154 + 
        @par Complexity
 
3155 + 
        Constant.
 
3156 +
 
3157 + 
        @par Note
 
3158 + 
        This function is the const-qualified overload of @ref as_double, which
 
3159 + 
        is intended for direct access to the underlying object, __if__ it has
 
3160 + 
        the type `double`. It does not convert the underlying object to type
 
3161 + 
        `double` even if a lossless conversion is possible. If you are not sure
 
3162 + 
        which kind your `value` has, and you only care about getting a `double`
 
3163 + 
        number, consider using @ref to_number instead.
 
3164 + 
    */
2331   
    BOOST_JSON_DECL
3165   
    BOOST_JSON_DECL
2332   
    double
3166   
    double
2333 - 
    /// @}
 
2334   
    as_double(source_location const& loc = BOOST_CURRENT_LOCATION) const;
3167   
    as_double(source_location const& loc = BOOST_CURRENT_LOCATION) const;
2335  
3168  
2336 - 
    /** Return the underlying `bool`, or throw an exception.
3169 + 
    /** Return a reference to the underlying `bool`, or throw an exception.
2337  
3170  
2338 - 
        If @ref is_bool() is `true`, returns a reference to **(1)** or a copy
3171 + 
        If @ref is_bool() is `true`, returns
2339 - 
        of **(2)** the underlying `bool`, otherwise throws an exception.
3172 + 
        a reference to the underlying `bool`,
 
3173 + 
        otherwise throws an exception.
2340  
3174  
2341   
        @par Exception Safety
3175   
        @par Exception Safety
2342   
        Strong guarantee.
3176   
        Strong guarantee.
2343  
3177  
2344 - 
        @throw boost::system::system_error `! this->is_bool()`.
3178 + 
        @throw `boost::system::system_error` `! this->is_bool()`.
2345  
3179  
2346 - 
        @param loc @ref boost::source_location to use in thrown exception; the
3180 + 
        @param loc `source_location` to use in thrown exception; the source
2347 - 
               source location of the call site by default.
3181 + 
            location of the call site by default.
2348  
3182  
2349   
        @par Complexity
3183   
        @par Complexity
2350 -
 
2351 - 
        @{
 
2352   
        Constant.
3184   
        Constant.
2353   
    */
3185   
    */
2354   
    BOOST_JSON_DECL
3186   
    BOOST_JSON_DECL
2355   
    bool&
3187   
    bool&
2356   
    as_bool(source_location const& loc = BOOST_CURRENT_LOCATION);
3188   
    as_bool(source_location const& loc = BOOST_CURRENT_LOCATION);
2357  
3189  
2358 - 
    /// Overload
3190 + 
    /** Return the underlying `bool`, or throw an exception.
 
3191 +
 
3192 + 
        If @ref is_bool() is `true`, returns
 
3193 + 
        the underlying `bool`,
 
3194 + 
        otherwise throws an exception.
 
3195 +
 
3196 + 
        @par Exception Safety
 
3197 + 
        Strong guarantee.
 
3198 +
 
3199 + 
        @throw `boost::system::system_error` `! this->is_bool()`.
 
3200 +
 
3201 + 
        @param loc `source_location` to use in thrown exception; the source
 
3202 + 
            location of the call site by default.
 
3203 +
 
3204 + 
        @par Complexity
 
3205 + 
        Constant.
 
3206 + 
    */
2359   
    BOOST_JSON_DECL
3207   
    BOOST_JSON_DECL
2360   
    bool
3208   
    bool
2361 - 
    /// @}
 
2362   
    as_bool(source_location const& loc = BOOST_CURRENT_LOCATION) const;
3209   
    as_bool(source_location const& loc = BOOST_CURRENT_LOCATION) const;
2363  
3210  
2364   
    //------------------------------------------------------
3211   
    //------------------------------------------------------
2365  
3212  
2366 - 
    /** Return the underlying @ref object, without checking.
3213 + 
    /** Return a reference to the underlying `object`, without checking.
2367  
3214  
2368 - 
        This is the fastest way to access the underlying representation when
3215 + 
        This is the fastest way to access the underlying
2369 - 
        the kind is known in advance.
3216 + 
        representation when the kind is known in advance.
2370  
3217  
2371   
        @par Preconditions
3218   
        @par Preconditions
2372  
3219  
2373   
        @code
3220   
        @code
2374   
        this->is_object()
3221   
        this->is_object()
2375   
        @endcode
3222   
        @endcode
2376  
3223  
2377   
        @par Complexity
3224   
        @par Complexity
2378   
        Constant.
3225   
        Constant.
2379  
3226  
2380   
        @par Exception Safety
3227   
        @par Exception Safety
2381 -
 
2382 - 
        @{
 
2383   
        No-throw guarantee.
3228   
        No-throw guarantee.
2384   
    */
3229   
    */
 
3230 + 
    /** @{ */
2385   
    object&
3231   
    object&
2386   
    get_object() & noexcept
3232   
    get_object() & noexcept
2387   
    {
3233   
    {
2388   
        BOOST_ASSERT(is_object());
3234   
        BOOST_ASSERT(is_object());
2389   
        return obj_;
3235   
        return obj_;
2390   
    }
3236   
    }
2391  
3237  
2392   
    object&&
3238   
    object&&
2393   
    get_object() && noexcept
3239   
    get_object() && noexcept
2394   
    {
3240   
    {
2395   
        BOOST_ASSERT(is_object());
3241   
        BOOST_ASSERT(is_object());
2396   
        return std::move(obj_);
3242   
        return std::move(obj_);
2397   
    }
3243   
    }
2398  
3244  
2399   
    object const&
3245   
    object const&
2400   
    get_object() const& noexcept
3246   
    get_object() const& noexcept
2401   
    {
3247   
    {
2402   
        BOOST_ASSERT(is_object());
3248   
        BOOST_ASSERT(is_object());
2403   
        return obj_;
3249   
        return obj_;
2404   
    }
3250   
    }
2405 - 
    /// @}
3251 + 
    /** @} */
2406  
3252  
2407 - 
    /** Return the underlying @ref array, without checking.
3253 + 
    /** Return a reference to the underlying `array`, without checking.
2408  
3254  
2409 - 
        This is the fastest way to access the underlying representation when
3255 + 
        This is the fastest way to access the underlying
2410 - 
        the kind is known in advance.
3256 + 
        representation when the kind is known in advance.
2411  
3257  
2412   
        @par Preconditions
3258   
        @par Preconditions
2413  
3259  
2414   
        @code
3260   
        @code
2415   
        this->is_array()
3261   
        this->is_array()
2416   
        @endcode
3262   
        @endcode
2417  
3263  
2418   
        @par Complexity
3264   
        @par Complexity
2419   
        Constant.
3265   
        Constant.
2420  
3266  
2421   
        @par Exception Safety
3267   
        @par Exception Safety
2422 -
 
2423 - 
        @{
 
2424   
        No-throw guarantee.
3268   
        No-throw guarantee.
2425   
    */
3269   
    */
 
3270 + 
    /** @{ */
2426   
    array&
3271   
    array&
2427   
    get_array() & noexcept
3272   
    get_array() & noexcept
2428   
    {
3273   
    {
2429   
        BOOST_ASSERT(is_array());
3274   
        BOOST_ASSERT(is_array());
2430   
        return arr_;
3275   
        return arr_;
2431   
    }
3276   
    }
2432  
3277  
2433   
    array&&
3278   
    array&&
2434   
    get_array() && noexcept
3279   
    get_array() && noexcept
2435   
    {
3280   
    {
2436   
        BOOST_ASSERT(is_array());
3281   
        BOOST_ASSERT(is_array());
2437   
        return std::move(arr_);
3282   
        return std::move(arr_);
2438   
    }
3283   
    }
2439  
3284  
2440   
    array const&
3285   
    array const&
2441   
    get_array() const& noexcept
3286   
    get_array() const& noexcept
2442   
    {
3287   
    {
2443   
        BOOST_ASSERT(is_array());
3288   
        BOOST_ASSERT(is_array());
2444   
        return arr_;
3289   
        return arr_;
2445   
    }
3290   
    }
2446 - 
    /// @}
3291 + 
    /** @} */
2447  
3292  
2448 - 
    /** Return the underlying @ref string, without checking.
3293 + 
    /** Return a reference to the underlying `string`, without checking.
2449  
3294  
2450 - 
        This is the fastest way to access the underlying representation when
3295 + 
        This is the fastest way to access the underlying
2451 - 
        the kind is known in advance.
3296 + 
        representation when the kind is known in advance.
2452  
3297  
2453   
        @par Preconditions
3298   
        @par Preconditions
2454  
3299  
2455   
        @code
3300   
        @code
2456   
        this->is_string()
3301   
        this->is_string()
2457   
        @endcode
3302   
        @endcode
2458  
3303  
2459   
        @par Complexity
3304   
        @par Complexity
2460   
        Constant.
3305   
        Constant.
2461  
3306  
2462   
        @par Exception Safety
3307   
        @par Exception Safety
2463 -
 
2464 - 
        @{
 
2465   
        No-throw guarantee.
3308   
        No-throw guarantee.
2466   
    */
3309   
    */
 
3310 + 
    /** @{ */
2467   
    string&
3311   
    string&
2468   
    get_string() & noexcept
3312   
    get_string() & noexcept
2469   
    {
3313   
    {
2470   
        BOOST_ASSERT(is_string());
3314   
        BOOST_ASSERT(is_string());
2471   
        return str_;
3315   
        return str_;
2472   
    }
3316   
    }
2473  
3317  
2474   
    string&&
3318   
    string&&
2475   
    get_string() && noexcept
3319   
    get_string() && noexcept
2476   
    {
3320   
    {
2477   
        BOOST_ASSERT(is_string());
3321   
        BOOST_ASSERT(is_string());
2478   
        return std::move(str_);
3322   
        return std::move(str_);
2479   
    }
3323   
    }
2480  
3324  
2481   
    string const&
3325   
    string const&
2482   
    get_string() const& noexcept
3326   
    get_string() const& noexcept
2483   
    {
3327   
    {
2484   
        BOOST_ASSERT(is_string());
3328   
        BOOST_ASSERT(is_string());
2485   
        return str_;
3329   
        return str_;
2486   
    }
3330   
    }
2487 - 
    /// @}
3331 + 
    /** @} */
2488  
3332  
2489 - 
    /** Return the underlying `std::int64_t`, without checking.
3333 + 
    /** Return a reference to the underlying `std::int64_t`, without checking.
2490  
3334  
2491 - 
        This is the fastest way to access the underlying representation when
3335 + 
        This is the fastest way to access the underlying
2492 - 
        the kind is known in advance.
3336 + 
        representation when the kind is known in advance.
2493  
3337  
2494   
        @par Preconditions
3338   
        @par Preconditions
2495  
3339  
2496   
        @code
3340   
        @code
2497   
        this->is_int64()
3341   
        this->is_int64()
2498   
        @endcode
3342   
        @endcode
2499  
3343  
2500   
        @par Complexity
3344   
        @par Complexity
2501   
        Constant.
3345   
        Constant.
2502  
3346  
2503   
        @par Exception Safety
3347   
        @par Exception Safety
2504 -
 
2505 - 
        @{
 
2506   
        No-throw guarantee.
3348   
        No-throw guarantee.
2507   
    */
3349   
    */
2508   
    std::int64_t&
3350   
    std::int64_t&
2509   
    get_int64() noexcept
3351   
    get_int64() noexcept
2510   
    {
3352   
    {
2511   
        BOOST_ASSERT(is_int64());
3353   
        BOOST_ASSERT(is_int64());
2512   
        return sca_.i;
3354   
        return sca_.i;
2513   
    }
3355   
    }
2514  
3356  
 
3357 + 
    /** Return the underlying `std::int64_t`, without checking.
 
3358 +
 
3359 + 
        This is the fastest way to access the underlying
 
3360 + 
        representation when the kind is known in advance.
 
3361 +
 
3362 + 
        @par Preconditions
 
3363 +
 
3364 + 
        @code
 
3365 + 
        this->is_int64()
 
3366 + 
        @endcode
 
3367 +
 
3368 + 
        @par Complexity
 
3369 + 
        Constant.
 
3370 +
 
3371 + 
        @par Exception Safety
 
3372 + 
        No-throw guarantee.
 
3373 + 
    */
2515   
    std::int64_t
3374   
    std::int64_t
2516   
    get_int64() const noexcept
3375   
    get_int64() const noexcept
2517   
    {
3376   
    {
2518   
        BOOST_ASSERT(is_int64());
3377   
        BOOST_ASSERT(is_int64());
2519   
        return sca_.i;
3378   
        return sca_.i;
2520 - 
    /// @}
 
2521   
    }
3379   
    }
2522  
3380  
2523 - 
    /** Return the underlying `std::uint64_t`, without checking.
3381 + 
    /** Return a reference to the underlying `std::uint64_t`, without checking.
2524  
3382  
2525 - 
        This is the fastest way to access the underlying representation when
3383 + 
        This is the fastest way to access the underlying
2526 - 
        the kind is known in advance.
3384 + 
        representation when the kind is known in advance.
2527  
3385  
2528   
        @par Preconditions
3386   
        @par Preconditions
2529  
3387  
2530   
        @code
3388   
        @code
2531   
        this->is_uint64()
3389   
        this->is_uint64()
2532   
        @endcode
3390   
        @endcode
2533  
3391  
2534   
        @par Complexity
3392   
        @par Complexity
2535   
        Constant.
3393   
        Constant.
2536  
3394  
2537   
        @par Exception Safety
3395   
        @par Exception Safety
2538 -
 
2539 - 
        @{
 
2540   
        No-throw guarantee.
3396   
        No-throw guarantee.
2541   
    */
3397   
    */
2542   
    std::uint64_t&
3398   
    std::uint64_t&
2543   
    get_uint64() noexcept
3399   
    get_uint64() noexcept
2544   
    {
3400   
    {
2545   
        BOOST_ASSERT(is_uint64());
3401   
        BOOST_ASSERT(is_uint64());
2546   
        return sca_.u;
3402   
        return sca_.u;
2547   
    }
3403   
    }
2548  
3404  
 
3405 + 
    /** Return the underlying `std::uint64_t`, without checking.
 
3406 +
 
3407 + 
        This is the fastest way to access the underlying
 
3408 + 
        representation when the kind is known in advance.
 
3409 +
 
3410 + 
        @par Preconditions
 
3411 +
 
3412 + 
        @code
 
3413 + 
        this->is_uint64()
 
3414 + 
        @endcode
 
3415 +
 
3416 + 
        @par Complexity
 
3417 + 
        Constant.
 
3418 +
 
3419 + 
        @par Exception Safety
 
3420 + 
        No-throw guarantee.
 
3421 + 
    */
2549   
    std::uint64_t
3422   
    std::uint64_t
2550   
    get_uint64() const noexcept
3423   
    get_uint64() const noexcept
2551   
    {
3424   
    {
2552   
        BOOST_ASSERT(is_uint64());
3425   
        BOOST_ASSERT(is_uint64());
2553   
        return sca_.u;
3426   
        return sca_.u;
2554 - 
    /// @}
 
2555   
    }
3427   
    }
2556  
3428  
2557 - 
    /** Return the underlying `double`, without checking.
3429 + 
    /** Return a reference to the underlying `double`, without checking.
2558  
3430  
2559   
        This is the fastest way to access the underlying
3431   
        This is the fastest way to access the underlying
2560   
        representation when the kind is known in advance.
3432   
        representation when the kind is known in advance.
2561  
3433  
2562   
        @par Preconditions
3434   
        @par Preconditions
2563  
3435  
2564   
        @code
3436   
        @code
2565   
        this->is_double()
3437   
        this->is_double()
2566   
        @endcode
3438   
        @endcode
2567  
3439  
2568   
        @par Complexity
3440   
        @par Complexity
2569   
        Constant.
3441   
        Constant.
2570  
3442  
2571   
        @par Exception Safety
3443   
        @par Exception Safety
2572 -
 
2573 - 
        @{
 
2574   
        No-throw guarantee.
3444   
        No-throw guarantee.
2575   
    */
3445   
    */
2576   
    double&
3446   
    double&
2577   
    get_double() noexcept
3447   
    get_double() noexcept
2578   
    {
3448   
    {
2579   
        BOOST_ASSERT(is_double());
3449   
        BOOST_ASSERT(is_double());
2580   
        return sca_.d;
3450   
        return sca_.d;
2581   
    }
3451   
    }
2582  
3452  
 
3453 + 
    /** Return the underlying `double`, without checking.
 
3454 +
 
3455 + 
        This is the fastest way to access the underlying
 
3456 + 
        representation when the kind is known in advance.
 
3457 +
 
3458 + 
        @par Preconditions
 
3459 +
 
3460 + 
        @code
 
3461 + 
        this->is_double()
 
3462 + 
        @endcode
 
3463 +
 
3464 + 
        @par Complexity
 
3465 + 
        Constant.
 
3466 +
 
3467 + 
        @par Exception Safety
 
3468 + 
        No-throw guarantee.
 
3469 + 
    */
2583   
    double
3470   
    double
2584   
    get_double() const noexcept
3471   
    get_double() const noexcept
2585   
    {
3472   
    {
2586   
        BOOST_ASSERT(is_double());
3473   
        BOOST_ASSERT(is_double());
2587   
        return sca_.d;
3474   
        return sca_.d;
2588 - 
    /// @}
 
2589   
    }
3475   
    }
2590  
3476  
2591 - 
    /** Return the underlying `bool`, without checking.
3477 + 
    /** Return a reference to the underlying `bool`, without checking.
2592  
3478  
2593 - 
        This is the fastest way to access the underlying representation when
3479 + 
        This is the fastest way to access the underlying
2594 - 
        the kind is known in advance.
3480 + 
        representation when the kind is known in advance.
2595  
3481  
2596   
        @par Preconditions
3482   
        @par Preconditions
2597  
3483  
2598   
        @code
3484   
        @code
2599   
        this->is_bool()
3485   
        this->is_bool()
2600   
        @endcode
3486   
        @endcode
2601  
3487  
2602   
        @par Complexity
3488   
        @par Complexity
2603   
        Constant.
3489   
        Constant.
2604  
3490  
2605   
        @par Exception Safety
3491   
        @par Exception Safety
2606 -
 
2607 - 
        @{
 
2608   
        No-throw guarantee.
3492   
        No-throw guarantee.
2609   
    */
3493   
    */
2610   
    bool&
3494   
    bool&
2611   
    get_bool() noexcept
3495   
    get_bool() noexcept
2612   
    {
3496   
    {
2613   
        BOOST_ASSERT(is_bool());
3497   
        BOOST_ASSERT(is_bool());
2614   
        return sca_.b;
3498   
        return sca_.b;
2615   
    }
3499   
    }
2616  
3500  
 
3501 + 
    /** Return the underlying `bool`, without checking.
 
3502 +
 
3503 + 
        This is the fastest way to access the underlying
 
3504 + 
        representation when the kind is known in advance.
 
3505 +
 
3506 + 
        @par Preconditions
 
3507 +
 
3508 + 
        @code
 
3509 + 
        this->is_bool()
 
3510 + 
        @endcode
 
3511 +
 
3512 + 
        @par Complexity
 
3513 + 
        Constant.
 
3514 +
 
3515 + 
        @par Exception Safety
 
3516 + 
        No-throw guarantee.
 
3517 + 
    */
2617   
    bool
3518   
    bool
2618   
    get_bool() const noexcept
3519   
    get_bool() const noexcept
2619   
    {
3520   
    {
2620   
        BOOST_ASSERT(is_bool());
3521   
        BOOST_ASSERT(is_bool());
2621   
        return sca_.b;
3522   
        return sca_.b;
2622 - 
    /// @}
 
2623   
    }
3523   
    }
2624  
3524  
2625   
    //------------------------------------------------------
3525   
    //------------------------------------------------------
2626  
3526  
2627   
    /** Access an element, with bounds checking.
3527   
    /** Access an element, with bounds checking.
2628  
3528  
2629   
        Returns `boost::system::result` containing a reference to the element
3529   
        Returns `boost::system::result` containing a reference to the element
2630 - 
        of the underlying ccontainer, if such element exists. If the underlying
3530 + 
        of the underlying object, if `pos` is within its range. If `pos` is
2631 - 
        value is not a container of the suitable type or the container doesn't
 
2632 - 
        have a corresponding element the result contains an `error_code`.
 
2633 -
 
2634 - 
        , if `pos` is within its range. If `pos` is
 
2635   
        outside of that range, or the underlying value is not an object the
3531   
        outside of that range, or the underlying value is not an object the
2636 -
3532 + 
        result contains an `error_code`.
2637 - 
        Returns @ref boost::system::result containing a reference to the
 
2638 - 
        element of the underlying @ref array, if `pos` is within its range. If
 
2639 - 
        `pos` is outside of that range, or the underlying value is not an array
 
2640 - 
        the result contains an `error_code`.
 
2641 -
 
2642 - 
        This function is used to access elements of
 
2643 - 
        the underlying container, or throw an exception if that could not be
 
2644 - 
        done.
 
2645 -
 
2646 - 
        @li **(1)**, **(2)** require the underlying container to be an
 
2647 - 
            @ref object, and look for an element with the key `key`.
 
2648 - 
        @li **(3)**, **(4)** require the underlying container to be an
 
2649 - 
            @ref array, and look  for an element at index `pos`.
 
2650  
3533  
2651   
        @par Exception Safety
3534   
        @par Exception Safety
2652   
        No-throw guarantee.
3535   
        No-throw guarantee.
2653  
3536  
2654   
        @param key The key of the element to find.
3537   
        @param key The key of the element to find.
2655  
3538  
2656   
        @par Complexity
3539   
        @par Complexity
2657 -
 
2658 - 
        @par Exception Safety
 
2659 - 
        No-throw guarantee.
 
2660 -
 
2661 - 
        @{
 
2662   
        Constant.
3540   
        Constant.
2663   
    */
3541   
    */
 
3542 + 
    /** @{ */
2664   
    BOOST_JSON_DECL
3543   
    BOOST_JSON_DECL
2665   
    boost::system::result<value&>
3544   
    boost::system::result<value&>
2666   
    try_at(string_view key) noexcept;
3545   
    try_at(string_view key) noexcept;
2667  
3546  
2668   
    BOOST_JSON_DECL
3547   
    BOOST_JSON_DECL
2669   
    boost::system::result<value const&>
3548   
    boost::system::result<value const&>
2670   
    try_at(string_view key) const noexcept;
3549   
    try_at(string_view key) const noexcept;
2671 -
3550 + 
    /** @} */
2672 - 
    /** Overload
 
2673 -
 
2674 - 
        @param pos A zero-based array index.
 
2675 - 
    */
 
2676 - 
    BOOST_JSON_DECL
 
2677 - 
    boost::system::result<value&>
 
2678 - 
    try_at(std::size_t pos) noexcept;
 
2679 -
 
2680 - 
    /// Overload
 
2681 - 
    BOOST_JSON_DECL
 
2682 - 
    boost::system::result<value const&>
 
2683 - 
    try_at(std::size_t pos) const noexcept;
 
2684 - 
    /// @}
 
2685 -
 
2686  
3551  
2687   
    /** Access an element, with bounds checking.
3552   
    /** Access an element, with bounds checking.
2688  
3553  
2689   
        This function is used to access elements of
3554   
        This function is used to access elements of
2690 - 
        the underlying container, or throw an exception if that could not be
3555 + 
        the underlying object, or throw an exception
2691 - 
        done.
3556 + 
        if the value is not an object.
2692 -
 
2693 - 
        @li **(1)**--**(3)** is equivalent to
 
2694 - 
            `this->as_object(loc).at(key, loc)`.
 
2695 - 
        @li **(4)**--**(6)** is equivalent to
 
2696 - 
            `this->as_array(loc).at(pos, loc)`.
 
2697  
3557  
2698   
        @par Complexity
3558   
        @par Complexity
2699   
        Constant.
3559   
        Constant.
2700  
3560  
2701   
        @par Exception Safety
3561   
        @par Exception Safety
2702   
        Strong guarantee.
3562   
        Strong guarantee.
2703  
3563  
2704 - 
        @param loc @ref boost::source_location to use in thrown exception; the
 
2705 - 
               source location of the call site by default.
 
2706   
        @param key The key of the element to find.
3564   
        @param key The key of the element to find.
2707  
3565  
2708 - 
        @throw boost::system::system_error The underlying type of value is not
3566 + 
        @param loc `source_location` to use in thrown exception; the source
2709 - 
               the container type corresponding to the first argument (i.e.
3567 + 
            location of the call site by default.
2710 - 
               using an index with an @ref object).
 
2711 - 
        @throw boost::system::system_error An element corresponding to the
 
2712 - 
               first argument was not found.
 
2713 -
 
2714 - 
        @see @ref as_array, @ref as_object.
 
2715  
3568  
2716 - 
        @{
3569 + 
        @return `this->as_object(loc).at( key, loc )`.
2717   
    */
3570   
    */
 
3571 + 
    /** @{ */
2718   
    value&
3572   
    value&
2719   
    at(string_view key, source_location const& loc = BOOST_CURRENT_LOCATION) &
3573   
    at(string_view key, source_location const& loc = BOOST_CURRENT_LOCATION) &
2720   
    {
3574   
    {
2721   
        return as_object(loc).at(key, loc);
3575   
        return as_object(loc).at(key, loc);
2722   
    }
3576   
    }
2723 - 
    /// Overload
 
2724  
3577  
2725   
    value&&
3578   
    value&&
2726   
    at(string_view key, source_location const& loc = BOOST_CURRENT_LOCATION) &&
3579   
    at(string_view key, source_location const& loc = BOOST_CURRENT_LOCATION) &&
2727   
    {
3580   
    {
2728   
        return std::move( as_object(loc) ).at(key, loc);
3581   
        return std::move( as_object(loc) ).at(key, loc);
2729   
    }
3582   
    }
2730 - 
    /// Overload
 
2731  
3583  
2732   
    value const&
3584   
    value const&
2733   
    at(
3585   
    at(
2734   
        string_view key,
3586   
        string_view key,
2735   
        source_location const& loc = BOOST_CURRENT_LOCATION) const&
3587   
        source_location const& loc = BOOST_CURRENT_LOCATION) const&
2736   
    {
3588   
    {
2737   
        return as_object(loc).at(key, loc);
3589   
        return as_object(loc).at(key, loc);
2738   
    }
3590   
    }
 
3591 + 
    /** @} */
2739  
3592  
2740 - 
    /** Overload
3593 + 
    /** Access an element, with bounds checking.
 
3594 +
 
3595 + 
        Returns `boost::system::result` containing a reference to the element
 
3596 + 
        of the underlying array, if `pos` is within its range. If `pos` is
 
3597 + 
        outside of that range, or the underlying value is not an array the
 
3598 + 
        result contains an `error_code`.
 
3599 +
 
3600 + 
        @par Exception Safety
 
3601 + 
        No-throw guarantee.
2741  
3602  
2742   
        @param pos A zero-based array index.
3603   
        @param pos A zero-based array index.
2743 - 
        @param loc
3604 +
 
3605 + 
        @par Complexity
 
3606 + 
        Constant.
 
3607 + 
    */
 
3608 + 
    /** @{ */
 
3609 + 
    BOOST_JSON_DECL
 
3610 + 
    boost::system::result<value&>
 
3611 + 
    try_at(std::size_t pos) noexcept;
 
3612 +
 
3613 + 
    BOOST_JSON_DECL
 
3614 + 
    boost::system::result<value const&>
 
3615 + 
    try_at(std::size_t pos) const noexcept;
 
3616 + 
    /** @} */
 
3617 +
 
3618 + 
    /** Access an element, with bounds checking.
 
3619 +
 
3620 + 
        This function is used to access elements of
 
3621 + 
        the underlying array, or throw an exception
 
3622 + 
        if the value is not an array.
 
3623 +
 
3624 + 
        @par Complexity
 
3625 + 
        Constant.
 
3626 +
 
3627 + 
        @par Exception Safety
 
3628 + 
        Strong guarantee.
 
3629 +
 
3630 + 
        @param pos A zero-based array index.
 
3631 +
 
3632 + 
        @param loc `source_location` to use in thrown exception; the source
 
3633 + 
            location of the call site by default.
 
3634 +
 
3635 + 
        @return `this->as_array(loc).at( pos, loc )`.
2744   
    */
3636   
    */
 
3637 + 
    /** @{ */
2745   
    value &
3638   
    value &
2746   
    at(std::size_t pos, source_location const& loc = BOOST_CURRENT_LOCATION) &
3639   
    at(std::size_t pos, source_location const& loc = BOOST_CURRENT_LOCATION) &
2747   
    {
3640   
    {
2748   
        return as_array(loc).at(pos, loc);
3641   
        return as_array(loc).at(pos, loc);
2749   
    }
3642   
    }
2750 - 
    /// Overload
 
2751  
3643  
2752   
    value&&
3644   
    value&&
2753   
    at(std::size_t pos, source_location const& loc = BOOST_CURRENT_LOCATION) &&
3645   
    at(std::size_t pos, source_location const& loc = BOOST_CURRENT_LOCATION) &&
2754   
    {
3646   
    {
2755   
        return std::move( as_array(loc) ).at(pos, loc);
3647   
        return std::move( as_array(loc) ).at(pos, loc);
2756   
    }
3648   
    }
2757 - 
    /// Overload
 
2758  
3649  
2759   
    value const&
3650   
    value const&
2760 - 
    at(std::size_t pos,
3651 + 
    at(
2761 - 
       source_location const& loc = BOOST_CURRENT_LOCATION) const&
3652 + 
        std::size_t pos,
 
3653 + 
        source_location const& loc = BOOST_CURRENT_LOCATION) const&
2762   
    {
3654   
    {
2763   
        return as_array(loc).at(pos, loc);
3655   
        return as_array(loc).at(pos, loc);
2764   
    }
3656   
    }
2765 - 
    /// @}
3657 + 
    /** @} */
2766  
3658  
2767   
    /** Access an element via JSON Pointer.
3659   
    /** Access an element via JSON Pointer.
2768  
3660  
2769   
        This function is used to access a (potentially nested) element of the
3661   
        This function is used to access a (potentially nested) element of the
2770   
        value using a JSON Pointer string.
3662   
        value using a JSON Pointer string.
2771  
3663  
2772   
        @par Complexity
3664   
        @par Complexity
2773   
        Linear in the sizes of `ptr` and underlying array, object, or string.
3665   
        Linear in the sizes of `ptr` and underlying array, object, or string.
2774  
3666  
2775   
        @par Exception Safety
3667   
        @par Exception Safety
2776   
        No-throw guarantee.
3668   
        No-throw guarantee.
2777  
3669  
2778   
        @param ptr JSON Pointer string.
3670   
        @param ptr JSON Pointer string.
2779  
3671  
2780 - 
        @return @ref boost::system::result containing either a reference to the
3672 + 
        @return `boost::system::result<value&>` containing either a reference
2781 - 
                element identified by `ptr` or a corresponding `error_code`.
3673 + 
            to the element identified by `ptr` or a corresponding `error_code`.
2782  
3674  
2783   
        @see
3675   
        @see
2784 -
 
2785 - 
        @{
 
2786   
            [RFC 6901 - JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901).
3676   
            [RFC 6901 - JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901).
2787   
    */
3677   
    */
2788   
    BOOST_JSON_DECL
3678   
    BOOST_JSON_DECL
2789   
    system::result<value const&>
3679   
    system::result<value const&>
2790   
    try_at_pointer(string_view ptr) const noexcept;
3680   
    try_at_pointer(string_view ptr) const noexcept;
2791  
3681  
 
3682 + 
    /** Access an element via JSON Pointer.
 
3683 +
 
3684 + 
        This function is used to access a (potentially nested) element of the
 
3685 + 
        value using a JSON Pointer string.
 
3686 +
 
3687 + 
        @par Complexity
 
3688 + 
        Linear in the sizes of `ptr` and underlying array, object, or string.
 
3689 +
 
3690 + 
        @par Exception Safety
 
3691 + 
        No-throw guarantee.
 
3692 +
 
3693 + 
        @param ptr JSON Pointer string.
 
3694 +
 
3695 + 
        @return `boost::system::result<value const&>` containing either a
 
3696 + 
            reference to the element identified by `ptr` or a corresponding
 
3697 + 
            `error_code`.
 
3698 +
 
3699 + 
        @see
 
3700 + 
            [RFC 6901 - JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901).
 
3701 + 
    */
2792   
    BOOST_JSON_DECL
3702   
    BOOST_JSON_DECL
2793   
    system::result<value&>
3703   
    system::result<value&>
2794 - 
    /// @}
 
2795   
    try_at_pointer(string_view ptr) noexcept;
3704   
    try_at_pointer(string_view ptr) noexcept;
2796  
3705  
2797   
    /** Access an element via JSON Pointer.
3706   
    /** Access an element via JSON Pointer.
2798  
3707  
2799 - 
        This function is used to access a (potentially nested) element of the
3708 + 
        This function is used to access a (potentially nested)
2800 - 
        value using a JSON Pointer string.
3709 + 
        element of the value using a JSON Pointer string.
2801  
3710  
2802   
        @par Complexity
3711   
        @par Complexity
2803 - 
        Linear in the sizes of `ptr` and the underlying container.
3712 + 
        Linear in the sizes of `ptr` and underlying array, object, or string.
2804  
3713  
2805   
        @par Exception Safety
3714   
        @par Exception Safety
2806   
        Strong guarantee.
3715   
        Strong guarantee.
2807  
3716  
2808   
        @param ptr JSON Pointer string.
3717   
        @param ptr JSON Pointer string.
2809 - 
        @param loc @ref boost::source_location to use in thrown exception; the
3718 +
2810 - 
               source location of the call site by default.
3719 + 
        @param loc `source_location` to use in thrown exception; the source
 
3720 + 
            location of the call site by default.
2811  
3721  
2812   
        @return reference to the element identified by `ptr`.
3722   
        @return reference to the element identified by `ptr`.
2813  
3723  
2814 - 
        @throw boost::system::system_error if an error occurs.
3724 + 
        @throw `boost::system::system_error` if an error occurs.
2815  
3725  
2816   
        @see
3726   
        @see
2817 - 
            [RFC 6901 - JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901).
3727 + 
        <a href="https://datatracker.ietf.org/doc/html/rfc6901">
2818 -
3728 + 
            RFC 6901 - JavaScript Object Notation (JSON) Pointer</a>
2819 - 
        @{
 
2820   
    */
3729   
    */
 
3730 + 
    /** @{ */
2821   
    BOOST_JSON_DECL
3731   
    BOOST_JSON_DECL
2822   
    value const&
3732   
    value const&
2823   
    at_pointer(
3733   
    at_pointer(
2824   
        string_view ptr,
3734   
        string_view ptr,
2825   
        source_location const& loc = BOOST_CURRENT_LOCATION) const&;
3735   
        source_location const& loc = BOOST_CURRENT_LOCATION) const&;
2826 - 
    /// Overload
 
2827  
3736  
2828   
    inline
3737   
    inline
2829   
    value&&
3738   
    value&&
2830   
    at_pointer(
3739   
    at_pointer(
2831   
        string_view ptr,
3740   
        string_view ptr,
2832   
        source_location const& loc = BOOST_CURRENT_LOCATION) &&;
3741   
        source_location const& loc = BOOST_CURRENT_LOCATION) &&;
2833 - 
    /// Overload
 
2834  
3742  
2835   
    inline
3743   
    inline
2836   
    value&
3744   
    value&
2837   
    at_pointer(
3745   
    at_pointer(
2838   
        string_view ptr,
3746   
        string_view ptr,
2839   
        source_location const& loc = BOOST_CURRENT_LOCATION) &;
3747   
        source_location const& loc = BOOST_CURRENT_LOCATION) &;
2840 - 
    /// @}
3748 + 
    /** @} */
2841  
3749  
2842   
    /** Access an element via JSON Pointer.
3750   
    /** Access an element via JSON Pointer.
2843  
3751  
2844 - 
        This function is used to access a (potentially nested) element of the
3752 + 
        This function is used to access a (potentially nested)
2845 - 
        value using a JSON Pointer string.
3753 + 
        element of the value using a JSON Pointer string.
2846  
3754  
2847   
        @par Complexity
3755   
        @par Complexity
2848 - 
        Linear in the sizes of `ptr` and underlying container.
3756 + 
        Linear in the sizes of `ptr` and underlying array, object, or string.
2849  
3757  
2850   
        @par Exception Safety
3758   
        @par Exception Safety
2851   
        No-throw guarantee.
3759   
        No-throw guarantee.
2852  
3760  
2853   
        @param ptr JSON Pointer string.
3761   
        @param ptr JSON Pointer string.
 
3762 +
2854   
        @param ec Set to the error, if any occurred.
3763   
        @param ec Set to the error, if any occurred.
2855  
3764  
2856   
        @return pointer to the element identified by `ptr`.
3765   
        @return pointer to the element identified by `ptr`.
2857  
3766  
2858   
        @see
3767   
        @see
2859 - 
            [RFC 6901 - JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901)
3768 + 
        <a href="https://datatracker.ietf.org/doc/html/rfc6901">
2860 -
3769 + 
            RFC 6901 - JavaScript Object Notation (JSON) Pointer</a>
2861 - 
        @{
 
2862   
    */
3770   
    */
 
3771 + 
    /** @{ */
2863   
    BOOST_JSON_DECL
3772   
    BOOST_JSON_DECL
2864   
    value const*
3773   
    value const*
2865   
    find_pointer(string_view ptr, system::error_code& ec) const noexcept;
3774   
    find_pointer(string_view ptr, system::error_code& ec) const noexcept;
2866  
3775  
2867   
    BOOST_JSON_DECL
3776   
    BOOST_JSON_DECL
2868   
    value*
3777   
    value*
2869   
    find_pointer(string_view ptr, system::error_code& ec) noexcept;
3778   
    find_pointer(string_view ptr, system::error_code& ec) noexcept;
2870  
3779  
2871   
    BOOST_JSON_DECL
3780   
    BOOST_JSON_DECL
2872   
    value const*
3781   
    value const*
2873   
    find_pointer(string_view ptr, std::error_code& ec) const noexcept;
3782   
    find_pointer(string_view ptr, std::error_code& ec) const noexcept;
2874  
3783  
2875   
    BOOST_JSON_DECL
3784   
    BOOST_JSON_DECL
2876   
    value*
3785   
    value*
2877   
    find_pointer(string_view ptr, std::error_code& ec) noexcept;
3786   
    find_pointer(string_view ptr, std::error_code& ec) noexcept;
2878 - 
    /// @}
3787 + 
    /** @} */
2879  
3788  
2880   
    //------------------------------------------------------
3789   
    //------------------------------------------------------
2881  
3790  
2882   
    /** Set an element via JSON Pointer.
3791   
    /** Set an element via JSON Pointer.
2883  
3792  
2884   
        This function is used to insert or assign to a potentially nested
3793   
        This function is used to insert or assign to a potentially nested
2885   
        element of the value using a JSON Pointer string. The function may
3794   
        element of the value using a JSON Pointer string. The function may
2886   
        create intermediate elements corresponding to pointer segments.
3795   
        create intermediate elements corresponding to pointer segments.
 
3796 + 
        <br/>
2887  
3797  
2888   
        The particular conditions when and what kind of intermediate element
3798   
        The particular conditions when and what kind of intermediate element
2889   
        is created is governed by the `ptr` parameter.
3799   
        is created is governed by the `ptr` parameter.
2890  
3800  
2891   
        Each pointer token is considered in sequence. For each token
3801   
        Each pointer token is considered in sequence. For each token
2892  
3802  
2893   
        - if the containing value is an @ref object, then a new `null`
3803   
        - if the containing value is an @ref object, then a new `null`
2894   
          element is created with key equal to unescaped token string;
3804   
          element is created with key equal to unescaped token string;
2895   
          otherwise
3805   
          otherwise
2896  
3806  
2897   
        - if the containing value is an @ref array, and the token represents a
3807   
        - if the containing value is an @ref array, and the token represents a
2898   
          past-the-end marker, then a `null` element is appended to the array;
3808   
          past-the-end marker, then a `null` element is appended to the array;
2899   
          otherwise
3809   
          otherwise
2900  
3810  
2901   
        - if the containing value is an @ref array, and the token represents a
3811   
        - if the containing value is an @ref array, and the token represents a
2902   
          number, then if the difference between the number and array's size
3812   
          number, then if the difference between the number and array's size
2903   
          is smaller than `opts.max_created_elements`, then the size of the
3813   
          is smaller than `opts.max_created_elements`, then the size of the
2904   
          array is increased, so that the number can reference an element in the
3814   
          array is increased, so that the number can reference an element in the
2905   
          array; otherwise
3815   
          array; otherwise
2906  
3816  
2907   
        - if the containing value is of different @ref kind and
3817   
        - if the containing value is of different @ref kind and
2908   
          `opts.replace_any_scalar` is `true`, or the value is `null`, then
3818   
          `opts.replace_any_scalar` is `true`, or the value is `null`, then
2909  
3819  
2910   
           - if `opts.create_arrays` is `true` and the token either represents
3820   
           - if `opts.create_arrays` is `true` and the token either represents
2911   
             past-the-end marker or a number, then the value is replaced with
3821   
             past-the-end marker or a number, then the value is replaced with
2912   
             an empty array and the token is considered again; otherwise
3822   
             an empty array and the token is considered again; otherwise
2913  
3823  
2914   
           - if `opts.create_objects` is `true`, then the value is replaced
3824   
           - if `opts.create_objects` is `true`, then the value is replaced
2915   
             with an empty object and the token is considered again; otherwise
3825   
             with an empty object and the token is considered again; otherwise
2916  
3826  
2917   
        - an error is produced.
3827   
        - an error is produced.
2918  
3828  
2919   
        @par Complexity
3829   
        @par Complexity
2920   
        Linear in the sum of size of `ptr`, size of underlying array, object,
3830   
        Linear in the sum of size of `ptr`, size of underlying array, object,
2921   
        or string and `opts.max_created_elements`.
3831   
        or string and `opts.max_created_elements`.
2922  
3832  
2923   
        @par Exception Safety
3833   
        @par Exception Safety
2924 - 
        Basic guarantee. Calls to `memory_resource::allocate` may throw.
3834 + 
        Basic guarantee.
 
3835 + 
        Calls to `memory_resource::allocate` may throw.
2925  
3836  
2926   
        @param sv JSON Pointer string.
3837   
        @param sv JSON Pointer string.
 
3838 +
2927   
        @param ref The value to assign to pointed element.
3839   
        @param ref The value to assign to pointed element.
 
3840 +
2928   
        @param opts The options for the algorithm.
3841   
        @param opts The options for the algorithm.
2929  
3842  
2930 - 
        @return @ref boost::system::result containing either a reference to the
3843 + 
        @return `boost::json::result<value&>` containing either a reference to
2931 - 
                element identified by `ptr` or a corresponding `error_code`.
3844 + 
            the element identified by `ptr` or a corresponding `error_code`.
2932  
3845  
2933   
        @see
3846   
        @see
2934   
            @ref set_pointer_options,
3847   
            @ref set_pointer_options,
2935   
            [RFC 6901 - JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901).
3848   
            [RFC 6901 - JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901).
2936   
    */
3849   
    */
2937   
    BOOST_JSON_DECL
3850   
    BOOST_JSON_DECL
2938   
    system::result<value&>
3851   
    system::result<value&>
2939   
    try_set_at_pointer(
3852   
    try_set_at_pointer(
2940   
        string_view sv,
3853   
        string_view sv,
2941   
        value_ref ref,
3854   
        value_ref ref,
2942   
        set_pointer_options const& opts = {} );
3855   
        set_pointer_options const& opts = {} );
2943  
3856  
2944   
    /** Set an element via JSON Pointer.
3857   
    /** Set an element via JSON Pointer.
2945  
3858  
2946   
        This function is used to insert or assign to a potentially nested
3859   
        This function is used to insert or assign to a potentially nested
2947   
        element of the value using a JSON Pointer string. The function may
3860   
        element of the value using a JSON Pointer string. The function may
2948   
        create intermediate elements corresponding to pointer segments.
3861   
        create intermediate elements corresponding to pointer segments.
 
3862 + 
        <br/>
2949  
3863  
2950   
        The particular conditions when and what kind of intermediate element
3864   
        The particular conditions when and what kind of intermediate element
2951   
        is created is governed by the `ptr` parameter.
3865   
        is created is governed by the `ptr` parameter.
2952  
3866  
2953   
        Each pointer token is considered in sequence. For each token
3867   
        Each pointer token is considered in sequence. For each token
2954  
3868  
2955   
        - if the containing value is an @ref object, then a new `null`
3869   
        - if the containing value is an @ref object, then a new `null`
2956   
        element is created with key equal to unescaped token string; otherwise
3870   
        element is created with key equal to unescaped token string; otherwise
2957  
3871  
2958   
        - if the containing value is an @ref array, and the token represents a
3872   
        - if the containing value is an @ref array, and the token represents a
2959   
        past-the-end marker, then a `null` element is appended to the array;
3873   
        past-the-end marker, then a `null` element is appended to the array;
2960   
        otherwise
3874   
        otherwise
2961  
3875  
2962   
        - if the containing value is an @ref array, and the token represents a
3876   
        - if the containing value is an @ref array, and the token represents a
2963   
        number, then if the difference between the number and array's size
3877   
        number, then if the difference between the number and array's size
2964   
        is smaller than `opts.max_created_elements`, then the size of the
3878   
        is smaller than `opts.max_created_elements`, then the size of the
2965   
        array is increased, so that the number can reference an element in the
3879   
        array is increased, so that the number can reference an element in the
2966   
        array; otherwise
3880   
        array; otherwise
2967  
3881  
2968   
        - if the containing value is of different @ref kind and
3882   
        - if the containing value is of different @ref kind and
2969   
          `opts.replace_any_scalar` is `true`, or the value is `null`, then
3883   
          `opts.replace_any_scalar` is `true`, or the value is `null`, then
2970  
3884  
2971   
           - if `opts.create_arrays` is `true` and the token either represents
3885   
           - if `opts.create_arrays` is `true` and the token either represents
2972   
             past-the-end marker or a number, then the value is replaced with
3886   
             past-the-end marker or a number, then the value is replaced with
2973   
             an empty array and the token is considered again; otherwise
3887   
             an empty array and the token is considered again; otherwise
2974  
3888  
2975   
           - if `opts.create_objects` is `true`, then the value is replaced
3889   
           - if `opts.create_objects` is `true`, then the value is replaced
2976   
             with an empty object and the token is considered again; otherwise
3890   
             with an empty object and the token is considered again; otherwise
2977  
3891  
2978   
        - an error is produced.
3892   
        - an error is produced.
2979  
3893  
2980   
        @par Complexity
3894   
        @par Complexity
2981   
        Linear in the sum of size of `ptr`, size of underlying array, object,
3895   
        Linear in the sum of size of `ptr`, size of underlying array, object,
2982   
        or string and `opts.max_created_elements`.
3896   
        or string and `opts.max_created_elements`.
2983  
3897  
2984   
        @par Exception Safety
3898   
        @par Exception Safety
2985   
        Basic guarantee.
3899   
        Basic guarantee.
2986   
        Calls to `memory_resource::allocate` may throw.
3900   
        Calls to `memory_resource::allocate` may throw.
2987  
3901  
2988   
        @param sv JSON Pointer string.
3902   
        @param sv JSON Pointer string.
2989  
3903  
2990   
        @param ref The value to assign to pointed element.
3904   
        @param ref The value to assign to pointed element.
2991  
3905  
2992   
        @param opts The options for the algorithm.
3906   
        @param opts The options for the algorithm.
2993  
3907  
2994   
        @return Reference to the element identified by `ptr`.
3908   
        @return Reference to the element identified by `ptr`.
2995 - 
        @throws boost::system::system_error Overload **(1)** reports errors by
 
2996 - 
                throwing exceptions.
 
2997 -
 
2998  
3909  
2999   
        @see @ref set_pointer_options,
3910   
        @see @ref set_pointer_options,
3000 - 
            [RFC 6901 - JavaScript Object Notation (JSON) Pointer](https://datatracker.ietf.org/doc/html/rfc6901">).
3911 + 
        <a href="https://datatracker.ietf.org/doc/html/rfc6901">
3001 -
3912 + 
            RFC 6901 - JavaScript Object Notation (JSON) Pointer</a>.
3002 - 
        @{
 
3003   
    */
3913   
    */
3004   
    BOOST_JSON_DECL
3914   
    BOOST_JSON_DECL
3005   
    value&
3915   
    value&
3006   
    set_at_pointer(
3916   
    set_at_pointer(
3007   
        string_view sv,
3917   
        string_view sv,
3008   
        value_ref ref,
3918   
        value_ref ref,
3009   
        set_pointer_options const& opts = {} );
3919   
        set_pointer_options const& opts = {} );
3010  
3920  
3011 - 
    /** Overload
3921 + 
    /** Set an element via JSON Pointer.
 
3922 +
 
3923 + 
        This function is used to insert or assign to a potentially nested
 
3924 + 
        element of the value using a JSON Pointer string. The function may
 
3925 + 
        create intermediate elements corresponding to pointer segments.
 
3926 + 
        <br/>
 
3927 +
 
3928 + 
        The particular conditions when and what kind of intermediate element
 
3929 + 
        is created is governed by the `ptr` parameter.
 
3930 +
 
3931 + 
        Each pointer token is considered in sequence. For each token
 
3932 +
 
3933 + 
        - if the containing value is an @ref object, then a new `null`
 
3934 + 
          element is created with key equal to unescaped token string;
 
3935 + 
          otherwise
 
3936 +
 
3937 + 
        - if the containing value is an @ref array, and the token represents a
 
3938 + 
          past-the-end marker, then a `null` element is appended to the array;
 
3939 + 
          otherwise
 
3940 +
 
3941 + 
        - if the containing value is an @ref array, and the token represents a
 
3942 + 
          number, then if the difference between the number and array's size
 
3943 + 
          is smaller than `opts.max_created_elements`, then the size of the
 
3944 + 
          array is increased, so that the number can reference an element in the
 
3945 + 
          array; otherwise
 
3946 +
 
3947 + 
        - if the containing value is of different @ref kind and
 
3948 + 
          `opts.replace_any_scalar` is `true`, or the value is `null`, then
 
3949 +
 
3950 + 
           - if `opts.create_arrays` is `true` and the token either represents
 
3951 + 
             past-the-end marker or a number, then the value is replaced with
 
3952 + 
             an empty array and the token is considered again; otherwise
 
3953 +
 
3954 + 
           - if `opts.create_objects` is `true`, then the value is replaced
 
3955 + 
             with an empty object and the token is considered again; otherwise
 
3956 +
 
3957 + 
        - an error is produced.
 
3958 +
 
3959 + 
        @par Complexity
 
3960 + 
        Linear in the sum of size of `ptr`, size of underlying array, object,
 
3961 + 
        or string and `opts.max_created_elements`.
 
3962 +
 
3963 + 
        @par Exception Safety
 
3964 + 
        Basic guarantee.
 
3965 + 
        Calls to `memory_resource::allocate` may throw.
 
3966 +
 
3967 + 
        @param sv JSON Pointer string.
 
3968 +
 
3969 + 
        @param ref The value to assign to pointed element.
3012  
3970  
3013   
        @param ec Set to the error, if any occurred.
3971   
        @param ec Set to the error, if any occurred.
3014 - 
        @param sv
3972 +
3015 - 
        @param ref
3973 + 
        @param opts The options for the algorithm.
3016 - 
        @param opts
3974 +
 
3975 + 
        @return Pointer to the element identified by `ptr`.
 
3976 +
 
3977 + 
        @see @ref set_pointer_options,
 
3978 + 
        <a href="https://datatracker.ietf.org/doc/html/rfc6901">
 
3979 + 
            RFC 6901 - JavaScript Object Notation (JSON) Pointer</a>.
3017   
    */
3980   
    */
 
3981 + 
    /** @{ */
3018   
    BOOST_JSON_DECL
3982   
    BOOST_JSON_DECL
3019   
    value*
3983   
    value*
3020   
    set_at_pointer(
3984   
    set_at_pointer(
3021   
        string_view sv,
3985   
        string_view sv,
3022   
        value_ref ref,
3986   
        value_ref ref,
3023   
        system::error_code& ec,
3987   
        system::error_code& ec,
3024   
        set_pointer_options const& opts = {} );
3988   
        set_pointer_options const& opts = {} );
3025 - 
    /// Overload
 
3026  
3989  
3027   
    BOOST_JSON_DECL
3990   
    BOOST_JSON_DECL
3028   
    value*
3991   
    value*
3029   
    set_at_pointer(
3992   
    set_at_pointer(
3030   
        string_view sv,
3993   
        string_view sv,
3031   
        value_ref ref,
3994   
        value_ref ref,
3032   
        std::error_code& ec,
3995   
        std::error_code& ec,
3033   
        set_pointer_options const& opts = {} );
3996   
        set_pointer_options const& opts = {} );
3034 - 
    /// @}
3997 + 
    /** @} */
3035  
3998  
3036   
    //------------------------------------------------------
3999   
    //------------------------------------------------------
3037  
4000  
3038 - 
    /** Check if two values are equal.
4001 + 
    /** Return `true` if two values are equal.
3039  
4002  
3040 - 
        Two values are equal when they are the same kind and their referenced
4003 + 
        Two values are equal when they are the
3041 - 
        values are equal, or when they are both integral types and their
4004 + 
        same kind and their referenced values
3042 - 
        integral representations are equal.
4005 + 
        are equal, or when they are both integral
 
4006 + 
        types and their integral representations
 
4007 + 
        are equal.
3043  
4008  
3044   
        @par Complexity
4009   
        @par Complexity
3045 - 
        Constant or linear in the size of the underlying @ref array, @ref object,
4010 + 
        Constant or linear in the size of
3046 - 
        or @ref string.
4011 + 
        the array, object, or string.
3047  
4012  
3048   
        @par Exception Safety
4013   
        @par Exception Safety
3049   
        No-throw guarantee.
4014   
        No-throw guarantee.
3050   
    */
4015   
    */
3051   
    // inline friend speeds up overload resolution
4016   
    // inline friend speeds up overload resolution
3052   
    friend
4017   
    friend
3053   
    bool
4018   
    bool
3054   
    operator==(
4019   
    operator==(
3055   
        value const& lhs,
4020   
        value const& lhs,
3056   
        value const& rhs) noexcept
4021   
        value const& rhs) noexcept
3057   
    {
4022   
    {
3058   
        return lhs.equal(rhs);
4023   
        return lhs.equal(rhs);
3059   
    }
4024   
    }
3060  
4025  
3061 - 
    /** Check if two values are not equal.
4026 + 
    /** Return `true` if two values are not equal.
3062  
4027  
3063 - 
        Two values are equal when they are the same kind and their referenced
4028 + 
        Two values are equal when they are the
3064 - 
        values are equal, or when they are both integral types and their
4029 + 
        same kind and their referenced values
3065 - 
        integral representations are equal.
4030 + 
        are equal, or when they are both integral
 
4031 + 
        types and their integral representations
 
4032 + 
        are equal.
3066  
4033  
3067   
        @par Complexity
4034   
        @par Complexity
3068 - 
        Constant or linear in the size of the underlying @ref array,
4035 + 
        Constant or linear in the size of
3069 - 
        @ref object, or @ref string.
4036 + 
        the array, object, or string.
3070  
4037  
3071   
        @par Exception Safety
4038   
        @par Exception Safety
3072   
        No-throw guarantee.
4039   
        No-throw guarantee.
3073   
    */
4040   
    */
3074   
    friend
4041   
    friend
3075   
    bool
4042   
    bool
3076   
    operator!=(
4043   
    operator!=(
3077   
        value const& lhs,
4044   
        value const& lhs,
3078   
        value const& rhs) noexcept
4045   
        value const& rhs) noexcept
3079   
    {
4046   
    {
3080   
        return ! (lhs == rhs);
4047   
        return ! (lhs == rhs);
3081   
    }
4048   
    }
3082  
4049  
3083   
    /** Serialize @ref value to an output stream.
4050   
    /** Serialize @ref value to an output stream.
3084  
4051  
3085 - 
        This function serializes a `value` as JSON text into the output stream.
4052 + 
        This function serializes a `value` as JSON into the output stream.
3086  
4053  
3087   
        @return Reference to `os`.
4054   
        @return Reference to `os`.
3088  
4055  
3089   
        @par Complexity
4056   
        @par Complexity
3090   
        Constant or linear in the size of `jv`.
4057   
        Constant or linear in the size of `jv`.
3091  
4058  
3092   
        @par Exception Safety
4059   
        @par Exception Safety
3093   
        Strong guarantee.
4060   
        Strong guarantee.
3094   
        Calls to `memory_resource::allocate` may throw.
4061   
        Calls to `memory_resource::allocate` may throw.
3095  
4062  
3096   
        @param os The output stream to serialize to.
4063   
        @param os The output stream to serialize to.
3097  
4064  
3098   
        @param jv The value to serialize.
4065   
        @param jv The value to serialize.
3099   
    */
4066   
    */
3100   
    BOOST_JSON_DECL
4067   
    BOOST_JSON_DECL
3101   
    friend
4068   
    friend
3102   
    std::ostream&
4069   
    std::ostream&
3103   
    operator<<(
4070   
    operator<<(
3104   
        std::ostream& os,
4071   
        std::ostream& os,
3105   
        value const& jv);
4072   
        value const& jv);
3106  
4073  
3107   
    /** Parse @ref value from an input stream.
4074   
    /** Parse @ref value from an input stream.
3108  
4075  
3109   
        This function parses JSON from an input stream into a `value`. If
4076   
        This function parses JSON from an input stream into a `value`. If
3110 - 
        parsing fails, @ref std::ios_base::failbit will be set for `is` and
4077 + 
        parsing fails, `std::ios_base::failbit` will be set for `is` and
3111 - 
        `jv` will be left unchanged. Regardless of whether @ref
4078 + 
        `jv` will be left unchanged. Regardless of whether `skipws` flag is set
3112 - 
        std::ios_base::skipws flag is set on `is`, consumes whitespace before
4079 + 
        on `is`, consumes whitespace before and after JSON, because whitespace
3113 - 
        and after JSON, because whitespace is considered a part of JSON.
4080 + 
        is considered a part of JSON. Behaves as
3114 - 
        Behaves as
 
3115   
        [_FormattedInputFunction_](https://en.cppreference.com/w/cpp/named_req/FormattedInputFunction).
4081   
        [_FormattedInputFunction_](https://en.cppreference.com/w/cpp/named_req/FormattedInputFunction).
3116  
4082  
3117 - 
        @note This operator cannot assume that the stream only contains a
4083 + 
        Note: this operator cannot assume that the stream only contains a
3118   
        single JSON document, which may result in **very underwhelming
4084   
        single JSON document, which may result in **very underwhelming
3119   
        performance**, if the stream isn't cooperative. If you know that your
4085   
        performance**, if the stream isn't cooperative. If you know that your
3120   
        input consists of a single JSON document, consider using @ref parse
4086   
        input consists of a single JSON document, consider using @ref parse
3121   
        function instead.
4087   
        function instead.
3122  
4088  
3123   
        @return Reference to `is`.
4089   
        @return Reference to `is`.
3124  
4090  
3125   
        @par Complexity
4091   
        @par Complexity
3126   
        Linear in the size of JSON data.
4092   
        Linear in the size of JSON data.
3127  
4093  
3128   
        @par Exception Safety
4094   
        @par Exception Safety
3129   
        Basic guarantee.
4095   
        Basic guarantee.
3130   
        Calls to `memory_resource::allocate` may throw.
4096   
        Calls to `memory_resource::allocate` may throw.
3131 - 
        The stream may throw as configured by @ref std::ios::exceptions.
4097 + 
        The stream may throw as configured by
 
4098 + 
        [`std::ios::exceptions`](https://en.cppreference.com/w/cpp/io/basic_ios/exceptions).
3132  
4099  
3133   
        @param is The input stream to parse from.
4100   
        @param is The input stream to parse from.
3134  
4101  
3135   
        @param jv The value to parse into.
4102   
        @param jv The value to parse into.
3136  
4103  
3137   
        @see @ref parse.
4104   
        @see @ref parse.
3138   
    */
4105   
    */
3139   
    BOOST_JSON_DECL
4106   
    BOOST_JSON_DECL
3140   
    friend
4107   
    friend
3141   
    std::istream&
4108   
    std::istream&
3142   
    operator>>(
4109   
    operator>>(
3143   
        std::istream& is,
4110   
        std::istream& is,
3144   
        value& jv);
4111   
        value& jv);
3145  
4112  
3146 - 
    /** Helper for @ref boost::hash support.
4113 + 
    /** Helper for `boost::hash` support
3147  
4114  
3148   
        Computes a hash value for `jv`. This function is used by
4115   
        Computes a hash value for `jv`. This function is used by
3149   
        `boost::hash<value>`. Similar overloads for @ref array, @ref object,
4116   
        `boost::hash<value>`. Similar overloads for @ref array, @ref object,
3150   
        and @ref string do not exist, because those types are supported by
4117   
        and @ref string do not exist, because those types are supported by
3151   
        `boost::hash` out of the box.
4118   
        `boost::hash` out of the box.
3152  
4119  
3153   
        @return hash value for `jv`.
4120   
        @return hash value for `jv`.
3154  
4121  
3155   
        @param jv `value` for which a hash is to be computed.
4122   
        @param jv `value` for which a hash is to be computed.
3156  
4123  
3157   
        @see [Boost.ContainerHash](https://boost.org/libs/container_hash).
4124   
        @see [Boost.ContainerHash](https://boost.org/libs/container_hash).
3158   
     */
4125   
     */
3159   
#ifndef BOOST_JSON_DOCS
4126   
#ifndef BOOST_JSON_DOCS
3160   
    template<
4127   
    template<
3161   
        class T,
4128   
        class T,
3162   
        typename std::enable_if<
4129   
        typename std::enable_if<
3163   
            std::is_same< detail::remove_cvref<T>, value >::value >::type*
4130   
            std::is_same< detail::remove_cvref<T>, value >::value >::type*
3164   
                = nullptr>
4131   
                = nullptr>
3165   
    friend
4132   
    friend
3166   
    std::size_t
4133   
    std::size_t
3167   
    hash_value( T const& jv ) noexcept
4134   
    hash_value( T const& jv ) noexcept
3168   
#else
4135   
#else
3169   
    friend
4136   
    friend
3170   
    inline
4137   
    inline
3171   
    std::size_t
4138   
    std::size_t
3172   
    hash_value( value const& jv ) noexcept
4139   
    hash_value( value const& jv ) noexcept
3173   
#endif
4140   
#endif
3174   
    {
4141   
    {
3175   
        return detail::hash_value_impl(jv);
4142   
        return detail::hash_value_impl(jv);
3176   
    }
4143   
    }
3177  
4144  
3178   
private:
4145   
private:
3179   
    static
4146   
    static
3180   
    void
4147   
    void
3181   
    relocate(
4148   
    relocate(
3182   
        value* dest,
4149   
        value* dest,
3183   
        value const& src) noexcept
4150   
        value const& src) noexcept
3184   
    {
4151   
    {
3185   
        std::memcpy(
4152   
        std::memcpy(
3186   
            static_cast<void*>(dest),
4153   
            static_cast<void*>(dest),
3187   
            &src,
4154   
            &src,
3188   
            sizeof(src));
4155   
            sizeof(src));
3189   
    }
4156   
    }
3190  
4157  
3191   
    BOOST_JSON_DECL
4158   
    BOOST_JSON_DECL
3192   
    storage_ptr
4159   
    storage_ptr
3193   
    destroy() noexcept;
4160   
    destroy() noexcept;
3194  
4161  
3195   
    BOOST_JSON_DECL
4162   
    BOOST_JSON_DECL
3196   
    bool
4163   
    bool
3197   
    equal(value const& other) const noexcept;
4164   
    equal(value const& other) const noexcept;
3198  
4165  
3199   
    template<class T>
4166   
    template<class T>
3200   
    auto
4167   
    auto
3201   
    to_number(error& e) const noexcept ->
4168   
    to_number(error& e) const noexcept ->
3202   
        typename std::enable_if<
4169   
        typename std::enable_if<
3203   
            std::is_signed<T>::value &&
4170   
            std::is_signed<T>::value &&
3204   
            ! std::is_floating_point<T>::value,
4171   
            ! std::is_floating_point<T>::value,
3205   
                T>::type
4172   
                T>::type
3206   
    {
4173   
    {
3207   
        if(sca_.k == json::kind::int64)
4174   
        if(sca_.k == json::kind::int64)
3208   
        {
4175   
        {
3209   
            auto const i = sca_.i;
4176   
            auto const i = sca_.i;
3210   
            if( i >= (std::numeric_limits<T>::min)() &&
4177   
            if( i >= (std::numeric_limits<T>::min)() &&
3211   
                i <= (std::numeric_limits<T>::max)())
4178   
                i <= (std::numeric_limits<T>::max)())
3212   
            {
4179   
            {
3213   
                e = {};
4180   
                e = {};
3214   
                return static_cast<T>(i);
4181   
                return static_cast<T>(i);
3215   
            }
4182   
            }
3216   
            e = error::not_exact;
4183   
            e = error::not_exact;
3217   
        }
4184   
        }
3218   
        else if(sca_.k == json::kind::uint64)
4185   
        else if(sca_.k == json::kind::uint64)
3219   
        {
4186   
        {
3220   
            auto const u = sca_.u;
4187   
            auto const u = sca_.u;
3221   
            if(u <= static_cast<std::uint64_t>((
4188   
            if(u <= static_cast<std::uint64_t>((
3222   
                std::numeric_limits<T>::max)()))
4189   
                std::numeric_limits<T>::max)()))
3223   
            {
4190   
            {
3224   
                e = {};
4191   
                e = {};
3225   
                return static_cast<T>(u);
4192   
                return static_cast<T>(u);
3226   
            }
4193   
            }
3227   
            e = error::not_exact;
4194   
            e = error::not_exact;
3228   
        }
4195   
        }
3229   
        else if(sca_.k == json::kind::double_)
4196   
        else if(sca_.k == json::kind::double_)
3230   
        {
4197   
        {
3231   
            auto const d = sca_.d;
4198   
            auto const d = sca_.d;
3232   
            if( d >= static_cast<double>(
4199   
            if( d >= static_cast<double>(
3233   
                    (detail::to_number_limit<T>::min)()) &&
4200   
                    (detail::to_number_limit<T>::min)()) &&
3234   
                d <= static_cast<double>(
4201   
                d <= static_cast<double>(
3235   
                    (detail::to_number_limit<T>::max)()) &&
4202   
                    (detail::to_number_limit<T>::max)()) &&
3236   
                static_cast<T>(d) == d)
4203   
                static_cast<T>(d) == d)
3237   
            {
4204   
            {
3238   
                e = {};
4205   
                e = {};
3239   
                return static_cast<T>(d);
4206   
                return static_cast<T>(d);
3240   
            }
4207   
            }
3241   
            e = error::not_exact;
4208   
            e = error::not_exact;
3242   
        }
4209   
        }
3243   
        else
4210   
        else
3244   
        {
4211   
        {
3245   
            e = error::not_number;
4212   
            e = error::not_number;
3246   
        }
4213   
        }
3247   
        return T{};
4214   
        return T{};
3248   
    }
4215   
    }
3249  
4216  
3250   
    template<class T>
4217   
    template<class T>
3251   
    auto
4218   
    auto
3252   
    to_number(error& e) const noexcept ->
4219   
    to_number(error& e) const noexcept ->
3253   
        typename std::enable_if<
4220   
        typename std::enable_if<
3254   
            std::is_unsigned<T>::value &&
4221   
            std::is_unsigned<T>::value &&
3255   
            ! std::is_same<T, bool>::value,
4222   
            ! std::is_same<T, bool>::value,
3256   
                T>::type
4223   
                T>::type
3257   
    {
4224   
    {
3258   
        if(sca_.k == json::kind::int64)
4225   
        if(sca_.k == json::kind::int64)
3259   
        {
4226   
        {
3260   
            auto const i = sca_.i;
4227   
            auto const i = sca_.i;
3261   
            if( i >= 0 && static_cast<std::uint64_t>(i) <=
4228   
            if( i >= 0 && static_cast<std::uint64_t>(i) <=
3262   
                (std::numeric_limits<T>::max)())
4229   
                (std::numeric_limits<T>::max)())
3263   
            {
4230   
            {
3264   
                e = {};
4231   
                e = {};
3265   
                return static_cast<T>(i);
4232   
                return static_cast<T>(i);
3266   
            }
4233   
            }
3267   
            e = error::not_exact;
4234   
            e = error::not_exact;
3268   
        }
4235   
        }
3269   
        else if(sca_.k == json::kind::uint64)
4236   
        else if(sca_.k == json::kind::uint64)
3270   
        {
4237   
        {
3271   
            auto const u = sca_.u;
4238   
            auto const u = sca_.u;
3272   
            if(u <= (std::numeric_limits<T>::max)())
4239   
            if(u <= (std::numeric_limits<T>::max)())
3273   
            {
4240   
            {
3274   
                e = {};
4241   
                e = {};
3275   
                return static_cast<T>(u);
4242   
                return static_cast<T>(u);
3276   
            }
4243   
            }
3277   
            e = error::not_exact;
4244   
            e = error::not_exact;
3278   
        }
4245   
        }
3279   
        else if(sca_.k == json::kind::double_)
4246   
        else if(sca_.k == json::kind::double_)
3280   
        {
4247   
        {
3281   
            auto const d = sca_.d;
4248   
            auto const d = sca_.d;
3282   
            if( d >= 0 &&
4249   
            if( d >= 0 &&
3283   
                d <= (detail::to_number_limit<T>::max)() &&
4250   
                d <= (detail::to_number_limit<T>::max)() &&
3284   
                static_cast<T>(d) == d)
4251   
                static_cast<T>(d) == d)
3285   
            {
4252   
            {
3286   
                e = {};
4253   
                e = {};
3287   
                return static_cast<T>(d);
4254   
                return static_cast<T>(d);
3288   
            }
4255   
            }
3289   
            e = error::not_exact;
4256   
            e = error::not_exact;
3290   
        }
4257   
        }
3291   
        else
4258   
        else
3292   
        {
4259   
        {
3293   
            e = error::not_number;
4260   
            e = error::not_number;
3294   
        }
4261   
        }
3295   
        return T{};
4262   
        return T{};
3296   
    }
4263   
    }
3297  
4264  
3298   
    template<class T>
4265   
    template<class T>
3299   
    auto
4266   
    auto
3300   
    to_number(error& e) const noexcept ->
4267   
    to_number(error& e) const noexcept ->
3301   
        typename std::enable_if<
4268   
        typename std::enable_if<
3302   
            std::is_floating_point<
4269   
            std::is_floating_point<
3303   
                T>::value, T>::type
4270   
                T>::value, T>::type
3304   
    {
4271   
    {
3305   
        if(sca_.k == json::kind::int64)
4272   
        if(sca_.k == json::kind::int64)
3306   
        {
4273   
        {
3307   
            e = {};
4274   
            e = {};
3308   
            return static_cast<T>(sca_.i);
4275   
            return static_cast<T>(sca_.i);
3309   
        }
4276   
        }
3310   
        if(sca_.k == json::kind::uint64)
4277   
        if(sca_.k == json::kind::uint64)
3311   
        {
4278   
        {
3312   
            e = {};
4279   
            e = {};
3313   
            return static_cast<T>(sca_.u);
4280   
            return static_cast<T>(sca_.u);
3314   
        }
4281   
        }
3315   
        if(sca_.k == json::kind::double_)
4282   
        if(sca_.k == json::kind::double_)
3316   
        {
4283   
        {
3317   
            e = {};
4284   
            e = {};
3318   
            return static_cast<T>(sca_.d);
4285   
            return static_cast<T>(sca_.d);
3319   
        }
4286   
        }
3320   
        e = error::not_number;
4287   
        e = error::not_number;
3321   
        return {};
4288   
        return {};
3322   
    }
4289   
    }
3323   
};
4290   
};
3324  
4291  
3325   
// Make sure things are as big as we think they should be
4292   
// Make sure things are as big as we think they should be
3326   
#if BOOST_JSON_ARCH == 64
4293   
#if BOOST_JSON_ARCH == 64
3327 - 
BOOST_CORE_STATIC_ASSERT( sizeof(value) == 24 );
4294 + 
BOOST_STATIC_ASSERT(sizeof(value) == 24);
3328   
#elif BOOST_JSON_ARCH == 32
4295   
#elif BOOST_JSON_ARCH == 32
3329 - 
BOOST_CORE_STATIC_ASSERT( sizeof(value) == 16 );
4296 + 
BOOST_STATIC_ASSERT(sizeof(value) == 16);
3330   
#else
4297   
#else
3331   
# error Unknown architecture
4298   
# error Unknown architecture
3332   
#endif
4299   
#endif
3333  
4300  
3334   
//----------------------------------------------------------
4301   
//----------------------------------------------------------
3335  
4302  
3336   
/** A key/value pair.
4303   
/** A key/value pair.
3337  
4304  
3338 - 
    This is the type of element used by the @ref object container.
4305 + 
    This is the type of element used by the @ref object
 
4306 + 
    container.
3339   
*/
4307   
*/
3340   
class key_value_pair
4308   
class key_value_pair
3341   
{
4309   
{
3342   
#ifndef BOOST_JSON_DOCS
4310   
#ifndef BOOST_JSON_DOCS
3343   
    friend struct detail::access;
4311   
    friend struct detail::access;
3344   
    using access = detail::access;
4312   
    using access = detail::access;
3345   
#endif
4313   
#endif
3346  
4314  
3347   
    BOOST_JSON_DECL
4315   
    BOOST_JSON_DECL
3348   
    static char const empty_[1];
4316   
    static char const empty_[1];
3349  
4317  
3350   
    inline
4318   
    inline
3351   
    key_value_pair(
4319   
    key_value_pair(
3352   
        pilfered<json::value> k,
4320   
        pilfered<json::value> k,
3353   
        pilfered<json::value> v) noexcept;
4321   
        pilfered<json::value> v) noexcept;
3354  
4322  
3355   
public:
4323   
public:
3356 - 
    /** Assignment
4324 + 
    /// Copy assignment (deleted).
3357 -
 
3358 - 
        This type is not copy or move-assignable. The copy assignment operator
 
3359 - 
        is deleted.
 
3360 - 
    */
 
3361   
    key_value_pair&
4325   
    key_value_pair&
3362   
    operator=(key_value_pair const&) = delete;
4326   
    operator=(key_value_pair const&) = delete;
3363  
4327  
3364   
    /** Destructor.
4328   
    /** Destructor.
3365  
4329  
3366 - 
        The value is destroyed and all internally allocated memory is freed.
4330 + 
        The value is destroyed and all internally
 
4331 + 
        allocated memory is freed.
3367   
    */
4332   
    */
3368   
    ~key_value_pair() noexcept
4333   
    ~key_value_pair() noexcept
3369   
    {
4334   
    {
3370   
        auto const& sp = value_.storage();
4335   
        auto const& sp = value_.storage();
3371   
        if(sp.is_not_shared_and_deallocate_is_trivial())
4336   
        if(sp.is_not_shared_and_deallocate_is_trivial())
3372   
            return;
4337   
            return;
3373   
        if(key_ == empty_)
4338   
        if(key_ == empty_)
3374   
            return;
4339   
            return;
3375   
        sp->deallocate(const_cast<char*>(key_),
4340   
        sp->deallocate(const_cast<char*>(key_),
3376   
            len_ + 1, alignof(char));
4341   
            len_ + 1, alignof(char));
3377   
    }
4342   
    }
3378  
4343  
3379 - 
    /** Constructors.
4344 + 
    /** Copy constructor.
3380  
4345  
3381 - 
        Construct a key/value pair.
4346 + 
        This constructs a key/value pair with a
 
4347 + 
        copy of another key/value pair, using
 
4348 + 
        the same memory resource as `other`.
3382  
4349  
3383 - 
        @li **(1)** uses a copy of the characters of `key`, and constructs the
4350 + 
        @par Exception Safety
3384 - 
            value as if by `value(std::forward<Args>(args)...)`.
4351 + 
        Strong guarantee.
3385 - 
        @li **(2)** equivalent to `key_value_pair(p.first, p.second, sp)`.
4352 + 
        Calls to `memory_resource::allocate` may throw.
3386 - 
        @li **(3)** equivalent to
 
3387 - 
            `key_value_pair(p.first, std::move(p.second), sp)`.
 
3388 - 
        @li **(4)** equivalent to
 
3389 - 
            `key_value_pair(other.key(), other.value(), sp)`.
 
3390 - 
        @li **(5)** equivalent to
 
3391 - 
            `key_value_pair(other.key(), other.value(), other.storage())`.
 
3392 - 
        @li **(6)** the pair s constructed by acquiring ownership of the
 
3393 - 
            contents of `other` using move semantics.
 
3394 - 
        @li **(7)** the pair is constructed by acquiring ownership of the
 
3395 - 
            contents of `other` using pilfer semantics. This is more efficient
 
3396 - 
            than move construction, when it is known that the moved-from object
 
3397 - 
            will be immediately destroyed afterwards.
 
3398  
4353  
3399 - 
        With **(2)**, **(3)**, **(4)** the pair uses the memory resource of
4354 + 
        @param other The key/value pair to copy.
3400 - 
        `sp`. With **(5)**, **(6)**, **(7)** it uses the memory resource of
4355 + 
    */
3401 - 
        `other.storage()`. With **(1)** it uses whatever memory resource
4356 + 
    key_value_pair(
3402 - 
        `value(std::forward<Args>(args)...)` would use. In any case the pair
4357 + 
        key_value_pair const& other)
3403 - 
        acquires shared ownership of its memory resource
4358 + 
        : key_value_pair(other,
 
4359 + 
            other.storage())
 
4360 + 
    {
 
4361 + 
    }
3404  
4362  
3405 - 
        After **(6)** `other` holds an empty key, and a null value with its
4363 + 
    /** Copy constructor.
3406 - 
        current storage pointer.
 
3407  
4364  
3408 - 
        After **(7)** `other` is not in a usable state and may only be destroyed.
4365 + 
        This constructs a key/value pair with a
 
4366 + 
        copy of another key/value pair, using
 
4367 + 
        the specified memory resource.
 
4368 +
 
4369 + 
        @par Exception Safety
 
4370 + 
        Strong guarantee.
 
4371 + 
        Calls to `memory_resource::allocate` may throw.
 
4372 +
 
4373 + 
        @param other The key/value pair to copy.
 
4374 +
 
4375 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
4376 + 
        use. The element will acquire shared ownership of the memory resource.
 
4377 + 
    */
 
4378 + 
    BOOST_JSON_DECL
 
4379 + 
    key_value_pair(
 
4380 + 
        key_value_pair const& other,
 
4381 + 
        storage_ptr sp);
 
4382 +
 
4383 + 
    /** Move constructor.
 
4384 +
 
4385 + 
        The pair is constructed by acquiring
 
4386 + 
        ownership of the contents of `other` and
 
4387 + 
        shared ownership of `other`'s memory resource.
 
4388 +
 
4389 + 
        @note
 
4390 +
 
4391 + 
        After construction, the moved-from pair holds an
 
4392 + 
        empty key, and a null value with its current
 
4393 + 
        storage pointer.
3409  
4394  
3410   
        @par Complexity
4395   
        @par Complexity
3411   
        Constant.
4396   
        Constant.
3412  
4397  
3413   
        @par Exception Safety
4398   
        @par Exception Safety
3414 - 
        Strong guarantee. Calls to `memory_resource::allocate` may throw.
4399 + 
        No-throw guarantee.
3415 - 
        @param key The key string to use.
 
3416 - 
        @param args Optional arguments forwarded to the @ref value constructor.
 
3417  
4400  
3418 - 
        @throw boost::system::system_error The size of the key would exceed
4401 + 
        @param other The pair to move.
3419 - 
               @ref string::max_size.
4402 + 
    */
 
4403 + 
    key_value_pair(
 
4404 + 
        key_value_pair&& other) noexcept
 
4405 + 
        : value_(std::move(other.value_))
 
4406 + 
        , key_(detail::exchange(
 
4407 + 
            other.key_, empty_))
 
4408 + 
        , len_(detail::exchange(
 
4409 + 
            other.len_, 0))
 
4410 + 
    {
 
4411 + 
    }
 
4412 +
 
4413 + 
    /** Pilfer constructor.
 
4414 +
 
4415 + 
        The pair is constructed by acquiring ownership
 
4416 + 
        of the contents of `other` using pilfer semantics.
 
4417 + 
        This is more efficient than move construction, when
 
4418 + 
        it is known that the moved-from object will be
 
4419 + 
        immediately destroyed afterwards.
 
4420 +
 
4421 + 
        @par Complexity
 
4422 + 
        Constant.
 
4423 +
 
4424 + 
        @par Exception Safety
 
4425 + 
        No-throw guarantee.
 
4426 +
 
4427 + 
        @param other The value to pilfer. After pilfer
 
4428 + 
        construction, `other` is not in a usable state
 
4429 + 
        and may only be destroyed.
3420  
4430  
3421   
        @see @ref pilfer,
4431   
        @see @ref pilfer,
3422 - 
             [Valueless Variants Considered Harmful](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0308r0.html).
4432 + 
            <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0308r0.html">
 
4433 + 
                Valueless Variants Considered Harmful</a>
 
4434 + 
    */
 
4435 + 
    key_value_pair(
 
4436 + 
        pilfered<key_value_pair> other) noexcept
 
4437 + 
        : value_(pilfer(other.get().value_))
 
4438 + 
        , key_(detail::exchange(
 
4439 + 
            other.get().key_, empty_))
 
4440 + 
        , len_(detail::exchange(
 
4441 + 
            other.get().len_, 0))
 
4442 + 
    {
 
4443 + 
    }
3423  
4444  
3424 - 
        @{
4445 + 
    /** Constructor.
 
4446 +
 
4447 + 
        This constructs a key/value pair.
 
4448 +
 
4449 + 
        @par Exception Safety
 
4450 + 
        Strong guarantee.
 
4451 + 
        Calls to `memory_resource::allocate` may throw.
 
4452 +
 
4453 + 
        @param key The key string to use.
 
4454 +
 
4455 + 
        @param args Optional arguments forwarded to
 
4456 + 
        the @ref value constructor.
3425   
    */
4457   
    */
3426   
    template<class... Args>
4458   
    template<class... Args>
3427   
    explicit
4459   
    explicit
3428   
    key_value_pair(
4460   
    key_value_pair(
3429   
        string_view key,
4461   
        string_view key,
3430   
        Args&&... args)
4462   
        Args&&... args)
3431   
        : value_(std::forward<Args>(args)...)
4463   
        : value_(std::forward<Args>(args)...)
3432   
    {
4464   
    {
3433   
        if(key.size() > string::max_size())
4465   
        if(key.size() > string::max_size())
3434   
        {
4466   
        {
3435   
            BOOST_STATIC_CONSTEXPR source_location loc = BOOST_CURRENT_LOCATION;
4467   
            BOOST_STATIC_CONSTEXPR source_location loc = BOOST_CURRENT_LOCATION;
3436   
            detail::throw_system_error( error::key_too_large, &loc );
4468   
            detail::throw_system_error( error::key_too_large, &loc );
3437   
        }
4469   
        }
3438   
        auto s = reinterpret_cast<
4470   
        auto s = reinterpret_cast<
3439   
            char*>(value_.storage()->
4471   
            char*>(value_.storage()->
3440   
                allocate(key.size() + 1, alignof(char)));
4472   
                allocate(key.size() + 1, alignof(char)));
3441   
        std::memcpy(s, key.data(), key.size());
4473   
        std::memcpy(s, key.data(), key.size());
3442   
        s[key.size()] = 0;
4474   
        s[key.size()] = 0;
3443   
        key_ = s;
4475   
        key_ = s;
3444   
        len_ = static_cast<
4476   
        len_ = static_cast<
3445   
            std::uint32_t>(key.size());
4477   
            std::uint32_t>(key.size());
3446   
    }
4478   
    }
3447  
4479  
3448 - 
    /** Overload
4480 + 
    /** Constructor.
3449  
4481  
3450 - 
        @param p A `std::pair` with the key string and @ref value to construct
4482 + 
        This constructs a key/value pair. A
3451 - 
               with.
4483 + 
        copy of the specified value is made,
3452 - 
        @param sp A pointer to the @ref boost::container::pmr::memory_resource
4484 + 
        using the specified memory resource.
3453 - 
               to use.
4485 +
 
4486 + 
        @par Exception Safety
 
4487 + 
        Strong guarantee.
 
4488 + 
        Calls to `memory_resource::allocate` may throw.
 
4489 +
 
4490 + 
        @param p A `std::pair` with the key
 
4491 + 
            string and @ref value to construct with.
 
4492 +
 
4493 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
4494 + 
        use. The element will acquire shared ownership of the memory resource.
3454   
    */
4495   
    */
3455   
    explicit
4496   
    explicit
3456   
    key_value_pair(
4497   
    key_value_pair(
3457   
        std::pair<
4498   
        std::pair<
3458   
            string_view,
4499   
            string_view,
3459   
            json::value> const& p,
4500   
            json::value> const& p,
3460   
        storage_ptr sp = {})
4501   
        storage_ptr sp = {})
3461   
        : key_value_pair(
4502   
        : key_value_pair(
3462   
            p.first,
4503   
            p.first,
3463   
            p.second,
4504   
            p.second,
3464   
            std::move(sp))
4505   
            std::move(sp))
3465   
    {
4506   
    {
3466   
    }
4507   
    }
3467  
4508  
3468 - 
    /// Overload
4509 + 
    /** Constructor.
 
4510 +
 
4511 + 
        This constructs a key/value pair.
 
4512 + 
        Ownership of the specified value is
 
4513 + 
        transferred by move construction.
 
4514 +
 
4515 + 
        @par Exception Safety
 
4516 + 
        Strong guarantee.
 
4517 + 
        Calls to `memory_resource::allocate` may throw.
 
4518 +
 
4519 + 
        @param p A `std::pair` with the key
 
4520 + 
            string and @ref value to construct with.
 
4521 +
 
4522 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
4523 + 
        use. The element will acquire shared ownership of the memory resource.
 
4524 + 
    */
3469   
    explicit
4525   
    explicit
3470   
    key_value_pair(
4526   
    key_value_pair(
3471   
        std::pair<
4527   
        std::pair<
3472   
            string_view,
4528   
            string_view,
3473   
            json::value>&& p,
4529   
            json::value>&& p,
3474   
        storage_ptr sp = {})
4530   
        storage_ptr sp = {})
3475   
        : key_value_pair(
4531   
        : key_value_pair(
3476   
            p.first,
4532   
            p.first,
3477   
            std::move(p).second,
4533   
            std::move(p).second,
3478   
            std::move(sp))
4534   
            std::move(sp))
3479   
    {
4535   
    {
3480   
    }
4536   
    }
3481  
4537  
3482 - 
    /** Overload
4538 + 
    /** Return the associated memory resource.
3483 -
 
3484 - 
        @param other Another key/value pair.
 
3485 - 
        @param sp
 
3486 - 
    */
 
3487 - 
    BOOST_JSON_DECL
 
3488 - 
    key_value_pair(
 
3489 - 
        key_value_pair const& other,
 
3490 - 
        storage_ptr sp);
 
3491 -
 
3492 - 
    /// Overload
 
3493 - 
    key_value_pair(
 
3494 - 
        key_value_pair const& other)
 
3495 - 
        : key_value_pair(other,
 
3496 - 
            other.storage())
 
3497 - 
    {
 
3498 - 
    }
 
3499 -
 
3500 - 
    /// Overload
 
3501 - 
    key_value_pair(
 
3502 - 
        key_value_pair&& other) noexcept
 
3503 - 
        : value_(std::move(other.value_))
 
3504 - 
        , key_(detail::exchange(
 
3505 - 
            other.key_, empty_))
 
3506 - 
        , len_(detail::exchange(
 
3507 - 
            other.len_, 0))
 
3508 - 
    {
 
3509 - 
    }
 
3510 -
 
3511 - 
    /// Overload
 
3512 - 
    key_value_pair(
 
3513 - 
        pilfered<key_value_pair> other) noexcept
 
3514 - 
        : value_(pilfer(other.get().value_))
 
3515 - 
        , key_(detail::exchange(
 
3516 - 
            other.get().key_, empty_))
 
3517 - 
        , len_(detail::exchange(
 
3518 - 
            other.get().len_, 0))
 
3519 - 
    {
 
3520 - 
    }
 
3521 - 
    /// @}
 
3522 -
 
3523 - 
    /** The associated memory resource.
 
3524  
4539  
3525 - 
        Returns a pointer to the memory resource used to construct the value.
4540 + 
        This returns a pointer to the memory
 
4541 + 
        resource used to construct the value.
3526  
4542  
3527   
        @par Complexity
4543   
        @par Complexity
3528   
        Constant.
4544   
        Constant.
3529  
4545  
3530   
        @par Exception Safety
4546   
        @par Exception Safety
3531   
        No-throw guarantee.
4547   
        No-throw guarantee.
3532   
    */
4548   
    */
3533   
    storage_ptr const&
4549   
    storage_ptr const&
3534   
    storage() const noexcept
4550   
    storage() const noexcept
3535   
    {
4551   
    {
3536   
        return value_.storage();
4552   
        return value_.storage();
3537   
    }
4553   
    }
3538  
4554  
3539 - 
    /** The pair's key.
4555 + 
    /** Return the key of this element.
3540  
4556  
3541 - 
        After construction, the key may not be modified.
4557 + 
        After construction, the key may
 
4558 + 
        not be modified.
3542  
4559  
3543   
        @par Complexity
4560   
        @par Complexity
3544   
        Constant.
4561   
        Constant.
3545  
4562  
3546   
        @par Exception Safety
4563   
        @par Exception Safety
3547   
        No-throw guarantee.
4564   
        No-throw guarantee.
3548   
    */
4565   
    */
3549   
    string_view const
4566   
    string_view const
3550   
    key() const noexcept
4567   
    key() const noexcept
3551   
    {
4568   
    {
3552   
        return { key_, len_ };
4569   
        return { key_, len_ };
3553   
    }
4570   
    }
3554  
4571  
3555 - 
    /** The pair's key as a null-terminated string.
4572 + 
    /** Return the key of this element as a null-terminated string.
3556  
4573  
3557   
        @par Complexity
4574   
        @par Complexity
3558   
        Constant.
4575   
        Constant.
3559  
4576  
3560   
        @par Exception Safety
4577   
        @par Exception Safety
3561   
        No-throw guarantee.
4578   
        No-throw guarantee.
3562   
    */
4579   
    */
3563   
    char const*
4580   
    char const*
3564   
    key_c_str() const noexcept
4581   
    key_c_str() const noexcept
3565   
    {
4582   
    {
3566   
        return key_;
4583   
        return key_;
3567   
    }
4584   
    }
3568  
4585  
3569 - 
    /** The pair's value.
4586 + 
    /** Return the value of this element.
3570  
4587  
3571   
        @par Complexity
4588   
        @par Complexity
3572   
        Constant.
4589   
        Constant.
3573  
4590  
3574   
        @par Exception Safety
4591   
        @par Exception Safety
3575 -
 
3576 - 
        @{
 
3577   
        No-throw guarantee.
4592   
        No-throw guarantee.
3578   
    */
4593   
    */
 
4594 + 
    /** @{ */
3579   
    json::value const&
4595   
    json::value const&
3580   
    value() const& noexcept
4596   
    value() const& noexcept
3581   
    {
4597   
    {
3582   
        return value_;
4598   
        return value_;
3583   
    }
4599   
    }
3584  
4600  
3585   
    json::value&&
4601   
    json::value&&
3586   
    value() && noexcept
4602   
    value() && noexcept
3587   
    {
4603   
    {
3588   
        return std::move( value() );
4604   
        return std::move( value() );
3589   
    }
4605   
    }
3590  
4606  
3591   
    json::value&
4607   
    json::value&
3592   
    value() & noexcept
4608   
    value() & noexcept
3593   
    {
4609   
    {
3594   
        return value_;
4610   
        return value_;
3595   
    }
4611   
    }
3596 - 
    /// @}
4612 + 
    /** @} */
3597  
4613  
3598   
private:
4614   
private:
3599   
    json::value value_;
4615   
    json::value value_;
3600   
    char const* key_;
4616   
    char const* key_;
3601   
    std::uint32_t len_;
4617   
    std::uint32_t len_;
3602   
    std::uint32_t next_;
4618   
    std::uint32_t next_;
3603   
};
4619   
};
3604  
4620  
3605   
//----------------------------------------------------------
4621   
//----------------------------------------------------------
3606  
4622  
3607   
#ifdef BOOST_JSON_DOCS
4623   
#ifdef BOOST_JSON_DOCS
3608  
4624  
3609   
/** Tuple-like element access.
4625   
/** Tuple-like element access.
3610  
4626  
3611 - 
    This overload of `get` permits the key and value of a @ref key_value_pair
4627 + 
    This overload permits the key and value
3612 - 
    to be accessed by index. For example:
4628 + 
    of a `key_value_pair` to be accessed
 
4629 + 
    by index. For example:
3613  
4630  
3614   
    @code
4631   
    @code
 
4632 +
3615   
    key_value_pair kvp("num", 42);
4633   
    key_value_pair kvp("num", 42);
 
4634 +
3616   
    string_view key = get<0>(kvp);
4635   
    string_view key = get<0>(kvp);
3617   
    value& jv = get<1>(kvp);
4636   
    value& jv = get<1>(kvp);
 
4637 +
3618   
    @endcode
4638   
    @endcode
3619  
4639  
3620   
    @par Structured Bindings
4640   
    @par Structured Bindings
3621 - 
    When using C++17 or greater, objects of type @ref key_value_pair may be
4641 +
3622 - 
    used to initialize structured bindings:
4642 + 
    When using C++17 or greater, objects of type
 
4643 + 
    @ref key_value_pair may be used to initialize
 
4644 + 
    structured bindings:
3623  
4645  
3624   
    @code
4646   
    @code
 
4647 +
3625   
    key_value_pair kvp("num", 42);
4648   
    key_value_pair kvp("num", 42);
 
4649 +
3626   
    auto& [key, value] = kvp;
4650   
    auto& [key, value] = kvp;
 
4651 +
3627   
    @endcode
4652   
    @endcode
3628  
4653  
3629   
    Depending on the value of `I`, the return type will be:
4654   
    Depending on the value of `I`, the return type will be:
3630  
4655  
3631   
    @li `string_view const` if `I == 0`, or
4656   
    @li `string_view const` if `I == 0`, or
 
4657 +
3632   
    @li `value&`, `value const&`, or `value&&` if `I == 1`.
4658   
    @li `value&`, `value const&`, or `value&&` if `I == 1`.
3633  
4659  
3634 - 
    Using any other value for `I` is ill-formed.
4660 + 
    Any other value for `I` is ill-formed.
 
4661 +
 
4662 + 
    @tparam I The element index to access.
3635  
4663  
3636 - 
    `std::is_same_v< std::remove_cvref_t<T>, key_value_pair >`
 
3637   
    @par Constraints
4664   
    @par Constraints
3638  
4665  
3639 - 
    @tparam I The element index to access.
4666 + 
    `std::is_same_v< std::remove_cvref_t<T>, key_value_pair >`
3640  
4667  
3641 - 
    @return `kvp.key()` if `I == 0`, or `kvp.value()` if `I == 1`.
4668 + 
    @return `kvp.key()` if `I == 0`, or `kvp.value()`
 
4669 + 
    if `I == 1`.
3642  
4670  
3643 - 
    @param kvp The @ref key_value_pair object to access.
4671 + 
    @param kvp The @ref key_value_pair object
 
4672 + 
    to access.
3644   
*/
4673   
*/
3645   
template<
4674   
template<
3646   
    std::size_t I,
4675   
    std::size_t I,
3647   
    class T>
4676   
    class T>
3648   
__see_below__
4677   
__see_below__
3649   
get(T&& kvp) noexcept;
4678   
get(T&& kvp) noexcept;
3650  
4679  
3651   
#else
4680   
#else
3652  
4681  
3653   
template<std::size_t I>
4682   
template<std::size_t I>
3654   
auto
4683   
auto
3655   
get(key_value_pair const&) noexcept ->
4684   
get(key_value_pair const&) noexcept ->
3656   
    typename std::conditional<I == 0,
4685   
    typename std::conditional<I == 0,
3657   
        string_view const,
4686   
        string_view const,
3658   
        value const&>::type
4687   
        value const&>::type
3659   
{
4688   
{
3660   
    static_assert(I == 0,
4689   
    static_assert(I == 0,
3661   
        "key_value_pair index out of range");
4690   
        "key_value_pair index out of range");
3662   
}
4691   
}
3663  
4692  
3664   
template<std::size_t I>
4693   
template<std::size_t I>
3665   
auto
4694   
auto
3666   
get(key_value_pair&) noexcept ->
4695   
get(key_value_pair&) noexcept ->
3667   
    typename std::conditional<I == 0,
4696   
    typename std::conditional<I == 0,
3668   
        string_view const,
4697   
        string_view const,
3669   
        value&>::type
4698   
        value&>::type
3670   
{
4699   
{
3671   
    static_assert(I == 0,
4700   
    static_assert(I == 0,
3672   
        "key_value_pair index out of range");
4701   
        "key_value_pair index out of range");
3673   
}
4702   
}
3674  
4703  
3675   
template<std::size_t I>
4704   
template<std::size_t I>
3676   
auto
4705   
auto
3677   
get(key_value_pair&&) noexcept ->
4706   
get(key_value_pair&&) noexcept ->
3678   
    typename std::conditional<I == 0,
4707   
    typename std::conditional<I == 0,
3679   
        string_view const,
4708   
        string_view const,
3680   
        value&&>::type
4709   
        value&&>::type
3681   
{
4710   
{
3682   
    static_assert(I == 0,
4711   
    static_assert(I == 0,
3683   
        "key_value_pair index out of range");
4712   
        "key_value_pair index out of range");
3684   
}
4713   
}
3685  
4714  
3686   
/** Extracts a key_value_pair's key using tuple-like interface
4715   
/** Extracts a key_value_pair's key using tuple-like interface
3687   
*/
4716   
*/
3688   
template<>
4717   
template<>
3689   
inline
4718   
inline
3690   
string_view const
4719   
string_view const
3691   
get<0>(key_value_pair const& kvp) noexcept
4720   
get<0>(key_value_pair const& kvp) noexcept
3692   
{
4721   
{
3693   
    return kvp.key();
4722   
    return kvp.key();
3694   
}
4723   
}
3695  
4724  
3696   
/** Extracts a key_value_pair's key using tuple-like interface
4725   
/** Extracts a key_value_pair's key using tuple-like interface
3697   
*/
4726   
*/
3698   
template<>
4727   
template<>
3699   
inline
4728   
inline
3700   
string_view const
4729   
string_view const
3701   
get<0>(key_value_pair& kvp) noexcept
4730   
get<0>(key_value_pair& kvp) noexcept
3702   
{
4731   
{
3703   
    return kvp.key();
4732   
    return kvp.key();
3704   
}
4733   
}
3705  
4734  
3706   
/** Extracts a key_value_pair's key using tuple-like interface
4735   
/** Extracts a key_value_pair's key using tuple-like interface
3707   
*/
4736   
*/
3708   
template<>
4737   
template<>
3709   
inline
4738   
inline
3710   
string_view const
4739   
string_view const
3711   
get<0>(key_value_pair&& kvp) noexcept
4740   
get<0>(key_value_pair&& kvp) noexcept
3712   
{
4741   
{
3713   
    return kvp.key();
4742   
    return kvp.key();
3714   
}
4743   
}
3715  
4744  
3716   
/** Extracts a key_value_pair's value using tuple-like interface
4745   
/** Extracts a key_value_pair's value using tuple-like interface
3717   
*/
4746   
*/
3718   
template<>
4747   
template<>
3719   
inline
4748   
inline
3720   
value const&
4749   
value const&
3721   
get<1>(key_value_pair const& kvp) noexcept
4750   
get<1>(key_value_pair const& kvp) noexcept
3722   
{
4751   
{
3723   
    return kvp.value();
4752   
    return kvp.value();
3724   
}
4753   
}
3725  
4754  
3726   
/** Extracts a key_value_pair's value using tuple-like interface
4755   
/** Extracts a key_value_pair's value using tuple-like interface
3727   
*/
4756   
*/
3728   
template<>
4757   
template<>
3729   
inline
4758   
inline
3730   
value&
4759   
value&
3731   
get<1>(key_value_pair& kvp) noexcept
4760   
get<1>(key_value_pair& kvp) noexcept
3732   
{
4761   
{
3733   
    return kvp.value();
4762   
    return kvp.value();
3734   
}
4763   
}
3735  
4764  
3736   
/** Extracts a key_value_pair's value using tuple-like interface
4765   
/** Extracts a key_value_pair's value using tuple-like interface
3737   
*/
4766   
*/
3738   
template<>
4767   
template<>
3739   
inline
4768   
inline
3740   
value&&
4769   
value&&
3741   
get<1>(key_value_pair&& kvp) noexcept
4770   
get<1>(key_value_pair&& kvp) noexcept
3742   
{
4771   
{
3743   
    return std::move(kvp.value());
4772   
    return std::move(kvp.value());
3744   
}
4773   
}
3745  
4774  
3746   
#endif
4775   
#endif
3747  
4776  
3748   
} // namespace json
4777   
} // namespace json
3749   
} // namespace boost
4778   
} // namespace boost
3750  
4779  
3751   
#ifdef __clang__
4780   
#ifdef __clang__
3752   
# pragma clang diagnostic push
4781   
# pragma clang diagnostic push
3753   
# pragma clang diagnostic ignored "-Wmismatched-tags"
4782   
# pragma clang diagnostic ignored "-Wmismatched-tags"
3754   
#endif
4783   
#endif
3755  
4784  
3756   
#ifndef BOOST_JSON_DOCS
4785   
#ifndef BOOST_JSON_DOCS
3757  
4786  
3758   
namespace std {
4787   
namespace std {
3759  
4788  
3760   
/** Tuple-like size access for key_value_pair
4789   
/** Tuple-like size access for key_value_pair
3761   
*/
4790   
*/
3762   
template<>
4791   
template<>
3763   
struct tuple_size< ::boost::json::key_value_pair >
4792   
struct tuple_size< ::boost::json::key_value_pair >
3764   
    : std::integral_constant<std::size_t, 2>
4793   
    : std::integral_constant<std::size_t, 2>
3765   
{
4794   
{
3766   
};
4795   
};
3767  
4796  
3768   
/** Tuple-like access for the key type of key_value_pair
4797   
/** Tuple-like access for the key type of key_value_pair
3769   
*/
4798   
*/
3770   
template<>
4799   
template<>
3771   
struct tuple_element<0, ::boost::json::key_value_pair>
4800   
struct tuple_element<0, ::boost::json::key_value_pair>
3772   
{
4801   
{
3773   
    using type = ::boost::json::string_view const;
4802   
    using type = ::boost::json::string_view const;
3774   
};
4803   
};
3775  
4804  
3776   
/** Tuple-like access for the value type of key_value_pair
4805   
/** Tuple-like access for the value type of key_value_pair
3777   
*/
4806   
*/
3778   
template<>
4807   
template<>
3779   
struct tuple_element<1, ::boost::json::key_value_pair>
4808   
struct tuple_element<1, ::boost::json::key_value_pair>
3780   
{
4809   
{
3781   
    using type = ::boost::json::value&;
4810   
    using type = ::boost::json::value&;
3782   
};
4811   
};
3783  
4812  
3784   
/** Tuple-like access for the value type of key_value_pair
4813   
/** Tuple-like access for the value type of key_value_pair
3785   
*/
4814   
*/
3786   
template<>
4815   
template<>
3787   
struct tuple_element<1, ::boost::json::key_value_pair const>
4816   
struct tuple_element<1, ::boost::json::key_value_pair const>
3788   
{
4817   
{
3789   
    using type = ::boost::json::value const&;
4818   
    using type = ::boost::json::value const&;
3790   
};
4819   
};
3791  
4820  
3792   
} // std
4821   
} // std
3793  
4822  
3794   
#endif
4823   
#endif
3795  
4824  
3796   
// std::hash specialization
4825   
// std::hash specialization
3797   
#ifndef BOOST_JSON_DOCS
4826   
#ifndef BOOST_JSON_DOCS
3798   
namespace std {
4827   
namespace std {
3799   
template <>
4828   
template <>
3800   
struct hash< ::boost::json::value > {
4829   
struct hash< ::boost::json::value > {
3801   
    BOOST_JSON_DECL
4830   
    BOOST_JSON_DECL
3802   
    std::size_t
4831   
    std::size_t
3803   
    operator()(::boost::json::value const& jv) const noexcept;
4832   
    operator()(::boost::json::value const& jv) const noexcept;
3804   
};
4833   
};
3805   
} // std
4834   
} // std
3806   
#endif
4835   
#endif
3807  
4836  
3808  
4837  
3809   
#ifdef __clang__
4838   
#ifdef __clang__
3810   
# pragma clang diagnostic pop
4839   
# pragma clang diagnostic pop
3811   
#endif
4840   
#endif
3812  
4841  
3813   
// These are here because value, array,
4842   
// These are here because value, array,
3814   
// and object form cyclic references.
4843   
// and object form cyclic references.
3815  
4844  
3816   
#include <boost/json/detail/impl/array.hpp>
4845   
#include <boost/json/detail/impl/array.hpp>
3817   
#include <boost/json/impl/array.hpp>
4846   
#include <boost/json/impl/array.hpp>
3818   
#include <boost/json/impl/object.hpp>
4847   
#include <boost/json/impl/object.hpp>
3819   
#include <boost/json/impl/value.hpp>
4848   
#include <boost/json/impl/value.hpp>
3820  
4849  
3821   
// These must come after array and object
4850   
// These must come after array and object
3822   
#include <boost/json/impl/value_ref.hpp>
4851   
#include <boost/json/impl/value_ref.hpp>
3823  
4852  
3824   
#endif
4853   
#endif