forked from boostorg/static_string
109 lines
4.2 KiB
Plaintext
109 lines
4.2 KiB
Plaintext
[/
|
|
Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
|
|
Copyright (c) 2019 Krystian Stasiowski (sdkrystian at gmail dot 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/static_string
|
|
]
|
|
|
|
[library Boost.StaticString
|
|
[id static_string]
|
|
[quickbook 1.6]
|
|
[copyright 2016 - 2019 Vinnie Falco]
|
|
[copyright 2019 Krystian Stasiowski]
|
|
[purpose String Library]
|
|
[license
|
|
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])
|
|
]
|
|
[authors [Falco, Vinnie], [Stasiowski, Krystian]]
|
|
[category template]
|
|
[category generic]
|
|
]
|
|
|
|
[template mdash[] '''— ''']
|
|
[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
|
|
[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
|
|
|
|
[template path_link[path name] '''<ulink url="../../'''[path]'''">'''[name]'''</ulink>''']
|
|
[template include_file[path][^<'''<ulink url="../../../../'''[path]'''">'''[path]'''</ulink>'''>]]
|
|
|
|
[def __InputIterator__ [@https://en.cppreference.com/w/cpp/named_req/InputIterator ['InputIterator]]]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[section Introduction]
|
|
|
|
This library provides a dynamically resizable string of characters with
|
|
compile-time fixed capacity and contiguous embedded storage in which the
|
|
characters are placed within the string object itself. Its API closely
|
|
resembles that of `std::string`
|
|
|
|
[endsect]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[section Motivation]
|
|
|
|
A fixed capacity string is useful when:
|
|
|
|
* Memory allocation is not possible, e.g., embedded environments without a free
|
|
store, where only a stack and the static memory segment are available.
|
|
* Memory allocation imposes an unacceptable performance penalty.
|
|
e.g., with respect to latency.
|
|
* Allocation of objects with complex lifetimes in the static-memory
|
|
segment is required.
|
|
* A dynamically-resizable string is required within `constexpr` functions.
|
|
* The storage location of the static_vector elements is required to be
|
|
within the string object itself (e.g. to support `memcpy` for serialization
|
|
purposes).
|
|
|
|
[endsect]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[section Design]
|
|
|
|
The over-arching design goal is to resemble the interface and behavior of
|
|
`std::string` as much as possible. When any operation would exceed the
|
|
maximum allowed size of the string, `std::length_error` is thrown. All
|
|
algorithms which throw exceptions provide the strong exception safety
|
|
guarantee. This is intended to be a drop in replacement for `std::string`.
|
|
All the operations for `static_string` work when the source is within the string itself.
|
|
|
|
The API of `static_string` only diverges from `std::string` in few places,
|
|
being `substr` for which this implementation returns a string view instead of `static_string`,
|
|
and certain functions that will never throw are marked as `noexcept`, which diverges from
|
|
those of `std::string`. Every function that is in the C++20 specification of `std::string` is
|
|
present in this implementation, with the only difference being the lack of `constexpr`
|
|
for the time being. The avaliable overloads for `static_string` are identical to those
|
|
of `std::string`, except for `operator+` which is explicitly deleted as no reasonable implementation
|
|
would be possible, due to the difficulty in determining the size of the resulting `static_string`.
|
|
|
|
[endsect]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[section Iterators]
|
|
|
|
The iterator invalidation rules are different than those for `std::string`,
|
|
since:
|
|
|
|
* Moving a string invalidates all iterators
|
|
* Swapping two strings invalidates all iterators
|
|
|
|
[endsect]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[section:ref Reference]
|
|
[include reference.qbk]
|
|
[endsect]
|
|
|
|
[/-----------------------------------------------------------------------------]
|
|
|
|
[xinclude index.xml]
|