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.

Members

Public Constructors

Name

Description

CStringT::CStringT

Constructs a CStringT object in various ways.

CStringT::~CStringT

Destroys a CStringT object.

Public Methods

Name

Description

CStringT::AllocSysString

Allocates a BSTR from CStringT data.

CStringT::AnsiToOem

Makes an in-place conversion from the ANSI character set to the OEM character set.

CStringT::AppendFormat

Appends formatted data to an existing CStringT object.

CStringT::Collate

Compares two strings (case sensitive, uses locale-specific information).

CStringT::CollateNoCase

Compares two strings (case insensitive, uses locale-specific information).

CStringT::Compare

Compares two strings (case sensitive).

CStringT::CompareNoCase

Compares two strings (case insensitive).

CStringT::Delete

Deletes a character or characters from a string.

CStringT::Find

Finds a character or substring inside a larger string.

CStringT::FindOneOf

Finds the first matching character from a set.

CStringT::Format

Formats the string as sprintf does.

CStringT::FormatMessage

Formats a message string.

CStringT::FormatMessageV

Formats a message string using a variable argument list.

CStringT::FormatV

Formats the string using a variable list of arguments.

CStringT::GetEnvironmentVariable

Sets the string to the value of the specified environment variable.

CStringT::Insert

Inserts a single character or a substring at the given index within the string.

CStringT::Left

Extracts the left part of a string.

CStringT::LoadString

Loads an existing CStringT object from a Windows resource.

CStringT::MakeLower

Converts all the characters in this string to lowercase characters.

CStringT::MakeReverse

Reverses the string.

CStringT::MakeUpper

Converts all the characters in this string to uppercase characters.

CStringT::Mid

Extracts the middle part of a string.

CStringT::OemToAnsi

Makes an in-place conversion from the OEM character set to the ANSI character set.

CStringT::Remove

Removes indicated characters from a string.

CStringT::Replace

Replaces indicated characters with other characters.

CStringT::ReverseFind

Finds a character inside a larger string; starts from the end.

CStringT::Right

Extracts the right part of a string.

CStringT::SetSysString

Sets an existing BSTR object with data from a CStringT object.

CStringT::SpanExcluding

Extracts characters from the string, starting with the first character, that are not in the set of characters identified by pszCharSet.

CStringT::SpanIncluding

Extracts a substring that contains only the characters in a set.

CStringT::Tokenize

Extracts specified tokens in a target string.

CStringT::Trim

Trims all leading and trailing whitespace characters from the string.

CStringT::TrimLeft

Trims leading whitespace characters from the string.

CStringT::TrimRight

Trims trailing whitespace characters from the string.

Operators

CStringT::operator =

Assigns a new value to a CStringT object.

CStringT::operator +

Concatenates two strings or a character and a string.

CStringT::operator +=

Concatenates a new string to the end of an existing string.

CStringT::operator ==

Determines if two strings are logically equal.

CStringT::operator !=

Determines if two strings are logically not equal.

CStringT::operator <

Determines if the string on the left side of the operator is less than to the string on the right side.

CStringT::operator >

Determines if the string on the left side of the operator is greater than to the string on the right side.

CStringT::operator <=

Determines if the string on the left side of the operator is less than or equal to the string on the right side.

CStringT::operator >=

Determines if the string on the left side of the operator is greater than or equal to the string on the right side.

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.

Inheritance Hierarchy

CSimpleStringT

CStringT

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

ATL/MFC Shared Classes