Woopsi 1.3
Nintendo DS Gui Framework
Public Member Functions | Protected Member Functions | Protected Attributes | Friends
WoopsiUI::WoopsiString Class Reference

#include <libwoopsi/include/woopsistring.h>

List of all members.

Public Member Functions

 WoopsiString ()
 WoopsiString (const char *text)
 WoopsiString (const u32 letter)
 WoopsiString (const WoopsiString &string)
 WoopsiString (const WoopsiString &string, const s32 startIndex)
 WoopsiString (const WoopsiString &string, const s32 startIndex, const s32 length)
virtual ~WoopsiString ()
StringIteratornewStringIterator () const
virtual void copyToCharArray (char *buffer) const
virtual void setText (const WoopsiString &text, const s32 startIndex, const s32 length)
virtual void setText (const WoopsiString &text)
virtual void setText (const char *text)
virtual void setText (const u32 text)
virtual void append (const WoopsiString &text)
virtual void insert (const WoopsiString &text, const s32 index)
virtual void remove (const s32 startIndex)
virtual void remove (const s32 startIndex, const s32 count)
virtual const s32 getLength () const
virtual const s32 getByteCount () const
virtual const u32 getCharAt (s32 index) const
const s32 indexOf (u32 letter) const
const s32 indexOf (u32 letter, s32 startIndex) const
virtual const s32 indexOf (u32 letter, s32 startIndex, s32 count) const
const s32 lastIndexOf (u32 letter) const
const s32 lastIndexOf (u32 letter, s32 startIndex) const
virtual const s32 lastIndexOf (u32 letter, s32 startIndex, s32 count) const
WoopsiString subString (s32 startIndex) const
WoopsiString subString (s32 startIndex, s32 length) const
WoopsiStringoperator= (const WoopsiString &string)
WoopsiStringoperator= (const char *string)
WoopsiStringoperator= (u32 letter)
WoopsiString operator+ (const WoopsiString &string)
WoopsiStringoperator+= (const WoopsiString &string)
bool operator== (const WoopsiString &string)
bool operator!= (const WoopsiString &string)
virtual s8 compareTo (const WoopsiString &string, bool caseSensitive=false) const
s32 indexOf (const char *text) const
s32 indexOf (const char *text, s32 startIndex) const
s32 indexOf (const WoopsiString &text, s32 startIndex, s32 count) const
s32 lastIndexOf (const char *text) const
s32 lastIndexOf (const char *text, s32 startIndex) const
s32 lastIndexOf (const WoopsiString &text, s32 startIndex, s32 count) const
void format (const char *format,...)
void format (const char *format, va_list args)
void replace (const WoopsiString &oldText, const WoopsiString &newText)
void replace (const WoopsiString &oldText, const WoopsiString &newText, const s32 startIndex)
void replace (const s32 startIndex, const s32 count, const WoopsiString &newText)
void replace (const WoopsiString &oldText, const WoopsiString &newText, const s32 startIndex, const s32 replaceCount)
void split (const WoopsiString &separator, WoopsiArray< WoopsiString > &result) const
void split (const WoopsiString &separator, bool allowEmptyEntries, WoopsiArray< WoopsiString > &result) const

Protected Member Functions

virtual void init ()
virtual void allocateMemory (s32 chars, bool preserve)
virtual bool hasData () const
virtual s32 getAllocatedSize () const
s32 filterString (char *dest, const char *src, s32 sourceBytes, s32 *totalUnicodeChars) const
virtual const char * getCharArray () const
virtual char * getToken (const s32 index) const
u32 getCodePoint (const char *string, u8 *numChars=NULL) const

Protected Attributes

char * _text

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


Constructor & Destructor Documentation

WoopsiUI::WoopsiString::WoopsiString ( )

Constructor to create a blank string.

WoopsiUI::WoopsiString::WoopsiString ( const char *  text)

Constructor to create a string from a char array.

Parameters:
textPointer to a char array to use as the basis of the string.
WoopsiUI::WoopsiString::WoopsiString ( const u32  letter)

Constructor to create a string from a single character.

Parameters:
letterSingle character to use as the basis of the string.
WoopsiUI::WoopsiString::WoopsiString ( const WoopsiString string)

Copy constructor.

Parameters:
stringWoopsiString object to create a copy of.
WoopsiUI::WoopsiString::WoopsiString ( const WoopsiString string,
const s32  startIndex 
)

Constructor that creates a copy of the supplied string from startIndex onwards (ie. it creates a substring).

Parameters:
stringWoopsiString object to create a copy of.
startIndexThe index to copy from.
WoopsiUI::WoopsiString::WoopsiString ( const WoopsiString string,
const s32  startIndex,
const s32  length 
)

Constructor that creates a copy of the supplied string from startIndex until startIndex + count (ie. it creates a substring).

Parameters:
stringWoopsiString object to create a copy of.
startIndexThe index to copy from.
lengthThe number of characters to copy.
virtual WoopsiUI::WoopsiString::~WoopsiString ( ) [inline, virtual]

Destructor.


Member Function Documentation

virtual void WoopsiUI::WoopsiString::allocateMemory ( s32  chars,
bool  preserve 
) [protected, virtual]

Allocate memory for the string.

Parameters:
charsNumber of chars to allocate.
preserveIf true, the data in the existing memory will be preserved if new memory must be allocated
virtual void WoopsiUI::WoopsiString::append ( const WoopsiString text) [virtual]

Append text to the end of the string.

Parameters:
textString to append.
virtual s8 WoopsiUI::WoopsiString::compareTo ( const WoopsiString string,
bool  caseSensitive = false 
) const [virtual]

Compares this string to the argument.

Parameters:
stringString to compare to.
caseSensitivePerforms a case-sensitive compare if this is set to true.
Returns:
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:
bufferBuffer 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:
destDestination string.
srcSource string.
sourceBytesNumber of bytes in the source string.
totalUnicodeCharsOutput 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:
formatThe format to use.
argsThe 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:
formatThe 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:
indexThe 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:
stringString to analyse.
numCharsPointer 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:
indexIndex 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.
s32 WoopsiUI::WoopsiString::indexOf ( const WoopsiString text,
s32  startIndex,
s32  count 
) const

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:
textThe char array to find.
startIndexThe index to start searching from.
countThe 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:
letterLetter to find.
startIndexThe index to start searching from.
countThe 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:
letterLetter 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:
letterLetter to find.
startIndexThe 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:
textThe 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:
textThe char array to find.
startIndexThe 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.
virtual void WoopsiUI::WoopsiString::init ( ) [protected, virtual]

Initialise the string's default state; called by constructors.

virtual void WoopsiUI::WoopsiString::insert ( const WoopsiString text,
const s32  index 
) [virtual]

Insert text at the specified character index.

Parameters:
textThe text to insert.
indexThe index at which to insert the text.
const s32 WoopsiUI::WoopsiString::lastIndexOf ( u32  letter) const

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

Parameters:
letterLetter 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:
textThe 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:
textThe char array to find.
startIndexThe 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:
letterLetter to find.
startIndexThe 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".

Parameters:
letterLetter to find.
startIndexThe index to start searching from.
countThe number of characters to examine.
Returns:
The index of the letter.
s32 WoopsiUI::WoopsiString::lastIndexOf ( const WoopsiString text,
s32  startIndex,
s32  count 
) const

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:
textThe char array to find.
startIndexThe index to start searching from.
countThe 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.
StringIterator* WoopsiUI::WoopsiString::newStringIterator ( ) const

Creates and returns a new StringIterator object that will iterate over this string. The object must be manually deleted once it is no longer needed.

Returns:
A new StringIterator object.
bool WoopsiUI::WoopsiString::operator!= ( const WoopsiString string) [inline]

Overloaded inequality operator. Checks if this string and the supplied argument are not equal.

Parameters:
stringThe string to compare with.
Returns:
False if the strings are equal; true if not.
WoopsiString WoopsiUI::WoopsiString::operator+ ( const WoopsiString string)

Overloaded addition operator. Creates a copy of the current string, appends the parameter string, and returns the updated copy.

Parameters:
stringThe string to append.
Returns:
A copy of this string with the parameter string appended.
WoopsiString& WoopsiUI::WoopsiString::operator+= ( const WoopsiString string)

Overloaded compound addition/assignment operator. Appends the parameter string to the current string.

Parameters:
stringThe string to append.
Returns:
This string.
WoopsiString& WoopsiUI::WoopsiString::operator= ( u32  letter)

Overloaded assignment operator. Copies the data from the argument char to this string.

Parameters:
letterThe char to copy.
Returns:
This string.
WoopsiString& WoopsiUI::WoopsiString::operator= ( const WoopsiString string)

Overloaded assignment operator. Copies the data within the argument string to this string.

Parameters:
stringThe string to copy.
Returns:
This string.
WoopsiString& WoopsiUI::WoopsiString::operator= ( const char *  string)

Overloaded assignment operator. Copies the data within the argument char array to this string.

Parameters:
stringThe string to copy.
Returns:
This string.
bool WoopsiUI::WoopsiString::operator== ( const WoopsiString string) [inline]

Overloaded equality operator. Checks if this string and the supplied argument are equal.

Parameters:
stringThe string to compare with.
Returns:
True if the strings are equal; false if not.
virtual void WoopsiUI::WoopsiString::remove ( const s32  startIndex,
const s32  count 
) [virtual]

Remove specified number of characters from the string from the start index onwards.

Parameters:
startIndexIndex to remove from.
countNumber of characters to remove.
virtual void WoopsiUI::WoopsiString::remove ( const s32  startIndex) [virtual]

Remove all characters from the string from the start index onwards.

Parameters:
startIndexIndex to remove from.
void WoopsiUI::WoopsiString::replace ( const WoopsiString oldText,
const WoopsiString newText 
)

Replace all instances of oldText within the current string with newText.

Parameters:
oldTextThe text to search for and replace.
newTextThe new text that will appear in place of the old.
void WoopsiUI::WoopsiString::replace ( const s32  startIndex,
const s32  count,
const WoopsiString newText 
)

Replace the text between the bounds defined by startIndex and startIndex + count with newText.

Parameters:
startIndexThe index to start replacing from.
countThe number of characters to replace.
newTextThe new text that will appear in place of the old.
void WoopsiUI::WoopsiString::replace ( const WoopsiString oldText,
const WoopsiString newText,
const s32  startIndex,
const s32  replaceCount 
)

Replace the first replaceCount instances of oldText within the current string from startIndex onwards with newText.

Parameters:
oldTextThe text to search for and replace.
newTextThe new text that will appear in place of the old.
startIndexThe index to start replacing from.
replaceCountThe number of replacements to make.
void WoopsiUI::WoopsiString::replace ( const WoopsiString oldText,
const WoopsiString newText,
const s32  startIndex 
)

Replace all instances of oldText within the current string from startIndex onwards with newText.

Parameters:
oldTextThe text to search for and replace.
newTextThe new text that will appear in place of the old.
startIndexThe index to start replacing from.
virtual void WoopsiUI::WoopsiString::setText ( const WoopsiString text,
const s32  startIndex,
const s32  length 
) [virtual]

Set the text in the string to be a substring of the supplied text.

Parameters:
textWoopsiString containing the new data for this string.
startIndexThe starting point of the substring.
lengthThe length of the substring.
virtual void WoopsiUI::WoopsiString::setText ( const u32  text) [virtual]

Set the text in the string.

Parameters:
textCharacter to to use as the new data for this string.
virtual void WoopsiUI::WoopsiString::setText ( const char *  text) [virtual]

Set the text in the string.

Parameters:
textChar array to use as the new data for this string.
virtual void WoopsiUI::WoopsiString::setText ( const WoopsiString text) [virtual]

Set the text in the string.

Parameters:
textWoopsiString containing the new data for this string.
void WoopsiUI::WoopsiString::split ( const WoopsiString separator,
WoopsiArray< WoopsiString > &  result 
) const

Splits the string into substrings divided by the supplied separator. The substrings will be placed in the result WoopsiArray.

Parameters:
separatorString used to divide this string.
resultWill be populated with the subsections of the divided string.
void WoopsiUI::WoopsiString::split ( const WoopsiString separator,
bool  allowEmptyEntries,
WoopsiArray< WoopsiString > &  result 
) const

Splits the string into substrings divided by the supplied separator. The substrings will be placed in the result WoopsiArray.

Parameters:
separatorString used to divide this string.
allowEmptyEntriesIf set to false, any empty substrings produced by the dividing process will not be added to the result array.
resultWill be populated with the subsections of the divided string.
WoopsiString WoopsiUI::WoopsiString::subString ( s32  startIndex,
s32  length 
) const

Get a substring from this string.

Parameters:
startIndexThe starting point of the substring.
lengthThe length of the substring.
Returns:
A new WoopsiString object containing the substring.
WoopsiString WoopsiUI::WoopsiString::subString ( s32  startIndex) const

Get a substring from this string.

Parameters:
startIndexThe starting point of the substring.
Returns:
A new WoopsiString object containing the substring.

Member Data Documentation

char* WoopsiUI::WoopsiString::_text [protected]

Raw char array data


The documentation for this class was generated from the following file:
 All Classes Functions Variables Enumerations Enumerator