CEGUI::String Class Reference

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

List of all members.

Classes

class  const_iterator
 Constant forward iterator class for String objects. More...
struct  FastLessCompare
 Functor that can be used as comparator in a std::map with String keys. It's faster than using the default, but the map will no longer be sorted alphabetically. More...
class  iterator
 Forward iterator class for String objects. 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 ptrdiff_t difference_type
 Signed type used for differences.
typedef utf32 & reference
 Type used for utf32 code point references.
typedef const utf32 & const_reference
 Type used for constant utf32 code point references.
typedef utf32 * pointer
 Type used for utf32 code point pointers.
typedef const utf32 * const_pointer
 Type used for constant utf32 code point pointers.
typedef std::reverse_iterator
< const_iterator
const_reverse_iterator
 Constant reverse iterator class for String objects.
typedef std::reverse_iterator
< iterator
reverse_iterator
 Reverse iterator class for String objects.

Public Member Functions

 String (void)
 Constructs an empty string.
 ~String (void)
 Destructor for String objects.
 String (const String &str)
 Copy constructor - Creates a new string with the same value as str.
 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.
 String (const std::string &std_str)
 Constructs a new string and initialises it using the std::string std_str.
 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.
 String (const utf8 *utf8_str)
 Constructs a new String object and initialise it using the provided utf8 encoded string buffer.
 String (const utf8 *utf8_str, size_type chars_len)
 Constructs a new String object and initialise it using the provided utf8 encoded string buffer.
 String (size_type num, utf32 code_point)
 Constructs a new String that is initialised with the specified code point.
 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).
 String (const char *cstr)
 Constructs a new String object and initialise it using the provided c-string.
 String (const char *chars, size_type chars_len)
 Constructs a new String object and initialise it using characters from the provided char array.
size_type size (void) const
 Returns the size of the String in code points.
size_type length (void) const
 Returns the size of the String in code points.
bool empty (void) const
 Returns true if the String is empty.
size_type capacity (void) const
 Return the number of code points that the String could hold before a re-allocation would be required.
void reserve (size_type num=0)
 Specifies the amount of reserve capacity to allocate.
int compare (const String &str) const
 Compares this String with the String 'str'.
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'.
int compare (const std::string &std_str) const
 Compares this String with the std::string 'std_str'.
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'.
int compare (const utf8 *utf8_str) const
 Compares this String with the null-terminated utf8 encoded 'utf8_str'.
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'.
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'.
int compare (const char *cstr) const
 Compares this String with the given c-string.
int compare (size_type idx, size_type len, const char *cstr) const
 Compares code points from this String with the given c-string.
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.
reference operator[] (size_type idx)
 Returns the code point at the given index.
value_type operator[] (size_type idx) const
 Returns the code point at the given index.
reference at (size_type idx)
 Returns the code point at the given index.
const_reference at (size_type idx) const
 Returns the code point at the given index.
const char * c_str (void) const
 Returns contents of the String as a null terminated string of utf8 encoded data.
const utf8 * data (void) const
 Returns contents of the String as utf8 encoded data.
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.
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.
Stringoperator= (const String &str)
 Assign the value of String str to this String.
Stringassign (const String &str, size_type str_idx=0, size_type str_num=npos)
 Assign a sub-string of String str to this String.
Stringoperator= (const std::string &std_str)
 Assign the value of std::string std_str to this String.
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.
Stringoperator= (const utf8 *utf8_str)
 Assign to this String the string value represented by the given null-terminated utf8 encoded data.
Stringassign (const utf8 *utf8_str)
 Assign to this String the string value represented by the given null-terminated utf8 encoded data.
Stringassign (const utf8 *utf8_str, size_type str_num)
 Assign to this String the string value represented by the given utf8 encoded data.
Stringoperator= (utf32 code_point)
 Assigns the specified utf32 code point to this String. Result is always a String 1 code point in length.
Stringassign (size_type num, utf32 code_point)
 Assigns the specified code point repeatedly to the String.
Stringoperator= (const char *cstr)
 Assign to this String the given C-string.
Stringassign (const char *cstr)
 Assign to this String the given C-string.
Stringassign (const char *chars, size_type chars_len)
 Assign to this String a number of chars from a char array.
void swap (String &str)
 Swaps the value of this String with the given String str.
Stringoperator+= (const String &str)
 Appends the String str.
Stringappend (const String &str, size_type str_idx=0, size_type str_num=npos)
 Appends a sub-string of the String str.
Stringoperator+= (const std::string &std_str)
 Appends the std::string std_str.
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.
Stringoperator+= (const utf8 *utf8_str)
 Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.
Stringappend (const utf8 *utf8_str)
 Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.
Stringappend (const utf8 *utf8_str, size_type len)
 Appends to the String the utf8 encoded data in the buffer utf8_str.
Stringoperator+= (utf32 code_point)
 Appends a single code point to the string.
Stringappend (size_type num, utf32 code_point)
 Appends a single code point multiple times to the string.
void push_back (utf32 code_point)
 Appends a single code point to the string.
Stringappend (const_iterator iter_beg, const_iterator iter_end)
 Appends the code points in the reange [beg, end).
Stringoperator+= (const char *cstr)
 Appends to the String the given c-string.
Stringappend (const char *cstr)
 Appends to the String the given c-string.
Stringappend (const char *chars, size_type chars_len)
 Appends to the String chars from the given char array.
Stringinsert (size_type idx, const String &str)
 Inserts the given String object at the specified position.
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.
Stringinsert (size_type idx, const std::string &std_str)
 Inserts the given std::string object at the specified position.
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.
Stringinsert (size_type idx, const utf8 *utf8_str)
 Inserts the given null-terminated utf8 encoded data at the specified position.
Stringinsert (size_type idx, const utf8 *utf8_str, size_type len)
 Inserts the given utf8 encoded data at the specified position.
Stringinsert (size_type idx, size_type num, utf32 code_point)
 Inserts a code point multiple times into the String.
void insert (iterator pos, size_type num, utf32 code_point)
 Inserts a code point multiple times into the String.
iterator insert (iterator pos, utf32 code_point)
 Inserts a single code point into the String.
void insert (iterator iter_pos, const_iterator iter_beg, const_iterator iter_end)
 Inserts code points specified by the range [beg, end).
Stringinsert (size_type idx, const char *cstr)
 Inserts the given c-string at the specified position.
Stringinsert (size_type idx, const char *chars, size_type chars_len)
 Inserts chars from the given char array at the specified position.
void clear (void)
 Removes all data from the String.
Stringerase (void)
 Removes all data from the String.
Stringerase (size_type idx)
 Erase a single code point from the string.
Stringerase (size_type idx, size_type len=npos)
 Erase a range of code points.
Stringerase (iterator pos)
 Erase the code point described by the given iterator.
Stringerase (iterator iter_beg, iterator iter_end)
 Erase a range of code points described by the iterators [beg, end).
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.
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.
Stringreplace (size_type idx, size_type len, const String &str)
 Replace code points in the String with the specified String object.
Stringreplace (iterator iter_beg, iterator iter_end, const String &str)
 Replace the code points in the range [beg, end) with the specified String object.
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.
Stringreplace (size_type idx, size_type len, const std::string &std_str)
 Replace code points in the String with the specified std::string object.
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.
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.
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.
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.
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.
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.
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.
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.
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).
Stringreplace (size_type idx, size_type len, const char *cstr)
 Replace code points in the String with the specified c-string.
Stringreplace (iterator iter_beg, iterator iter_end, const char *cstr)
 Replace the code points in the range [beg, end) with the specified c-string.
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.
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.
size_type find (utf32 code_point, size_type idx=0) const
 Search forwards for a given code point.
size_type rfind (utf32 code_point, size_type idx=npos) const
 Search backwards for a given code point.
size_type find (const String &str, size_type idx=0) const
 Search forwards for a sub-string.
size_type rfind (const String &str, size_type idx=npos) const
 Search backwards for a sub-string.
size_type find (const std::string &std_str, size_type idx=0) const
 Search forwards for a sub-string.
size_type rfind (const std::string &std_str, size_type idx=npos) const
 Search backwards for a sub-string.
size_type find (const utf8 *utf8_str, size_type idx=0) const
 Search forwards for a sub-string.
size_type rfind (const utf8 *utf8_str, size_type idx=npos) const
 Search backwards for a sub-string.
size_type find (const utf8 *utf8_str, size_type idx, size_type str_len) const
 Search forwards for a sub-string.
size_type rfind (const utf8 *utf8_str, size_type idx, size_type str_len) const
 Search backwards for a sub-string.
size_type find (const char *cstr, size_type idx=0) const
 Search forwards for a sub-string.
size_type rfind (const char *cstr, size_type idx=npos) const
 Search backwards for a sub-string.
size_type find (const char *chars, size_type idx, size_type chars_len) const
 Search forwards for a sub-string.
size_type rfind (const char *chars, size_type idx, size_type chars_len) const
 Search backwards for a sub-string.
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.
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.
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.
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.
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.
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.
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.
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.
size_type find_first_of (utf32 code_point, size_type idx=0) const
 Search forwards for a given code point.
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.
size_type find_first_of (const char *cstr, size_type idx=0) const
 Find the first occurrence of one of a set of chars.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
size_type find_last_of (utf32 code_point, size_type idx=npos) const
 Search for last occurrence of a given code point.
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.
size_type find_last_of (const char *cstr, size_type idx=npos) const
 Find the last occurrence of one of a set of chars.
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.
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.
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.
String substr (size_type idx=0, size_type len=npos) const
 Returns a substring of this String.
iterator begin (void)
 Return a forwards iterator that describes the beginning of the String.
const_iterator begin (void) const
 Return a constant forwards iterator that describes the beginning of the String.
iterator end (void)
 Return a forwards iterator that describes the end of the String.
const_iterator end (void) const
 Return a constant forwards iterator that describes the end of the String.
reverse_iterator rbegin (void)
 Return a reverse iterator that describes the beginning of the String.
const_reverse_iterator rbegin (void) const
 Return a constant reverse iterator that describes the beginning of the String.
reverse_iterator rend (void)
 Return a reverse iterator that describes the end of the String.
const_reverse_iterator rend (void) const
 Return a constant reverse iterator that describes the end of the String.

Static Public Member Functions

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

Static Public Attributes

static const size_type npos = (String::size_type)(-1)
 Value used to represent 'not found' conditions and 'all code points' etc.


Detailed Description

String class used within the GUI system.

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


Constructor & Destructor Documentation

CEGUI::String::String ( const String str  )  [inline]

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

Parameters:
str String object used to initialise the newly created string
Returns:
Nothing

CEGUI::String::String ( const String str,
size_type  str_idx,
size_type  str_num = npos 
) [inline]

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

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

CEGUI::String::String ( const std::string &  std_str  )  [inline]

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

Parameters:
std_str The std::string object that is to be used to initialise the new String object.
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Returns:
Nothing
Exceptions:
std::length_error Thrown if resulting String object would be too big.

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

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

Parameters:
std_str std::string object used to initialise the newly created string
str_idx Starting character of std_str to be used when initialising the new String
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Parameters:
str_num Maximum number of characters from std_str that are to be assigned to the new String
Returns:
Nothing
Exceptions:
std::length_error Thrown if resulting String object would be too big.

CEGUI::String::String ( const utf8 *  utf8_str  )  [inline]

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

Parameters:
utf8_str Pointer to a buffer containing a null-terminated Unicode string encoded as utf8 data.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Returns:
Nothing
Exceptions:
std::length_error Thrown if resulting String object would be too big.

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

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

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

Parameters:
utf8_str Pointer to a buffer containing Unicode string data encoded as utf8.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
chars_len Length of the provided utf8 string in code units (not code-points).
Returns:
Nothing
Exceptions:
std::length_error Thrown if resulting String object would be too big.

CEGUI::String::String ( size_type  num,
utf32  code_point 
) [inline]

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

Parameters:
num The number of times code_point is to be put into new String object
code_point The Unicode code point to be used when initialising the String object
Returns:
Nothing
Exceptions:
std::length_error Thrown if resulting String object would be too big.

CEGUI::String::String ( const_iterator  iter_beg,
const_iterator  iter_end 
) [inline]

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

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

CEGUI::String::String ( const char *  cstr  )  [inline]

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

Parameters:
c_str Pointer to a c-string.
Returns:
Nothing
Exceptions:
std::length_error Thrown if resulting String object would be too big.

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

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

Parameters:
chars char array.
chars_len Number of chars from the array to be used.
Returns:
Nothing
Exceptions:
std::length_error Thrown if resulting String object would be too big.


Member Function Documentation

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

Appends to the String chars from the given char array.

Parameters:
chars char array holding the chars that are to be appended
chars_len Number of chars to be appended
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too large, or if chars_len was 'npos'

String& CEGUI::String::append ( const char *  cstr  )  [inline]

Appends to the String the given c-string.

Parameters:
c_str c-string that is to be appended.
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::append ( const_iterator  iter_beg,
const_iterator  iter_end 
) [inline]

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

Parameters:
beg Iterator describing the start of the range to be appended
end Iterator describing the (exclusive) end of the range to be appended.
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if the resulting string would be too large.

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

Appends a single code point multiple times to the string.

Parameters:
num Number of copies of the code point to be appended
code_point utf32 Unicode code point that is to be appended
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too long, or if num was 'npos'.

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

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

Parameters:
utf8_str Buffer holding the utf8 encoded data that is to be appended
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
len Number of code units (not code points) in the buffer to be appended
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too large, or if len was 'npos'

String& CEGUI::String::append ( const utf8 *  utf8_str  )  [inline]

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

Parameters:
utf8_str Buffer holding the null-terminated utf8 encoded data that is to be appended
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too large.

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

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

Parameters:
std_str std::string object containing data to be appended
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Parameters:
str_idx Index of the first character to be appended
str_num Maximum number of characters to be appended
Returns:
This String after the append operation
Exceptions:
std::out_of_range Thrown if str_idx is invalid for std_str.
std::length_error Thrown if resulting String would be too large.

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

Appends a sub-string of the String str.

Parameters:
str String object containing data to be appended
str_idx Index of the first code point to be appended
str_num Maximum number of code points to be appended
Returns:
This String after the append operation
Exceptions:
std::out_of_range Thrown if str_idx is invalid for str.
std::length_error Thrown if resulting String would be too large.

References d_cplength, and ptr().

Referenced by CEGUI::Window::appendText(), CEGUI::TabControl::makeButtonName(), CEGUI::MultiLineEditbox::MultiLineEditbox(), CEGUI::MultiLineEditbox::onMouseTripleClicked(), CEGUI::MultiLineEditbox::onTextChanged(), CEGUI::operator+(), and CEGUI::XercesParser::transcodeXmlCharToString().

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

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

Parameters:
chars char array.
chars_len Number of chars to be assigned.
Returns:
This String after the assignment has happened
Exceptions:
std::length_error Thrown if the resulting String would have been too large.

String& CEGUI::String::assign ( const char *  cstr  )  [inline]

Assign to this String the given C-string.

Parameters:
c_str Pointer to a valid C style string.
Returns:
This String after the assignment has happened
Exceptions:
std::length_error Thrown if the resulting String would have been too large.

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

Assigns the specified code point repeatedly to the String.

Parameters:
num The number of times to assign the code point
code_point Valid utf32 Unicode code point to be assigned to the string
Returns:
This String after assignment.
Exceptions:
std::length_error Thrown if num was 'npos'

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

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

Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
utf8_str Buffer containing valid utf8 encoded data
str_num Number of code units (not code points) in the buffer pointed to by utf8_str
Returns:
This String after the assignment has happened
Exceptions:
std::length_error Thrown if the resulting String would have been too large, or if str_num is 'npos'.

String& CEGUI::String::assign ( const utf8 *  utf8_str  )  [inline]

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

Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
utf8_str Buffer containing valid null-terminated utf8 encoded data
Returns:
This String after the assignment has happened
Exceptions:
std::length_error Thrown if the resulting String would have been too large.

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

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

Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Parameters:
std_str std::string object containing the string value to be assigned.
str_idx Index of the first character of std_str to be assigned
str_num Maximum number of characters from std_str to be assigned
Returns:
This String after the assignment has happened
Exceptions:
std::out_of_range Thrown if str_idx is invalid for std_str
std::length_error Thrown if the resulting String would have been too large.

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

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

Parameters:
str String object containing the string data to be assigned.
str_idx Index of the first code point in str that is to be assigned
str_num Maximum number of code points from str that are be be assigned
Returns:
This String after the assignment has happened
Exceptions:
std::out_of_range Thrown if str_idx is invalid for str

References d_cplength, and ptr().

const_reference CEGUI::String::at ( size_type  idx  )  const [inline]

Returns the code point at the given index.

Parameters:
idx Zero based index of the code point to be returned.
Returns:
The utf32 code point at the given index within the String.
Exceptions:
std::out_of_range Thrown if idx is >= length().

reference CEGUI::String::at ( size_type  idx  )  [inline]

Returns the code point at the given index.

Parameters:
idx Zero based index of the code point to be returned.
Returns:
The utf32 code point at the given index within the String.
Exceptions:
std::out_of_range Thrown if idx is >= length().

const_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.

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.

Referenced by CEGUI::Font::getFormattedLineCount().

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.

Referenced by CEGUI::ListHeader::createInitialisedSegment(), CEGUI::DynamicModule::DynamicModule(), CEGUI::Config_xmlHandler::elementStart(), CEGUI::Exception::Exception(), CEGUI::DynamicModule::getSymbolAddress(), CEGUI::Spinner::getValueFromText(), CEGUI::Editbox::isStringValid(), CEGUI::LuaFunctor::pushNamedFunction(), CEGUI::ThumbProperties::HorzRange::set(), CEGUI::ThumbProperties::VertRange::set(), CEGUI::DefaultLogger::setLogFilename(), and CEGUI::Editbox::setValidationString().

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]

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

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

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
idx Index of the first code point from this String to consider.
len Maximum number of code points from this String to consider.
chars The array containing the chars that are to compared with this String.
chars_len The number of chars in the array.
Returns:
  • 0 if the specified sub-strings are equal
  • <0 if specified sub-strings are lexicographically smaller than chars
  • >0 if specified sub-strings are lexicographically greater than chars
Exceptions:
std::out_of_range Thrown if idx is invalid.
std::length_error Thrown if chars_len is set to npos.

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

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

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
idx Index of the first code point from this String to consider.
len Maximum number of code points from this String to consider.
c_str The c-string that is to compared with this String.
Returns:
  • 0 if the specified sub-strings are equal
  • <0 if specified sub-strings are lexicographically smaller than c_str
  • >0 if specified sub-strings are lexicographically greater than c_str
Exceptions:
std::out_of_range Thrown if idx is invalid.

int CEGUI::String::compare ( const char *  cstr  )  const [inline]

Compares this String with the given c-string.

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
c_str The c-string that is to compared with this String.
Returns:
  • 0 if the strings are equal
  • <0 if this string is lexicographically smaller than c_str
  • >0 if this string is lexicographically greater than c_str

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

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

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
idx Index of the first code point from this String to consider.
len Maximum number of code points from this String to consider.
utf8_str The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
str_cplen The number of encoded code points in the buffer utf8_str (this is not the same as the number of code units).
Returns:
  • 0 if the specified sub-strings are equal
  • <0 if specified sub-strings are lexicographically smaller than utf8_str
  • >0 if specified sub-strings are lexicographically greater than utf8_str
Exceptions:
std::out_of_range Thrown if idx is invalid.
std::length_error Thrown if str_cplen is set to npos.

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

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

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
idx Index of the first code point from this String to consider.
len Maximum number of code points from this String to consider.
utf8_str The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Returns:
  • 0 if the specified sub-strings are equal
  • <0 if specified sub-strings are lexicographically smaller than utf8_str
  • >0 if specified sub-strings are lexicographically greater than utf8_str
Exceptions:
std::out_of_range Thrown if idx is invalid.

int CEGUI::String::compare ( const utf8 *  utf8_str  )  const [inline]

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

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
utf8_str The buffer containing valid Unicode data encoded as utf8 that is to compared with this String.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Returns:
  • 0 if the strings are equal
  • <0 if this string is lexicographically smaller than utf8_str
  • >0 if this string is lexicographically greater than utf8_str

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

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

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
idx Index of the first code point from this String to consider.
len Maximum number of code points from this String to consider.
std_str The std::string object that is to compared with this String.
Note:
Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.
Parameters:
str_idx Index of the first character from std::string std_str to consider.
str_len Maximum number of characters from std::string std_str to consider
Returns:
  • 0 if the specified sub-strings are equal
  • <0 if specified sub-strings are lexicographically smaller than std_str
  • >0 if specified sub-strings are lexicographically greater than std_str
Exceptions:
std::out_of_range Thrown if either idx or str_idx are invalid.

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

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

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
std_str The std::string object that is to compared with this String.
Note:
Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.
Returns:
  • 0 if the string objects are equal
  • <0 if this string is lexicographically smaller than std_str
  • >0 if this string is lexicographically greater than std_str

int CEGUI::String::compare ( size_type  idx,
size_type  len,
const String str,
size_type  str_idx = 0,
size_type  str_len = npos 
) const [inline]

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

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
idx Index of the first code point from this String to consider.
len Maximum number of code points from this String to consider.
str The String object that is to compared with this String.
str_idx Index of the first code point from String str to consider.
str_len Maximum number of code points from String str to consider
Returns:
  • 0 if the specified sub-strings are equal
  • <0 if specified sub-strings are lexicographically smaller than str
  • >0 if specified sub-strings are lexicographically greater than str
Exceptions:
std::out_of_range Thrown if either idx or str_idx are invalid.

References d_cplength, and ptr().

int CEGUI::String::compare ( const String str  )  const [inline]

Compares this String with the String 'str'.

Note:
This does currently not properly consider Unicode and / or the system locale.
Parameters:
str The String object that is to compared with this String.
Returns:
  • 0 if the String objects are equal
  • <0 if this String is lexicographically smaller than str
  • >0 if this String is lexicographically greater than str

Referenced by CEGUI::operator!=(), CEGUI::operator<(), CEGUI::operator<=(), CEGUI::operator==(), CEGUI::operator>(), CEGUI::operator>=(), and CEGUI::Window::rename().

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

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

Parameters:
buf Pointer to a buffer that is to receive the encoded data (this must be big enough to hold the encoded data)
len Maximum number of code points from the String that should be encoded into the buffer
idx Index of the first code point to be encoded into the buffer
Returns:
The number of utf8 encoded code units transferred to the buffer.
Note:
A code unit does not equal a code point. A utf32 code point, when encoded as utf8, can occupy between 1 and 4 code units.
Exceptions:
std::out_of_range Thrown if idx was invalid for this String.

const utf8* CEGUI::String::data ( void   )  const [inline]

Returns contents of the String as utf8 encoded data.

Returns:
Pointer to a buffer containing the contents of the String encoded utf8 data.
Note:
The buffer returned from this function is owned by the String object.

Any function that modifies the String data will invalidate the buffer returned by this call.

bool CEGUI::String::empty ( void   )  const [inline]

Returns true if the String is empty.

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

Referenced by CEGUI::WidgetComponent::create(), CEGUI::FontManager::createFont(), CEGUI::FalagardListHeader::createNewSegment(), CEGUI::FalagardTabControl::createTabButton(), CEGUI::WindowManager::createWindow(), CEGUI::DynamicModule::DynamicModule(), CEGUI::PropertyLinkDefinition::get(), CEGUI::LuaScriptModule::getActivePCallErrorHandlerReference(), CEGUI::LuaScriptModule::getActivePCallErrorHandlerString(), CEGUI::PropertyLinkDefinition::getTargetWindow(), CEGUI::Window::getTooltipText(), CEGUI::Window::getType(), CEGUI::PropertyDim::getValue_impl(), CEGUI::FontDim::getValue_impl(), CEGUI::WidgetDim::getValue_impl(), CEGUI::Spinner::getValueFromText(), CEGUI::SectionSpecification::initColourRectForOverride(), CEGUI::FalagardComponentBase::initColoursRect(), CEGUI::ImagerySection::initMasterColourRect(), CEGUI::ComponentArea::isAreaFetchedFromProperty(), CEGUI::TextComponent::isFontFetchedFromProperty(), CEGUI::ImageryComponent::isImageFetchedFromProperty(), CEGUI::Window::isPropertyAtDefault(), CEGUI::TextComponent::isTextFetchedFromProperty(), CEGUI::PixmapFont::load(), CEGUI::Imageset::load(), CEGUI::FreeTypeFont::load(), CEGUI::WindowManager::loadWindowLayout(), CEGUI::Spinner::onValueChanged(), CEGUI::WidgetLookManager::parseLookNFeelSpecification(), CEGUI::Window::performChildWindowLayout(), CEGUI::Window::rename(), CEGUI::SectionSpecification::render(), CEGUI::TextComponent::render_impl(), CEGUI::ImageryComponent::render_impl(), CEGUI::WindowProperties::MouseCursorImage::set(), CEGUI::WindowProperties::Font::set(), CEGUI::PropertyLinkDefinition::set(), CEGUI::DragContainerProperties::DragCursorImage::set(), CEGUI::System::setDefaultFont(), CEGUI::System::setDefaultTooltip(), CEGUI::Window::setFont(), CEGUI::Window::setLookNFeel(), CEGUI::Window::setTooltipType(), CEGUI::Window::setWindowRenderer(), CEGUI::LuaFunctor::SubscribeEvent(), CEGUI::System::System(), CEGUI::FreeTypeFont::updateFont(), CEGUI::FalagardComponentBase::writeColoursXML(), CEGUI::FalagardComponentBase::writeHorzFormatXML(), CEGUI::FalagardComponentBase::writeVertFormatXML(), CEGUI::PropertyLinkDefinition::writeXMLAttributes(), CEGUI::PropertyDefinitionBase::writeXMLAttributes(), CEGUI::PropertyDim::writeXMLElementAttributes_impl(), CEGUI::FontDim::writeXMLElementAttributes_impl(), CEGUI::WidgetDim::writeXMLElementAttributes_impl(), CEGUI::Font::writeXMLToStream(), CEGUI::WidgetComponent::writeXMLToStream(), CEGUI::TextComponent::writeXMLToStream(), CEGUI::SectionSpecification::writeXMLToStream(), CEGUI::ImagerySection::writeXMLToStream(), and CEGUI::System::~System().

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.

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.

Referenced by CEGUI::Font::getFormattedLineCount().

String& CEGUI::String::erase ( iterator  iter_beg,
iterator  iter_end 
) [inline]

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

Parameters:
beg Iterator describing the postion of the beginning of the range to erase
end Iterator describing the postion of the (exclusive) end of the range to erase
Returns:
This String after the erase operation.

String& CEGUI::String::erase ( iterator  pos  )  [inline]

Erase the code point described by the given iterator.

Parameters:
pos Iterator describing the code point to be erased
Returns:
This String after the erase operation.

String& CEGUI::String::erase ( size_type  idx,
size_type  len = npos 
) [inline]

Erase a range of code points.

Parameters:
idx Index of the first code point to be removed.
len Maximum number of code points to be removed.
Returns:
This String after the erase operation.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

String& CEGUI::String::erase ( size_type  idx  )  [inline]

Erase a single code point from the string.

Parameters:
idx The index of the code point to be removed.
Returns:
This String after the erase operation
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

String& CEGUI::String::erase ( void   )  [inline]

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

Search forwards for a sub-string.

Parameters:
chars char array describing the sub-string to search for
idx Index of the code point where the search is to start
chars_len Number of chars in the char array.
Returns:
  • Index of the first occurrence of sub-string chars travelling forwards from idx.
  • npos if the sub-string could not be found
Exceptions:
std::length_error Thrown if chars_len is 'npos'

size_type CEGUI::String::find ( const char *  cstr,
size_type  idx = 0 
) const [inline]

Search forwards for a sub-string.

Parameters:
c_str c-string describing the sub-string to search for
idx Index of the code point where the search is to start
Returns:
  • Index of the first occurrence of sub-string c_str travelling forwards from idx.
  • npos if the sub-string could not be found
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

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

Search forwards for a sub-string.

Parameters:
utf8_str Buffer containing utf8 encoded data describing the sub-string to search for
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the code point where the search is to start
str_len Length of the utf8 encoded sub-string in utf8 code units (not code points)
Returns:
  • Index of the first occurrence of sub-string utf8_str travelling forwards from idx.
  • npos if the sub-string could not be found
Exceptions:
std::length_error Thrown if str_len is 'npos'

size_type CEGUI::String::find ( const utf8 *  utf8_str,
size_type  idx = 0 
) const [inline]

Search forwards for a sub-string.

Parameters:
utf8_str Buffer containing null-terminated utf8 encoded data describing the sub-string to search for
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the code point where the search is to start
Returns:
  • Index of the first occurrence of sub-string utf8_str travelling forwards from idx.
  • npos if the sub-string could not be found
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

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

Search forwards for a sub-string.

Parameters:
std_str std::string object describing the sub-string to search for
Note:
Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.
Parameters:
idx Index of the code point where the search is to start
Returns:
  • Index of the first occurrence of sub-string std_str travelling forwards from idx.
  • npos if the sub-string could not be found

size_type CEGUI::String::find ( const String str,
size_type  idx = 0 
) const [inline]

Search forwards for a sub-string.

Parameters:
str String object describing the sub-string to search for
idx Index of the code point where the search is to start
Returns:
  • Index of the first occurrence of sub-string str travelling forwards from idx.
  • npos if the sub-string could not be found

References d_cplength.

size_type CEGUI::String::find ( utf32  code_point,
size_type  idx = 0 
) const [inline]

Search forwards for a given code point.

Parameters:
code_point The utf32 code point to search for
idx Index of the code point where the search is to start.
Returns:
  • Index of the first occurrence of code_point travelling forwards from idx.
  • npos if the code point could not be found

Referenced by CEGUI::TabControl::addChild_impl(), CEGUI::ScrollablePane::addChild_impl(), CEGUI::GroupBox::addChild_impl(), find_first_not_of(), find_first_of(), find_last_not_of(), find_last_of(), CEGUI::TextUtils::getNextWordStartIdx(), CEGUI::TextUtils::getWordStartIdx(), CEGUI::TabControl::removeChild_impl(), CEGUI::ScrollablePane::removeChild_impl(), CEGUI::GroupBox::removeChild_impl(), CEGUI::MultiColumnListProperties::ColumnHeader::set(), CEGUI::Window::setFalagardType(), and CEGUI::Property::writeXMLToStream().

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

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

Parameters:
chars char array containing the set of chars.
idx Index of the start point for the search
chars_len Number of chars in the car array.
Returns:
  • Index of the first code point that does not match any one of the chars in chars starting from from idx.
  • npos if all code points matched any of the chars in chars.
Exceptions:
std::length_error Thrown if chars_len was 'npos'.

size_type CEGUI::String::find_first_not_of ( const char *  cstr,
size_type  idx = 0 
) const [inline]

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

Parameters:
c_str c-string describing the set of chars.
idx Index of the start point for the search
Returns:
  • Index of the first code point that does not match any one of the chars in c_str starting from from idx.
  • npos if all code points matched any of the chars in c_str.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_first_not_of ( utf32  code_point,
size_type  idx = 0 
) const [inline]

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

Parameters:
code_point The utf32 code point to search for
idx Index of the code point where the search is to start.
Returns:
  • Index of the first code point that does not match code_point starting from from idx.
  • npos if all code points matched code_point
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

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

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

Parameters:
utf8_str Buffer containing utf8 encoded data describing the set of code points.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the start point for the search
str_len Length of the utf8 encoded data in utf8 code units (not code points).
Returns:
  • Index of the first code point that does not match any one of the code points in utf8_str starting from from idx.
  • npos if all code points matched one of the code points in utf8_str.
Exceptions:
std::length_error Thrown if str_len was 'npos'.

size_type CEGUI::String::find_first_not_of ( const utf8 *  utf8_str,
size_type  idx = 0 
) const [inline]

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

Parameters:
utf8_str Buffer containing null-terminated utf8 encoded data describing the set of code points.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the start point for the search
Returns:
  • Index of the first code point that does not match any one of the code points in utf8_str starting from from idx.
  • npos if all code points matched one of the code points in utf8_str.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

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

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

Parameters:
std_str std::string object describing the set of code points.
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Parameters:
idx Index of the start point for the search
Returns:
  • Index of the first code point that does not match any one of the code points in std_str starting from from idx.
  • npos if all code points matched one of the code points in std_str.

size_type CEGUI::String::find_first_not_of ( const String str,
size_type  idx = 0 
) const [inline]

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

Parameters:
str String object describing the set of code points.
idx Index of the start point for the search
Returns:
  • Index of the first code point that does not match any one of the code points in str starting from from idx.
  • npos if all code points matched one of the code points in str.

References find().

Referenced by CEGUI::Font::drawWrappedText(), CEGUI::Font::getFormattedLineCount(), CEGUI::TextUtils::getNextWord(), CEGUI::TextUtils::getNextWordStartIdx(), CEGUI::Font::getWrappedTextExtent(), and CEGUI::TextUtils::trimLeadingChars().

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

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

Parameters:
chars char array containing the set of chars.
idx Index of the start point for the search
chars_len Number of chars in the char array.
Returns:
  • Index of the first occurrence of any one of the chars in chars starting from from idx.
  • npos if none of the chars in chars were found.
Exceptions:
std::length_error Thrown if chars_len was 'npos'.

size_type CEGUI::String::find_first_of ( const char *  cstr,
size_type  idx = 0 
) const [inline]

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

Parameters:
c_str c-string describing the set of chars.
idx Index of the start point for the search
Returns:
  • Index of the first occurrence of any one of the chars in c_str starting from from idx.
  • npos if none of the chars in c_str were found.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_first_of ( utf32  code_point,
size_type  idx = 0 
) const [inline]

Search forwards for a given code point.

Parameters:
code_point The utf32 code point to search for
idx Index of the code point where the search is to start.
Returns:
  • Index of the first occurrence of code_point starting from from idx.
  • npos if the code point could not be found

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

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

Parameters:
utf8_str Buffer containing utf8 encoded data describing the set of code points.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the start point for the search
str_len Length of the utf8 encoded data in utf8 code units (not code points).
Returns:
  • Index of the first occurrence of any one of the code points in utf8_str starting from from idx.
  • npos if none of the code points in utf8_str were found.
Exceptions:
std::length_error Thrown if str_len was 'npos'.

size_type CEGUI::String::find_first_of ( const utf8 *  utf8_str,
size_type  idx = 0 
) const [inline]

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

Parameters:
utf8_str Buffer containing null-terminated utf8 encoded data describing the set of code points.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the start point for the search
Returns:
  • Index of the first occurrence of any one of the code points in utf8_str starting from from idx.
  • npos if none of the code points in utf8_str were found.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

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

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

Parameters:
std_str std::string object describing the set of code points.
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Parameters:
idx Index of the start point for the search
Returns:
  • Index of the first occurrence of any one of the code points in std_str starting from from idx.
  • npos if none of the code points in std_str were found.

size_type CEGUI::String::find_first_of ( const String str,
size_type  idx = 0 
) const [inline]

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

Parameters:
str String object describing the set of code points.
idx Index of the start point for the search
Returns:
  • Index of the first occurrence of any one of the code points in str starting from from idx.
  • npos if none of the code points in str were found.

References find().

Referenced by CEGUI::Font::drawText(), CEGUI::MultiLineEditbox::formatText(), CEGUI::Font::getFormattedLineCount(), CEGUI::Font::getFormattedTextExtent(), CEGUI::MultiLineEditbox::getNextTokenLength(), CEGUI::TextUtils::getNextWord(), CEGUI::TextUtils::getNextWordStartIdx(), CEGUI::MultiLineEditbox::onMouseTripleClicked(), CEGUI::LuaFunctor::pushNamedFunction(), and CEGUI::MultiColumnListProperties::ColumnHeader::set().

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

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

Parameters:
chars char array containing the set of chars.
idx Index of the start point for the search
chars_len Number of chars in the char array.
Returns:
  • Index of the last code point that does not match any one of the chars in chars, starting from from idx.
  • npos if all code points matched any of the chars in chars.
Exceptions:
std::length_error Thrown if chars_len was 'npos'.

size_type CEGUI::String::find_last_not_of ( const char *  cstr,
size_type  idx = npos 
) const [inline]

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

Parameters:
c_str c-string describing the set of chars.
idx Index of the start point for the search
Returns:
  • Index of the last code point that does not match any one of the chars in c_str starting from idx.
  • npos if all code points matched any of the chars in c_str.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_last_not_of ( utf32  code_point,
size_type  idx = npos 
) const [inline]

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

Parameters:
code_point The utf32 code point to search for
idx Index of the code point where the search is to start.
Returns:
  • Index of the last code point that does not match code_point starting from from idx.
  • npos if all code points matched code_point

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

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

Parameters:
utf8_str Buffer containing utf8 encoded data describing the set of code points.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the start point for the search
str_len Length of the utf8 encoded data in utf8 code units (not code points).
Returns:
  • Index of the last code point that does not match any one of the code points in utf8_str starting from from idx.
  • npos if all code points matched one of the code points in utf8_str.
Exceptions:
std::length_error Thrown if str_len was 'npos'.

size_type CEGUI::String::find_last_not_of ( const utf8 *  utf8_str,
size_type  idx = npos 
) const [inline]

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

Parameters:
utf8_str Buffer containing null-terminated utf8 encoded data describing the set of code points.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the start point for the search
Returns:
  • Index of the last code point that does not match any one of the code points in utf8_str starting from idx.
  • npos if all code points matched one of the code points in utf8_str.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

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

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

Parameters:
std_str std::string object describing the set of code points.
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Parameters:
idx Index of the start point for the search
Returns:
  • Index of the last code point that does not match any one of the code points in std_str starting from idx.
  • npos if all code points matched one of the code points in std_str.

size_type CEGUI::String::find_last_not_of ( const String str,
size_type  idx = npos 
) const [inline]

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

Parameters:
str String object describing the set of code points.
idx Index of the start point for the search
Returns:
  • Index of the last code point that does not match any one of the code points in str starting from idx.
  • npos if all code points matched one of the code points in str.

References find().

Referenced by CEGUI::TextUtils::getWordStartIdx(), and CEGUI::TextUtils::trimTrailingChars().

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

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

Parameters:
chars char array containing the set of chars.
idx Index of the start point for the search
chars_len Number of chars in the char array.
Returns:
  • Index of the last occurrence of any one of the chars in chars, starting from from idx.
  • npos if none of the chars in chars were found.
Exceptions:
std::length_error Thrown if chars_len was 'npos'.

size_type CEGUI::String::find_last_of ( const char *  cstr,
size_type  idx = npos 
) const [inline]

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

Parameters:
c_str c-string describing the set of chars.
idx Index of the start point for the search
Returns:
  • Index of the last occurrence of any one of the chars in c_str starting from idx.
  • npos if none of the chars in c_str were found.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

size_type CEGUI::String::find_last_of ( utf32  code_point,
size_type  idx = npos 
) const [inline]

Search for last occurrence of a given code point.

Parameters:
code_point The utf32 code point to search for
idx Index of the code point where the search is to start.
Returns:
  • Index of the last occurrence of code_point starting from idx.
  • npos if the code point could not be found

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

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

Parameters:
utf8_str Buffer containing utf8 encoded data describing the set of code points.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the start point for the search
str_len Length of the utf8 encoded data in utf8 code units (not code points).
Returns:
  • Index of the last occurrence of any one of the code points in utf8_str starting from from idx.
  • npos if none of the code points in utf8_str were found.
Exceptions:
std::length_error Thrown if str_len was 'npos'.

size_type CEGUI::String::find_last_of ( const utf8 *  utf8_str,
size_type  idx = npos 
) const [inline]

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

Parameters:
utf8_str Buffer containing null-terminated utf8 encoded data describing the set of code points.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the start point for the search
Returns:
  • Index of the last occurrence of any one of the code points in utf8_str starting from idx.
  • npos if none of the code points in utf8_str were found.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

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

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

Parameters:
std_str std::string object describing the set of code points.
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Parameters:
idx Index of the start point for the search
Returns:
  • Index of the last occurrence of any one of the code points in std_str starting from idx.
  • npos if none of the code points in std_str were found.

size_type CEGUI::String::find_last_of ( const String str,
size_type  idx = npos 
) const [inline]

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

Parameters:
str String object describing the set of code points.
idx Index of the start point for the search
Returns:
  • Index of the last occurrence of any one of the code points in str starting from idx.
  • npos if none of the code points in str were found.

References find().

Referenced by CEGUI::TextUtils::getWordStartIdx(), CEGUI::TabControl::makeButtonName(), CEGUI::MultiLineEditbox::onMouseTripleClicked(), and CEGUI::MultiColumnListProperties::ColumnHeader::set().

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

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

Parameters:
idx Index where the data is to be inserted.
chars char array containing the chars that are to be inserted.
chars_len Length of the char array to be inserted.
Returns:
This String after the insert.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.
std::length_error Thrown if resulting String would be too large, or if chars_len is 'npos'

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

Inserts the given c-string at the specified position.

Parameters:
idx Index where the c-string is to be inserted.
c_str c-string that is to be inserted.
Returns:
This String after the insert.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.
std::length_error Thrown if resulting String would be too large.

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

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

Parameters:
pos Iterator describing the position where the data is to be inserted
beg Iterator describing the begining of the range to be inserted
end Iterator describing the (exclusive) end of the range to be inserted.
Returns:
Nothing.
Exceptions:
std::length_error Thrown if resulting String would be too large.

iterator CEGUI::String::insert ( iterator  pos,
utf32  code_point 
) [inline]

Inserts a single code point into the String.

Parameters:
pos Iterator describing the position where the code point is to be inserted
code_point The utf32 code point that is to be inserted
Returns:
This String after the insertion.
Exceptions:
std::length_error Thrown if resulting String would be too large.

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

Inserts a code point multiple times into the String.

Parameters:
pos Iterator describing the position where the code point(s) are to be inserted
num The number of times to insert the code point
code_point The utf32 code point that is to be inserted
Returns:
This String after the insertion.
Exceptions:
std::length_error Thrown if resulting String would be too large, or if num is 'npos'

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

Inserts a code point multiple times into the String.

Parameters:
idx Index where the code point(s) are to be inserted
num The number of times to insert the code point
code_point The utf32 code point that is to be inserted
Returns:
This String after the insertion.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.
std::length_error Thrown if resulting String would be too large, or if num is 'npos'

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

Inserts the given utf8 encoded data at the specified position.

Parameters:
idx Index where the data is to be inserted.
utf8_str Buffer containing the utf8 encoded data that is to be inserted.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
len Length of the data to be inserted in uf8 code units (not code points)
Returns:
This String after the insert.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.
std::length_error Thrown if resulting String would be too large, or if len is 'npos'

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

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

Parameters:
idx Index where the data is to be inserted.
utf8_str Buffer containing the null-terminated utf8 encoded data that is to be inserted.
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Returns:
This String after the insert.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.
std::length_error Thrown if resulting String would be too large.

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

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

Parameters:
idx Index where the string is to be inserted.
std_str std::string object containing data to be inserted.
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Parameters:
str_idx Index of the first character from std_str to be inserted.
str_num Maximum number of characters from str to be inserted.
Returns:
This String after the insert.
Exceptions:
std::out_of_range Thrown if idx or str_idx are out of range.
std::length_error Thrown if resulting String would be too large.

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

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

Parameters:
idx Index where the std::string is to be inserted.
std_str std::string object that is to be inserted.
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Returns:
This String after the insert.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.
std::length_error Thrown if resulting String would be too large.

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

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

Parameters:
idx Index where the string is to be inserted.
str String object containing data to be inserted.
str_idx Index of the first code point from str to be inserted.
str_num Maximum number of code points from str to be inserted.
Returns:
This String after the insert.
Exceptions:
std::out_of_range Thrown if idx or str_idx are out of range.
std::length_error Thrown if resulting String would be too large.

References d_cplength, and ptr().

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

Inserts the given String object at the specified position.

Parameters:
idx Index where the string is to be inserted.
str String object that is to be inserted.
Returns:
This String after the insert.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.
std::length_error Thrown if resulting String would be too large.

Referenced by CEGUI::DynamicModule::DynamicModule(), CEGUI::MultiLineEditbox::handleNewLine(), CEGUI::Window::insertText(), CEGUI::MultiLineEditbox::onCharacter(), CEGUI::Editbox::onCharacter(), and CEGUI::FalagardEditbox::render().

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

Referenced by CEGUI::Font::drawText(), CEGUI::Font::drawTextLine(), CEGUI::Font::drawTextLineJustified(), CEGUI::Combobox::droplist_SelectionAcceptedHandler(), CEGUI::DynamicModule::DynamicModule(), CEGUI::filenameHasTGAExtension(), CEGUI::MultiLineEditbox::formatText(), CEGUI::Font::getCharAtPixel(), CEGUI::Font::getFormattedLineCount(), CEGUI::Font::getFormattedTextExtent(), CEGUI::MultiLineEditbox::getLineNumberFromIndex(), CEGUI::MultiLineEditbox::getNextTokenLength(), CEGUI::TextUtils::getNextWord(), CEGUI::Font::getNextWord(), CEGUI::TextUtils::getNextWordStartIdx(), CEGUI::Font::getTextExtent(), CEGUI::FalagardEditbox::getTextIndexFromPosition(), CEGUI::TextUtils::getWordStartIdx(), CEGUI::MultiLineEditbox::handleCharRight(), CEGUI::Editbox::handleCharRight(), CEGUI::MultiLineEditbox::handleDelete(), CEGUI::Editbox::handleDelete(), CEGUI::MultiLineEditbox::handleDocEnd(), CEGUI::Editbox::handleEnd(), CEGUI::MultiLineEditbox::handleNewLine(), CEGUI::MultiLineEditbox::handleWordRight(), CEGUI::Editbox::handleWordRight(), CEGUI::MultiLineEditbox::onCharacter(), CEGUI::Editbox::onCharacter(), CEGUI::MultiLineEditbox::onMouseDoubleClicked(), CEGUI::Editbox::onMouseDoubleClicked(), CEGUI::MultiLineEditbox::onMouseTripleClicked(), CEGUI::Editbox::onMouseTripleClicked(), CEGUI::MultiLineEditbox::onTextChanged(), CEGUI::Editbox::onTextChanged(), CEGUI::Window::rename(), CEGUI::FalagardEditbox::render(), CEGUI::MultiLineEditbox::setCaratIndex(), CEGUI::Editbox::setCaratIndex(), CEGUI::Window::setFalagardType(), CEGUI::MultiLineEditbox::setMaxTextLength(), CEGUI::Editbox::setMaxTextLength(), CEGUI::MultiLineEditbox::setSelection(), CEGUI::Editbox::setSelection(), and CEGUI::WidgetLookManager::writeWidgetLookSeriesToStream().

static size_type CEGUI::String::max_size ( void   )  [inline, static]

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 char *  cstr  )  [inline]

Appends to the String the given c-string.

Parameters:
c_str c-string that is to be appended.
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::operator+= ( utf32  code_point  )  [inline]

Appends a single code point to the string.

Parameters:
code_point utf32 Unicode code point that is to be appended
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too long.

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

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

Parameters:
utf8_str buffer holding the null-terminated utf8 encoded data that is to be appended
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too large.

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

Appends the std::string std_str.

Parameters:
std_str std::string object that is to be appended
Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too large.

String& CEGUI::String::operator+= ( const String str  )  [inline]

Appends the String str.

Parameters:
str String object that is to be appended
Returns:
This String after the append operation
Exceptions:
std::length_error Thrown if resulting String would be too large.

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

Assign to this String the given C-string.

Parameters:
c_str Pointer to a valid C style string.
Returns:
This String after the assignment has happened
Exceptions:
std::length_error Thrown if the resulting String would have been too large.

String& CEGUI::String::operator= ( utf32  code_point  )  [inline]

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

Parameters:
code_point Valid utf32 Unicode code point to be assigned to the string
Returns:
This String after assignment

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

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

Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
utf8_str Buffer containing valid null-terminated utf8 encoded data
Returns:
This String after the assignment has happened
Exceptions:
std::length_error Thrown if the resulting String would have been too large.

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

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

Note:
The characters of std_str are taken to be unencoded data which represent Unicode code points 0x00..0xFF. No translation of the provided data will occur.
Parameters:
std_str std::string object containing the string value to be assigned.
Returns:
This String after the assignment has happened
Exceptions:
std::length_error Thrown if the resulting String would have been too large.

String& CEGUI::String::operator= ( const String str  )  [inline]

Assign the value of String str to this String.

Parameters:
str String object containing the string value to be assigned.
Returns:
This String after the assignment has happened

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

Returns the code point at the given index.

Parameters:
idx Zero based index of the code point to be returned.
Note:
  • For constant strings length()/size() provide a valid index and will access the default utf32 value.
  • For non-constant strings length()/size() is an invalid index, and acceesing (especially writing) this index could cause string corruption.
Returns:
The utf32 code point at the given index within the String.

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

Returns the code point at the given index.

Parameters:
idx Zero based index of the code point to be returned.
Note:
  • For constant strings length()/size() provide a valid index and will access the default utf32 value.
  • For non-constant strings length()/size() is an invalid index, and acceesing (especially writing) this index could cause string corruption.
Returns:
The utf32 code point at the given index within the String.

void CEGUI::String::push_back ( utf32  code_point  )  [inline]

Appends a single code point to the string.

Parameters:
code_point utf32 Unicode code point that is to be appended
Returns:
Nothing
Exceptions:
std::length_error Thrown if resulting String would be too long.

Referenced by CEGUI::FalagardItemListbox::getItemRenderArea().

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::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::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)

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)

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

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

Note:
If beg == end, the operation is a insert at iterator position beg
Parameters:
beg Iterator describing the start of the range to be replaced
end Iterator describing the (exclusive) end of the range to be replaced.
chars char array containing the chars that are to replace the specified range of code points
chars_len Number of chars in the char array.
Returns:
This String after the replace operation
Exceptions:
std::length_error Thrown if the resulting String would be too large, or if chars_len was 'npos'.

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

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

Parameters:
idx Index of the first code point to be replaced
len Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
chars char array containing the cars that are to replace the specified code points
chars_len Number of chars in the char array.
Returns:
This String after the replace operation
Exceptions:
std::out_of_range Thrown if idx is invalid for this String
std::length_error Thrown if the resulting String would be too large, or if chars_len was 'npos'.

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

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

Note:
If beg == end, the operation is a insert at iterator position beg
Parameters:
beg Iterator describing the start of the range to be replaced
end Iterator describing the (exclusive) end of the range to be replaced.
c_str c-string that is to replace the specified range of code points
Returns:
This String after the replace operation
Exceptions:
std::length_error Thrown if the resulting String would be too large.

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

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

Parameters:
idx Index of the first code point to be replaced
len Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
c_str c-string that is to replace the specified code points
Returns:
This String after the replace operation
Exceptions:
std::out_of_range Thrown if idx is invalid for this String
std::length_error Thrown if the resulting String would be too large.

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

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

Note:
If beg == end, the operation is an insert at iterator position beg
Parameters:
beg Iterator describing the start of the range to be replaced
end Iterator describing the (exclusive) end of the range to be replaced.
newBeg Iterator describing the beginning of the range to insert.
newEnd Iterator describing the (exclusive) end of the range to insert.
Returns:
This String after the insert operation.
Exceptions:
std::length_error Thrown if the resulting string would be too long.

References CEGUI::String::const_iterator::d_ptr.

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

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

Note:
If beg == end, the operation is an insert at iterator position beg
Parameters:
beg Iterator describing the start of the range to be replaced
end Iterator describing the (exclusive) end of the range to be replaced.
num Number of occurrences of code_point that are to replace the specified range of code points
code_point Code point that is to be used when replacing the specified range of code points
Returns:
This String after the replace operation
Exceptions:
std::length_error Thrown if resulting String would have been too long, or if num was 'npos'.

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

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

Parameters:
idx Index of the first code point to be replaced
len Maximum number of code points to replace. If this is 0 the operation is an insert
num Number of occurrences of code_point that are to replace the specified range of code points
code_point Code point that is to be used when replacing the specified range of code points
Returns:
This String after the replace operation.
Exceptions:
std::out_of_range Thrown if idx is invalid for this String
std::length_error Thrown if resulting String would have been too long, or if num was 'npos'.

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

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

Note:
If beg == end, the operation is a insert at iterator position beg
Parameters:
beg Iterator describing the start of the range to be replaced
end Iterator describing the (exclusive) end of the range to be replaced.
utf8_str Buffer containing the null-terminated utf8 encoded data that is to replace the specified range of code points
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
str_len Length of the utf8 encoded data in utf8 code units (not code points).
Returns:
This String after the replace operation
Exceptions:
std::length_error Thrown if the resulting String would be too large, or if str_len was 'npos'.

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

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

Parameters:
idx Index of the first code point to be replaced
len Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
utf8_str Buffer containing the null-terminated utf8 encoded data that is to replace the specified code points
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
str_len Length of the utf8 encoded data in utf8 code units (not code points).
Returns:
This String after the replace operation
Exceptions:
std::out_of_range Thrown if idx is invalid for this String
std::length_error Thrown if the resulting String would be too large, or if str_len was 'npos'.

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

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

Note:
If beg == end, the operation is a insert at iterator position beg
Parameters:
beg Iterator describing the start of the range to be replaced
end Iterator describing the (exclusive) end of the range to be replaced.
utf8_str Buffer containing the null-terminated utf8 encoded data that is to replace the specified range of code points
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Returns:
This String after the replace operation
Exceptions:
std::length_error Thrown if the resulting String would be too large.

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

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

Parameters:
idx Index of the first code point to be replaced
len Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
utf8_str Buffer containing the null-terminated utf8 encoded data that is to replace the specified code points
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Returns:
This String after the replace operation
Exceptions:
std::out_of_range Thrown if idx is invalid for this String
std::length_error Thrown if the resulting String would be too large.

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

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

Parameters:
idx Index of the first code point to be replaced
len Maximum number of code points to be replaced. If this is 0, the operation is an insert at position idx.
std_str std::string object containing the data that will replace the specified range of code points
Note:
Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.
Parameters:
str_idx Index of the first code point of std_str that is to replace the specified code point range
str_num Maximum number of code points of std_str that are to replace the specified code point range
Returns:
This String after the replace operation
Exceptions:
std::out_of_range Thrown if either idx, or str_idx are invalid
std::length_error Thrown if the resulting String would have been too large.

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

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

Note:
If beg == end, the operation is a insert at iterator position beg
Parameters:
beg Iterator describing the start of the range to be replaced
end Iterator describing the (exclusive) end of the range to be replaced.
std_str The std::string object that is to replace the specified range of code points
Note:
Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.
Returns:
This String after the replace operation
Exceptions:
std::length_error Thrown if the resulting String would be too large.

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

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

Parameters:
idx Index of the first code point to be replaced
len Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
std_str The std::string object that is to replace the specified code points
Note:
Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.
Returns:
This String after the replace operation
Exceptions:
std::out_of_range Thrown if idx is invalid for this String
std::length_error Thrown if the resulting String would be too large.

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

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

Parameters:
idx Index of the first code point to be replaced
len Maximum number of code points to be replaced. If this is 0, the operation is an insert at position idx.
str String object containing the data that will replace the specified range of code points
str_idx Index of the first code point of str that is to replace the specified code point range
str_num Maximum number of code points of str that are to replace the specified code point range
Returns:
This String after the replace operation
Exceptions:
std::out_of_range Thrown if either idx, or str_idx are invalid
std::length_error Thrown if the resulting String would have been too large.

References d_cplength, and ptr().

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

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

Note:
If beg == end, the operation is a insert at iterator position beg
Parameters:
beg Iterator describing the start of the range to be replaced
end Iterator describing the (exclusive) end of the range to be replaced.
str The String object that is to replace the specified range of code points
Returns:
This String after the replace operation
Exceptions:
std::length_error Thrown if the resulting String would be too large.

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

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

Parameters:
idx Index of the first code point to be replaced
len Maximum number of code points to be replaced (if this is 0, operation is an insert at position idx)
str The String object that is to replace the specified code points
Returns:
This String after the replace operation
Exceptions:
std::out_of_range Thrown if idx is invalid for this String
std::length_error Thrown if the resulting String would be too large.

void CEGUI::String::reserve ( size_type  num = 0  )  [inline]

Specifies the amount of reserve capacity to allocate.

Parameters:
num The number of code points to allocate space for. If num is larger that the current reserve, then a re-allocation will occur. If num is smaller than the current reserve (but not 0) the buffer may be shrunk to the larger of the specified number, or the current String size (operation is currently not implemented). If num is 0, then the buffer is re-allocated to fit the current String size.
Returns:
Nothing
Exceptions:
std::length_error Thrown if resulting String object would be too big.

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

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

Parameters:
num The length, in code points, that the String is to be made.
code_point The utf32 code point that should be used when majing the String larger
Returns:
Nothing.
Exceptions:
std::length_error Thrown if the String would be too large.

void CEGUI::String::resize ( size_type  num  )  [inline]

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

Parameters:
num The length, in code points, that the String is to be made.
Returns:
Nothing.
Exceptions:
std::length_error Thrown if the String would be too large.

Referenced by CEGUI::MultiLineEditbox::setMaxTextLength(), CEGUI::Editbox::setMaxTextLength(), and CEGUI::TextUtils::trimTrailingChars().

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

Search backwards for a sub-string.

Parameters:
chars char array describing the sub-string to search for
idx Index of the code point where the search is to start
chars_len Number of chars in the char array.
Returns:
  • Index of the first occurrence of sub-string chars travelling backwards from idx.
  • npos if the sub-string could not be found
Exceptions:
std::length_error Thrown if chars_len is 'npos'

size_type CEGUI::String::rfind ( const char *  cstr,
size_type  idx = npos 
) const [inline]

Search backwards for a sub-string.

Parameters:
c_str c-string describing the sub-string to search for
idx Index of the code point where the search is to start
Returns:
  • Index of the first occurrence of sub-string c_str travelling backwards from idx.
  • npos if the sub-string could not be found
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

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

Search backwards for a sub-string.

Parameters:
utf8_str Buffer containing utf8 encoded data describing the sub-string to search for
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the code point where the search is to start
str_len Length of the utf8 encoded sub-string in utf8 code units (not code points)
Returns:
  • Index of the first occurrence of sub-string utf8_str travelling backwards from idx.
  • npos if the sub-string could not be found
Exceptions:
std::length_error Thrown if str_len is 'npos'

size_type CEGUI::String::rfind ( const utf8 *  utf8_str,
size_type  idx = npos 
) const [inline]

Search backwards for a sub-string.

Parameters:
utf8_str Buffer containing null-terminated utf8 encoded data describing the sub-string to search for
Note:
A basic string literal (cast to utf8*) can be passed to this function, provided that the string is comprised only of code points 0x00..0x7f. The use of extended ASCII characters (with values >0x7f) would result in incorrect behaviour as the String will attempt to 'decode' the data, with unpredictable results.
Parameters:
idx Index of the code point where the search is to start
Returns:
  • Index of the first occurrence of sub-string utf8_str travelling backwards from idx.
  • npos if the sub-string could not be found
Exceptions:
std::out_of_range Thrown if idx is invalid for this String.

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

Search backwards for a sub-string.

Parameters:
std_str std::string object describing the sub-string to search for
Note:
Characters from std_str are considered to represent Unicode code points in the range 0x00..0xFF. No translation of the encountered data is performed.
Parameters:
idx Index of the code point where the search is to start
Returns:
  • Index of the first occurrence of sub-string std_str travelling backwards from idx.
  • npos if the sub-string could not be found

size_type CEGUI::String::rfind ( const String str,
size_type  idx = npos 
) const [inline]

Search backwards for a sub-string.

Parameters:
str String object describing the sub-string to search for
idx Index of the code point where the search is to start
Returns:
  • Index of the first occurrence of sub-string str travelling backwards from idx.
  • npos if the sub-string could not be found

References d_cplength.

size_type CEGUI::String::rfind ( utf32  code_point,
size_type  idx = npos 
) const [inline]

Search backwards for a given code point.

Parameters:
code_point The utf32 code point to search for
idx Index of the code point where the search is to start.
Returns:
  • Index of the first occurrence of code_point travelling backwards from idx.
  • npos if the code point could not be found

Referenced by CEGUI::MultiColumnListProperties::ColumnHeader::set(), and CEGUI::Window::Window().

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]

void CEGUI::String::swap ( String str  )  [inline]

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

Parameters:
str String object whos value is to be swapped with this String.
Returns:
Nothing

References d_buffer, d_cplength, d_quickbuff, and d_reserve.

Referenced by CEGUI::swap().

size_type CEGUI::String::utf8_stream_len ( size_type  num = npos,
size_type  idx = 0 
) const [inline]

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

Parameters:
num Maximum number of code points to consider when calculating utf8 encoded size.
idx Index of the first code point to consider when calculating the utf8 encoded size
Returns:
The number of utf8 code units (bytes) required to hold the specified sub-string when encoded as utf8 data.
Exceptions:
std::out_of_range Thrown if idx was invalid for this String.


Generated on Thu Nov 27 20:34:31 2008 for Crazy Eddies GUI System by  doxygen 1.5.7.1