CString Operations Relating to C-Style Strings
A CString object contains character string data.
CString inherits the set of the methods and operators that are defined in the class template CStringT to work with string data. (
CString is a typedef that specializes
CStringT to work with the kind of character data that
CString does not store character data internally as a C-style null-terminated string. Instead,
CString tracks the length of character data so that it can more securely watch the data and the space it requires.
CString does accept C-style strings, and provides ways to access character data as a C-style string. This topic contains the following sections that explain how to use a
CString object as if it were a C-style null-terminated string.
Using CString as a C-Style Null-Terminated String
To use a
CString object as a C-style string, cast the object to LPCTSTR. In the following example, the
CString returns a pointer to a read-only C-style null-terminated string. The
strcpy function puts a copy of the C-style string in the variable
CString aCString = "A string"; char myString; strcpy(myString, (LPCTSTR)aCString);
You can use
CString methods, for example,
SetAt, to modify individual characters in the string object. However, the LPCTSTR pointer is temporary and becomes invalid when any change is made to
CString can also go out of scope and be automatically deleted. We recommend that you get a fresh LPCTSTR pointer of a
CString object every time that you use one.
Sometimes you may require a copy of
CString data to modify directly. Use the more secured function
strcpy_s (or the Unicode/MBCS-portable
_tcscpy_s) to copy the
CString object into a separate buffer. This is where characters can be safely modified, as shown by the following example.
CString theString(_T("This is a test")); int sizeOfString = (theString.GetLength() + 1); LPTSTR lpsz = new TCHAR[sizeOfString]; _tcscpy_s(lpsz, sizeOfString, theString); //... modify lpsz as much as you want
The third argument to
strcpy_s (or the Unicode/MBCS-portable
_tcscpy_s) is either a
const wchar_t* (Unicode) or a
const char* (ANSI). The example above passes a
CString for this argument. The C++ compiler automatically applies the conversion function defined for the
CString class that converts a
CString to an
LPCTSTR. The ability to define casting operations from one type to another is one of the most useful features of C++.
Working with Standard Run-Time Library String Functions
You should be able to find a
CString method to perform any string operation for which you might consider using the standard C run-time library string functions such as
strcmp (or the Unicode/MBCS-portable
If you must use the C run-time string functions, you can use the techniques described in _core_using_cstring_as_a_c.2d.style_null.2d.terminated_string. You can copy the
CString object to an equivalent C-style string buffer, perform your operations on the buffer, and then assign the resulting C-style string back to a
Modifying CString Contents Directly
In most situations, you should use
CString member functions to modify the contents of a
CString object or to convert the
CString to a C-style character string.
There are some situations where it makes sense to directly modify the
CString contents, for example, when you work with operating-system functions that require a character buffer.
ReleaseBuffer methods offer access to the internal character buffer of a
CString object and let you modify it directly. The following steps show how to use these functions for this purpose.
To use GetBuffer and ReleaseBuffer to access the internal character buffer of a CString object
CStringobject and specify the length of the buffer you require.
Use the pointer returned by
GetBufferto write characters directly into the
CStringobject to update all the internal
CStringstate information, for example, the length of the string. After you modify the contents of a
CStringobject directly, you must call
ReleaseBufferbefore you call any other
Using CString Objects with Variable Argument Functions
Some C functions take a variable number of arguments. A notable example is
printf_s. Because of the way this kind of function is declared, the compiler cannot be sure of the type of the arguments and cannot determine which conversion operation to perform on each argument. Therefore, it is essential that you use an explicit type cast when passing a
CString object to a function that takes a variable number of arguments.
To use a
CString object in a variable argument function, explicitly cast the
CString to an LPCTSTR string, as shown in the following example.
CString kindOfFruit = _T("bananas"); int howmany = 25; _tprintf_s(_T("You have %d %s\n"), howmany, (LPCTSTR)kindOfFruit);
Specifying CString Formal Parameters
For most functions that need a string argument, it is best to specify the formal parameter in the function prototype as a
const pointer to a character (
LPCTSTR) instead of a
CString. When a formal parameter is specified as a
const pointer to a character, you can pass either a pointer to a TCHAR array, a literal string [
"hi there"], or a
CString object. The
CString object will be automatically converted to an LPCTSTR. Any place you can use an LPCTSTR, you can also use a
You can also specify a formal parameter as a constant string reference (that is,
const CString&) if the argument will not be modified. Drop the const modifier if the string will be modified by the function. If a default null value is desired, initialize it to the null string [
""], as shown below:
void AddCustomer(const CString& name, const CString& address, const CString& comment = _T(""));
For most function results, you can simply return a
CString object by value.