Basic CString Operations
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at 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 anotherCString
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](../Topic/CString%20Semantics.md).
> [!NOTE]
> 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](../Topic/Unicode%20and%20Multibyte%20Character%20Set%20\(MBCS\)%20Support.md).
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
Strings (ATL/MFC)
CStringT Class
Class Template Instantiation
Explicit Specialization of Class Templates
Template Specialization
How to: Convert Between Various String Types