Protected Attributes

Friends

class

StringIterator

Detailed Description

Unicode mutable string class. Uses UTF-8 encoding. For optimal performance, use the StringIterator class to iterate over a WoopsiString instance.

Where possible, the string avoids allocating memory each time the string grows or shrinks. This means that the string may consume more memory than the number of chars would seem to dictate if the object previously contained a large string that has subsequently been truncated. It also means that increasing the length of such a string is a cheaper operation as memory does not need to allocated and copied.

Additionally, the string increases its array size by _growAmount every time it needs to allocate extra memory, potentially reducing the number of reallocs needed.

The string is not null-terminated. Instead, it uses a _stringLength member that stores the number of characters in the string. This saves a byte and makes calls to getLength() run in O(1) time instead of O(n).

Zero if both strings are equal. A value greater than zero indicates that this string is greater than the argument string. A value less than zero indicates the opposite. Note that the return value indicates the *byte* that does not match, not the *character*.

virtual void WoopsiUI::WoopsiString::copyToCharArray

(

char *

buffer

)

const [virtual]

Copy the internal array to the supplied buffer. The buffer must be large enough to contain the full text in the string. The getByteCount() method can be used to obtain the length of the string. Unlike the WoopsiString class, the char array is null-terminated. The buffer must be (getByteCount() + 1) bytes long, in order to accommodate the terminator.

Parameters:

buffer

Buffer to copy the internal char array to.

s32 WoopsiUI::WoopsiString::filterString

(

char *

dest,

const char *

src,

s32

sourceBytes,

s32 *

totalUnicodeChars

)

const [protected]

Copies the valid utf-8 tokens of the string src into string dest and returns the number of bytes in the filtered string.

Parameters:

dest

Destination string.

src

Source string.

sourceBytes

Number of bytes in the source string.

totalUnicodeChars

Output parameter populated with the total number of unicode characters in the filtered string.

Returns:

The number of bytes in the filtered string.

void WoopsiUI::WoopsiString::format

(

const char *

format,

va_list

args

)

Formats the supplied char array using standard printf() syntax. The formatted text replaces the contents of the current string object. Note that va_start() must be called before this method is used, and va_end() must be called when it finishes.

Note that the compiler message regarding va_list mangling changes in GCC 4.4 are not problems with Woopsi's code. They are the result of the GCC team bizarrely deciding to include news items in compiler messages: http://gcc.gnu.org/bugzilla/show_bug.cgi?id=42748

Parameters:

format

The format to use.

args

The formatting arguments.

void WoopsiUI::WoopsiString::format

(

const char *

format,

...

)

Formats the supplied char array using standard printf() syntax. The formatted text replaces the contents of the current string object.

Parameters:

format

The format to use.

...

The formatting arguments.

virtual s32 WoopsiUI::WoopsiString::getAllocatedSize

(

)

const [inline, protected, virtual]

Get the amount of allocated memory.

Returns:

The number of chars allocated in RAM.

virtual const s32 WoopsiUI::WoopsiString::getByteCount

(

)

const [inline, virtual]

Get the of number of bytes in the string.

Returns:

The number of bytes of the string.

virtual const char* WoopsiUI::WoopsiString::getCharArray

(

)

const [inline, protected, virtual]

Returns a pointer to the raw char array data.

Returns:

Pointer to the char array.

virtual const u32 WoopsiUI::WoopsiString::getCharAt

(

s32

index

)

const [virtual]

Get the character at the specified index. This function is useful for finding the occasional character at an index, but for iterating over strings it is exceptionally slow. The newStringIterator() method should be used to retrieve an iterator object that can iterate over the string efficiently.

Parameters:

index

The index of the character to retrieve.

Returns:

The character at the specified index.

u32 WoopsiUI::WoopsiString::getCodePoint

(

const char *

string,

u8 *

numChars = NULL

)

const [protected]

Get the number of chars read in the UTF-8 token and its codepoint. In the case of an invalid codepoint, the value returned will be 0.

Parameters:

string

String to analyse.

numChars

Pointer to a u8 that will hold the number of chars in the codepoint once the method ends.

Returns:

The codepoint. Returns 0 if the codepoint is invalid.

virtual const s32 WoopsiUI::WoopsiString::getLength

(

)

const [inline, virtual]

Get the of number of UTF-8 tokens (ie. the length) of the string.

Returns:

The length of the string.

virtual char* WoopsiUI::WoopsiString::getToken

(

const s32

index

)

const [protected, virtual]

Return a pointer to the specified UTF-8 token.

Parameters:

index

Index of the UTF-8 token to retrieve.

virtual bool WoopsiUI::WoopsiString::hasData

(

)

const [inline, protected, virtual]

Check if we've got any string data stored or not.

Returns:

True if the string contains any data; false if no data has yet been supplied.

Gets the character index of the first occurence of the supplied string within the bounds of the current string between startIndex and startIndex + count. If the string is not found, the method will return -1.

Parameters:

text

The char array to find.

startIndex

The index to start searching from.

count

The number of characters to examine.

Returns:

The index of the char array within the current string if it exists, or -1 if it does not.

virtual const s32 WoopsiUI::WoopsiString::indexOf

(

u32

letter,

s32

startIndex,

s32

count

)

const [virtual]

Returns the first index of the specified letter within the string. Will return -1 if the letter is not found. Scans through the string from "startIndex" until it has examined all letters within the range "count".

Parameters:

letter

Letter to find.

startIndex

The index to start searching from.

count

The number of characters to examine.

Returns:

The index of the letter.

const s32 WoopsiUI::WoopsiString::indexOf

(

u32

letter

)

const

Returns the first index of the specified letter within the string. Will return -1 if the letter is not found.

Parameters:

letter

Letter to find.

Returns:

The index of the letter.

const s32 WoopsiUI::WoopsiString::indexOf

(

u32

letter,

s32

startIndex

)

const

Returns the first index of the specified letter within the string. Will return -1 if the letter is not found. Scans through the string from "startIndex" until it has examined all subsequent letters.

Parameters:

letter

Letter to find.

startIndex

The index to start searching from.

Returns:

The index of the letter.

s32 WoopsiUI::WoopsiString::indexOf

(

const char *

text

)

const

Gets the character index of the first occurence of the supplied char array within the string. If the char array is not found, the method will return -1.

Parameters:

text

The char array to find.

Returns:

The index of the char array within the current string if it exists, or -1 if it does not.

s32 WoopsiUI::WoopsiString::indexOf

(

const char *

text,

s32

startIndex

)

const

Gets the character index of the first occurence after startIndex of the supplied char array within the string. If the char array is not found, the method will return -1.

Parameters:

text

The char array to find.

startIndex

The index to start searching from.

Returns:

The index of the char array within the current string if it exists, or -1 if it does not.

Returns the last index of the specified letter within the string. Will return -1 if the letter is not found.

Parameters:

letter

Letter to find.

Returns:

The index of the letter.

s32 WoopsiUI::WoopsiString::lastIndexOf

(

const char *

text

)

const

Gets the character index of the last occurence of the supplied char array within the string. If the char array is not found, the method will return -1.

Parameters:

text

The char array to find.

Returns:

The index of the char array within the current string if it exists, or -1 if it does not.

s32 WoopsiUI::WoopsiString::lastIndexOf

(

const char *

text,

s32

startIndex

)

const

Gets the character index of the last occurence after startIndex of the supplied char array within the string. If the char array is not found, the method will return -1.

Parameters:

text

The char array to find.

startIndex

The index to start searching from.

Returns:

The index of the char array within the current string if it exists, or -1 if it does not.

const s32 WoopsiUI::WoopsiString::lastIndexOf

(

u32

letter,

s32

startIndex

)

const

Returns the last index of the specified letter within the string. Will return -1 if the letter is not found. Scans through the string backwards from "startIndex" until it has examined all preceding letters within the string.

Parameters:

letter

Letter to find.

startIndex

The index to start searching from.

Returns:

The index of the letter.

virtual const s32 WoopsiUI::WoopsiString::lastIndexOf

(

u32

letter,

s32

startIndex,

s32

count

)

const [virtual]

Returns the last index of the specified letter within the string. Will return -1 if the letter is not found. Scans through the string backwards from "startIndex" until it has examined all letters within the range "count".

Gets the character index of the last occurence of the supplied string within the bounds of the current string between startIndex and startIndex - count. If the string is not found, the method will return -1.

Parameters:

text

The char array to find.

startIndex

The index to start searching from.

count

The number of characters to examine.

Returns:

The index of the char array within the current string if it exists, or -1 if it does not.