From 692360d0ed14c608c985ad6ad9c58f6c3225d852 Mon Sep 17 00:00:00 2001 From: John Wellbelove Date: Sat, 11 Apr 2026 22:47:31 +0200 Subject: [PATCH] Added documentation for string_stream and string utilities. --- docs/raw/strings/Strings page.txt | 38 -- docs/raw/strings/string_stream.txt | 95 ----- docs/strings/_index.md | 8 + docs/strings/string_stream.md | 142 +++++++ docs/strings/string_utilities.md | 620 +++++++++++++++++++++++++++++ 5 files changed, 770 insertions(+), 133 deletions(-) delete mode 100644 docs/raw/strings/Strings page.txt delete mode 100644 docs/raw/strings/string_stream.txt create mode 100644 docs/strings/string_stream.md create mode 100644 docs/strings/string_utilities.md diff --git a/docs/raw/strings/Strings page.txt b/docs/raw/strings/Strings page.txt deleted file mode 100644 index 2b48b6ea..00000000 --- a/docs/raw/strings/Strings page.txt +++ /dev/null @@ -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. - diff --git a/docs/raw/strings/string_stream.txt b/docs/raw/strings/string_stream.txt deleted file mode 100644 index 2c49a1ff..00000000 --- a/docs/raw/strings/string_stream.txt +++ /dev/null @@ -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" - diff --git a/docs/strings/_index.md b/docs/strings/_index.md index 15de8ffb..c98a25ec 100644 --- a/docs/strings/_index.md +++ b/docs/strings/_index.md @@ -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` diff --git a/docs/strings/string_stream.md b/docs/strings/string_stream.md new file mode 100644 index 00000000..d9fce919 --- /dev/null +++ b/docs/strings/string_stream.md @@ -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"`. + diff --git a/docs/strings/string_utilities.md b/docs/strings/string_utilities.md new file mode 100644 index 00000000..64b8b9c0 --- /dev/null +++ b/docs/strings/string_utilities.md @@ -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* pairsbegin, + const etl::pair* 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* pairsbegin, + const etl::pair* 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 get_token(const INPUT_TYPE& s, + const char* delimiters, + const etl::optional& 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; +using Token = etl::optional; + +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 +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::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 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. +