CStringT Class
This class represents a CStringT object.
template< typename BaseType, class StringTraits >
class CStringT :
public CSimpleStringT< BaseType, _CSTRING_IMPL_::_MFCDLLTraitsCheck< BaseType, StringTraits > ::c_bIsMFCDLLTraits>
Parameters
BaseType
The character type of the string class. Can be one of the following:char (for ANSI character strings).
wchar_t (for Unicode character strings).
TCHAR (for both ANSI and Unicode character strings).
StringTraits
Determines if the string class needs C Run-Time (CRT) Library support and where string resources are located. Can be one of the following:StrTraitATL< wchar_t | char | TCHAR, ChTraitsCRT< wchar_t | char | TCHAR > >
The class requires CRT support and searches for resource strings in the module specified by m_hInstResource (a member of the application's module class).
StrTraitATL< wchar_t | char | TCHAR, ChTraitsOS< wchar_t | char | TCHAR > >
The class does not require CRT support and searches for resource strings in the module specified by m_hInstResource (a member of the application's module class).
StrTraitMFC< wchar_t | char | TCHAR, ChTraitsCRT< wchar_t | char | TCHAR > >
The class requires CRT support and searches for resource strings using the standard MFC search algorithm.
StrTraitMFC< wchar_t | char | TCHAR, ChTraitsOS< wchar_t | char | TCHAR > >
The class does not require CRT support and searches for resource strings using the standard MFC search algorithm.
Remarks
CStringT inherits from CSimpleStringT Class. Advanced features, such as character manipulation, ordering, and searching, are implemented by CStringT.
Note
CStringT objects are capable of throwing exceptions. This occurs when a CStringT object runs out of memory for any reason.
A CStringT object consists of a variable-length sequence of characters. CStringT provides functions and operators using syntax similar to that of Basic. Concatenation and comparison operators, together with simplified memory management, make CStringT objects easier to use than ordinary character arrays.
Note
Although it is possible to create CStringT instances that contain embedded null characters, we recommend against it. Calling methods and operators on CStringT objects that contain embedded null characters can produce unintended results.
By using different combinations of the BaseType and StringTraits parameters, CStringT objects can come in the following types, which are have been predefined by the ATL libraries.
If using in an ATL application:
CString, CStringA, and CStringW are exported from the MFC DLL (MFC90.DLL), never from user DLLs. This is done to prevent CStringT from being multiply defined.
Note
If you encountered linker errors when exporting a CString-derived class from an MFC extension DLL in Visual C++ .NET 2002 and have applied the workaround as described in the Knowledge Base article, "Linking Errors When You Import CString-Derived Classes" (Q309801), you should remove the workaround code, because this has been fixed in Visual C++ .NET 2003. You can find Knowledge Base articles on the MSDN Library CD-ROM or at https://support.microsoft.com/support.
The following string types are available within MFC-based applications:
CStringT type |
Declaration |
|---|---|
CStringA |
An ANSI character type string with CRT support. |
CStringW |
A Unicode character type string with CRT support. |
CString |
Both ANSI and Unicode character types with CRT support. |
The following string types are available in projects where ATL_CSTRING_NO_CRT is defined:
CStringT type |
Declaration |
|---|---|
CAtlStringA |
An ANSI character type string without CRT support. |
CAtlStringW |
A Unicode character type string without CRT support. |
CAtlString |
Both ANSI and Unicode character types without CRT support. |
The following string types are available in projects where ATL_CSTRING_NO_CRT is not defined:
CStringT type |
Declaration |
|---|---|
CAtlStringA |
An ANSI character type string with CRT support. |
CAtlStringW |
A Unicode character type string with CRT support. |
CAtlString |
Both ANSI and Unicode character types with CRT support. |
CString objects also have the following characteristics:
CStringT objects can grow as a result of concatenation operations.
CStringT objects follow "value semantics." Think of a CStringT object as an actual string, not as a pointer to a string.
You can freely substitute CStringT objects for PCXSTR function arguments.
Custom memory management for string buffers. For more information, see Memory Management and CStringT.
CStringT Predefined Types
Because CStringT uses a template argument to define the character type (either wchar_t or char) supported, method parameter types can be complicated at times. To simplify this issue, a set of predefined types is defined and used throughout the CStringT class. The following table lists the various types:
Name |
Description |
|---|---|
XCHAR |
A single character (either wchar_t or char) with the same character type as the CStringT object. |
YCHAR |
A single character (either wchar_t or char) with the opposite character type as the CStringT object. |
PXSTR |
A pointer to a character string (either wchar_t or char) with the same character type as the CStringT object. |
PYSTR |
A pointer to a character string (either wchar_t or char) with the opposite character type as the CStringT object. |
PCXSTR |
A pointer to a const character string (either wchar_t or char) with the same character type as the CStringT object. |
PCYSTR |
A pointer to a const character string (either wchar_t or char) with the opposite character type as the CStringT object. |
Note
Code that previously used undocumented methods of CString (such as AssignCopy) must be replaced with code that uses the following documented methods of CStringT (such as GetBuffer or ReleaseBuffer). These methods are inherited from CSimpleStringT.
Requirements
Header |
Use for |
|---|---|
cstringt.h |
MFC-only string objects |
atlstr.h |
Non-MFC string objects |