coffee/etl
1
0
Fork 0
mirror of https://github.com/ETLCPP/etl.git synced 2026-04-30 19:09:10 +08:00
Code Issues Packages Projects Releases Wiki Activity

Added documentation for string_stream and string utilities.

Browse Source
This commit is contained in:
John Wellbelove 2026-04-11 22:47:31 +02:00
parent 4540ed317b
commit 692360d0ed
5 changed files with 770 additions and 133 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
docs/raw/strings/Strings page.txt
View File

@ -1,38 +0,0 @@
Strings
____________________________________________________________________________________________________
String
The library defines a set of string templates that have been specially tailored for embedded systems.
They have a maximum capacity fixed at compile time and make no calls to malloc/free or new/delete.
They are completely deterministic.
The ETL provides etl::string, etl::wstring, etl::u16string and etl::u32string.
____________________________________________________________________________________________________
String View
The ETL defines string view classes that provide a lost cost view into a string.
The ETL provides etl::string_view, etl::wstring_view, etl::u16string_view and etl::u32string_view.
____________________________________________________________________________________________________
To String
The ETL defines a utility to create strings according to a format.
The ETL provides etl::to_string, etl::to_wstring, etl::to_u16string and etl::to_u32string.
____________________________________________________________________________________________________
To Arithmetic
The ETL defines a utility to convert strings to values.
____________________________________________________________________________________________________
String Stream
The ETL defines string stream classes that stream values into a string.
The ETL provides etl::string_stream, etl::wstring_stream, etl::u16string_stream
and etl::u32string_stream.
____________________________________________________________________________________________________
String Utilities
The ETL provides a set of string to examine and manipulate strings.
____________________________________________________________________________________________________
Format Specification
A class is defined to format the output of etl::to_string, etl::to_wstring, etl::to_u16string and etl::to_u32string.

95
docs/raw/strings/string_stream.txt
View File

@ -1,95 +0,0 @@
string_stream
wstring_stream
u16string_stream
u32string_stream
Classes to build strings using a streaming api.
Uses etl::basic_format_spec to define the required formatting.
The documentation below is for etl::string_stream.
The other streams have a similar API, though using w, u16 or u32 types.
____________________________________________________________________________________________________
Member functions
explicit string_stream(etl::istring& str)
Construct, using the supplied string as a buffer.
Uses the default format spec.
____________________________________________________________________________________________________
string_stream(etl::istring& str, const etl::format_spec& spec)
Construct, using the supplied string as a buffer.
Initialised with the supplied format spec.
____________________________________________________________________________________________________
void set_format(const etl::format_spec& spec_)
Sets a new format spec to use.
____________________________________________________________________________________________________
const etl::format_spec& get_format() const
Gets the current format spec.
____________________________________________________________________________________________________
etl::istring& str()
Gets a reference to the internal string.
____________________________________________________________________________________________________
const etl::istring& str() const
Gets a const reference to the internal string.
____________________________________________________________________________________________________
void str(const etl::istring::const_pointer p)
Resets the internal string to the text pointed to by p.
____________________________________________________________________________________________________
void str(const etl::istring& text)
Resets the internal string to text.
____________________________________________________________________________________________________
Streaming operators
string_stream& operator <<(string_stream& ss, T value)
Where T may be one of the following:-
Any fundamental type.
etl::format_spec
etl::setbase(n)
etl::bin
etl::oct
etl::dec
etl::hex
etl::setfill(c)
etl::setw(n)
etl::setprecision(n)
etl::left
etl::right
etl::boolalpha
etl::noboolalpha
etl::uppercase
etl::nouppercase
etl::showbase
etl::noshowbase
etl::string
etl::istring
etl::string_view
const char*
See etl::format_spec
Custom user types may be streamed by overloading the streaming operator.
____________________________________________________________________________________________________
Examples
Using format_spec
etl::format_spec format1 = etl::format_spec().hex().width(8).fill('0');
etl::format_spec format2;
etl::format_spec format3 = etl::format_spec().width(6).fill('#').precision(3);
etl::string<50> text;
etl::string_stream stream(text);
stream << format1 << 1193046 << format2 << " " << format3 << 3.1415;
const etl::istring& result = stream.str();
text is set to "00123456 #3.142"
____________________________________________________________________________________________________
Using stream manipulators
etl::string<50> text;
etl::string_stream stream(text);
stream << etl::hex << etl::setw(8) << etl::setfill('0') << 1193046
<< etl::setw(0) << " "
<< etl::setw(6) << etl::setfill('#') << etl::setprecision(3) << 3.1415;
const etl::istring& result = stream.str();
text is set to "00123456 #3.142"

8
docs/strings/_index.md
View File

@ -36,3 +36,11 @@ The ETL provides a set of string to examine and manipulate strings.
## Format Specification
A class is defined to format the output of `etl::to_string`, `etl::to_wstring`, `etl::to_u16string`, and `etl::to_u32string`.
## Format
A C++20 style `etl::format`.
## Print
A C++23 style `etl::print`

142
docs/strings/string_stream.md Normal file
View File

@ -0,0 +1,142 @@
---
title: "string_stream"
---
## Streaming types
`string_stream`
`wstring_stream`
`u16string_stream`
`u32string_stream`
Classes to build strings using a streaming API.
Uses `etl::basic_format_spec` to define the required formatting.
The documentation below is for `etl::string_stream`.
The other streams have a similar API, though using `w`, `u8`, `u16` or `u32` types.
## Member functions
```cpp
explicit string_stream(etl::istring& str)
```
**Description**
Construct, using the supplied string as a buffer.
Uses the default `format_spec`.
---
```cpp
string_stream(etl::istring& str, const etl::format_spec& spec)
```
**Description**
Construct, using the supplied string as a buffer.
Initialised with the supplied `format_spec`.
---
```cpp
void set_format(const etl::format_spec& spec_)
```
**Description**
Sets a new `format_spec` to use.
---
```cpp
const etl::format_spec& get_format() const
```
**Description**
Gets the current `format_spec`.
---
```cpp
etl::istring& str()
```
**Description**
Gets a reference to the internal string.
```cpp
const etl::istring& str() const
```
**Description**
Gets a const reference to the internal string.
---
```cpp
void str(const etl::istring::const_pointer p)
```
**Description**
Resets the internal string to the text pointed to by `p`.
---
```cpp
void str(const etl::istring& text)
```
**Description**
Resets the internal string to `text`.
## Streaming operators
```cpp
string_stream& operator <<(string_stream& ss, T value)
```
**Description**
Where `T` may be one of the following:-
Any fundamental type.
`etl::format_spec`
`etl::setb0ase(n)`
`etl::bin`
`etl::oct`
`etl::dec`
`etl::hex`
`etl::setfill(c)`
`etl::setw(n)`
`etl::setprecision(n)`
`etl::left`
`etl::right`
`etl::boolalpha`
`etl::noboolalpha`
`etl::uppercase`
`etl::nouppercase`
`etl::showbase`
`etl::noshowbase`
`etl::string`
`etl::istring`
`etl::string_view`
`const char*`
See `etl::format_spec`
Custom user types may be streamed by overloading the streaming operator.
## Examples
### Using format_spec
```cpp
etl::format_spec format1 = etl::format_spec().hex().width(8).fill('0');
etl::format_spec format2;
etl::format_spec format3 = etl::format_spec().width(6).fill('#').precision(3);
etl::string<50> text;
etl::string_stream stream(text);
stream << format1 << 1193046 << format2 << " " << format3 << 3.1415;
const etl::istring& result = stream.str();
```
`text` is set to `"00123456 #3.142"`.
### Using stream manipulators
```cpp
etl::string<50> text;
etl::string_stream stream(text);
stream << etl::hex << etl::setw(8) << etl::setfill('0') << 1193046
<< etl::setw(0) << " "
<< etl::setw(6) << etl::setfill('#') << etl::setprecision(3) << 3.1415;
const etl::istring& result = stream.str();
```
`text` is set to `"00123456 #3.142"`.

620
docs/strings/string_utilities.md Normal file
View File

@ -0,0 +1,620 @@
---
title: "String Utilities"
---
A set of utilities to make string manipulation a little easier.
The documentation below is for handling `etl::string`.
The other strings have a similar API, though using `w`,, `u8`, `u16` or `u32` types from the ETL and STL.
The string utilities are compatible with any string-like container that exposes a compatible API.
**Example**
```cpp
void trim_whitespace_left(etl::istring& s)
void trim_whitespace_left(etl::iwstring& s)
void trim_whitespace_left(std::string& s)
void trim_whitespace_left(std::u32string& s)
```
## Whitespace
Whitespace characters are deemed as `' '`, `'\t'`, `'\n'`, `'\r'`, `'\f'`, `'\v'`
### Modifying functions
```cpp
void trim_whitespace_left(etl::istring& s)
```
**Description**
Trims the whitespace characters from the left of s.
---
```cpp
void trim_from_left(etl::istring& s,
etl::istring::const_pointer trim_characters)
```
**Description**
Trims any of the characters in trim_characters from the left of `s`.
Stops at the first character not in `trim_characters`.
---
```cpp
void trim_left(etl::istring& s,
etl::istring::const_pointer delimiters)
```
**Description**
Trims all of the characters in up to the first character in `delimiters` from the left of `s`.
---
```cpp
void trim_whitespace_right(etl::istring& s)
```
**Description**
Trims the whitespace characters from the right of `s`.
---
```cpp
void trim_from_right(etl::istring& s,
etl::istring::const_pointer trim_characters)
```
**Description**
Trims any of the characters in `trim_characters` from the right of `s`.
Stops at the first character not in `trim_characters`.
---
```cpp
void trim_right(etl::istring& s,
etl::istring::const_pointer delimiters)
```
**Description**
Trims all of the characters in up to the first character in `delimiters` from the right of `s`.
---
```cpp
void trim_whitespace(etl::istring& s)
```
**Description**
Trims the whitespace characters from both ends of `s.`
---
```cpp
void trim_from(etl::istring& s,
etl::istring::const_pointer trim_characters)
```
**Description**
Trims any of the characters in `trim_characters` from the right of `s`.
Stops at the first character not in `trim_characters`.
---
```cpp
void trim(etl::istring& s,
etl::istring::const_pointer delimiters)
```
**Description**
Trims all of the characters in up to the first character in `delimiters` from both ends of `s`.
---
...cpp
void reverse(etl::istring& s)
```
**Description**
Reverses `s`.
---
```cpp
void left_n(etl::istring& s,
size_t n)
```
**Description**
Trims `s` to the left `n` most characters.
If the string is less than `n` characters long then it is left unchanged.
---
```cpp
void right_n(etl::istring& s,
size_t n)
```
**Description**
Trims `s` to the right `n` most characters.
If the string is less than `n` characters long then it is left unchanged.
---
```cpp
void pad_left(etl::istring& s,
size_t required_size,
etl::istring::value_type pad_char)
```
**Description**
Pads `s` to length required_size by adding `pad_char` to the left.
If the string length is greater than or equal to required_size then it is left unchanged.
---
```cpp
void pad_right(etl::istring& s,
size_t required_size,
etl::istring::value_type pad_char)
```
**Description**
Pads `s` to length required_size by adding `pad_char` to the right.
If the string length is greater than or equal to required_size then it is left unchanged.
---
```cpp
void pad(etl::istring& s,
size_t required_size,
string_pad_direction pad_direction,
etl::istring::value_type pad_char)
```
Pads `s` to length `required_size` by adding `pad_char` to the end specified by `pad_direction`.
If the string length is greater than or equal to required_size then it is left unchanged.
---
```cpp
void to_upper_case(etl::istring& s)
```
**Description**
Change `s` to upper case.
`"hElLo WoRLd"` => `"HELLO WORLD"`
Valid for `etl::istring` only.
---
```cpp
void to_lower_case(etl::istring& s)
```
**Description**
Change `s` to lower case.
`"hElLo WoRLd"` => `"hello world"`
Valid for `etl::istring` only.
---
```cpp
void to_sentence_case(etl::istring& s)
```
**Description**
Change `s` to sentence case.
`"hElLo WoRLd"` => `"Hello world"`
Valid for `etl::istring` only.
---
```cpp
void replace(etl::istring& s,
const etl::pair<etl::istring::value_type,
etl::istring::value_type>* pairsbegin,
const etl::pair<etl::istring::value_type,
etl::istring::value_type>* pairsend)
```
**Arguments**
`pairsbegin` Pointer to the first pair in the list.
`pairsend` Pointer to one past the last pair in the list.
**Description**
Replaces characters according the supplied lookup table of `etl::pair`.
Each pair specifies an old/new character replacement.
---
```cpp
void replace(etl::istring& s,
const etl::pair<const etl::istring::value_type*,
const etl::istring::value_type*>* pairsbegin,
const etl::pair<const etl::istring::value_type*,
const etl::istring::value_type*>* pairsend)
```
**Arguments**
`pairsbegin` Pointer to the first pair in the list.
`pairsend` Pointer to one past the last pair in the list.
**Description**
Replaces strings according the supplied lookup table of `etl::pair`.
Each pair specifies an old/new string replacement.
## Non-modifying functions
```cpp
etl::string_view trim_view_whitespace_left(const etl::string_view& view)
```
**Description**
Returns a `string_view` of the whitespace characters trimmed from the left of `view`.
---
```cpp
etl::string_view trim_from_view_left(const etl::string_view& view,
etl::istring::const_pointer trim_characters)
```
**Description**
Returns a `string_view` of the characters in `trim_characters` trimmed from the left of `view`.
Stops at the first character not in `trim_characters`.
---
```cpp
etl::string_view trim_view_left(etl::string_view& view,
etl::string_view::const_pointer delimiters)
```
**Description**
Returns a `string_view` of the characters in up to the first character in `delimiters` from the left of `view`.
---
```cpp
etl::string_view trim_view_whitespace_right(const etl::string_view& view)
```
**Description**
Returns a `string_view` of the whitespace characters trimmed from the right of `view`.
---
```cpp
etl::string_view trim_from_view_right(const etl::string_view& view,
etl::istring::const_pointer trim_characters)
```
**Description**
Returns a `string_view` of the characters in `trim_characters` trimmed from the right of `view`.
Stops at the first character not in `trim_characters`.
---
```cpp
etl::string_view trim_view_right(const etl::string_view& view,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `string_view` of the characters in up to the first character in `delimiters` from the right of `view`.
---
```cpp
etl::string_view trim_whitespace(const etl::string_view& view)
```
**Description**
Returns a `string_view` of the whitespace characters trimmed from both ends of `view`.
---
```cpp
etl::string_view trim_view_from(const etl::string_view& view,
etl::istring::const_pointer trim_characters)
```
**Description**
Returns a `string_view` of the characters in `trim_characters` trimmed from both ends of `view`.
Stops at the first character not in `trim_characters`.
---
```cpp
etl::string_view trim(const etl::string_view& view,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `string_view` of the characters in up to the first character in `delimiters` from both ends of `view`.
---
```cpp
etl::string_view left_n_view(etl::string_view view,
size_t n)
```
Returns a `string_view` to the left `n` most characters of `view`.
If the string is less than `n characters long then the returned view equal the supplied `view`.
---
```cpp
etl::string_view right_n_view(etl::string_view view,
size_t n)
```
**Description**
Returns a `string_view` to the right `n` most characters of `view`.
If the string is less than `n` characters long then the returned view equal the supplied `view`.
---
```cppp
etl::optional<etl::string_view> get_token(const INPUT_TYPE& s,
const char* delimiters,
const etl::optional<etl::string_view>& last_view,
bool ignore_empty_tokens)
```
**Description**
Where `INPUT_TYPE` is any container type that supports `data()` and `size()` member functions.
Tokenizes the string.
The returned token will be invalid for the call after the last token has been extracted.
`s` The string to tokenize.
`delimiters` The delimiters between tokens.
`last_view` The last returned token view or default constructed view.
`ignore_empty_tokens` If `true`, empty tokens will be ignored, otherwise empty tokens will return an empty view.
**Example**
```cpp
using String = etl::string<32>;
using StringView = etl::string_view;
using Vector = etl::vector<String, 10>;
using Token = etl::optional<StringView>;
String text(" The cat.sat, on;the:mat .,;:");
Vector tokens;
Token token; // Default constructed token.
while ((token = etl::get_token(text, " .,;:", token, true))) // Exit once we get an invalid token.
{
// Place it in the token list.
tokens.emplace_back(token.value());
}
```
`tokens` will contain `"The", "cat", "sat", "on", "the", "mat"`.
---
```cpp
template <typename TInput, typename TOutput>
bool get_token_list(const TInput& input,
TOutput& output,
typename TInput::const_pointer delimiters,
bool ignore_empty_tokens,
size_t max_n_tokens = etl::integral_limits<size_t>::max)
```
>20.41.0
**Description**
Splits a string of tokens to a set of views, according to a set of `delimiters`.
`input` The input string.
`output` A reference to an output container of string views.
`delimiters` A pointer to a string of valid `delimiters`.
`ignore_empty_tokens` If `true` then empty tokens are ignored.
`max_n_tokens` The maximum number of tokens to collect. Default: tokenise everything.
**Return**
`true` if all tokens were added to the list, otherwise `false`.
The tokenisation stops if:
1. The end of the input text is reached.
2. The max_size() of the output container is reached.
3. The number of tokens found reaches max_n_tokens.
The input container must define the type `const_pointer`.
The output container must define the type `value_type`.
The output container must define the member function `max_size()` that returns the maximum size of the container.
The output container must define the member function `push_back()` that pushes the view on to the back of the container.
**Example**
```cpp
std::string text(",,,The,cat,sat,,on,the,mat");
std::vector<std::string_view> views;
bool all_views_found = etl::get_token_list(text, views, ",", true, 3);
all_views_found == false
views.size() == 3
views[0] == "The"
views[1] == "cat"
views[2] == "sat"
```
## Find functions
```cpp
etl::istring::iterator find_first_of(etl::istring::iterator first,
etl::istring::iterator last,
etl::istring::const_pointer delimiters)
```
**Description**
Returns an iterator to the first instance of a character in `delimiters`.
Returns `last` if not found.
---
```cpp
etl::istring::const_iterator find_first_of(etl::istring::const_iterator first,
etl::istring::const_iterator last,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the first instance of a character in `delimiters`.
Returns `last` if not found.
---
```cpp
etl::istring::iterator find_first_of(etl::istring& s,
etl::istring::const_pointer delimiters)
```
**Description**
Returns an `iterator` to the first instance of a character in `delimiters`.
Returns `s.end()` if not found.
---
```cpp
etl::istring::const_iterator find_first_of(const etl::istring& s,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the first instance of a character in `delimiters`.
Returns `s.end()` if not found.
---
```cpp
etl::istring::const_iterator find_first_of(const etl::string_view& view,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the first instance of a character in `delimiters`.
Returns `view.end()` if not found.
---
```cpp
etl::istring::iterator find_first_not_of(etl::istring::iterator first,
etl::istring::iterator last,
etl::istring::const_pointer delimiters)
```
**Description**
Returns an `iterator` to the first instance of a character not in `delimiters`.
Returns `last` if not found.
---
```cpp
etl::istring::const_iterator find_first_not_of(etl::istring::const_iterator first,
etl::istring::const_iterator last,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the first instance of a character not in `delimiters`.
Returns `last` if not found.
---
```cpp
etl::istring::iterator find_first_not_of(etl::istring& s,
etl::istring::const_pointer delimiters)
```
**Description**
Returns an `iterator` to the first instance of a character not in `delimiters`.
Returns `s.end()` if not found.
---
```cpp
etl::istring::const_iterator find_first_not_of(const etl::istring& s,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the first instance of a character not in `delimiters`.
Returns `s.end()` if not found.
---
```cpp
etl::istring::const_iterator find_first_not_of(const etl::string_view& view,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the first instance of a character not in `delimiters`.
Returns `view.end()` if not found.
---
```cpp
etl::istring::iterator find_last_of(etl::istring::iterator first,
etl::istring::iterator last,
etl::istring::const_pointer delimiters)
```
**Description**
Returns an `iterator` to the last instance of a character in `delimiters`.
Returns `last` if not found.
---
```cpp
etl::istring::const_iterator find_last_of(etl::istring::const_iterator first,
etl::istring::const_iterator last,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the last instance of a character in `delimiters`.
Returns `last` if not found.
---
```cpp
etl::istring::iterator find_last_of(etl::istring& s, etl::istring::const_pointer delimiters)
```
**Description**
Returns an `iterator` to the last instance of a character in `delimiters`.
Returns `s.end()` if not found.
---
```cpp
etl::istring::const_iterator find_last_of(const etl::istring& s,
etl::istring::const_pointer delimiters)
```
Returns a `const_iterator` to the last instance of a character in `delimiters`.
Returns `s.end()` if not found.
---
```cpp
etl::istring::const_iterator find_last_of(const etl::string_view& view,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the last instance of a character in `delimiters`.
Returns `view.end()` if not found.
---
```cpp
etl::istring::iterator find_last_not_of(etl::istring::iterator first,
etl::istring::iterator last,
etl::istring::const_pointer delimiters)
```
**Description**
Returns an `iterator` to the last instance of a character not in `delimiters`.
Returns `last` if not found.
---
```cpp
etl::istring::const_iterator find_last_not_of(etl::istring::const_iterator first,
etl::istring::const_iterator last,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the last instance of a character not in `delimiters`.
Returns `last` if not found.
---
```cpp
etl::istring::iterator find_last_not_of(etl::istring& s,
etl::istring::const_pointer delimiters)
```
**Description**
Returns an `iterator` to the last instance of a character not in `delimiters`.
Returns `last` if not found.
---
```cpp
etl::istring::const_iterator find_last_not_of(const etl::istring& s,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the last instance of a character not in `delimiters`.
Returns `s.end()` if not found.
---
```cpp
etl::istring::const_iterator find_last_not_of(const etl::string_view& view,
etl::istring::const_pointer delimiters)
```
**Description**
Returns a `const_iterator` to the last instance of a character not in `delimiters`.
Returns `view.end()` if not found.