coffee/etl
1
0
Fork 0
mirror of https://github.com/ETLCPP/etl.git synced 2026-06-16 00:46:03 +08:00
Code Issues Packages Projects Releases Wiki Activity
etl/docs/strings/string_utilities.md
John Wellbelove 4a88884b39
Issue/add hugo support for documentation (#1449) 
* Add ranges

* Initial Hugo setup

* Work in progress

* Added selection for local or remote site

* Updated to 'light' theme

* Changed to using Hextra Hugo theme

* Changed to using Hextra Hugo theme

* Changed to Hextra Hugo theme

* Change to Hextra Hugo theme

* Updated Hugo setup.

* Updated Hugo setup.

# Conflicts:
#	docs/releases/_index.md

* Work in progress

* Added new fonts

Added new documentation

* Latest documentation updates

* Latest documentation updates

# Conflicts:
#	docs/containers/array.md
#	docs/containers/array_view.md
#	docs/containers/array_wrapper.md
#	docs/containers/bip_buffer_spsc_atomic.md
#	docs/containers/bitset.md
#	docs/containers/indirect_vector.md
#	docs/containers/vector.md
#	docs/getting-started/compilers.md

* Added bloom_filter markdown doc

* Added more documentation

Updated CSS for light and dark modes

* Fixed some menus

Added mode documentation files

* Updated CSS rules

Added badges to home page
Added uniqur_ptr + pool tutorial

* Fixed formatting on the home page markdown

Modified light amd dark code formatting

* Updated unique_ptr-with-pool

* Added container and shared message tutorials

* Updates to documentation

* Added const_multimap

* Updated source-formatting.md

* Added initial raw text files form Web site editor

* Innore coverage build directory

* Exported raw text documentation files from the web site editor

* Hugo updates

* Added Hugo intalation and markdown descriptions

* More addition to the documentation

* Added closure.md and updates to delegate.md

* Added format.md

* Added documentation for etl::delegate_observable, etl::function, Base64 codec

* Added io_port documentation

* Added basic_format_spec

* Added documentation for string_stream and string utilities.

* Added more documentation

Updated the documentation CSS

* Added documentation for clocks, day, duration

* Added more documentation for chrono classes

Updated callouts

* More chrono documentation

* Completed chrono documentation

* Maths functions documentation

* Completed maths documentation

* Completed maths documentation

* Completed maths documentation

* Completed maths documentation

* Added multiple documentation files

* Added iterator.md

* Added debug_count.md and versions.md

* Added debug_count.md and versions.md

* Added more documentation

* More documentation

* Added some design pattern documentation

Modified some of the layout files
Modified the About documentation

* Converted more documentation pages

Modified the site CSS

* Added more documentation

Moced some documentation files to new directories

* Added more documentation

Tweaks to CSS

* Added callback_timer_deferred_locked documentation

* Added callback_timer_locked documentation

* More documentation updates

* More documentation updates

* More documentation updates

* New documentation files.

Harmonised file name format

* New documentation files.

* Multiple document updates

* Multiple document updates

* Final conversion of web pages

* Updates before PR

* Updates before PR

* Updates before PR

# Conflicts:
#	docs/blog/_index.md

* Final pre PR updates

* Updates to message framework documentation

* Renamed directory

* Fix spelling

* Added author and date to blog files

Moved documentation files merged from development

* Fixed 'Description' typo

* Fix typos

# Conflicts:
#	docs/IO/io_port.md
#	docs/containers/sets/const-multiset.md
#	docs/containers/sets/const-set.md
#	docs/maths/correlation.md
#	docs/maths/gamma.md

* Renamed two files to lower case

* Minor renaming

* Added author and date

* Updated callout on bresenham_line.md

Added support for showing the ETL version on the documentation first page, by copying the version.txt file as a hugo asset.
Updated the Python 'update_release.py' to copy 'version.txt'

* Replace space in filename with hyphen.

Added more information to hugo-commands.md

* Replace space in filename with hyphen.

Added more information to hugo-commands.md

# Conflicts:
#	docs/getting-started/view-the-docs-locally/hugo-commands.md

* Added a link to pseudo_moving_average.md

* Updated title pages for groups

* Fixed missing 404 for non-existent pages

* Fixed coordinate variable names in the 'Calculating the intersection' example

---------

Co-authored-by: Roland Reichwein <Roland.Reichwein@bmw.de>
Co-authored-by: John Wellbelove <john.wellbelove@etlcpp.com>
Co-authored-by: John Wellbelove <john.wellbelove@etlcpp.co.uk>
2026-06-06 13:12:44 +01:00

621 lines
18 KiB
Markdown
Raw Blame History

---
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`.
---
```cpp
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.
Reference in New Issue View Git Blame Copy Permalink