A C++ template library for embedded applications
MIT licensed
Join the ETL community
Designed and
maintained by
John Wellbelove
Like the ETL? Become a patron!
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, 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
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

void trim_whitespace_left(etl::istring& s)

Trims the whitespace characters from the left of s.
____________________________________________________________________________________________________
void trim_from_left(etl::istring& s,
                    etl::istring::const_pointer trim_characters)

Trims any of the characters in trim_characters from the left of s.
Stops at the first character not in trim_characters.
____________________________________________________________________________________________________
void trim_left(etl::istring& s,
               etl::istring::const_pointer delimiters)

Trims all of the characters in up to the first character in delimiters from the left of s.
____________________________________________________________________________________________________
void trim_whitespace_right(etl::istring& s)

Trims the whitespace characters from the right of s.
___________________________________________________________________________________________________
void trim_from_right(etl::istring& s,
                     etl::istring::const_pointer trim_characters)

Trims any of the characters in trim_characters from the right of s.
Stops at the first character not in trim_characters.
____________________________________________________________________________________________________
void trim_right(etl::istring& s,
                etl::istring::const_pointer delimiters)

Trims all of the characters in up to the first character in delimiters from the right of s.
____________________________________________________________________________________________________
void trim_whitespace(etl::istring& s)

Trims the whitespace characters from both ends of s.
____________________________________________________________________________________________________
void trim_from(etl::istring& s,
               etl::istring::const_pointer trim_characters)

Trims any of the characters in trim_characters from the right of s.
Stops at the first character not in trim_characters.
____________________________________________________________________________________________________
void trim(etl::istring& s,
          etl::istring::const_pointer delimiters)
Trims all of the characters in up to the first character in delimiters from both ends of s.
____________________________________________________________________________________________________
void reverse(etl::istring& s)

Reverses s.
____________________________________________________________________________________________________
void left_n(etl::istring& s,
            size_t n)

Trims s to the left n most characters.
If the string is less than n characters long then it is left unchanged.
____________________________________________________________________________________________________
void right_n(etl::istring& s,
             size_t n)

Trims s to the right n most characters.
If the string is less than n characters long then it is left unchanged.
____________________________________________________________________________________________________
void pad_left(etl::istring& s,
              size_t required_size,
              etl::istring::value_type pad_char)

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.
____________________________________________________________________________________________________
void pad_right(etl::istring& s,
               size_t required_size,
               etl::istring::value_type pad_char)

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.
____________________________________________________________________________________________________
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.
____________________________________________________________________________________________________
void to_upper_case(etl::istring& s)

Change s to upper case.
"hElLo WoRLd" => "HELLO WORLD"

Valid for etl::istring only.
____________________________________________________________________________________________________
void to_lower_case(etl::istring& s)

Change s to lower case.
"hElLo WoRLd" => "hello world"

Valid for etl::istring only.
____________________________________________________________________________________________________
void to_sentence_case(etl::istring& s)

Change s to sentence case.
"hElLo WoRLd" => "Hello world"

Valid for etl::istring only.
____________________________________________________________________________________________________
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)

pairsbegin  Pointer to the first pair in the list.
pairsend    Pointer to one past the last pair in the list.

Replaces characters according the supplied lookup table of etl::pair.
Each pair specifies an old/new character replacement.

____________________________________________________________________________________________________
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)

pairsbegin  Pointer to the first pair in the list.
pairsend    Pointer to one past the last pair in the list.

Replaces strings according the supplied lookup table of etl::pair.
Each pair specifies an old/new string replacement.
____________________________________________________________________________________________________
Non-modifying functions

etl::string_view trim_view_whitespace_left(const etl::string_view& view)

Returns a string_view of the whitespace characters trimmed from the left of view.
____________________________________________________________________________________________________
etl::string_view trim_from_view_left(const etl::string_view& view,
                                     etl::istring::const_pointer trim_characters)

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.
____________________________________________________________________________________________________
etl::string_view trim_view_left(etl::string_view& view,
                                etl::string_view::const_pointer delimiters)

Returns a string_view of the characters in up to the first character in delimiters from the left  of view.
____________________________________________________________________________________________________
etl::string_view trim_view_whitespace_right(const etl::string_view& view)

Returns a string_view of the whitespace characters trimmed from the right of view.
____________________________________________________________________________________________________
etl::string_view trim_from_view_right(const etl::string_view& view,
                                      etl::istring::const_pointer trim_characters)

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.
____________________________________________________________________________________________________
etl::string_view trim_view_right(const etl::string_view& view,
                                 etl::istring::const_pointer delimiters)

Returns a string_view of the characters in up to the first character in delimiters from the right  of view.
____________________________________________________________________________________________________
etl::string_view trim_whitespace(const etl::string_view& view)

Returns a string_view of the whitespace characters trimmed from both ends of view.
____________________________________________________________________________________________________
etl::string_view trim_view_from(const etl::string_view& view,
                                etl::istring::const_pointer trim_characters)

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.
____________________________________________________________________________________________________
etl::string_view trim(const etl::string_view& view,
                      etl::istring::const_pointer delimiters)

Returns a string_view of the characters in up to the first character in delimiters from both ends of view.
____________________________________________________________________________________________________
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.
____________________________________________________________________________________________________
etl::string_view right_n_view(etl::string_view view,
                              size_t n)

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.
____________________________________________________________________________________________________
etl::optional<etl::string_view> get_token(const etl::istring& s,
                                          etl::istring::const_pointer delimiters,
                                          const etl::optional<etl::string_view>& last_view,
                                          bool ignore_empty_tokens)
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
using String     = etl::string<32>;
using StringView = etl::string_view;
using Vector     = etl::vector<String, 10>;
using Token      = etl::optional<String>;

String text("  The cat.sat,  on;the:mat .,;:");
Vector tokens;

StringView textview(text);
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"

____________________________________________________________________________________________________
Find functions

etl::istring::iterator find_first_of(etl::istring::iterator first,
                                     etl::istring::iterator last,
                                     etl::istring::const_pointer delimiters)

Returns an iterator to the first instance of a character in delimiters.
Returns last if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_first_of(etl::istring::const_iterator first,
                                           etl::istring::const_iterator last,
                                           etl::istring::const_pointer delimiters)

Returns a const iterator to the first instance of a character in delimiters.
Returns last if not found.
____________________________________________________________________________________________________
etl::istring::iterator find_first_of(etl::istring& s,
                                     etl::istring::const_pointer delimiters)

Returns an iterator to the first instance of a character in delimiters.
Returns s.end() if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_first_of(const etl::istring& s,
                                           etl::istring::const_pointer delimiters)

Returns a const iterator to the first instance of a character in delimiters.
Returns s.end() if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_first_of(const etl::string_view& view,
                                           etl::istring::const_pointer delimiters)

Returns a const iterator to the first instance of a character in delimiters.
Returns view.end() if not found.
____________________________________________________________________________________________________
etl::istring::iterator find_first_not_of(etl::istring::iterator first,
                                         etl::istring::iterator last,
                                         etl::istring::const_pointer delimiters)

Returns an iterator to the first instance of a character not in delimiters.
Returns last if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_first_not_of(etl::istring::const_iterator first,  
                                               etl::istring::const_iterator last,
                                               etl::istring::const_pointer delimiters)

Returns a const iterator to the first instance of a character not in delimiters.
Returns last if not found.
____________________________________________________________________________________________________
etl::istring::iterator find_first_not_of(etl::istring& s,
                                         etl::istring::const_pointer delimiters)

Returns an iterator to the first instance of a character not in delimiters.
Returns s.end() if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_first_not_of(const etl::istring& s,
                                               etl::istring::const_pointer delimiters)

Returns a const iterator to the first instance of a character not in delimiters.
Returns s.end() if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_first_not_of(const etl::string_view& view,
                                               etl::istring::const_pointer delimiters)

Returns a const iterator to the first instance of a character not in delimiters.
Returns view.end() if not found.
____________________________________________________________________________________________________
etl::istring::iterator find_last_of(etl::istring::iterator first,
                                    etl::istring::iterator last,
                                    etl::istring::const_pointer delimiters)

Returns an iterator to the last instance of a character in delimiters.
Returns last if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_last_of(etl::istring::const_iterator first,
                                          etl::istring::const_iterator last,
                                          etl::istring::const_pointer delimiters)

Returns a const iterator to the last instance of a character in delimiters.
Returns last if not found.
____________________________________________________________________________________________________
etl::istring::iterator find_last_of(etl::istring& s, etl::istring::const_pointer delimiters)

Returns an iterator to the last instance of a character in delimiters.
Returns s.end() if not found.
____________________________________________________________________________________________________
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.
____________________________________________________________________________________________________
etl::istring::const_iterator find_last_of(const etl::string_view& view,
                                          etl::istring::const_pointer delimiters)

Returns a const iterator to the last instance of a character in delimiters.
Returns view.end() if not found.
____________________________________________________________________________________________________
etl::istring::iterator find_last_not_of(etl::istring::iterator first,
                                        etl::istring::iterator last,
                                        etl::istring::const_pointer delimiters)

Returns an iterator to the last instance of a character not in delimiters.
Returns last if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_last_not_of(etl::istring::const_iterator first,
                                              etl::istring::const_iterator last,
                                              etl::istring::const_pointer delimiters)

Returns a const iterator to the last instance of a character not in delimiters.
Returns last if not found.
____________________________________________________________________________________________________
etl::istring::iterator find_last_not_of(etl::istring& s,
                                        etl::istring::const_pointer delimiters)

Returns an iterator to the last instance of a character not in delimiters.
Returns last if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_last_not_of(const etl::istring& s,
                                              etl::istring::const_pointer delimiters)

Returns a const iterator to the last instance of a character not in delimiters.
Returns s.end() if not found.
____________________________________________________________________________________________________
etl::istring::const_iterator find_last_not_of(const etl::string_view& view,
                                              etl::istring::const_pointer delimiters)

Returns a const iterator to the last instance of a character not in delimiters.
Returns view.end() if not found.
string_utilities.h