boostorg/static_string
1
0
Fork 1
mirror of https://github.com/boostorg/static_string.git synced 2025-07-29 12:07:42 +02:00
Code Issues Packages Projects Releases Wiki 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
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
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.
* 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 memcopy for serialization
within the string object itself (e.g. to support `memcpy` for serialization
purposes).
[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
maximum allowed size of the string, `std::length_error` is thrown. All
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]