utilities

The namespace for the utilities library. More...

Classes
struct	commas_facet
	A std::numpunct facet that puts the commas in the thousand spots so 10000.5 -> 10,000.5. More...
class	message
	A utilities::message object captures a location where the message was created and optionally a payload string. More...
class	stopwatch
	See the Stopwatch page for all the details. More...

Concepts
concept	has_to_string
	A concept that matches any type that has an accessible std::string to_string() const method.

Typedefs
using	precise_stopwatch = stopwatch<std::chrono::high_resolution_clock>
	Theoretically the most precise stopwatch – it might get put off by system reboots etc.
using	steady_stopwatch = stopwatch<std::chrono::steady_clock>
	A stopwatch that is guaranteed to be monotonic.
using	system_stopwatch = stopwatch<std::chrono::system_clock>
	A stopwatch that is uses the system clock.

Functions
template<typename Clock>
std::ostream &	operator<< (std::ostream &os, const stopwatch< Clock > &rhs)
	The usual output operator.
template<class Rep, class Period>
constexpr double	to_seconds (const std::chrono::duration< Rep, Period > &d)
	A convenience function that converts a std::chrono::duration to a double number of seconds.
std::string	read_line (std::istream &s, std::string_view comment_begin="#")
	Reads one 'line' from a stream and returns that as a new std::string.
std::istream &	rewind (std::istream &is)
	Rewind an input stream to the start.
std::size_t	line_count (std::istream &is, std::string_view comment_begin="#")
	Counts the number of lines in the input stream.
constexpr char32_t	to_upper (char32_t cp) noexcept
	Converts a wide character to its upper case equivalent if it is a lowercase letter.
constexpr char32_t	to_lower (char32_t cp) noexcept
	Converts a wide character to its lower case equivalent if it is a uppercase letter.
void	upper_case (std::string &str)
	Converts a string to upper case in-place.
void	lower_case (std::string &str)
	Converts a string to lower case in place.
void	trim_left (std::string &str)
	Removes any leading white-space from a string in-place.
void	trim_right (std::string &str)
	Remove any trailing white-space from a string in-place.
void	trim (std::string &str)
	Removes all leading & trailing white-space from a string in-place.
void	replace_left (std::string &str, std::string_view target, std::string_view replacement)
	Replace the first occurrence of a target substring with some other string in-place.
void	replace_right (std::string &str, std::string_view target, std::string_view replacement)
	Replace the final occurrence of a target substring with some other string in-place.
void	replace (std::string &str, std::string_view target, std::string_view replacement)
	Replace all occurrences of a target substring with some other string in-place.
void	replace_space (std::string &s, const std::string &with=" ", bool also_trim=true)
	Replace all contiguous white space sequences in a string in-place.
void	condense (std::string &s, bool also_trim=true)
	Condense contiguous white space sequences in a string in-place.
void	erase_left (std::string &str, std::string_view target)
	Erase the first occurrence of a target substring.
void	erase_right (std::string &str, std::string_view target)
	Erase the last occurrence of a target substring.
void	erase (std::string &str, std::string_view target)
	Erase all occurrences of a target substring.
void	remove_surrounds (std::string &s)
	Removes "surrounds" from a string in-place so for example: (text) -> text.
void	standardize (std::string &s)
	"Standardize" a string – turns "[ hallo world ] " or " Hallo World" into "HALLO WORLD"
std::string	upper_cased (std::string_view input)
	Returns a new string that is a copy of the input converted to upper case.
std::string	lower_cased (std::string_view input)
	Returns a new string that is a copy of the input converted to lower case.
std::string	trimmed_left (std::string_view input)
	Returns a new string that is a copy of the input with leading white-space removed.
std::string	trimmed_right (std::string_view input)
	Returns a new string that is a copy of the input with trailing white-space removed.
std::string	trimmed (std::string_view input)
	Returns a new string that is a copy of the input with all leading and trailing white-space removed.
std::string	replaced_left (std::string_view input, std::string_view target, std::string_view replacement)
	Returns a new string that is a copy of the input with the first occurrence of a target substring replaced.
std::string	replaced_right (std::string_view input, std::string_view target, std::string_view replacement)
	Returns a new string that is a copy of the input with the final occurrence of a target substring replaced.
std::string	replaced (std::string_view input, std::string_view target, std::string_view replacement)
	Returns a new string that is a copy of the input with all occurrences of a target substring replaced.
std::string	replaced_space (std::string_view input, const std::string &with=" ", bool also_trim=true)
	Returns a new string that is a copy of the input with all contiguous white space sequences replaced.
std::string	condensed (std::string_view input, bool also_trim=true)
	Returns a copy of the input with all contiguous white space sequences replaced with one space.
std::string	erased_left (std::string_view input, std::string_view target)
	Returns a new string that is a copy of the input with the first occurrence of a target substring erased.
std::string	erased_right (std::string_view input, std::string_view target)
	Returns a new string that is a copy of the input with the last occurrence of a target substring erased.
std::string	erased (std::string_view input, std::string_view target)
	Returns a new string that is a copy of the input with the all occurrence of a target substring erased.
std::string	removed_surrounds (std::string_view input)
	Returns a new string that is a copy of the input with "surrounds" stripped from it.
std::string	standardized (std::string_view input)
	Returns a "standardized" string that is a copy of the input.
bool	starts_with (std::string_view str, std::string_view prefix)
	Check if a string starts with a particular prefix string.
bool	ends_with (std::string_view str, std::string_view suffix)
	Check if a string ends with a particular suffix string.
template<typename T>
constexpr std::optional< T >	possible (std::string_view in, const char **next=nullptr)
	Try to read a value of a particular type from a string.
template<std::input_iterator InputIt, std::forward_iterator ForwardIt, typename BinaryFunc>
constexpr void	for_each_token (InputIt ib, InputIt ie, ForwardIt db, ForwardIt de, BinaryFunc function)
	Given input text and delimiters, tokenize the text and then passes the tokens to a function you supply.
template<typename Container_t>
constexpr void	tokenize (std::string_view input, Container_t &output, std::string_view delimiters="\t,;: ", bool skip=true)
	Tokenize a string and put the tokens into the supplied output container.
std::vector< std::string >	split (std::string_view input, std::string_view delimiters="\t,;: ", bool skip=true)
	Tokenize a string and return the tokens as a vector of strings.
template<typename Iter, typename Traits, typename CharT, typename UnaryFunction>
std::basic_string< CharT >	regex_replace (Iter ib, Iter ie, const std::basic_regex< CharT, Traits > &re, UnaryFunction f)
	A version of regex_replace(...) where each match in turn is is run through a function you supply.
template<typename Traits, typename CharT, typename UnaryFunction>
std::string	regex_replace (const std::string &s, const std::basic_regex< CharT, Traits > &re, UnaryFunction f)
	A version of regex_replace(...) where each match in turn is is run through a function you supply.
void	imbue_stream_with_commas (std::ios_base &strm=std::cout, bool on=true)
	Force a stream to insert commas into large numbers for readability so that 23456.7 is printed as 23,456.7.
void	imbue_global_with_commas (bool on=true)
	Force the global locale to insert commas into large numbers so that 23456.7 is printed as 23,456.7.
void	pretty_print_thousands (bool on=true)
	Force the global locale & the usual output streams to insert commas into large numbers.
template<typename T>
constexpr auto	type ()
	Returns a string representing an object's "type" as the compiler/preprocessor sees.
template<typename T>
constexpr auto	type (const T &)
	Returns a string representing an object's "type" as the compiler/preprocessor sees.

Detailed Description

The namespace for the utilities library.

Function Documentation

condense()

void utilities::condense ( std::string & s, bool also_trim = true )

inline

Condense contiguous white space sequences in a string in-place.

By default any white space at the beginning and end is removed entirely. Use the also_trim argument to change that.

Example

std::string str = "Hello,   World!  ";
utilities::condense(str);
assert_eq(str, "Hello, World!");

condensed()

std::string utilities::condensed ( std::string_view input, bool also_trim = true )

inline

Returns a copy of the input with all contiguous white space sequences replaced with one space.

By default any white space at the beginning and end is removed entirely. Use the also_trim argument to change that.

Example

std::string str = "Hello,   World!  ";
auto condensed_str = utilities::condensed(str);
assert_eq(condensed_str, "Hello, World!");

ends_with()

bool utilities::ends_with ( std::string_view str, std::string_view suffix )

inline

Check if a string ends with a particular suffix string.

Example

std::string str = "Hello, World!";
bool ends_with_world = utilities::ends_with(str, "World!");
assert_eq(ends_with_world, true);

erase()

void utilities::erase ( std::string & str, std::string_view target )

inline

Erase all occurrences of a target substring.

Example

std::string str = "abcdefghijklmnopqrstuvwxyz";
utilities::erase(str, "def");
assert_eq(str, "abcghijklmnopqrstuvwxyz");

erase_left()

void utilities::erase_left ( std::string & str, std::string_view target )

inline

Erase the first occurrence of a target substring.

Example

std::string str = "Hello, World!";
utilities::erase_left(str, "World");
assert_eq(str, "Hello, !");

erase_right()

void utilities::erase_right ( std::string & str, std::string_view target )

inline

Erase the last occurrence of a target substring.

Example

std::string str = "Hello, World!";
utilities:: erase_right(str, "World");
assert_eq(str, "Hello, !");

erased()

std::string utilities::erased ( std::string_view input, std::string_view target )

inline

Returns a new string that is a copy of the input with the all occurrence of a target substring erased.

Example

std::string str = "abcdefghijklmnopqrstuvwxyz";
auto erased_str = utilities::erased(str, "def");
assert_eq(erased_str, "abcghijklmnopqrstuvwxyz");

erased_left()

std::string utilities::erased_left ( std::string_view input, std::string_view target )

inline

Returns a new string that is a copy of the input with the first occurrence of a target substring erased.

Example

std::string str = "Hello, World!";
auto erased_left_str = utilities::erased_left(str, "World");
assert_eq(erased_left_str, "Hello, !");

erased_right()

std::string utilities::erased_right ( std::string_view input, std::string_view target )

inline

Returns a new string that is a copy of the input with the last occurrence of a target substring erased.

Example

std::string str = "Hello, World!";
auto erased_right_str = utilities::erased_right(str, "World");
assert_eq(erased_right_str, "Hello, !");

for_each_token()

template<std::input_iterator InputIt, std::forward_iterator ForwardIt, typename BinaryFunc>

void utilities::for_each_token ( InputIt ib, InputIt ie, ForwardIt db, ForwardIt de, BinaryFunc function )

constexpr

Given input text and delimiters, tokenize the text and then passes the tokens to a function you supply.

• If the text is in str this parameter might be cbegin(str).
• If the text is in str this parameter might be cend(str).
• If the possible delimiters are in delims this might be cbegin(delims).
• If the possible delimiters are in delims this might be cend(delims).
• Will be called with a token like this function(token_begin, token_end).

Credit to blog article

imbue_global_with_commas()

void utilities::imbue_global_with_commas ( bool on = true )

inline

Force the global locale to insert commas into large numbers so that 23456.7 is printed as 23,456.7.

You can set the argument to false to return the locale to its default behaviour.

This function is primarily used to get std::format & friends to work correctly with the {:L} specifier.

imbue_stream_with_commas()

void utilities::imbue_stream_with_commas ( std::ios_base & strm = std::cout, bool on = true )

inline

Force a stream to insert commas into large numbers for readability so that 23456.7 is printed as 23,456.7.

Parameters

strm	The stream you want to have this property – defaults to std::cout.
on	You can set this second argument to false to return the stream to its default behaviour.

line_count()

std::size_t utilities::line_count ( std::istream & is, std::string_view comment_begin = "#" )

inline

Counts the number of lines in the input stream.

Note

If the comment start string is empty we use std::getline to read the lines, otherwise we use our own version read_line so comment lines are excluded etc.

lower_case()

void utilities::lower_case ( std::string & str )

inline

Converts a string to lower case in place.

Uses the to_lower(...) function to convert each character to its lower case equivalent if it is an uppercase letter. Any non-ASCII, non-letter characters are left unchanged.

Example

std::string str = "HELLO, WORLD!";
utilities::lower_case(str);
assert_eq(str, "hello, world!");

lower_cased()

std::string utilities::lower_cased ( std::string_view input )

inline

Returns a new string that is a copy of the input converted to lower case.

Uses the standard C-library tolower(...) function (so will not work for wide character sets).

Example

std::string str = "Hello, World!";
auto lower_str = utilities::lower_cased(str);
assert_eq(lower_str, "hello, world!");

operator<<()

template<typename Clock>

std::ostream & utilities::operator<< ( std::ostream & os, const stopwatch< Clock > & rhs )

inline

The usual output operator.

Prints the name of the stopwatch if any followed by the elapsed time in seconds.

possible()

template<typename T>

std::optional< T > utilities::possible ( std::string_view in, const char ** next = nullptr )

constexpr

Try to read a value of a particular type from a string.

Uses std::from_chars(...) to retrieve a possible integral type from a string.

Example

std::string str = "123.456";
auto x = utilities::possible<double>(str);
assert_eq(*x, 123.456);

pretty_print_thousands()

void utilities::pretty_print_thousands ( bool on = true )

inline

Force the global locale & the usual output streams to insert commas into large numbers.

You can set the argument to false to return the locale to its default behaviour.

Example

utilities::pretty_print_thousands();
auto x_str = std::format("x = {:L}", 123456789.9);
assert_eq(x_str, "x = 123,456,789.9");

read_line()

std::string utilities::read_line ( std::istream & s, std::string_view comment_begin = "#" )

inline

Reads one 'line' from a stream and returns that as a new std::string.

By default we strip out comments that start with a '#' character and run to the end of the line. You can change the comment start character by passing a different string to comment_begin argument.

Note

Unlike the std::getline(...) this version strips trailing comments (starting with a '#' by default). It also completely ignores blank lines and assumes that lines ending with a '\' continue to the next.

regex_replace() [1/2]

template<typename Traits, typename CharT, typename UnaryFunction>

std::string utilities::regex_replace	(	const std::string &	s,
		const std::basic_regex< CharT, Traits > &	re,
		UnaryFunction	f )

A version of regex_replace(...) where each match in turn is is run through a function you supply.

• s The string to hunt for matches in.
• re The regular expression that defines the match we are after.
• f A callback function that will be passed the match and should return the desired output string.

Credit to stackoverflow article

regex_replace() [2/2]

template<typename Iter, typename Traits, typename CharT, typename UnaryFunction>

std::basic_string< CharT > utilities::regex_replace	(	Iter	ib,
		Iter	ie,
		const std::basic_regex< CharT, Traits > &	re,
		UnaryFunction	f )

A version of regex_replace(...) where each match in turn is is run through a function you supply.

• ib e.g. std::cbegin(a_string).
• ie e.g. std::cend(a_string).
• re The regular expression that defines the match we are after.
• f A callback function that will be passed the match and should return the desired output string.

Credit to stackoverflow article

remove_surrounds()

void utilities::remove_surrounds ( std::string & s )

inline

Removes "surrounds" from a string in-place so for example: (text) -> text.

Multiple surrounds also work so <<<text>>> -> text. The "surrounds" are only removed if they are correctly balanced.

Example

std::string str = "(Hello, World!)";
utilities::remove_surrounds(str);
assert_eq(str, "Hello, World!");

removed_surrounds()

std::string utilities::removed_surrounds ( std::string_view input )

inline

Returns a new string that is a copy of the input with "surrounds" stripped from it.

• Multiple surrounds also work so <<<text>>> -> text.
• The "surrounds" are only removed if they are correctly balanced.

Example

std::string str = "(Hello, World!)";
auto removed_surrounds_str = utilities::removed_surrounds(str);
assert_eq(removed_surrounds_str, "Hello, World!");

replace()

void utilities::replace ( std::string & str, std::string_view target, std::string_view replacement )

inline

Replace all occurrences of a target substring with some other string in-place.

Example

std::string str = "Hello, World! Hello, Universe!";
utilities::replace(str, "Hello", "Goodbye");
assert_eq(str, "Goodbye, World! Goodbye, Universe!");

replace_left()

void utilities::replace_left ( std::string & str, std::string_view target, std::string_view replacement )

inline

Replace the first occurrence of a target substring with some other string in-place.

Example

std::string str = "Hello, World!";
utilities::replace_left(str, "World", "Universe");
assert_eq(str, "Hello, Universe!");

replace_right()

void utilities::replace_right ( std::string & str, std::string_view target, std::string_view replacement )

inline

Replace the final occurrence of a target substring with some other string in-place.

Example

std::string str = "Hello, World!";
utilities::replace_right(str, "World", "Universe");
assert_eq(str, "Hello, Universe!");

replace_space()

void utilities::replace_space ( std::string & s, const std::string & with = " ", bool also_trim = true )

inline

Replace all contiguous white space sequences in a string in-place.

By default they are replaced with a single space character. YUse the with argument to change that.

By default any white space at the beginning and end is removed entirely. Use the also_trim argument to change that.

Example

std::string str = "    Hello   World!  ";
utilities::replace_space(str);
assert_eq(str, "Hello World!");

replaced()

std::string utilities::replaced ( std::string_view input, std::string_view target, std::string_view replacement )

inline

Returns a new string that is a copy of the input with all occurrences of a target substring replaced.

Example

std::string str = "Hello World! Hello Universe!";
auto replaced_str = utilities::replaced(str, "Hello", "Goodbye");
assert_eq(replaced_str, "Goodbye World! Goodbye Universe!");

replaced_left()

std::string utilities::replaced_left ( std::string_view input, std::string_view target, std::string_view replacement )

inline

Returns a new string that is a copy of the input with the first occurrence of a target substring replaced.

Example

std::string str = "Hello, World!";
auto replaced_str = utilities::replaced_left(str, "World", "Universe");
assert_eq(replaced_str, "Hello, Universe!");

replaced_right()

std::string utilities::replaced_right ( std::string_view input, std::string_view target, std::string_view replacement )

inline

Returns a new string that is a copy of the input with the final occurrence of a target substring replaced.

Example

std::string str = "Hello, World!";
auto replaced_str = utilities::replaced_right(str, "World", "Universe");
assert_eq(replaced_str, "Hello, Universe!");

replaced_space()

std::string utilities::replaced_space ( std::string_view input, const std::string & with = " ", bool also_trim = true )

inline

Returns a new string that is a copy of the input with all contiguous white space sequences replaced.

• By default they are replaced with a single space character. Use the with argument to change that.
• By default any white space at the beginning and end is removed entirely. Use the also_trim argument to change that.

Example

std::string str = "  Hello    World!  ";
auto replaced_space_str = utilities::replaced_space(str);
assert_eq(replaced_space_str, "Hello World!");

split()

std::vector< std::string > utilities::split ( std::string_view input, std::string_view delimiters = "\t,;: ", bool skip = true )

inline

Tokenize a string and return the tokens as a vector of strings.

• By default tokens are broken on white space, commas, semi-colons, and colons. Use the delimiters argument to change that.
• By default we ignore any empty tokens (e.g. two spaces in a row). Use the skip argument to change that.

Example

std::string str = "Hello, World";
auto tokens = utilities::split(str);
std::vector<std::string> expected = {"Hello", "World"};
assert_eq(tokens, expected);

standardize()

void utilities::standardize ( std::string & s )

inline

"Standardize" a string – turns "[ hallo world ] " or " Hallo World" into "HALLO WORLD"

Example

std::string str = "[ hallo   world ]  ";
utilities::standardize(str);
assert_eq(str, "HALLO WORLD");

standardized()

std::string utilities::standardized ( std::string_view input )

inline

Returns a "standardized" string that is a copy of the input.

For example, input "[ hallo world ]" or " Hallo World" is returned as "HALLO WORLD"

Example

std::string str = "[ hallo world ]";
auto standardized_str = utilities::standardized(str);
assert_eq(standardized_str, "HALLO WORLD");

starts_with()

bool utilities::starts_with ( std::string_view str, std::string_view prefix )

inline

Check if a string starts with a particular prefix string.

Example

std::string str = "Hello, World!";
bool starts_with_hello = utilities::starts_with(str, "Hello");
assert_eq(starts_with_hello, true);

to_lower()

char32_t utilities::to_lower ( char32_t cp )

nodiscardconstexprnoexcept

Converts a wide character to its lower case equivalent if it is a uppercase letter.

Faster than the standard C-library tolower(...) function but only works for ASCII characters.

Example

assert(utilities::to_lower('A') == 'a');
assert(utilities::to_lower('Z') == 'z');
assert(utilities::to_lower('a') == 'a');
assert(utilities::to_lower('z') == 'z');
assert(utilities::to_lower('=') == '=');

to_upper()

char32_t utilities::to_upper ( char32_t cp )

nodiscardconstexprnoexcept

Converts a wide character to its upper case equivalent if it is a lowercase letter.

Faster than the standard C-library toupper(...) function but only works for ASCII characters.

Example

assert(utilities::to_upper('a') == 'A');
assert(utilities::to_upper('z') == 'Z');
assert(utilities::to_upper('A') == 'A');
assert(utilities::to_upper('Z') == 'Z');
assert(utilities::to_upper('=') == '=');

tokenize()

template<typename Container_t>

void utilities::tokenize ( std::string_view input, Container_t & output, std::string_view delimiters = "\t,;: ", bool skip = true )

constexpr

Tokenize a string and put the tokens into the supplied output container.

• By default we ignore any empty tokens (e.g. two spaces in a row). Use the skip argument to change that.
• By default tokens are broken on white space, commas, semi-colons, and colons. Use the delimiters argument to change that.
• You pass in this "STL" container which we fill with the tokens.

Example

std::string str = "Hello, World";
std::vector<std::string> tokens;
utilities::tokenize(str, tokens);
std::vector<std::string> expected = {"Hello", "World"};
assert_eq(tokens, expected);

trim()

void utilities::trim ( std::string & str )

inline

Removes all leading & trailing white-space from a string in-place.

Example

std::string str = "  Hello, World!  ";
utilities::trim(str);
assert_eq(str, "Hello, World!");

trim_left()

void utilities::trim_left ( std::string & str )

inline

Removes any leading white-space from a string in-place.

Example

std::string str = "  Hello, World!";
utilities::trim_left(str);
assert_eq(str, "Hello, World!");

trim_right()

void utilities::trim_right ( std::string & str )

inline

Remove any trailing white-space from a string in-place.

Example

std::string str = "Hello, World!  ";
utilities::trim_right(str);
assert_eq(str, "Hello, World!");

trimmed()

std::string utilities::trimmed ( std::string_view input )

inline

Returns a new string that is a copy of the input with all leading and trailing white-space removed.

Example

std::string str = "  Hello, World!  ";
auto trimmed_str = utilities::trimmed(str);
assert_eq(trimmed_str, "Hello, World!");

trimmed_left()

std::string utilities::trimmed_left ( std::string_view input )

inline

Returns a new string that is a copy of the input with leading white-space removed.

Example

std::string str = "  Hello, World!";
auto trimmed_left_str = utilities::trimmed_left(str);
assert_eq(trimmed_left_str, "Hello, World!");

trimmed_right()

std::string utilities::trimmed_right ( std::string_view input )

inline

Returns a new string that is a copy of the input with trailing white-space removed.

Example

std::string str = "Hello, World!  ";
auto trimmed_right_str = utilities::trimmed_right(str);
assert_eq(trimmed_right_str, "Hello, World!");

upper_case()

void utilities::upper_case ( std::string & str )

inline

Converts a string to upper case in-place.

Uses the to_upper(...) function to convert each character to its upper case equivalent if it is a lowercase letter. Any non-ASCII, non-letter characters are left unchanged.

Example

std::string str = "Hello, World!";
utilities::upper_case(str);
assert_eq(str, "HELLO, WORLD!");

upper_cased()

std::string utilities::upper_cased ( std::string_view input )

inline

Returns a new string that is a copy of the input converted to upper case.

Uses the standard C-library toupper(...) function (so will not work for wide character sets).

Example

std::string str = "Hello, World!";
auto upper_str = utilities::upper_cased(str);
assert_eq(upper_str, "HELLO, WORLD!");