CString Operations Relating to C-Style Strings
Updated: October 2009
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 supports.)
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.
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 myString.
CString aCString = "A string"; char myString; strcpy(myString, (LPCTSTR)aString);
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. The 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.
The third argument to strcpy_s (or the Unicode/MBCS-portable _tcscpy_s) is either a constwchar_t* () or a const char* (). The earlier example passes a CString for this argument. The 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++.
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 _tcscmp).
If you must use the C run-time string functions, you can use the techniques described in Converting to C-Style Null-Terminated Strings. 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 CString object.
In most situations, you should use CString methods 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.
The GetBuffer and 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
Call GetBuffer for a CString object and specify the length of the buffer you require.
Use the pointer returned by GetBuffer to write characters directly into the CString object.
Call ReleaseBuffer for the CString object to update all the internal CString state information, for example, the length of the string. After you modify the contents of a CString object directly, you must call ReleaseBuffer before you call any other CString member 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 the type of the arguments and cannot determine which conversion operation to perform on each argument. Therefore, you must use an explicit type cast when you pass 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.
For functions that require a string argument, you can 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. Wherever you can use an LPCTSTR, you can also use a CString object.
You can also specify a formal parameter as a constant string reference (that is, constCString&) if the argument will not be modified. Drop the const modifier if the string will be modified by the function. If you want a default null value, initialize it to the null string [""], as shown in the following example.
For most function results, you can return a CString object by value.