feedc0de/boost_static_string
1
0
Fork 0
forked from boostorg/static_string
Code Pull Requests Activity

Update docs with design

Browse Source
This commit is contained in:
Krystian Stasiowski
2019-11-07 23:25:18 -05:00
parent ae94f411d9
commit 566a163536
2 changed files with 12 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@ -14,48 +14,6 @@ compile-time fixed capacity and contiguous embedded storage in which the
characters are placed within the string object itself. Its API closely characters are placed within the string object itself. Its API closely
resembles that of `std::string` resembles that of `std::string`
## 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).
## 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 `fixed_string` work when the source is within the string itself.
The API of `fixed_string` only diverges from `std::string` in few places,
being `substr` for which this implementation returns a string view instead of `fixed_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 `fixed_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 `fixed_string`.
## 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
## License ## License
Distributed under the Boost Software License, Version 1.0. Distributed under the Boost Software License, Version 1.0.

14
doc/qbk/main.qbk
View File

@ -57,7 +57,7 @@ A fixed capacity string is useful when:
segment is required. segment is required.
* A dynamically-resizable string is required within `constexpr` functions. * A dynamically-resizable string is required within `constexpr` functions.
* The storage location of the static_vector elements is required to be * The storage location of the static_vector elements is required to be
within the string object itself (e.g. to support memcopy for serialization within the string object itself (e.g. to support `memcpy` for serialization
purposes). purposes).
[endsect] [endsect]
@ -70,7 +70,17 @@ 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 `std::string` as much as possible. When any operation would exceed the
maximum allowed size of the string, `std::length_error` is thrown. All maximum allowed size of the string, `std::length_error` is thrown. All
algorithms which throw exceptions provide the strong exception safety algorithms which throw exceptions provide the strong exception safety
guarantee. guarantee. This is intended to be a drop in replacement for `std::string`.
All the operations for `fixed_string` work when the source is within the string itself.
The API of `fixed_string` only diverges from `std::string` in few places,
being `substr` for which this implementation returns a string view instead of `fixed_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 `fixed_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 `fixed_string`.
[endsect] [endsect]