1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 Copyright (c) 2019-2020 Krystian Stasiowski (sdkrystian at gmail dot com) 4 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) 7 8 Official repository: https://github.com/boostorg/static_string 9] 10 11[library Boost.StaticString 12 [id static_string] 13 [quickbook 1.6] 14 [copyright 2019 - 2020 Krystian Stasiowski] 15 [copyright 2016 - 2019 Vinnie Falco] 16 [purpose String Library] 17 [license 18 Distributed under the Boost Software License, Version 1.0. 19 (See accompanying file LICENSE_1_0.txt or copy at 20 [@http://www.boost.org/LICENSE_1_0.txt]) 21 ] 22 [authors [Stasiowski, Krystian], [Falco, Vinnie]] 23 [category template] 24 [category generic] 25] 26 27[template mdash[] '''— '''] 28[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>'''] 29[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>'''] 30 31[template path_link[path name] '''<ulink url="../../'''[path]'''">'''[name]'''</ulink>'''] 32[template include_file[path][^<'''<ulink url="../../../../'''[path]'''">'''[path]'''</ulink>'''>]] 33 34[def __InputIterator__ [@https://en.cppreference.com/w/cpp/named_req/InputIterator ['InputIterator]]] 35 36[/-----------------------------------------------------------------------------] 37 38[heading Introduction] 39 40This library provides a dynamically resizable string of characters with 41compile-time fixed capacity and contiguous embedded storage in which the 42characters are placed within the string object itself. Its API closely 43resembles that of `std::string`. 44 45[/-----------------------------------------------------------------------------] 46 47[heading Motivation] 48 49A fixed capacity string is useful when: 50 51* Memory allocation is not possible, e.g., embedded environments without a free 52 store, where only a stack and the static memory segment are available. 53* Memory allocation imposes an unacceptable performance penalty. 54 e.g., with respect to latency. 55* Allocation of objects with complex lifetimes in the static-memory 56 segment is required. 57* A dynamically-resizable string is required within `constexpr` functions. 58* The storage location of the static_vector elements is required to be 59 within the string object itself (e.g. to support `memcpy` for serialization 60 purposes). 61 62[/-----------------------------------------------------------------------------] 63 64[heading Requirements] 65 66The library is usable in two different modes: standalone and Boost dependent. This library defaults to Boost dependent mode; standalone mode is opt-in through the use of a configuration macro. 67 68When in Boost dependent mode, the library requires the use of at least C++11, in addition to Boost.Core, Boost.Utility, and Boost.ContainerHash. In standalone mode, C++17 is required but no libraries except for the standard library are needed. 69 70[/-----------------------------------------------------------------------------] 71 72[heading Design] 73 74The over-arching design goal is to resemble the interface and behavior of 75`std::string` as much as possible. When any operation would exceed the 76maximum allowed size of the string, `std::length_error` is thrown if exceptions are enabled. All 77algorithms which throw exceptions provide the strong exception safety 78guarantee. This is intended to be a drop in replacement for `std::string`. 79 80The API of `static_string` only diverges from `std::string` in few places, 81one of which is the addition of the `subview` function, for which this implementation 82returns a string view instead of `static_string`, 83and certain functions that will never throw are marked as `noexcept`, which diverges from 84those of `std::string`. The available overloads for `static_string` are identical to those 85of `std::string`. 86 87[/-----------------------------------------------------------------------------] 88 89[heading Iterators] 90 91The iterator invalidation rules differ from those of `std::string`: 92 93* Moving a `static_string` invalidates all iterators 94* Swapping two `static_string`s invalidates all iterators 95 96[/-----------------------------------------------------------------------------] 97 98[heading Optimizations] 99 100Depending on the character type and size used for a specialization of `static_string`, certain optimizations are used to reduce the size of the class type. Given the name of a specialization of the form `basic_static_string<N, CharT, Traits>`: 101 102* If `N` is 0, then the class has no non-static data members. Given two objects `a` and `b` of type `basic_static_string<0, T, Traits>` and `static_string<0, U, Traits>` respectively, the pointer value returned by `data()` will be the same if `T` and `U` are the same. 103 104* Otherwise, the type of the member used to store the size of the `static_string` will be the smallest standard unsigned integer type that can represent the value `N`. 105 106[/-----------------------------------------------------------------------------] 107 108[heading Configuration] 109 110Certain features can be enabled and disabled though defining configuration macros. The macros and the associated feature they control are: 111 112* `BOOST_STATIC_STRING_STANDALONE`: When defined, the library is put into standalone mode. 113 114[/-----------------------------------------------------------------------------] 115 116[heading Acknowledgments] 117 118Thanks to [@https://github.com/K-ballo Agustín Bergé], [@https://github.com/pdimov Peter Dimov], [@https://github.com/glenfe Glen Fernandes], and [@https://github.com/LeonineKing1199 Christian Mazakas] for their constant feedback and guidance during the development of this library. 119 120The development of this library is sponsored by [@https://cppalliance.org The C++ Alliance]. 121 122[/-----------------------------------------------------------------------------] 123 124[heading Reference] 125 126Defined in namespace `boost::static_strings`: 127 128[link static_string.ref.boost__static_strings__basic_static_string `basic_static_string`] 129 130[/-----------------------------------------------------------------------------] 131 132[section:ref Reference] 133[include reference.qbk] 134[endsect] 135 136[/-----------------------------------------------------------------------------] 137 138[xinclude index.xml]