[/
    Copyright (c) 2019 Vinnie Falco (vinnie.falco@gmail.com)
    Copyright (c) 2020 Krystian Stasiowski (sdkrystian@gmail.com)

    Distributed under the Boost Software License, Version 1.0. (See accompanying
    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

    Official repository: https://github.com/boostorg/json
]

[/-----------------------------------------------------------------------------]

[section string]

Modifiable sequences of characters are represented using objects of type __string__.
The interface and functionality of __string__ is
the same as `std::basic_string` except that:

* __string__ is not a class template,

* __string__ uses `char` as its character type,

* redundant overloads for string operations have been replaced
with a __string_view__ based interface,

* access to characters in the range `[size(), capacity())` is permitted,

* __storage_ptr__ is used instead of __Allocator__, and

* guaranteed small buffer optimisation that avoids allocating memory for
small strings.

With augmented interface, operations requiring an input string
are implemented as a single overload with a parameter of type
__string_view__, and can accept most string-like objects.
Objects such as null terminated character pointers, `std::string`,
`json::string`, subranges of strings, and objects
convertible to __string_view__ can all be passed to these functions.

[snippet_strings_4]

More formally, `std::string` member function overloads that accept any of the
following parameter combinations as an input string:

* a `std::string` parameter, or

* a `std::string` parameter and two `size_type` parameters that specify a substring, or

* a parameter of a type convertible to __string_view__, or

* a parameter of a type convertible to __string_view__ and two
`size_type` parameters that specify a substring, or

* a `const_pointer`, or

* a parameter of type `const_pointer` and a `size_type` parameter
that specifies the length of the string

are replaced with an overload accepting a __string_view__ parameter.

This design removes several redundant overloads from the interface.
For example, the 11 overloads of `std::string::insert` are reduced
to just 3 in __string__, while still providing identical functionality.
In addition to these changes, overloads taking a `std::initializer_list<char>`
parameter have been removed. Such overloads have little use,
as they serve as little more than a wrappers for arrays with an inefficient syntax:

[snippet_strings_3]

With the removal of overloads that specify parameters for a substring, a member function
`subview` that returns a __string_view__ is provided to facilitate cheap substring operations:

[snippet_strings_2]

A __string__ may be constructed using the __default_memory_resource__ without
incurring any memory allocations. Alternatively, a __storage_ptr__ can be
provided explicitly:

[snippet_strings_1]

[heading Formatted Output]

When a __string__ is formatted to a __std_ostream__, the result is a valid
JSON. That is, the result will be double quoted and the contents properly
escaped per the JSON specification.

[heading Accessing storage beyond `size()`]

__string__ directly supports access to its storage in the range
`[size(), capacity())`. This can be used for efficient assembly of a string
from several parts. After the string is assembled, use the member function
[link json.ref.boost__json__string.grow `grow()`] to update the string's size
and insert the null terminator. For example:

[snippet_strings_5]

[endsect]
