# CEGUI::String Class Reference

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

List of all members.

## 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.
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)
| Return the number of utf8 code units required to hold an area of the String when encoded as utf8 data.
String & | operator= (const String &str)
| Assign the value of String str to this String.
String & | assign (const String &str, size_type str_idx=0, size_type str_num=npos)
| Assign a sub-string of String str to this String.
String & | operator= (const std::string &std_str)
| Assign the value of std::string std_str to this String.
String & | assign (const std::string &std_str, size_type str_idx=0, size_type str_num=npos)
| Assign a sub-string of std::string std_str to this String.
String & | operator= (const utf8 *utf8_str)
| Assign to this String the string value represented by the given null-terminated utf8 encoded data.
String & | assign (const utf8 *utf8_str)
| Assign to this String the string value represented by the given null-terminated utf8 encoded data.
String & | assign (const utf8 *utf8_str, size_type str_num)
| Assign to this String the string value represented by the given utf8 encoded data.
String & | operator= (utf32 code_point)
| Assigns the specified utf32 code point to this String. Result is always a String 1 code point in length.
String & | assign (size_type num, utf32 code_point)
| Assigns the specified code point repeatedly to the String.
String & | operator= (const char *cstr)
| Assign to this String the given C-string.
String & | assign (const char *cstr)
| Assign to this String the given C-string.
String & | assign (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.
String & | operator+= (const String &str)
| Appends the String str.
String & | append (const String &str, size_type str_idx=0, size_type str_num=npos)
| Appends a sub-string of the String str.
String & | operator+= (const std::string &std_str)
| Appends the std::string std_str.
String & | append (const std::string &std_str, size_type str_idx=0, size_type str_num=npos)
| Appends a sub-string of the std::string std_str.
String & | operator+= (const utf8 *utf8_str)
| Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.
String & | append (const utf8 *utf8_str)
| Appends to the String the null-terminated utf8 encoded data in the buffer utf8_str.
String & | append (const utf8 *utf8_str, size_type len)
| Appends to the String the utf8 encoded data in the buffer utf8_str.
String & | operator+= (utf32 code_point)
| Appends a single code point to the string.
String & | append (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.
String & | append (const_iterator iter_beg, const_iterator iter_end)
| Appends the code points in the reange [beg, end).
String & | operator+= (const char *cstr)
| Appends to the String the given c-string.
String & | append (const char *cstr)
| Appends to the String the given c-string.
String & | append (const char *chars, size_type chars_len)
| Appends to the String chars from the given char array.
String & | insert (size_type idx, const String &str)
| Inserts the given String object at the specified position.
String & | insert (size_type idx, const String &str, size_type str_idx, size_type str_num)
| Inserts a sub-string of the given String object at the specified position.
String & | insert (size_type idx, const std::string &std_str)
| Inserts the given std::string object at the specified position.
String & | insert (size_type idx, const std::string &std_str, size_type str_idx, size_type str_num)
| Inserts a sub-string of the given std::string object at the specified position.
String & | insert (size_type idx, const utf8 *utf8_str)
| Inserts the given null-terminated utf8 encoded data at the specified position.
String & | insert (size_type idx, const utf8 *utf8_str, size_type len)
| Inserts the given utf8 encoded data at the specified position.
String & | insert (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).
String & | insert (size_type idx, const char *cstr)
| Inserts the given c-string at the specified position.
String & | insert (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.
String & | erase (void)
| Removes all data from the String.
String & | erase (size_type idx)
| Erase a single code point from the string.
String & | erase (size_type idx, size_type len=npos)
| Erase a range of code points.
String & | erase (iterator pos)
| Erase the code point described by the given iterator.
String & | erase (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.
String & | replace (size_type idx, size_type len, const String &str)
| Replace code points in the String with the specified String object.
String & | replace (iterator iter_beg, iterator iter_end, const String &str)
| Replace the code points in the range [beg, end) with the specified String object.
String & | replace (size_type idx, size_type len, const String &str, size_type str_idx, size_type str_num)
| Replace code points in the String with a specified sub-string of a given String object.
String & | replace (size_type idx, size_type len, const std::string &std_str)
| Replace code points in the String with the specified std::string object.
String & | replace (iterator iter_beg, iterator iter_end, const std::string &std_str)
| Replace the code points in the range [beg, end) with the specified std::string object.
String & | replace (size_type idx, size_type len, const std::string &std_str, size_type str_idx, size_type str_num)
| Replace code points in the String with a specified sub-string of a given std::string object.
String & | replace (size_type idx, size_type len, const utf8 *utf8_str)
| Replace code points in the String with the specified null-terminated utf8 encoded data.
String & | replace (iterator iter_beg, iterator iter_end, const utf8 *utf8_str)
| Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data.
String & | replace (size_type idx, size_type len, const utf8 *utf8_str, size_type str_len)
| Replace code points in the String with the specified utf8 encoded data.
String & | replace (iterator iter_beg, iterator iter_end, const utf8 *utf8_str, size_type str_len)
| Replace the code points in the range [beg, end) with the specified null-terminated utf8 encoded data.
String & | replace (size_type idx, size_type len, size_type num, utf32 code_point)
| Replaces a specified range of code points with occurrences of a given code point.
String & | replace (iterator iter_beg, iterator iter_end, size_type num, utf32 code_point)
| Replace the code points in the range [beg, end) with occurrences of a given code point.
String & | replace (iterator iter_beg, iterator iter_end, const_iterator iter_newBeg, const_iterator iter_newEnd)
| Replace the code points in the range [beg, end) with code points from the range [newBeg, newEnd).
String & | replace (size_type idx, size_type len, const char *cstr)
| Replace code points in the String with the specified c-string.
String & | replace (iterator iter_beg, iterator iter_end, const char *cstr)
| Replace the code points in the range [beg, end) with the specified c-string.
String & | replace (size_type idx, size_type len, const char *chars, size_type chars_len)
| Replace code points in the String with chars from the given char array.
String & | replace (iterator iter_beg, iterator iter_end, const char *chars, size_type chars_len)
| Replace the code points in the range [beg, end) with chars from the given char array.
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.

## Classes

class | const_iterator
| Constant forward iterator class for String objects. More...
class | iterator
| Forward iterator class for String objects. More...

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

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

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.

const char* CEGUI::String::c_str | ( | void |  | ) | const`[inline]`

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

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

Note:
  The buffer returned from this function is owned by the String object.

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

size_type CEGUI::String::capacity | ( | void |  | ) | const`[inline]`

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

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

void CEGUI::String::clear | ( | void |  | ) | `[inline]`

Removes all data from the String.

Returns:
  Nothing

int CEGUI::String::compare | ( | 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.

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

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.

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.

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]`

Removes all data from the String.

Returns:
  The empty String (*this)

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

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

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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

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

Search backwards for a given code point.

Parameters:

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

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

size_type CEGUI::String::size | ( | void |  | ) | const`[inline]`

Returns the size of the String in code points.

Returns:
  Number of code points currently in the String

String CEGUI::String::substr | ( | size_type | idx = `0`,
|  | size_type | len = `npos`
| ) | const`[inline]`

Returns a substring of this String.

Parameters:

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

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

Exceptions:

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

void CEGUI::String::swap | ( | String & | str | ) | `[inline]`

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

Parameters:

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

Returns:
  Nothing

size_type CEGUI::String::utf8_stream_len | ( | size_type | num = `npos`,
|  | size_type | idx = `0`
| ) | `[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.