UnicodeString Class Reference

#include <UnicodeString.h>

Public Types
enum	{ MAX_FORMAT_BUF_LEN = 2048 , MAX_LEN = 32767 }

Public Member Functions
	UnicodeString ()
	UnicodeString (const UnicodeString &stringSrc)
	UnicodeString (const WideChar *s)
	~UnicodeString ()
int	getLength () const
Bool	isEmpty () const
void	clear ()
WideChar	getCharAt (int index) const
const WideChar *	str () const
WideChar *	getBufferForRead (Int len)
void	set (const UnicodeString &stringSrc)
void	set (const WideChar *s)
void	translate (const AsciiString &stringSrc)
void	concat (const UnicodeString &stringSrc)
void	concat (const WideChar *s)
void	concat (const WideChar c)
void	trim (void)
void	removeLastChar ()
void	format (UnicodeString format,...)
void	format (const WideChar *format,...)
void	format_va (const UnicodeString &format, va_list args)
void	format_va (const WideChar *format, va_list args)
int	compare (const UnicodeString &stringSrc) const
int	compare (const WideChar *s) const
int	compareNoCase (const UnicodeString &stringSrc) const
int	compareNoCase (const WideChar *s) const
Bool	nextToken (UnicodeString *token, UnicodeString delimiters=UnicodeString::TheEmptyString)
UnicodeString &	operator= (const UnicodeString &stringSrc)
	the same as set()
UnicodeString &	operator= (const WideChar *s)
	the same as set()

Static Public Attributes
static UnicodeString	TheEmptyString

Protected Member Functions
WideChar *	peek () const
void	releaseBuffer ()
void	ensureUniqueBufferOfSize (int numCharsNeeded, Bool preserveData, const WideChar *strToCpy, const WideChar *strToCat)

Protected Attributes
UnicodeStringData *	m_data

Detailed Description

UnicodeString is the fundamental double-byte string type used in the Generals code base, and should be preferred over all other string constructions (e.g., array of WideChar, STL string<>, WWVegas StringClass, etc.)

Of course, other string setups may be used when necessary or appropriate!

UnicodeString is modeled after the MFC CString class, with some minor syntactic differences to keep in line with our coding conventions.

Basically, UnicodeString allows you to treat a string as an intrinsic type, rather analogous to 'int' – when passed by value, a new string is created, and modifying the new string doesn't modify the original. This is done fairly efficiently, so that no new memory allocation is done unless the string is actually modified.

Naturally, UnicodeString handles all memory issues, so there's no need to do anything to free memory... just allow the UnicodeString's destructor to run.

UnicodeStrings are suitable for use as automatic, member, or static variables.

Definition at line 84 of file UnicodeString.h.

Member Enumeration Documentation

anonymous enum

anonymous enum

Enumerator
MAX_FORMAT_BUF_LEN	max total len of string created by format/format_va
MAX_LEN	max total len of any UnicodeString, in chars

Definition at line 117 of file UnicodeString.h.

Constructor & Destructor Documentation

UnicodeString() [1/3]

UnicodeString::UnicodeString ( )

inline

Default constructor – construct a new, empty UnicodeString.

Definition at line 303 of file UnicodeString.h.

UnicodeString() [2/3]

UnicodeString::UnicodeString

(

const UnicodeString &

stringSrc

)

Copy constructor – make this UnicodeString identical to the other UnicodeString. (This is actually quite efficient, because they will simply share the same string and increment the refcount.)

Definition at line 71 of file UnicodeString.cpp.

UnicodeString() [3/3]

UnicodeString::UnicodeString ( const WideChar * s )

explicit

Constructor – from a literal string. Constructs an UnicodeString with the given string. Note that a copy of the string is made; the input ptr is not saved. Note also that this is declared 'explicit' to avoid implicit conversions from const-WideChar-* (e.g., as input arguments).

Definition at line 144 of file UnicodeString.cpp.

~UnicodeString()

UnicodeString::~UnicodeString ( )

inline

Destructor. Not too exciting... clean up the works and such.

Definition at line 309 of file UnicodeString.h.

Member Function Documentation

clear()

void UnicodeString::clear ( )

inline

Make the string empty. Equivalent to (str = "") but slightly more efficient.

Definition at line 330 of file UnicodeString.h.

compare() [1/2]

int UnicodeString::compare ( const UnicodeString & stringSrc ) const

inline

Conceptually identical to wsccmp().

Definition at line 390 of file UnicodeString.h.

compare() [2/2]

int UnicodeString::compare ( const WideChar * s ) const

inline

Conceptually identical to wsccmp().

Definition at line 397 of file UnicodeString.h.

compareNoCase() [1/2]

int UnicodeString::compareNoCase ( const UnicodeString & stringSrc ) const

inline

Conceptually identical to _wcsicmp().

Definition at line 404 of file UnicodeString.h.

compareNoCase() [2/2]

int UnicodeString::compareNoCase ( const WideChar * s ) const

inline

Conceptually identical to _wcsicmp().

Definition at line 411 of file UnicodeString.h.

concat() [1/3]

void UnicodeString::concat ( const UnicodeString & stringSrc )

inline

Concatenate the given string onto self.

Definition at line 372 of file UnicodeString.h.

concat() [2/3]

void UnicodeString::concat

(

const WideChar *

s

)

Concatenate the given string onto self.

Definition at line 212 of file UnicodeString.cpp.

concat() [3/3]

void UnicodeString::concat ( const WideChar c )

inline

Concatenate the given character onto self.

this can probably be made more efficient, if necessary

Definition at line 380 of file UnicodeString.h.

ensureUniqueBufferOfSize()

void UnicodeString::ensureUniqueBufferOfSize ( int numCharsNeeded, Bool preserveData, const WideChar * strToCpy, const WideChar * strToCat )

protected

Definition at line 80 of file UnicodeString.cpp.

format() [1/2]

void UnicodeString::format	(	const WideChar *	format,
			... )

Definition at line 297 of file UnicodeString.cpp.

format() [2/2]

void UnicodeString::format	(	UnicodeString	format,
			... )

Analogous to sprintf() – this formats a string according to the given sprintf-style format string (and the variable argument list) and stores the result in self.

Definition at line 286 of file UnicodeString.cpp.

format_va() [1/2]

void UnicodeString::format_va	(	const UnicodeString &	format,
		va_list	args )

Identical to format(), but takes a va_list rather than a variable argument list. (i.e., analogous to vsprintf.)

Definition at line 308 of file UnicodeString.cpp.

format_va() [2/2]

void UnicodeString::format_va	(	const WideChar *	format,
		va_list	args )

Definition at line 319 of file UnicodeString.cpp.

getBufferForRead()

WideChar * UnicodeString::getBufferForRead

(

Int

len

)

Makes sure there is room for a string of len+1 characters, and returns a pointer to the string buffer. This ensures that the string buffer is NOT shared. This is intended for the file reader, that is reading new strings in from a file. jba.

Definition at line 190 of file UnicodeString.cpp.

getCharAt()

WideChar UnicodeString::getCharAt ( int index ) const

inline

Return the character and the given (zero-based) index into the string. No range checking is done (except in debug mode).

Definition at line 338 of file UnicodeString.h.

getLength()

int UnicodeString::getLength ( ) const

inline

Return the length, in characters (not bytes!), of the string.

Definition at line 316 of file UnicodeString.h.

isEmpty()

Bool UnicodeString::isEmpty ( ) const

inline

Return true iff the length of the string is zero. Equivalent to (getLength() == 0) but slightly more efficient.

Definition at line 323 of file UnicodeString.h.

nextToken()

Bool UnicodeString::nextToken	(	UnicodeString *	token,
		UnicodeString	delimiters = UnicodeString::TheEmptyString )

conceptually similar to strtok():

extract the next whitespace-delimited token from the front of 'this' and copy it into 'token', returning true if a nonempty token was found. (note that this modifies 'this' as well, stripping the token off!)

Definition at line 330 of file UnicodeString.cpp.

operator=() [1/2]

UnicodeString & UnicodeString::operator= ( const UnicodeString & stringSrc )

inline

the same as set()

Definition at line 354 of file UnicodeString.h.

operator=() [2/2]

UnicodeString & UnicodeString::operator= ( const WideChar * s )

inline

the same as set()

Definition at line 363 of file UnicodeString.h.

peek()

WideChar * UnicodeString::peek ( ) const

inlineprotected

Definition at line 295 of file UnicodeString.h.

releaseBuffer()

void UnicodeString::releaseBuffer ( )

protected

Definition at line 128 of file UnicodeString.cpp.

removeLastChar()

void UnicodeString::removeLastChar

(

)

Remove the final character in the string. If the string is empty, do nothing. (This is a rather dorky method, but used a lot in text editing, thus its presence here.)

Definition at line 270 of file UnicodeString.cpp.

set() [1/2]

void UnicodeString::set

(

const UnicodeString &

stringSrc

)

Replace the contents of self with the given string. (This is actually quite efficient, because they will simply share the same string and increment the refcount.)

Definition at line 155 of file UnicodeString.cpp.

set() [2/2]

void UnicodeString::set

(

const WideChar *

s

)

Replace the contents of self with the given string. Note that a copy of the string is made; the input ptr is not saved.

Definition at line 171 of file UnicodeString.cpp.

str()

const WideChar * UnicodeString::str ( ) const

inline

Return a pointer to the (null-terminated) string. Note that this is a const pointer: do NOT change this! It is imperative that it be impossible (or at least, really difficuly) for someone to change our private data, since it might be shared amongst other UnicodeStrings.

Definition at line 346 of file UnicodeString.h.

translate()

void UnicodeString::translate

(

const AsciiString &

stringSrc

)

replace contents of self with the given string. Note the nomenclature is translate rather than set; this is because not all single-byte strings translate one-for-one into UnicodeStrings, so some data manipulation may be necessary, and the resulting strings may not be equivalent.

Todo

srj put in a real translation here; this will only work for 7-bit ascii

Definition at line 200 of file UnicodeString.cpp.

trim()

void UnicodeString::trim

(

void

)

Remove leading and trailing whitespace from the string.

Definition at line 231 of file UnicodeString.cpp.

Member Data Documentation

m_data

UnicodeStringData* UnicodeString::m_data

protected

Definition at line 109 of file UnicodeString.h.

TheEmptyString

UnicodeString UnicodeString::TheEmptyString

static

This is a convenient global used to indicate the empty string, so we don't need to construct temporaries for such a common thing.

Definition at line 129 of file UnicodeString.h.

---

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

• Code/GameEngine/Include/Common/UnicodeString.h
• Code/GameEngine/Source/Common/System/UnicodeString.cpp