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

Collaboration diagram for String Processing:

Detailed Description

Utility functions for working with std::string.

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

enum	CaseSensitivity { CaseSensitive = 0 , CaseInsensitive = 1 }
	Enumeration for levenshteinDistance.

Functions
void	replaceAll (std::string &str, std::string_view from, std::string_view to)
	Replaces all occurrences of from in str with to.

std::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	removeLetters (std::string &str)
	Removes all alphabetic characters in place.

std::string	fromDurationMs (double durationInMilliseconds)
	Convert a duration in milliseconds to a human-readable string with days, hours, minutes where applicable.

std::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	ordinal (int num)
	Convert an integer number to its ordinal number string representation, such as "1st", "2nd", "3rd", "4th", etc.

int	naturalCompare (const std::string &str1, const std::string &str2)
	Compare two strings according to the natural sort order.

int	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	iEquals (std::string_view a, std::string_view b)
	Compares both strings case insensitive, returns true if they are the same (case insensitive)

bool	startsWith (std::string_view str, std::string_view prefix)
	Checks whether the input string has the given prefix.

bool	iStartsWith (std::string_view str, std::string_view prefix)
	Checks whether the input string has the given prefix, ignoring case (case-insensitive).

bool	endsWith (std::string_view str, std::string_view suffix)
	Checks whether the input string has the given suffix.

bool	iEndsWith (std::string_view str, std::string_view suffix)
	Checks whether the input string has the given suffix, ignoring case (case-insensitive).

bool	contains (std::string_view str, std::string_view substring)
	Checks whether the input string contains the given substring.

bool	iContains (std::string_view str, std::string_view substring)
	Checks whether the input string contains the given substring, ignoring case (case-insensitive).

bool	containsAnyOf (std::string_view str, std::string_view characters)
	Checks whether the input string contains any of the given characters.

bool	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	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	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	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	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	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	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	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	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	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	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	toLower (std::string &input)
	Convert the input string to lower case characters.

void	toUpper (std::string &input)
	Convert the input string to upper case characters.

std::string	toLowerCopy (std::string_view input)
	Convert the input string to lower case characters.

std::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	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	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	join (const std::initializer_list< T > &list, const std::string &sep)
	Helper methods for initializer lists.

std::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 >	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 >	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 >	splitCamelCase (const std::string &input)
	Split camel case string into words.

Enumeration Type Documentation

◆ SplitOptions

enum 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 > 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 > 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 > 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 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 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 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 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 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 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 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()