cugl::strtool Namespace Reference

Enumerations
enum	UnicodeType : int {   SPACE = 0, NEWLINE = 1, CONTROL = 2, CJK = 3,   CHAR = 4 }

Functions
std::string	to_string (Uint8 value)
std::string	to_string (Sint16 value)
std::string	to_string (Uint16 value)
std::string	to_string (Sint32 value)
std::string	to_string (Uint32 value)
std::string	to_string (Sint64 value)
std::string	to_string (Uint64 value)
std::string	to_string (float value, int precision=-1)
std::string	to_string (double value, int precision=-1)
std::string	to_string (Uint8 *array, size_t length, size_t offset=0)
std::string	to_string (Sint16 *array, size_t length, size_t offset=0)
std::string	to_string (Uint16 *array, size_t length, size_t offset=0)
std::string	to_string (Sint32 *array, size_t length, size_t offset=0)
std::string	to_string (Uint32 *array, size_t length, size_t offset=0)
std::string	to_string (Sint64 *array, size_t length, size_t offset=0)
std::string	to_string (Uint64 *array, size_t length, size_t offset=0)
std::string	to_string (float *array, size_t length, size_t offset=0, int precision=-1)
std::string	to_string (double *array, size_t length, size_t offset=0, int precision=-1)
Uint8	stou8 (const std::string str, std::size_t *pos=0, int base=10)
Sint16	stos16 (const std::string str, std::size_t *pos=0, int base=10)
Uint16	stou16 (const std::string str, std::size_t *pos=0, int base=10)
Sint32	stos32 (const std::string str, std::size_t *pos=0, int base=10)
Uint32	stou32 (const std::string str, std::size_t *pos=0, int base=10)
Sint64	stos64 (const std::string str, std::size_t *pos=0, int base=10)
Uint64	stou64 (const std::string str, std::size_t *pos=0, int base=10)
float	stof (const std::string str, std::size_t *pos=0)
double	stod (const std::string str, std::size_t *pos=0)
bool	isalpha (const std::string str)
bool	isalphanum (const std::string str)
bool	isnumeric (const std::string str)
bool	isnumber (const std::string str)
int	count (const std::string str, const std::string a)
bool	starts_with (const std::string str, const std::string a)
bool	ends_with (const std::string str, const std::string a)
bool	islower (const std::string str)
bool	isupper (const std::string str)
std::vector< std::string >	split (const std::string str, const std::string sep)
std::vector< std::string >	splitlines (const std::string str)
std::string	join (const std::string sep, std::initializer_list< std::string > elts)
std::string	join (const std::string sep, std::vector< std::string > elts)
std::string	join (const std::string sep, const std::string *elts, size_t size)
std::string	trim (const std::string str)
std::string	ltrim (const std::string str)
std::string	rtrim (const std::string str)
template<typename ... Args>
std::string	format (const std::string format, Args ... args)
std::string	tolower (std::string str)
std::string	toupper (const std::string str)
std::string	replace (const std::string str, const std::string a, const std::string b)
std::string	replaceall (const std::string str, const std::string a, const std::string b)
UnicodeType	getUnicodeType (Uint32 code)
UnicodeType	getUnicodeType (const std::string str)
UnicodeType	getUnicodeType (const char *substr, const char *end)
std::vector< Uint32 >	getCodePoints (const std::string str)
std::vector< Uint32 >	getCodePoints (const char *substr, const char *end)
size_t	getUTF8Length (const std::string str)
size_t	getUTF8Length (const char *substr, const char *end)

Detailed Description

A platform independent module for generating strings.

The functions in this namespace are necessary because Android does not support a lot of the built-in string methods. Therefore, we need alternate definitions that are platform agnostic. Note that these functions have names that are very similar to those in the std namespace, but all live in the cugl::strtool namespace.

Note that this module does not refer to the integral types as short, int, long, etc. Those types are NOT cross-platform. For example, a long is 8 bytes on Unix/OS X, but 4 bytes on some Win32 platforms. Hence we use the SDL naming convention instead.

Enumeration Type Documentation

UnicodeType

enum cugl::strtool::UnicodeType : int

This enum categorizes the type of unicode characters we might encounter

Unicode character types are independent of font choice. Identifying non-printable characters (or spacing) is useful for when we need to break up text over multiple lines.

Enumerator
SPACE	A basic space character This type include tabs (which CUGL converts to spaces) but not newlines or other control characters. It also includes the unicode no-break space.
NEWLINE	A newline character This includes both the special characters \n and \r. It also includes the unicode "next line" (0x0085). It does not include form feeds or any other control characters.
CONTROL	An unprintable character This includes any unprintable character that is not a newline.
CJK	A CJK (Chinese, Japanese, Korean) character. These unicode characters are of special note as each character is a word. This is useful for when deciding how to break up a line of text.
CHAR	An other type of printable character. This is the standard type of character. It includes all printable ASCII and Latin supplementals. It also includes emojis.

Function Documentation

count()

int cugl::strtool::count	(	const std::string	str,
		const std::string	a
	)

Returns the number of times substring a appears in str.

Overlapping substring count. So count("aaa","aa") returns 2.

Parameters

str	The string to count from
a	The substring to count

Returns

the number of times substring a appears in str.

ends_with()

bool cugl::strtool::ends_with	(	const std::string	str,
		const std::string	a
	)

Returns true if str ends with the substring a.

Parameters

str	The string to query
a	The substring to match

Returns

true if str ends with the substring a.

format()

template<typename ... Args>

std::string cugl::strtool::format	(	const std::string	format,
		Args ...	args
	)

Returns a new string from the given formatter and arguments

This funciton is similar to the C-function sprintf except that it supports C++ style strings.

Parameters

format	The formatting string
args	The argument list

Returns

a new string from the given formatter and arguments

getCodePoints() [1/2]

std::vector<Uint32> cugl::strtool::getCodePoints	(	const char *	substr,
		const char *	end
	)

Returns the code points for the elements of substr.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. Note that for an ASCII string, this will simply fill the vector with the elements of str.

Parameters

substr	The start of the string to test
end	The end of the string to test

Returns

the code points for the elements of substr.

getCodePoints() [2/2]

std::vector<Uint32> cugl::strtool::getCodePoints

(

const std::string

str

)

Returns the code points for the elements of str.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. Note that for an ASCII string, this will simply fill the vector with the elements of str.

Parameters

str	The string to convert

Returns

the code points for the elements of str.

getUnicodeType() [1/3]

UnicodeType cugl::strtool::getUnicodeType	(	const char *	substr,
		const char *	end
	)

Returns the unicode type for the FIRST character of substr.

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. Note that a character of a UTF8 string may comprise multiple elements of the string type.

Parameters

substr	The start of the string to test
end	The end of the string to test

Returns

the unicode type for the FIRST character of substr.

getUnicodeType() [2/3]

UnicodeType cugl::strtool::getUnicodeType

(

const std::string

str

)

Returns the unicode type for the FIRST character of str.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. Note that a character of a UTF8 string may comprise multiple elements of the string type.

Parameters

str	The string to test

Returns

the unicode type for the FIRST character of str.

getUnicodeType() [3/3]

UnicodeType cugl::strtool::getUnicodeType

(

Uint32

code

)

Returns the unicode type for the given unicode code point

A unicode code point is the 32-bit representation of a character. It is endian specific and therefore not serializable. A UTF8 representation should be used for serialization.

Parameters

code	The unicode code point

Returns

the unicode type for the given unicode code point

getUTF8Length() [1/2]

size_t cugl::strtool::getUTF8Length	(	const char *	substr,
		const char *	end
	)

Returns the length of substr in UTF8 encoding

The C-style string substr need not be null-terminated. Instead, the termination is indicated by the parameter end. This provides efficient substring processing.

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. Note that for an ASCII string, this will simply return the size of the string.

Parameters

substr	The start of the string to test
end	The end of the string to test

Returns

the length of substr in UTF8 encoding

getUTF8Length() [2/2]

size_t cugl::strtool::getUTF8Length

(

const std::string

str

)

Returns the length of str in UTF8 encoding

The string may either be in UTF8 or ASCII; the method will handle conversion automatically. Note that for an ASCII string, this will simply return the size of the string.

Parameters

str	The string to convert

Returns

the length of str in UTF8 encoding

isalpha()

bool cugl::strtool::isalpha

(

const std::string

str

)

Returns true if the string only contains alphabetic characters.

This function uses the current C++ locale.

Parameters

str	The string to check

Returns

true if the string only contains alphabetic characters.

isalphanum()

bool cugl::strtool::isalphanum

(

const std::string

str

)

Returns true if the string only contains alphabetic and numeric characters.

This function uses the current C++ locale.

Parameters

str	The string to check

Returns

true if the string only contains alphabetic and numeric characters.

islower()

bool cugl::strtool::islower

(

const std::string

str

)

Returns true if the string is lower case

This method ignores any non-letter characters and returns true if str is the empty string. So the only way it can be false is if there is an upper case letter in the string.

This function uses the current C++ locale.

Parameters

str	The string to query

Returns

true if the string is lower case

isnumber()

bool cugl::strtool::isnumber

(

const std::string

str

)

Returns true if the string can safely be converted to a number (double)

This function uses the current C++ locale.

Parameters

str	The string to check

Returns

true if the string can safely be converted to a number (double)

isnumeric()

bool cugl::strtool::isnumeric

(

const std::string

str

)

Returns true if the string only contains numeric characters.

This function uses the current C++ locale.

Parameters

str	The string to check

Returns

true if the string only contains numeric characters.

isupper()

bool cugl::strtool::isupper

(

const std::string

str

)

Returns true if the string is upper case

This method ignores any non-letter characters and returns true if str is the empty string. So the only way it can be false is if there is a lower case letter in the string.

This function uses the current C++ locale.

Parameters

str	The string to query

Returns

true if the string is upper case

join() [1/3]

std::string cugl::strtool::join	(	const std::string	sep,
		const std::string *	elts,
		size_t	size
	)

Returns a string that is the concatenation of elts.

The string sep is placed between each concatenated item of elts. If elts is one element or none, then sep is ignored.

Parameters

sep	The join separator
elts	The strings to join
size	The number of items in elts.

Returns

a string that is the concatentation of elts.

join() [2/3]

std::string cugl::strtool::join	(	const std::string	sep,
		std::initializer_list< std::string >	elts
	)

Returns a string that is the concatenation of elts.

The string sep is placed between each concatenated item of elts. If elts is one element or none, then sep is ignored.

Parameters

sep	The join separator
elts	The strings to join

Returns

a string that is the concatentation of elts.

join() [3/3]

std::string cugl::strtool::join	(	const std::string	sep,
		std::vector< std::string >	elts
	)

Returns a string that is the concatenation of elts.

The string sep is placed between each concatenated item of elts. If elts is one element or none, then sep is ignored.

Parameters

sep	The join separator
elts	The strings to join

Returns

a string that is the concatentation of elts.

ltrim()

std::string cugl::strtool::ltrim

(

const std::string

str

)

Returns a copy of str with any leading whitespace removed.

This function uses the current C++ locale.

Parameters

str	The string to trim

Returns

a copy of str with any leading whitespace removed.

replace()

std::string cugl::strtool::replace	(	const std::string	str,
		const std::string	a,
		const std::string	b
	)

Returns a copy of str with the first instance of a replaced by b.

If a is not a substring of str, the function returns an unmodified copy of str.

Parameters

str	The string to modify
a	The substring to replace
b	The substring to substitute

Returns

a copy of str with the first instance of a replaced by b.

replaceall()

std::string cugl::strtool::replaceall	(	const std::string	str,
		const std::string	a,
		const std::string	b
	)

Returns a copy of str with all instances of a replaced by b.

If a is not a substring of str, the function returns an unmodified copy of str.

Parameters

str	The string to modify
a	The substring to replace
b	The substring to substitute

Returns

a copy of str with all instances of a replaced by b.

rtrim()

std::string cugl::strtool::rtrim

(

const std::string

str

)

Returns a copy of str with any trailing whitespace removed.

This function uses the current C++ locale.

Parameters

str	The string to trim

Returns

a copy of str with any trailing whitespace removed.

split()

std::vector<std::string> cugl::strtool::split	(	const std::string	str,
		const std::string	sep
	)

Returns a list of substrings separate by the given separator

The separator is interpretted exactly; no whitespace is removed around the separator. If the separator is the empty string, this function will return a list of the characters in str.

Parameters

str	The string to split
sep	The splitting delimeter

Returns

a list of substrings separate by the given separator

splitlines()

std::vector<std::string> cugl::strtool::splitlines

(

const std::string

str

)

Returns a list of substrings separated by the line separator

This function treats both newlines and carriage returns as line separators. Windows-style line separators (CR+NL) do not produce an extra line in the middle.

Parameters

str	The string to split

Returns

a list of substrings separate by the line separator

starts_with()

bool cugl::strtool::starts_with	(	const std::string	str,
		const std::string	a
	)

Returns true if str starts with the substring a.

Parameters

str	The string to query
a	The substring to match

Returns

true if str starts with the substring a.

stod()

double cugl::strtool::stod	(	const std::string	str,
		std::size_t *	pos = 0
	)

Returns the double equivalent to the given string

This function discards any whitespace characters (as determined by std::isspace()) until first non-whitespace character is found. Then it takes as many characters as possible to form a valid floating point representation and converts them to a floating point value.

Parameters

str	the string to convert
pos	address of an integer to store the number of characters processed

Returns

the double equivalent to the given string

stof()

float cugl::strtool::stof	(	const std::string	str,
		std::size_t *	pos = 0
	)

Returns the float equivalent to the given string

This function discards any whitespace characters (as determined by std::isspace()) until first non-whitespace character is found. Then it takes as many characters as possible to form a valid floating point representation and converts them to a floating point value.

Parameters

str	the string to convert
pos	address of an integer to store the number of characters processed

Returns

the float equivalent to the given string

stos16()

Sint16 cugl::strtool::stos16	(	const std::string	str,
		std::size_t *	pos = 0,
		int	base = 10
	)

Returns the signed 16 bit integer equivalent to the given string

This function discards any whitespace characters (as identified by calling isspace()) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to a long value.

Parameters

str	the string to convert
pos	address of an integer to store the number of characters processed
base	the number base

Returns

the signed 16 bit integer equivalent to the given string

stos32()

Sint32 cugl::strtool::stos32	(	const std::string	str,
		std::size_t *	pos = 0,
		int	base = 10
	)

Returns the signed 32 bit integer equivalent to the given string

This function discards any whitespace characters (as identified by calling isspace()) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to a long value.

Parameters

str	the string to convert
pos	address of an integer to store the number of characters processed
base	the number base

Returns

the signed 32 bit integer equivalent to the given string

stos64()

Sint64 cugl::strtool::stos64	(	const std::string	str,
		std::size_t *	pos = 0,
		int	base = 10
	)

Returns the signed 64 bit integer equivalent to the given string

This function discards any whitespace characters (as identified by calling isspace()) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to a long value.

Parameters

str	the string to convert
pos	address of an integer to store the number of characters processed
base	the number base

Returns

the signed 64 bit integer equivalent to the given string

stou16()

Uint16 cugl::strtool::stou16	(	const std::string	str,
		std::size_t *	pos = 0,
		int	base = 10
	)

Returns the unsigned 16 bit integer equivalent to the given string

This function discards any whitespace characters (as identified by calling isspace()) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to a long value.

Parameters

str	the string to convert
pos	address of an integer to store the number of characters processed
base	the number base

Returns

the unsigned 16 bit integer equivalent to the given string

stou32()

Uint32 cugl::strtool::stou32	(	const std::string	str,
		std::size_t *	pos = 0,
		int	base = 10
	)

Returns the unsigned 32 bit integer equivalent to the given string

This function discards any whitespace characters (as identified by calling isspace()) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to a long value.

Parameters

str	the string to convert
pos	address of an integer to store the number of characters processed
base	the number base

Returns

the unsigned 32 bit integer equivalent to the given string

stou64()

Uint64 cugl::strtool::stou64	(	const std::string	str,
		std::size_t *	pos = 0,
		int	base = 10
	)

Returns the unsigned 64 bit integer equivalent to the given string

This function discards any whitespace characters (as identified by calling isspace()) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to a long value.

Parameters

str	the string to convert
pos	address of an integer to store the number of characters processed
base	the number base

Returns

the unsigned 64 bit integer equivalent to the given string

stou8()

Uint8 cugl::strtool::stou8	(	const std::string	str,
		std::size_t *	pos = 0,
		int	base = 10
	)

Returns the byte equivalent to the given string

This function discards any whitespace characters (as identified by calling isspace()) until the first non-whitespace character is found, then takes as many characters as possible to form a valid base-n (where n=base) integer number representation and converts them to an integer value.

Parameters

str	the string to convert
pos	address of an integer to store the number of characters processed
base	the number base

Returns

the byte equivalent to the given string

to_string() [1/18]

std::string cugl::strtool::to_string	(	double *	array,
		size_t	length,
		size_t	offset = 0,
		int	precision = -1
	)

Returns a string equivalent to the given double array

The value is display as a python-style list in brackets.

As with to_string(double), this function allows us to specify a precision (the number of digits to display after the decimal point). If precision is negative, then maximum precision will be used.

Parameters

array	the array to convert
length	the array length
offset	the starting position in the array
precision	the number of digits to display after the decimal

Returns

a string equivalent to the given double array

to_string() [2/18]

std::string cugl::strtool::to_string	(	double	value,
		int	precision = -1
	)

Returns a string equivalent to the given double value

This function differs from std::to_string(double) in that it allows us to specify a precision (the number of digits to display after the decimal point). If precision is negative, then maximum precision will be used.

Parameters

value	the numeric value to convert
precision	the number of digits to display after the decimal

Returns

a string equivalent to the given double value

to_string() [3/18]

std::string cugl::strtool::to_string	(	float *	array,
		size_t	length,
		size_t	offset = 0,
		int	precision = -1
	)

Returns a string equivalent to the given float array

The value is display as a python-style list in brackets.

As with to_string(float), this function allows us to specify a precision (the number of digits to display after the decimal point). If precision is negative, then maximum precision will be used.

Parameters

array	the array to convert
length	the array length
offset	the starting position in the array
precision	the number of digits to display after the decimal

Returns

a string equivalent to the given float array

to_string() [4/18]

std::string cugl::strtool::to_string	(	float	value,
		int	precision = -1
	)

Returns a string equivalent to the given float value

This function differs from std::to_string(float) in that it allows us to specify a precision (the number of digits to display after the decimal point). If precision is negative, then maximum precision will be used.

Parameters

value	the numeric value to convert
precision	the number of digits to display after the decimal

Returns

a string equivalent to the given float value

to_string() [5/18]

std::string cugl::strtool::to_string	(	Sint16 *	array,
		size_t	length,
		size_t	offset = 0
	)

Returns a string equivalent to the signed 16 bit integer array

The value is display as a python-style list in brackets.

Parameters

array	the array to convert
length	the array length
offset	the starting position in the array

Returns

a string equivalent to the signed 16 bit integer array

to_string() [6/18]

std::string cugl::strtool::to_string

(

Sint16

value

)

Returns a string equivalent to the given signed 16 bit integer

Parameters

value

the numeric value to convert

Returns

a string equivalent to the given signed 16 bit integer

to_string() [7/18]

std::string cugl::strtool::to_string	(	Sint32 *	array,
		size_t	length,
		size_t	offset = 0
	)

Returns a string equivalent to the signed 32 bit integer array

The value is display as a python-style list in brackets.

Parameters

array	the array to convert
length	the array length
offset	the starting position in the array

Returns

a string equivalent to the signed 32 bit integer array

to_string() [8/18]

std::string cugl::strtool::to_string

(

Sint32

value

)

Returns a string equivalent to the given signed 32 bit integer

Parameters

value

the numeric value to convert

Returns

a string equivalent to the given signed 32 bit integer

to_string() [9/18]

std::string cugl::strtool::to_string	(	Sint64 *	array,
		size_t	length,
		size_t	offset = 0
	)

Returns a string equivalent to the signed 64 bit integer array

The value is display as a python-style list in brackets.

Parameters

array	the array to convert
length	the array length
offset	the starting position in the array

Returns

a string equivalent to the signed 64 bit integer array

to_string() [10/18]

std::string cugl::strtool::to_string

(

Sint64

value

)

Returns a string equivalent to the given signed 64 bit integer

Parameters

value

the numeric value to convert

Returns

a string equivalent to the given signed 64 bit integer

to_string() [11/18]

std::string cugl::strtool::to_string	(	Uint16 *	array,
		size_t	length,
		size_t	offset = 0
	)

Returns a string equivalent to the unsigned 16 bit integer array

The value is display as a python-style list in brackets.

Parameters

array	the array to convert
length	the array length
offset	the starting position in the array

Returns

a string equivalent to the unsigned 16 bit integer array

to_string() [12/18]

std::string cugl::strtool::to_string

(

Uint16

value

)

Returns a string equivalent to the given unsigned 16 bit integer

Parameters

value

the numeric value to convert

Returns

a string equivalent to the given unsigned 16 bit integer

to_string() [13/18]

std::string cugl::strtool::to_string	(	Uint32 *	array,
		size_t	length,
		size_t	offset = 0
	)

Returns a string equivalent to the unsigned 32 bit integer array

The value is display as a python-style list in brackets.

Parameters

array	the array to convert
length	the array length
offset	the starting position in the array

Returns

a string equivalent to the unsigned 32 bit integer array

to_string() [14/18]

std::string cugl::strtool::to_string

(

Uint32

value

)

Returns a string equivalent to the given unsigned 32 bit integer

Parameters

value

the numeric value to convert

Returns

a string equivalent to the given unsigned 32 bit integer

to_string() [15/18]

std::string cugl::strtool::to_string	(	Uint64 *	array,
		size_t	length,
		size_t	offset = 0
	)

Returns a string equivalent to the unsigned 64 bit integer array

The value is display as a python-style list in brackets.

Parameters

array	the array to convert
length	the array length
offset	the starting position in the array

Returns

a string equivalent to the unsigned 64 bit integer array

to_string() [16/18]

std::string cugl::strtool::to_string

(

Uint64

value

)

Returns a string equivalent to the given unsigned 64 bit integer

Parameters

value

the numeric value to convert

Returns

a string equivalent to the given unsigned 64 bit integer

to_string() [17/18]

std::string cugl::strtool::to_string	(	Uint8 *	array,
		size_t	length,
		size_t	offset = 0
	)

Returns a string equivalent to the given byte array

The value is display as a python-style list in brackets.

Parameters

array	the array to convert
length	the array length
offset	the starting position in the array

Returns

a string equivalent to the given byte array

to_string() [18/18]

std::string cugl::strtool::to_string

(

Uint8

value

)

Returns a string equivalent to the given byte

The value is displayed as a number, not a character.

Parameters

value

the numeric value to convert

Returns

a string equivalent to the given byte

tolower()

std::string cugl::strtool::tolower

(

std::string

str

)

Returns a lower case copy of str.

This function uses the current C++ locale.

Parameters

str	The string to convert

Returns

a lower case copy of str.

toupper()

std::string cugl::strtool::toupper

(

const std::string

str

)

Returns an upper case copy of str.

This function uses the current C++ locale.

Parameters

str	The string to convert

Returns

an upper case copy of str.

trim()

std::string cugl::strtool::trim

(

const std::string

str

)

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

This function uses the current C++ locale.

Parameters

str	The string to trim

Returns

a copy of str with any leading and trailing whitespace removed.