String class used within the GUI system. More...

Inheritance diagram for CEGUI::String:

Collaboration diagram for CEGUI::String:

Classes
class	const_iterator
	const iterator for String. More...

class	iterator
	regular iterator for String. More...

Public Types
typedef utf32	value_type
	Basic 'code point' type used for String (utf32)

typedef size_t	size_type
	Unsigned type used for size values and indices.

typedef std::ptrdiff_t	difference_type
	Signed type used for differences.

typedef utf32 &	reference
	Type used for utf32 code point references.

typedef const utf32 &	const_reference
	Type used for constant utf32 code point references.

typedef utf32 *	pointer
	Type used for utf32 code point pointers.

typedef const utf32 *	const_pointer
	Type used for constant utf32 code point pointers.

typedef std::reverse_iterator< const_iterator >	const_reverse_iterator
	Constant reverse iterator class for String objects.

typedef std::reverse_iterator< iterator >	reverse_iterator
	Reverse iterator class for String objects.

Public Member Functions
	String (void)
	Constructs an empty string.

	~String (void)
	Destructor for String objects.

	String (const String &str)
	Copy constructor - Creates a new string with the same value as str. More...

	String (const String &str, size_type str_idx, size_type str_num=npos)
	Constructs a new string initialised with code points from another String object. More...

	String (const std::string &std_str)
	Constructs a new string and initialises it using the std::string std_str. More...

	String (const std::string &std_str, size_type str_idx, size_type str_num=npos)
	Constructs a new string initialised with characters from the given std::string object. More...

	String (const utf8 *utf8_str)
	Constructs a new String object and initialise it using the provided utf8 encoded string buffer. More...

	String (const utf8 *utf8_str, size_type chars_len)
	Constructs a new String object and initialise it using the provided utf8 encoded string buffer. More...

	String (size_type num, utf32 code_point)
	Constructs a new String that is initialised with the specified code point. More...

	String (const_iterator iter_beg, const_iterator iter_end)
	Construct a new string object and initialise it with code-points from the range [beg, end). More...

	String (const char *cstr)
	Constructs a new String object and initialise it using the provided c-string. More...

	String (const char *chars, size_type chars_len)
	Constructs a new String object and initialise it using characters from the provided char array. More...

size_type	size (void) const
	Returns the size of the String in code points. More...

size_type	length (void) const
	Returns the size of the String in code points. More...

bool	empty (void) const
	Returns true if the String is empty. More...

size_type	max_size (void) const
	Returns the maximum size of a String. More...

size_type	capacity (void) const
	Return the number of code points that the String could hold before a re-allocation would be required. More...

void	reserve (size_type num=0)
	Specifies the amount of reserve capacity to allocate. More...

int	compare (const String &str) const
	Compares this String with the String 'str'. More...

int	compare (size_type idx, size_type len, const String &str, size_type str_idx=0, size_type str_len=npos) const
	Compares code points from this String with code points from the String 'str'. More...

int	compare (const std::string &std_str) const
	Compares this String with the std::string 'std_str'. More...

int	compare (size_type idx, size_type len, const std::string &std_str, size_type str_idx=0, size_type str_len=npos) const
	Compares code points from this String with code points from the std::string 'std_str'. More...

int	compare (const utf8 *utf8_str) const
	Compares this String with the null-terminated utf8 encoded 'utf8_str'. More...

int	compare (size_type idx, size_type len, const utf8 *utf8_str) const
	Compares code points from this String with the null-terminated utf8 encoded 'utf8_str'. More...

int	compare (size_type idx, size_type len, const utf8 *utf8_str, size_type str_cplen) const
	Compares code points from this String with the utf8 encoded data in buffer 'utf8_str'. More...

int	compare (const char *cstr) const
	Compares this String with the given c-string. More...

int	compare (size_type idx, size_type len, const char *cstr) const
	Compares code points from this String with the given c-string. More...

int	compare (size_type idx, size_type len, const char *chars, size_type chars_len) const
	Compares code points from this String with chars in the given char array. More...

reference	operator[] (size_type idx)
	Returns the code point at the given index. More...

value_type	operator[] (size_type idx) const
	Returns the code point at the given index. More...

reference	at (size_type idx)
	Returns the code point at the given index. More...

const_reference	at (size_type idx) const
	Returns the code point at the given index. More...

const char *	c_str (void) const
	Returns contents of the String as a null terminated string of utf8 encoded data. More...

const utf8 *	data (void) const
	Returns contents of the String as utf8 encoded data. More...

utf32 *	ptr (void)
	Returns a pointer to the buffer in use.

const utf32 *	ptr (void) const
	Returns a pointer to the buffer in use. (const version)

size_type	copy (utf8 *buf, size_type len=npos, size_type idx=0) const
	Copies an area of the String into the provided buffer as encoded utf8 data. More...

size_type	utf8_stream_len (size_type num=npos, size_type idx=0) const
	Return the number of utf8 code units required to hold an area of the String when encoded as utf8 data. More...

String &	operator= (const String &str)
	Assign the value of String str to this String. More...

String &	assign (const String &str, size_type str_idx=0, size_type str_num=npos)
	Assign a sub-string of String str to this String. More...

String &	operator= (const std::string &std_str)
	Assign the value of std::string std_str to this String. More...

String &	assign (const std::string &std_str, size_type str_idx=0, size_type str_num=npos)
	Assign a sub-string of std::string std_str to this String. More...

String &	operator= (const utf8 *utf8_str)
	Assign to this String the string value represented by the given null-terminated utf8 encoded data. More...

String &	assign (const utf8 *utf8_str)
	Assign to this String the string value represented by the given null-terminated utf8 encoded data. More...

String &	assign (const utf8 *utf8_str, size_type str_num)
	Assign to this String the string value represented by the given utf8 encoded data. More...

String &	operator= (utf32 code_point)
	Assigns the specified utf32 code point to this String. Result is always a String 1 code point in length. More...

String &	assign (size_type num, utf32 code_point)
	Assigns the specified code point repeatedly to the String. More...

String &	operator= (const char *cstr)
	Assign to this String the given C-string. More...

String &	assign (const char *cstr)
	Assign to this String the given C-string. More...

String &	assign (const char *chars, size_type chars_len)
	Assign to this String a number of chars from a char array. More...

void	swap (String &str)
	Swaps the value of this String with the given String str. More...

String &	operator+= (const String &str)
	Appends the String str. More...

String &	append (const String &str, size_type str_idx=0, size_type str_num=npos)
	Appends a sub-string of the String str. More...

String &	operator+= (const std::string &std_str)
	Appends the std::string std_str. More...

String &	append (const std::string &std_str, size_type str_idx=0, size_type str_num=npos)
	Appends a sub-string of the std::string std_str. More...

String &	operator+= (const utf8 *utf8_str)
	Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str. More...

String &	append (const utf8 *utf8_str)
	Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str. More...

String &	append (const utf8 *utf8_str, size_type len)
	Appends to the String the utf8 encoded data in the buffer utf8_str. More...

String &	operator+= (utf32 code_point)
	Appends a single code point to the string. More...

String &	append (size_type num, utf32 code_point)
	Appends a single code point multiple times to the string. More...

void	push_back (utf32 code_point)
	Appends a single code point to the string. More...

String &	append (const_iterator iter_beg, const_iterator iter_end)
	Appends the code points in the reange [beg, end) More...

String &	operator+= (const char *cstr)
	Appends to the String the given c-string. More...

String &	append (const char *cstr)
	Appends to the String the given c-string. More...

String &	append (const char *chars, size_type chars_len)
	Appends to the String chars from the given char array. More...

String &	insert (size_type idx, const String &str)
	Inserts the given String object at the specified position. More...

String &	insert (size_type idx, const String &str, size_type str_idx, size_type str_num)
	Inserts a sub-string of the given String object at the specified position. More...

String &	insert (size_type idx, const std::string &std_str)
	Inserts the given std::string object at the specified position. More...

String &	insert (size_type idx, const std::string &std_str, size_type str_idx, size_type str_num)
	Inserts a sub-string of the given std::string object at the specified position. More...

String &	insert (size_type idx, const utf8 *utf8_str)
	Inserts the given null-terminated utf8 encoded data at the specified position. More...

String &	insert (size_type idx, const utf8 *utf8_str, size_type len)
	Inserts the given utf8 encoded data at the specified position. More...

String &	insert (size_type idx, size_type num, utf32 code_point)
	Inserts a code point multiple times into the String. More...

void	insert (iterator pos, size_type num, utf32 code_point)
	Inserts a code point multiple times into the String. More...

iterator	insert (iterator pos, utf32 code_point)
	Inserts a single code point into the String. More...

void	insert (iterator iter_pos, const_iterator iter_beg, const_iterator iter_end)
	Inserts code points specified by the range [beg, end). More...

String &	insert (size_type idx, const char *cstr)
	Inserts the given c-string at the specified position. More...

String &	insert (size_type idx, const char *chars, size_type chars_len)
	Inserts chars from the given char array at the specified position. More...

void	clear (void)
	Removes all data from the String. More...

String &	erase (void)
	Removes all data from the String. More...

String &	erase (size_type idx)
	Erase a single code point from the string. More...

String &	erase (size_type idx, size_type len)
	Erase a range of code points. More...

String &	erase (iterator pos)
	Erase the code point described by the given iterator. More...

String &	erase (iterator iter_beg, iterator iter_end)
	Erase a range of code points described by the iterators [beg, end). More...

void	resize (size_type num)
	Resizes the String either by inserting default utf32 code points to make it larger, or by truncating to make it smaller. More...

void	resize (size_type num, utf32 code_point)
	Resizes the String either by inserting the given utf32 code point to make it larger, or by truncating to make it smaller. More...

String &	replace (size_type idx, size_type len, const String &str)
	Replace code points in the String with the specified String object. More...

String &	replace (iterator iter_beg, iterator iter_end, const String &str)
	Replace the code points in the range [beg, end) with the specified String object. More...

String &	replace (size_type idx, size_type len, const String &str, size_type str_idx, size_type str_num)
	Replace code points in the String with a specified sub-string of a given String object. More...

String &	replace (size_type idx, size_type len, const std::string &std_str)
	Replace code points in the String with the specified std::string object. More...

String &	replace (iterator iter_beg, iterator iter_end, const std::string &std_str)
	Replace the code points in the range [beg, end) with the specified std::string object. More...

String &	replace (size_type idx, size_type len, const std::string &std_str, size_type str_idx, size_type str_num)
	Replace code points in the String with a specified sub-string of a given std::string object. More...

String &	replace (size_type idx, size_type len, const utf8 *utf8_str)
	Replace code points in the String with the specified null-terminated utf8 encoded data. More...

String &	replace (iterator iter_beg, iterator iter_end, const utf8 *utf8_str)
	Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data. More...

String &	replace (size_type idx, size_type len, const utf8 *utf8_str, size_type str_len)
	Replace code points in the String with the specified utf8 encoded data. More...

String &	replace (iterator iter_beg, iterator iter_end, const utf8 *utf8_str, size_type str_len)
	Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data. More...

String &	replace (size_type idx, size_type len, size_type num, utf32 code_point)
	Replaces a specified range of code points with occurrences of a given code point. More...

String &	replace (iterator iter_beg, iterator iter_end, size_type num, utf32 code_point)
	Replace the code points in the range [beg, end) with occurrences of a given code point. More...

String &	replace (iterator iter_beg, iterator iter_end, const_iterator iter_newBeg, const_iterator iter_newEnd)
	Replace the code points in the range [beg, end) with code points from the range [newBeg, newEnd). More...

String &	replace (size_type idx, size_type len, const char *cstr)
	Replace code points in the String with the specified c-string. More...

String &	replace (iterator iter_beg, iterator iter_end, const char *cstr)
	Replace the code points in the range [beg, end) with the specified c-string. More...

String &	replace (size_type idx, size_type len, const char *chars, size_type chars_len)
	Replace code points in the String with chars from the given char array. More...

String &	replace (iterator iter_beg, iterator iter_end, const char *chars, size_type chars_len)
	Replace the code points in the range [beg, end) with chars from the given char array. More...

size_type	find (utf32 code_point, size_type idx=0) const
	Search forwards for a given code point. More...

size_type	rfind (utf32 code_point, size_type idx=npos) const
	Search backwards for a given code point. More...

size_type	find (const String &str, size_type idx=0) const
	Search forwards for a sub-string. More...

size_type	rfind (const String &str, size_type idx=npos) const
	Search backwards for a sub-string. More...

size_type	find (const std::string &std_str, size_type idx=0) const
	Search forwards for a sub-string. More...

size_type	rfind (const std::string &std_str, size_type idx=npos) const
	Search backwards for a sub-string. More...

size_type	find (const utf8 *utf8_str, size_type idx=0) const
	Search forwards for a sub-string. More...

size_type	rfind (const utf8 *utf8_str, size_type idx=npos) const
	Search backwards for a sub-string. More...

size_type	find (const utf8 *utf8_str, size_type idx, size_type str_len) const
	Search forwards for a sub-string. More...

size_type	rfind (const utf8 *utf8_str, size_type idx, size_type str_len) const
	Search backwards for a sub-string. More...

size_type	find (const char *cstr, size_type idx=0) const
	Search forwards for a sub-string. More...

size_type	rfind (const char *cstr, size_type idx=npos) const
	Search backwards for a sub-string. More...

size_type	find (const char *chars, size_type idx, size_type chars_len) const
	Search forwards for a sub-string. More...

size_type	rfind (const char *chars, size_type idx, size_type chars_len) const
	Search backwards for a sub-string. More...

size_type	find_first_of (const String &str, size_type idx=0) const
	Find the first occurrence of one of a set of code points. More...

size_type	find_first_not_of (const String &str, size_type idx=0) const
	Find the first code point that is not one of a set of code points. More...

size_type	find_first_of (const std::string &std_str, size_type idx=0) const
	Find the first occurrence of one of a set of code points. More...

size_type	find_first_not_of (const std::string &std_str, size_type idx=0) const
	Find the first code point that is not one of a set of code points. More...

size_type	find_first_of (const utf8 *utf8_str, size_type idx=0) const
	Find the first occurrence of one of a set of code points. More...

size_type	find_first_not_of (const utf8 *utf8_str, size_type idx=0) const
	Find the first code point that is not one of a set of code points. More...

size_type	find_first_of (const utf8 *utf8_str, size_type idx, size_type str_len) const
	Find the first occurrence of one of a set of code points. More...

size_type	find_first_not_of (const utf8 *utf8_str, size_type idx, size_type str_len) const
	Find the first code point that is not one of a set of code points. More...

size_type	find_first_of (utf32 code_point, size_type idx=0) const
	Search forwards for a given code point. More...

size_type	find_first_not_of (utf32 code_point, size_type idx=0) const
	Search forwards for the first code point that does not match a given code point. More...

size_type	find_first_of (const char *cstr, size_type idx=0) const
	Find the first occurrence of one of a set of chars. More...

size_type	find_first_not_of (const char *cstr, size_type idx=0) const
	Find the first code point that is not one of a set of chars. More...

size_type	find_first_of (const char *chars, size_type idx, size_type chars_len) const
	Find the first occurrence of one of a set of chars. More...

size_type	find_first_not_of (const char *chars, size_type idx, size_type chars_len) const
	Find the first code point that is not one of a set of chars. More...

size_type	find_last_of (const String &str, size_type idx=npos) const
	Find the last occurrence of one of a set of code points. More...

size_type	find_last_not_of (const String &str, size_type idx=npos) const
	Find the last code point that is not one of a set of code points. More...

size_type	find_last_of (const std::string &std_str, size_type idx=npos) const
	Find the last occurrence of one of a set of code points. More...

size_type	find_last_not_of (const std::string &std_str, size_type idx=npos) const
	Find the last code point that is not one of a set of code points. More...

size_type	find_last_of (const utf8 *utf8_str, size_type idx=npos) const
	Find the last occurrence of one of a set of code points. More...

size_type	find_last_not_of (const utf8 *utf8_str, size_type idx=npos) const
	Find the last code point that is not one of a set of code points. More...

size_type	find_last_of (const utf8 *utf8_str, size_type idx, size_type str_len) const
	Find the last occurrence of one of a set of code points. More...

size_type	find_last_not_of (const utf8 *utf8_str, size_type idx, size_type str_len) const
	Find the last code point that is not one of a set of code points. More...

size_type	find_last_of (utf32 code_point, size_type idx=npos) const
	Search for last occurrence of a given code point. More...

size_type	find_last_not_of (utf32 code_point, size_type idx=npos) const
	Search for the last code point that does not match a given code point. More...

size_type	find_last_of (const char *cstr, size_type idx=npos) const
	Find the last occurrence of one of a set of chars. More...

size_type	find_last_not_of (const char *cstr, size_type idx=npos) const
	Find the last code point that is not one of a set of chars. More...

size_type	find_last_of (const char *chars, size_type idx, size_type chars_len) const
	Find the last occurrence of one of a set of chars. More...

size_type	find_last_not_of (const char *chars, size_type idx, size_type chars_len) const
	Find the last code point that is not one of a set of chars. More...

String	substr (size_type idx=0, size_type len=npos) const
	Returns a substring of this String. More...

iterator	begin (void)
	Return a forwards iterator that describes the beginning of the String. More...

const_iterator	begin (void) const
	Return a constant forwards iterator that describes the beginning of the String. More...

iterator	end (void)
	Return a forwards iterator that describes the end of the String. More...

const_iterator	end (void) const
	Return a constant forwards iterator that describes the end of the String. More...

reverse_iterator	rbegin (void)
	Return a reverse iterator that describes the beginning of the String. More...

const_reverse_iterator	rbegin (void) const
	Return a constant reverse iterator that describes the beginning of the String. More...

reverse_iterator	rend (void)
	Return a reverse iterator that describes the end of the String. More...

const_reverse_iterator	rend (void) const
	Return a constant reverse iterator that describes the end of the String. More...

Static Public Attributes
static const size_type	npos
	Value used to represent 'not found' conditions and 'all code points' etc.

Detailed Description

String class used within the GUI system.

For the most part, this class can replace std::string in basic usage. However, currently String does not use the current locale, and also comparisons do not take into account the Unicode data tables, so are not 'correct' as such.

Constructor & Destructor Documentation

CEGUI::String::String ( const String & str )

inline

Copy constructor - Creates a new string with the same value as str.

Parameters

str	String object used to initialise the newly created string

Returns: Nothing

CEGUI::String::String	(	const String &	str,
		size_type	str_idx,
		size_type	str_num = `npos`
	)

inline

Constructs a new string initialised with code points from another String object.

Parameters

str	String object used to initialise the newly created string
str_idx	Starting code-point of str to be used when initialising the new String
str_num	Maximum number of code points from str that are to be assigned to the new String

Returns: Nothing

CEGUI::String::String ( const std::string & std_str )

inline

Constructs a new string and initialises it using the std::string std_str.

Parameters

std_str The std::string object that is to be used to initialise the new String object.

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Returns: Nothing

Exceptions

std::length_error Thrown if resulting String object would be too big.

CEGUI::String::String	(	const std::string &	std_str,
		size_type	str_idx,
		size_type	str_num = `npos`
	)

inline

Constructs a new string initialised with characters from the given std::string object.

Parameters

std_str	std::string object used to initialise the newly created string
str_idx	Starting character of std_str to be used when initialising the new String

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Parameters

str_num Maximum number of characters from std_str that are to be assigned to the new String

Returns: Nothing

Exceptions

std::length_error Thrown if resulting String object would be too big.

CEGUI::String::String ( const utf8 * utf8_str )

inline

Constructs a new String object and initialise it using the provided utf8 encoded string buffer.

Parameters

utf8_str Pointer to a buffer containing a null-terminated Unicode string encoded as utf8 data.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Returns: Nothing

Exceptions

std::length_error Thrown if resulting String object would be too big.

CEGUI::String::String	(	const utf8 *	utf8_str,
		size_type	chars_len
	)

inline

Constructs a new String object and initialise it using the provided utf8 encoded string buffer.

A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

utf8_str Pointer to a buffer containing Unicode string data encoded as utf8.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

chars_len Length of the provided utf8 string in code units (not code-points).

Returns: Nothing

Exceptions

std::length_error Thrown if resulting String object would be too big.

CEGUI::String::String	(	size_type	num,
		utf32	code_point
	)

inline

Constructs a new String that is initialised with the specified code point.

Parameters

num	The number of times code_point is to be put into new String object
code_point	The Unicode code point to be used when initialising the String object

Returns: Nothing

Exceptions

std::length_error Thrown if resulting String object would be too big.

CEGUI::String::String	(	const_iterator	iter_beg,
		const_iterator	iter_end
	)

inline

Construct a new string object and initialise it with code-points from the range [beg, end).

Parameters

beg	Iterator describing the start of the data to be used when initialising the String object
end	Iterator describing the (exclusive) end of the data to be used when initialising the String object

Returns: Nothing

CEGUI::String::String ( const char * cstr )

inline

Constructs a new String object and initialise it using the provided c-string.

Parameters

c_str Pointer to a c-string.

Returns: Nothing

Exceptions

std::length_error Thrown if resulting String object would be too big.

CEGUI::String::String	(	const char *	chars,
		size_type	chars_len
	)

inline

Constructs a new String object and initialise it using characters from the provided char array.

Parameters

chars	char array.
chars_len	Number of chars from the array to be used.

Returns: Nothing

Exceptions

std::length_error Thrown if resulting String object would be too big.

Member Function Documentation

String& CEGUI::String::append	(	const String &	str,
		size_type	str_idx = `0`,
		size_type	str_num = `npos`
	)

inline

Appends a sub-string of the String str.

Parameters

str	String object containing data to be appended
str_idx	Index of the first code point to be appended
str_num	Maximum number of code points to be appended

Returns: This String after the append operation

Exceptions

std::out_of_range	Thrown if str_idx is invalid for str.
std::length_error	Thrown if resulting String would be too large.

References ptr().

String& CEGUI::String::append	(	const std::string &	std_str,
		size_type	str_idx = `0`,
		size_type	str_num = `npos`
	)

inline

Appends a sub-string of the std::string std_str.

Parameters

std_str std::string object containing data to be appended

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Parameters

str_idx	Index of the first character to be appended
str_num	Maximum number of characters to be appended

Returns: This String after the append operation

Exceptions

std::out_of_range	Thrown if str_idx is invalid for std_str.
std::length_error	Thrown if resulting String would be too large.

String& CEGUI::String::append ( const utf8 * utf8_str )

inline

Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.

Parameters

utf8_str Buffer holding the null-terminated utf8 encoded data that is to be appended

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::append	(	const utf8 *	utf8_str,
		size_type	len
	)

inline

Appends to the String the utf8 encoded data in the buffer utf8_str.

Parameters

utf8_str Buffer holding the utf8 encoded data that is to be appended

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

len	Number of code units (not code points) in the buffer to be appended

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too large, or if len was 'npos'

String& CEGUI::String::append	(	size_type	num,
		utf32	code_point
	)

inline

Appends a single code point multiple times to the string.

Parameters

num	Number of copies of the code point to be appended
code_point	utf32 Unicode code point that is to be appended

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too long, or if num was 'npos'.

String& CEGUI::String::append	(	const_iterator	iter_beg,
		const_iterator	iter_end
	)

inline

Appends the code points in the reange [beg, end)

Parameters

beg	Iterator describing the start of the range to be appended
end	Iterator describing the (exclusive) end of the range to be appended.

Returns: This String after the append operation

Exceptions

std::length_error Thrown if the resulting string would be too large.

String& CEGUI::String::append ( const char * cstr )

inline

Appends to the String the given c-string.

Parameters

c_str c-string that is to be appended.

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::append	(	const char *	chars,
		size_type	chars_len
	)

inline

Appends to the String chars from the given char array.

Parameters

chars	char array holding the chars that are to be appended
chars_len	Number of chars to be appended

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too large, or if chars_len was 'npos'

String& CEGUI::String::assign	(	const String &	str,
		size_type	str_idx = `0`,
		size_type	str_num = `npos`
	)

inline

Assign a sub-string of String str to this String.

Parameters

str	String object containing the string data to be assigned.
str_idx	Index of the first code point in str that is to be assigned
str_num	Maximum number of code points from str that are be be assigned

Returns: This String after the assignment has happened

Exceptions

std::out_of_range Thrown if str_idx is invalid for str

References ptr().

String& CEGUI::String::assign	(	const std::string &	std_str,
		size_type	str_idx = `0`,
		size_type	str_num = `npos`
	)

inline

Assign a sub-string of std::string std_str to this String.

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Parameters

std_str	std::string object containing the string value to be assigned.
str_idx	Index of the first character of std_str to be assigned
str_num	Maximum number of characters from std_str to be assigned

Returns: This String after the assignment has happened

Exceptions

std::out_of_range	Thrown if str_idx is invalid for std_str
std::length_error	Thrown if the resulting String would have been too large.

String& CEGUI::String::assign ( const utf8 * utf8_str )

inline

Assign to this String the string value represented by the given null-terminated utf8 encoded data.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

utf8_str Buffer containing valid null-terminated utf8 encoded data

Returns: This String after the assignment has happened

Exceptions

std::length_error Thrown if the resulting String would have been too large.

String& CEGUI::String::assign	(	const utf8 *	utf8_str,
		size_type	str_num
	)

inline

Assign to this String the string value represented by the given utf8 encoded data.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

utf8_str	Buffer containing valid utf8 encoded data
str_num	Number of code units (not code points) in the buffer pointed to by utf8_str

Returns: This String after the assignment has happened

Exceptions

std::length_error Thrown if the resulting String would have been too large, or if str_num is 'npos'.

String& CEGUI::String::assign	(	size_type	num,
		utf32	code_point
	)

inline

Assigns the specified code point repeatedly to the String.

Parameters

num	The number of times to assign the code point
code_point	Valid utf32 Unicode code point to be assigned to the string

Returns: This String after assignment.

Exceptions

std::length_error Thrown if num was 'npos'

String& CEGUI::String::assign ( const char * cstr )

inline

Assign to this String the given C-string.

Parameters

c_str Pointer to a valid C style string.

Returns: This String after the assignment has happened

Exceptions

std::length_error Thrown if the resulting String would have been too large.

String& CEGUI::String::assign	(	const char *	chars,
		size_type	chars_len
	)

inline

Assign to this String a number of chars from a char array.

Parameters

chars	char array.
chars_len	Number of chars to be assigned.

Returns: This String after the assignment has happened

Exceptions

std::length_error Thrown if the resulting String would have been too large.

reference CEGUI::String::at ( size_type idx )

inline

Returns the code point at the given index.

Parameters

idx	Zero based index of the code point to be returned.

Returns: The utf32 code point at the given index within the String.

Exceptions

std::out_of_range Thrown if idx is >= length().

const_reference CEGUI::String::at ( size_type idx ) const

inline

Returns the code point at the given index.

Parameters

idx	Zero based index of the code point to be returned.

Returns: The utf32 code point at the given index within the String.

Exceptions

std::out_of_range Thrown if idx is >= length().

iterator CEGUI::String::begin ( void )

inline

Return a forwards iterator that describes the beginning of the String.

Returns: iterator object that describes the beginning of the String.

const_iterator CEGUI::String::begin ( void ) const

inline

Return a constant forwards iterator that describes the beginning of the String.

Returns: const_iterator object that describes the beginning of the String.

const char* CEGUI::String::c_str ( void ) const

inline

Returns contents of the String as a null terminated string of utf8 encoded data.

Returns: Pointer to a char buffer containing the contents of the String encoded as null-terminated utf8 data.

Note: The buffer returned from this function is owned by the String object.; Any function that modifies the String data will invalidate the buffer returned by this call.

size_type CEGUI::String::capacity ( void ) const

inline

Return the number of code points that the String could hold before a re-allocation would be required.

Returns: Size of the current reserve buffer. This is the maximum number of code points the String could hold before a buffer re-allocation would be required

void CEGUI::String::clear ( void )

inline

Removes all data from the String.

Returns: Nothing

int CEGUI::String::compare ( const String & str ) const

inline

Compares this String with the String 'str'.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

str	The String object that is to compared with this String.

Returns

0 if the String objects are equal
<0 if this String is lexicographically smaller than str
>0 if this String is lexicographically greater than str

int CEGUI::String::compare	(	size_type	idx,
		size_type	len,
		const String &	str,
		size_type	str_idx = `0`,
		size_type	str_len = `npos`
	)		const

inline

Compares code points from this String with code points from the String 'str'.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

idx	Index of the first code point from this String to consider.
len	Maximum number of code points from this String to consider.
str	The String object that is to compared with this String.
str_idx	Index of the first code point from String str to consider.
str_len	Maximum number of code points from String str to consider

Returns

0 if the specified sub-strings are equal
<0 if specified sub-strings are lexicographically smaller than str
>0 if specified sub-strings are lexicographically greater than str

Exceptions

std::out_of_range Thrown if either idx or str_idx are invalid.

References ptr().

int CEGUI::String::compare ( const std::string & std_str ) const

inline

Compares this String with the std::string 'std_str'.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

std_str The std::string object that is to compared with this String.

Note: Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.

Returns

0 if the string objects are equal
<0 if this string is lexicographically smaller than std_str
>0 if this string is lexicographically greater than std_str

int CEGUI::String::compare	(	size_type	idx,
		size_type	len,
		const std::string &	std_str,
		size_type	str_idx = `0`,
		size_type	str_len = `npos`
	)		const

inline

Compares code points from this String with code points from the std::string 'std_str'.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

idx	Index of the first code point from this String to consider.
len	Maximum number of code points from this String to consider.
std_str	The std::string object that is to compared with this String.

Note: Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.

Parameters

str_idx	Index of the first character from std::string std_str to consider.
str_len	Maximum number of characters from std::string std_str to consider

Returns

0 if the specified sub-strings are equal
<0 if specified sub-strings are lexicographically smaller than std_str
>0 if specified sub-strings are lexicographically greater than std_str

Exceptions

std::out_of_range Thrown if either idx or str_idx are invalid.

int CEGUI::String::compare ( const utf8 * utf8_str ) const

inline

Compares this String with the null-terminated utf8 encoded 'utf8_str'.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

utf8_str The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Returns

0 if the strings are equal
<0 if this string is lexicographically smaller than utf8_str
>0 if this string is lexicographically greater than utf8_str

int CEGUI::String::compare	(	size_type	idx,
		size_type	len,
		const utf8 *	utf8_str
	)		const

inline

Compares code points from this String with the null-terminated utf8 encoded 'utf8_str'.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

idx	Index of the first code point from this String to consider.
len	Maximum number of code points from this String to consider.
utf8_str	The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Returns

0 if the specified sub-strings are equal
<0 if specified sub-strings are lexicographically smaller than utf8_str
>0 if specified sub-strings are lexicographically greater than utf8_str

Exceptions

std::out_of_range Thrown if idx is invalid.

int CEGUI::String::compare	(	size_type	idx,
		size_type	len,
		const utf8 *	utf8_str,
		size_type	str_cplen
	)		const

inline

Compares code points from this String with the utf8 encoded data in buffer 'utf8_str'.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

idx	Index of the first code point from this String to consider.
len	Maximum number of code points from this String to consider.
utf8_str	The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

str_cplen The number of encoded code points in the buffer utf8_str (this is not the same as the number of code units).

Returns

0 if the specified sub-strings are equal
<0 if specified sub-strings are lexicographically smaller than utf8_str
>0 if specified sub-strings are lexicographically greater than utf8_str

Exceptions

std::out_of_range	Thrown if idx is invalid.
std::length_error	Thrown if str_cplen is set to npos.

int CEGUI::String::compare ( const char * cstr ) const

inline

Compares this String with the given c-string.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

c_str The c-string that is to compared with this String.

Returns

0 if the strings are equal
<0 if this string is lexicographically smaller than c_str
>0 if this string is lexicographically greater than c_str

int CEGUI::String::compare	(	size_type	idx,
		size_type	len,
		const char *	cstr
	)		const

inline

Compares code points from this String with the given c-string.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

idx	Index of the first code point from this String to consider.
len	Maximum number of code points from this String to consider.
c_str	The c-string that is to compared with this String.

Returns

0 if the specified sub-strings are equal
<0 if specified sub-strings are lexicographically smaller than c_str
>0 if specified sub-strings are lexicographically greater than c_str

Exceptions

std::out_of_range Thrown if idx is invalid.

int CEGUI::String::compare	(	size_type	idx,
		size_type	len,
		const char *	chars,
		size_type	chars_len
	)		const

inline

Compares code points from this String with chars in the given char array.

Note: This does currently not properly consider Unicode and / or the system locale.

Parameters

idx	Index of the first code point from this String to consider.
len	Maximum number of code points from this String to consider.
chars	The array containing the chars that are to compared with this String.
chars_len	The number of chars in the array.

Returns

0 if the specified sub-strings are equal
<0 if specified sub-strings are lexicographically smaller than chars
>0 if specified sub-strings are lexicographically greater than chars

Exceptions

std::out_of_range	Thrown if idx is invalid.
std::length_error	Thrown if chars_len is set to npos.

size_type CEGUI::String::copy	(	utf8 *	buf,
		size_type	len = `npos`,
		size_type	idx = `0`
	)		const

inline

Copies an area of the String into the provided buffer as encoded utf8 data.

Parameters

buf	Pointer to a buffer that is to receive the encoded data (this must be big enough to hold the encoded data)
len	Maximum number of code points from the String that should be encoded into the buffer
idx	Index of the first code point to be encoded into the buffer

Returns: The number of utf8 encoded code units transferred to the buffer.

Note: A code unit does not equal a code point. A utf32 code point, when encoded as utf8, can occupy between 1 and 4 code units.

Exceptions

std::out_of_range Thrown if idx was invalid for this String.

const utf8* CEGUI::String::data ( void ) const

inline

Returns contents of the String as utf8 encoded data.

Returns: Pointer to a buffer containing the contents of the String encoded utf8 data.

Note: The buffer returned from this function is owned by the String object.; Any function that modifies the String data will invalidate the buffer returned by this call.

bool CEGUI::String::empty ( void ) const

inline

Returns true if the String is empty.

Returns: true if the String is empty, else false.

Referenced by CEGUI::PropertyLinkDefinition< T >::getTargetWindow().

iterator CEGUI::String::end ( void )

inline

Return a forwards iterator that describes the end of the String.

Returns: iterator object that describes the end of the String.

const_iterator CEGUI::String::end ( void ) const

inline

Return a constant forwards iterator that describes the end of the String.

Returns: const_iterator object that describes the end of the String.

String& CEGUI::String::erase ( void )

inline

Removes all data from the String.

Returns: The empty String (*this)

String& CEGUI::String::erase ( size_type idx )

inline

Erase a single code point from the string.

Parameters

idx	The index of the code point to be removed.

Returns: This String after the erase operation

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

String& CEGUI::String::erase	(	size_type	idx,
		size_type	len
	)

inline

Erase a range of code points.

Parameters

idx	Index of the first code point to be removed.
len	Maximum number of code points to be removed.

Returns: This String after the erase operation.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

String& CEGUI::String::erase ( iterator pos )

inline

Erase the code point described by the given iterator.

Parameters

pos	Iterator describing the code point to be erased

Returns: This String after the erase operation.

String& CEGUI::String::erase	(	iterator	iter_beg,
		iterator	iter_end
	)

inline

Erase a range of code points described by the iterators [beg, end).

Parameters

beg	Iterator describing the postion of the beginning of the range to erase
end	Iterator describing the postion of the (exclusive) end of the range to erase

Returns: This String after the erase operation.

size_type CEGUI::String::find	(	utf32	code_point,
		size_type	idx = `0`
	)		const

inline

Search forwards for a given code point.

Parameters

code_point	The utf32 code point to search for
idx	Index of the code point where the search is to start.

Returns

Index of the first occurrence of code_point travelling forwards from idx.
npos if the code point could not be found

Referenced by find_first_not_of(), find_first_of(), find_last_not_of(), and find_last_of().

size_type CEGUI::String::find	(	const String &	str,
		size_type	idx = `0`
	)		const

inline

Search forwards for a sub-string.

Parameters

str	String object describing the sub-string to search for
idx	Index of the code point where the search is to start

Returns

Index of the first occurrence of sub-string str travelling forwards from idx.
npos if the sub-string could not be found

size_type CEGUI::String::find	(	const std::string &	std_str,
		size_type	idx = `0`
	)		const

inline

Search forwards for a sub-string.

Parameters

std_str std::string object describing the sub-string to search for

Note: Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.

Parameters

idx	Index of the code point where the search is to start

Returns

Index of the first occurrence of sub-string std_str travelling forwards from idx.
npos if the sub-string could not be found

size_type CEGUI::String::find	(	const utf8 *	utf8_str,
		size_type	idx = `0`
	)		const

inline

Search forwards for a sub-string.

Parameters

utf8_str Buffer containing null-terminated utf8 encoded data describing the sub-string to search for

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the code point where the search is to start

Returns

Index of the first occurrence of sub-string utf8_str travelling forwards from idx.
npos if the sub-string could not be found

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find	(	const utf8 *	utf8_str,
		size_type	idx,
		size_type	str_len
	)		const

inline

Search forwards for a sub-string.

Parameters

utf8_str Buffer containing utf8 encoded data describing the sub-string to search for

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the code point where the search is to start
str_len	Length of the utf8 encoded sub-string in utf8 code units (not code points)

Returns

Index of the first occurrence of sub-string utf8_str travelling forwards from idx.
npos if the sub-string could not be found

Exceptions

std::length_error Thrown if str_len is 'npos'

size_type CEGUI::String::find	(	const char *	cstr,
		size_type	idx = `0`
	)		const

inline

Search forwards for a sub-string.

Parameters

c_str	c-string describing the sub-string to search for
idx	Index of the code point where the search is to start

Returns

Index of the first occurrence of sub-string c_str travelling forwards from idx.
npos if the sub-string could not be found

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find	(	const char *	chars,
		size_type	idx,
		size_type	chars_len
	)		const

inline

Search forwards for a sub-string.

Parameters

chars	char array describing the sub-string to search for
idx	Index of the code point where the search is to start
chars_len	Number of chars in the char array.

Returns

Index of the first occurrence of sub-string chars travelling forwards from idx.
npos if the sub-string could not be found

Exceptions

std::length_error Thrown if chars_len is 'npos'

size_type CEGUI::String::find_first_not_of	(	const String &	str,
		size_type	idx = `0`
	)		const

inline

Find the first code point that is not one of a set of code points.

Parameters

str	String object describing the set of code points.
idx	Index of the start point for the search

Returns

Index of the first code point that does not match any one of the code points in str starting from from idx.
npos if all code points matched one of the code points in str.

References find().

size_type CEGUI::String::find_first_not_of	(	const std::string &	std_str,
		size_type	idx = `0`
	)		const

inline

Find the first code point that is not one of a set of code points.

Parameters

std_str std::string object describing the set of code points.

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Parameters

idx	Index of the start point for the search

Returns

Index of the first code point that does not match any one of the code points in std_str starting from from idx.
npos if all code points matched one of the code points in std_str.

size_type CEGUI::String::find_first_not_of	(	const utf8 *	utf8_str,
		size_type	idx = `0`
	)		const

inline

Find the first code point that is not one of a set of code points.

Parameters

utf8_str Buffer containing null-terminated utf8 encoded data describing the set of code points.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the start point for the search

Returns

Index of the first code point that does not match any one of the code points in utf8_str starting from from idx.
npos if all code points matched one of the code points in utf8_str.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_first_not_of	(	const utf8 *	utf8_str,
		size_type	idx,
		size_type	str_len
	)		const

inline

Find the first code point that is not one of a set of code points.

Parameters

utf8_str Buffer containing utf8 encoded data describing the set of code points.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the start point for the search
str_len	Length of the utf8 encoded data in utf8 code units (not code points).

Returns

Index of the first code point that does not match any one of the code points in utf8_str starting from from idx.
npos if all code points matched one of the code points in utf8_str.

Exceptions

std::length_error Thrown if str_len was 'npos'.

size_type CEGUI::String::find_first_not_of	(	utf32	code_point,
		size_type	idx = `0`
	)		const

inline

Search forwards for the first code point that does not match a given code point.

Parameters

code_point	The utf32 code point to search for
idx	Index of the code point where the search is to start.

Returns

Index of the first code point that does not match code_point starting from from idx.
npos if all code points matched code_point

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_first_not_of	(	const char *	cstr,
		size_type	idx = `0`
	)		const

inline

Find the first code point that is not one of a set of chars.

Parameters

c_str	c-string describing the set of chars.
idx	Index of the start point for the search

Returns

Index of the first code point that does not match any one of the chars in c_str starting from from idx.
npos if all code points matched any of the chars in c_str.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_first_not_of	(	const char *	chars,
		size_type	idx,
		size_type	chars_len
	)		const

inline

Find the first code point that is not one of a set of chars.

Parameters

chars	char array containing the set of chars.
idx	Index of the start point for the search
chars_len	Number of chars in the car array.

Returns

Index of the first code point that does not match any one of the chars in chars starting from from idx.
npos if all code points matched any of the chars in chars.

Exceptions

std::length_error Thrown if chars_len was 'npos'.

size_type CEGUI::String::find_first_of	(	const String &	str,
		size_type	idx = `0`
	)		const

inline

Find the first occurrence of one of a set of code points.

Parameters

str	String object describing the set of code points.
idx	Index of the start point for the search

Returns

Index of the first occurrence of any one of the code points in str starting from from idx.
npos if none of the code points in str were found.

References find().

size_type CEGUI::String::find_first_of	(	const std::string &	std_str,
		size_type	idx = `0`
	)		const

inline

Find the first occurrence of one of a set of code points.

Parameters

std_str std::string object describing the set of code points.

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Parameters

idx	Index of the start point for the search

Returns

Index of the first occurrence of any one of the code points in std_str starting from from idx.
npos if none of the code points in std_str were found.

size_type CEGUI::String::find_first_of	(	const utf8 *	utf8_str,
		size_type	idx = `0`
	)		const

inline

Find the first occurrence of one of a set of code points.

Parameters

utf8_str Buffer containing null-terminated utf8 encoded data describing the set of code points.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the start point for the search

Returns

Index of the first occurrence of any one of the code points in utf8_str starting from from idx.
npos if none of the code points in utf8_str were found.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_first_of	(	const utf8 *	utf8_str,
		size_type	idx,
		size_type	str_len
	)		const

inline

Find the first occurrence of one of a set of code points.

Parameters

utf8_str Buffer containing utf8 encoded data describing the set of code points.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the start point for the search
str_len	Length of the utf8 encoded data in utf8 code units (not code points).

Returns

Index of the first occurrence of any one of the code points in utf8_str starting from from idx.
npos if none of the code points in utf8_str were found.

Exceptions

std::length_error Thrown if str_len was 'npos'.

size_type CEGUI::String::find_first_of	(	utf32	code_point,
		size_type	idx = `0`
	)		const

inline

Search forwards for a given code point.

Parameters

code_point	The utf32 code point to search for
idx	Index of the code point where the search is to start.

Returns

Index of the first occurrence of code_point starting from from idx.
npos if the code point could not be found

size_type CEGUI::String::find_first_of	(	const char *	cstr,
		size_type	idx = `0`
	)		const

inline

Find the first occurrence of one of a set of chars.

Parameters

c_str	c-string describing the set of chars.
idx	Index of the start point for the search

Returns

Index of the first occurrence of any one of the chars in c_str starting from from idx.
npos if none of the chars in c_str were found.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_first_of	(	const char *	chars,
		size_type	idx,
		size_type	chars_len
	)		const

inline

Find the first occurrence of one of a set of chars.

Parameters

chars	char array containing the set of chars.
idx	Index of the start point for the search
chars_len	Number of chars in the char array.

Returns

Index of the first occurrence of any one of the chars in chars starting from from idx.
npos if none of the chars in chars were found.

Exceptions

std::length_error Thrown if chars_len was 'npos'.

size_type CEGUI::String::find_last_not_of	(	const String &	str,
		size_type	idx = `npos`
	)		const

inline

Find the last code point that is not one of a set of code points.

Parameters

str	String object describing the set of code points.
idx	Index of the start point for the search

Returns

Index of the last code point that does not match any one of the code points in str starting from idx.
npos if all code points matched one of the code points in str.

References find().

size_type CEGUI::String::find_last_not_of	(	const std::string &	std_str,
		size_type	idx = `npos`
	)		const

inline

Find the last code point that is not one of a set of code points.

Parameters

std_str std::string object describing the set of code points.

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Parameters

idx	Index of the start point for the search

Returns

Index of the last code point that does not match any one of the code points in std_str starting from idx.
npos if all code points matched one of the code points in std_str.

size_type CEGUI::String::find_last_not_of	(	const utf8 *	utf8_str,
		size_type	idx = `npos`
	)		const

inline

Find the last code point that is not one of a set of code points.

Parameters

utf8_str Buffer containing null-terminated utf8 encoded data describing the set of code points.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the start point for the search

Returns

Index of the last code point that does not match any one of the code points in utf8_str starting from idx.
npos if all code points matched one of the code points in utf8_str.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_last_not_of	(	const utf8 *	utf8_str,
		size_type	idx,
		size_type	str_len
	)		const

inline

Find the last code point that is not one of a set of code points.

Parameters

utf8_str Buffer containing utf8 encoded data describing the set of code points.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the start point for the search
str_len	Length of the utf8 encoded data in utf8 code units (not code points).

Returns

Index of the last code point that does not match any one of the code points in utf8_str starting from from idx.
npos if all code points matched one of the code points in utf8_str.

Exceptions

std::length_error Thrown if str_len was 'npos'.

size_type CEGUI::String::find_last_not_of	(	utf32	code_point,
		size_type	idx = `npos`
	)		const

inline

Search for the last code point that does not match a given code point.

Parameters

code_point	The utf32 code point to search for
idx	Index of the code point where the search is to start.

Returns

Index of the last code point that does not match code_point starting from from idx.
npos if all code points matched code_point

size_type CEGUI::String::find_last_not_of	(	const char *	cstr,
		size_type	idx = `npos`
	)		const

inline

Find the last code point that is not one of a set of chars.

Parameters

c_str	c-string describing the set of chars.
idx	Index of the start point for the search

Returns

Index of the last code point that does not match any one of the chars in c_str starting from idx.
npos if all code points matched any of the chars in c_str.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_last_not_of	(	const char *	chars,
		size_type	idx,
		size_type	chars_len
	)		const

inline

Find the last code point that is not one of a set of chars.

Parameters

chars	char array containing the set of chars.
idx	Index of the start point for the search
chars_len	Number of chars in the char array.

Returns

Index of the last code point that does not match any one of the chars in chars, starting from from idx.
npos if all code points matched any of the chars in chars.

Exceptions

std::length_error Thrown if chars_len was 'npos'.

size_type CEGUI::String::find_last_of	(	const String &	str,
		size_type	idx = `npos`
	)		const

inline

Find the last occurrence of one of a set of code points.

Parameters

str	String object describing the set of code points.
idx	Index of the start point for the search

Returns

Index of the last occurrence of any one of the code points in str starting from idx.
npos if none of the code points in str were found.

References find().

size_type CEGUI::String::find_last_of	(	const std::string &	std_str,
		size_type	idx = `npos`
	)		const

inline

Find the last occurrence of one of a set of code points.

Parameters

std_str std::string object describing the set of code points.

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Parameters

idx	Index of the start point for the search

Returns

Index of the last occurrence of any one of the code points in std_str starting from idx.
npos if none of the code points in std_str were found.

size_type CEGUI::String::find_last_of	(	const utf8 *	utf8_str,
		size_type	idx = `npos`
	)		const

inline

Find the last occurrence of one of a set of code points.

Parameters

utf8_str Buffer containing null-terminated utf8 encoded data describing the set of code points.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the start point for the search

Returns

Index of the last occurrence of any one of the code points in utf8_str starting from idx.
npos if none of the code points in utf8_str were found.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_last_of	(	const utf8 *	utf8_str,
		size_type	idx,
		size_type	str_len
	)		const

inline

Find the last occurrence of one of a set of code points.

Parameters

utf8_str Buffer containing utf8 encoded data describing the set of code points.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the start point for the search
str_len	Length of the utf8 encoded data in utf8 code units (not code points).

Returns

Index of the last occurrence of any one of the code points in utf8_str starting from from idx.
npos if none of the code points in utf8_str were found.

Exceptions

std::length_error Thrown if str_len was 'npos'.

size_type CEGUI::String::find_last_of	(	utf32	code_point,
		size_type	idx = `npos`
	)		const

inline

Search for last occurrence of a given code point.

Parameters

code_point	The utf32 code point to search for
idx	Index of the code point where the search is to start.

Returns

Index of the last occurrence of code_point starting from idx.
npos if the code point could not be found

size_type CEGUI::String::find_last_of	(	const char *	cstr,
		size_type	idx = `npos`
	)		const

inline

Find the last occurrence of one of a set of chars.

Parameters

c_str	c-string describing the set of chars.
idx	Index of the start point for the search

Returns

Index of the last occurrence of any one of the chars in c_str starting from idx.
npos if none of the chars in c_str were found.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_last_of	(	const char *	chars,
		size_type	idx,
		size_type	chars_len
	)		const

inline

Find the last occurrence of one of a set of chars.

Parameters

chars	char array containing the set of chars.
idx	Index of the start point for the search
chars_len	Number of chars in the char array.

Returns

Index of the last occurrence of any one of the chars in chars, starting from from idx.
npos if none of the chars in chars were found.

Exceptions

std::length_error Thrown if chars_len was 'npos'.

String& CEGUI::String::insert	(	size_type	idx,
		const String &	str
	)

inline

Inserts the given String object at the specified position.

Parameters

idx	Index where the string is to be inserted.
str	String object that is to be inserted.

Returns: This String after the insert.

Exceptions

std::out_of_range	Thrown if idx is invalid for this String.
std::length_error	Thrown if resulting String would be too large.

String& CEGUI::String::insert	(	size_type	idx,
		const String &	str,
		size_type	str_idx,
		size_type	str_num
	)

inline

Inserts a sub-string of the given String object at the specified position.

Parameters

idx	Index where the string is to be inserted.
str	String object containing data to be inserted.
str_idx	Index of the first code point from str to be inserted.
str_num	Maximum number of code points from str to be inserted.

Returns: This String after the insert.

Exceptions

std::out_of_range	Thrown if idx or str_idx are out of range.
std::length_error	Thrown if resulting String would be too large.

References ptr().

String& CEGUI::String::insert	(	size_type	idx,
		const std::string &	std_str
	)

inline

Inserts the given std::string object at the specified position.

Parameters

idx	Index where the std::string is to be inserted.
std_str	std::string object that is to be inserted.

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Returns: This String after the insert.

Exceptions

std::out_of_range	Thrown if idx is invalid for this String.
std::length_error	Thrown if resulting String would be too large.

String& CEGUI::String::insert	(	size_type	idx,
		const std::string &	std_str,
		size_type	str_idx,
		size_type	str_num
	)

inline

Inserts a sub-string of the given std::string object at the specified position.

Parameters

idx	Index where the string is to be inserted.
std_str	std::string object containing data to be inserted.

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Parameters

str_idx	Index of the first character from std_str to be inserted.
str_num	Maximum number of characters from str to be inserted.

Returns: This String after the insert.

Exceptions

std::out_of_range	Thrown if idx or str_idx are out of range.
std::length_error	Thrown if resulting String would be too large.

String& CEGUI::String::insert	(	size_type	idx,
		const utf8 *	utf8_str
	)

inline

Inserts the given null-terminated utf8 encoded data at the specified position.

Parameters

idx	Index where the data is to be inserted.
utf8_str	Buffer containing the null-terminated utf8 encoded data that is to be inserted.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Returns: This String after the insert.

Exceptions

std::out_of_range	Thrown if idx is invalid for this String.
std::length_error	Thrown if resulting String would be too large.

String& CEGUI::String::insert	(	size_type	idx,
		const utf8 *	utf8_str,
		size_type	len
	)

inline

Inserts the given utf8 encoded data at the specified position.

Parameters

idx	Index where the data is to be inserted.
utf8_str	Buffer containing the utf8 encoded data that is to be inserted.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

len	Length of the data to be inserted in uf8 code units (not code points)

Returns: This String after the insert.

Exceptions

std::out_of_range	Thrown if idx is invalid for this String.
std::length_error	Thrown if resulting String would be too large, or if len is 'npos'

String& CEGUI::String::insert	(	size_type	idx,
		size_type	num,
		utf32	code_point
	)

inline

Inserts a code point multiple times into the String.

Parameters

idx	Index where the code point(s) are to be inserted
num	The number of times to insert the code point
code_point	The utf32 code point that is to be inserted

Returns: This String after the insertion.

Exceptions

std::out_of_range	Thrown if idx is invalid for this String.
std::length_error	Thrown if resulting String would be too large, or if num is 'npos'

void CEGUI::String::insert	(	iterator	pos,
		size_type	num,
		utf32	code_point
	)

inline

Inserts a code point multiple times into the String.

Parameters

pos	Iterator describing the position where the code point(s) are to be inserted
num	The number of times to insert the code point
code_point	The utf32 code point that is to be inserted

Returns: This String after the insertion.

Exceptions

std::length_error Thrown if resulting String would be too large, or if num is 'npos'

iterator CEGUI::String::insert	(	iterator	pos,
		utf32	code_point
	)

inline

Inserts a single code point into the String.

Parameters

pos	Iterator describing the position where the code point is to be inserted
code_point	The utf32 code point that is to be inserted

Returns: This String after the insertion.

Exceptions

std::length_error Thrown if resulting String would be too large.

void CEGUI::String::insert	(	iterator	iter_pos,
		const_iterator	iter_beg,
		const_iterator	iter_end
	)

inline

Inserts code points specified by the range [beg, end).

Parameters

pos	Iterator describing the position where the data is to be inserted
beg	Iterator describing the begining of the range to be inserted
end	Iterator describing the (exclusive) end of the range to be inserted.

Returns: Nothing.

Exceptions

std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::insert	(	size_type	idx,
		const char *	cstr
	)

inline

Inserts the given c-string at the specified position.

Parameters

idx	Index where the c-string is to be inserted.
c_str	c-string that is to be inserted.

Returns: This String after the insert.

Exceptions

std::out_of_range	Thrown if idx is invalid for this String.
std::length_error	Thrown if resulting String would be too large.

String& CEGUI::String::insert	(	size_type	idx,
		const char *	chars,
		size_type	chars_len
	)

inline

Inserts chars from the given char array at the specified position.

Parameters

idx	Index where the data is to be inserted.
chars	char array containing the chars that are to be inserted.
chars_len	Length of the char array to be inserted.

Returns: This String after the insert.

Exceptions

std::out_of_range	Thrown if idx is invalid for this String.
std::length_error	Thrown if resulting String would be too large, or if chars_len is 'npos'

size_type CEGUI::String::length ( void ) const

inline

Returns the size of the String in code points.

Returns: Number of code points currently in the String

size_type CEGUI::String::max_size ( void ) const

inline

Returns the maximum size of a String.

Any operation that would result in a String that is larger than this value will throw the std::length_error exception.

Returns: The maximum number of code points that a string can contain

String& CEGUI::String::operator+= ( const String & str )

inline

Appends the String str.

Parameters

str	String object that is to be appended

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::operator+= ( const std::string & std_str )

inline

Appends the std::string std_str.

Parameters

std_str std::string object that is to be appended

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::operator+= ( const utf8 * utf8_str )

inline

Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.

Parameters

utf8_str buffer holding the null-terminated utf8 encoded data that is to be appended

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::operator+= ( utf32 code_point )

inline

Appends a single code point to the string.

Parameters

code_point utf32 Unicode code point that is to be appended

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too long.

String& CEGUI::String::operator+= ( const char * cstr )

inline

Appends to the String the given c-string.

Parameters

c_str c-string that is to be appended.

Returns: This String after the append operation

Exceptions

std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::operator= ( const String & str )

inline

Assign the value of String str to this String.

Parameters

str	String object containing the string value to be assigned.

Returns: This String after the assignment has happened

String& CEGUI::String::operator= ( const std::string & std_str )

inline

Assign the value of std::string std_str to this String.

Note: The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.

Parameters

std_str std::string object containing the string value to be assigned.

Returns: This String after the assignment has happened

Exceptions

std::length_error Thrown if the resulting String would have been too large.

String& CEGUI::String::operator= ( const utf8 * utf8_str )

inline

Assign to this String the string value represented by the given null-terminated utf8 encoded data.

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

utf8_str Buffer containing valid null-terminated utf8 encoded data

Returns: This String after the assignment has happened

Exceptions

std::length_error Thrown if the resulting String would have been too large.

String& CEGUI::String::operator= ( utf32 code_point )

inline

Assigns the specified utf32 code point to this String. Result is always a String 1 code point in length.

Parameters

code_point Valid utf32 Unicode code point to be assigned to the string

Returns: This String after assignment

String& CEGUI::String::operator= ( const char * cstr )

inline

Assign to this String the given C-string.

Parameters

c_str Pointer to a valid C style string.

Returns: This String after the assignment has happened

Exceptions

std::length_error Thrown if the resulting String would have been too large.

reference CEGUI::String::operator[] ( size_type idx )

inline

Returns the code point at the given index.

Parameters

idx	Zero based index of the code point to be returned.

Note

For constant strings length()/size() provide a valid index and will access the default utf32 value.
For non-constant strings length()/size() is an invalid index, and acceesing (especially writing) this index could cause string corruption.

Returns: The utf32 code point at the given index within the String.

value_type CEGUI::String::operator[] ( size_type idx ) const

inline

Returns the code point at the given index.

Parameters

idx	Zero based index of the code point to be returned.

Note

For constant strings length()/size() provide a valid index and will access the default utf32 value.
For non-constant strings length()/size() is an invalid index, and acceesing (especially writing) this index could cause string corruption.

Returns: The utf32 code point at the given index within the String.

void CEGUI::String::push_back ( utf32 code_point )

inline

Appends a single code point to the string.

Parameters

code_point utf32 Unicode code point that is to be appended

Returns: Nothing

Exceptions

std::length_error Thrown if resulting String would be too long.

reverse_iterator CEGUI::String::rbegin ( void )

inline

Return a reverse iterator that describes the beginning of the String.

Returns: reverse_iterator object that describes the beginning of the String (so is actually at the end)

const_reverse_iterator CEGUI::String::rbegin ( void ) const

inline

Return a constant reverse iterator that describes the beginning of the String.

Returns: const_reverse_iterator object that describes the beginning of the String (so is actually at the end)

reverse_iterator CEGUI::String::rend ( void )

inline

Return a reverse iterator that describes the end of the String.

Returns: reverse_iterator object that describes the end of the String (so is actually at the beginning)

const_reverse_iterator CEGUI::String::rend ( void ) const

inline

Return a constant reverse iterator that describes the end of the String.

Returns: const_reverse_iterator object that describes the end of the String (so is actually at the beginning)

String& CEGUI::String::replace	(	size_type	idx,
		size_type	len,
		const String &	str
	)

inline

Replace code points in the String with the specified String object.

Parameters

idx	Index of the first code point to be replaced
len	Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
str	The String object that is to replace the specified code points

Returns: This String after the replace operation

Exceptions

std::out_of_range	Thrown if idx is invalid for this String
std::length_error	Thrown if the resulting String would be too large.

String& CEGUI::String::replace	(	iterator	iter_beg,
		iterator	iter_end,
		const String &	str
	)

inline

Replace the code points in the range [beg, end) with the specified String object.

Note: If beg == end, the operation is a insert at iterator position beg

Parameters

beg	Iterator describing the start of the range to be replaced
end	Iterator describing the (exclusive) end of the range to be replaced.
str	The String object that is to replace the specified range of code points

Returns: This String after the replace operation

Exceptions

std::length_error Thrown if the resulting String would be too large.

String& CEGUI::String::replace	(	size_type	idx,
		size_type	len,
		const String &	str,
		size_type	str_idx,
		size_type	str_num
	)

inline

Replace code points in the String with a specified sub-string of a given String object.

Parameters

idx	Index of the first code point to be replaced
len	Maximum number of code points to be replaced. If this is 0, the operation is an insert at position idx.
str	String object containing the data that will replace the specified range of code points
str_idx	Index of the first code point of str that is to replace the specified code point range
str_num	Maximum number of code points of str that are to replace the specified code point range

Returns: This String after the replace operation

Exceptions

std::out_of_range	Thrown if either idx, or str_idx are invalid
std::length_error	Thrown if the resulting String would have been too large.

References ptr().

String& CEGUI::String::replace	(	size_type	idx,
		size_type	len,
		const std::string &	std_str
	)

inline

Replace code points in the String with the specified std::string object.

Parameters

idx	Index of the first code point to be replaced
len	Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
std_str	The std::string object that is to replace the specified code points

Note: Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.

Returns: This String after the replace operation

Exceptions

std::out_of_range	Thrown if idx is invalid for this String
std::length_error	Thrown if the resulting String would be too large.

String& CEGUI::String::replace	(	iterator	iter_beg,
		iterator	iter_end,
		const std::string &	std_str
	)

inline

Replace the code points in the range [beg, end) with the specified std::string object.

Note: If beg == end, the operation is a insert at iterator position beg

Parameters

beg	Iterator describing the start of the range to be replaced
end	Iterator describing the (exclusive) end of the range to be replaced.
std_str	The std::string object that is to replace the specified range of code points

Note: Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.

Returns: This String after the replace operation

Exceptions

std::length_error Thrown if the resulting String would be too large.

String& CEGUI::String::replace	(	size_type	idx,
		size_type	len,
		const std::string &	std_str,
		size_type	str_idx,
		size_type	str_num
	)

inline

Replace code points in the String with a specified sub-string of a given std::string object.

Parameters

idx	Index of the first code point to be replaced
len	Maximum number of code points to be replaced. If this is 0, the operation is an insert at position idx.
std_str	std::string object containing the data that will replace the specified range of code points

Note: Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.

Parameters

str_idx	Index of the first code point of std_str that is to replace the specified code point range
str_num	Maximum number of code points of std_str that are to replace the specified code point range

Returns: This String after the replace operation

Exceptions

std::out_of_range	Thrown if either idx, or str_idx are invalid
std::length_error	Thrown if the resulting String would have been too large.

String& CEGUI::String::replace	(	size_type	idx,
		size_type	len,
		const utf8 *	utf8_str
	)

inline

Replace code points in the String with the specified null-terminated utf8 encoded data.

Parameters

idx	Index of the first code point to be replaced
len	Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
utf8_str	Buffer containing the null-terminated utf8 encoded data that is to replace the specified code points

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Returns: This String after the replace operation

Exceptions

std::out_of_range	Thrown if idx is invalid for this String
std::length_error	Thrown if the resulting String would be too large.

String& CEGUI::String::replace	(	iterator	iter_beg,
		iterator	iter_end,
		const utf8 *	utf8_str
	)

inline

Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data.

Note: If beg == end, the operation is a insert at iterator position beg

Parameters

beg	Iterator describing the start of the range to be replaced
end	Iterator describing the (exclusive) end of the range to be replaced.
utf8_str	Buffer containing the null-terminated utf8 encoded data that is to replace the specified range of code points

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Returns: This String after the replace operation

Exceptions

std::length_error Thrown if the resulting String would be too large.

String& CEGUI::String::replace	(	size_type	idx,
		size_type	len,
		const utf8 *	utf8_str,
		size_type	str_len
	)

inline

Replace code points in the String with the specified utf8 encoded data.

Parameters

idx	Index of the first code point to be replaced
len	Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
utf8_str	Buffer containing the null-terminated utf8 encoded data that is to replace the specified code points

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

str_len Length of the utf8 encoded data in utf8 code units (not code points).

Returns: This String after the replace operation

Exceptions

std::out_of_range	Thrown if idx is invalid for this String
std::length_error	Thrown if the resulting String would be too large, or if str_len was 'npos'.

String& CEGUI::String::replace	(	iterator	iter_beg,
		iterator	iter_end,
		const utf8 *	utf8_str,
		size_type	str_len
	)

inline

Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data.

Note: If beg == end, the operation is a insert at iterator position beg

Parameters

beg	Iterator describing the start of the range to be replaced
end	Iterator describing the (exclusive) end of the range to be replaced.
utf8_str	Buffer containing the null-terminated utf8 encoded data that is to replace the specified range of code points

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

str_len Length of the utf8 encoded data in utf8 code units (not code points).

Returns: This String after the replace operation

Exceptions

std::length_error Thrown if the resulting String would be too large, or if str_len was 'npos'.

String& CEGUI::String::replace	(	size_type	idx,
		size_type	len,
		size_type	num,
		utf32	code_point
	)

inline

Replaces a specified range of code points with occurrences of a given code point.

Parameters

idx	Index of the first code point to be replaced
len	Maximum number of code points to replace. If this is 0 the operation is an insert
num	Number of occurrences of code_point that are to replace the specified range of code points
code_point	Code point that is to be used when replacing the specified range of code points

Returns: This String after the replace operation.

Exceptions

std::out_of_range	Thrown if idx is invalid for this String
std::length_error	Thrown if resulting String would have been too long, or if num was 'npos'.

String& CEGUI::String::replace	(	iterator	iter_beg,
		iterator	iter_end,
		size_type	num,
		utf32	code_point
	)

inline

Replace the code points in the range [beg, end) with occurrences of a given code point.

Note: If beg == end, the operation is an insert at iterator position beg

Parameters

beg	Iterator describing the start of the range to be replaced
end	Iterator describing the (exclusive) end of the range to be replaced.
num	Number of occurrences of code_point that are to replace the specified range of code points
code_point	Code point that is to be used when replacing the specified range of code points

Returns: This String after the replace operation

Exceptions

std::length_error Thrown if resulting String would have been too long, or if num was 'npos'.

String& CEGUI::String::replace	(	iterator	iter_beg,
		iterator	iter_end,
		const_iterator	iter_newBeg,
		const_iterator	iter_newEnd
	)

inline

Replace the code points in the range [beg, end) with code points from the range [newBeg, newEnd).

Note: If beg == end, the operation is an insert at iterator position beg

Parameters

beg	Iterator describing the start of the range to be replaced
end	Iterator describing the (exclusive) end of the range to be replaced.
newBeg	Iterator describing the beginning of the range to insert.
newEnd	Iterator describing the (exclusive) end of the range to insert.

Returns: This String after the insert operation.

Exceptions

std::length_error Thrown if the resulting string would be too long.

String& CEGUI::String::replace	(	size_type	idx,
		size_type	len,
		const char *	cstr
	)

inline

Replace code points in the String with the specified c-string.

Parameters

idx	Index of the first code point to be replaced
len	Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
c_str	c-string that is to replace the specified code points

Returns: This String after the replace operation

Exceptions

std::out_of_range	Thrown if idx is invalid for this String
std::length_error	Thrown if the resulting String would be too large.

String& CEGUI::String::replace	(	iterator	iter_beg,
		iterator	iter_end,
		const char *	cstr
	)

inline

Replace the code points in the range [beg, end) with the specified c-string.

Note: If beg == end, the operation is a insert at iterator position beg

Parameters

beg	Iterator describing the start of the range to be replaced
end	Iterator describing the (exclusive) end of the range to be replaced.
c_str	c-string that is to replace the specified range of code points

Returns: This String after the replace operation

Exceptions

std::length_error Thrown if the resulting String would be too large.

String& CEGUI::String::replace	(	size_type	idx,
		size_type	len,
		const char *	chars,
		size_type	chars_len
	)

inline

Replace code points in the String with chars from the given char array.

Parameters

idx	Index of the first code point to be replaced
len	Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
chars	char array containing the cars that are to replace the specified code points
chars_len	Number of chars in the char array.

Returns: This String after the replace operation

Exceptions

std::out_of_range	Thrown if idx is invalid for this String
std::length_error	Thrown if the resulting String would be too large, or if chars_len was 'npos'.

String& CEGUI::String::replace	(	iterator	iter_beg,
		iterator	iter_end,
		const char *	chars,
		size_type	chars_len
	)

inline

Replace the code points in the range [beg, end) with chars from the given char array.

Note: If beg == end, the operation is a insert at iterator position beg

Parameters

beg	Iterator describing the start of the range to be replaced
end	Iterator describing the (exclusive) end of the range to be replaced.
chars	char array containing the chars that are to replace the specified range of code points
chars_len	Number of chars in the char array.

Returns: This String after the replace operation

Exceptions

std::length_error Thrown if the resulting String would be too large, or if chars_len was 'npos'.

void CEGUI::String::reserve ( size_type num = 0 )

inline

Specifies the amount of reserve capacity to allocate.

Parameters

num The number of code points to allocate space for. If num is larger that the current reserve, then a re-allocation will occur. If num is smaller than the current reserve (but not 0) the buffer may be shrunk to the larger of the specified number, or the current String size (operation is currently not implemented). If num is 0, then the buffer is re-allocated to fit the current String size.

Returns: Nothing

Exceptions

std::length_error Thrown if resulting String object would be too big.

void CEGUI::String::resize ( size_type num )

inline

Resizes the String either by inserting default utf32 code points to make it larger, or by truncating to make it smaller.

Parameters

num	The length, in code points, that the String is to be made.

Returns: Nothing.

Exceptions

std::length_error Thrown if the String would be too large.

void CEGUI::String::resize	(	size_type	num,
		utf32	code_point
	)

inline

Resizes the String either by inserting the given utf32 code point to make it larger, or by truncating to make it smaller.

Parameters

num	The length, in code points, that the String is to be made.
code_point	The utf32 code point that should be used when majing the String larger

Returns: Nothing.

Exceptions

std::length_error Thrown if the String would be too large.

size_type CEGUI::String::rfind	(	utf32	code_point,
		size_type	idx = `npos`
	)		const

inline

Search backwards for a given code point.

Parameters

code_point	The utf32 code point to search for
idx	Index of the code point where the search is to start.

Returns

Index of the first occurrence of code_point travelling backwards from idx.
npos if the code point could not be found

size_type CEGUI::String::rfind	(	const String &	str,
		size_type	idx = `npos`
	)		const

inline

Search backwards for a sub-string.

Parameters

str	String object describing the sub-string to search for
idx	Index of the code point where the search is to start

Returns

Index of the first occurrence of sub-string str travelling backwards from idx.
npos if the sub-string could not be found

size_type CEGUI::String::rfind	(	const std::string &	std_str,
		size_type	idx = `npos`
	)		const

inline

Search backwards for a sub-string.

Parameters

std_str std::string object describing the sub-string to search for

Note: Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.

Parameters

idx	Index of the code point where the search is to start

Returns

Index of the first occurrence of sub-string std_str travelling backwards from idx.
npos if the sub-string could not be found

size_type CEGUI::String::rfind	(	const utf8 *	utf8_str,
		size_type	idx = `npos`
	)		const

inline

Search backwards for a sub-string.

Parameters

utf8_str Buffer containing null-terminated utf8 encoded data describing the sub-string to search for

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the code point where the search is to start

Returns

Index of the first occurrence of sub-string utf8_str travelling backwards from idx.
npos if the sub-string could not be found

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::rfind	(	const utf8 *	utf8_str,
		size_type	idx,
		size_type	str_len
	)		const

inline

Search backwards for a sub-string.

Parameters

utf8_str Buffer containing utf8 encoded data describing the sub-string to search for

Note: A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.

Parameters

idx	Index of the code point where the search is to start
str_len	Length of the utf8 encoded sub-string in utf8 code units (not code points)

Returns

Index of the first occurrence of sub-string utf8_str travelling backwards from idx.
npos if the sub-string could not be found

Exceptions

std::length_error Thrown if str_len is 'npos'

size_type CEGUI::String::rfind	(	const char *	cstr,
		size_type	idx = `npos`
	)		const

inline

Search backwards for a sub-string.

Parameters

c_str	c-string describing the sub-string to search for
idx	Index of the code point where the search is to start

Returns

Index of the first occurrence of sub-string c_str travelling backwards from idx.
npos if the sub-string could not be found

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::rfind	(	const char *	chars,
		size_type	idx,
		size_type	chars_len
	)		const

inline

Search backwards for a sub-string.

Parameters

chars	char array describing the sub-string to search for
idx	Index of the code point where the search is to start
chars_len	Number of chars in the char array.

Returns

Index of the first occurrence of sub-string chars travelling backwards from idx.
npos if the sub-string could not be found

Exceptions

std::length_error Thrown if chars_len is 'npos'

size_type CEGUI::String::size ( void ) const

inline

Returns the size of the String in code points.

Returns: Number of code points currently in the String

String CEGUI::String::substr	(	size_type	idx = `0`,
		size_type	len = `npos`
	)		const

inline

Returns a substring of this String.

Parameters

idx	Index of the first code point to use for the sub-string.
len	Maximum number of code points to use for the sub-string

Returns: A String object containing the specified sub-string.

Exceptions

std::out_of_range Thrown if idx is invalid for this String.

void CEGUI::String::swap ( String & str )

inline

Swaps the value of this String with the given String str.

Parameters

str	String object whos value is to be swapped with this String.

Returns: Nothing

size_type CEGUI::String::utf8_stream_len	(	size_type	num = `npos`,
		size_type	idx = `0`
	)		const

inline

Return the number of utf8 code units required to hold an area of the String when encoded as utf8 data.

Parameters

num	Maximum number of code points to consider when calculating utf8 encoded size.
idx	Index of the first code point to consider when calculating the utf8 encoded size

Returns: The number of utf8 code units (bytes) required to hold the specified sub-string when encoded as utf8 data.

Exceptions

std::out_of_range Thrown if idx was invalid for this String.

Classes

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation