CStringT Class

  • Article

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

See Also

Reference

Hierarchy Chart

CSimpleStringT Class

Other Resources

CStringT Members

ATL/MFC Shared Classes

Change History

Date

History

Reason

May 2009

Added CSimpleStringT to See Also.

Information enhancement.

July 2010

Added text stating that GetBuffer is inherited from CSimpleStringT.

Customer feedback.