Provides string algorithms. More...

Modules
	String classification function objects
	Provides string related function objects for classification.

Classes
struct	gears::string::is_any_of< CharT >
	Function object to check a character is any of the provided. More...

Functions
template<typename String >
meta::Unqualified< String >	gears::string::to_lower (String str, const std::locale &loc=std::locale())
	Turns a string to lower case. More...

template<typename String >
meta::Unqualified< String >	gears::string::to_upper (String str, const std::locale &loc=std::locale())
	Turns a string to upper case. More...

template<typename String >
bool	gears::string::is_all_lower (const String &str, const std::locale &loc=std::locale())
	Checks if a string is all lower case. More...

template<typename String >
bool	gears::string::is_all_upper (const String &str, const std::locale &loc=std::locale())
	Checks if a string is all upper case. More...

template<typename String , typename UnaryPredicate >
string_find_detail::SizeType < String >	gears::string::find_first_of (const String &str, UnaryPredicate &&pred)
	Find first occurrence of a predicate being met. More...

template<typename String , typename UnaryPredicate >
string_find_detail::SizeType < String >	gears::string::find_first_not_of (const String &str, UnaryPredicate &&pred)
	Find first occurrence of a predicate not being met. More...

template<typename String , typename UnaryPredicate >
string_find_detail::SizeType < String >	gears::string::find_last_of (const String &str, UnaryPredicate &&pred)
	Find last occurrence of a predicate being met. More...

template<typename String , typename UnaryPredicate >
string_find_detail::SizeType < String >	gears::string::find_last_not_of (const String &str, UnaryPredicate &&pred)
	Find last occurrence of a predicate not being met. More...

template<typename Target , typename CharT >
Target	gears::string::lexical_cast (const std::basic_string< CharT > &str)
	Converts a string to its integral representation. More...

template<typename String >
bool	gears::string::iequal (const String &lhs, const String &rhs, const std::locale &loc=std::locale())
	Checks if the strings are case insensitive equal. More...

template<typename String >
bool	gears::string::starts_with (const String &str, const String &other)
	Checks if a string starts with another string. More...

template<typename String >
bool	gears::string::istarts_with (const String &str, const String &other, const std::locale &loc=std::locale())
	Checks if a string starts with another string in a case insensitive way. More...

template<typename String >
bool	gears::string::ends_with (const String &str, const String &other)
	Checks if a string ends with another string. More...

template<typename String >
bool	gears::string::iends_with (const String &str, const String &other, const std::locale &loc=std::locale())
	Checks if a string ends with another string in a case insensitive way. More...

template<typename String >
bool	gears::string::contains (const String &str, const String &other)
	Checks if a string is a substring of another. More...

template<typename String >
bool	gears::string::icontains (const String &str, const String &other, const std::locale &loc=std::locale())
	Checks in a case insensitive way if a string is a substring of another. More...

template<typename String , typename UnaryPredicate >
bool	gears::string::all (const String &str, UnaryPredicate &&pred)
	Checks if a string meets a predicate. More...

template<typename String >
meta::Unqualified< String >	gears::string::replace_first (String str, const String &from, const String &to)
	Replace first occurrence of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::replace_last (String str, const String &from, const String &to)
	Replace last occurrence of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::replace_nth (String str, size_t nth, const String &from, const String &to)
	Replace Nth occurrence of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::replace_all (String str, const String &from, const String &to)
	Replace all occurrences of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::erase_first (String str, const String &erase)
	Erases the first occurrence of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::erase_last (String str, const String &erase)
	Erases the last occurrence of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::erase_nth (String str, size_t nth, const String &erase)
	Erases the Nth occurrence of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::erase_all (String str, const String &erase)
	Erases all occurrences of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::left (String str, size_t n)
	Returns the left portion of a string. More...

template<typename String >
meta::Unqualified< String >	gears::string::right (String str, size_t n)
	Returns the right portion of a string. More...

template<typename String >
meta::Unqualified< String >	gears::string::reverse (String str)
	Reverses a string. More...

template<typename String , typename Cont >
meta::Unqualified< String >	gears::string::join (const Cont &cont, const String &sep)
	Joins a container together with a separator. More...

template<typename String , typename Cont , typename UnaryPredicate >
meta::Unqualified< String >	gears::string::join_if (const Cont &cont, const String &sep, UnaryPredicate &&pred)
	Joins a container together with a separator and a filter. More...

template<typename String , typename OutIt >
OutIt	gears::string::split (const String &str, const String &sep, OutIt it)
	Splits a string into a container. More...

template<typename String , typename UnaryPredicate >
meta::Unqualified< String >	gears::string::trim_left_if (String str, UnaryPredicate &&pred)
	Removes the left part of the string until the predicate is met. More...

template<typename String , typename UnaryPredicate >
meta::Unqualified< String >	gears::string::trim_right_if (String str, UnaryPredicate &&pred)
	Removes the right part of the string until the predicate is met. More...

template<typename String , typename UnaryPredicate >
meta::Unqualified< String >	gears::string::trim_if (String &&str, UnaryPredicate &&pred)
	Removes both the left and the right part of the string given a predicate. More...

template<typename String >
meta::Unqualified< String >	gears::string::trim_left (String &&str, const std::locale &loc=std::locale())
	Removes the space characters from the left of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::trim_right (String &&str, const std::locale &loc=std::locale())
	Removes the space characters from the right of the string. More...

template<typename String >
meta::Unqualified< String >	gears::string::trim (String &&str, const std::locale &loc=std::locale())
	Removes the space characters from both the left and right of the string. More...

Detailed Description

This module provides string algorithms to help with the lack of high level algorithms with std::string. All the functions do not modify the string in-place and instead return a new string.

Under the <gears/string/literals.hpp> header there is a user defined literal _s to help construct a string easier. It's provided for all basic_string types, e.g. std::wstring, std::string, etc.

using namespace gears::string::literals; // required

auto str = "hello world"_s; // decltype(str) is std::string

Function Documentation

template<typename String , typename UnaryPredicate >

bool gears::string::all	(	const String &	str,
		UnaryPredicate &&	pred
	)

inline

Checks if a string meets a predicate.

Parameters

str	The string to search through.
pred	The predicate to use.

Returns: true if the string meets the predicate on every character, false otherwise.

Definition at line 240 of file predicate.hpp.

template<typename String >

bool gears::string::contains	(	const String &	str,
		const String &	other
	)

inline

Checks if a string is a substring of another. It is a wrapper around std::basic_string::find except it returns a boolean rather than std::basic_string::size_t.

Parameters

str	The string to search through.
other	The substring to find.

Returns: true if the substring is found, false otherwise.

Definition at line 196 of file predicate.hpp.

template<typename String >

bool gears::string::ends_with	(	const String &	str,
		const String &	other
	)

inline

Checks if a string ends with another string.

Example:

bool t = string::ends_with("hello world"_s, "world"_s); // true

Parameters

str	The string to search through.
other	The string to find.

Returns: true if the string ends with other, false otherwise.

Definition at line 147 of file predicate.hpp.

template<typename String >

meta::Unqualified<String> gears::string::erase_all	(	String	str,
		const String &	erase
	)

inline

Erases all occurrences of the string. When erasing, the string is deleted. It is as if called with replace with an empty string.

Parameters

str	The string to do the searching and erasing on.
erase	The string to erase.

Returns: A new string with the erased occurrences removed.

Definition at line 195 of file replace.hpp.

template<typename String >

meta::Unqualified<String> gears::string::erase_first	(	String	str,
		const String &	erase
	)

inline

Erases the first occurrence of the string. When erasing, the string is deleted. It is as if called with replace with an empty string.

Parameters

str	The string to do the searching and erasing on.
erase	The string to erase.

Returns: A new string with the erased occurrences removed.

Definition at line 134 of file replace.hpp.

template<typename String >

meta::Unqualified<String> gears::string::erase_last	(	String	str,
		const String &	erase
	)

inline

Erases the last occurrence of the string. When erasing, the string is deleted. It is as if called with replace with an empty string.

Parameters

str	The string to do the searching and erasing on.
erase	The string to erase.

Returns: A new string with the erased occurrences removed.

Definition at line 154 of file replace.hpp.

template<typename String >

meta::Unqualified<String> gears::string::erase_nth	(	String	str,
		size_t	nth,
		const String &	erase
	)

inline

Erases the Nth occurrence of the string. When erasing, the string is deleted. It is as if called with replace with an empty string.

Parameters

str	The string to do the searching and erasing on.
nth	The Nth occurrence.
erase	The string to erase.

Returns: A new string with the erased occurrences removed.

Definition at line 175 of file replace.hpp.

template<typename String , typename UnaryPredicate >

string_find_detail::SizeType<String> gears::string::find_first_not_of	(	const String &	str,
		UnaryPredicate &&	pred
	)

inline

Find first occurrence of a predicate not being met.

Predicate must have the the prototype of bool(CharT).

Parameters

str	String to search through.
pred	Predicate to use.

Returns: The position found of the predicate not being met. If not found, returns String::npos.

Definition at line 76 of file find.hpp.

template<typename String , typename UnaryPredicate >

string_find_detail::SizeType<String> gears::string::find_first_of	(	const String &	str,
		UnaryPredicate &&	pred
	)

inline

Find first occurrence of a predicate being met.

Predicate must have the the prototype of bool(CharT).

Parameters

str	String to search through.
pred	Predicate to use.

Returns: The position found of the predicate being met. If not found, returns String::npos.

Definition at line 56 of file find.hpp.

template<typename String , typename UnaryPredicate >

string_find_detail::SizeType<String> gears::string::find_last_not_of	(	const String &	str,
		UnaryPredicate &&	pred
	)

inline

Find last occurrence of a predicate not being met.

Predicate must have the the prototype of bool(CharT).

Parameters

str	String to search through.
pred	Predicate to use.

Returns: The position found of the predicate not being met. If not found, returns String::npos.

Definition at line 112 of file find.hpp.

template<typename String , typename UnaryPredicate >

string_find_detail::SizeType<String> gears::string::find_last_of	(	const String &	str,
		UnaryPredicate &&	pred
	)

inline

Find last occurrence of a predicate being met.

Predicate must have the the prototype of bool(CharT).

Parameters

str	String to search through.
pred	Predicate to use.

Returns: The position found of the predicate being met. If not found, returns String::npos.

Definition at line 92 of file find.hpp.

template<typename String >

bool gears::string::icontains	(	const String &	str,
		const String &	other,
		const std::locale &	loc = `std::locale()`
	)

inline

Checks in a case insensitive way if a string is a substring of another with the locale given. It is a wrapper around std::basic_string::find except it returns a boolean rather than std::basic_string::size_t.

Parameters

str	The string to search through.
other	The substring to find.
loc	The locale to use.

Returns: true if the substring is found, false otherwise.

Definition at line 213 of file predicate.hpp.

template<typename String >

bool gears::string::iends_with	(	const String &	str,
		const String &	other,
		const std::locale &	loc = `std::locale()`
	)

inline

Checks if a string ends with another string in a case insensitive way with a given locale.

Example:

bool t = string::iends_with("HeLLo wORld"_s, "WORLD"_s); // true

Parameters

str	The string to search through.
other	The string to find.
loc	The locale to use.

Returns: true if the string ends with other, false otherwise.

Definition at line 172 of file predicate.hpp.

template<typename String >

bool gears::string::iequal	(	const String &	lhs,
		const String &	rhs,
		const std::locale &	loc = `std::locale()`
	)

inline

Checks if the strings are case insensitive equal with the locale provided.

Example:

bool t = string::iequal("HELLO"_s, "hello"_s); // true

Parameters

lhs	Left hand side string to compare with.
rhs	Right hand side string to compare with.
loc	The locale to use.

Returns: true if the strings are case insensitive equal, false otherwise.

Definition at line 71 of file predicate.hpp.

template<typename String >

bool gears::string::is_all_lower	(	const String &	str,
		const std::locale &	loc = `std::locale()`
	)

inline

Checks if a string is all lower case with the provided locale.

Parameters

str	String to search through
loc	The locale to use.

Returns: true is all characters are lower case, false otherwise.

Definition at line 74 of file case.hpp.

template<typename String >

bool gears::string::is_all_upper	(	const String &	str,
		const std::locale &	loc = `std::locale()`
	)

inline

Checks if a string is all upper case with the provided locale.

Parameters

str	String to search through
loc	The locale to use.

Returns: true is all characters are upper case, false otherwise.

Definition at line 92 of file case.hpp.

template<typename String >

bool gears::string::istarts_with	(	const String &	str,
		const String &	other,
		const std::locale &	loc = `std::locale()`
	)

inline

Checks if a string starts with another string in a case insensitive way with a given locale.

Example:

bool t = string::istarts_with("hello world"_s, "HELLO"_s); // true

Parameters

str	The string to search through.
other	The string to find.
loc	The locale to use.

Returns: true if the string starts with other, false otherwise.

Definition at line 121 of file predicate.hpp.

template<typename String , typename Cont >

meta::Unqualified<String> gears::string::join	(	const Cont &	cont,
		const String &	sep
	)

inline

Joins a container together with a separator.

Example:

#include <gears/string.hpp>
#include <iostream>
#include <vector>
namespace string = gears::string;
using namespace gears::string::literals;
int main() {
    std::vector<int> v = { 1, 2, 3, 4, 5, 6, 7 };
    std::cout << string::join(v, ", "_s);
}

Output:

1, 2, 3, 4, 5, 6, 7

Parameters

cont	Container to join.
sep	The separator to join with.

Returns: A string with the values of the container separated by the separator.

Definition at line 131 of file transforms.hpp.

template<typename String , typename Cont , typename UnaryPredicate >

meta::Unqualified<String> gears::string::join_if	(	const Cont &	cont,
		const String &	sep,
		UnaryPredicate &&	pred
	)

inline

Joins a container together with a separator when the predicate is met. If the predicate isn't met, then the value will not be in the final string.

Parameters

cont	Container to join.
sep	The separator to join with.
pred	The predicate used to filter.

Returns: A string with the filtered values and separated by the separator.

Definition at line 157 of file transforms.hpp.

template<typename String >

meta::Unqualified<String> gears::string::left	(	String	str,
		size_t	n
	)

inline

Returns the left portion of a string by a given shift.

If the shift provided is larger than the size, then the original string is returned.

auto str = string::left("hello world"_s, 6);

// str == "hello"

Parameters

str	The string to shift left by.
n	The number of places to shift left by.

Returns: A string shifted left.

Definition at line 50 of file transforms.hpp.

template<typename Target , typename CharT >

Target gears::string::lexical_cast ( const std::basic_string< CharT > & str )

inline

Converts a string to its arithmetic representation. A generic way of handling the standard library's std::sto* functions. If the conversion fails, throws std::invalid_argument. If a specialisation isn't picked, the function falls back to using std::basic_istringstream. The type to convert to must be DefaultConstructible. All cv-qualifiers are removed from the type before casting.

Parameters

str	String to convert from.

Template Parameters

Target Type to convert to.

Exceptions

std::invalid_argument thrown whenever conversion fails.

Returns: The arithmetic representation of the string.

Definition at line 160 of file lexical_cast.hpp.

template<typename String >

meta::Unqualified<String> gears::string::replace_all	(	String	str,
		const String &	from,
		const String &	to
	)

inline

Replace all occurrences of the string with another.

Parameters

str	The string to do the find and replacing on.
from	The string to find.
to	The string to replace with.

Returns: A new string with the replaced occurrence.

Definition at line 113 of file replace.hpp.

template<typename String >

meta::Unqualified<String> gears::string::replace_first	(	String	str,
		const String &	from,
		const String &	to
	)

inline

Replace the first occurrence of the string with another.

Parameters

str	The string to do the find and replacing on.
from	The string to find.
to	The string to replace with.

Returns: A new string with the replaced occurrence.

Definition at line 54 of file replace.hpp.

template<typename String >

meta::Unqualified<String> gears::string::replace_last	(	String	str,
		const String &	from,
		const String &	to
	)

inline

Replace the last occurrence of the string with another.

Parameters

str	The string to do the find and replacing on.
from	The string to find.
to	The string to replace with.

Returns: A new string with the replaced occurrence.

Definition at line 73 of file replace.hpp.

template<typename String >

meta::Unqualified<String> gears::string::replace_nth	(	String	str,
		size_t	nth,
		const String &	from,
		const String &	to
	)

inline

Replace the Nth occurrence of the string with another. If the Nth occurrence is not found, then no replacing takes place.

Parameters

str	The string to do the find and replacing on.
nth	The Nth occurrence.
from	The string to find.
to	The string to replace with.

Returns: A new string with the replaced occurrence.

Definition at line 94 of file replace.hpp.

template<typename String >

meta::Unqualified<String> gears::string::reverse ( String str )

inline

Reverses a string.

Parameters

str	The string to reverse.

Returns: The reversed string.

Definition at line 90 of file transforms.hpp.

template<typename String >

meta::Unqualified<String> gears::string::right	(	String	str,
		size_t	n
	)

inline

Returns the right portion of a string by a given shift.

If the shift provided is larger than the size, then the original string is returned.

auto str = string::right("hello world"_s, 6);

// str == "world"

Parameters

str	The string to shift right by.
n	The number of places to shift right by.

Returns: A string shifted right.

Definition at line 75 of file transforms.hpp.

template<typename String , typename OutIt >

OutIt gears::string::split	(	const String &	str,
		const String &	sep,
		OutIt	it
	)

inline

Splits a string into a container.

Example:

#include <gears/string.hpp>
#include <gears/io/prettyprint.hpp>
#include <vector>
#include <iterator>
#include <iostream>
namespace string = gears::string;
using namespace gears::string::literals;
using namespace gears::io::operators;
int main() {
    auto str = "hello;one;two;three;four;five"_s;
    std::vector<std::string> strings;
    string::split(str, ";"_s, std::back_inserter(strings));
    std::cout << strings;
}

Output:

[hello, one, two, three, four, five]

Parameters

str	The string to split.
sep	The substring to split against.
it	An output iterator to insert into.

Returns: The output iterator.

Definition at line 217 of file transforms.hpp.

template<typename String >

bool gears::string::starts_with	(	const String &	str,
		const String &	other
	)

inline

Checks if a string starts with another string.

Example:

bool t = string::starts_with("hello world"_s, "hello"_s); // true

Parameters

str	The string to search through.
other	The string to find.

Returns: true if the string starts with other, false otherwise.

Definition at line 99 of file predicate.hpp.

template<typename String >

meta::Unqualified<String> gears::string::to_lower	(	String	str,
		const std::locale &	loc = `std::locale()`
	)

inline

Turns a string to lower case with the provided locale.

Parameters

str	String to transform to lower case.
loc	The locale to use.

Returns: the lower case string

Definition at line 40 of file case.hpp.

template<typename String >

meta::Unqualified<String> gears::string::to_upper	(	String	str,
		const std::locale &	loc = `std::locale()`
	)

inline

Turns a string to upper case with the provided locale.

Parameters

str	String to transform to upper case.
loc	The locale to use.

Returns: the upper case string

Definition at line 57 of file case.hpp.

template<typename String >

meta::Unqualified<String> gears::string::trim	(	String &&	str,
		const std::locale &	loc = `std::locale()`
	)

inline

Removes the space characters from both the left and right of the string as classified by the locale.

Parameters

str	The string to trim.
loc	The locale to classify spaces with.

Returns: A string with both the left and right spaces removed.

Definition at line 149 of file trim.hpp.

template<typename String , typename UnaryPredicate >

meta::Unqualified<String> gears::string::trim_if	(	String &&	str,
		UnaryPredicate &&	pred
	)

inline

Removes both the left and the right part of the string given a predicate.

Example:

auto str = string::trim_right_if("123hello world123"_s, [](char c) {
    return std::isdigit(c);
});
// str == "hello world"

Parameters

str	The string to search through.
pred	The predicate to use.

Returns: A string with the right and left part removed.

Definition at line 104 of file trim.hpp.

template<typename String >

meta::Unqualified<String> gears::string::trim_left	(	String &&	str,
		const std::locale &	loc = `std::locale()`
	)

inline

Removes the space characters from the left of the string as classified by the locale.

Parameters

str	The string to trim.
loc	The locale to classify spaces with.

Returns: A string with the left spaces removed.

Definition at line 119 of file trim.hpp.

template<typename String , typename UnaryPredicate >

meta::Unqualified<String> gears::string::trim_left_if	(	String	str,
		UnaryPredicate &&	pred
	)

inline

Removes the left part of the string until the predicate is met.

Example:

auto str = string::trim_left_if("12984713hello world"_s, [](char c) {
    return std::isdigit(c);
});
// str == "hello world"

If the predicate is never met, returns the original string.

Parameters

str	String to search through.
pred	Predicate to use.

Returns: A string with the left part removed.

Definition at line 50 of file trim.hpp.

template<typename String >

meta::Unqualified<String> gears::string::trim_right	(	String &&	str,
		const std::locale &	loc = `std::locale()`
	)

inline

Removes the space characters from the right of the string as classified by the locale.

Parameters

str	The string to trim.
loc	The locale to classify spaces with.

Returns: A string with the right spaces removed.

Definition at line 134 of file trim.hpp.

template<typename String , typename UnaryPredicate >

meta::Unqualified<String> gears::string::trim_right_if	(	String	str,
		UnaryPredicate &&	pred
	)

inline

Removes the right part of the string until the predicate is met.

Example:

auto str = string::trim_right_if("hello world18324728361"_s, [](char c) {
    return std::isdigit(c);
});
// str == "hello world"

If the predicate is never met, returns the original string.

Parameters

str	String to search through.
pred	Predicate to use.

Returns: A string with the right part removed.

Definition at line 78 of file trim.hpp.

Modules

Classes

Functions

Detailed Description

Function Documentation