CascadeString Class Reference

an easy to use string class More...

#include <cascade/util/CascadeString.h>

Inheritance diagram for CascadeString:

List of all members.

Public Types
typedef bool(*	LanguageEnumProc )(const CascadeString &lang, const CascadeString &friendlyLang, void *pClientData)
Public Member Functions
	CascadeString ()
	CascadeString (const CascadeString &string)
	CascadeString (const char *pString)
virtual	~CascadeString ()
bool	LoadString (const char *pResourceID)
u32	GetLength () const
u32	GetTerminatedLength () const
u32	CountChars () const
CascadeUnicodeChar	ReadOneUnicodeChar (u32 &ioToken) const
CascadeUnicodeChar	ReadNthUnicodeChar (u32 inIdx) const
void	AppendUnicodeChar (CascadeUnicodeChar inCh)
bool	IsEmpty () const
void	Empty ()
bool	TrimAllocation ()
void	Truncate (u32 nNewLength)
u32	TruncateToByteLen (u32 nNewByteLength, bool bBreakOnChar=true)
bool	IsEqual (const char *pString, bool bCaseSensitive=true) const
s32	Compare (const char *pString, bool bCaseSensitive=true, bool bIgnoreDiacritical=false, u32 nLen=0xFFFFFFFF) const
s32	CompareNBytes (const char *pString, u32 nBytes) const
	*this is greater than pString and 0 if they are equal.
bool	Contains (const char *pString, bool bCaseSensitive=true, bool bIgnoreDiacriticals=false) const
	*this is greater than pString and 0 if they are equal.
bool	ContainsBytes (const char *pString) const
void	ToLower (bool bStripDiacriticals=false)
void	ToUpper (bool bStripDiacriticals=false)
void	StripDiacriticals ()
	operator const char * () const
const CascadeString &	operator= (const char *pString)
const CascadeString &	operator= (const CascadeString &string)
const CascadeString &	operator+= (const char *pString)
const CascadeString &	operator+= (char ch)
char	operator[] (u32 nIndex)
Static Public Member Functions
static bool	SetSystemLanguage (const char *pLanguage)
	Sets the default system-wide natural language to pLang.
static bool	GetSystemLanguage (char *pLanguageToSet, u32 nBuffLen)
	Fills pLanguageToSet with the value of the default system-wide natural language.
static bool	EnumerateStringResourceLanguages (class CascadeStream &stream, LanguageEnumProc callback, void *pClientData)
static bool	LoadStringResources (class CascadeStream &stream, const char *pLang=NULL, bool bClearFirst=true)
static void	ClearStringResources ()
static bool	AddStringResource (const CascadeString &resourceID, const CascadeString &string)
static bool	RemoveStringResource (const CascadeString &resourceID)
static CascadeUnicodeChar	UnicodeCharToUpper (CascadeUnicodeChar inChar)
static CascadeUnicodeChar	UnicodeCharToLower (CascadeUnicodeChar inChar)
static CascadeUnicodeChar	UnicodeCharStripDiacritical (CascadeUnicodeChar inChar)
static bool	UnicodeCharIsAlpha (CascadeUnicodeChar inChar)
static bool	UnicodeCharIsDigit (CascadeUnicodeChar inChar)

---

Detailed Description

an easy to use string class

Skip the description

CascadeString provides easy to use object-based string operations, including copy, append, truncate, comparison. Memory management when copying, appending, etc. is handled automatically.

---

class CascadeString

---

Member Typedef Documentation

typedef bool(* CascadeString::LanguageEnumProc)(const CascadeString &lang, const CascadeString &friendlyLang, void *pClientData)

---

Constructor & Destructor Documentation

CascadeString::CascadeString (   )

default constructor Creates an empty string

CascadeString::CascadeString (  const CascadeString &  string  )

copy constructor Initializes this string as a copy of the supplied CascadeString object Parameters: string  the CascadeString to copy

CascadeString::CascadeString (  const char *  pString  )

parameterized constructor Initializes the string with a copy of the char* passed in as an argument. Parameters: pString  the char* to copy

virtual CascadeString::~CascadeString (   )  [virtual]

destructor Frees any memory allocated for this string

---

Member Function Documentation

static bool CascadeString::AddStringResource (  const CascadeString &  resourceID, const CascadeString &  string )  [static]

programatically adds a string resource Programatically adds a string resource Parameters: resourceID  the ID of the resource string  the string Returns: whether or not the string was successfully added

void CascadeString::AppendUnicodeChar (  CascadeUnicodeChar  inCh  )

appends 32-bit Unicode character to the string (in UTF-8 format) Appends the supplied 32-bit Unicode character to the string as UTF-8 Parameters: inCh  the 32-bit Unicode character to append

static void CascadeString::ClearStringResources (   )  [static]

clears the set of loaded string resources Clears the set of loaded string resources. See also: LoadStringResources()

s32 CascadeString::Compare (  const char *  pString, bool  bCaseSensitive = true, bool  bIgnoreDiacritical = false, u32  nLen = 0xFFFFFFFF )  const

compare this string with another Compares the supplied ASCII or UTF-8 c string or CascadeString with this one, optionally ignoring case and/or diacritical, and optionally limiting the length of the comparison. Parameters: pString  the c string or CascadeString to compare against bCaseSensitive  optional parameter, true by default. If true, do a case-sensitive comparison (valid for characters in the Latin-1 character set). Otherwise, ignore case. bIgnoreDiacritical  optional parameter, false by default. If true, Latin-1 characters with accents or other diacriticals are compared as if they did not have the diacritical. nLen  optional parameter, 0xFFFFFFFF by default. Set this to any non-zero number to limit the comparison of the strings to that many characters (like strncmp, except treats multi-byte utf-8 characters as single characters) Returns: < 0 if *this is less than pString, > 0 if

s32 CascadeString::CompareNBytes (  const char *  pString, u32  nBytes )  const

*this is greater than pString and 0 if they are equal. compare this string with another, with a length limit Compares the supplied c string or CascadeString with this one, optionally ignoring case. Only the first nBytes bytes are compared. Unlike Compare(), this function is not UTF-8 aware, and does not obey the localizable sort order string. Use this where rapid comparison of ASCII strings is needed (it is basically strncmp). Pass 0xFFFFFFFF in nBytes to compare whole strings like strcmp. Parameters: pString  the c string or CascadeString to compare against nBytes  the number of bytes to compare. Returns: < 0 if *this is less than pString, > 0 if

bool CascadeString::Contains (  const char *  pString, bool  bCaseSensitive = true, bool  bIgnoreDiacriticals = false )  const

*this is greater than pString and 0 if they are equal. test for containment Tests to see if the supplied c string or CascadeString is contained within this one, optionally ignoring case and optionally ignoring diacritical marks. Parameters: pString  the c string or CascadeString to test bCaseSensitive  optional parameter, true by default. If true, do a case-sensitive test. Otherwise, ignore case. bIgnoreDiacriticals  optional parameter, false by default. If true, characters are compared as though they had no diacritical marks (has the same limitations as UnicodeCharStripDiacritical()). Returns: true if the string is contained, or false if not. Returns false if either string is empty.

bool CascadeString::ContainsBytes (  const char *  pString  )  const

test for containment Tests to see if the supplied c string or CascadeString is contained within this one, in byte-wise fashion (no UTF-8 or case consideration); Parameters: pString  the c string or CascadeString to test Returns: true if the string is contained, or false if not. Returns false if either string is empty.

u32 CascadeString::CountChars (   )  const

returns the number of utf-8 characters in the string returns the number of utf-8 characters in the string Returns: the number of utf-8 characters in the string

void CascadeString::Empty (   )

empties the string

static bool CascadeString::EnumerateStringResourceLanguages (  class CascadeStream &  stream, LanguageEnumProc  callback, void *  pClientData )  [static]

enumerates languages in a string resource file Enumerates the languages in a string resource file. In your callback, lang is the language specifier (for use in LoadStringResources) and friendlyLang is the localized name of the language for display to the end user. Return false in your enumeration callback to stop enumeration. Returns true if no errors and enumeration not stopped.

u32 CascadeString::GetLength (   )  const [inline]

returns the length of the string Returns the length of the string (like strlen) Returns: the length of the string, excluding terminator

static bool CascadeString::GetSystemLanguage (  char *  pLanguageToSet, u32  nBuffLen )  [static]

Fills pLanguageToSet with the value of the default system-wide natural language.

u32 CascadeString::GetTerminatedLength (   )  const [inline]

returns the length of the string, with terminator Returns the length of the string, including terminating null Returns: the length of the string, including termination

bool CascadeString::IsEmpty (   )  const [inline]

determines whether or not the string is empty

bool CascadeString::IsEqual (  const char *  pString, bool  bCaseSensitive = true )  const [inline]

tests two strings for equality IsEqual tests two strings for equality, optional ignoring case. Parameters: pString  the string to test for equality (either a c string or CascadeString) bCaseSensitive  optional parameter, true by default. If true, do a case-sensitive comparison. Otherwise, ignore case. Returns: true if the strings match, or false if not

bool CascadeString::LoadString (  const char *  pResourceID  )

loads a resource string into this CascadeString Loads this CascadeString with a copy of the resource string identified by the resource string ID passed in. Your program must call LoadStringResources() before using LoadString(). Parameters: pResourceID  the ascii ID of the string to load Returns: whether or not the the string was loaded (pResourceID refers to a known resource string) See also: LoadStringResources() About String Resources

static bool CascadeString::LoadStringResources (  class CascadeStream &  stream, const char *  pLang = NULL, bool  bClearFirst = true )  [static]

loads a set of string resources Loads a set of string resources from a stream. The stream must provide data in the Roku string resource file format. Strings for the default language (English) are loaded unless specified explicitly with the pLang parameter. When bClearFirst is true, the current set of string resources is cleared before loading. When bClearFirst is false, multiple subsequent calls to LoadStringResources() [on different resource files] will have the following effect: Strings with new resource ids will be added to (expand) the pool of string resources. New strings with resource ids that already exist will replace the existing strings Parameters: stream  the stream to get the string resources from. pLang  the language of the resources to load (defaults to English). bClearFirst  whether or not the current set of string resources should be cleared before loading Returns: whether or not string resources were added See also: ClearStringResources() About String Resources Note: Currently LoadStringResources() must only be called within your main Currently "eng" is the hard-coded backup language that will be used when "eng" strings exist while your requested language strings don't. This behavior should be paramaterized in the future. app thread and before any threads call LoadString()

CascadeString::operator const char * (   )  const [inline]

the magic casting operator operator const char *() const is a casting operator that turns a CascadeString into a const char * This casting operator always returns a non-null value so if this->GetLength() == 0, then the casting operator will return a non-null empty string. Note: DANGER: The const char* returned is NOT VALID after destruction of the parent object. This means that you MUST NOT use this operator on temporary objects, like this: char *foo = (const char*) bar->FunctionThatReturnsACascadeString(); ::strcpy( baz, foo ); A CascadeString returned from a function this way vanishes as soon as the cast operator is called, so the assigned pointer is now pointing to freed memory. the contents of the returned char* are subject to change if the parent object is manipulated. If you want the contents of the string at a point in time, not subject to change, then copy the result, or copy the CascadeString object. DANGER: The const char* returned may BECOME INVALID after certain operations performed on the parent object. For example, appending data may cause the internal representation to be reallocated in a new location, leaving the returned value of this function pointing to freed memory. Due to the above warnings, this operator should be used with great caution and thorough understanding of the issues discussed. It would be prudent to never assign a pointer variable to the result of this function (as demonstrated in the example above). Returns: the CascadeString as a const char *

const CascadeString& CascadeString::operator+= (  char  ch  )

append operator Appends the supplied character to this string

const CascadeString& CascadeString::operator+= (  const char *  pString  )

append operator Appends the supplied char* to this string

const CascadeString& CascadeString::operator= (  const CascadeString &  string  )  [inline]

assignment operator Makes this string a copy of the supplied string

const CascadeString& CascadeString::operator= (  const char *  pString  )

assignment operator Makes this string a copy of the supplied char*

char CascadeString::operator[] (  u32  nIndex  )  [inline]

array index operator Returns the character at index nIndex in the string. If the index is out of range, returns \'\0\' Note: This function returns a SINGLE character. You may not take the address of that character to read the remainder of the string as you would with a normal char *. Parameters: nIndex  the index of the desired character Returns: the character at index nIndex, or \'\0\' if nIndex out of range

CascadeUnicodeChar CascadeString::ReadNthUnicodeChar (  u32  inIdx  )  const

returns the nth 32-bit Unicode character from the string Returns the nth 32-bit Unicode character from the string. For higher-performance iteration from the start of the string, see ReadOneUnicodeChar(). Parameters: inidx  the index (starting from 0) of the desired character. Returns: The 32-bit Unicode code point of a single character at the position specified by inIdx or zero if the index is too large.

CascadeUnicodeChar CascadeString::ReadOneUnicodeChar (  u32 &  ioToken  )  const

returns a single 32-bit Unicode character from the string Returns a single 32-bit Unicode character from the string. Token parameter allows getting subsequent characters Parameters: ioToken  Set to zero (0) for first call to get the first character. Token value will be modified by the call. Pass the modified token in on subsequent calls to get subsequent characters quickly. DO NOT use a non-zero token if the string has been modified since it was returned. For direct access to the nth character, see ReadNthUnicodeChar() Returns: The 32-bit Unicode code point of a single character, or zero if there are no more characters in the string.

static bool CascadeString::RemoveStringResource (  const CascadeString &  resourceID  )  [static]

programatically removes a string resource Programatically removes a string resource Parameters: resourceID  the ID of the resource to remove Returns: whether or not the resource was removed

static bool CascadeString::SetSystemLanguage (  const char *  pLanguage  )  [static]

Sets the default system-wide natural language to pLang.

void CascadeString::StripDiacriticals (   )

remove diacritical markings from this string Removes diacritical markings from the characters in the string. Useful for comparisons or the like. Shares the limitations of UnicodeCharStripDiacritical

void CascadeString::ToLower (  bool  bStripDiacriticals = false  )

make this string lowercase Makes this string lowercase. Useful for comparisons, etc. Parameters: bStripDiacriticals  optional parameter, defaults to false. If true, diacritical marks are removed from characters before case conversion (has the same limitations as UnicodeCharStripDiacritical())

void CascadeString::ToUpper (  bool  bStripDiacriticals = false  )

make this string uppercase Makes this string uppercase. Useful for comparisons, etc. Parameters: bStripDiacriticals  optional parameter, defaults to false. If true, diacritical marks are removed from characters before case conversion (has the same limitations as UnicodeCharStripDiacritical())

bool CascadeString::TrimAllocation (   )

trims the allocated memory associated with this CascadeString Causes the memory allocated for the string to be reallocated to exactly fit the current string. Returns: true if successful, false if failure. May fail if memory may not be reallocated.

void CascadeString::Truncate (  u32  nNewLength  )

truncate to length Truncate the string to the supplied length, leaving the result null-terminated. If the string is already shorter than this length, this has no effect. Parameters: nNewLength  the desired new length of the string, excluding terminator

u32 CascadeString::TruncateToByteLen (  u32  nNewByteLength, bool  bBreakOnChar = true )

truncate to length Truncate the string to the supplied length in bytes (not including the null terminator), leaving the result null-terminated. The bBreakOnChar argument determines whether the function will look for a UTF-8 character boundary on which to break. If your string is ASCII or UTF-8, you should pass true. If you're using another encoding, pass false and be aware that the truncation may happen in the middle of a multi-byte sequence. If the string is already shorter than this length, this has no effect. Example usage: you need to copy a string into a fixed 64-byte field in a struct. Call myString.TruncateToByteLen( 63 ) to trim it to fit, including the NULL. Parameters: nNewByteLength  the desired new length of the string, excluding terminator, expressed in bytes. bBreakOnChar  optional parameter determines whether to look for UTF-8 character boundaries to break the string, potentially resulting in a final truncated string that is shorter than the requested bytes. True by default. Returns: the new length of the string in bytes, excluding terminator

static bool CascadeString::UnicodeCharIsAlpha (  CascadeUnicodeChar  inChar  )  [static]

tests Unicode character for alpha Tests Unicode character for alpha. Valid only for Latin-1 Parameters: the  32-bit Unicode character to test Returns: true if the supplied character is in the alpha range of the ASCII or Latin-1 sets. False otherwise.

static bool CascadeString::UnicodeCharIsDigit (  CascadeUnicodeChar  inChar  )  [static]

tests Unicode character for representing a numeric digit Tests Unicode character for representing a numeric digit . Valid only for Latin-1 Parameters: the  32-bit Unicode character to set Returns: true if the supplied character is one of the digits 0-9. False otherwise.

static CascadeUnicodeChar CascadeString::UnicodeCharStripDiacritical (  CascadeUnicodeChar  inChar  )  [static]

removes diacritical mark from input character Removes diacritical mark from input character. If the supplied character is within the Latin-1 character set, and is a character with a diacritical (e.g. e with an acute accent) then the corresponding un-accented character is returned. Characters that do not have unaccented versions are returned unmodified. Parameters: inChar  the 32-bit Unicode character to convert Returns: a 32-bit Unicode character which is either the supplied character minus any diacritical, or the supplied character if no corresponding unmodified character exists.

static CascadeUnicodeChar CascadeString::UnicodeCharToLower (  CascadeUnicodeChar  inChar  )  [static]

converts a Unicode character to lower case Converts a Unicode character to lower case. In the current revision, this is valid for characters witin the Latin-1 character set ONLY. Parameters: inChar  The Unicode character to make lowercase Returns: The lowercase version of the character, if the character was within the Latin-1 set and if it has an lowercase version, or the unmodified character if not.

static CascadeUnicodeChar CascadeString::UnicodeCharToUpper (  CascadeUnicodeChar  inChar  )  [static]

converts a Unicode character to upper case Converts a Unicode character to upper case. In the current revision, this is valid for characters witin the Latin-1 character set ONLY. Parameters: inChar  The Unicode character to make uppercase Returns: The uppercase version of the character, if the character was within the Latin-1 set and if it has an uppercase version, or the unmodified character if not.

---

The documentation for this class was generated from the following file:

• CascadeString.h

---