CString

Win32++

CString Class

Description

This class is intended to provide much the same functionality of the MFC/ATL CString class that ships with Microsoft compilers. The CString class specified here is compatible with other compilers such as Borland 5.5 and MinGW.

CString Members

Initialisation and Assignment

CString

CString();

CString(LPCSTR pszText);

CString(LPCWSTR pszText);

CString(TCHAR ch, int nLength = 1);

CString(LPCTSTR pszText, int nLength);

Constructor for CString.

operator =

CString& operator = (const CString& str);

CString& operator = (const TCHAR ch);

CString& operator = (LPCSTR pszText);

CString& operator = (LPCWSTR pszText);

Assigns a value to the CString. Attributes c_str

LPCTSTR c_str() const;

Converts the CString to a LPCTSTR. GetString

tString& GetString();

Returns a reference to the underlying std::basic_string<TCHAR>. GetLength

int GetLength() const;

Returns the length in characters. operator LPCTSTR

operator LPCTSTR() const;

Converts the CString to a LPCTSTR. operator BSTR

operator BSTR() const;

Converts the CString to a BSTR. Operations AllocSysString

BSTR AllocSysString() const;

Allocates a BSTR from the CString content. AppendFormat

void AppendFormat(LPCTSTR pszFormat,...);

void AppendFormat(UINT nFormatID, ...);

Appends formatted data to an the CString content. Collate

int Collate(LPCTSTR pszText) const;

Performs a case sensitive comparison of the two strings using locale-specific information. CollateNoCase

int CollateNoCase(LPCTSTR pszText) const;

Performs a case insensitive comparison of the two strings using locale-specific information. Compare

int Compare(LPCTSTR pszText) const;

Performs a case sensitive comparison of the two strings. CompareNoCase

int CompareNoCase(LPCTSTR pszText) const;

Performs a case insensitive comparison of the two strings. Delete

int Delete(int nIndex, int nCount = 1);

Deletes a character or characters from the string. Empty

void Empty();

Erases the contents of the string. Find

int Find(TCHAR ch, int nIndex = 0 ) const;

int Find(LPCTSTR pszText, int nStart = 0) const;

Finds a character in the string. FindOneOf

int FindOneOf(LPCTSTR pszText) const;

Finds the first matching character from a set. Format

void Format(UINT nID, ...);

void Format(LPCTSTR pszFormat,...);

Formats the string as sprintf does. FormatV

void FormatV(LPCTSTR pszFormat, va_list args);

Formats the string using a variable list of arguments. FormatMessage

void FormatMessage(LPCTSTR pszFormat,...);

Formats a message string. FormatMessageV

void FormatMessageV(LPCTSTR pszFormat, va_list args);

Formats a message string using a variable argument list. GetAt

TCHAR GetAt(int nIndex) const;

Returns the character at the specified location within the string. GetBuffer

LPTSTR GetBuffer(int nMinBufLength);

Creates a buffer of nMinBufLength charaters (+1 extra for NULL termination) and returns a pointer to this buffer. This buffer can be used by any function which accepts a LPTSTR. Care must be taken not to exceed the length of the buffer. Use ReleaseBuffer to copy this buffer back to the CString object. GetEnvironmentVariable

BOOL GetEnvironmentVariable(LPCTSTR pszVar);

Sets the string to the value of the specified environment variable. GetErrorString

void GetErrorString(DWORD dwError);

Returns the error string for the specified System Error Code (e.g from GetLastErrror). Insert

int Insert(int nIndex, TCHAR ch);

int Insert(int nIndex, const CString& str);

Inserts a single character or a substring at the given index within the string. IsEmpty

BOOL IsEmpty() const;

Returns TRUE if the string is empty. Left

CString Left(int nCount) const;

Extracts the left part of a string. LoadString

BOOL LoadString(UINT nID);

Loads the string from a Windows resource. MakeLower

void MakeLower();

Converts all the characters in this string to lowercase characters. MakeReverse

void MakeReverse();

Reverses the string. MakeUpper

void MakeUpper();

Converts all the characters in this string to uppercase characters. Mid

CString Mid(int nFirst) const;

CString Mid(int nFirst, int nCount) const;

Extracts the middle part of a string. ReleaseBuffer

void ReleaseBuffer( int nNewLength = -1 );

This copies the contents of the buffer (acquired by GetBuffer) to this CString, and releases the contents of the buffer. The default length of -1 copies from the buffer until a null terminator is reached. If the buffer doesn't contain a null terminator, you must specify the buffer's length. Remove

int Remove(LPCTSTR pszText);

Removes each occurrence of the specified substring from the string. Replace

int Replace(TCHAR chOld, TCHAR chNew);

int Replace(const LPCTSTR pszOld, LPCTSTR pszNew);

Replaces each occurance of the old character with the new character. ReverseFind

int ReverseFind(LPCTSTR pszText, int nStart = -1) const;

Search for a substring within the string, starting from the end. Right

CString Right(int nCount) const;

Extracts the right part of a string. SetAt

void SetAt(int nIndex, TCHAR ch);

Sets the character at the specified position to the specified value. SetSysString

BSTR SetSysString(BSTR* pBstr) const;

Sets an existing BSTR object to the string. SpanExcluding

CString SpanExcluding(LPCTSTR pszText) const;

Extracts characters from the string, starting with the first character, that are not in the set of characters identified by pszCharSet. SpanIncluding

CString SpanIncluding(LPCTSTR pszText) const;

Extracts a substring that contains only the characters in a set. Tokenize

CString Tokenize(LPCTSTR pszTokens, int& iStart) const;

Extracts specified tokens in a target string. Trim

void Trim();

Trims all leading and trailing whitespace characters from the string. TrimLeft

void TrimLeft();

void TrimLeft(TCHAR chTarget);

void TrimLeft(LPCTSTR pszTargets);

Trims white space characters or the specified set of characters from the beginning of the string. TrimRight

TrimRight();

void TrimRight(TCHAR chTarget);

void TrimRight(LPCTSTR pszTargets);

Trims trailing whitespace characters or the specified set of characters from the string. Truncate

void Truncate(int nNewLength);

Reduces the length of the string to the specified amount. operator +

friend CString operator + (const CString& string1, const CString& string2);

friend CString operator + (const CString& string, LPCTSTR pszText);

friend CString operator + (const CString& string, TCHAR ch);

friend CString operator + (LPCTSTR pszText, const CString& string);

friend CString operator + (TCHAR ch, const CString& string);

Appends the specified characters to the string. operator +=

CString& operator += (const CString& str);

CString& operator += (LPCSTR szText);

CString& operator += (LPCWSTR szText);

CString& operator += (const TCHAR ch);

Appends and then assigns the specified characters to the string. operator []

TCHAR& operator [] (int nIndex);

Returns the character at the specified index. Comparisons operator ==

bool operator == (LPCTSTR pszText) const;

Performs a case sensitive comparison of the two strings. Returns true of the two strings are the same. operator !=

bool operator != (LPCTSTR pszText) const;

Performs a case sensitive comparison of the two strings. Returns true if the two strings are not the same. operator <

friend bool operator < (const CString& string1, const CString& string2);

friend bool operator < (const CString& string1, LPCTSTR pszText);

Performs a case sensitive comparison of the two strings. operator >

friend bool operator > (const CString& string1, const CString& string2);

friend bool operator > (const CString& string1, LPCTSTR pszText);

Performs a case sensitive comparison of the two strings. operator <=

friend bool operator <= (const CString& string1, const CString& string2);

friend bool operator <= (const CString& string1, LPCTSTR pszText);

Performs a case sensitive comparison of the two strings. operator >=

friend bool operator >= (const CString& string1, const CString& string2);

friend bool operator >= (const CString& string1, LPCTSTR pszText);

Performs a case sensitive comparison of the two strings.

Remarks

Using the CString class

The following code demonstrates how to assign strings to a CString.

// Assign some text to CString
CString str1 = _T("Hello World.");
CString str2 = _T(" I like strings.");
CString str3 = str1 + str2;
SetWindowText(str3);

// How to use GetBuffer and SetBuffer with functions expecting a TCHAR array
CString str;
int nLength = ::GetWindowTextLength(m_hWnd);
::GetWindowText(m_hWnd, str.GetBuffer(nLength), nLength + 1);
str.ReleaseBuffer();

Differences between this class and the MFC/ATL CString class

The constructors for this class accepts only TCHARs. The various text conversion functions can be used to convert from other character types to TCHARs.
This class is not reference counted, so these CStrings should be passed as references or const references when used as function arguments. As a result there
is no need for functions like LockBuffer and UnLockBuffer.

The Format functions only accepts POD (Plain Old Data) arguments. It does not accept arguments which are class or struct objects. In particular it does not accept CString objects, unless these are cast to LPCTSTR. This is demonstrates valid and invalid usage:

CString string1(_T("Hello World"));
CString string2;
	
// This is invalid, and produces undefined behaviour.
string2.Format(_T("String1 is: %s"), string1); // No! you can't do this
	
// This is ok
string2.Format(_T("String1 is: %s"), (LPCTSTR)string1); // Yes, this is correct

This class provides a few additional functions:
- c_str Returns a const TCHAR string. This is an alternative for casting to LPCTSTR.
- GetErrorString Assigns CString to the error string for the specified System Error Code.
- GetString Returns a reference to the underlying std::basic_string<TCHAR>.

Summary Information

Header file	c_string.h
Win32/64 support	Yes
WinCE support	Yes

previous page start next page