mirror of
https://github.com/ETLCPP/etl.git
synced 2026-06-27 21:08:44 +08:00
407 lines
21 KiB
Plaintext
407 lines
21 KiB
Plaintext
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"
|
|
____________________________________________________________________________________________________
|
|
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
|
|
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.
|
|
|
|
Returns 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
|
|
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
|
|
|
|
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.
|
|
|