Main Page   Modules   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members  

TString Class Reference

Yet another string class. More...

#include <TString.h>

List of all members.

Public Methods

bool set (PCSTR)
bool set (PCWSTR)
bool set (const WCHAR)
bool set (const CHAR)
bool set (const int)
int getBufferSize () const
int getLength () const
PCTSTR get () const
 operator PCTSTR () const
 Overloaded static cast operator. More...

TCHAR operator[] (const int) const
const TString & operator= (const TString &)
const TString & operator= (PCSTR)
const TString & operator= (PCWSTR)
const TString & operator= (const WCHAR)
const TString & operator= (const CHAR)
bool operator! () const
 clear ()
 TString (const WCHAR)
 TString (const CHAR)
 TString (const int)
 TString (PCSTR)
 TString (PCWSTR)
 TString (const TString &)
 TString ()
virtual ~TString ()
const TString & operator+= (const TString &)
const TString & operator+= (PCSTR)
const TString & operator+= (PCWSTR)
const TString & operator+= (const WCHAR)
const TString & operator+= (const CHAR)

Private Methods

int stringCopy (PCSTR, const int=-1)
int stringCopy (PCWSTR, const int=-1)
int memoryAlloc (PCSTR, const bool=true)
int memoryAlloc (PCWSTR, const bool=true)
bool alloc (const int)
 memoryDealloc ()

Private Attributes

PTSTR string
 The actual string.

int bufferLength
 string length + null terminator.


Static Private Attributes

PTSTR EMPTYSTRING = TEXT("")

Friends

TString operator+ (const TString &, const TString &)
TString operator+ (const TString &, PCSTR)
TString operator+ (const TString &, PCWSTR)
TString operator+ (PCSTR, const TString &)
TString operator+ (PCWSTR, const TString &)
TString operator+ (const TString &, const WCHAR)
TString operator+ (const TString &, const CHAR)
TString operator+ (const WCHAR, const TString &)
TString operator+ (const CHAR, const TString &)

Detailed Description

TString is designed to allow the use of both ANSI and Unicode Strings. It can be compiled in either an ANSI or Unicode environment and converts as necessary to the native string format. The =, + and += operators are overloaded to assign, concatenate and append.

Definition at line 21 of file TString.h.

Constructor & Destructor Documentation

TString::TString (  const WCHAR    unicodeChar ) 
 

ANSI Character constructor

Definition at line 79 of file TString.cpp.

References bufferLength, EMPTYSTRING, set(), and string. 

00080 {
00081     bufferLength = 1;
00082     string = EMPTYSTRING;
00083     set(unicodeChar);
00084 }

TString::TString (  const CHAR    ansiChar ) 
 

Unicode Character constructor

Definition at line 89 of file TString.cpp.

References bufferLength, EMPTYSTRING, set(), and string. 

00090 {
00091     bufferLength = 1;
00092     string = EMPTYSTRING;
00093     set(ansiChar);
00094 }

TString::TString (  const int    integer )  [explicit]
 

Expilict integer constructor /todo remove construtor and replace capability with a printf style function

Definition at line 100 of file TString.cpp.

References bufferLength, EMPTYSTRING, set(), and string. 

00101 {
00102     bufferLength = 1;
00103     string = EMPTYSTRING;
00104     set(integer);
00105 }

TString::TString (  PCSTR    ansiString ) 
 

ANSI String constructor

Definition at line 59 of file TString.cpp.

References bufferLength, EMPTYSTRING, set(), and string. 

00060 {
00061     bufferLength = 1;
00062     string = EMPTYSTRING;
00063     set(ansiString);
00064 }

TString::TString (  PCWSTR    unicodeString ) 
 

Unicode String constructor

Definition at line 69 of file TString.cpp.

References bufferLength, EMPTYSTRING, set(), and string. 

00070 {
00071     bufferLength = 1;
00072     string = EMPTYSTRING;
00073     set(unicodeString);
00074 }

TString::TString (  const TString &    copy ) 
 

Copy constructor

Definition at line 49 of file TString.cpp.

References bufferLength, EMPTYSTRING, get(), set(), and string. 

00050 {
00051     bufferLength = 1;
00052     string = EMPTYSTRING;
00053     set(copy.get());
00054 }

TString::TString (    ) 
 

Default constructor creates an empty string

Definition at line 40 of file TString.cpp.

References bufferLength, EMPTYSTRING, and string.

Referenced by operator+=(). 

00041 {
00042     bufferLength = 1;
00043     string = EMPTYSTRING;
00044 }

TString::~TString (    )  [virtual]
 

Object Destructor

Definition at line 111 of file TString.cpp.

References memoryDealloc(). 

00112 {
00113     memoryDealloc();
00114 }

Member Function Documentation

bool TString::alloc (  const int    length )  [inline, private]
 

The Actual memory allocation function. If you wish to use heap allocation functions then only this and memoryDealloc() require alteration

Definition at line 567 of file TString.cpp.

References bufferLength, EMPTYSTRING, string, and TSTRING_BUFFERSIZE.

Referenced by memoryAlloc(), operator+(), operator+=(), and set(). 

00568 {
00569     // Allocate memory
00570     string = new TCHAR[TSTRING_BUFFERSIZE(length)];
00571     // Check Allocation
00572     if ( string == NULL ){
00573         bufferLength = 1;
00574         string = EMPTYSTRING;
00575         return false;
00576     } else {
00577         bufferLength = length;
00578         return true;
00579     }
00580 }

TString::clear (    ) 
 

Release the Strings buffer and set it to equal an empty string

Definition at line 446 of file TString.cpp.

References memoryDealloc().

Referenced by set(). 

00447 {
00448     memoryDealloc();
00449 }

PCTSTR TString::get (    )  const
 

Gets a constant pointer to the String. Unicode if compiled with UNICODE, ANSI otherwise.

Returns:
PCTSTR : Constant pointer to a native string

Definition at line 440 of file TString.cpp.

References string.

Referenced by operator PCTSTR(), operator=(), and TString(). 

00441 {
00442     return string;
00443 }

int TString::getBufferSize (    )  const
 

Return the size (in bytes) of the buffer required to hold the current string

Definition at line 452 of file TString.cpp.

References bufferLength, and TSTRING_BUFFERSIZE. 

00453 {
00454     return TSTRING_BUFFERSIZE(bufferLength);
00455 }

int TString::getLength (    )  const
 

Return the length of the String excluding the terminating character

Definition at line 458 of file TString.cpp.

References bufferLength. 

00459 {
00460     return bufferLength - 1;
00461 }

int TString::memoryAlloc (  PCWSTR    unicodeString,
const bool    allocate = true
)  [inline, private]
 

Allocate the memory required to store the string. Along with it's overloaded version this is the only point that requires modification to change the way TString reallocates memory each time its contents is changed.

Parameters:
ansiString  : The terminated Unicode string
allocate  : if false then don't perform the alloaction
Returns:
int :
0 if unable to calculate length
| -1 if unable to alloc
| the buffer size

Definition at line 525 of file TString.cpp.

References alloc(), bufferLength, memoryDealloc(), TSTRING_BUFFERLENGTHW, and TSTRING_BUFFERSIZE. 

00526 {
00527     int length;
00528 
00529 #ifdef UNICODE
00530 
00531     length =  TSTRING_BUFFERLENGTHW(unicodeString);
00532 
00533     if( !allocate )
00534         return TSTRING_BUFFERSIZE(length);
00535 
00536 #else
00537 
00538     length = WideCharToMultiByte(
00539             CP_ACP,         // code page
00540             0,              // performance and mapping flags
00541             unicodeString,  // wide-character string
00542             -1,             // calculate number of chars in string
00543             NULL,           // buffer for new string (not used yet)
00544             0,              // return size of required buffer in bytes
00545             NULL,           // default for unmappable chars
00546             NULL);          // set when default char used
00547 
00548     if( !allocate || length == 0)
00549         return TSTRING_BUFFERSIZE(length);
00550 
00551 #endif    
00552 
00553     memoryDealloc();
00554 
00555     if( alloc(length) )
00556         return TSTRING_BUFFERSIZE(bufferLength);
00557     else 
00558         return -1;
00559 
00560 }

int TString::memoryAlloc (  PCSTR    ansiString,
const bool    allocate = true
)  [inline, private]
 

Allocate the memory required to store the string. Along with it's overloaded version this is the only point that requires modification to change the way TString reallocates memory each time its contents is changed.

Parameters:
ansiString  : The terminated ANSI string
allocate  : if false then don't perform the alloaction
Returns:
int :
0 if unable to calculate length
| -1 if unable to alloc
| the buffer size

Definition at line 477 of file TString.cpp.

References alloc(), bufferLength, memoryDealloc(), and TSTRING_BUFFERSIZE.

Referenced by set(). 

00478 {
00479     int length;
00480 
00481 #ifdef UNICODE
00482 
00483     // Calculate string length
00484     length = MultiByteToWideChar(
00485             CP_ACP,     // code page
00486             0,          // character-type options
00487             ansiString, // string to map
00488             -1,         // calculate number characters in string (inc terminator)
00489             NULL,       // wide-character buffer (not used yet)
00490             0);         // return size of required buffer in bytes
00491 
00492     if( !allocate || length == 0)
00493         return TSTRING_BUFFERSIZE(length);
00494 
00495 #else
00496 
00497     length = calculateTotalLength(ansiString);
00498 
00499     if( !allocate )
00500         return TSTRING_BUFFERSIZE(length);
00501 
00502 #endif
00503 
00504     memoryDealloc();
00505 
00506     if( alloc(length) )
00507         return TSTRING_BUFFERSIZE(bufferLength);
00508     else 
00509         return -1;
00510 
00511 }

TString::memoryDealloc (    )  [inline, private]
 

The memory deallocation function. Release the memory, and set this to equal the empty string. If you wish to use heap allocation functions then only this and alloc() require alteration.

Definition at line 588 of file TString.cpp.

References bufferLength, EMPTYSTRING, and string.

Referenced by clear(), memoryAlloc(), operator+=(), and ~TString(). 

00589 {
00590     if( string != EMPTYSTRING ){
00591         delete [] string;
00592         string = EMPTYSTRING;
00593         bufferLength = 1;
00594     }
00595 }

TString::operator PCTSTR (    )  const [inline]
 

Allows a TString to be used anywhere a constant String is expected

Definition at line 48 of file TString.h.

References EMPTYSTRING, and get(). 

00048 { return get(); }

bool TString::operator! (    )  const
 

Is not empty operator

Returns:
bool : true if string is empty, false otherwise

Definition at line 324 of file TString.cpp.

References bufferLength. 

00325 {
00326     return bufferLength == 1;
00327 }

const TString & TString::operator+= (  const CHAR    right ) 
 

Overloading of the += operator. Appends the right string to this TString

Definition at line 292 of file TString.cpp.

References TString(). 

00293 {
00294     *this += TString(right);
00295     return *this;
00296 }

const TString & TString::operator+= (  const WCHAR    right ) 
 

Overloading of the += operator. Appends the right string to this TString

Definition at line 286 of file TString.cpp.

References TString(). 

00287 {
00288     *this += TString(right);
00289     return *this;
00290 }

const TString & TString::operator+= (  PCWSTR    right ) 
 

Overloading of the += operator. Appends the right string to this TString

Definition at line 280 of file TString.cpp.

References TString(). 

00281 {
00282     *this += TString(right);
00283     return *this;
00284 }

const TString & TString::operator+= (  PCSTR    right ) 
 

Overloading of the += operator. Appends the right string to this TString

Definition at line 274 of file TString.cpp.

References TString(). 

00275 {
00276     *this += TString(right);
00277     return *this;
00278 }

const TString & TString::operator+= (  const TString &    right ) 
 

Overloading of the += operator. Appends the right string to this TString

Definition at line 247 of file TString.cpp.

References alloc(), bufferLength, memoryDealloc(), string, and stringCopy(). 

00248 {
00249     TString left( *this );
00250 
00251     memoryDealloc();
00252 
00253     const int totalLength = left.bufferLength - 1 + right.bufferLength;
00254 
00255     assert( alloc( totalLength ) );
00256 
00257     assert( stringCopy ( left, left.bufferLength ) == left.bufferLength );
00258 
00259 #ifdef UNICODE
00260 
00261     wcscat( string, right.string );
00262 
00263 #else
00264 
00265     strcat( string, right.string );
00266 
00267 #endif
00268 
00269     return *this;
00270 }

const TString & TString::operator= (  const CHAR    ansiChar ) 
 

ANSI character assignment operator

Definition at line 230 of file TString.cpp.

References set(). 

00231 {
00232     set(ansiChar);
00233     return *this;
00234 }

const TString & TString::operator= (  const WCHAR    unicodeChar ) 
 

Unicode character assignment operator

Definition at line 237 of file TString.cpp.

References set(). 

00238 {
00239     set(unicodeChar);
00240     return *this;
00241 }

const TString & TString::operator= (  PCWSTR    right ) 
 

Unicode assignment operator

Definition at line 216 of file TString.cpp.

References set(), and string. 

00217 {
00218 #ifdef UNICODE
00219     // if native to unicode then it is possible that this is a self assignment 
00220     if(right == string)
00221         return *this;
00222 #endif
00223 
00224     set(right);
00225 
00226     return *this;
00227 }

const TString & TString::operator= (  PCSTR    right ) 
 

ANSI assignment operator

Definition at line 202 of file TString.cpp.

References set(), and string. 

00203 {
00204 #ifndef UNICODE
00205     // if native to ansi then it is possible that this is a self assignment 
00206     if(right == string)
00207         return *this;
00208 #endif
00209 
00210     set(right);
00211 
00212     return *this;
00213 }

const TString & TString::operator= (  const TString &    right ) 
 

Assignment operator

Definition at line 193 of file TString.cpp.

References get(), and set(). 

00194 {
00195     if(&right != this)
00196         set(right.get());
00197 
00198     return *this;
00199 }

TCHAR TString::operator[] (  const int    index )  const
 

Array access operator (doesn't allow modification)

Parameters:
index  : index into the string
Returns:
TCHAR : a native CHARACTER
Exceptions:
EXCEPTION_ARRAY_BOUNDS_EXCEEDED 

Definition at line 310 of file TString.cpp.

References bufferLength, and string. 

00311 {
00312     if( index < 0 || index > bufferLength - 1 )
00313         RaiseException(EXCEPTION_ARRAY_BOUNDS_EXCEEDED, 0, 0, NULL);
00314 
00315     TCHAR rtrn = string[index];
00316     return rtrn;
00317 }

bool TString::set (  const int    integer ) 
 

Sets this TString to a string representation of an integer

Parameters:
integer  : The value to be represented
Returns:
bool : false iff errors encountered
Note:
Functionality should be replaced with a printf style function

Definition at line 419 of file TString.cpp.

References set(). 

00420 {
00421     TCHAR temp[12]; // temp: longest string needed to represent int
00422 
00423 #ifdef UNICODE
00424     swprintf(temp, L"%d", integer);
00425 #else
00426     sprintf(temp, "%d", integer);
00427 #endif 
00428 
00429     return set(temp);
00430 }

bool TString::set (  const CHAR    ansiChar ) 
 

Sets this TString to the given ANSI Character plus a terminating character

Parameters:
ansiChar  : A character
Returns:
bool : false iff errors encountered

Definition at line 384 of file TString.cpp.

References alloc(), string, and stringCopy(). 

00385 {
00386     if( alloc(1+1) ){
00387         *(string + 1)  = TEXT('');
00388         return stringCopy(&ansiChar, 1) == 1;
00389     } else
00390         return false;
00391 }

bool TString::set (  const WCHAR    unicodeChar ) 
 

Sets this TString to the given Unicode Character plus a terminating character

Parameters:
unicodeChar  : A wide character
Returns:
bool : false iff errors encountered

Definition at line 400 of file TString.cpp.

References alloc(), string, and stringCopy(). 

00401 {
00402     if( alloc(1+1) ){
00403         *(string + 1)  = TEXT('');
00404         return stringCopy(&unicodeChar, 1) == 1;
00405     } else
00406         return false;
00407 }

bool TString::set (  PCWSTR    unicodeString ) 
 

Sets this TString to the given Unicode String. If the string is a null pointer the TString is simply emptied

Parameters:
unicodeString  : A constant pointer to a wide character string
Returns:
bool : false iff errors encountered

Definition at line 362 of file TString.cpp.

References clear(), memoryAlloc(), stringCopy(), TSTRING_BUFFERLENGTHW, and TSTRING_BUFFERSIZE. 

00363 {
00364     if( unicodeString == NULL ){
00365         clear();
00366         return true;
00367     }
00368 
00369     int unicodeLength = TSTRING_BUFFERLENGTHW(unicodeString);
00370 
00371     if( memoryAlloc(unicodeString) == TSTRING_BUFFERSIZE(unicodeLength) )
00372         return stringCopy(unicodeString, unicodeLength) == unicodeLength;
00373     else
00374         return false;
00375 }

bool TString::set (  PCSTR    ansiString ) 
 

Sets this TString to the given ANSI String. If the string is a null pointer the TString is simply emptied

Parameters:
ansiString  : A constant pointer to a C style string (i.e. ANSI)
Returns:
bool : false iff errors encountered

Definition at line 339 of file TString.cpp.

References clear(), memoryAlloc(), stringCopy(), TSTRING_BUFFERLENGTHA, and TSTRING_BUFFERSIZE.

Referenced by operator=(), set(), and TString(). 

00340 {
00341     if( ansiString == NULL ){
00342         clear();
00343         return true;
00344     }
00345 
00346     int ansiLength = TSTRING_BUFFERLENGTHA(ansiString);
00347 
00348     if( memoryAlloc(ansiString) == TSTRING_BUFFERSIZE(ansiLength) )
00349         return stringCopy(ansiString, ansiLength) == ansiLength;
00350     else
00351         return false;
00352 }

int TString::stringCopy (  PCWSTR    unicodeString,
const int    length = -1
)  [inline, private]
 

Relies on this buffer being large enough to hold the string

Parameters:
length  : must include terminator if one is to be copied. If 0 length is calculated
Returns:
int : the number of characters copied (including terminator)

Definition at line 634 of file TString.cpp.

References bufferLength, string, TSTRING_BUFFERLENGTHW, and TSTRING_BUFFERSIZE. 

00635 {
00636 #ifdef UNICODE
00637 
00638     int unicodeLength = length;
00639     if( unicodeLength < 0 ){
00640         unicodeLength = TSTRING_BUFFERLENGTHW(unicodeString);
00641     }
00642 
00643     __try{
00644         CopyMemory(string, unicodeString, TSTRING_BUFFERSIZE(unicodeLength));
00645     }
00646     __except( (GetExceptionCode() == EXCEPTION_ACCESS_VIOLATION) 
00647             ? EXCEPTION_EXECUTE_HANDLER : EXCEPTION_CONTINUE_SEARCH) {
00648         return -1;
00649     }
00650     
00651     return unicodeLength;
00652 
00653 #else
00654 
00655     // Convert Unicode to ANSI
00656     return WideCharToMultiByte(CP_ACP,  0, unicodeString, length, string, TSTRING_BUFFERSIZE(bufferLength), NULL, NULL);
00657 
00658 #endif
00659 }

int TString::stringCopy (  PCSTR    ansiString,
const int    length = -1
)  [inline, private]
 

Relies on this buffer being large enough to hold the string

Parameters:
length  : must include terminator if one is to be copied. If 0 length is calculated
Returns:
int : the number of characters copied (including terminator)

Definition at line 602 of file TString.cpp.

References bufferLength, string, and TSTRING_BUFFERSIZE.

Referenced by operator+(), operator+=(), and set(). 

00603 {
00604 #ifdef UNICODE
00605 
00606     // Convert ANSI to Unicode
00607     return MultiByteToWideChar(CP_ACP, 0, ansiString, length, string, TSTRING_BUFFERSIZE(bufferLength));
00608 
00609 #else
00610 
00611     int ansiLength = length;
00612     if( ansiLength < 0 ){
00613         ansiLength = calculateTotalLength(ansiString);
00614     }
00615 
00616     __try{
00617         CopyMemory(string, ansiString, TSTRING_BUFFERSIZE(ansiLength));
00618     }
00619     __except( (GetExceptionCode() == EXCEPTION_ACCESS_VIOLATION) 
00620             ? EXCEPTION_EXECUTE_HANDLER : EXCEPTION_CONTINUE_SEARCH) {
00621         return -1;
00622     }
00623     
00624     return ansiLength;
00625 
00626 #endif
00627 }

Friends And Related Function Documentation

TString operator+ (  const CHAR    left,
const TString &    right
)  [friend]
 

Overloading of the + operator to perform the concatenation of two strings

Definition at line 185 of file TString.cpp. 

00186 {
00187     return TString(left) + right;
00188 }

TString operator+ (  const WCHAR    left,
const TString &    right
)  [friend]
 

Overloading of the + operator to perform the concatenation of two strings

Definition at line 180 of file TString.cpp. 

00181 {
00182     return TString(left) + right;
00183 }

TString operator+ (  const TString &    left,
const CHAR    right
)  [friend]
 

Overloading of the + operator to perform the concatenation of two strings

Definition at line 175 of file TString.cpp. 

00176 {
00177     return left + TString(right);
00178 }

TString operator+ (  const TString &    left,
const WCHAR    right
)  [friend]
 

Overloading of the + operator to perform the concatenation of two strings

Definition at line 170 of file TString.cpp. 

00171 {
00172     return left + TString(right);
00173 }

TString operator+ (  PCWSTR    left,
const TString &    right
)  [friend]
 

Overloading of the + operator to perform the concatenation of two strings

Definition at line 165 of file TString.cpp. 

00166 {
00167     return TString(left) + right;
00168 }

TString operator+ (  PCSTR    left,
const TString &    right
)  [friend]
 

Overloading of the + operator to perform the concatenation of two strings

Definition at line 160 of file TString.cpp. 

00161 {
00162     return TString(left) + right;
00163 }

TString operator+ (  const TString &    left,
PCWSTR    right
)  [friend]
 

Overloading of the + operator to perform the concatenation of two strings

Definition at line 155 of file TString.cpp. 

00156 {
00157     return left + TString(right);
00158 }

TString operator+ (  const TString &    left,
PCSTR    right
)  [friend]
 

Overloading of the + operator to perform the concatenation of two strings

Definition at line 150 of file TString.cpp. 

00151 {
00152     return left + TString(right);
00153 }

TString operator+ (  const TString &    left,
const TString &    right
)  [friend]
 

Overloading of the + operator to perform the concatenation of two strings

Definition at line 122 of file TString.cpp. 

00123 {
00124     // Length of right (less term) + this length (includes term)
00125     const int totalLength = left.bufferLength - 1 + right.bufferLength;
00126 
00127     TString rtrn;
00128 
00129     // Alloc sufficient memory
00130     assert( rtrn.alloc( totalLength ) );
00131 
00132     // Copy left to rtrn (inc term)
00133     assert( rtrn.stringCopy( left, left.bufferLength ) == left.bufferLength );
00134 
00135 #ifdef UNICODE
00136 
00137     wcscat( rtrn.string, right.string );
00138 
00139 #else
00140 
00141     strcat( rtrn.string, right.string );
00142 
00143 #endif
00144 
00145     return rtrn;
00146 }

Member Data Documentation

PTSTR TString::EMPTYSTRING = TEXT("") [static, private]
 

A static variable holding an empty string

Definition at line 120 of file TString.cpp.

Referenced by alloc(), memoryDealloc(), operator PCTSTR(), and TString().

The documentation for this class was generated from the following files:
Generated on Mon Mar 25 06:30:00 2002 for Window Dressing by doxygen1.2.13.1 written by Dimitri van Heesch, © 1997-2001