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!
or
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 INPUT_TYPE& s,
                                          const char* delimiters,
                                          const etl::optional<etl::string_view>& last_view,
                                          bool ignore_empty_tokens)

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