Utility functions for working with std::string. More...

Collaboration diagram for String Processing:

Detailed Description

Utility functions for working with std::string.

Enumerations
enum	ImFusion::String::SplitOptions { ImFusion::String::Default = 0 , ImFusion::String::AnyOf = 1 << 0 , ImFusion::String::IgnoreEmptyParts = 1 << 1 , ImFusion::String::TrimWhitespace = 1 << 2 }
	Bitflag enumeration for String::split(). More...
enum	ImFusion::String::CaseSensitivity { CaseSensitive = 0 , CaseInsensitive = 1 }
	Enumeration for levenshteinDistance.

Functions
void	ImFusion::String::replaceAll (std::string &str, std::string_view from, std::string_view to)
	Replaces all occurrences of from in str with to.
std::string	ImFusion::String::replaceAllCopy (std::string_view str, std::string_view from, std::string_view to)
	Returns a copy of str with all occurrences of replaced by to.
void	ImFusion::String::removeLetters (std::string &str)
	Removes all alphabetic characters in place.
std::string	ImFusion::String::fromDurationMs (double durationInMilliseconds)
	Convert a duration in milliseconds to a human-readable string with days, hours, minutes where applicable.
std::string	ImFusion::String::fromDouble (double value, std::optional< int > maxDecimals=std::nullopt)
	Convert a double to a string representation, with a limited max number of decimals.
std::string	ImFusion::String::ordinal (int num)
	Convert an integer number to its ordinal number string representation, such as "1st", "2nd", "3rd", "4th", etc.
int	ImFusion::String::naturalCompare (const std::string &str1, const std::string &str2)
	Compare two strings according to the natural sort order.
int	ImFusion::String::levenshteinDistance (const std::string &source, const std::string &target, CaseSensitivity sensitivity=CaseSensitive)
	Computes the Levenshtein distance (also known as Edit distance) between two strings.

Comparison and substring search
bool	ImFusion::String::iEquals (std::string_view a, std::string_view b)
	Compares both strings case insensitive, returns true if they are the same (case insensitive).
bool	ImFusion::String::startsWith (std::string_view str, std::string_view prefix)
	Checks whether the input string has the given prefix.
bool	ImFusion::String::iStartsWith (std::string_view str, std::string_view prefix)
	Checks whether the input string has the given prefix, ignoring case (case-insensitive).
bool	ImFusion::String::endsWith (std::string_view str, std::string_view suffix)
	Checks whether the input string has the given suffix.
bool	ImFusion::String::iEndsWith (std::string_view str, std::string_view suffix)
	Checks whether the input string has the given suffix, ignoring case (case-insensitive).
bool	ImFusion::String::contains (std::string_view str, std::string_view substring)
	Checks whether the input string contains the given substring.
bool	ImFusion::String::iContains (std::string_view str, std::string_view substring)
	Checks whether the input string contains the given substring, ignoring case (case-insensitive).
bool	ImFusion::String::containsAnyOf (std::string_view str, std::string_view characters)
	Checks whether the input string contains any of the given characters.
bool	ImFusion::String::iContainsAnyOf (std::string_view str, std::string_view characters)
	Checks whether the input string contains any of the given characters, ignoring case (case-insensitive).
bool	ImFusion::String::matchesPattern (std::string_view str, std::string_view pattern)
	Checks if a string matches a pattern containing * and ? wildcards.

Remove whitespace at the ends
void	ImFusion::String::trim (std::string &str, std::string_view whitespace=" \t\f\v\r\n")
	Removes all leading and trailing occurrences of the characters in whitespace from str in-place.
void	ImFusion::String::ltrim (std::string &str, std::string_view whitespace=" \t\f\v\r\n")
	Removes all leading occurrences of the characters in whitespace from str in-place.
void	ImFusion::String::rtrim (std::string &str, std::string_view whitespace=" \t\f\v\r\n")
	Removes all trailing occurrences of the characters in whitespace from str in-place.
std::string	ImFusion::String::trimCopy (std::string_view str, std::string_view whitespace=" \t\f\v\r\n")
	Returns a copy of str with all leading and trailing occurrences of whitespace removed.
std::string	ImFusion::String::ltrimCopy (std::string_view str, std::string_view whitespace=" \t\f\v\r\n")
	Returns a copy of str with all leading occurrences of the characters in whitespace removed.
std::string	ImFusion::String::rtrimCopy (std::string_view str, std::string_view whitespace=" \t\f\v\r\n")
	Returns a copy of str with all trailing occurrences of the characters in whitespace removed.
std::string_view	ImFusion::String::trimRef (std::string_view str, std::string_view whitespace=" \t\f\v\r\n")
	Returns a std::string_view into the input string where all leading and trailing occurrences of whitespace are removed.
std::string_view	ImFusion::String::ltrimRef (std::string_view str, std::string_view whitespace=" \t\f\v\r\n")
	Returns a std::string_view into the input string where all leading occurrences of whitespace are removed.
std::string_view	ImFusion::String::rtrimRef (std::string_view str, std::string_view whitespace=" \t\f\v\r\n")
	Returns a std::string_view into the input string where all trailing occurrences of whitespace are removed.

Change capitalization of 7 bit ASCII strings
void	ImFusion::String::toLower (std::string &input)
	Convert the input string to lower case characters.
void	ImFusion::String::toUpper (std::string &input)
	Convert the input string to upper case characters.
std::string	ImFusion::String::toLowerCopy (std::string_view input)
	Convert the input string to lower case characters.
std::string	ImFusion::String::toUpperCopy (std::string_view input)
	Convert the input string to upper case characters.

Split strings into individual elements and vice-versa
template<typename Container, typename UnaryOperation>
std::string	ImFusion::String::join (const Container &list, UnaryOperation unary_op, const std::string &sep)
	Joins the list to a string and separates the elements with sep.
template<typename C>
std::string	ImFusion::String::join (const C &list, const std::string &sep)
	Joins the list to a string and separates the elements with sep.
template<typename T>
std::string	ImFusion::String::join (const std::initializer_list< T > &list, const std::string &sep)
	Helper methods for initializer lists.
std::string	ImFusion::String::joinNonEmpty (const std::vector< std::string > &vec, const std::string &sep="")
	Joins a vector of strings together, interposing a separator (empty by default).
std::vector< std::string >	ImFusion::String::split (std::string_view input, std::string_view separator, Flags< SplitOptions > splitOptions=SplitOptions::Default)
	Splits input into substrings based on the given separator and splitOptions.
std::vector< std::string_view >	ImFusion::String::splitRef (std::string_view input, std::string_view separator, Flags< SplitOptions > splitOptions=SplitOptions::Default)
	Splits input into substring views based on the given separator and splitOptions.
std::vector< std::string >	ImFusion::String::splitCamelCase (const std::string &input)
	Split camel case string into words.

Enumeration Type Documentation

◆ SplitOptions

enum ImFusion::String::SplitOptions

#include <ImFusion/Core/String.h>

Bitflag enumeration for String::split().

Enumerator
Default	Use the whole separator string as delimiter, keep empty parts.
AnyOf	Use any character in the separator string as possible delimiter.
IgnoreEmptyParts	Do not add empty strings to the result vector.
TrimWhitespace	Trim any whitespace ( \t\f\v\r\n) from the individual substrings.

Function Documentation

◆ iEquals()

bool ImFusion::String::iEquals	(	std::string_view	a,
		std::string_view	b )

#include <ImFusion/Core/String.h>

Compares both strings case insensitive, returns true if they are the same (case insensitive).

Note: Will use the current locale and is only guaranteed to work on 7 bit ASCII characters.

Parameters

a	First string to compare
b	Second string to compare

◆ iStartsWith()

bool ImFusion::String::iStartsWith	(	std::string_view	str,
		std::string_view	prefix )

#include <ImFusion/Core/String.h>

Checks whether the input string has the given prefix, ignoring case (case-insensitive).

Note: Will use the current locale and is only guaranteed to work on 7 bit ASCII characters.

◆ iEndsWith()

bool ImFusion::String::iEndsWith	(	std::string_view	str,
		std::string_view	suffix )

#include <ImFusion/Core/String.h>

Checks whether the input string has the given suffix, ignoring case (case-insensitive).

Note: Will use the current locale and is only guaranteed to work on 7 bit ASCII characters.

◆ iContains()

bool ImFusion::String::iContains	(	std::string_view	str,
		std::string_view	substring )

#include <ImFusion/Core/String.h>

Checks whether the input string contains the given substring, ignoring case (case-insensitive).

Note: Will use the current locale and is only guaranteed to work on 7 bit ASCII characters.

◆ iContainsAnyOf()

bool ImFusion::String::iContainsAnyOf	(	std::string_view	str,
		std::string_view	characters )

#include <ImFusion/Core/String.h>

Checks whether the input string contains any of the given characters, ignoring case (case-insensitive).

Note: Will use the current locale and is only guaranteed to work on 7 bit ASCII characters.

◆ matchesPattern()

bool ImFusion::String::matchesPattern	(	std::string_view	str,
		std::string_view	pattern )

#include <ImFusion/Core/String.h>

Checks if a string matches a pattern containing * and ? wildcards.

This function matches the input string str against the given pattern, where the pattern may contain zero or more wildcard characters. Each * matches any sequence of characters (including the empty sequence). Each ? matches any character exactly once.

Parameters

str	The input string to match.
pattern	The pattern string, possibly containing * and ? wildcards.

Returns: True if str matches pattern, false otherwise.

◆ trim()

void ImFusion::String::trim	(	std::string &	str,
		std::string_view	whitespace = " \t\f\v\r\n" )

#include <ImFusion/Core/String.h>

Removes all leading and trailing occurrences of the characters in whitespace from str in-place.

Parameters

str	The string to trim.
whitespace	Set of whitespace characters which shall be removed at the beginning and the end.

◆ ltrim()

void ImFusion::String::ltrim	(	std::string &	str,
		std::string_view	whitespace = " \t\f\v\r\n" )

#include <ImFusion/Core/String.h>

Removes all leading occurrences of the characters in whitespace from str in-place.

Parameters

str	The string to trim.
whitespace	Set of whitespace characters which shall be removed at the beginning.

◆ rtrim()

void ImFusion::String::rtrim	(	std::string &	str,
		std::string_view	whitespace = " \t\f\v\r\n" )

#include <ImFusion/Core/String.h>

Removes all trailing occurrences of the characters in whitespace from str in-place.

Parameters

str	The string to trim.
whitespace	Set of whitespace characters which shall be removed at the end.

◆ trimCopy()

std::string ImFusion::String::trimCopy	(	std::string_view	str,
		std::string_view	whitespace = " \t\f\v\r\n" )

#include <ImFusion/Core/String.h>

Returns a copy of str with all leading and trailing occurrences of whitespace removed.

Parameters

str	The string to trim.
whitespace	Set of whitespace characters which shall be removed at the beginning and the end.

◆ ltrimCopy()

std::string ImFusion::String::ltrimCopy	(	std::string_view	str,
		std::string_view	whitespace = " \t\f\v\r\n" )

#include <ImFusion/Core/String.h>

Returns a copy of str with all leading occurrences of the characters in whitespace removed.

Parameters

str	The string to trim.
whitespace	Set of whitespace characters which shall be removed at the beginning.

◆ rtrimCopy()

std::string ImFusion::String::rtrimCopy	(	std::string_view	str,
		std::string_view	whitespace = " \t\f\v\r\n" )

#include <ImFusion/Core/String.h>

Returns a copy of str with all trailing occurrences of the characters in whitespace removed.

Parameters

str	The string to trim.
whitespace	Set of whitespace characters which shall be removed at the end.

◆ trimRef()

std::string_view ImFusion::String::trimRef	(	std::string_view	str,
		std::string_view	whitespace = " \t\f\v\r\n" )

#include <ImFusion/Core/String.h>

Returns a std::string_view into the input string where all leading and trailing occurrences of whitespace are removed.

Parameters

str	The string to trim.
whitespace	Set of whitespace characters which shall be removed at the beginning and the end.

◆ ltrimRef()

std::string_view ImFusion::String::ltrimRef	(	std::string_view	str,
		std::string_view	whitespace = " \t\f\v\r\n" )

#include <ImFusion/Core/String.h>

Returns a std::string_view into the input string where all leading occurrences of whitespace are removed.

Parameters

str	The string to trim.
whitespace	Set of whitespace characters which shall be removed at the beginning and the end.

◆ rtrimRef()

std::string_view ImFusion::String::rtrimRef	(	std::string_view	str,
		std::string_view	whitespace = " \t\f\v\r\n" )

#include <ImFusion/Core/String.h>

Returns a std::string_view into the input string where all trailing occurrences of whitespace are removed.

Parameters

str	The string to trim.
whitespace	Set of whitespace characters which shall be removed at the beginning and the end.

◆ toLower()

void ImFusion::String::toLower ( std::string & input )

#include <ImFusion/Core/String.h>

Convert the input string to lower case characters.

Note: Will use the current locale and is only guaranteed to work on 7 bit ASCII characters.

◆ toUpper()

void ImFusion::String::toUpper ( std::string & input )

#include <ImFusion/Core/String.h>

Convert the input string to upper case characters.

Note: Will use the current locale and is only guaranteed to work on 7 bit ASCII characters.

◆ toLowerCopy()

std::string ImFusion::String::toLowerCopy ( std::string_view input )

#include <ImFusion/Core/String.h>

Convert the input string to lower case characters.

Note: Will use the current locale and is only guaranteed to work on 7 bit ASCII characters.

◆ toUpperCopy()

std::string ImFusion::String::toUpperCopy ( std::string_view input )

#include <ImFusion/Core/String.h>

Convert the input string to upper case characters.

Note: Will use the current locale and is only guaranteed to work on 7 bit ASCII characters.

◆ join() [1/2]

template<typename Container, typename UnaryOperation>

std::string ImFusion::String::join	(	const Container &	list,
		UnaryOperation	unary_op,
		const std::string &	sep )

inline

#include <ImFusion/Core/String.h>

Joins the list to a string and separates the elements with sep.

Each element is converted with unary_op to a string.

Example:

std::vector vec({1, 2, 3, 4});

join(vec, [](int i) { return std::to_string(i); }, "/");

ImFusion::String::join

std::string join(const Container &list, UnaryOperation unary_op, const std::string &sep)

Joins the list to a string and separates the elements with sep.

Definition String.h:190

std::to_string

T to_string(T... args)

std::vector

-> "1/2/3/4"

◆ join() [2/2]

template<typename C>

std::string ImFusion::String::join	(	const C &	list,
		const std::string &	sep )

inline

#include <ImFusion/Core/String.h>

Joins the list to a string and separates the elements with sep.

Each element is converted by std::stringstream to a string.

Example:

std::vector vec({1, 2, 3, 4});

String::join(vec, "/");

-> "1/2/3/4"

◆ joinNonEmpty()

std::string ImFusion::String::joinNonEmpty	(	const std::vector< std::string > &	vec,
		const std::string &	sep = "" )

#include <ImFusion/Core/String.h>

Joins a vector of strings together, interposing a separator (empty by default).

Empty strings will not turn into a duplicated separator.

◆ split()

std::vector< std::string > ImFusion::String::split	(	std::string_view	input,
		std::string_view	separator,
		Flags< SplitOptions >	splitOptions = SplitOptions::Default )

#include <ImFusion/Core/String.h>

Splits input into substrings based on the given separator and splitOptions.

Parameters

input	Input string
separator	Delimiter string, splitOptions defines whether the whole string or any of its characters is used as delimiter. If separator is empty the entire input string is returned without any splits.
splitOptions	Selected flags defining how to interpret separator, whether or not to ignore empty strings in the result, and whether or not to trim the individual substrings.

◆ splitRef()

std::vector< std::string_view > ImFusion::String::splitRef	(	std::string_view	input,
		std::string_view	separator,
		Flags< SplitOptions >	splitOptions = SplitOptions::Default )

#include <ImFusion/Core/String.h>

Splits input into substring views based on the given separator and splitOptions.

Parameters

input	Input string
separator	Delimiter string, splitOptions defines whether the whole string or any of its characters is used as delimiter. If separator is empty the entire input string is returned without any splits.
splitOptions	Selected flags defining how to interpret separator, whether or not to ignore empty strings in the result, and whether or not to trim the individual substrings.

Warning: This function returns a list of string_views which are valid as long as input exists. Changing or destroying input afterwards will cause all return values to be dangling pointers. Use split() if you can not guarantee this invariant.

◆ splitCamelCase()

std::vector< std::string > ImFusion::String::splitCamelCase ( const std::string & input )

#include <ImFusion/Core/String.h>

Split camel case string into words.

Parameters

input The input string to split.

Returns: A vector of strings, each representing a word from the input string.

The input string will be split at each uppercase letter following anything else than an uppercase letter. The first letter of each word will be uppercase. E.g. "CamelCaseString" -> {"Camel", "Case", "String"}, "CamelCase123MPR" -> {"Camel", "Case123", "MPR"}, "camelCase" -> {"Camel", "Case"}

◆ replaceAll()

void ImFusion::String::replaceAll	(	std::string &	str,
		std::string_view	from,
		std::string_view	to )

#include <ImFusion/Core/String.h>

Replaces all occurrences of from in str with to.

Parameters

str	String to perform replacement on.
from	String to be replaced.
to	String replace.

◆ replaceAllCopy()

std::string ImFusion::String::replaceAllCopy	(	std::string_view	str,
		std::string_view	from,
		std::string_view	to )

#include <ImFusion/Core/String.h>

Returns a copy of str with all occurrences of replaced by to.

Parameters

str	String to perform replacement on.
from	String to be replaced.
to	String replace.

◆ removeLetters()

void ImFusion::String::removeLetters ( std::string & str )

#include <ImFusion/Core/String.h>

Removes all alphabetic characters in place.

Parameters

str	The string from which all alphabetic characters should be removed.

◆ fromDurationMs()

std::string ImFusion::String::fromDurationMs ( double durationInMilliseconds )

#include <ImFusion/Core/String.h>

Convert a duration in milliseconds to a human-readable string with days, hours, minutes where applicable.

Parameters

durationInMilliseconds Double to be converted into a string.

◆ fromDouble()

std::string ImFusion::String::fromDouble	(	double	value,
		std::optional< int >	maxDecimals = std::nullopt )

#include <ImFusion/Core/String.h>

Convert a double to a string representation, with a limited max number of decimals.

When maxDecimals is not provided, it is equivalent to std::numeric_limits<double>::digits10. The returned string always uses '.' separation to avoid region-dependent bugs. "NAN", "INF" or "-INF" may be returned as special cases. The returned string also has the property of containing a minimum amount of characters, for example:

0 -> "14"
10 -> "14.1"
1 -> "14.1"

Parameters

value Double to be converted into a string.

maxDecimals Max number of decimals that the returned string may contain. If the value can only be represented in scientific notation, then this function returns a scientific notation and this argument determines the number of decimals in the significand part. This argument is clipped between 0 and std::numeric_limits<double>::max_digits10. When not provided, it is equivalent to std::numeric_limits<double>::digits10. The roundtrip "double -> string -> double" is only guaranteed with std::numeric_limits<double>::max_digits10. The roundtrip "string -> double -> string" is only guaranteed with std::numeric_limits<double>::digits10. However, with std::numeric_limits<double>::digits10 this function returns a string such that the roundtrip "double -> string -> double" is still a valid double.

◆ naturalCompare()

int ImFusion::String::naturalCompare	(	const std::string &	str1,
		const std::string &	str2 )

#include <ImFusion/Core/String.h>

Compare two strings according to the natural sort order.

The natural sort order is the same as the alphanumerical sort order except that multi-digit numbers are treated atomically. E.g.:

ab2 < xd2 < xd10
x1y < x02y < x10y
01 < 10 < 0012

Returns

1 if str1 > str2
-1 if str1 < str2
0 if str1 == str2

◆ levenshteinDistance()

int ImFusion::String::levenshteinDistance	(	const std::string &	source,
		const std::string &	target,
		CaseSensitivity	sensitivity = CaseSensitive )

#include <ImFusion/Core/String.h>

Computes the Levenshtein distance (also known as Edit distance) between two strings.

This distance is the minimal number of character edits (replacement, insertion, deletion) that are needed to map the source string to the target string. For example, the distance between the string "heard" and "bird" would be 3 (two substitutions and one deletion).

Detailed Description

Enumerations

Functions

Comparison and substring search

Remove whitespace at the ends

Change capitalization of 7 bit ASCII strings

Split strings into individual elements and vice-versa

Enumeration Type Documentation

◆ SplitOptions

Function Documentation

◆ iEquals()

◆ iStartsWith()

◆ iEndsWith()

◆ iContains()

◆ iContainsAnyOf()

◆ matchesPattern()

◆ trim()

◆ ltrim()

◆ rtrim()

◆ trimCopy()

◆ ltrimCopy()

◆ rtrimCopy()

◆ trimRef()

◆ ltrimRef()

◆ rtrimRef()

◆ toLower()

◆ toUpper()

◆ toLowerCopy()

◆ toUpperCopy()

◆ join() [1/2]

◆ join() [2/2]

◆ joinNonEmpty()

◆ split()

◆ splitRef()

◆ splitCamelCase()

◆ replaceAll()

◆ replaceAllCopy()

◆ removeLetters()

◆ fromDurationMs()

◆ fromDouble()

◆ naturalCompare()

◆ levenshteinDistance()