Crazy Eddie's GUI System  0.8.5
CEGUI::String Class Reference

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_iteratorconst_reverse_iterator
 Constant reverse iterator class for String objects.
 
typedef std::reverse_iterator< iteratorreverse_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...
 
Stringoperator= (const String &str)
 Assign the value of String str to this String. More...
 
Stringassign (const String &str, size_type str_idx=0, size_type str_num=npos)
 Assign a sub-string of String str to this String. More...
 
Stringoperator= (const std::string &std_str)
 Assign the value of std::string std_str to this String. More...
 
Stringassign (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...
 
Stringoperator= (const utf8 *utf8_str)
 Assign to this String the string value represented by the given null-terminated utf8 encoded data. More...
 
Stringassign (const utf8 *utf8_str)
 Assign to this String the string value represented by the given null-terminated utf8 encoded data. More...
 
Stringassign (const utf8 *utf8_str, size_type str_num)
 Assign to this String the string value represented by the given utf8 encoded data. More...
 
Stringoperator= (utf32 code_point)
 Assigns the specified utf32 code point to this String. Result is always a String 1 code point in length. More...
 
Stringassign (size_type num, utf32 code_point)
 Assigns the specified code point repeatedly to the String. More...
 
Stringoperator= (const char *cstr)
 Assign to this String the given C-string. More...
 
Stringassign (const char *cstr)
 Assign to this String the given C-string. More...
 
Stringassign (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...
 
Stringoperator+= (const String &str)
 Appends the String str. More...
 
Stringappend (const String &str, size_type str_idx=0, size_type str_num=npos)
 Appends a sub-string of the String str. More...
 
Stringoperator+= (const std::string &std_str)
 Appends the std::string std_str. More...
 
Stringappend (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...
 
Stringoperator+= (const utf8 *utf8_str)
 Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str. More...
 
Stringappend (const utf8 *utf8_str)
 Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str. More...
 
Stringappend (const utf8 *utf8_str, size_type len)
 Appends to the String the utf8 encoded data in the buffer utf8_str. More...
 
Stringoperator+= (utf32 code_point)
 Appends a single code point to the string. More...
 
Stringappend (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...
 
Stringappend (const_iterator iter_beg, const_iterator iter_end)
 Appends the code points in the reange [beg, end) More...
 
Stringoperator+= (const char *cstr)
 Appends to the String the given c-string. More...
 
Stringappend (const char *cstr)
 Appends to the String the given c-string. More...
 
Stringappend (const char *chars, size_type chars_len)
 Appends to the String chars from the given char array. More...
 
Stringinsert (size_type idx, const String &str)
 Inserts the given String object at the specified position. More...
 
Stringinsert (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...
 
Stringinsert (size_type idx, const std::string &std_str)
 Inserts the given std::string object at the specified position. More...
 
Stringinsert (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...
 
Stringinsert (size_type idx, const utf8 *utf8_str)
 Inserts the given null-terminated utf8 encoded data at the specified position. More...
 
Stringinsert (size_type idx, const utf8 *utf8_str, size_type len)
 Inserts the given utf8 encoded data at the specified position. More...
 
Stringinsert (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...
 
Stringinsert (size_type idx, const char *cstr)
 Inserts the given c-string at the specified position. More...
 
Stringinsert (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...
 
Stringerase (void)
 Removes all data from the String. More...
 
Stringerase (size_type idx)
 Erase a single code point from the string. More...
 
Stringerase (size_type idx, size_type len)
 Erase a range of code points. More...
 
Stringerase (iterator pos)
 Erase the code point described by the given iterator. More...
 
Stringerase (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...
 
Stringreplace (size_type idx, size_type len, const String &str)
 Replace code points in the String with the specified String object. More...
 
Stringreplace (iterator iter_beg, iterator iter_end, const String &str)
 Replace the code points in the range [beg, end) with the specified String object. More...
 
Stringreplace (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...
 
Stringreplace (size_type idx, size_type len, const std::string &std_str)
 Replace code points in the String with the specified std::string object. More...
 
Stringreplace (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...
 
Stringreplace (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...
 
Stringreplace (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...
 
Stringreplace (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...
 
Stringreplace (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...
 
Stringreplace (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...
 
Stringreplace (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...
 
Stringreplace (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...
 
Stringreplace (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...
 
Stringreplace (size_type idx, size_type len, const char *cstr)
 Replace code points in the String with the specified c-string. More...
 
Stringreplace (iterator iter_beg, iterator iter_end, const char *cstr)
 Replace the code points in the range [beg, end) with the specified c-string. More...
 
Stringreplace (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...
 
Stringreplace (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
strString 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
strString object used to initialise the newly created string
str_idxStarting code-point of str to be used when initialising the new String
str_numMaximum 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_strThe 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_errorThrown 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_strstd::string object used to initialise the newly created string
str_idxStarting 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_numMaximum number of characters from std_str that are to be assigned to the new String
Returns
Nothing
Exceptions
std::length_errorThrown 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_strPointer 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_errorThrown 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_strPointer 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_lenLength of the provided utf8 string in code units (not code-points).
Returns
Nothing
Exceptions
std::length_errorThrown 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
numThe number of times code_point is to be put into new String object
code_pointThe Unicode code point to be used when initialising the String object
Returns
Nothing
Exceptions
std::length_errorThrown 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
begIterator describing the start of the data to be used when initialising the String object
endIterator 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_strPointer to a c-string.
Returns
Nothing
Exceptions
std::length_errorThrown 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
charschar array.
chars_lenNumber of chars from the array to be used.
Returns
Nothing
Exceptions
std::length_errorThrown 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
strString object containing data to be appended
str_idxIndex of the first code point to be appended
str_numMaximum number of code points to be appended
Returns
This String after the append operation
Exceptions
std::out_of_rangeThrown if str_idx is invalid for str.
std::length_errorThrown 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_strstd::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_idxIndex of the first character to be appended
str_numMaximum number of characters to be appended
Returns
This String after the append operation
Exceptions
std::out_of_rangeThrown if str_idx is invalid for std_str.
std::length_errorThrown 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_strBuffer 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_errorThrown 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_strBuffer 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
lenNumber of code units (not code points) in the buffer to be appended
Returns
This String after the append operation
Exceptions
std::length_errorThrown 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
numNumber of copies of the code point to be appended
code_pointutf32 Unicode code point that is to be appended
Returns
This String after the append operation
Exceptions
std::length_errorThrown 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
begIterator describing the start of the range to be appended
endIterator describing the (exclusive) end of the range to be appended.
Returns
This String after the append operation
Exceptions
std::length_errorThrown 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_strc-string that is to be appended.
Returns
This String after the append operation
Exceptions
std::length_errorThrown 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
charschar array holding the chars that are to be appended
chars_lenNumber of chars to be appended
Returns
This String after the append operation
Exceptions
std::length_errorThrown 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
strString object containing the string data to be assigned.
str_idxIndex of the first code point in str that is to be assigned
str_numMaximum number of code points from str that are be be assigned
Returns
This String after the assignment has happened
Exceptions
std::out_of_rangeThrown 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_strstd::string object containing the string value to be assigned.
str_idxIndex of the first character of std_str to be assigned
str_numMaximum number of characters from std_str to be assigned
Returns
This String after the assignment has happened
Exceptions
std::out_of_rangeThrown if str_idx is invalid for std_str
std::length_errorThrown 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_strBuffer containing valid null-terminated utf8 encoded data
Returns
This String after the assignment has happened
Exceptions
std::length_errorThrown 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_strBuffer containing valid utf8 encoded data
str_numNumber 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_errorThrown 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
numThe number of times to assign the code point
code_pointValid utf32 Unicode code point to be assigned to the string
Returns
This String after assignment.
Exceptions
std::length_errorThrown if num was 'npos'
String& CEGUI::String::assign ( const char *  cstr)
inline

Assign to this String the given C-string.

Parameters
c_strPointer to a valid C style string.
Returns
This String after the assignment has happened
Exceptions
std::length_errorThrown 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
charschar array.
chars_lenNumber of chars to be assigned.
Returns
This String after the assignment has happened
Exceptions
std::length_errorThrown 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
idxZero 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_rangeThrown if idx is >= length().
const_reference CEGUI::String::at ( size_type  idx) const
inline

Returns the code point at the given index.

Parameters
idxZero 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_rangeThrown 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
strThe 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
idxIndex of the first code point from this String to consider.
lenMaximum number of code points from this String to consider.
strThe String object that is to compared with this String.
str_idxIndex of the first code point from String str to consider.
str_lenMaximum 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_rangeThrown 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_strThe 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
idxIndex of the first code point from this String to consider.
lenMaximum number of code points from this String to consider.
std_strThe 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_idxIndex of the first character from std::string std_str to consider.
str_lenMaximum 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_rangeThrown 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_strThe 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
idxIndex of the first code point from this String to consider.
lenMaximum number of code points from this String to consider.
utf8_strThe 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_rangeThrown 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
idxIndex of the first code point from this String to consider.
lenMaximum number of code points from this String to consider.
utf8_strThe 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_cplenThe 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_rangeThrown if idx is invalid.
std::length_errorThrown 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_strThe 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
idxIndex of the first code point from this String to consider.
lenMaximum number of code points from this String to consider.
c_strThe 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_rangeThrown 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
idxIndex of the first code point from this String to consider.
lenMaximum number of code points from this String to consider.
charsThe array containing the chars that are to compared with this String.
chars_lenThe 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_rangeThrown if idx is invalid.
std::length_errorThrown 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
bufPointer to a buffer that is to receive the encoded data (this must be big enough to hold the encoded data)
lenMaximum number of code points from the String that should be encoded into the buffer
idxIndex 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_rangeThrown 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
idxThe index of the code point to be removed.
Returns
This String after the erase operation
Exceptions
std::out_of_rangeThrown 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
idxIndex of the first code point to be removed.
lenMaximum number of code points to be removed.
Returns
This String after the erase operation.
Exceptions
std::out_of_rangeThrown if idx is invalid for this String.
String& CEGUI::String::erase ( iterator  pos)
inline

Erase the code point described by the given iterator.

Parameters
posIterator 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
begIterator describing the postion of the beginning of the range to erase
endIterator 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_pointThe utf32 code point to search for
idxIndex 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
strString object describing the sub-string to search for
idxIndex 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_strstd::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
idxIndex 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_strBuffer 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
idxIndex 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_rangeThrown 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_strBuffer 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
idxIndex of the code point where the search is to start
str_lenLength 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_errorThrown 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_strc-string describing the sub-string to search for
idxIndex 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_rangeThrown 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
charschar array describing the sub-string to search for
idxIndex of the code point where the search is to start
chars_lenNumber 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_errorThrown 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
strString object describing the set of code points.
idxIndex 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_strstd::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
idxIndex 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_strBuffer 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
idxIndex 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_rangeThrown 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_strBuffer 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
idxIndex of the start point for the search
str_lenLength 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_errorThrown 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_pointThe utf32 code point to search for
idxIndex 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_rangeThrown 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_strc-string describing the set of chars.
idxIndex 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_rangeThrown 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
charschar array containing the set of chars.
idxIndex of the start point for the search
chars_lenNumber 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_errorThrown 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
strString object describing the set of code points.
idxIndex 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_strstd::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
idxIndex 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_strBuffer 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
idxIndex 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_rangeThrown 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_strBuffer 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
idxIndex of the start point for the search
str_lenLength 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_errorThrown 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_pointThe utf32 code point to search for
idxIndex 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_strc-string describing the set of chars.
idxIndex 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_rangeThrown 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
charschar array containing the set of chars.
idxIndex of the start point for the search
chars_lenNumber 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_errorThrown 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
strString object describing the set of code points.
idxIndex 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_strstd::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
idxIndex 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_strBuffer 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
idxIndex 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_rangeThrown 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_strBuffer 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
idxIndex of the start point for the search
str_lenLength 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_errorThrown 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_pointThe utf32 code point to search for
idxIndex 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_strc-string describing the set of chars.
idxIndex 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_rangeThrown 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
charschar array containing the set of chars.
idxIndex of the start point for the search
chars_lenNumber 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_errorThrown 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
strString object describing the set of code points.
idxIndex 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_strstd::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
idxIndex 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_strBuffer 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
idxIndex 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_rangeThrown 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_strBuffer 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
idxIndex of the start point for the search
str_lenLength 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_errorThrown 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_pointThe utf32 code point to search for
idxIndex 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_strc-string describing the set of chars.
idxIndex 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_rangeThrown 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
charschar array containing the set of chars.
idxIndex of the start point for the search
chars_lenNumber 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_errorThrown 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
idxIndex where the string is to be inserted.
strString object that is to be inserted.
Returns
This String after the insert.
Exceptions
std::out_of_rangeThrown if idx is invalid for this String.
std::length_errorThrown 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
idxIndex where the string is to be inserted.
strString object containing data to be inserted.
str_idxIndex of the first code point from str to be inserted.
str_numMaximum number of code points from str to be inserted.
Returns
This String after the insert.
Exceptions
std::out_of_rangeThrown if idx or str_idx are out of range.
std::length_errorThrown 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
idxIndex where the std::string is to be inserted.
std_strstd::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_rangeThrown if idx is invalid for this String.
std::length_errorThrown 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
idxIndex where the string is to be inserted.
std_strstd::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_idxIndex of the first character from std_str to be inserted.
str_numMaximum number of characters from str to be inserted.
Returns
This String after the insert.
Exceptions
std::out_of_rangeThrown if idx or str_idx are out of range.
std::length_errorThrown 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
idxIndex where the data is to be inserted.
utf8_strBuffer 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_rangeThrown if idx is invalid for this String.
std::length_errorThrown 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
idxIndex where the data is to be inserted.
utf8_strBuffer 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
lenLength of the data to be inserted in uf8 code units (not code points)
Returns
This String after the insert.
Exceptions
std::out_of_rangeThrown if idx is invalid for this String.
std::length_errorThrown 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
idxIndex where the code point(s) are to be inserted
numThe number of times to insert the code point
code_pointThe utf32 code point that is to be inserted
Returns
This String after the insertion.
Exceptions
std::out_of_rangeThrown if idx is invalid for this String.
std::length_errorThrown 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
posIterator describing the position where the code point(s) are to be inserted
numThe number of times to insert the code point
code_pointThe utf32 code point that is to be inserted
Returns
This String after the insertion.
Exceptions
std::length_errorThrown 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
posIterator describing the position where the code point is to be inserted
code_pointThe utf32 code point that is to be inserted
Returns
This String after the insertion.
Exceptions
std::length_errorThrown 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
posIterator describing the position where the data is to be inserted
begIterator describing the begining of the range to be inserted
endIterator describing the (exclusive) end of the range to be inserted.
Returns
Nothing.
Exceptions
std::length_errorThrown 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
idxIndex where the c-string is to be inserted.
c_strc-string that is to be inserted.
Returns
This String after the insert.
Exceptions
std::out_of_rangeThrown if idx is invalid for this String.
std::length_errorThrown 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
idxIndex where the data is to be inserted.
charschar array containing the chars that are to be inserted.
chars_lenLength of the char array to be inserted.
Returns
This String after the insert.
Exceptions
std::out_of_rangeThrown if idx is invalid for this String.
std::length_errorThrown 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
strString object that is to be appended
Returns
This String after the append operation
Exceptions
std::length_errorThrown 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_strstd::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_errorThrown 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_strbuffer 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_errorThrown 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_pointutf32 Unicode code point that is to be appended
Returns
This String after the append operation
Exceptions
std::length_errorThrown 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_strc-string that is to be appended.
Returns
This String after the append operation
Exceptions
std::length_errorThrown 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
strString 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_strstd::string object containing the string value to be assigned.
Returns
This String after the assignment has happened
Exceptions
std::length_errorThrown 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_strBuffer containing valid null-terminated utf8 encoded data
Returns
This String after the assignment has happened
Exceptions
std::length_errorThrown 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_pointValid 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_strPointer to a valid C style string.
Returns
This String after the assignment has happened
Exceptions
std::length_errorThrown 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
idxZero 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
idxZero 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_pointutf32 Unicode code point that is to be appended
Returns
Nothing
Exceptions
std::length_errorThrown 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
idxIndex of the first code point to be replaced
lenMaximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
strThe String object that is to replace the specified code points
Returns
This String after the replace operation
Exceptions
std::out_of_rangeThrown if idx is invalid for this String
std::length_errorThrown 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
begIterator describing the start of the range to be replaced
endIterator describing the (exclusive) end of the range to be replaced.
strThe String object that is to replace the specified range of code points
Returns
This String after the replace operation
Exceptions
std::length_errorThrown 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
idxIndex of the first code point to be replaced
lenMaximum number of code points to be replaced. If this is 0, the operation is an insert at position idx.
strString object containing the data that will replace the specified range of code points
str_idxIndex of the first code point of str that is to replace the specified code point range
str_numMaximum 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_rangeThrown if either idx, or str_idx are invalid
std::length_errorThrown 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
idxIndex of the first code point to be replaced
lenMaximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
std_strThe 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_rangeThrown if idx is invalid for this String
std::length_errorThrown 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
begIterator describing the start of the range to be replaced
endIterator describing the (exclusive) end of the range to be replaced.
std_strThe 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_errorThrown 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
idxIndex of the first code point to be replaced
lenMaximum number of code points to be replaced. If this is 0, the operation is an insert at position idx.
std_strstd::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_idxIndex of the first code point of std_str that is to replace the specified code point range
str_numMaximum 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_rangeThrown if either idx, or str_idx are invalid
std::length_errorThrown 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
idxIndex of the first code point to be replaced
lenMaximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
utf8_strBuffer 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_rangeThrown if idx is invalid for this String
std::length_errorThrown 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
begIterator describing the start of the range to be replaced
endIterator describing the (exclusive) end of the range to be replaced.
utf8_strBuffer 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_errorThrown 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
idxIndex of the first code point to be replaced
lenMaximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
utf8_strBuffer 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_lenLength of the utf8 encoded data in utf8 code units (not code points).
Returns
This String after the replace operation
Exceptions
std::out_of_rangeThrown if idx is invalid for this String
std::length_errorThrown 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
begIterator describing the start of the range to be replaced
endIterator describing the (exclusive) end of the range to be replaced.
utf8_strBuffer 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_lenLength of the utf8 encoded data in utf8 code units (not code points).
Returns
This String after the replace operation
Exceptions
std::length_errorThrown 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
idxIndex of the first code point to be replaced
lenMaximum number of code points to replace. If this is 0 the operation is an insert
numNumber of occurrences of code_point that are to replace the specified range of code points
code_pointCode 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_rangeThrown if idx is invalid for this String
std::length_errorThrown 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
begIterator describing the start of the range to be replaced
endIterator describing the (exclusive) end of the range to be replaced.
numNumber of occurrences of code_point that are to replace the specified range of code points
code_pointCode point that is to be used when replacing the specified range of code points
Returns
This String after the replace operation
Exceptions
std::length_errorThrown 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
begIterator describing the start of the range to be replaced
endIterator describing the (exclusive) end of the range to be replaced.
newBegIterator describing the beginning of the range to insert.
newEndIterator describing the (exclusive) end of the range to insert.
Returns
This String after the insert operation.
Exceptions
std::length_errorThrown 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
idxIndex of the first code point to be replaced
lenMaximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
c_strc-string that is to replace the specified code points
Returns
This String after the replace operation
Exceptions
std::out_of_rangeThrown if idx is invalid for this String
std::length_errorThrown 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
begIterator describing the start of the range to be replaced
endIterator describing the (exclusive) end of the range to be replaced.
c_strc-string that is to replace the specified range of code points
Returns
This String after the replace operation
Exceptions
std::length_errorThrown 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
idxIndex of the first code point to be replaced
lenMaximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
charschar array containing the cars that are to replace the specified code points
chars_lenNumber of chars in the char array.
Returns
This String after the replace operation
Exceptions
std::out_of_rangeThrown if idx is invalid for this String
std::length_errorThrown 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
begIterator describing the start of the range to be replaced
endIterator describing the (exclusive) end of the range to be replaced.
charschar array containing the chars that are to replace the specified range of code points
chars_lenNumber of chars in the char array.
Returns
This String after the replace operation
Exceptions
std::length_errorThrown 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
numThe 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_errorThrown 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
numThe length, in code points, that the String is to be made.
Returns
Nothing.
Exceptions
std::length_errorThrown 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
numThe length, in code points, that the String is to be made.
code_pointThe utf32 code point that should be used when majing the String larger
Returns
Nothing.
Exceptions
std::length_errorThrown 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_pointThe utf32 code point to search for
idxIndex 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
strString object describing the sub-string to search for
idxIndex 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_strstd::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
idxIndex 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_strBuffer 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
idxIndex 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_rangeThrown 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_strBuffer 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
idxIndex of the code point where the search is to start
str_lenLength 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_errorThrown 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_strc-string describing the sub-string to search for
idxIndex 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_rangeThrown 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
charschar array describing the sub-string to search for
idxIndex of the code point where the search is to start
chars_lenNumber 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_errorThrown 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
idxIndex of the first code point to use for the sub-string.
lenMaximum number of code points to use for the sub-string
Returns
A String object containing the specified sub-string.
Exceptions
std::out_of_rangeThrown 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
strString 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
numMaximum number of code points to consider when calculating utf8 encoded size.
idxIndex 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_rangeThrown if idx was invalid for this String.