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_STRING_HPP
11   
#ifndef BOOST_JSON_STRING_HPP
12   
#define BOOST_JSON_STRING_HPP
12   
#define BOOST_JSON_STRING_HPP
13  
13  
14   
#include <boost/json/detail/config.hpp>
14   
#include <boost/json/detail/config.hpp>
15   
#include <boost/json/pilfer.hpp>
15   
#include <boost/json/pilfer.hpp>
16   
#include <boost/json/storage_ptr.hpp>
16   
#include <boost/json/storage_ptr.hpp>
17   
#include <boost/json/string_view.hpp>
17   
#include <boost/json/string_view.hpp>
18   
#include <boost/json/detail/digest.hpp>
18   
#include <boost/json/detail/digest.hpp>
19   
#include <boost/json/detail/except.hpp>
19   
#include <boost/json/detail/except.hpp>
20   
#include <boost/json/detail/string_impl.hpp>
20   
#include <boost/json/detail/string_impl.hpp>
21   
#include <boost/json/detail/value.hpp>
21   
#include <boost/json/detail/value.hpp>
22   
#include <boost/system/result.hpp>
22   
#include <boost/system/result.hpp>
23   
#include <cstring>
23   
#include <cstring>
24   
#include <iosfwd>
24   
#include <iosfwd>
25   
#include <iterator>
25   
#include <iterator>
26   
#include <new>
26   
#include <new>
27   
#include <type_traits>
27   
#include <type_traits>
28   
#include <utility>
28   
#include <utility>
29  
29  
30   
namespace boost {
30   
namespace boost {
31   
namespace json {
31   
namespace json {
32  
32  
33   
class value;
33   
class value;
34  
34  
35   
/** The native type of string values.
35   
/** The native type of string values.
36  
36  
37 - 
    Instances of string store and manipulate sequences of `char` using the
37 + 
    Instances of string store and manipulate sequences
38 - 
    UTF-8 encoding. The elements of a string are stored contiguously. A pointer
38 + 
    of `char` using the UTF-8 encoding. The elements of
39 - 
    to any character in a string may be passed to functions that expect
39 + 
    a string are stored contiguously. A pointer to any
40 - 
    a pointer to the first element of a null-terminated `char` array. The type
40 + 
    character in a string may be passed to functions
41 - 
    uses small buffer optimisation to avoid allocations for small strings.
41 + 
    that expect a pointer to the first element of a
 
42 + 
    null-terminated `char` array. The type uses small
 
43 + 
    buffer optimisation to avoid allocations for small
 
44 + 
    strings.
42  
45  
43   
    String iterators are regular `char` pointers.
46   
    String iterators are regular `char` pointers.
44  
47  
45 - 
    @attention `string` member functions do not validate any UTF-8 byte sequences
48 + 
    @note `string` member functions do not validate
46 - 
    passed to them.
49 + 
    any UTF-8 byte sequences passed to them.
47  
50  
48   
    @par Thread Safety
51   
    @par Thread Safety
49 - 
    Non-const member functions may not be called concurrently with any other
52 +
50 - 
    member functions.
53 + 
    Non-const member functions may not be called
 
54 + 
    concurrently with any other member functions.
51  
55  
52   
    @par Satisfies
56   
    @par Satisfies
53 - 
        [_ContiguousContainer_](https://en.cppreference.com/w/cpp/named_req/ContiguousContainer),
57 + 
        <a href="https://en.cppreference.com/w/cpp/named_req/ContiguousContainer"><em>ContiguousContainer</em></a>,
54 - 
        [_ReversibleContainer_](https://en.cppreference.com/w/cpp/named_req/ReversibleContainer),
58 + 
        <a href="https://en.cppreference.com/w/cpp/named_req/ReversibleContainer"><em>ReversibleContainer</em></a>, and
55 - 
        and {req_SequenceContainer}.
59 + 
        <a href="https://en.cppreference.com/w/cpp/named_req/SequenceContainer"><em>SequenceContainer</em></a>.
56   
*/
60   
*/
57   
class string
61   
class string
58   
{
62   
{
59   
    friend class value;
63   
    friend class value;
60   
#ifndef BOOST_JSON_DOCS
64   
#ifndef BOOST_JSON_DOCS
61   
    // VFALCO doc toolchain shouldn't show this but does
65   
    // VFALCO doc toolchain shouldn't show this but does
62   
    friend struct detail::access;
66   
    friend struct detail::access;
63   
#endif
67   
#endif
64  
68  
65   
    using string_impl = detail::string_impl;
69   
    using string_impl = detail::string_impl;
66  
70  
67   
    inline
71   
    inline
68   
    string(
72   
    string(
69   
        detail::key_t const&,
73   
        detail::key_t const&,
70   
        string_view s,
74   
        string_view s,
71   
        storage_ptr sp);
75   
        storage_ptr sp);
72  
76  
73   
    inline
77   
    inline
74   
    string(
78   
    string(
75   
        detail::key_t const&,
79   
        detail::key_t const&,
76   
        string_view s1,
80   
        string_view s1,
77   
        string_view s2,
81   
        string_view s2,
78   
        storage_ptr sp);
82   
        storage_ptr sp);
79  
83  
80   
public:
84   
public:
81   
    /// Associated [Allocator](https://en.cppreference.com/w/cpp/named_req/Allocator)
85   
    /// Associated [Allocator](https://en.cppreference.com/w/cpp/named_req/Allocator)
82   
    using allocator_type = container::pmr::polymorphic_allocator<value>;
86   
    using allocator_type = container::pmr::polymorphic_allocator<value>;
83  
87  
84   
    /// The type of a character
88   
    /// The type of a character
85   
    using value_type        = char;
89   
    using value_type        = char;
86  
90  
87   
    /// The type used to represent unsigned integers
91   
    /// The type used to represent unsigned integers
88   
    using size_type         = std::size_t;
92   
    using size_type         = std::size_t;
89  
93  
90   
    /// The type used to represent signed integers
94   
    /// The type used to represent signed integers
91   
    using difference_type   = std::ptrdiff_t;
95   
    using difference_type   = std::ptrdiff_t;
92  
96  
93   
    /// A pointer to an element
97   
    /// A pointer to an element
94   
    using pointer           = char*;
98   
    using pointer           = char*;
95  
99  
96   
    /// A const pointer to an element
100   
    /// A const pointer to an element
97   
    using const_pointer     = char const*;
101   
    using const_pointer     = char const*;
98  
102  
99   
    /// A reference to an element
103   
    /// A reference to an element
100   
    using reference         = char&;
104   
    using reference         = char&;
101  
105  
102   
    /// A const reference to an element
106   
    /// A const reference to an element
103   
    using const_reference   = const char&;
107   
    using const_reference   = const char&;
104  
108  
105   
    /// A random access iterator to an element
109   
    /// A random access iterator to an element
106   
    using iterator          = char*;
110   
    using iterator          = char*;
107  
111  
108   
    /// A random access const iterator to an element
112   
    /// A random access const iterator to an element
109   
    using const_iterator    = char const*;
113   
    using const_iterator    = char const*;
110  
114  
111   
    /// A reverse random access iterator to an element
115   
    /// A reverse random access iterator to an element
112   
    using reverse_iterator =
116   
    using reverse_iterator =
113   
        std::reverse_iterator<iterator>;
117   
        std::reverse_iterator<iterator>;
114  
118  
115   
    /// A reverse random access const iterator to an element
119   
    /// A reverse random access const iterator to an element
116   
    using const_reverse_iterator =
120   
    using const_reverse_iterator =
117   
        std::reverse_iterator<const_iterator>;
121   
        std::reverse_iterator<const_iterator>;
118  
122  
119 - 
    /** A special index
123 + 
    /// A special index
120 -
 
121 - 
        Represents the end of the string.
 
122 - 
    */
 
123   
    static constexpr std::size_t npos =
124   
    static constexpr std::size_t npos =
124   
        string_view::npos;
125   
        string_view::npos;
125  
126  
126   
private:
127   
private:
127   
    template<class T>
128   
    template<class T>
128   
    using is_inputit = typename std::enable_if<
129   
    using is_inputit = typename std::enable_if<
129   
        std::is_convertible<typename
130   
        std::is_convertible<typename
130   
            std::iterator_traits<T>::reference,
131   
            std::iterator_traits<T>::reference,
131   
            char>::value>::type;
132   
            char>::value>::type;
132  
133  
133   
    storage_ptr sp_; // must come first
134   
    storage_ptr sp_; // must come first
134   
    string_impl impl_;
135   
    string_impl impl_;
135  
136  
136   
public:
137   
public:
137   
    /** Destructor.
138   
    /** Destructor.
138  
139  
139 - 
        Any dynamically allocated internal storage is freed.
140 + 
        Any dynamically allocated internal storage
 
141 + 
        is freed.
140  
142  
141   
        @par Complexity
143   
        @par Complexity
142   
        Constant.
144   
        Constant.
143  
145  
144   
        @par Exception Safety
146   
        @par Exception Safety
145   
        No-throw guarantee.
147   
        No-throw guarantee.
146   
    */
148   
    */
147   
    ~string() noexcept
149   
    ~string() noexcept
148   
    {
150   
    {
149   
        impl_.destroy(sp_);
151   
        impl_.destroy(sp_);
150   
    }
152   
    }
151  
153  
152   
    //------------------------------------------------------
154   
    //------------------------------------------------------
153   
    //
155   
    //
154   
    // Construction
156   
    // Construction
155   
    //
157   
    //
156   
    //------------------------------------------------------
158   
    //------------------------------------------------------
157  
159  
158 - 
    /** Constructors.
160 + 
    /** Default constructor.
159 -
 
160 - 
        Construct a string.
 
161 -
 
162 - 
        @li **(1)**, **(2)** the string is empty with a non-zero,
 
163 - 
            unspecified capacity.
 
164 -
 
165 - 
        @li **(3)** the string is filled with `count` copies of character `ch`.
 
166 -
 
167 - 
        @li **(4)** the string will contain a copy of the characters of `s`.
 
168 -
 
169 - 
        @li **(5)** the string will contain a copy of the characters of the
 
170 - 
            null-terminated string `s`.
 
171 -
 
172 - 
        @li **(6)** the string will contain a copy of the characters in the
 
173 - 
            range `[s, s + count)`.
 
174 -
 
175 - 
        @li **(7)** the string will contain a copy of the characters in the
 
176 - 
            range `[first, last)`.
 
177 -
 
178 - 
        @li **(8)**, **(9)** the string contains a copy of the characters of
 
179 - 
            `other`.
 
180 -
 
181 - 
        @li **(10)** the string acquires ownership of the contents of `other`.
 
182  
161  
183 - 
        @li **(11)** equivalent to **(10)** if `*sp == *other.storage()`;
162 + 
        The string will have a zero size and a non-zero,
184 - 
            otherwise equivalent to **(9)**.
163 + 
        unspecified capacity, using the [default memory resource].
185  
164  
186 - 
        @li **(12)** the string is acquires ownership of the contents of
165 + 
        @par Complexity
187 - 
            `other` using pilfer semantics. This is more efficient than move
 
188 - 
            construction, when it is known that the moved-from object
 
189 - 
            will be immediately destroyed afterwards.
 
190  
166  
191 - 
        With **(2)**--**(7)**, **(9)**, **(11)** the constructed string uses
167 + 
        Constant.
192 - 
        memory resource of `sp`. With **(8)**, **(10)**, and **(12)** it uses
 
193 - 
        `other`'s memory resource. In either case the string will share the
 
194 - 
        ownership of the memory resource. With **(1)** it uses the
 
195 - 
        \<\<default_memory_resource, default memory resource\>\>.
 
196  
168  
197 - 
        After **(10)** `other` behaves as if newly constructed with its
169 + 
        [default memory resource]: json/allocators/storage_ptr.html#json.allocators.storage_ptr.default_memory_resource
198 - 
        current storage pointer.
170 + 
    */
 
171 + 
    string() = default;
199  
172  
200 - 
        After **(12)** `other` is not in a usable state and may only be
173 + 
    /** Pilfer constructor.
201 - 
        destroyed.
 
202  
174  
203 - 
        @par Constraints
175 + 
        The string is constructed by acquiring ownership
204 - 
        `InputIt` satisfies {req_InputIterator}.
176 + 
        of the contents of `other` using pilfer semantics.
 
177 + 
        This is more efficient than move construction, when
 
178 + 
        it is known that the moved-from object will be
 
179 + 
        immediately destroyed afterwards.
205  
180  
206   
        @par Complexity
181   
        @par Complexity
207 - 
        @li **(1)**, **(2)**, **(10)**, **(12)** constant.
182 + 
        Constant.
208 - 
        @li **(3)** linear in `count`.
 
209 - 
        @li **(4)** linear in `s.size()`.
 
210 - 
        @li **(5)** linear in `std::strlen(s)`.
 
211 - 
        @li **(6)** linear in `count`.
 
212 - 
        @li **(7)** linear in `std::distance(first, last)`.
 
213 - 
        @li **(8)**, **(9)** linear in `other.size()`.
 
214 - 
        @li **(11)** constant if `*sp == *other.storage()`; otherwise linear in
 
215 - 
            `other.size()`.
 
216  
183  
217   
        @par Exception Safety
184   
        @par Exception Safety
218 - 
        @li **(1)**, **(2)**, **(10)**, **(12)** no-throw guarantee.
185 + 
        No-throw guarantee.
219 - 
        @li **(3)**--**(6)**, **(8)**, **(9)**, **(11)**  strong guarantee.
 
220 - 
        @li **(7)** strong guarantee if `InputIt` satisfies
 
221 - 
        {req_ForwardIterator}, basic guarantee otherwise.
 
222 -
 
223 - 
        Calls to `memory_resource::allocate` may throw.
 
224  
186  
225 - 
        @throw boost::system::system_error The constructed string's size would
187 + 
        @param other The value to pilfer. After pilfer
226 - 
               have exceeded @ref max_size().
188 + 
        construction, `other` is not in a usable state
 
189 + 
        and may only be destroyed.
227  
190  
228   
        @see @ref pilfer,
191   
        @see @ref pilfer,
229 - 
            [Valueless Variants Considered Harmful](http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0308r0.html).
192 + 
            <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2016/p0308r0.html">
230 -
193 + 
                Valueless Variants Considered Harmful</a>
231 - 
        @{
 
232   
    */
194   
    */
233 - 
    string() = default;
195 + 
    string(pilfered<string> other) noexcept
 
196 + 
        : sp_(std::move(other.get().sp_))
 
197 + 
        , impl_(other.get().impl_)
 
198 + 
    {
 
199 + 
        ::new(&other.get().impl_) string_impl();
 
200 + 
    }
234  
201  
235 - 
    /** Overload
202 + 
    /** Constructor.
236  
203  
237 - 
        @param sp A pointer to the @ref boost::container::pmr::memory_resource
204 + 
        The string will have zero size and a non-zero,
238 - 
        to use. The container will acquire shared ownership of the memory
205 + 
        unspecified capacity, obtained from the specified
 
206 + 
        memory resource.
 
207 +
 
208 + 
        @par Complexity
 
209 +
 
210 + 
        Constant.
 
211 +
 
212 + 
        @param sp A pointer to the `boost::container::pmr::memory_resource` to
 
213 + 
        use. The container will acquire shared ownership of the memory
239   
        resource.
214   
        resource.
240   
    */
215   
    */
241   
    explicit
216   
    explicit
242   
    string(storage_ptr sp)
217   
    string(storage_ptr sp)
243   
        : sp_(std::move(sp))
218   
        : sp_(std::move(sp))
244   
    {
219   
    {
245   
    }
220   
    }
246  
221  
247 - 
    /** Overload
222 + 
    /** Constructor.
 
223 +
 
224 + 
        Construct the contents with `count` copies of
 
225 + 
        character `ch`.
 
226 +
 
227 + 
        @par Complexity
 
228 +
 
229 + 
        Linear in `count`.
 
230 +
 
231 + 
        @par Exception Safety
 
232 +
 
233 + 
        Strong guarantee.
 
234 + 
        Calls to `memory_resource::allocate` may throw.
248  
235  
249   
        @param count The size of the resulting string.
236   
        @param count The size of the resulting string.
250 - 
        @param ch The value to initialize characters of the string with.
237 +
251 - 
        @param sp
238 + 
        @param ch The value to initialize characters
 
239 + 
        of the string with.
 
240 +
 
241 + 
        @param sp An optional pointer to the
 
242 + 
        `boost::container::pmr::memory_resource` to use. The container will
 
243 + 
        acquire shared ownership of the memory resource. The default argument
 
244 + 
        for this parameter is `{}`.
 
245 +
 
246 + 
        @throw `boost::system::system_error` `count > max_size()`.
252   
    */
247   
    */
253   
    BOOST_JSON_DECL
248   
    BOOST_JSON_DECL
254   
    explicit
249   
    explicit
255   
    string(
250   
    string(
256   
        std::size_t count,
251   
        std::size_t count,
257   
        char ch,
252   
        char ch,
258   
        storage_ptr sp = {});
253   
        storage_ptr sp = {});
259  
254  
260 - 
    /** Overload
255 + 
    /** Constructor.
261  
256  
262 - 
        @param s The string to copy from.
257 + 
        Construct the contents with those of the null
263 - 
        @param sp
258 + 
        terminated string pointed to by `s`. The length
264 - 
    */
259 + 
        of the string is determined by the first null
265 - 
    BOOST_JSON_DECL
260 + 
        character.
266 - 
    string(
 
267 - 
        string_view s,
 
268 - 
        storage_ptr sp = {});
 
269  
261  
270 - 
    /// Overload
262 + 
        @par Complexity
 
263 +
 
264 + 
        Linear in `strlen(s)`.
 
265 +
 
266 + 
        @par Exception Safety
 
267 +
 
268 + 
        Strong guarantee.
 
269 + 
        Calls to `memory_resource::allocate` may throw.
 
270 +
 
271 + 
        @param s A pointer to a character string used to
 
272 + 
        copy from.
 
273 +
 
274 + 
        @param sp An optional pointer to the
 
275 + 
        `boost::container::pmr::memory_resource` to use. The container will
 
276 + 
        acquire shared ownership of the memory resource. The default argument
 
277 + 
        for this parameter is `{}`.
 
278 +
 
279 + 
        @throw `boost::system::system_error` `strlen(s) > max_size()`.
 
280 + 
    */
271   
    BOOST_JSON_DECL
281   
    BOOST_JSON_DECL
272   
    string(
282   
    string(
273   
        char const* s,
283   
        char const* s,
274   
        storage_ptr sp = {});
284   
        storage_ptr sp = {});
275  
285  
276 - 
    /// Overload
286 + 
    /** Constructor.
 
287 +
 
288 + 
        Construct the contents with copies of the
 
289 + 
        characters in the range `{s, s+count)`.
 
290 + 
        This range can contain null characters.
 
291 +
 
292 + 
        @par Complexity
 
293 +
 
294 + 
        Linear in `count`.
 
295 +
 
296 + 
        @par Exception Safety
 
297 +
 
298 + 
        Strong guarantee.
 
299 + 
        Calls to `memory_resource::allocate` may throw.
 
300 +
 
301 + 
        @param count The number of characters to copy.
 
302 +
 
303 + 
        @param s A pointer to a character string used to
 
304 + 
        copy from.
 
305 +
 
306 + 
        @param sp An optional pointer to the
 
307 + 
        `boost::container::pmr::memory_resource` to use. The container will
 
308 + 
        acquire shared ownership of the memory resource. The default argument
 
309 + 
        for this parameter is `{}`.
 
310 +
 
311 + 
        @throw `boost::system::system_error` `count > max_size()`.
 
312 + 
    */
277   
    BOOST_JSON_DECL
313   
    BOOST_JSON_DECL
278   
    explicit
314   
    explicit
279   
    string(
315   
    string(
280   
        char const* s,
316   
        char const* s,
281   
        std::size_t count,
317   
        std::size_t count,
282   
        storage_ptr sp = {});
318   
        storage_ptr sp = {});
283  
319  
284 - 
    /** Overload
320 + 
    /** Constructor.
 
321 +
 
322 + 
        Construct the contents with copies of characters
 
323 + 
        in the range `{first, last)`.
 
324 +
 
325 + 
        @par Complexity
 
326 +
 
327 + 
        Linear in `std::distance(first, last)`.
 
328 +
 
329 + 
        @par Exception Safety
 
330 +
 
331 + 
        Strong guarantee.
 
332 + 
        Calls to `memory_resource::allocate` may throw.
285  
333  
286   
        @tparam InputIt The type of the iterators.
334   
        @tparam InputIt The type of the iterators.
287  
335  
288 - 
        @param first An input iterator pointing to the first character to
336 + 
        @par Constraints
289 - 
               insert, or pointing to the end of the range.
337 +
290 - 
        @param last An input iterator pointing to the end of the range.
338 + 
        `InputIt` satisfies __InputIterator__.
291 - 
        @param sp
339 +
 
340 + 
        @param first An input iterator pointing to the
 
341 + 
        first character to insert, or pointing to the
 
342 + 
        end of the range.
 
343 +
 
344 + 
        @param last An input iterator pointing to the end
 
345 + 
        of the range.
 
346 +
 
347 + 
        @param sp An optional pointer to the
 
348 + 
        `boost::container::pmr::memory_resource` to use. The container will
 
349 + 
        acquire shared ownership of the memory resource. The default argument
 
350 + 
        for this parameter is `{}`.
 
351 +
 
352 + 
        @throw `boost::system::system_error` `std::distance(first, last) > max_size()`.
292   
    */
353   
    */
293   
    template<class InputIt
354   
    template<class InputIt
294   
    #ifndef BOOST_JSON_DOCS
355   
    #ifndef BOOST_JSON_DOCS
295   
        ,class = is_inputit<InputIt>
356   
        ,class = is_inputit<InputIt>
296   
    #endif
357   
    #endif
297   
    >
358   
    >
298   
    explicit
359   
    explicit
299   
    string(
360   
    string(
300   
        InputIt first,
361   
        InputIt first,
301   
        InputIt last,
362   
        InputIt last,
302   
        storage_ptr sp = {});
363   
        storage_ptr sp = {});
303  
364  
304 - 
    /** Overload
365 + 
    /** Copy constructor.
305 - 
        @param other The source string.
366 +
 
367 + 
        Construct the contents with a copy of `other`.
 
368 +
 
369 + 
        @par Complexity
 
370 +
 
371 + 
        Linear in `other.size()`.
 
372 +
 
373 + 
        @par Exception Safety
 
374 +
 
375 + 
        Strong guarantee.
 
376 + 
        Calls to `memory_resource::allocate` may throw.
 
377 +
 
378 + 
        @param other The string to use as a source
 
379 + 
        to copy from.
306   
    */
380   
    */
307   
    BOOST_JSON_DECL
381   
    BOOST_JSON_DECL
308   
    string(string const& other);
382   
    string(string const& other);
309  
383  
310 - 
    /// Overload
384 + 
    /** Constructor.
 
385 +
 
386 + 
        Construct the contents with a copy of `other`.
 
387 +
 
388 + 
        @par Complexity
 
389 +
 
390 + 
        Linear in `other.size()`.
 
391 +
 
392 + 
        @par Exception Safety
 
393 +
 
394 + 
        Strong guarantee.
 
395 + 
        Calls to `memory_resource::allocate` may throw.
 
396 +
 
397 + 
        @param other The string to use as a source
 
398 + 
        to copy from.
 
399 +
 
400 + 
        @param sp An optional pointer to the
 
401 + 
        `boost::container::pmr::memory_resource` to use. The container will
 
402 + 
        acquire shared ownership of the memory resource. The default argument
 
403 + 
        for this parameter is `{}`.
 
404 + 
    */
311   
    BOOST_JSON_DECL
405   
    BOOST_JSON_DECL
312   
    explicit
406   
    explicit
313   
    string(
407   
    string(
314   
        string const& other,
408   
        string const& other,
315   
        storage_ptr sp);
409   
        storage_ptr sp);
316  
410  
317 - 
    /// Overload
411 + 
    /** Move constructor.
 
412 +
 
413 + 
        Constructs the string with the contents of `other` using move
 
414 + 
        semantics. Ownership of the underlying memory is transferred. The
 
415 + 
        container acquires shared ownership of the
 
416 + 
        `boost::container::pmr::memory_resource` used by `other`. After
 
417 + 
        construction, the moved-from string behaves as if newly constructed
 
418 + 
        with its current memory resource.
 
419 +
 
420 + 
        @par Complexity
 
421 +
 
422 + 
        Constant.
 
423 +
 
424 + 
        @param other The string to move
 
425 + 
    */
318   
    string(string&& other) noexcept
426   
    string(string&& other) noexcept
319   
        : sp_(other.sp_)
427   
        : sp_(other.sp_)
320   
        , impl_(other.impl_)
428   
        , impl_(other.impl_)
321   
    {
429   
    {
322   
        ::new(&other.impl_) string_impl();
430   
        ::new(&other.impl_) string_impl();
323   
    }
431   
    }
324  
432  
325 - 
    /// Overload
433 + 
    /** Constructor.
 
434 +
 
435 + 
        Construct the contents with those of `other`
 
436 + 
        using move semantics.
 
437 +
 
438 + 
        @li If `*other.storage() == *sp`, ownership of the underlying memory is
 
439 + 
        transferred in constant time, with no possibility of exceptions. After
 
440 + 
        construction, the moved-from string behaves as if newly constructed
 
441 + 
        with its current `boost::container::pmr::memory_resource`. Otherwise,
 
442 +
 
443 + 
        @li If `*other.storage() != *sp`,
 
444 + 
        a copy of the characters in `other` is made. In
 
445 + 
        this case, the moved-from string is not changed.
 
446 +
 
447 + 
        @par Complexity
 
448 +
 
449 + 
        Constant or linear in `other.size()`.
 
450 +
 
451 + 
        @par Exception Safety
 
452 +
 
453 + 
        Strong guarantee.
 
454 + 
        Calls to `memory_resource::allocate` may throw.
 
455 +
 
456 + 
        @param other The string to assign from.
 
457 +
 
458 + 
        @param sp An optional pointer to the
 
459 + 
        `boost::container::pmr::memory_resource` to use. The container will
 
460 + 
        acquire shared ownership of the memory resource. The default argument
 
461 + 
        for this parameter is `{}`.
 
462 + 
    */
326   
    BOOST_JSON_DECL
463   
    BOOST_JSON_DECL
327   
    explicit
464   
    explicit
328   
    string(
465   
    string(
329   
        string&& other,
466   
        string&& other,
330   
        storage_ptr sp);
467   
        storage_ptr sp);
331  
468  
332 - 
    /// Overload
469 + 
    /** Constructor.
333 - 
    string(pilfered<string> other) noexcept
470 +
334 - 
        : sp_(std::move(other.get().sp_))
471 + 
        Construct the contents with those of a
335 - 
        , impl_(other.get().impl_)
472 + 
        string view. This view can contain
336 - 
    {
473 + 
        null characters.
337 - 
        ::new(&other.get().impl_) string_impl();
474 +
338 - 
    }
475 + 
        @par Complexity
339 - 
    /// @}
476 +
 
477 + 
        Linear in `s.size()`.
 
478 +
 
479 + 
        @par Exception Safety
 
480 +
 
481 + 
        Strong guarantee.
 
482 + 
        Calls to `memory_resource::allocate` may throw.
 
483 +
 
484 + 
        @param s The string view to copy from.
 
485 +
 
486 + 
        @param sp An optional pointer to the
 
487 + 
        `boost::container::pmr::memory_resource` to use. The container will
 
488 + 
        acquire shared ownership of the memory resource. The default argument
 
489 + 
        for this parameter is `{}`.
 
490 +
 
491 + 
        @throw `boost::system::system_error` `std::distance(first, last) > max_size()`.
 
492 + 
    */
 
493 + 
    BOOST_JSON_DECL
 
494 + 
    string(
 
495 + 
        string_view s,
 
496 + 
        storage_ptr sp = {});
340  
497  
341   
    //------------------------------------------------------
498   
    //------------------------------------------------------
342   
    //
499   
    //
343   
    // Assignment
500   
    // Assignment
344   
    //
501   
    //
345   
    //------------------------------------------------------
502   
    //------------------------------------------------------
346  
503  
347 - 
    /** Assignment operators.
504 + 
    /** Copy assignment.
348 -
 
349 - 
        @li **(1)**, **(4)** the contents are replaced with an element-wise
 
350 - 
            copy of `other`.
 
351 - 
        @li **(2)** takes ownership of `other`'s element storage if
 
352 - 
            `*storage() == *other.storage()`; otherwise equivalent to **(1)**.
 
353 - 
        @li **(3)** the contents are replaced with an element-wise copy of
 
354 - 
            null-terminated string `s`.
 
355  
505  
356 - 
        After **(2)**, the moved-from array behaves as if newly constructed
506 + 
        Replace the contents with a copy of `other`.
357 - 
        with its current storage pointer.
 
358  
507  
359   
        @par Complexity
508   
        @par Complexity
360 - 
        @li **(1)**, **(4)** linear in `other.size()`.
509 +
361 - 
        @li **(2)** constant if `*storage() == *other.storage()`; otherwise
510 + 
        Linear in `other.size()`.
362 - 
            linear in `other.size()`.
 
363 - 
        @li **(3)** linear in `std::strlen(s)`.
 
364  
511  
365 - 
        {sp} **(2)** provides strong guarantee if
 
366 - 
        `*storage() != *other.storage()` and no-throw guarantee otherwise.
 
367 - 
        Other overloads provide strong guarantee.
 
368 - 
        Calls to `memory_resource::allocate` may throw.
 
369   
        @par Exception Safety
512   
        @par Exception Safety
370  
513  
371 - 
        @param other The string to copy.
514 + 
        Strong guarantee.
 
515 + 
        Calls to `memory_resource::allocate` may throw.
372  
516  
373   
        @return `*this`
517   
        @return `*this`
374  
518  
375 - 
        @{
519 + 
        @param other The string to use as a source
 
520 + 
        to copy from.
376   
    */
521   
    */
377   
    BOOST_JSON_DECL
522   
    BOOST_JSON_DECL
378   
    string&
523   
    string&
379   
    operator=(string const& other);
524   
    operator=(string const& other);
380  
525  
 
526 + 
    /** Move assignment.
 
527 +
 
528 + 
        Replace the contents with those of `other`
 
529 + 
        using move semantics.
 
530 +
 
531 + 
        @li If `&other == this`, do nothing. Otherwise,
 
532 +
 
533 + 
        @li If `*other.storage() == *this->storage()`, ownership of the
 
534 + 
        underlying memory is transferred in constant time, with no possibility
 
535 + 
        of exceptions. After construction, the moved-from string behaves as if
 
536 + 
        newly constructed with its current
 
537 + 
        `boost::container::pmr::memory_resource`. Otherwise,
 
538 +
 
539 + 
        @li a copy of the characters in `other` is made. In
 
540 + 
        this case, the moved-from container is not changed.
 
541 +
 
542 + 
        @par Complexity
 
543 +
 
544 + 
        Constant or linear in `other.size()`.
 
545 +
 
546 + 
        @par Exception Safety
 
547 +
 
548 + 
        Strong guarantee.
 
549 + 
        Calls to `memory_resource::allocate` may throw.
 
550 +
 
551 + 
        @return `*this`
 
552 +
 
553 + 
        @param other The string to use as a source
 
554 + 
        to move from.
 
555 + 
    */
381   
    BOOST_JSON_DECL
556   
    BOOST_JSON_DECL
382   
    string&
557   
    string&
383   
    operator=(string&& other);
558   
    operator=(string&& other);
384  
559  
385 - 
    /** Overload
560 + 
    /** Assign a value to the string.
 
561 +
 
562 + 
        Replaces the contents with those of the null
 
563 + 
        terminated string pointed to by `s`. The length
 
564 + 
        of the string is determined by the first null
 
565 + 
        character.
 
566 +
 
567 + 
        @par Complexity
 
568 +
 
569 + 
        Linear in `std::strlen(s)`.
 
570 +
 
571 + 
        @par Exception Safety
 
572 +
 
573 + 
        Strong guarantee.
 
574 + 
        Calls to `memory_resource::allocate` may throw.
 
575 +
 
576 + 
        @return `*this`
386  
577  
387   
        @param s The null-terminated character string.
578   
        @param s The null-terminated character string.
388  
579  
389 - 
        @throw boost::system::system_error `std::strlen(s) >` @ref max_size().
580 + 
        @throw `boost::system::system_error` `std::strlen(s) > max_size()`.
390   
    */
581   
    */
391   
    BOOST_JSON_DECL
582   
    BOOST_JSON_DECL
392   
    string&
583   
    string&
393   
    operator=(char const* s);
584   
    operator=(char const* s);
394  
585  
395 - 
    /** Overload
586 + 
    /** Assign a value to the string.
396  
587  
397 - 
        @throw `boost::system::system_error` `other.size() >` @ref max_size().
588 + 
        Replaces the contents with those of a
 
589 + 
        string view. This view can contain
 
590 + 
        null characters.
 
591 +
 
592 + 
        @par Complexity
 
593 +
 
594 + 
        Linear in `s.size()`.
 
595 +
 
596 + 
        @par Exception Safety
 
597 +
 
598 + 
        Strong guarantee.
 
599 + 
        Calls to `memory_resource::allocate` may throw.
 
600 +
 
601 + 
        @return `*this`
 
602 +
 
603 + 
        @param s The string view to copy from.
 
604 +
 
605 + 
        @throw `boost::system::system_error` `s.size() > max_size()`.
398   
    */
606   
    */
399   
    BOOST_JSON_DECL
607   
    BOOST_JSON_DECL
400   
    string&
608   
    string&
401 - 
    operator=(string_view other);
609 + 
    operator=(string_view s);
402 - 
    /// @}
610 +
 
611 + 
    //------------------------------------------------------
403  
612  
404   
    /** Assign characters to a string.
613   
    /** Assign characters to a string.
405  
614  
406 - 
        @li **(1)** replaces the contents with `count` copies of character
615 + 
        Replace the contents with `count` copies of
407 - 
        `ch`.
616 + 
        character `ch`.
408  
617  
409 - 
        @li **(2)** replaces the contents with copies of the characters in the
618 + 
        @par Complexity
410 - 
        range `[s, s + count)`. This range can contain null characters.
 
411  
619  
412 - 
        @li **(3)** replaces the contents with those of the null terminated
620 + 
        Linear in `count`.
413 - 
        string `s`. The length of the string is determined by the first null
 
414 - 
        character.
 
415  
621  
416 - 
        @li **(4)** replaces the contents with copies of characters in the
622 + 
        @par Exception Safety
417 - 
        range `[first, last)`.
 
418  
623  
419 - 
        @li **(5)** Replaces the contents with those of string view `s`. This
624 + 
        Strong guarantee.
420 - 
        view can contain null characters.
625 + 
        Calls to `memory_resource::allocate` may throw.
421  
626  
422 - 
        @li **(6)** replaces the contents with a copy of the characters of
627 + 
        @return `*this`
423 - 
        `other`.
 
424  
628  
425 - 
        @li **(7)** if `*storage() == *other.storage()` takes ownership of the
629 + 
        @param count The size of the resulting string.
426 - 
        element storage of `other`; otherwise equivalent to **(6)**.
 
427  
630  
428 - 
        Self-assignment using **(7)** does nothing.
631 + 
        @param ch The value to initialize characters
 
632 + 
        of the string with.
429  
633  
430 - 
        After **(7)** `other` is left in valid but unspecified state.
634 + 
        @throw `boost::system::system_error` `count > max_size()`.
 
635 + 
    */
 
636 + 
    BOOST_JSON_DECL
 
637 + 
    string&
 
638 + 
    assign(
 
639 + 
        std::size_t count,
 
640 + 
        char ch);
431  
641  
432 - 
        @par Constraints
642 + 
    /** Assign characters to a string.
433 - 
        `InputIt` satisfies {req_InputIterator}.
643 +
 
644 + 
        Replace the contents with a copy of `other`.
434  
645  
435   
        @par Complexity
646   
        @par Complexity
436 - 
        @li **(1)**, **(2)** linear in `count`.
647 +
437 - 
        @li **(3)** linear in `std::strlen(s)`.
648 + 
        Linear in `other.size()`.
438 - 
        @li **(4)** linear in `std::distance(first, last)`.
 
439 - 
        @li **(5)** linear in `s.size()`.
 
440 - 
        @li **(6)** linear in `other.size()`.
 
441 - 
        @li **(7)** constant if `*storage() == *other.storage()`, otherwise
 
442 - 
            linear in `other.size()`.
 
443  
649  
444 - 
        {sp} **(7)** provides strong guarantee if
 
445 - 
        `*storage() != *other.storage()` and no-throw guarantee otherwise.
 
446 - 
        Other overloads provide strong guarantee. Calls to
 
447 - 
        `memory_resource::allocate` may throw.
 
448   
        @par Exception Safety
650   
        @par Exception Safety
449  
651  
450 - 
        @return `*this`.
652 + 
        Strong guarantee.
 
653 + 
        Calls to `memory_resource::allocate` may throw.
451  
654  
452 - 
        @param count The number of the characters to use.
655 + 
        @return `*this`
453  
656  
454 - 
        @param ch The character to fill the string with.
657 + 
        @param other The string to use as a source
 
658 + 
        to copy from.
 
659 + 
    */
 
660 + 
    BOOST_JSON_DECL
 
661 + 
    string&
 
662 + 
    assign(
 
663 + 
        string const& other);
455  
664  
456 - 
        @throw boost::system::system_error The size of the string after the
665 + 
    /** Assign characters to a string.
457 - 
        operation would exceed @ref max_size().
 
458  
666  
459 - 
        @{
667 + 
        Replace the contents with those of `other`
 
668 + 
        using move semantics.
 
669 +
 
670 + 
        @li If `&other == this`, do nothing. Otherwise,
 
671 +
 
672 + 
        @li If `*other.storage() == *this->storage()`, ownership of the
 
673 + 
        underlying memory is transferred in constant time, with no possibility
 
674 + 
        of exceptions. After construction, the moved-from string behaves as if
 
675 + 
        newly constructed with its current
 
676 + 
        `boost::container::pmr::memory_resource`, otherwise
 
677 +
 
678 + 
        @li If `*other.storage() != *this->storage()`,
 
679 + 
        a copy of the characters in `other` is made.
 
680 + 
        In this case, the moved-from container
 
681 + 
        is not changed.
 
682 +
 
683 + 
        @par Complexity
 
684 +
 
685 + 
        Constant or linear in `other.size()`.
 
686 +
 
687 + 
        @par Exception Safety
 
688 +
 
689 + 
        Strong guarantee.
 
690 + 
        Calls to `memory_resource::allocate` may throw.
 
691 +
 
692 + 
        @return `*this`
 
693 +
 
694 + 
        @param other The string to assign from.
460   
    */
695   
    */
461   
    BOOST_JSON_DECL
696   
    BOOST_JSON_DECL
462   
    string&
697   
    string&
463 - 
    assign(
698 + 
    assign(string&& other);
464 - 
        std::size_t count,
 
465 - 
        char ch);
 
466  
699  
467 - 
    /** Overload
700 + 
    /** Assign characters to a string.
468 - 
        @param s A pointer to a character string used to copy from.
701 +
469 - 
        @param count
702 + 
        Replaces the contents with copies of the
 
703 + 
        characters in the range `{s, s+count)`. This
 
704 + 
        range can contain null characters.
 
705 +
 
706 + 
        @par Complexity
 
707 +
 
708 + 
        Linear in `count`.
 
709 +
 
710 + 
        @par Exception Safety
 
711 +
 
712 + 
        Strong guarantee.
 
713 + 
        Calls to `memory_resource::allocate` may throw.
 
714 +
 
715 + 
        @return `*this`
 
716 +
 
717 + 
        @param count The number of characters to copy.
 
718 +
 
719 + 
        @param s A pointer to a character string used to
 
720 + 
        copy from.
 
721 +
 
722 + 
        @throw `boost::system::system_error` `count > max_size()`.
470   
    */
723   
    */
471   
    BOOST_JSON_DECL
724   
    BOOST_JSON_DECL
472   
    string&
725   
    string&
473   
    assign(
726   
    assign(
474   
        char const* s,
727   
        char const* s,
475   
        std::size_t count);
728   
        std::size_t count);
476  
729  
477 - 
    /** Overload
730 + 
    /** Assign characters to a string.
478 - 
        @param s
731 +
 
732 + 
        Replaces the contents with those of the null
 
733 + 
        terminated string pointed to by `s`. The length
 
734 + 
        of the string is determined by the first null
 
735 + 
        character.
 
736 +
 
737 + 
        @par Complexity
 
738 +
 
739 + 
        Linear in `strlen(s)`.
 
740 +
 
741 + 
        @par Exception Safety
 
742 +
 
743 + 
        Strong guarantee.
 
744 +
 
745 + 
        @note
 
746 +
 
747 + 
        Calls to `memory_resource::allocate` may throw.
 
748 +
 
749 + 
        @return `*this`
 
750 +
 
751 + 
        @param s A pointer to a character string used to
 
752 + 
        copy from.
 
753 +
 
754 + 
        @throw `boost::system::system_error` `strlen(s) > max_size()`.
479   
    */
755   
    */
480   
    BOOST_JSON_DECL
756   
    BOOST_JSON_DECL
481   
    string&
757   
    string&
482   
    assign(
758   
    assign(
483   
        char const* s);
759   
        char const* s);
484  
760  
485 - 
    /** Overload
761 + 
    /** Assign characters to a string.
 
762 +
 
763 + 
        Replaces the contents with copies of characters
 
764 + 
        in the range `{first, last)`.
 
765 +
 
766 + 
        @par Complexity
 
767 +
 
768 + 
        Linear in `std::distance(first, last)`.
 
769 +
 
770 + 
        @par Exception Safety
 
771 +
 
772 + 
        Strong guarantee.
 
773 + 
        Calls to `memory_resource::allocate` may throw.
486  
774  
487   
        @tparam InputIt The type of the iterators.
775   
        @tparam InputIt The type of the iterators.
488  
776  
489 - 
        @param first An input iterator pointing to the first character to
777 + 
        @par Constraints
490 - 
        insert, or pointing to the end of the range.
778 +
491 - 
        @param last An input iterator pointing to the end of the range.
779 + 
        `InputIt` satisfies __InputIterator__.
 
780 +
 
781 + 
        @return `*this`
 
782 +
 
783 + 
        @param first An input iterator pointing to the
 
784 + 
        first character to insert, or pointing to the
 
785 + 
        end of the range.
 
786 +
 
787 + 
        @param last An input iterator pointing to the end
 
788 + 
        of the range.
 
789 +
 
790 + 
        @throw `boost::system::system_error` `std::distance(first, last) > max_size()`.
492   
    */
791   
    */
493   
    template<class InputIt
792   
    template<class InputIt
494   
    #ifndef BOOST_JSON_DOCS
793   
    #ifndef BOOST_JSON_DOCS
495   
        ,class = is_inputit<InputIt>
794   
        ,class = is_inputit<InputIt>
496   
    #endif
795   
    #endif
497   
    >
796   
    >
498   
    string&
797   
    string&
499   
    assign(
798   
    assign(
500   
        InputIt first,
799   
        InputIt first,
501   
        InputIt last);
800   
        InputIt last);
502  
801  
503 - 
    /** Overload
802 + 
    /** Assign characters to a string.
 
803 +
 
804 + 
        Replaces the contents with those of a
 
805 + 
        string view. This view can contain
 
806 + 
        null characters.
 
807 +
 
808 + 
        @par Complexity
 
809 +
 
810 + 
        Linear in `s.size()`.
 
811 +
 
812 + 
        @par Exception Safety
 
813 +
 
814 + 
        Strong guarantee.
 
815 + 
        Calls to `memory_resource::allocate` may throw.
 
816 +
 
817 + 
        @return `*this`
 
818 +
504   
        @param s The string view to copy from.
819   
        @param s The string view to copy from.
 
820 +
 
821 + 
        @throw `boost::system::system_error` `s.size() > max_size()`.
505   
    */
822   
    */
506   
    string&
823   
    string&
507   
    assign(string_view s)
824   
    assign(string_view s)
508   
    {
825   
    {
509   
        return assign(s.data(), s.size());
826   
        return assign(s.data(), s.size());
510   
    }
827   
    }
511  
828  
512 - 
    /** Overload
829 + 
    //------------------------------------------------------
513 - 
        @param other Another string.
 
514 - 
    */
 
515 - 
    BOOST_JSON_DECL
 
516 - 
    string&
 
517 - 
    assign(
 
518 - 
        string const& other);
 
519 -
 
520 - 
    /** Overload
 
521 - 
        @param other
 
522 - 
    */
 
523 - 
    BOOST_JSON_DECL
 
524 - 
    string&
 
525 - 
    assign(string&& other);
 
526 - 
    /// @}
 
527  
830  
528   
    /** Return the associated memory resource.
831   
    /** Return the associated memory resource.
529  
832  
530 - 
        This function returns a smart pointer to the
833 + 
        This returns the `boost::container::pmr::memory_resource` used by
531 - 
        @ref boost::container::pmr::memory_resource used by the container.
834 + 
        the container.
532  
835  
533   
        @par Complexity
836   
        @par Complexity
 
837 +
534   
        Constant.
838   
        Constant.
535  
839  
536   
        @par Exception Safety
840   
        @par Exception Safety
 
841 +
537   
        No-throw guarantee.
842   
        No-throw guarantee.
538   
    */
843   
    */
539   
    storage_ptr const&
844   
    storage_ptr const&
540   
    storage() const noexcept
845   
    storage() const noexcept
541   
    {
846   
    {
542   
        return sp_;
847   
        return sp_;
543   
    }
848   
    }
544  
849  
545   
    /** Return the associated allocator.
850   
    /** Return the associated allocator.
546  
851  
547   
        This function returns an instance of @ref allocator_type constructed
852   
        This function returns an instance of @ref allocator_type constructed
548 - 
        from the associated @ref boost::container::pmr::memory_resource.
853 + 
        from the associated `boost::container::pmr::memory_resource`.
549  
854  
550   
        @par Complexity
855   
        @par Complexity
 
856 +
551   
        Constant.
857   
        Constant.
552  
858  
553   
        @par Exception Safety
859   
        @par Exception Safety
 
860 +
554   
        No-throw guarantee.
861   
        No-throw guarantee.
555   
    */
862   
    */
556   
    allocator_type
863   
    allocator_type
557   
    get_allocator() const noexcept
864   
    get_allocator() const noexcept
558   
    {
865   
    {
559   
        return sp_.get();
866   
        return sp_.get();
560   
    }
867   
    }
561  
868  
562   
    //------------------------------------------------------
869   
    //------------------------------------------------------
563   
    //
870   
    //
564   
    // Element Access
871   
    // Element Access
565   
    //
872   
    //
566   
    //------------------------------------------------------
873   
    //------------------------------------------------------
567  
874  
568   
    /** Return a character with bounds checking.
875   
    /** Return a character with bounds checking.
569  
876  
570 - 
        Returns @ref boost::system::result containing a reference to the
877 + 
        Returns `boost::system::result` containing a reference to the character
571 - 
        character specified at location `pos`, if `pos` is within the range of
878 + 
        specified at location `pos`, if `pos` is within the range of the
572 - 
        the string. Otherwise the result contains an `error_code`.
879 + 
        string. Otherwise the result contains an `error_code`.
573  
880  
574   
        @par Exception Safety
881   
        @par Exception Safety
575   
        Strong guarantee.
882   
        Strong guarantee.
576  
883  
577   
        @param pos A zero-based index to access.
884   
        @param pos A zero-based index to access.
578  
885  
579   
        @par Complexity
886   
        @par Complexity
580 -
 
581 - 
        @{
 
582   
        Constant.
887   
        Constant.
583   
    */
888   
    */
 
889 + 
    /** @{ */
584   
    BOOST_JSON_DECL
890   
    BOOST_JSON_DECL
585   
    system::result<char&>
891   
    system::result<char&>
586   
    try_at(std::size_t pos) noexcept;
892   
    try_at(std::size_t pos) noexcept;
587  
893  
588   
    BOOST_JSON_DECL
894   
    BOOST_JSON_DECL
589   
    system::result<char const&>
895   
    system::result<char const&>
590   
    try_at(std::size_t pos) const noexcept;
896   
    try_at(std::size_t pos) const noexcept;
591 - 
    /// @}
897 + 
    /** @} */
592  
898  
593   
    /** Return a character with bounds checking.
899   
    /** Return a character with bounds checking.
594  
900  
595 - 
        Returns a reference to the character specified at location `pos`.
901 + 
        Returns a reference to the character specified at
 
902 + 
        location `pos`.
596  
903  
597   
        @par Complexity
904   
        @par Complexity
 
905 +
598   
        Constant.
906   
        Constant.
599  
907  
600   
        @par Exception Safety
908   
        @par Exception Safety
 
909 +
601   
        Strong guarantee.
910   
        Strong guarantee.
602  
911  
603 - 
        @param loc `source_location` to use in thrown exception; the source
 
604 - 
               location of the call site by default.
 
605   
        @param pos A zero-based index to access.
912   
        @param pos A zero-based index to access.
606  
913  
607 - 
        @throw boost::system::system_error `pos >=` @ref size().
914 + 
        @param loc `source_location` to use in thrown exception; the source
 
915 + 
            location of the call site by default.
608  
916  
609 - 
        @{
917 + 
        @throw `boost::system::system_error` `pos >= size()`.
610   
    */
918   
    */
 
919 + 
    /** @{ */
611   
    inline
920   
    inline
612   
    char&
921   
    char&
613   
    at(
922   
    at(
614   
        std::size_t pos,
923   
        std::size_t pos,
615   
        source_location const& loc = BOOST_CURRENT_LOCATION);
924   
        source_location const& loc = BOOST_CURRENT_LOCATION);
616  
925  
617   
    BOOST_JSON_DECL
926   
    BOOST_JSON_DECL
618   
    char const&
927   
    char const&
619   
    at(
928   
    at(
620   
        std::size_t pos,
929   
        std::size_t pos,
621   
        source_location const& loc = BOOST_CURRENT_LOCATION) const;
930   
        source_location const& loc = BOOST_CURRENT_LOCATION) const;
622 - 
    /// @}
931 + 
    /** @} */
623  
932  
624   
    /** Return a character without bounds checking.
933   
    /** Return a character without bounds checking.
625  
934  
626 - 
        Returns a reference to the character specified at location `pos`.
935 + 
        Returns a reference to the character specified at
 
936 + 
        location `pos`.
627  
937  
628   
        @par Complexity
938   
        @par Complexity
 
939 +
629   
        Constant.
940   
        Constant.
630  
941  
631 - 
        @pre
942 + 
        @par Precondition
 
943 +
632   
        @code
944   
        @code
633 - 
        pos < size()
945 + 
        pos >= size
634   
        @endcode
946   
        @endcode
635  
947  
636 -
 
637 - 
        @{
 
638   
        @param pos A zero-based index to access.
948   
        @param pos A zero-based index to access.
639   
    */
949   
    */
640   
    char&
950   
    char&
641   
    operator[](std::size_t pos)
951   
    operator[](std::size_t pos)
642   
    {
952   
    {
643   
        return impl_.data()[pos];
953   
        return impl_.data()[pos];
644   
    }
954   
    }
645  
955  
 
956 + 
   /**  Return a character without bounds checking.
 
957 +
 
958 + 
        Returns a reference to the character specified at
 
959 + 
        location `pos`.
 
960 +
 
961 + 
        @par Complexity
 
962 +
 
963 + 
        Constant.
 
964 +
 
965 + 
        @par Precondition
 
966 +
 
967 + 
        @code
 
968 + 
        pos >= size
 
969 + 
        @endcode
 
970 +
 
971 + 
        @param pos A zero-based index to access.
 
972 + 
    */
646   
    const char&
973   
    const char&
647   
    operator[](std::size_t pos) const
974   
    operator[](std::size_t pos) const
648   
    {
975   
    {
649   
        return impl_.data()[pos];
976   
        return impl_.data()[pos];
650 - 
    /// @}
 
651   
    }
977   
    }
652  
978  
653   
    /** Return the first character.
979   
    /** Return the first character.
654  
980  
655   
        Returns a reference to the first character.
981   
        Returns a reference to the first character.
656 - 
        @pre
 
657 - 
        @code
 
658 - 
        ! empty()
 
659 - 
        @endcode
 
660 -
 
661  
982  
662   
        @par Complexity
983   
        @par Complexity
 
984 +
663   
        Constant.
985   
        Constant.
664  
986  
665 - 
        @par Exception Safety
987 + 
        @par Precondition
666 - 
        No-throw guarantee.
 
667  
988  
668 - 
        @{
989 + 
        @code
 
990 + 
        not empty()
 
991 + 
        @endcode
669   
    */
992   
    */
670   
    char&
993   
    char&
671   
    front()
994   
    front()
672   
    {
995   
    {
673   
        return impl_.data()[0];
996   
        return impl_.data()[0];
674   
    }
997   
    }
675  
998  
 
999 + 
    /** Return the first character.
 
1000 +
 
1001 + 
        Returns a reference to the first character.
 
1002 +
 
1003 + 
        @par Complexity
 
1004 +
 
1005 + 
        Constant.
 
1006 +
 
1007 + 
        @par Precondition
 
1008 +
 
1009 + 
        @code
 
1010 + 
        not empty()
 
1011 + 
        @endcode
 
1012 + 
    */
676   
    char const&
1013   
    char const&
677   
    front() const
1014   
    front() const
678   
    {
1015   
    {
679   
        return impl_.data()[0];
1016   
        return impl_.data()[0];
680 - 
    /// @}
 
681   
    }
1017   
    }
682  
1018  
683   
    /** Return the last character.
1019   
    /** Return the last character.
684  
1020  
685   
        Returns a reference to the last character.
1021   
        Returns a reference to the last character.
686 - 
        @pre
 
687 - 
        @code
 
688 - 
        ! empty()
 
689 - 
        @endcode
 
690 -
 
691  
1022  
692   
        @par Complexity
1023   
        @par Complexity
 
1024 +
693   
        Constant.
1025   
        Constant.
694  
1026  
695 - 
        @{
1027 + 
        @par Precondition
 
1028 +
 
1029 + 
        @code
 
1030 + 
        not empty()
 
1031 + 
        @endcode
696   
    */
1032   
    */
697   
    char&
1033   
    char&
698   
    back()
1034   
    back()
699   
    {
1035   
    {
700   
        return impl_.data()[impl_.size() - 1];
1036   
        return impl_.data()[impl_.size() - 1];
701   
    }
1037   
    }
702  
1038  
 
1039 + 
    /** Return the last character.
 
1040 +
 
1041 + 
        Returns a reference to the last character.
 
1042 +
 
1043 + 
        @par Complexity
 
1044 +
 
1045 + 
        Constant.
 
1046 +
 
1047 + 
        @par Precondition
 
1048 +
 
1049 + 
        @code
 
1050 + 
        not empty()
 
1051 + 
        @endcode
 
1052 + 
    */
703   
    char const&
1053   
    char const&
704   
    back() const
1054   
    back() const
705   
    {
1055   
    {
706   
        return impl_.data()[impl_.size() - 1];
1056   
        return impl_.data()[impl_.size() - 1];
707 - 
    /// @}
 
708   
    }
1057   
    }
709  
1058  
710   
    /** Return the underlying character array directly.
1059   
    /** Return the underlying character array directly.
711  
1060  
712 - 
        Returns a pointer to the underlying array serving as storage. The value
1061 + 
        Returns a pointer to the underlying array
713 - 
        returned is such that the range `[data(), data() + size())` is always
1062 + 
        serving as storage. The value returned is such that
714 - 
        a valid range, even if the container is empty.
1063 + 
        the range `{data(), data()+size())` is always a
715 -
1064 + 
        valid range, even if the container is empty.
716 - 
        @note The value returned from this function is never equal to
 
717 - 
        `nullptr`.
 
718  
1065  
719 - 
        Constant.
 
720   
        @par Complexity
1066   
        @par Complexity
721  
1067  
722 - 
        @par Exception Safety
1068 + 
        Constant.
723 - 
        No-throw guarantee.
 
724  
1069  
725 - 
        @{
1070 + 
        @note The value returned from
 
1071 + 
        this function is never equal to `nullptr`.
726   
    */
1072   
    */
727   
    char*
1073   
    char*
728   
    data() noexcept
1074   
    data() noexcept
729   
    {
1075   
    {
730   
        return impl_.data();
1076   
        return impl_.data();
731   
    }
1077   
    }
732  
1078  
 
1079 + 
    /** Return the underlying character array directly.
 
1080 +
 
1081 + 
        Returns a pointer to the underlying array
 
1082 + 
        serving as storage.
 
1083 +
 
1084 + 
        @note The value returned is such that
 
1085 + 
        the range `{data(), data() + size())` is always a
 
1086 + 
        valid range, even if the container is empty.
 
1087 + 
        The value returned from
 
1088 + 
        this function is never equal to `nullptr`.
 
1089 +
 
1090 + 
        @par Complexity
 
1091 +
 
1092 + 
        Constant.
 
1093 + 
    */
733   
    char const*
1094   
    char const*
734   
    data() const noexcept
1095   
    data() const noexcept
735   
    {
1096   
    {
736   
        return impl_.data();
1097   
        return impl_.data();
737 - 
    /// @@}
 
738   
    }
1098   
    }
739  
1099  
740   
    /** Return the underlying character array directly.
1100   
    /** Return the underlying character array directly.
741  
1101  
742 - 
        Returns a pointer to the underlying array serving as storage. The value
1102 + 
        Returns a pointer to the underlying array
743 - 
        returned is such that the range `[c_str(), c_str() + size())` is always
1103 + 
        serving as storage. The value returned is such that
744 - 
        a valid range, even if the container is empty.
1104 + 
        the range `{c_str(), c_str() + size()}` is always a
745 -
1105 + 
        valid range, even if the container is empty.
746 - 
        @note The value returned from this function is never equal to
 
747 - 
        `nullptr`.
 
748  
1106  
749   
        @par Complexity
1107   
        @par Complexity
 
1108 +
750   
        Constant.
1109   
        Constant.
 
1110 +
 
1111 + 
        @note The value returned from
 
1112 + 
        this function is never equal to `nullptr`.
751   
    */
1113   
    */
752   
    char const*
1114   
    char const*
753   
    c_str() const noexcept
1115   
    c_str() const noexcept
754   
    {
1116   
    {
755   
        return impl_.data();
1117   
        return impl_.data();
756   
    }
1118   
    }
757  
1119  
758   
    /** Convert to a @ref string_view referring to the string.
1120   
    /** Convert to a @ref string_view referring to the string.
759  
1121  
760   
        Returns a string view to the
1122   
        Returns a string view to the
761   
        underlying character string. The size of the view
1123   
        underlying character string. The size of the view
762   
        does not include the null terminator.
1124   
        does not include the null terminator.
763  
1125  
764   
        @par Complexity
1126   
        @par Complexity
765  
1127  
766   
        Constant.
1128   
        Constant.
767   
    */
1129   
    */
768   
    operator string_view() const noexcept
1130   
    operator string_view() const noexcept
769   
    {
1131   
    {
770   
        return {data(), size()};
1132   
        return {data(), size()};
771   
    }
1133   
    }
772  
1134  
773   
#if ! defined(BOOST_NO_CXX17_HDR_STRING_VIEW)
1135   
#if ! defined(BOOST_NO_CXX17_HDR_STRING_VIEW)
774 - 
    /** Convert to @ref std::string_view referring to the string.
1136 + 
    /** Convert to a `std::string_view` referring to the string.
775  
1137  
776   
        Returns a string view to the underlying character string. The size of
1138   
        Returns a string view to the underlying character string. The size of
777   
        the view does not include the null terminator.
1139   
        the view does not include the null terminator.
778  
1140  
779 - 
        This overload is not defined when `BOOST_NO_CXX17_HDR_STRING_VIEW` is
1141 + 
        This overload is not defined when `BOOST_NO_CXX17_HDR_STRING_VIEW`
780 - 
        defined.
1142 + 
        is defined.
781  
1143  
782   
        @par Complexity
1144   
        @par Complexity
783  
1145  
784   
        Constant.
1146   
        Constant.
785   
    */
1147   
    */
786   
    operator std::string_view() const noexcept
1148   
    operator std::string_view() const noexcept
787   
    {
1149   
    {
788   
        return {data(), size()};
1150   
        return {data(), size()};
789   
    }
1151   
    }
790   
#endif
1152   
#endif
791  
1153  
792   
    //------------------------------------------------------
1154   
    //------------------------------------------------------
793   
    //
1155   
    //
794   
    // Iterators
1156   
    // Iterators
795   
    //
1157   
    //
796   
    //------------------------------------------------------
1158   
    //------------------------------------------------------
797  
1159  
798   
    /** Return an iterator to the beginning.
1160   
    /** Return an iterator to the beginning.
799  
1161  
800   
        If the container is empty, @ref end() is returned.
1162   
        If the container is empty, @ref end() is returned.
801  
1163  
802   
        @par Complexity
1164   
        @par Complexity
803   
        Constant.
1165   
        Constant.
804  
1166  
805   
        @par Exception Safety
1167   
        @par Exception Safety
806 -
 
807 - 
        @{
 
808   
        No-throw guarantee.
1168   
        No-throw guarantee.
809   
    */
1169   
    */
810   
    iterator
1170   
    iterator
811   
    begin() noexcept
1171   
    begin() noexcept
812   
    {
1172   
    {
813   
        return impl_.data();
1173   
        return impl_.data();
814   
    }
1174   
    }
815  
1175  
 
1176 + 
    /** Return an iterator to the beginning.
 
1177 +
 
1178 + 
        If the container is empty, @ref end() is returned.
 
1179 +
 
1180 + 
        @par Complexity
 
1181 + 
        Constant.
 
1182 +
 
1183 + 
        @par Exception Safety
 
1184 + 
        No-throw guarantee.
 
1185 + 
    */
816   
    const_iterator
1186   
    const_iterator
817   
    begin() const noexcept
1187   
    begin() const noexcept
818   
    {
1188   
    {
819   
        return impl_.data();
1189   
        return impl_.data();
820 - 
    /// @}
 
821   
    }
1190   
    }
822  
1191  
823 - 
    /** Return a const iterator to the first element.
1192 + 
    /** Return an iterator to the beginning.
824  
1193  
825   
        If the container is empty, @ref cend() is returned.
1194   
        If the container is empty, @ref cend() is returned.
826  
1195  
827   
        @par Complexity
1196   
        @par Complexity
828   
        Constant.
1197   
        Constant.
829  
1198  
830   
        @par Exception Safety
1199   
        @par Exception Safety
831   
        No-throw guarantee.
1200   
        No-throw guarantee.
832   
    */
1201   
    */
833   
    const_iterator
1202   
    const_iterator
834   
    cbegin() const noexcept
1203   
    cbegin() const noexcept
835   
    {
1204   
    {
836   
        return impl_.data();
1205   
        return impl_.data();
837   
    }
1206   
    }
838  
1207  
839   
    /** Return an iterator to the end.
1208   
    /** Return an iterator to the end.
840  
1209  
841 - 
        The returned iterator only acts as a sentinel. Dereferencing it results
1210 + 
        Returns an iterator to the character
842 - 
        in undefined behavior.
1211 + 
        following the last character of the string.
 
1212 + 
        This character acts as a placeholder, attempting
 
1213 + 
        to access it results in undefined behavior.
843  
1214  
844   
        @par Complexity
1215   
        @par Complexity
845   
        Constant.
1216   
        Constant.
846  
1217  
847   
        @par Exception Safety
1218   
        @par Exception Safety
848 -
 
849 - 
        @{
 
850   
        No-throw guarantee.
1219   
        No-throw guarantee.
851   
    */
1220   
    */
852   
    iterator
1221   
    iterator
853   
    end() noexcept
1222   
    end() noexcept
854   
    {
1223   
    {
855   
        return impl_.end();
1224   
        return impl_.end();
856   
    }
1225   
    }
857  
1226  
 
1227 + 
    /** Return an iterator to the end.
 
1228 +
 
1229 + 
        Returns an iterator to the character following
 
1230 + 
        the last character of the string.
 
1231 + 
        This character acts as a placeholder, attempting
 
1232 + 
        to access it results in undefined behavior.
 
1233 +
 
1234 + 
        @par Complexity
 
1235 + 
        Constant.
 
1236 +
 
1237 + 
        @par Exception Safety
 
1238 + 
        No-throw guarantee.
 
1239 + 
    */
858   
    const_iterator
1240   
    const_iterator
859   
    end() const noexcept
1241   
    end() const noexcept
860   
    {
1242   
    {
861   
        return impl_.end();
1243   
        return impl_.end();
862 - 
    /// @}
 
863   
    }
1244   
    }
864  
1245  
865 - 
    /** Return a const iterator past the last element.
1246 + 
    /** Return an iterator to the end.
866  
1247  
867 - 
        The returned iterator only acts as a sentinel. Dereferencing it results
1248 + 
        Returns an iterator to the character following
868 - 
        in undefined behavior.
1249 + 
        the last character of the string.
 
1250 + 
        This character acts as a placeholder, attempting
 
1251 + 
        to access it results in undefined behavior.
869  
1252  
870   
        @par Complexity
1253   
        @par Complexity
871   
        Constant.
1254   
        Constant.
872  
1255  
873   
        @par Exception Safety
1256   
        @par Exception Safety
874   
        No-throw guarantee.
1257   
        No-throw guarantee.
875   
    */
1258   
    */
876   
    const_iterator
1259   
    const_iterator
877   
    cend() const noexcept
1260   
    cend() const noexcept
878   
    {
1261   
    {
879   
        return impl_.end();
1262   
        return impl_.end();
880   
    }
1263   
    }
881  
1264  
882   
    /** Return a reverse iterator to the first character of the reversed container.
1265   
    /** Return a reverse iterator to the first character of the reversed container.
883  
1266  
884 - 
        Returns the pointed-to character that corresponds to the last character
1267 + 
        Returns the pointed-to character that
885 - 
        of the non-reversed container. If the container is empty, @ref rend()
1268 + 
        corresponds to the last character of the
886 - 
        is returned.
1269 + 
        non-reversed container.
 
1270 + 
        If the container is empty, @ref rend() is returned.
887  
1271  
888   
        @par Complexity
1272   
        @par Complexity
889   
        Constant.
1273   
        Constant.
890  
1274  
891 - 
        @{
1275 + 
        @par Exception Safety
 
1276 + 
        No-throw guarantee.
892   
    */
1277   
    */
893   
    reverse_iterator
1278   
    reverse_iterator
894   
    rbegin() noexcept
1279   
    rbegin() noexcept
895   
    {
1280   
    {
896   
        return reverse_iterator(impl_.end());
1281   
        return reverse_iterator(impl_.end());
897   
    }
1282   
    }
898  
1283  
 
1284 + 
    /** Return a reverse iterator to the first character of the reversed container.
 
1285 +
 
1286 + 
        Returns the pointed-to character that
 
1287 + 
        corresponds to the last character of the
 
1288 + 
        non-reversed container.
 
1289 + 
        If the container is empty, @ref rend() is returned.
 
1290 +
 
1291 + 
        @par Complexity
 
1292 + 
        Constant.
 
1293 +
 
1294 + 
        @par Exception Safety
 
1295 + 
        No-throw guarantee.
 
1296 + 
    */
899   
    const_reverse_iterator
1297   
    const_reverse_iterator
900   
    rbegin() const noexcept
1298   
    rbegin() const noexcept
901   
    {
1299   
    {
902   
        return const_reverse_iterator(impl_.end());
1300   
        return const_reverse_iterator(impl_.end());
903 - 
    /// @}
 
904   
    }
1301   
    }
905  
1302  
906 - 
    /** Return a const reverse iterator to the first element of the reversed container.
1303 + 
    /** Return a reverse iterator to the first character of the reversed container.
907  
1304  
908 - 
        Returns the pointed-to character that corresponds to the last character
1305 + 
        Returns the pointed-to character that
909 - 
        of the non-reversed container. If the container is empty, @ref crend()
1306 + 
        corresponds to the last character of the
910 - 
        is returned.
1307 + 
        non-reversed container.
 
1308 + 
        If the container is empty, @ref crend() is returned.
911  
1309  
912   
        @par Complexity
1310   
        @par Complexity
913   
        Constant.
1311   
        Constant.
914  
1312  
915   
        @par Exception Safety
1313   
        @par Exception Safety
916   
        No-throw guarantee.
1314   
        No-throw guarantee.
917   
    */
1315   
    */
918   
    const_reverse_iterator
1316   
    const_reverse_iterator
919   
    crbegin() const noexcept
1317   
    crbegin() const noexcept
920   
    {
1318   
    {
921   
        return const_reverse_iterator(impl_.end());
1319   
        return const_reverse_iterator(impl_.end());
922   
    }
1320   
    }
923  
1321  
924   
    /** Return a reverse iterator to the character following the last character of the reversed container.
1322   
    /** Return a reverse iterator to the character following the last character of the reversed container.
925  
1323  
926 - 
        The pointed-to element corresponds to the element preceding the first
1324 + 
        Returns the pointed-to character that corresponds
927 - 
        element of the non-reversed container. The returned iterator only acts
1325 + 
        to the character preceding the first character of
928 - 
        as a sentinel. Dereferencing it results in undefined behavior.
1326 + 
        the non-reversed container.
 
1327 + 
        This character acts as a placeholder, attempting
 
1328 + 
        to access it results in undefined behavior.
929  
1329  
930   
        @par Complexity
1330   
        @par Complexity
931   
        Constant.
1331   
        Constant.
932  
1332  
933   
        @par Exception Safety
1333   
        @par Exception Safety
934 -
 
935 - 
        @{
 
936   
        No-throw guarantee.
1334   
        No-throw guarantee.
937   
    */
1335   
    */
938   
    reverse_iterator
1336   
    reverse_iterator
939   
    rend() noexcept
1337   
    rend() noexcept
940   
    {
1338   
    {
941   
        return reverse_iterator(begin());
1339   
        return reverse_iterator(begin());
942   
    }
1340   
    }
943  
1341  
 
1342 + 
    /** Return a reverse iterator to the character following the last character of the reversed container.
 
1343 +
 
1344 + 
        Returns the pointed-to character that corresponds
 
1345 + 
        to the character preceding the first character of
 
1346 + 
        the non-reversed container.
 
1347 + 
        This character acts as a placeholder, attempting
 
1348 + 
        to access it results in undefined behavior.
 
1349 +
 
1350 + 
        @par Complexity
 
1351 + 
        Constant.
 
1352 +
 
1353 + 
        @par Exception Safety
 
1354 + 
        No-throw guarantee.
 
1355 + 
    */
944   
    const_reverse_iterator
1356   
    const_reverse_iterator
945   
    rend() const noexcept
1357   
    rend() const noexcept
946   
    {
1358   
    {
947   
        return const_reverse_iterator(begin());
1359   
        return const_reverse_iterator(begin());
948 - 
    /// @}
 
949   
    }
1360   
    }
950  
1361  
951 - 
    /** Return a const reverse iterator to the character following the last character of the reversed container.
1362 + 
    /** Return a reverse iterator to the character following the last character of the reversed container.
952  
1363  
953 - 
        The pointed-to character corresponds to the character preceding the
1364 + 
        Returns the pointed-to character that corresponds
954 - 
        first character of the non-reversed container. The returned iterator
1365 + 
        to the character preceding the first character of
955 - 
        only acts as a sentinel. Dereferencing it results in undefined
1366 + 
        the non-reversed container.
956 - 
        behavior.
1367 + 
        This character acts as a placeholder, attempting
 
1368 + 
        to access it results in undefined behavior.
957  
1369  
958   
        @par Complexity
1370   
        @par Complexity
959   
        Constant.
1371   
        Constant.
960  
1372  
961   
        @par Exception Safety
1373   
        @par Exception Safety
962   
        No-throw guarantee.
1374   
        No-throw guarantee.
963   
    */
1375   
    */
964   
    const_reverse_iterator
1376   
    const_reverse_iterator
965   
    crend() const noexcept
1377   
    crend() const noexcept
966   
    {
1378   
    {
967   
        return const_reverse_iterator(begin());
1379   
        return const_reverse_iterator(begin());
968   
    }
1380   
    }
969  
1381  
970   
    //------------------------------------------------------
1382   
    //------------------------------------------------------
971   
    //
1383   
    //
972   
    // Capacity
1384   
    // Capacity
973   
    //
1385   
    //
974   
    //------------------------------------------------------
1386   
    //------------------------------------------------------
975  
1387  
976   
    /** Check if the string has no characters.
1388   
    /** Check if the string has no characters.
977  
1389  
978 - 
        Returns `true` if there are no characters in the string, i.e. @ref
1390 + 
        Returns `true` if there are no characters in
979 - 
        size() returns 0.
1391 + 
        the string, i.e. @ref size() returns 0.
980  
1392  
981 - 
        Constant.
 
982   
        @par Complexity
1393   
        @par Complexity
983  
1394  
984 - 
        @par Exception Safety
1395 + 
        Constant.
985 - 
        No-throw guarantee.
 
986   
    */
1396   
    */
987   
    bool
1397   
    bool
988   
    empty() const noexcept
1398   
    empty() const noexcept
989   
    {
1399   
    {
990   
        return impl_.size() == 0;
1400   
        return impl_.size() == 0;
991   
    }
1401   
    }
992  
1402  
993   
    /** Return the number of characters in the string.
1403   
    /** Return the number of characters in the string.
994  
1404  
995 - 
        The value returned does not include the null terminator, which is
1405 + 
        The value returned does not include the
996 - 
        always present.
1406 + 
        null terminator, which is always present.
997  
1407  
998   
        @par Complexity
1408   
        @par Complexity
 
1409 +
999   
        Constant.
1410   
        Constant.
1000   
    */
1411   
    */
1001   
    std::size_t
1412   
    std::size_t
1002   
    size() const noexcept
1413   
    size() const noexcept
1003   
    {
1414   
    {
1004   
        return impl_.size();
1415   
        return impl_.size();
1005   
    }
1416   
    }
1006  
1417  
1007   
    /** Return the maximum number of characters any string can hold.
1418   
    /** Return the maximum number of characters any string can hold.
1008  
1419  
1009 - 
        The maximum is an implementation-defined number. This value is
1420 + 
        The maximum is an implementation-defined number.
1010 - 
        a theoretical limit; at runtime, the actual maximum size may be less
1421 + 
        This value is a theoretical limit; at runtime,
1011 - 
        due to resource limits.
1422 + 
        the actual maximum size may be less due to
 
1423 + 
        resource limits.
1012  
1424  
1013   
        @par Complexity
1425   
        @par Complexity
 
1426 +
1014   
        Constant.
1427   
        Constant.
1015   
    */
1428   
    */
1016   
    static
1429   
    static
1017   
    constexpr
1430   
    constexpr
1018   
    std::size_t
1431   
    std::size_t
1019   
    max_size() noexcept
1432   
    max_size() noexcept
1020   
    {
1433   
    {
1021   
        return string_impl::max_size();
1434   
        return string_impl::max_size();
1022   
    }
1435   
    }
1023  
1436  
1024 - 
    /** Return the number of characters that can be held in currently allocated memory.
1437 + 
    /** Return the number of characters that can be held without a reallocation.
1025  
1438  
1026 - 
        Returns the number of characters that the container has currently
1439 + 
        This number represents the largest number of
1027 - 
        allocated space for. This number is never smaller than the value
1440 + 
        characters the currently allocated storage can contain.
1028 - 
        returned by @ref size().
1441 + 
        This number may be larger than the value returned
 
1442 + 
        by @ref size().
1029  
1443  
1030 - 
        Constant.
 
1031   
        @par Complexity
1444   
        @par Complexity
1032  
1445  
1033 - 
        @par Exception Safety
1446 + 
        Constant.
1034 - 
        No-throw guarantee.
 
1035   
    */
1447   
    */
1036   
    std::size_t
1448   
    std::size_t
1037   
    capacity() const noexcept
1449   
    capacity() const noexcept
1038   
    {
1450   
    {
1039   
        return impl_.capacity();
1451   
        return impl_.capacity();
1040   
    }
1452   
    }
1041  
1453  
1042   
    /** Increase the capacity to at least a certain amount.
1454   
    /** Increase the capacity to at least a certain amount.
1043  
1455  
1044 - 
        This increases the capacity of the array to a value that is greater
1456 + 
        This increases the capacity of the array to a value
1045 - 
        than or equal to `new_capacity`. If `new_capacity > `@ref capacity(),
1457 + 
        that is greater than or equal to `new_capacity`. If
1046 - 
        new memory is allocated. Otherwise, the call has no effect. The number
1458 + 
        `new_capacity > capacity()`, new memory is
1047 - 
        of elements and therefore the @ref size() of the container is not
1459 + 
        allocated. Otherwise, the call has no effect.
1048 - 
        changed.
1460 + 
        The number of elements and therefore the
1049 -
1461 + 
        @ref size() of the container is not changed.
1050 - 
        If new memory is allocated, all iterators including any past-the-end
 
1051 - 
        iterators, and all references to the elements are invalidated.
 
1052 - 
        Otherwise, no iterators or references are invalidated.
 
1053  
1462  
1054   
        @par Complexity
1463   
        @par Complexity
 
1464 +
1055   
        At most, linear in @ref size().
1465   
        At most, linear in @ref size().
1056  
1466  
1057   
        @par Exception Safety
1467   
        @par Exception Safety
1058 - 
        Strong guarantee. Calls to `memory_resource::allocate` may throw.
1468 +
 
1469 + 
        Strong guarantee.
 
1470 + 
        Calls to `memory_resource::allocate` may throw.
 
1471 +
 
1472 + 
        @note
 
1473 +
 
1474 + 
        If new memory is allocated, all iterators including
 
1475 + 
        any past-the-end iterators, and all references to
 
1476 + 
        the elements are invalidated. Otherwise, no
 
1477 + 
        iterators or references are invalidated.
1059  
1478  
1060   
        @param new_capacity The new capacity of the array.
1479   
        @param new_capacity The new capacity of the array.
1061  
1480  
1062 - 
        @throw boost::system::system_error `new_capacity > `@ref max_size().
1481 + 
        @throw `boost::system::system_error` `new_capacity > max_size()`.
1063   
    */
1482   
    */
1064   
    void
1483   
    void
1065   
    reserve(std::size_t new_capacity)
1484   
    reserve(std::size_t new_capacity)
1066   
    {
1485   
    {
1067   
        if(new_capacity <= capacity())
1486   
        if(new_capacity <= capacity())
1068   
            return;
1487   
            return;
1069   
        reserve_impl(new_capacity);
1488   
        reserve_impl(new_capacity);
1070   
    }
1489   
    }
1071  
1490  
1072   
    /** Request the removal of unused capacity.
1491   
    /** Request the removal of unused capacity.
1073  
1492  
1074 - 
        This performs a non-binding request to reduce @ref capacity() to
1493 + 
        This performs a non-binding request to reduce
1075 - 
        @ref size(). The request may or may not be fulfilled.
1494 + 
        @ref capacity() to @ref size(). The request may
1076 -
1495 + 
        or may not be fulfilled.
1077 - 
        @note If reallocation occurs, all iterators including  any past-the-end
 
1078 - 
        iterators, and all references to characters are invalidated. Otherwise,
 
1079 - 
        no iterators or references are invalidated.
 
1080  
1496  
1081   
        @par Complexity
1497   
        @par Complexity
 
1498 +
1082   
        At most, linear in @ref size().
1499   
        At most, linear in @ref size().
 
1500 +
 
1501 + 
        @note If reallocation occurs, all iterators
 
1502 + 
        including  any past-the-end iterators, and all
 
1503 + 
        references to characters are invalidated.
 
1504 + 
        Otherwise, no iterators or references are
 
1505 + 
        invalidated.
1083   
    */
1506   
    */
1084   
    BOOST_JSON_DECL
1507   
    BOOST_JSON_DECL
1085   
    void
1508   
    void
1086   
    shrink_to_fit();
1509   
    shrink_to_fit();
1087  
1510  
1088   
    //------------------------------------------------------
1511   
    //------------------------------------------------------
1089   
    //
1512   
    //
1090   
    // Operations
1513   
    // Operations
1091   
    //
1514   
    //
1092   
    //------------------------------------------------------
1515   
    //------------------------------------------------------
1093  
1516  
1094   
    /** Clear the contents.
1517   
    /** Clear the contents.
1095  
1518  
1096 - 
        Erases all characters from the string. After this call, @ref size()
1519 + 
        Erases all characters from the string. After this
1097 - 
        returns zero but @ref capacity() is unchanged. All references,
1520 + 
        call, @ref size() returns zero but @ref capacity()
1098 - 
        pointers, or iterators referring to contained elements are invalidated.
1521 + 
        is unchanged.
1099 - 
        Any past-the-end iterators are also invalidated.
 
1100  
1522  
1101   
        @par Complexity
1523   
        @par Complexity
 
1524 +
1102   
        Linear in @ref size().
1525   
        Linear in @ref size().
1103  
1526  
1104 - 
        @par Exception Safety
1527 + 
        @note All references, pointers, or iterators
1105 - 
        No-throw guarantee.
1528 + 
        referring to contained elements are invalidated.
 
1529 + 
        Any past-the-end iterators are also invalidated.
1106   
    */
1530   
    */
1107   
    BOOST_JSON_DECL
1531   
    BOOST_JSON_DECL
1108   
    void
1532   
    void
1109   
    clear() noexcept;
1533   
    clear() noexcept;
1110  
1534  
1111 - 
    /** Insert characters at the specified index.
1535 + 
    //------------------------------------------------------
1112  
1536  
1113 - 
        @li **(1)** inserts `sv`.
1537 + 
    /** Insert a string.
1114 - 
        @li **(2)** inserts `count` copies of `ch`.
 
1115 - 
        @li **(3)** inserts the character `ch`.
 
1116 - 
        @li **(4)** inserts characters from the range `[first, last)`.
 
1117  
1538  
1118 - 
        The first character is inserted at the index `pos`. All references,
1539 + 
        Inserts the `string_view` `sv` at the position `pos`.
1119 - 
        pointers, or iterators referring to contained elements are invalidated.
 
1120 - 
        Any past-the-end iterators are also invalidated.
 
1121  
1540  
1122 - 
        @par Constraints
1541 + 
        @par Exception Safety
1123 - 
        `InputIt` satisfies {req_InputIterator}.
 
1124  
1542  
1125 - 
        @pre
1543 + 
        Strong guarantee.
1126 - 
        `[first, last)` is a valid range.
 
1127  
1544  
1128 - 
        @par Exception Safety
1545 + 
        @note All references, pointers, or iterators
1129 - 
        @li **(1)**--*(3)* strong guarantee.
1546 + 
        referring to contained elements are invalidated.
1130 - 
        @li **(4)** strong guarantee if `InputIt` satisfies
1547 + 
        Any past-the-end iterators are also invalidated.
1131 - 
            {req_ForwardIterator}, basic guarantee otherwise.
 
1132  
1548  
1133   
        @return `*this`
1549   
        @return `*this`
1134  
1550  
1135 - 
        @param sv The `string_view` to insert.
 
1136 -
 
1137 - 
        @throw boost::system::system_error The size of the string would exceed
 
1138 - 
               @ref max_size().
 
1139   
        @param pos The index to insert at.
1551   
        @param pos The index to insert at.
1140  
1552  
1141 - 
        @throw boost::system::system_error `pos > `@ref size().
1553 + 
        @param sv The `string_view` to insert.
1142  
1554  
1143 - 
        @{
1555 + 
        @throw `boost::system::system_error` `size() + s.size() > max_size()`.
 
1556 + 
        @throw `boost::system::system_error` `pos > size()`.
1144   
    */
1557   
    */
1145   
    BOOST_JSON_DECL
1558   
    BOOST_JSON_DECL
1146   
    string&
1559   
    string&
1147   
    insert(
1560   
    insert(
1148   
        std::size_t pos,
1561   
        std::size_t pos,
1149   
        string_view sv);
1562   
        string_view sv);
1150  
1563  
1151 - 
    /** Overload
1564 + 
    /** Insert a character.
 
1565 +
 
1566 + 
        Inserts `count` copies of `ch` at the position `pos`.
 
1567 +
 
1568 + 
        @par Exception Safety
 
1569 +
 
1570 + 
        Strong guarantee.
 
1571 +
 
1572 + 
        @note All references, pointers, or iterators
 
1573 + 
        referring to contained elements are invalidated.
 
1574 + 
        Any past-the-end iterators are also invalidated.
 
1575 +
 
1576 + 
        @return `*this`
 
1577 +
 
1578 + 
        @param pos The index to insert at.
 
1579 +
1152   
        @param count The number of characters to insert.
1580   
        @param count The number of characters to insert.
 
1581 +
1153   
        @param ch The character to insert.
1582   
        @param ch The character to insert.
1154 - 
        @param pos
1583 +
 
1584 + 
        @throw `boost::system::system_error` `size() + count > max_size()`.
 
1585 + 
        @throw `boost::system::system_error` `pos > size()`.
1155   
    */
1586   
    */
1156   
    BOOST_JSON_DECL
1587   
    BOOST_JSON_DECL
1157   
    string&
1588   
    string&
1158   
    insert(
1589   
    insert(
1159   
        std::size_t pos,
1590   
        std::size_t pos,
1160   
        std::size_t count,
1591   
        std::size_t count,
1161   
        char ch);
1592   
        char ch);
1162  
1593  
1163 - 
    /** Overload
1594 + 
    /** Insert a character.
1164 - 
        @param pos
1595 +
1165 - 
        @param ch
1596 + 
        Inserts the character `ch` before the character
 
1597 + 
        at index `pos`.
 
1598 +
 
1599 + 
        @par Exception Safety
 
1600 +
 
1601 + 
        Strong guarantee.
 
1602 +
 
1603 + 
        @note All references, pointers, or iterators
 
1604 + 
        referring to contained elements are invalidated.
 
1605 + 
        Any past-the-end iterators are also invalidated.
 
1606 +
 
1607 + 
        @return `*this`
 
1608 +
 
1609 + 
        @param pos The index to insert at.
 
1610 +
 
1611 + 
        @param ch The character to insert.
 
1612 +
 
1613 + 
        @throw `boost::system::system_error` `size() + 1 > max_size()`.
 
1614 + 
        @throw `boost::system::system_error` `pos > size()`.
1166   
    */
1615   
    */
1167   
    string&
1616   
    string&
1168   
    insert(
1617   
    insert(
1169   
        size_type pos,
1618   
        size_type pos,
1170   
        char ch)
1619   
        char ch)
1171   
    {
1620   
    {
1172   
        return insert(pos, 1, ch);
1621   
        return insert(pos, 1, ch);
1173   
    }
1622   
    }
1174  
1623  
1175 - 
    /** Overload
1624 + 
    /** Insert a range of characters.
 
1625 +
 
1626 + 
        Inserts characters from the range `{first, last)`
 
1627 + 
        before the character at index `pos`.
 
1628 +
 
1629 + 
        @par Precondition
 
1630 +
 
1631 + 
        `{first, last)` is a valid range.
 
1632 +
 
1633 + 
        @par Exception Safety
 
1634 +
 
1635 + 
        Strong guarantee.
 
1636 +
 
1637 + 
        @note All references, pointers, or iterators
 
1638 + 
        referring to contained elements are invalidated.
 
1639 + 
        Any past-the-end iterators are also invalidated.
1176  
1640  
1177   
        @tparam InputIt The type of the iterators.
1641   
        @tparam InputIt The type of the iterators.
1178  
1642  
 
1643 + 
        @par Constraints
 
1644 +
 
1645 + 
        `InputIt` satisfies __InputIterator__.
 
1646 +
 
1647 + 
        @return `*this`
 
1648 +
 
1649 + 
        @param pos The index to insert at.
 
1650 +
1179   
        @param first The beginning of the character range.
1651   
        @param first The beginning of the character range.
 
1652 +
1180   
        @param last The end of the character range.
1653   
        @param last The end of the character range.
1181 - 
        @param pos
1654 +
 
1655 + 
        @throw `boost::system::system_error` `size() + insert_count > max_size()`.
 
1656 + 
        @throw `boost::system::system_error` `pos > size()`.
1182   
    */
1657   
    */
1183   
    template<class InputIt
1658   
    template<class InputIt
1184   
    #ifndef BOOST_JSON_DOCS
1659   
    #ifndef BOOST_JSON_DOCS
1185   
        ,class = is_inputit<InputIt>
1660   
        ,class = is_inputit<InputIt>
1186   
    #endif
1661   
    #endif
1187   
    >
1662   
    >
1188   
    string&
1663   
    string&
1189   
    insert(
1664   
    insert(
1190   
        size_type pos,
1665   
        size_type pos,
1191   
        InputIt first,
1666   
        InputIt first,
1192 - 
    /// @}
 
1193   
        InputIt last);
1667   
        InputIt last);
1194  
1668  
1195 - 
    /** Remove characters from the string.
1669 + 
    //------------------------------------------------------
1196 -
 
1197 - 
        @li **(1)** removes at most `count` but not more than `size() - pos`
 
1198 - 
            characters starting at `index`.
 
1199 - 
        @li **(2)** removes the character at `pos`.
 
1200 - 
        @li **(3)** removes characters in the range `[first, last)`.
 
1201 -
 
1202 - 
        All references, pointers, or iterators referring to contained elements
 
1203 - 
        are invalidated. Any past-the-end iterators are also invalidated.
 
1204  
1670  
1205 - 
        @pre
1671 + 
    /** Erase characters from the string.
1206 - 
        `pos`, `first`, and `last` are iterators into this string. `first` and
 
1207 - 
        `last` form a valid range.
 
1208  
1672  
1209 - 
        @par Complexity
1673 + 
        Erases `num` characters from the string, starting
1210 - 
        @li **(1)** linear in `count`.
1674 + 
        at `pos`.  `num` is determined as the smaller of
1211 - 
        @li **(2)** constant.
1675 + 
        `count` and `size() - pos`.
1212 - 
        @li **(3)** linear in `std::distance(first, last)`.
 
1213  
1676  
1214 - 
        Strong guarantee.
 
1215 -
 
1216 - 
        @return
 
1217 - 
        @li **(1)** `*this`.
 
1218   
        @par Exception Safety
1677   
        @par Exception Safety
1219  
1678  
1220 - 
        @li **(2)** An iterator referring to the character immediately
1679 + 
        Strong guarantee.
1221 - 
        following the removed character, or @ref end() if one does not exist.
 
1222  
1680  
1223 - 
        @li **(3)** An iterator referring to the character `last` previously
1681 + 
        @note All references, pointers, or iterators
1224 - 
        referred to, or @ref end() if one does not exist.
1682 + 
        referring to contained elements are invalidated.
 
1683 + 
        Any past-the-end iterators are also invalidated.
1225  
1684  
1226 - 
        @param index The index of the first character to remove.
1685 + 
        @return `*this`
1227  
1686  
1228 - 
        @param count The number of characters to remove. By default remove
1687 + 
        @param pos The index to erase at.
1229 - 
        until the end of the string.
1688 + 
        The default argument for this parameter is `0`.
1230  
1689  
1231 - 
        @throw boost::system::system_error `pos >` @ref size().
1690 + 
        @param count The number of characters to erase.
 
1691 + 
        The default argument for this parameter
 
1692 + 
        is @ref npos.
1232  
1693  
1233 - 
        @{
1694 + 
        @throw `boost::system::system_error` `pos > size()`.
1234   
    */
1695   
    */
1235   
    BOOST_JSON_DECL
1696   
    BOOST_JSON_DECL
1236   
    string&
1697   
    string&
1237   
    erase(
1698   
    erase(
1238 - 
        std::size_t index = 0,
1699 + 
        std::size_t pos = 0,
1239   
        std::size_t count = npos);
1700   
        std::size_t count = npos);
1240  
1701  
1241 - 
    /** Overload
1702 + 
    /** Erase a character from the string.
1242 - 
        @param pos An iterator referring to the character to erase.
1703 +
 
1704 + 
        Erases the character at `pos`.
 
1705 +
 
1706 + 
        @par Precondition
 
1707 +
 
1708 + 
        @code
 
1709 + 
        pos >= data() && pos <= data() + size()
 
1710 + 
        @endcode
 
1711 +
 
1712 + 
        @par Exception Safety
 
1713 +
 
1714 + 
        Strong guarantee.
 
1715 +
 
1716 + 
        @note All references, pointers, or iterators
 
1717 + 
        referring to contained elements are invalidated.
 
1718 + 
        Any past-the-end iterators are also invalidated.
 
1719 +
 
1720 + 
        @return An iterator referring to character
 
1721 + 
        immediately following the erased character, or
 
1722 + 
        @ref end() if one does not exist.
 
1723 +
 
1724 + 
        @param pos An iterator referring to the
 
1725 + 
        character to erase.
1243   
    */
1726   
    */
1244   
    BOOST_JSON_DECL
1727   
    BOOST_JSON_DECL
1245   
    iterator
1728   
    iterator
1246   
    erase(const_iterator pos);
1729   
    erase(const_iterator pos);
1247  
1730  
1248 - 
    /** Overload
1731 + 
    /** Erase a range from the string.
1249 - 
        @param first An iterator representing the first character to erase.
1732 +
1250 - 
        @param last An iterator one past the last character to erase.
1733 + 
        Erases the characters in the range `{first, last)`.
 
1734 +
 
1735 + 
        @par Precondition
 
1736 +
 
1737 + 
        `{first, last}` shall be valid within
 
1738 + 
        @code
 
1739 + 
        {data(), data() + size()}
 
1740 + 
        @endcode
 
1741 +
 
1742 + 
        @par Exception Safety
 
1743 +
 
1744 + 
        Strong guarantee.
 
1745 +
 
1746 + 
        @note All references, pointers, or iterators
 
1747 + 
        referring to contained elements are invalidated.
 
1748 + 
        Any past-the-end iterators are also invalidated.
 
1749 +
 
1750 + 
        @return An iterator referring to the character
 
1751 + 
        `last` previously referred to, or @ref end()
 
1752 + 
        if one does not exist.
 
1753 +
 
1754 + 
        @param first An iterator representing the first
 
1755 + 
        character to erase.
 
1756 +
 
1757 + 
        @param last An iterator one past the last
 
1758 + 
        character to erase.
1251   
    */
1759   
    */
1252   
    BOOST_JSON_DECL
1760   
    BOOST_JSON_DECL
1253   
    iterator
1761   
    iterator
1254   
    erase(
1762   
    erase(
1255   
        const_iterator first,
1763   
        const_iterator first,
1256 - 
    /// @}
 
1257   
        const_iterator last);
1764   
        const_iterator last);
1258  
1765  
1259   
    //------------------------------------------------------
1766   
    //------------------------------------------------------
1260  
1767  
1261   
    /** Append a character.
1768   
    /** Append a character.
1262  
1769  
1263   
        Appends a character to the end of the string.
1770   
        Appends a character to the end of the string.
1264  
1771  
1265   
        @par Exception Safety
1772   
        @par Exception Safety
 
1773 +
1266   
        Strong guarantee.
1774   
        Strong guarantee.
1267  
1775  
1268   
        @param ch The character to append.
1776   
        @param ch The character to append.
1269  
1777  
1270 - 
        @throw boost::system::system_error @ref size() `+ 1 > `@ref max_size().
1778 + 
        @throw `boost::system::system_error` `size() + 1 > max_size()`.
1271   
    */
1779   
    */
1272   
    BOOST_JSON_DECL
1780   
    BOOST_JSON_DECL
1273   
    void
1781   
    void
1274   
    push_back(char ch);
1782   
    push_back(char ch);
1275  
1783  
1276   
    /** Remove the last character.
1784   
    /** Remove the last character.
1277  
1785  
1278   
        Removes a character from the end of the string.
1786   
        Removes a character from the end of the string.
1279  
1787  
1280 - 
        @pre
1788 + 
        @par Precondition
 
1789 +
1281   
        @code
1790   
        @code
1282 - 
        ! empty()
1791 + 
        not empty()
1283   
        @endcode
1792   
        @endcode
1284   
    */
1793   
    */
1285   
    BOOST_JSON_DECL
1794   
    BOOST_JSON_DECL
1286   
    void
1795   
    void
1287   
    pop_back();
1796   
    pop_back();
1288  
1797  
1289   
    //------------------------------------------------------
1798   
    //------------------------------------------------------
1290  
1799  
1291   
    /** Append characters to the string.
1800   
    /** Append characters to the string.
1292  
1801  
1293 - 
        @li **(1)** appends `count` copies of `ch`.
1802 + 
        Appends `count` copies of `ch` to the end of
1294 -
1803 + 
        the string.
1295 - 
        @li **(2)** appends copies of characters of `sv`, preserving order.
 
1296 -
 
1297 - 
        @li **(3)** appends characters from the range `[first, last)`,
 
1298 - 
        preserving order.
 
1299 -
 
1300 - 
        @pre
 
1301 - 
        `[first, last)` shall be a valid range.
 
1302 -
 
1303 - 
        @par Constraints
 
1304 - 
        `InputIt` satisfies {req_InputIterator}.
 
1305  
1804  
1306   
        @par Exception Safety
1805   
        @par Exception Safety
 
1806 +
1307   
        Strong guarantee.
1807   
        Strong guarantee.
1308  
1808  
1309 - 
        @return `*this`.
1809 + 
        @return `*this`
1310  
1810  
1311 - 
        @param ch The character to append.
 
1312   
        @param count The number of characters to append.
1811   
        @param count The number of characters to append.
1313  
1812  
1314 - 
        @throw boost::system::system_error The size of the string after the
1813 + 
        @param ch The character to append.
1315 - 
        operation would exceed @ref max_size().
 
1316  
1814  
1317 - 
        @{
1815 + 
        @throw `boost::system::system_error` `size() + count > max_size()`.
1318   
    */
1816   
    */
1319   
    BOOST_JSON_DECL
1817   
    BOOST_JSON_DECL
1320   
    string&
1818   
    string&
1321   
    append(
1819   
    append(
1322   
        std::size_t count,
1820   
        std::size_t count,
1323   
        char ch);
1821   
        char ch);
1324  
1822  
1325 - 
    /** Overload
1823 + 
    /** Append a string to the string.
 
1824 +
 
1825 + 
        Appends `sv` the end of the string.
 
1826 +
 
1827 + 
        @par Exception Safety
 
1828 +
 
1829 + 
        Strong guarantee.
 
1830 +
 
1831 + 
        @return `*this`
 
1832 +
1326   
        @param sv The `string_view` to append.
1833   
        @param sv The `string_view` to append.
 
1834 +
 
1835 + 
        @throw `boost::system::system_error` `size() + s.size() > max_size()`.
1327   
    */
1836   
    */
1328   
    BOOST_JSON_DECL
1837   
    BOOST_JSON_DECL
1329   
    string&
1838   
    string&
1330   
    append(string_view sv);
1839   
    append(string_view sv);
1331  
1840  
1332 - 
    /** Overload
1841 + 
    /** Append a range of characters.
 
1842 +
 
1843 + 
        Appends characters from the range `{first, last)`
 
1844 + 
        to the end of the string.
 
1845 +
 
1846 + 
        @par Precondition
 
1847 +
 
1848 + 
        `{first, last)` shall be a valid range
 
1849 +
 
1850 + 
        @par Exception Safety
 
1851 +
 
1852 + 
        Strong guarantee.
1333  
1853  
1334   
        @tparam InputIt The type of the iterators.
1854   
        @tparam InputIt The type of the iterators.
1335  
1855  
1336 - 
        @param first An iterator representing the first character to append.
1856 + 
        @par Constraints
1337 - 
        @param last An iterator one past the last character to append.
1857 +
 
1858 + 
        `InputIt` satisfies __InputIterator__.
 
1859 +
 
1860 + 
        @return `*this`
 
1861 +
 
1862 + 
        @param first An iterator representing the
 
1863 + 
        first character to append.
 
1864 +
 
1865 + 
        @param last An iterator one past the
 
1866 + 
        last character to append.
 
1867 +
 
1868 + 
        @throw `boost::system::system_error` `size() + insert_count > max_size()`.
1338   
    */
1869   
    */
1339   
    template<class InputIt
1870   
    template<class InputIt
1340   
    #ifndef BOOST_JSON_DOCS
1871   
    #ifndef BOOST_JSON_DOCS
1341   
        ,class = is_inputit<InputIt>
1872   
        ,class = is_inputit<InputIt>
1342   
    #endif
1873   
    #endif
1343   
    >
1874   
    >
1344   
    string&
1875   
    string&
1345 - 
    /// @}
 
1346   
    append(InputIt first, InputIt last);
1876   
    append(InputIt first, InputIt last);
1347  
1877  
1348 - 
    /** Append characters to the string.
1878 + 
    //------------------------------------------------------
1349  
1879  
1350 - 
        @li **(1)** appends `[sv.begin(), sv.end())`.
1880 + 
    /** Append characters from a string.
1351 - 
        @li **(2)** appends `ch`.
1881 +
 
1882 + 
        Appends `{sv.begin(), sv.end())` to the end of
 
1883 + 
        the string.
1352  
1884  
1353   
        @par Exception Safety
1885   
        @par Exception Safety
 
1886 +
1354   
        Strong guarantee.
1887   
        Strong guarantee.
1355  
1888  
1356   
        @return `*this`
1889   
        @return `*this`
1357  
1890  
1358   
        @param sv The `string_view` to append.
1891   
        @param sv The `string_view` to append.
1359  
1892  
1360 - 
        @throw boost::system::system_error The size of the string after the
1893 + 
        @throw `boost::system::system_error` `size() + sv.size() > max_size()`.
1361 - 
        operation would exceed @ref max_size().
 
1362 -
 
1363 - 
        @{
 
1364   
    */
1894   
    */
1365   
    string&
1895   
    string&
1366   
    operator+=(string_view sv)
1896   
    operator+=(string_view sv)
1367   
    {
1897   
    {
1368   
        return append(sv);
1898   
        return append(sv);
1369   
    }
1899   
    }
1370  
1900  
1371 - 
    /** Overload
1901 + 
    /** Append a character.
 
1902 +
 
1903 + 
        Appends a character to the end of the string.
 
1904 +
 
1905 + 
        @par Exception Safety
 
1906 +
 
1907 + 
        Strong guarantee.
 
1908 +
1372   
        @param ch The character to append.
1909   
        @param ch The character to append.
 
1910 +
 
1911 + 
        @throw `boost::system::system_error` `size() + 1 > max_size()`.
1373   
    */
1912   
    */
1374   
    string&
1913   
    string&
1375   
    operator+=(char ch)
1914   
    operator+=(char ch)
1376   
    {
1915   
    {
1377   
        push_back(ch);
1916   
        push_back(ch);
1378   
        return *this;
1917   
        return *this;
1379 - 
    /// @}
 
1380   
    }
1918   
    }
1381  
1919  
1382   
    //------------------------------------------------------
1920   
    //------------------------------------------------------
1383  
1921  
1384   
    /** Compare a string with the string.
1922   
    /** Compare a string with the string.
1385  
1923  
1386 - 
        Let `comp` be `std::char_traits<char>::compare(data(), sv.data(),
1924 + 
        Let `comp` be
1387 - 
        std::min(size(), sv.size())`. If `comp != 0`, then the result is
1925 + 
        `std::char_traits<char>::compare(data(), sv.data(), std::min(size(), sv.size())`.
1388 - 
        `comp`. Otherwise, the result is `0` if `size() == sv.size()`, `-1` if
1926 + 
        If `comp != 0`, then the result is `comp`. Otherwise,
1389 - 
        `size() < sv.size()`, and `1` otherwise.
1927 + 
        the result is `0` if `size() == sv.size()`,
 
1928 + 
        `-1` if `size() < sv.size()`, and `1` otherwise.
1390  
1929  
1391   
        @par Complexity
1930   
        @par Complexity
 
1931 +
1392   
        Linear.
1932   
        Linear.
1393  
1933  
1394 - 
        @return The result of lexicographically comparing the characters of
1934 + 
        @return The result of lexicographically comparing
1395 - 
        `sv` and the string.
1935 + 
        the characters of `sv` and the string.
1396  
1936  
1397   
        @param sv The `string_view` to compare.
1937   
        @param sv The `string_view` to compare.
1398   
    */
1938   
    */
1399   
    int
1939   
    int
1400   
    compare(string_view sv) const noexcept
1940   
    compare(string_view sv) const noexcept
1401   
    {
1941   
    {
1402   
        return subview().compare(sv);
1942   
        return subview().compare(sv);
1403   
    }
1943   
    }
1404  
1944  
1405   
    //------------------------------------------------------
1945   
    //------------------------------------------------------
1406  
1946  
1407 - 
    /** Return whether the string begins with another string.
1947 + 
    /** Return whether the string begins with a string.
1408  
1948  
1409 - 
        @li **(1)** checks if the string begins with `s`.
1949 + 
        Returns `true` if the string begins with `s`,
1410 - 
        @li **(2)** checks if the string begins with `ch`.
1950 + 
        and `false` otherwise.
1411  
1951  
1412 - 
        @li **(1)** linear in `s.size()`.
 
1413 - 
        @li **(2)** constant.
 
1414   
        @par Complexity
1952   
        @par Complexity
1415  
1953  
1416 - 
        @param s The string to check for.
1954 + 
        Linear.
1417  
1955  
1418 - 
        @{
1956 + 
        @param s The `string_view` to check for.
1419   
    */
1957   
    */
1420   
    bool
1958   
    bool
1421   
    starts_with(string_view s) const noexcept
1959   
    starts_with(string_view s) const noexcept
1422   
    {
1960   
    {
1423   
        return subview(0, s.size()) == s;
1961   
        return subview(0, s.size()) == s;
1424   
    }
1962   
    }
1425  
1963  
1426 - 
    /** Overload
1964 + 
    /** Return whether the string begins with a character.
 
1965 +
 
1966 + 
        Returns `true` if the string begins with `ch`,
 
1967 + 
        and `false` otherwise.
 
1968 +
 
1969 + 
        @par Complexity
 
1970 +
 
1971 + 
        Constant.
1427  
1972  
1428   
        @param ch The character to check for.
1973   
        @param ch The character to check for.
1429   
    */
1974   
    */
1430   
    bool
1975   
    bool
1431   
    starts_with(char ch) const noexcept
1976   
    starts_with(char ch) const noexcept
1432   
    {
1977   
    {
1433   
        return ! empty() && front() == ch;
1978   
        return ! empty() && front() == ch;
1434 - 
    /// @}
 
1435   
    }
1979   
    }
1436  
1980  
1437 - 
    /** Check if the string ends with given suffix.
1981 + 
    /** Return whether the string end with a string.
1438  
1982  
1439 - 
        @li **(1)** returns `true` if the string ends with `s`.
1983 + 
        Returns `true` if the string end with `s`,
1440 - 
        @li **(2)** returns `true` if the string ends with the character `ch`.
1984 + 
        and `false` otherwise.
1441  
1985  
1442 - 
        @li **(1)** linear in `s`.
 
1443 - 
        @li **(2)** constant.
 
1444   
        @par Complexity
1986   
        @par Complexity
1445  
1987  
1446 - 
        @par Exception Safety
1988 + 
        Linear.
1447 - 
        No-throw guarantee.
 
1448  
1989  
1449 -
 
1450 - 
        @{
 
1451   
        @param s The string to check for.
1990   
        @param s The string to check for.
1452   
    */
1991   
    */
1453   
    bool
1992   
    bool
1454   
    ends_with(string_view s) const noexcept
1993   
    ends_with(string_view s) const noexcept
1455   
    {
1994   
    {
1456   
        return size() >= s.size() &&
1995   
        return size() >= s.size() &&
1457   
            subview(size() - s.size()) == s;
1996   
            subview(size() - s.size()) == s;
1458   
    }
1997   
    }
1459  
1998  
1460 - 
    /** Overload
1999 + 
    /** Return whether the string ends with a character.
 
2000 +
 
2001 + 
        Returns `true` if the string ends with `ch`,
 
2002 + 
        and `false` otherwise.
 
2003 +
 
2004 + 
        @par Complexity
 
2005 +
 
2006 + 
        Constant.
 
2007 +
1461   
        @param ch The character to check for.
2008   
        @param ch The character to check for.
1462   
    */
2009   
    */
1463   
    bool
2010   
    bool
1464   
    ends_with(char ch) const noexcept
2011   
    ends_with(char ch) const noexcept
1465   
    {
2012   
    {
1466   
        return ! empty() && back() == ch;
2013   
        return ! empty() && back() == ch;
1467 - 
    /// @}
 
1468 -
 
1469 - 
    /** Replace a substring with another string.
 
1470 -
 
1471 - 
        @li **(1)** replaces `std::min(count, size() - pos)` characters
 
1472 - 
            starting at index `pos` with those of `sv`.
 
1473 - 
        @li **(2)** replaces the characters in the range `[first, last)` with
 
1474 - 
            those of `sv`.
 
1475 - 
        @li **(3)** replaces the characters in the range `[first, last)` with
 
1476 - 
            those of `[first2, last2)`.
 
1477 - 
        @li **(4)** replaces `std::min(count, size() - pos)` characters
 
1478 - 
            starting at index `pos` with `count2` copies of `ch`.
 
1479 - 
        @li **(5)** replaces the characters in the range `[first, last)` with
 
1480 - 
            `count2` copies of `ch`.
 
1481   
    }
2014   
    }
1482  
2015  
1483 - 
        All references, pointers, or iterators referring to contained elements
2016 + 
    //------------------------------------------------------
1484 - 
        are invalidated. Any past-the-end iterators are also invalidated.
 
1485  
2017  
1486 - 
        @pre
2018 + 
    /** Replace a substring with a string.
1487 - 
        `[first, last)` is a valid range. `[first2, last2)` is a valid range.
 
1488  
2019  
1489 - 
        @par Constraints
2020 + 
        Replaces `rcount` characters starting at index
1490 - 
        `InputIt` satisfies {req_InputIterator}.
2021 + 
        `pos` with those of `sv`, where `rcount` is
 
2022 + 
        `std::min(count, size() - pos)`.
1491  
2023  
1492   
        @par Exception Safety
2024   
        @par Exception Safety
 
2025 +
1493   
        Strong guarantee.
2026   
        Strong guarantee.
1494  
2027  
 
2028 + 
        @note All references, pointers, or iterators
 
2029 + 
        referring to contained elements are invalidated.
 
2030 + 
        Any past-the-end iterators are also invalidated.
 
2031 +
1495   
        @return `*this`
2032   
        @return `*this`
1496  
2033  
1497   
        @param pos The index to replace at.
2034   
        @param pos The index to replace at.
1498  
2035  
1499   
        @param count The number of characters to replace.
2036   
        @param count The number of characters to replace.
1500  
2037  
1501   
        @param sv The `string_view` to replace with.
2038   
        @param sv The `string_view` to replace with.
1502  
2039  
1503 - 
        @throw boost::system::system_error The resulting string's size would
2040 + 
        @throw `boost::system::system_error` `size() + (sv.size() - rcount) > max_size()`.
1504 - 
               have exceeded @ref max_size().
2041 + 
        @throw `boost::system::system_error` `pos > size()`.
1505 -
 
1506 - 
        @{
 
1507   
    */
2042   
    */
1508   
    BOOST_JSON_DECL
2043   
    BOOST_JSON_DECL
1509   
    string&
2044   
    string&
1510   
    replace(
2045   
    replace(
1511   
        std::size_t pos,
2046   
        std::size_t pos,
1512   
        std::size_t count,
2047   
        std::size_t count,
1513   
        string_view sv);
2048   
        string_view sv);
1514  
2049  
1515 - 
    /** Overload
2050 + 
    /** Replace a range with a string.
1516  
2051  
1517 - 
        @param first An iterator referring to the first character to replace.
2052 + 
        Replaces the characters in the range
1518 - 
        @param last An iterator one past the end of the last character to
2053 + 
        `{first, last)` with those of `sv`.
1519 - 
               replace.
2054 +
1520 - 
        @param sv
2055 + 
        @par Precondition
 
2056 +
 
2057 + 
        `{first, last)` is a valid range.
 
2058 +
 
2059 + 
        @par Exception Safety
 
2060 +
 
2061 + 
        Strong guarantee.
 
2062 +
 
2063 + 
        @note All references, pointers, or iterators
 
2064 + 
        referring to contained elements are invalidated.
 
2065 + 
        Any past-the-end iterators are also invalidated.
 
2066 +
 
2067 + 
        @return `*this`
 
2068 +
 
2069 + 
        @param first An iterator referring to the first
 
2070 + 
        character to replace.
 
2071 +
 
2072 + 
        @param last An iterator one past the end of
 
2073 + 
        the last character to replace.
 
2074 +
 
2075 + 
        @param sv The `string_view` to replace with.
 
2076 +
 
2077 + 
        @throw `boost::system::system_error` `size() + (sv.size() - std::distance(first, last)) > max_size()`.
1521   
    */
2078   
    */
1522   
    string&
2079   
    string&
1523   
    replace(
2080   
    replace(
1524   
        const_iterator first,
2081   
        const_iterator first,
1525   
        const_iterator last,
2082   
        const_iterator last,
1526   
        string_view sv)
2083   
        string_view sv)
1527   
    {
2084   
    {
1528   
        return replace(first - begin(), last - first, sv);
2085   
        return replace(first - begin(), last - first, sv);
1529   
    }
2086   
    }
1530  
2087  
1531 - 
    /** Overload
2088 + 
    /** Replace a range with a range.
 
2089 +
 
2090 + 
        Replaces the characters in the range
 
2091 + 
        `{first, last)` with those of `{first2, last2)`.
 
2092 +
 
2093 + 
        @par Precondition
 
2094 +
 
2095 + 
        `{first, last)` is a valid range.
 
2096 +
 
2097 + 
        `{first2, last2)` is a valid range.
 
2098 +
 
2099 + 
        @par Exception Safety
 
2100 +
 
2101 + 
        Strong guarantee.
 
2102 +
 
2103 + 
        @note All references, pointers, or iterators
 
2104 + 
        referring to contained elements are invalidated.
 
2105 + 
        Any past-the-end iterators are also invalidated.
1532  
2106  
1533   
        @tparam InputIt The type of the iterators.
2107   
        @tparam InputIt The type of the iterators.
1534  
2108  
1535 - 
        @param first2 An iterator referring to the first character to replace
2109 + 
        @par Constraints
1536 - 
               with.
2110 +
1537 - 
        @param last2 An iterator one past the end of the last character to
2111 + 
        `InputIt` satisfies __InputIterator__.
1538 - 
               replace with.
2112 +
1539 - 
        @param first
2113 + 
        @return `*this`
1540 - 
        @param last
2114 +
 
2115 + 
        @param first An iterator referring to the first
 
2116 + 
        character to replace.
 
2117 +
 
2118 + 
        @param last An iterator one past the end of
 
2119 + 
        the last character to replace.
 
2120 +
 
2121 + 
        @param first2 An iterator referring to the first
 
2122 + 
        character to replace with.
 
2123 +
 
2124 + 
        @param last2 An iterator one past the end of
 
2125 + 
        the last character to replace with.
 
2126 +
 
2127 + 
        @throw `boost::system::system_error` `size() + (inserted - std::distance(first, last)) > max_size()`.
1541   
    */
2128   
    */
1542   
    template<class InputIt
2129   
    template<class InputIt
1543   
    #ifndef BOOST_JSON_DOCS
2130   
    #ifndef BOOST_JSON_DOCS
1544   
        ,class = is_inputit<InputIt>
2131   
        ,class = is_inputit<InputIt>
1545   
    #endif
2132   
    #endif
1546   
    >
2133   
    >
1547   
    string&
2134   
    string&
1548   
    replace(
2135   
    replace(
1549   
        const_iterator first,
2136   
        const_iterator first,
1550   
        const_iterator last,
2137   
        const_iterator last,
1551   
        InputIt first2,
2138   
        InputIt first2,
1552   
        InputIt last2);
2139   
        InputIt last2);
1553  
2140  
1554 - 
    /** Overload
2141 + 
    /** Replace a substring with copies of a character.
 
2142 +
 
2143 + 
        Replaces `rcount` characters starting at index
 
2144 + 
        `pos`with `count2` copies of `ch`, where
 
2145 + 
        `rcount` is `std::min(count, size() - pos)`.
 
2146 +
 
2147 + 
        @par Exception Safety
 
2148 +
 
2149 + 
        Strong guarantee.
 
2150 +
 
2151 + 
        @note All references, pointers, or iterators
 
2152 + 
        referring to contained elements are invalidated.
 
2153 + 
        Any past-the-end iterators are also invalidated.
 
2154 +
 
2155 + 
        @return `*this`
 
2156 +
 
2157 + 
        @param pos The index to replace at.
 
2158 +
 
2159 + 
        @param count The number of characters to replace.
 
2160 +
 
2161 + 
        @param count2 The number of characters to
 
2162 + 
        replace with.
1555 - 
        @param count2 The number of characters to replace with.
 
1556  
2163  
1557   
        @param ch The character to replace with.
2164   
        @param ch The character to replace with.
1558 - 
        @param pos
2165 +
1559 - 
        @param count
2166 + 
        @throw `boost::system::system_error` `size() + (count2 - rcount) > max_size()`.
 
2167 + 
        @throw `boost::system::system_error` `pos > size()`.
1560   
    */
2168   
    */
1561   
    BOOST_JSON_DECL
2169   
    BOOST_JSON_DECL
1562   
    string&
2170   
    string&
1563   
    replace(
2171   
    replace(
1564   
        std::size_t pos,
2172   
        std::size_t pos,
1565   
        std::size_t count,
2173   
        std::size_t count,
1566   
        std::size_t count2,
2174   
        std::size_t count2,
1567   
        char ch);
2175   
        char ch);
1568  
2176  
1569 - 
    /** Overload
2177 + 
    /** Replace a range with copies of a character.
1570  
2178  
1571 - 
        @param first
2179 + 
        Replaces the characters in the range
1572 - 
        @param last
2180 + 
        `{first, last)` with `count` copies of `ch`.
1573 - 
        @param count2
2181 +
1574 - 
        @param ch
2182 + 
        @par Precondition
 
2183 +
 
2184 + 
        `{first, last)` is a valid range.
 
2185 +
 
2186 + 
        @par Exception Safety
 
2187 +
 
2188 + 
        Strong guarantee.
 
2189 +
 
2190 + 
        @note All references, pointers, or iterators
 
2191 + 
        referring to contained elements are invalidated.
 
2192 + 
        Any past-the-end iterators are also invalidated.
 
2193 +
 
2194 + 
        @return `*this`
 
2195 +
 
2196 + 
        @param first An iterator referring to the first
 
2197 + 
        character to replace.
 
2198 +
 
2199 + 
        @param last An iterator one past the end of
 
2200 + 
        the last character to replace.
 
2201 +
 
2202 + 
        @param count The number of characters to
 
2203 + 
        replace with.
 
2204 +
 
2205 + 
        @param ch The character to replace with.
 
2206 +
 
2207 + 
        @throw `boost::system::system_error` `size() + (count - std::distance(first, last)) > max_size()`.
1575   
    */
2208   
    */
1576   
    string&
2209   
    string&
1577   
    replace(
2210   
    replace(
1578   
        const_iterator first,
2211   
        const_iterator first,
1579   
        const_iterator last,
2212   
        const_iterator last,
1580 - 
        std::size_t count2,
2213 + 
        std::size_t count,
1581   
        char ch)
2214   
        char ch)
1582   
    {
2215   
    {
1583 - 
        return replace(first - begin(), last - first, count2, ch);
2216 + 
        return replace(first - begin(), last - first, count, ch);
1584 - 
    /// @}
 
1585   
    }
2217   
    }
1586  
2218  
1587   
    //------------------------------------------------------
2219   
    //------------------------------------------------------
1588  
2220  
1589   
    /** Return a view.
2221   
    /** Return a view.
1590  
2222  
1591 - 
        @li **(1)** equivalent to `subview().substr(pos, count)`.
2223 + 
        Returns a view of a substring.
1592 - 
        @li **(2)** equivalent to `string_view(data(), size())`.
 
1593  
2224  
1594   
        @par Exception Safety
2225   
        @par Exception Safety
 
2226 +
1595   
        Strong guarantee.
2227   
        Strong guarantee.
1596  
2228  
1597 - 
        @param pos The index of the first character of the substring.
2229 + 
        @return `this->subview().substr(pos, count)`
 
2230 +
 
2231 + 
        @param pos The index to being the substring at.
 
2232 + 
        The default argument for this parameter is `0`.
 
2233 +
1598   
        @param count The length of the substring.
2234   
        @param count The length of the substring.
 
2235 + 
        The default argument for this parameter
 
2236 + 
        is @ref npos.
1599  
2237  
1600 - 
        @throw boost::system::system_error `pos > ` @ref size().
2238 + 
        @throw `boost::system::system_error` `pos > size()`.
1601   
    */
2239   
    */
1602   
    string_view
2240   
    string_view
1603   
    subview(
2241   
    subview(
1604 - 
        std::size_t pos,
2242 + 
        std::size_t pos
1605 - 
        std::size_t count = npos) const
2243 + 
        ,std::size_t count = npos) const
1606   
    {
2244   
    {
1607   
        return subview().substr(pos, count);
2245   
        return subview().substr(pos, count);
1608   
    }
2246   
    }
1609  
2247  
1610 - 
    /// Overload
2248 + 
    /** Return a view.
 
2249 +
 
2250 + 
        Returns a view of the whole string.
 
2251 +
 
2252 + 
        @par Exception Safety
 
2253 + 
        No-throw guarantee.
 
2254 +
 
2255 + 
        @return `string_view(this->data(), this->size())`.
 
2256 + 
    */
1611   
    string_view
2257   
    string_view
1612   
    subview() const noexcept
2258   
    subview() const noexcept
1613   
    {
2259   
    {
1614   
        return string_view( data(), size() );
2260   
        return string_view( data(), size() );
1615   
    }
2261   
    }
1616  
2262  
1617   
    //------------------------------------------------------
2263   
    //------------------------------------------------------
1618  
2264  
1619   
    /** Copy a substring to another string.
2265   
    /** Copy a substring to another string.
1620  
2266  
1621 - 
        Copies `std::min(count, size() - pos)` characters starting at index
2267 + 
        Copies `std::min(count, size() - pos)` characters
1622 - 
        `pos` to the string pointed to by `dest`.
2268 + 
        starting at index `pos` to the string pointed
 
2269 + 
        to by `dest`.
1623  
2270  
1624 - 
        @attention This function doesn't put the null terminator after the
2271 + 
        @note The resulting string is not null terminated.
1625 - 
        copied characters.
 
1626  
2272  
1627   
        @return The number of characters copied.
2273   
        @return The number of characters copied.
1628  
2274  
1629   
        @param count The number of characters to copy.
2275   
        @param count The number of characters to copy.
1630  
2276  
1631   
        @param dest The string to copy to.
2277   
        @param dest The string to copy to.
1632  
2278  
1633 - 
        @param pos The index to begin copying from.
2279 + 
        @param pos The index to begin copying from. The
 
2280 + 
        default argument for this parameter is `0`.
1634  
2281  
1635 - 
        @throw boost::system::system_error `pos >` @ref max_size().
2282 + 
        @throw `boost::system::system_error` `pos > max_size()`.
1636   
    */
2283   
    */
1637   
    std::size_t
2284   
    std::size_t
1638   
    copy(
2285   
    copy(
1639   
        char* dest,
2286   
        char* dest,
1640   
        std::size_t count,
2287   
        std::size_t count,
1641   
        std::size_t pos = 0) const
2288   
        std::size_t pos = 0) const
1642   
    {
2289   
    {
1643   
        return subview().copy(dest, count, pos);
2290   
        return subview().copy(dest, count, pos);
1644   
    }
2291   
    }
1645  
2292  
1646   
    //------------------------------------------------------
2293   
    //------------------------------------------------------
1647  
2294  
1648   
    /** Change the size of the string.
2295   
    /** Change the size of the string.
1649  
2296  
1650 - 
        Resizes the string to contain `count` characters. If
2297 + 
        Resizes the string to contain `count` characters.
1651 - 
        `count > `@ref size(), **(2)** appends copies of `ch` and **(1)**
2298 + 
        If `count > size()`, characters with the value `0`
1652 - 
        appends ``'\0'``. Otherwise, `size()` is reduced to `count`.
2299 + 
        are appended. Otherwise, `size()` is reduced
 
2300 + 
        to `count`.
1653  
2301  
1654   
        @param count The size to resize the string to.
2302   
        @param count The size to resize the string to.
1655  
2303  
1656 - 
        @throw boost::system::system_error `count > `@ref max_size().
2304 + 
        @throw `boost::system::system_error` `count > max_size()`.
1657 -
 
1658 - 
        @{
 
1659   
    */
2305   
    */
1660   
    void
2306   
    void
1661   
    resize(std::size_t count)
2307   
    resize(std::size_t count)
1662   
    {
2308   
    {
1663   
        resize(count, 0);
2309   
        resize(count, 0);
1664   
    }
2310   
    }
1665  
2311  
1666 - 
    /** Overload
2312 + 
    /** Change the size of the string.
1667  
2313  
1668 - 
        @param count
2314 + 
        Resizes the string to contain `count` characters.
1669 - 
        @param ch The characters to append if the size increases.
2315 + 
        If `count > size()`, copies of `ch` are
 
2316 + 
        appended. Otherwise, `size()` is reduced
 
2317 + 
        to `count`.
 
2318 +
 
2319 + 
        @param count The size to resize the string to.
 
2320 +
 
2321 + 
        @param ch The characters to append if the size
 
2322 + 
        increases.
 
2323 +
 
2324 + 
        @throw `boost::system::system_error` `count > max_size()`.
1670   
    */
2325   
    */
1671   
    BOOST_JSON_DECL
2326   
    BOOST_JSON_DECL
1672   
    void
2327   
    void
1673 - 
    /// @}
 
1674   
    resize(std::size_t count, char ch);
2328   
    resize(std::size_t count, char ch);
1675  
2329  
1676   
    /** Increase size without changing capacity.
2330   
    /** Increase size without changing capacity.
1677  
2331  
1678 - 
        This increases the size of the string by `n` characters, adjusting the
2332 + 
        This increases the size of the string by `n`
1679 - 
        position of the terminating null character for the new size. The new
2333 + 
        characters, adjusting the position of the
1680 - 
        characters remain uninitialized. This function may be used to append
2334 + 
        terminating null for the new size. The new
1681 - 
        characters directly into the storage between @ref end() and @ref data()
2335 + 
        characters remain uninitialized. This function
1682 - 
        ` + ` @ref capacity().
2336 + 
        may be used to append characters directly into
 
2337 + 
        the storage between `end()` and
 
2338 + 
        `data() + capacity()`.
 
2339 +
 
2340 + 
        @par Precondition
1683 - 
        @pre
 
1684  
2341  
1685   
        @code
2342   
        @code
1686   
        count <= capacity() - size()
2343   
        count <= capacity() - size()
1687   
        @endcode
2344   
        @endcode
1688  
2345  
1689   
        @param n The amount to increase the size by.
2346   
        @param n The amount to increase the size by.
1690   
    */
2347   
    */
1691   
    void
2348   
    void
1692   
    grow(std::size_t n) noexcept
2349   
    grow(std::size_t n) noexcept
1693   
    {
2350   
    {
1694   
        BOOST_ASSERT(
2351   
        BOOST_ASSERT(
1695   
            n <= impl_.capacity() - impl_.size());
2352   
            n <= impl_.capacity() - impl_.size());
1696   
        impl_.term(impl_.size() + n);
2353   
        impl_.term(impl_.size() + n);
1697   
    }
2354   
    }
1698  
2355  
 
2356 + 
    //------------------------------------------------------
 
2357 +
1699   
    /** Swap the contents.
2358   
    /** Swap the contents.
1700  
2359  
1701   
        Exchanges the contents of this string with another string. Ownership of
2360   
        Exchanges the contents of this string with another string. Ownership of
1702 - 
        the respective @ref boost::container::pmr::memory_resource objects is
2361 + 
        the respective `boost::container::pmr::memory_resource` objects is not
1703 - 
        not transferred.
2362 + 
        transferred.
1704  
2363  
1705   
        @li If `&other == this`, do nothing. Otherwise,
2364   
        @li If `&other == this`, do nothing. Otherwise,
1706 - 
        @li if `*other.storage() == *this->storage()`, ownership of the
2365 +
1707 - 
            underlying memory is swapped in constant time, with no possibility
2366 + 
        @li if `*other.storage() == *this->storage()`,
1708 - 
            of exceptions. All iterators and references remain valid.
2367 + 
        ownership of the underlying memory is swapped in
1709 - 
            Otherwise,
2368 + 
        constant time, with no possibility of exceptions.
1710 - 
        @li the contents are logically swapped by making copies, which can
2369 + 
        All iterators and references remain valid. Otherwise,
1711 - 
            throw. In this case all iterators and references are invalidated.
2370 +
 
2371 + 
        @li the contents are logically swapped by making copies,
 
2372 + 
        which can throw. In this case all iterators and
 
2373 + 
        references are invalidated.
1712  
2374  
1713   
        @par Complexity
2375   
        @par Complexity
1714 - 
        Constant or linear in @ref size() `+ other.size()`.
2376 +
 
2377 + 
        Constant or linear in @ref size() plus
 
2378 + 
        `other.size()`.
1715  
2379  
1716   
        @par Exception Safety
2380   
        @par Exception Safety
1717 - 
        Strong guarantee. Calls to `memory_resource::allocate` may throw.
2381 +
 
2382 + 
        Strong guarantee.
 
2383 + 
        Calls to `memory_resource::allocate` may throw.
1718   
    */
2384   
    */
1719   
    BOOST_JSON_DECL
2385   
    BOOST_JSON_DECL
1720   
    void
2386   
    void
1721   
    swap(string& other);
2387   
    swap(string& other);
1722  
2388  
1723   
    /** Exchange the given values.
2389   
    /** Exchange the given values.
1724  
2390  
1725   
        Exchanges the contents of the string `lhs` with another string `rhs`.
2391   
        Exchanges the contents of the string `lhs` with another string `rhs`.
1726 - 
        Ownership of the respective @ref boost::container::pmr::memory_resource
2392 + 
        Ownership of the respective `boost::container::pmr::memory_resource`
1727   
        objects is not transferred.
2393   
        objects is not transferred.
1728  
2394  
1729   
        @li If `&lhs == &rhs`, do nothing. Otherwise,
2395   
        @li If `&lhs == &rhs`, do nothing. Otherwise,
1730 - 
        @li if `*lhs.storage() == *rhs.storage()`, ownership of the underlying
2396 +
1731 - 
            memory is swapped in constant time, with no possibility of
2397 + 
        @li if `*lhs.storage() == *rhs.storage()`,
1732 - 
            exceptions. All iterators and references remain valid. Otherwise,
2398 + 
        ownership of the underlying memory is swapped in
1733 - 
        @li the contents are logically swapped by making a copy, which can
2399 + 
        constant time, with no possibility of exceptions.
1734 - 
            throw. In this case all iterators and references are invalidated.
2400 + 
        All iterators and references remain valid. Otherwise,
 
2401 +
 
2402 + 
        @li the contents are logically swapped by making a copy,
 
2403 + 
        which can throw. In this case all iterators and
 
2404 + 
        references are invalidated.
1735  
2405  
1736   
        @par Effects
2406   
        @par Effects
1737   
        @code
2407   
        @code
1738   
        lhs.swap( rhs );
2408   
        lhs.swap( rhs );
1739   
        @endcode
2409   
        @endcode
1740  
2410  
1741   
        @par Complexity
2411   
        @par Complexity
1742   
        Constant or linear in `lhs.size() + rhs.size()`.
2412   
        Constant or linear in `lhs.size() + rhs.size()`.
1743  
2413  
1744   
        @par Exception Safety
2414   
        @par Exception Safety
1745   
        Strong guarantee.
2415   
        Strong guarantee.
1746   
        Calls to `memory_resource::allocate` may throw.
2416   
        Calls to `memory_resource::allocate` may throw.
1747  
2417  
1748   
        @param lhs The string to exchange.
2418   
        @param lhs The string to exchange.
 
2419 +
1749   
        @param rhs The string to exchange.
2420   
        @param rhs The string to exchange.
1750  
2421  
1751   
        @see @ref string::swap
2422   
        @see @ref string::swap
1752   
    */
2423   
    */
1753   
    friend
2424   
    friend
1754   
    void
2425   
    void
1755   
    swap(string& lhs, string& rhs)
2426   
    swap(string& lhs, string& rhs)
1756   
    {
2427   
    {
1757   
        lhs.swap(rhs);
2428   
        lhs.swap(rhs);
1758   
    }
2429   
    }
1759   
    //------------------------------------------------------
2430   
    //------------------------------------------------------
1760   
    //
2431   
    //
1761   
    // Search
2432   
    // Search
1762   
    //
2433   
    //
1763   
    //------------------------------------------------------
2434   
    //------------------------------------------------------
1764  
2435  
1765 - 
    /** Find the first occurrence of characters within the string.
2436 + 
    /** Find the first occurrence of a string within the string.
1766 -
 
1767 - 
        Search from `pos` onward for the first substring that is equal to the
 
1768 - 
        first argument.
 
1769  
2437  
1770 - 
        @li **(1)** searches for the presense of the substring equal to `sv`.
2438 + 
        Returns the lowest index `idx` greater than or equal
1771 - 
        @li **(2)** searches for the presense of the substring consisting of
2439 + 
        to `pos` where each element of `sv`  is equal to
1772 - 
            the character `ch`.
2440 + 
        that of `{begin() + idx, begin() + idx + sv.size())`
 
2441 + 
        if one exists, and @ref npos otherwise.
1773  
2442  
1774 - 
        Linear in @ref size().
 
1775   
        @par Complexity
2443   
        @par Complexity
1776  
2444  
1777 - 
        @par Exception Safety
2445 + 
        Linear.
1778 - 
        No-throw guarantee.
 
1779  
2446  
1780 - 
        @return The index of the first character of the found substring, or
2447 + 
        @return The first occurrence of `sv` within the
1781 - 
        @ref npos if none was found.
2448 + 
        string starting at the index `pos`, or @ref npos
 
2449 + 
        if none exists.
1782  
2450  
1783 - 
        @param pos The index to start searching at.
 
1784   
        @param sv The `string_view` to search for.
2451   
        @param sv The `string_view` to search for.
1785  
2452  
1786 - 
        @{
2453 + 
        @param pos The index to start searching at.
 
2454 + 
        The default argument for this parameter is `0`.
1787   
    */
2455   
    */
1788   
    std::size_t
2456   
    std::size_t
1789   
    find(
2457   
    find(
1790   
        string_view sv,
2458   
        string_view sv,
1791   
        std::size_t pos = 0) const noexcept
2459   
        std::size_t pos = 0) const noexcept
1792   
    {
2460   
    {
1793   
        return subview().find(sv, pos);
2461   
        return subview().find(sv, pos);
1794   
    }
2462   
    }
1795  
2463  
1796 - 
    /** Overload
2464 + 
    /** Find the first occurrence of a character within the string.
 
2465 +
 
2466 + 
        Returns the index corrosponding to the first
 
2467 + 
        occurrence of `ch` within `{begin() + pos, end())`
 
2468 + 
        if it exists, and @ref npos otherwise.
 
2469 +
 
2470 + 
        @par Complexity
 
2471 +
 
2472 + 
        Linear.
 
2473 +
 
2474 + 
        @return The first occurrence of `ch` within the
 
2475 + 
        string starting at the index `pos`, or @ref npos
 
2476 + 
        if none exists.
1797  
2477  
1798   
        @param ch The character to search for.
2478   
        @param ch The character to search for.
1799 - 
        @param pos
2479 +
 
2480 + 
        @param pos The index to start searching at.
 
2481 + 
        The default argument for this parameter is `0`.
1800   
    */
2482   
    */
1801   
    std::size_t
2483   
    std::size_t
1802   
    find(
2484   
    find(
1803   
        char ch,
2485   
        char ch,
1804   
        std::size_t pos = 0) const noexcept
2486   
        std::size_t pos = 0) const noexcept
1805   
    {
2487   
    {
1806   
        return subview().find(ch, pos);
2488   
        return subview().find(ch, pos);
1807 - 
    /// @}
 
1808   
    }
2489   
    }
1809  
2490  
1810 - 
    /** Find the last occurrence of a string within the string.
2491 + 
    //------------------------------------------------------
1811  
2492  
1812 - 
        @li **(1)** searches for the last substring equal to `sv`.
2493 + 
    /** Find the last occurrence of a string within the string.
1813 - 
        @li **(2)** searches for the last occurrence of `ch`.
 
1814  
2494  
1815 - 
        Both functions search for substrings fully contained within `[begin(),
2495 + 
        Returns the highest index `idx` less than or equal
1816 - 
        begin() + pos)`.
2496 + 
        to `pos` where each element of `sv` is equal to that
 
2497 + 
        of `{begin() + idx, begin() + idx + sv.size())`
 
2498 + 
        if one exists, and @ref npos otherwise.
1817  
2499  
1818   
        @par Complexity
2500   
        @par Complexity
 
2501 +
1819   
        Linear.
2502   
        Linear.
1820  
2503  
1821 - 
        @return Index of the first character of the found substring or
2504 + 
        @return The last occurrence of `sv` within the
1822 - 
                @ref npos if none was found.
2505 + 
        string starting before or at the index `pos`,
 
2506 + 
        or @ref npos if none exists.
1823  
2507  
1824 - 
        @param sv The string to search for.
2508 + 
        @param sv The `string_view` to search for.
1825 - 
        @param pos The index to start searching at. By default searches from
 
1826 - 
               the end of the string.
 
1827  
2509  
1828 - 
        @{
2510 + 
        @param pos The index to start searching at.
 
2511 + 
        The default argument for this parameter
 
2512 + 
        is @ref npos.
1829   
    */
2513   
    */
1830   
    std::size_t
2514   
    std::size_t
1831   
    rfind(
2515   
    rfind(
1832   
        string_view sv,
2516   
        string_view sv,
1833   
        std::size_t pos = npos) const noexcept
2517   
        std::size_t pos = npos) const noexcept
1834   
    {
2518   
    {
1835   
        return subview().rfind(sv, pos);
2519   
        return subview().rfind(sv, pos);
1836   
    }
2520   
    }
1837  
2521  
1838 - 
    /** Overload
2522 + 
    /** Find the last occurrence of a character within the string.
 
2523 +
 
2524 + 
        Returns index corrosponding to the last occurrence
 
2525 + 
        of `ch` within `{begin(), begin() + pos}` if it
 
2526 + 
        exists, and @ref npos otherwise.
 
2527 +
 
2528 + 
        @par Complexity
 
2529 +
 
2530 + 
        Linear.
 
2531 +
 
2532 + 
        @return The last occurrence of `ch` within the
 
2533 + 
        string starting before or at the index `pos`,
 
2534 + 
        or @ref npos if none exists.
1839  
2535  
1840   
        @param ch The character to search for.
2536   
        @param ch The character to search for.
1841 - 
        @param pos
2537 +
 
2538 + 
        @param pos The index to stop searching at.
 
2539 + 
        The default argument for this parameter
 
2540 + 
        is @ref npos.
1842   
    */
2541   
    */
1843   
    std::size_t
2542   
    std::size_t
1844   
    rfind(
2543   
    rfind(
1845   
        char ch,
2544   
        char ch,
1846   
        std::size_t pos = npos) const noexcept
2545   
        std::size_t pos = npos) const noexcept
1847   
    {
2546   
    {
1848   
        return subview().rfind(ch, pos);
2547   
        return subview().rfind(ch, pos);
1849 - 
    /// @}
 
1850   
    }
2548   
    }
1851  
2549  
1852   
    //------------------------------------------------------
2550   
    //------------------------------------------------------
1853  
2551  
1854 - 
    /** Find the first character present in the specified string.
2552 + 
    /** Find the first occurrence of any of the characters within the string.
1855  
2553  
1856 - 
        Search from `pos` onward for the first character in this string that is
2554 + 
        Returns the index corrosponding to the first
1857 - 
        equal to any of the characters of `sv`.
2555 + 
        occurrence of any of the characters of `sv`
 
2556 + 
        within `{begin() + pos, end())` if it exists,
 
2557 + 
        and @ref npos otherwise.
1858  
2558  
1859 - 
        Linear in @ref size() `+ sv.size()`.
 
1860   
        @par Complexity
2559   
        @par Complexity
1861  
2560  
1862 - 
        @par Exception Safety
2561 + 
        Linear.
1863 - 
        No-throw guarantee.
 
1864  
2562  
1865 - 
        @return The index of the found character, or @ref npos if none exists.
2563 + 
        @return The first occurrence of any of the
 
2564 + 
        characters within `sv` within the string
 
2565 + 
        starting at the index `pos`, or @ref npos
 
2566 + 
        if none exists.
1866  
2567  
1867   
        @param sv The characters to search for.
2568   
        @param sv The characters to search for.
 
2569 +
1868   
        @param pos The index to start searching at.
2570   
        @param pos The index to start searching at.
 
2571 + 
        The default argument for this parameter is `0`.
1869   
    */
2572   
    */
1870   
    std::size_t
2573   
    std::size_t
1871   
    find_first_of(
2574   
    find_first_of(
1872   
        string_view sv,
2575   
        string_view sv,
1873   
        std::size_t pos = 0) const noexcept
2576   
        std::size_t pos = 0) const noexcept
1874   
    {
2577   
    {
1875   
        return subview().find_first_of(sv, pos);
2578   
        return subview().find_first_of(sv, pos);
1876   
    }
2579   
    }
1877  
2580  
1878 - 
    /** Find the first character missing from the specified string.
2581 + 
    //------------------------------------------------------
1879  
2582  
1880 - 
        Search from `pos` onward for the first character in this string that is
2583 + 
    /** Find the first occurrence of any of the characters not within the string.
1881 - 
        not equal to any of the characters in the string provided as the first
 
1882 - 
        argument.
 
1883  
2584  
1884 - 
        @li **(1)** compares with the characters in `sv`.
2585 + 
        Returns the index corrosponding to the first
1885 - 
        @li **(2)** compares with the character `ch`.
2586 + 
        character of `{begin() + pos, end())` that is
 
2587 + 
        not within `sv` if it exists, and @ref npos
 
2588 + 
        otherwise.
1886  
2589  
1887 - 
        @li **(1)** linear in @ref size() `+ sv.size()`.
 
1888 - 
        @li **(2)** linear in @ref size().
 
1889   
        @par Complexity
2590   
        @par Complexity
1890  
2591  
1891 - 
        @par Exception Safety
2592 + 
        Linear.
1892 - 
        No-throw guarantee.
 
1893  
2593  
1894 - 
        @return The index of the found character, or @ref npos if none exists.
2594 + 
        @return The first occurrence of a character that
 
2595 + 
        is not within `sv` within the string starting at
 
2596 + 
        the index `pos`, or @ref npos if none exists.
1895  
2597  
1896 - 
        @param sv The characters to compare with.
2598 + 
        @param sv The characters to ignore.
1897 - 
        @param pos The index to start searching at.
 
1898  
2599  
1899 - 
        @{
2600 + 
        @param pos The index to start searching at.
 
2601 + 
        The default argument for this parameter is `0`.
1900   
    */
2602   
    */
1901   
    std::size_t
2603   
    std::size_t
1902   
    find_first_not_of(
2604   
    find_first_not_of(
1903   
        string_view sv,
2605   
        string_view sv,
1904   
        std::size_t pos = 0) const noexcept
2606   
        std::size_t pos = 0) const noexcept
1905   
    {
2607   
    {
1906   
        return subview().find_first_not_of(sv, pos);
2608   
        return subview().find_first_not_of(sv, pos);
1907   
    }
2609   
    }
1908  
2610  
1909 - 
    /** Overload
2611 + 
    /** Find the first occurrence of a character not equal to `ch`.
1910 - 
        @param ch The character to compare with.
2612 +
1911 - 
        @param pos
2613 + 
        Returns the index corrosponding to the first
 
2614 + 
        character of `{begin() + pos, end())` that is
 
2615 + 
        not equal to `ch` if it exists, and
 
2616 + 
        @ref npos otherwise.
 
2617 +
 
2618 + 
        @par Complexity
 
2619 +
 
2620 + 
        Linear.
 
2621 +
 
2622 + 
        @return The first occurrence of a character that
 
2623 + 
        is not equal to `ch`, or @ref npos if none exists.
 
2624 +
 
2625 + 
        @param ch The character to ignore.
 
2626 +
 
2627 + 
        @param pos The index to start searching at.
 
2628 + 
        The default argument for this parameter is `0`.
1912   
    */
2629   
    */
1913   
    std::size_t
2630   
    std::size_t
1914   
    find_first_not_of(
2631   
    find_first_not_of(
1915   
        char ch,
2632   
        char ch,
1916   
        std::size_t pos = 0) const noexcept
2633   
        std::size_t pos = 0) const noexcept
1917   
    {
2634   
    {
1918   
        return subview().find_first_not_of(ch, pos);
2635   
        return subview().find_first_not_of(ch, pos);
1919 - 
    /// @}
 
1920   
    }
2636   
    }
1921  
2637  
1922 - 
    /** Find the last character present in the specified string.
2638 + 
    //------------------------------------------------------
1923  
2639  
1924 - 
        Search from `pos` backwards for the first character in this string that
2640 + 
    /** Find the last occurrence of any of the characters within the string.
1925 - 
        is equal to any of the characters of `sv`. If `pos` is equal to @ref
2641 +
1926 - 
        npos (the default), search from the last character.
2642 + 
        Returns the index corrosponding to the last
 
2643 + 
        occurrence of any of the characters of `sv` within
 
2644 + 
        `{begin(), begin() + pos}` if it exists,
 
2645 + 
        and @ref npos otherwise.
1927  
2646  
1928 - 
        Linear in @ref size() `+ sv.size()`.
 
1929   
        @par Complexity
2647   
        @par Complexity
1930  
2648  
1931 - 
        @par Exception Safety
2649 + 
        Linear.
1932 - 
        No-throw guarantee.
 
1933  
2650  
1934 - 
        @return The index of the found character, or @ref npos if none exists.
2651 + 
        @return The last occurrence of any of the
 
2652 + 
        characters within `sv` within the string starting
 
2653 + 
        before or at the index `pos`, or @ref npos if
 
2654 + 
        none exists.
1935  
2655  
1936   
        @param sv The characters to search for.
2656   
        @param sv The characters to search for.
1937 - 
        @param pos The index to start searching at.
2657 +
 
2658 + 
        @param pos The index to stop searching at.
 
2659 + 
        The default argument for this parameter
 
2660 + 
        is @ref npos.
1938   
    */
2661   
    */
1939   
    std::size_t
2662   
    std::size_t
1940   
    find_last_of(
2663   
    find_last_of(
1941   
        string_view sv,
2664   
        string_view sv,
1942   
        std::size_t pos = npos) const noexcept
2665   
        std::size_t pos = npos) const noexcept
1943   
    {
2666   
    {
1944   
        return subview().find_last_of(sv, pos);
2667   
        return subview().find_last_of(sv, pos);
1945   
    }
2668   
    }
1946  
2669  
1947 - 
    /** Find the last character missing from the specified string.
2670 + 
    //------------------------------------------------------
1948 -
 
1949  
2671  
1950 - 
        Search from `pos` backwards for the first character in this string that
2672 + 
    /** Find the last occurrence of a character not within the string.
1951 - 
        is not equal to any of the characters in the string provided as the
 
1952 - 
        first argument. If `pos` is equal to @ref npos (the default), search
 
1953 - 
        from the last character.
 
1954  
2673  
1955 - 
        @li **(1)** compares with the characters in `sv`.
2674 + 
        Returns the index corrosponding to the last
1956 - 
        @li **(2)** compares with the character `ch`.
2675 + 
        character of `{begin(), begin() + pos}` that is not
 
2676 + 
        within `sv` if it exists, and @ref npos otherwise.
1957  
2677  
1958 - 
        @li **(1)** linear in @ref size() `+ sv.size()`.
 
1959 - 
        @li **(2)** linear in @ref size().
 
1960   
        @par Complexity
2678   
        @par Complexity
1961  
2679  
1962 - 
        @par Exception Safety
2680 + 
        Linear.
1963 - 
        No-throw guarantee.
 
1964  
2681  
1965 - 
        @return The index of the found character, or @ref npos if none exists.
2682 + 
        @return The last occurrence of a character that is
 
2683 + 
        not within `sv` within the string before or at the
 
2684 + 
        index `pos`, or @ref npos if none exists.
1966  
2685  
1967 - 
        @param sv The characters to compare with.
2686 + 
        @param sv The characters to ignore.
1968 - 
        @param pos The index to start searching at.
 
1969  
2687  
1970 - 
        @{
2688 + 
        @param pos The index to stop searching at.
 
2689 + 
        The default argument for this parameter
 
2690 + 
        is @ref npos.
1971   
    */
2691   
    */
1972   
    std::size_t
2692   
    std::size_t
1973   
    find_last_not_of(
2693   
    find_last_not_of(
1974   
        string_view sv,
2694   
        string_view sv,
1975   
        std::size_t pos = npos) const noexcept
2695   
        std::size_t pos = npos) const noexcept
1976   
    {
2696   
    {
1977   
        return subview().find_last_not_of(sv, pos);
2697   
        return subview().find_last_not_of(sv, pos);
1978   
    }
2698   
    }
1979  
2699  
1980 - 
    /** Overload
2700 + 
    /** Find the last occurrence of a character not equal to `ch`.
1981 - 
        @param ch The character to compare with.
2701 +
1982 - 
        @param pos
2702 + 
        Returns the index corrosponding to the last
 
2703 + 
        character of `{begin(), begin() + pos}` that is
 
2704 + 
        not equal to `ch` if it exists, and @ref npos
 
2705 + 
        otherwise.
 
2706 +
 
2707 + 
        @par Complexity
 
2708 +
 
2709 + 
        Linear.
 
2710 +
 
2711 + 
        @return The last occurrence of a character that
 
2712 + 
        is not equal to `ch` before or at the index `pos`,
 
2713 + 
        or @ref npos if none exists.
 
2714 +
 
2715 + 
        @param ch The character to ignore.
 
2716 +
 
2717 + 
        @param pos The index to start searching at.
 
2718 + 
        The default argument for this parameter
 
2719 + 
        is @ref npos.
1983   
    */
2720   
    */
1984   
    std::size_t
2721   
    std::size_t
1985   
    find_last_not_of(
2722   
    find_last_not_of(
1986   
        char ch,
2723   
        char ch,
1987   
        std::size_t pos = npos) const noexcept
2724   
        std::size_t pos = npos) const noexcept
1988   
    {
2725   
    {
1989   
        return subview().find_last_not_of(ch, pos);
2726   
        return subview().find_last_not_of(ch, pos);
1990 - 
    /// @}
 
1991   
    }
2727   
    }
1992  
2728  
1993 - 
    /** Serialize a @ref string to an output stream.
2729 + 
    /** Serialize @ref string to an output stream.
1994  
2730  
1995   
        This function serializes a `string` as JSON into the output stream.
2731   
        This function serializes a `string` as JSON into the output stream.
1996  
2732  
1997   
        @return Reference to `os`.
2733   
        @return Reference to `os`.
1998  
2734  
1999   
        @par Complexity
2735   
        @par Complexity
2000 - 
        Linear in the `str.size()`.
2736 + 
        Constant or linear in the size of `str`.
2001  
2737  
2002   
        @par Exception Safety
2738   
        @par Exception Safety
2003 - 
        Strong guarantee. Calls to `memory_resource::allocate` may throw.
2739 + 
        Strong guarantee.
 
2740 + 
        Calls to `memory_resource::allocate` may throw.
2004  
2741  
2005   
        @param os The output stream to serialize to.
2742   
        @param os The output stream to serialize to.
 
2743 +
2006   
        @param str The value to serialize.
2744   
        @param str The value to serialize.
2007   
    */
2745   
    */
2008   
    BOOST_JSON_DECL
2746   
    BOOST_JSON_DECL
2009   
    friend
2747   
    friend
2010   
    std::ostream&
2748   
    std::ostream&
2011   
    operator<<(
2749   
    operator<<(
2012   
        std::ostream& os,
2750   
        std::ostream& os,
2013   
        string const& str);
2751   
        string const& str);
2014  
2752  
2015   
private:
2753   
private:
2016   
    class undo;
2754   
    class undo;
2017  
2755  
2018   
    template<class It>
2756   
    template<class It>
2019   
    using iter_cat = typename
2757   
    using iter_cat = typename
2020   
        std::iterator_traits<It>::iterator_category;
2758   
        std::iterator_traits<It>::iterator_category;
2021  
2759  
2022   
    template<class InputIt>
2760   
    template<class InputIt>
2023   
    void
2761   
    void
2024   
    assign(InputIt first, InputIt last,
2762   
    assign(InputIt first, InputIt last,
2025   
        std::random_access_iterator_tag);
2763   
        std::random_access_iterator_tag);
2026  
2764  
2027   
    template<class InputIt>
2765   
    template<class InputIt>
2028   
    void
2766   
    void
2029   
    assign(InputIt first, InputIt last,
2767   
    assign(InputIt first, InputIt last,
2030   
        std::input_iterator_tag);
2768   
        std::input_iterator_tag);
2031  
2769  
2032   
    template<class InputIt>
2770   
    template<class InputIt>
2033   
    void
2771   
    void
2034   
    append(InputIt first, InputIt last,
2772   
    append(InputIt first, InputIt last,
2035   
        std::random_access_iterator_tag);
2773   
        std::random_access_iterator_tag);
2036  
2774  
2037   
    template<class InputIt>
2775   
    template<class InputIt>
2038   
    void
2776   
    void
2039   
    append(InputIt first, InputIt last,
2777   
    append(InputIt first, InputIt last,
2040   
        std::input_iterator_tag);
2778   
        std::input_iterator_tag);
2041  
2779  
2042   
    BOOST_JSON_DECL
2780   
    BOOST_JSON_DECL
2043   
    void
2781   
    void
2044   
    reserve_impl(std::size_t new_capacity);
2782   
    reserve_impl(std::size_t new_capacity);
2045   
};
2783   
};
2046  
2784  
2047   
//----------------------------------------------------------
2785   
//----------------------------------------------------------
2048  
2786  
2049   
namespace detail
2787   
namespace detail
2050   
{
2788   
{
2051  
2789  
2052   
template <>
2790   
template <>
2053   
inline
2791   
inline
2054   
string_view
2792   
string_view
2055   
to_string_view<string>(string const& s) noexcept
2793   
to_string_view<string>(string const& s) noexcept
2056   
{
2794   
{
2057   
    return s.subview();
2795   
    return s.subview();
2058   
}
2796   
}
2059  
2797  
2060   
} // namespace detail
2798   
} // namespace detail
2061  
2799  
2062  
2800  
2063 - 
/** Checks if lhs equals rhs.
2801 + 
/** Return true if lhs equals rhs.
2064 -
 
2065 - 
    @li **(1)** A lexicographical comparison is used.
 
2066 - 
    @li **(2)** equivalent to `lhs.get() == rhs.get()`.
 
2067 -
 
2068 - 
    @par Complexity
 
2069 - 
    @li **(1)** linear in `lhs.size() + rhs.size()`.
 
2070 - 
    @li **(2)** constant.
 
2071  
2802  
2072 - 
    @par Exception Safety
2803 + 
    A lexicographical comparison is used.
2073 - 
    No-throw guarantee.
 
2074   
*/
2804   
*/
2075   
#ifdef BOOST_JSON_DOCS
2805   
#ifdef BOOST_JSON_DOCS
2076   
bool
2806   
bool
2077   
operator==(string const& lhs, string const& rhs) noexcept
2807   
operator==(string const& lhs, string const& rhs) noexcept
2078   
#else
2808   
#else
2079   
template<class T, class U>
2809   
template<class T, class U>
2080   
detail::string_comp_op_requirement<T, U>
2810   
detail::string_comp_op_requirement<T, U>
2081   
operator==(T const& lhs, U const& rhs) noexcept
2811   
operator==(T const& lhs, U const& rhs) noexcept
2082   
#endif
2812   
#endif
2083   
{
2813   
{
2084   
    return detail::to_string_view(lhs) == detail::to_string_view(rhs);
2814   
    return detail::to_string_view(lhs) == detail::to_string_view(rhs);
2085   
}
2815   
}
2086  
2816  
2087 - 
/** Checks if lhs does not equal rhs.
2817 + 
/** Return true if lhs does not equal rhs.
2088 -
 
2089 - 
    @li **(1)** A lexicographical comparison is used.
 
2090 - 
    @li **(2)** equivalent to `lhs.get() != rhs.get()`.
 
2091 -
 
2092 - 
    @par Complexity
 
2093 - 
    @li **(1)** linear in `lhs.size() + rhs.size()`.
 
2094 - 
    @li **(2)** constant.
 
2095  
2818  
2096 - 
    @par Exception Safety
2819 + 
    A lexicographical comparison is used.
2097 - 
    No-throw guarantee.
 
2098   
*/
2820   
*/
2099   
#ifdef BOOST_JSON_DOCS
2821   
#ifdef BOOST_JSON_DOCS
2100   
bool
2822   
bool
2101   
operator!=(string const& lhs, string const& rhs) noexcept
2823   
operator!=(string const& lhs, string const& rhs) noexcept
2102   
#else
2824   
#else
2103   
template<class T, class U>
2825   
template<class T, class U>
2104   
detail::string_comp_op_requirement<T, U>
2826   
detail::string_comp_op_requirement<T, U>
2105   
operator!=(T const& lhs, U const& rhs) noexcept
2827   
operator!=(T const& lhs, U const& rhs) noexcept
2106   
#endif
2828   
#endif
2107   
{
2829   
{
2108   
    return detail::to_string_view(lhs) != detail::to_string_view(rhs);
2830   
    return detail::to_string_view(lhs) != detail::to_string_view(rhs);
2109   
}
2831   
}
2110  
2832  
2111 - 
/** Check if lhs is less than rhs.
2833 + 
/** Return true if lhs is less than rhs.
2112  
2834  
2113 -
 
2114 - 
    @par Complexity
 
2115 - 
    Linear in `lhs.size() + rhs.size()`.
 
2116 -
 
2117 - 
    @par Exception Safety
 
2118 - 
    No-throw guarantee.
 
2119   
    A lexicographical comparison is used.
2835   
    A lexicographical comparison is used.
2120   
*/
2836   
*/
2121   
#ifdef BOOST_JSON_DOCS
2837   
#ifdef BOOST_JSON_DOCS
2122   
bool
2838   
bool
2123   
operator<(string const& lhs, string const& rhs) noexcept
2839   
operator<(string const& lhs, string const& rhs) noexcept
2124   
#else
2840   
#else
2125   
template<class T, class U>
2841   
template<class T, class U>
2126   
detail::string_comp_op_requirement<T, U>
2842   
detail::string_comp_op_requirement<T, U>
2127   
operator<(T const& lhs, U const& rhs) noexcept
2843   
operator<(T const& lhs, U const& rhs) noexcept
2128   
#endif
2844   
#endif
2129   
{
2845   
{
2130   
    return detail::to_string_view(lhs) < detail::to_string_view(rhs);
2846   
    return detail::to_string_view(lhs) < detail::to_string_view(rhs);
2131   
}
2847   
}
2132  
2848  
2133 - 
/** Check if lhs is less than or equal to rhs.
2849 + 
/** Return true if lhs is less than or equal to rhs.
2134  
2850  
2135 -
 
2136 - 
    @par Complexity
 
2137 - 
    Linear in `lhs.size() + rhs.size()`.
 
2138 -
 
2139 - 
    @par Exception Safety
 
2140 - 
    No-throw guarantee.
 
2141   
    A lexicographical comparison is used.
2851   
    A lexicographical comparison is used.
2142   
*/
2852   
*/
2143   
#ifdef BOOST_JSON_DOCS
2853   
#ifdef BOOST_JSON_DOCS
2144   
bool
2854   
bool
2145   
operator<=(string const& lhs, string const& rhs) noexcept
2855   
operator<=(string const& lhs, string const& rhs) noexcept
2146   
#else
2856   
#else
2147   
template<class T, class U>
2857   
template<class T, class U>
2148   
detail::string_comp_op_requirement<T, U>
2858   
detail::string_comp_op_requirement<T, U>
2149   
operator<=(T const& lhs, U const& rhs) noexcept
2859   
operator<=(T const& lhs, U const& rhs) noexcept
2150   
#endif
2860   
#endif
2151   
{
2861   
{
2152   
    return detail::to_string_view(lhs) <= detail::to_string_view(rhs);
2862   
    return detail::to_string_view(lhs) <= detail::to_string_view(rhs);
2153   
}
2863   
}
2154 - 
/** Check if lhs is more than or equal to rhs.
 
2155 -
 
2156 - 
    A lexicographical comparison is used.
 
2157 -
 
2158 - 
    @par Complexity
 
2159 - 
    Linear in `lhs.size() + rhs.size()`.
 
2160 -
 
2161 - 
    @par Exception Safety
 
2162 - 
    No-throw guarantee.
 
2163 - 
*/
 
2164  
2864  
2165   
#ifdef BOOST_JSON_DOCS
2865   
#ifdef BOOST_JSON_DOCS
2166   
bool
2866   
bool
2167   
operator>=(string const& lhs, string const& rhs) noexcept
2867   
operator>=(string const& lhs, string const& rhs) noexcept
2168   
#else
2868   
#else
2169   
template<class T, class U>
2869   
template<class T, class U>
2170   
detail::string_comp_op_requirement<T, U>
2870   
detail::string_comp_op_requirement<T, U>
2171   
operator>=(T const& lhs, U const& rhs) noexcept
2871   
operator>=(T const& lhs, U const& rhs) noexcept
2172   
#endif
2872   
#endif
2173   
{
2873   
{
2174   
    return detail::to_string_view(lhs) >= detail::to_string_view(rhs);
2874   
    return detail::to_string_view(lhs) >= detail::to_string_view(rhs);
2175   
}
2875   
}
2176  
2876  
2177 - 
/** Check if lhs is greater than rhs.
2877 + 
/** Return true if lhs is greater than rhs.
2178  
2878  
2179 -
 
2180 - 
    @par Complexity
 
2181 - 
    Linear in `lhs.size() + rhs.size()`.
 
2182 -
 
2183 - 
    @par Exception Safety
 
2184 - 
    No-throw guarantee.
 
2185   
    A lexicographical comparison is used.
2879   
    A lexicographical comparison is used.
2186   
*/
2880   
*/
2187   
#ifdef BOOST_JSON_DOCS
2881   
#ifdef BOOST_JSON_DOCS
2188   
bool
2882   
bool
2189   
operator>(string const& lhs, string const& rhs) noexcept
2883   
operator>(string const& lhs, string const& rhs) noexcept
2190   
#else
2884   
#else
2191   
template<class T, class U>
2885   
template<class T, class U>
2192   
detail::string_comp_op_requirement<T, U>
2886   
detail::string_comp_op_requirement<T, U>
2193   
operator>(T const& lhs, U const& rhs) noexcept
2887   
operator>(T const& lhs, U const& rhs) noexcept
2194   
#endif
2888   
#endif
2195   
{
2889   
{
2196   
    return detail::to_string_view(lhs) > detail::to_string_view(rhs);
2890   
    return detail::to_string_view(lhs) > detail::to_string_view(rhs);
2197   
}
2891   
}
2198  
2892  
2199   
} // namespace json
2893   
} // namespace json
2200   
} // namespace boost
2894   
} // namespace boost
2201  
2895  
2202   
// std::hash specialization
2896   
// std::hash specialization
2203   
#ifndef BOOST_JSON_DOCS
2897   
#ifndef BOOST_JSON_DOCS
2204   
namespace std {
2898   
namespace std {
2205   
template<>
2899   
template<>
2206   
struct hash< ::boost::json::string >
2900   
struct hash< ::boost::json::string >
2207   
{
2901   
{
2208   
    BOOST_JSON_DECL
2902   
    BOOST_JSON_DECL
2209   
    std::size_t
2903   
    std::size_t
2210   
    operator()( ::boost::json::string const& js ) const noexcept;
2904   
    operator()( ::boost::json::string const& js ) const noexcept;
2211   
};
2905   
};
2212   
} // std
2906   
} // std
2213   
#endif
2907   
#endif
2214  
2908  
2215   
#include <boost/json/impl/string.hpp>
2909   
#include <boost/json/impl/string.hpp>
2216  
2910  
2217   
#endif
2911   
#endif