Strings: CString Operations Relating to C-Style Strings

Article
09/15/2006

It is often useful to manipulate the contents of a object as if it were a C-style null-terminated string. This article covers the following topics:

Converting to C-style null-terminated strings
Working with standard run-time library string functions
Modifying CString contents directly
Using CString objects with variable argument functions
Specifying CString formal parameters

Converting to C-Style Null-Terminated Strings

Consider the following two cases:

In the simplest case, you can cast a CString object to be an LPCTSTR. The LPCTSTR type conversion operator returns a pointer to a read-only C-style null-terminated string from a CString object.

The pointer returned by LPCTSTR points into the data area used by the CString. If the CString goes out of scope and is automatically deleted or something else changes the contents of the CString, the LPCTSTR pointer will no longer be valid. Treat the string to which the pointer points as temporary.
You can use CString functions, such as SetAt, to modify individual characters in the string object. However, if you need a copy of a CString object’s characters that you can modify directly, use strcpy (or the Unicode/MBCS-portable _tcscpy) to copy the CString object into a separate buffer where the characters can be safely modified, as shown by the following example:
```
CString theString( "This is a test" );
LPTSTR lpsz = new TCHAR[theString.GetLength()+1];
_tcscpy(lpsz, theString);
//... modify lpsz as much as you want
```
Note The second argument to strcpy (or the Unicode/MBCS-portable _tcscpy) 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

In most situations, you should be able to find CString member functions 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 need to use the C run-time string functions, you can use the techniques described in Converting to C-Style Null-Terminated Strings to 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.

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.

However, there are certain situations, such as working with operating-system functions that require a character buffer, where it is advantageous to directly modify the CString contents.

The GetBuffer and ReleaseBuffer member functions allow you to gain access to the internal character buffer of a CString object and modify it directly. The following steps show how to use these functions for this purpose:

Call GetBuffer for a CString object, specifying 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 (such as the length of the string). After modifying a CString object’s contents directly, you must call ReleaseBuffer before calling any other CString member functions.

Using CString Objects with Variable Argument Functions

Some C functions take a variable number of arguments. A notable example is printf. 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 here:

CString kindOfFruit = "bananas";
int        howmany = 25;
printf( "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 CString object.

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 = "" );

For most function results, you can simply return a CString object by value.