Basic CString Operations
This topic explains the following basic CString operations:
Creating CString objects from standard C literal strings
Accessing individual characters in a CString
Concatenating two CString objects
Comparing CString objects
Converting CString objects
Class CString is based on class template CStringT Class. CString is a typedef of CStringT. More exactly, CString is a typedef of an explicit specialization of CStringT, which is a common way to use a class template to define a class. Similarly defined classes are CStringA and CStringW. For more information on explicit specialization, see Class Template Instantiation.
CString, CStringA, and CStringW are defined in atlstr.h. CStringT is defined in cstringt.h.
CString, CStringA, and CStringW each get a set of the methods and operators defined by CStringT for use with the string data they support. Some of the methods duplicate and, in some cases, surpass the string services of the C run-time libraries.
Note: CString is a native class. For a string class that is for use in a C++/CLI managed project, use System.String.
Creating CString Objects from Standard C Literal Strings
You can assign C-style literal strings to a CString just as you can assign one CString object to another.
Assign the value of a C literal string to a CString object.
CString myString = _T("This is a test");
Assign the value of one CString to another CString object.
CString oldString = _T("This is a test"); CString newString = oldString;
The contents of a CString object are copied when one CString object is assigned to another. Therefore, the two strings do not share a reference to the actual characters that make up the string. For more information about how to use CString objects as values, see CString Semantics.
Observação
To write your application so that it can be compiled for Unicode or for ANSI, code literal strings by using the _T macro. For more information, see Unicode and Multibyte Character Set (MBCS) Support.
Accessing Individual Characters in a CString
You can access individual characters in a CString object by using the GetAt and SetAt methods. You can also use the array element, or subscript, operator ( [ ] ) instead of GetAt to get individual characters. (This resembles accessing array elements by index, as in standard C-style strings.) Index values for CString characters are zero-based.
Concatenating Two CString Objects
To concatenate two CString objects, use the concatenation operators (+ or +=), as follows.
CString s1 = _T("This "); // Cascading concatenation
s1 += _T("is a ");
CString s2 = _T("test");
CString message = s1 + _T("big ") + s2;
// Message contains "This is a big test".
At least one argument to the concatenation operators (+ or +=) must be a CString object, but you can use a constant character string (for example, "big") or a char (for example, 'x') for the other argument.
Comparing CString Objects
The Compare method and the == operator for CString are equivalent. Compare, operator==, and CompareNoCase are MBCS and Unicode aware; CompareNoCase is also case-insensitive. The Collate method of CString is locale-sensitive and is often slower than Compare. Use Collate only where you must abide by the sorting rules as specified by the current locale.
The following table shows the available CString comparison functions and their equivalent Unicode/MBCS-portable functions in the C run-time library.
CString function |
MBCS function |
Unicode function |
---|---|---|
Compare |
_mbscmp |
wcscmp |
CompareNoCase |
_mbsicmp |
_wcsicmp |
Collate |
_mbscoll |
wcscoll |
The CStringT class template defines the relational operators (<, <=, >=, >, ==, and !=), which are available for use by CString. You can compare two CStrings by using these operators, as shown in the following example.
CString s1(_T("Tom"));
CString s2(_T("Jerry"));
ASSERT(s2 < s1);
Converting CString Objects
For information about converting CString objects to other string types, see How to: Convert Between Various String Types.
Using CString with wcout
To use a CString with wcout you must explicitly cast the object to a const wchar_t* as shown in the following example:
CString cs("meow");
wcout << (const wchar_t*) cs << endl;
Without the cast, cs is treated as a void* and wcout prints the address of the object. This behavior is caused by subtle interactions between template argument deduction and overload resolution which are in themselves correct and conformant with the C++ standard.
See Also
Reference
Explicit Specialization of Class Templates
Partial Specialization of Class Templates (C++)
Concepts
How to: Convert Between Various String Types
Other Resources
Change History
Date |
History |
Reason |
---|---|---|
March 2011 |
Added section describing CString behavior in wcout streams. |
Replace with one of the following tokens: Information enhancement. |