Edit

Share via

CStringT Class

  • Article

This class represents a CStringT object.

Syntax

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 doesn't 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 doesn't 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 aren't 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

Name Description
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 aren't logically 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 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 defined multiple times.

Note

If your code contains the workaround for linker errors that is described in Exporting String Classes Using CStringT, you should remove that code. It is no longer needed.

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 isn't 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 because 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

CStringT::AllocSysString

Allocates an Automation-compatible string of the type BSTR and copies the contents of the CStringT object into it, including the terminating null character.

BSTR AllocSysString() const;

Return Value

The newly allocated string.

Remarks

In MFC programs, a CMemoryException Class is thrown if insufficient memory exists. In ATL programs, a CAtlException is thrown. This function is normally used to return strings for Automation.

Commonly, if this string is passed to a COM function as an [in] parameter, then this requires the caller to free the string. This can be done by using SysFreeString, as described in the Windows SDK. For more information, see Allocating and Releasing Memory for a BSTR.

For more information about OLE allocation functions in Windows, see SysAllocString in the Windows SDK.

Example

The following example demonstrates the use of CStringT::AllocSysString.

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString str(_T("This is a test string!"));
BSTR bstr = str.AllocSysString();

// bstr now contains "This is a test string!", and can be
// passed to any OLE function requiring a BSTR.
// Normally, if you pass the BSTR, you will
// need to free the string after returning from the function call.

CStringT::AnsiToOem

Converts all the characters in this CStringT object from the ANSI character set to the OEM character set.

void AnsiToOem();

Remarks

The function isn't available if _UNICODE is defined.

Example

// OEM character 252 on most IBM-compatible computers in
// many countries/regions is superscript n, as in 2^n.
// Converting it to the ANSI English charset results in a
// normal character 'n', which is the closest possible
// representation.

CStringT<char, StrTraitATL<char, ChTraitsCRT<char>>> str((WCHAR)252);
str.OemToAnsi();
ASSERT(str[0] == 'n');

// Be aware that in OEM to ANSI conversion the 'n'
// from the previous result cannot be converted back to
// a supsercript n because the system does not know what
// the character's value truly was.
str.AnsiToOem();
ASSERT(str[0] != 252);
ASSERT(str[0] == 'n');

CStringT::AppendFormat

Appends formatted data to an existing CStringT object.

void __cdecl AppendFormat(PCXSTR pszFormat, [, argument] ...);
void __cdecl AppendFormat(UINT nFormatID, [, argument] ...);

Parameters

pszFormat
A format-control string.

nFormatID
The string resource identifier that contains the format-control string.

argument
Optional arguments.

Remarks

This function formats and appends a series of characters and values in the CStringT. Each optional argument (if any) is converted and appended according to the corresponding format specification in pszFormat or from the string resource identified by nFormatID.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str = _T("Some data:\t");

str.AppendFormat(_T("X value = %.2f\n"), 12345.12345);
_tprintf_s(_T("%s"), (LPCTSTR) str);

CStringT::Collate

Compares two strings using the generic-text function _tcscoll.

int Collate(PCXSTR psz) const throw();

Parameters

psz
The other string used for comparison.

Return Value

Zero if the strings are identical, < 0 if this CStringT object is less than psz, or > 0 if this CStringT object is greater than psz.

Remarks

The generic-text function _tcscoll, which is defined in TCHAR.H, maps to either strcoll, wcscoll, or _mbscoll, depending on the character set that is defined at compile time. Each function does a case-sensitive comparison of the strings according to the code page currently in use. For more information, see strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l.

CStringT::CollateNoCase

Compares two strings using the generic-text function _tcscoll.

int CollateNoCase(PCXSTR psz) const throw();

Parameters

psz
The other string used for comparison.

Return Value

Zero if the strings are identical (ignoring case), < 0 if this CStringT object is less than psz (ignoring case), or > 0 if this CStringT object is greater than psz (ignoring case).

Remarks

The generic-text function _tcscoll, which is defined in TCHAR.H, maps to either stricoll, wcsicoll, or _mbsicoll, depending on the character set that is defined at compile time. Each function does a case-insensitive comparison of the strings, according to the code page currently in use. For more information, see strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str1 = _T("Co-Op");
CAtlString str2 = _T("con");

int n;

// Collation uses language rules, such as ignoring dashes.
// NoCase version ignores case.
n = str1.CollateNoCase(str2);
ASSERT(n < 0);

// Comparison is a strict ASCII comparison with no language rules
// but still ignores case in NoCase version.
n = str1.CompareNoCase(str2);
ASSERT(n < 0);

CStringT::Compare

Compares two strings (case-sensitive).

int Compare(PCXSTR psz) const;

Parameters

psz
The other string used for comparison.

Return Value

Zero if the strings are identical, < 0 if this CStringT object is less than psz, or > 0 if this CStringT object is greater than psz.

Remarks

The generic-text function _tcscmp, which is defined in TCHAR.H, maps to either strcmp, wcscmp, or _mbscmp, depending on the character set that is defined at compile time. Each function does a case-sensitive comparison of the strings and isn't affected by locale. For more information, see strcmp, wcscmp, _mbscmp.

If the string contains embedded nulls, for purposes of comparison the string is considered to be truncated at the first embedded null character.

Example

The following example demonstrates the use of CStringT::Compare.

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s1(_T("abc"));
CAtlString s2(_T("abd"));
ASSERT(s1.Compare(s2) < 0);    // Compare with another CAtlString.
ASSERT(s1.Compare(_T("abe")) < 0); // Compare with LPTSTR string.

CStringT::CompareNoCase

Compares two strings (case-insensitive).

int CompareNoCase(PCXSTR psz) const throw();

Parameters

psz
The other string used for comparison.

Return Value

Zero if the strings are identical (ignoring case), <0 if this CStringT object is less than psz (ignoring case), or >0 if this CStringT object is greater than psz (ignoring case).

Remarks

The generic-text function _tcsicmp, which is defined in TCHAR.H, maps to either _stricmp, _wcsicmp or _mbsicmp, depending on the character set that is defined at compile time. Each function does a case-insensitive comparison of the strings. The comparison depends on the LC_CTYPE aspect of the locale but not LC_COLLATE. For more information, see _stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s1(_T("abc"));
CAtlString s2(_T("ABD"));
ASSERT(s1.CompareNoCase(s2) < 0); // Compare with a CAtlString.
ASSERT(s1.CompareNoCase(_T("ABE")) < 0); // Compare with LPTSTR string.

CStringT::CStringT

Constructs a CStringT object.

CStringT() throw() :
    CThisSimpleString(StringTraits::GetDefaultManager());

explicit CStringT(IAtlStringMgr* pStringMgr) throw() :
    CThisSimpleString( pStringMgr);

CStringT(const VARIANT& varSrc);

CStringT(const VARIANT& varSrc, IAtlStringMgr* pStringMgr);

CStringT(const CStringT& strSrc) :
    CThisSimpleString( strSrc);

operator CSimpleStringT<
                    BaseType,
                    !_CSTRING_IMPL_::_MFCDLLTraitsCheck<BaseType, StringTraits>
                    :: c_bIsMFCDLLTraits> &()

template <bool bMFCDLL>
CStringT(const CSimpleStringT<BaseType, bMFCDLL>& strSrc) :
    CThisSimpleString( strSrc);

template <class SystemString>
CStringT(SystemString^ pString) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const XCHAR* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(const YCHAR* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(LPCSTR pszSrc, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

CStringT(LPCWSTR pszSrc, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

CSTRING_EXPLICIT CStringT(const unsigned char* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

/*CSTRING_EXPLICIT*/ CStringT(char* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(unsigned char* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(wchar_t* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const unsigned char* pszSrc, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

CSTRING_EXPLICIT CStringT(char ch, int nLength = 1) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(wchar_t ch, int nLength = 1) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const XCHAR* pch, int nLength) :
    CThisSimpleString( pch, nLength, StringTraits::GetDefaultManager());

CStringT(const YCHAR* pch, int nLength) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const XCHAR* pch, int nLength, AtlStringMgr* pStringMgr) :
    CThisSimpleString( pch, nLength, pStringMgr);

CStringT(const YCHAR* pch, int nLength, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

Parameters

pch
A pointer to an array of characters of length nLength, not null-terminated.

nLength
A count of the number of characters in pch.

ch
A single character.

pszSrc
A null-terminated string to be copied into this CStringT object.

pStringMgr
A pointer to the memory manager for the CStringT object. For more information on IAtlStringMgr and memory management for CStringT, see Memory Management with CStringT.

strSrc
An existing CStringT object to be copied into this CStringT object. For more information on CThisString and CThisSimpleString, see the Remarks section.

varSrc
A variant object to be copied into this CStringT object.

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).

bMFCDLL
Boolean that specifies whether the project is an MFC DLL (TRUE) or not (FALSE).

SystemString
Must be System::String, and the project must be compiled with /clr.

pString
A handle for a CStringT object.

Remarks

Because the constructors copy the input data into new allocated storage, memory exceptions may result. Some of these constructors act as conversion functions. This allows you to substitute, for example, an LPTSTR where a CStringT object is expected.

  • CStringT( LPCSTR lpsz ): Constructs a Unicode CStringT from an ANSI string. You can also use this constructor to load a string resource as shown in the example below.

  • CStringT( LPCWSTR lpsz ): Constructs a CStringT from a Unicode string.

  • CStringT( const unsigned char* psz ): Allows you to construct a CStringT from a pointer to unsigned char.

Note

Define the _CSTRING_DISABLE_NARROW_WIDE_CONVERSION macro to turn off implicit string conversion between ANSI and Unicode strings. The macro excludes from compilation constructors that support conversion.

The strSrc parameter can be either a CStringT or CThisSimpleString object. For CStringT, use one of its default instantiations (CString, CStringA, or CStringW); for CThisSimpleString, use a this pointer. CThisSimpleString declares an instance of the CSimpleStringT Class, which is a smaller string class with less built-in functionality than the CStringT class.

The overload operator CSimpleStringT<>&() constructs a CStringT object from a CSimpleStringT declaration.

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.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s1;                    // Empty string
CAtlString s2(_T("cat"));           // From a C string literal
CAtlString s3 = s2;               // Copy constructor
CAtlString s4(s2 + _T(" ") + s3);   // From a string expression

CAtlString s5(_T('x'));             // s5 = "x"
CAtlString s6(_T('x'), 6);          // s6 = "xxxxxx"

CAtlString s7((LPCSTR)ID_FILE_NEW); // s7 = "Create a new document"

VARIANT var;
V_VT(&var) = VT_BSTR;
V_BSTR(&var) = ::SysAllocString(L"Football is a fun sport.");
CAtlString s8(var); // s8 = "Football is a fun sport."

// The following statement does not call the assignment operator.
// The compiler considers the following statement equivalent to
// CAtlString city("Paris")
CAtlString city = _T("Paris");

CStringT::~CStringT

Destroys the CStringT object.

~CStringT() throw();

Remarks

Destroys the CStringT object.

CStringT::Delete

Deletes a character or characters from a string starting with the character at the given index.

int Delete(int iIndex, int nCount = 1);

Parameters

iIndex
The zero-based index of the first character in the CStringT object to delete.

nCount
The number of characters to be removed.

Return Value

The length of the changed string.

Remarks

If nCount is longer than the string, the rest of the string will be removed.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("Soccer is best, but hockey is quicker!"));
_tprintf_s(_T("Before: %s\n"), (LPCTSTR)str);

int n = str.Delete(6, 3);
_tprintf_s(_T("After: %s\n"), (LPCTSTR)str);
ASSERT(n == str.GetLength());

Before: Soccer is best,
    but hockey is quicker!
After: Soccer best,
    but hockey is quicker!

CStringT::Find

Searches this string for the first match of a character or substring.

int Find(PCXSTR pszSub, int iStart=0) const throw();
int Find(XCHAR ch, int iStart=0) const throw();

Parameters

pszSub
A substring to search for.

iStart
The index of the character in the string to begin the search with, or 0 to start from the beginning.

ch
A single character to search for.

Return Value

The zero-based index of the first character in this CStringT object that matches the requested substring or characters; -1 if the substring or character isn't found.

Remarks

The function is overloaded to accept both single characters (similar to the run-time function strchr) and strings (similar to strstr).

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.Find(_T('c')) == 2);
ASSERT(s.Find(_T("de")) == 3);

CAtlString str(_T("The waves are still"));
int n = str.Find(_T('e'), 5);
ASSERT(n == 7);

CStringT::FindOneOf

Searches this string for the first character that matches any character contained in pszCharSet.

int FindOneOf(PCXSTR pszCharSet) const throw();

Parameters

pszCharSet
String containing characters for matching.

Return Value

The zero-based index of the first character in this string that is also in pszCharSet; -1 if there is no match.

Remarks

Finds the first occurrence of any of the characters in pszCharSet.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.FindOneOf(_T("xd")) == 3); // 'd' is first match

CStringT::Format

Writes formatted data to a CStringT in the same way that sprintf_s formats data into a C-style character array.

void __cdecl Format(UINT nFormatID, [, argument]...);
void __cdecl Format(PCXSTR pszFormat,  [, argument] ...);

Parameters

nFormatID
The string resource identifier that contains the format-control string.

pszFormat
A format-control string.

argument
Optional arguments.

Remarks

This function formats and stores a series of characters and values in the CStringT. Each optional argument (if any) is converted and output according to the corresponding format specification in pszFormat or from the string resource identified by nFormatID.

The call will fail if the string object itself is offered as a parameter to Format. For example, the following code will cause unpredictable results:

CAtlString str = _T("Some Data");
str.Format(_T("%s%d"), str, 123);   
// Attention: str is also used in the parameter list.

For more information, see Format Specification Syntax: printf and wprintf Functions.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString str;

str.Format(_T("Floating point: %.2f\n"), 12345.12345);
_tprintf_s(_T("%s"), (LPCTSTR) str);

str.Format(_T("Left-justified integer: %.6d\n"), 35);
_tprintf_s(_T("%s"), (LPCTSTR) str);

CStringT::FormatMessage

Formats a message string.

void __cdecl FormatMessage(UINT nFormatID, [, argument]...);
void __cdecl FormatMessage(PCXSTR pszFormat, [, argument]...);

Parameters

nFormatID
The string resource identifier that contains the unformatted message text.

pszFormat
Points to the format-control string. It will be scanned for inserts and formatted accordingly. The format string is similar to run-time function printf-style format strings, except it allows for the parameters to be inserted in an arbitrary order.

argument
Optional arguments.

Remarks

The function requires a message definition as input. The message definition is determined by pszFormat or from the string resource identified by nFormatID. The function copies the formatted message text to the CStringT object, processing any embedded insert sequences if requested.

Note

FormatMessage attempts to allocate system memory for the newly formatted string. If this attempt fails, a memory exception is automatically thrown.

Each insert must have a corresponding parameter following the pszFormat or nFormatID parameter. Within the message text, several escape sequences are supported for dynamically formatting the message. For more information, see the Windows FormatMessage function in the Windows SDK.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str;
int nAsked = 5;
int nAgree = 4;

str.FormatMessage(_T("%1!d! of %2!d! writers agree: Soccer is %3%!"), 
   nAgree, nAsked, _T("Best"));
ASSERT(str == _T("4 of 5 writers agree: Soccer is Best!"));

CStringT::FormatMessageV

Formats a message string using a variable argument list.

void FormatMessageV(PCXSTR pszFormat, va_list* pArgList);

Parameters

pszFormat
Points to the format-control string. It will be scanned for inserts and formatted accordingly. The format string is similar to run-time function printf-style format strings, except it allows for the parameters to be inserted in an arbitrary order.

pArgList
Pointer to a list of arguments.

Remarks

The function requires a message definition as input, determined by pszFormat. The function copies the formatted message text and a variable list of arguments to the CStringT object, processing any embedded insert sequences if requested.

Note

FormatMessageV calls CStringT::FormatMessage, which attempts to allocate system memory for the newly formatted string. If this attempt fails, a memory exception is automatically thrown.

For more information, see the Windows FormatMessage function in the Windows SDK.

CStringT::FormatV

Formats a message string using a variable argument list.

void FormatV(PCXSTR pszFormat, va_list args);

Parameters

pszFormat
Points to the format-control string. It will be scanned for inserts and formatted accordingly. The format string is similar to run-time function printf-style format strings, except it allows for the parameters to be inserted in an arbitrary order.

args
Pointer to a list of arguments.

Remarks

Writes a formatted string and a variable list of arguments to a CStringT string in the same way that vsprintf_s formats data into a C-style character array.

Example

void WriteString(LPCTSTR pstrFormat, ...)
{
    CString str;

    // format and write the data you were given
    va_list args;
    va_start(args, pstrFormat);

    str.FormatV(pstrFormat, args);
    va_end(args);

    _tprintf_s(str);
    return;
}

 

// Call the above WriteString function.
WriteString(_T("%d error(s) found in %d line(s)"), 10, 1351);

CStringT::GetEnvironmentVariable

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

BOOL GetEnvironmentVariable(PCXSTR pszVar);

Parameters

pszVar
Pointer to a null-terminated string that specifies the environment variable.

Return Value

Nonzero if successful; otherwise 0.

Remarks

Retrieves the value of the specified variable from the environment block of the calling process. The value is in the form of a null-terminated string of characters.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString EnvStr;

EnvStr.GetEnvironmentVariable(_T("TEMP"));
_tprintf_s(_T("Current value of TEMP variable: %s\n"), EnvStr);

CStringT::Insert

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

int Insert(int iIndex, PCXSTR psz);
int Insert(int iIndex, XCHAR ch);

Parameters

iIndex
The index of the character before which the insertion will take place.

psz
A pointer to the substring to be inserted.

ch
The character to be inserted.

Return Value

The length of the changed string.

Remarks

The iIndex parameter identifies the first character that will be moved to make room for the character or substring. If nIndex is zero, the insertion will occur before the entire string. If nIndex is higher than the length of the string, the function will concatenate the present string and the new material provided by either ch or psz.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("SoccerBest"));
int n = str.Insert(6, _T("is "));
ASSERT(n == str.GetLength());
_tprintf_s(_T("1: %s\n"), (LPCTSTR) str);

n = str.Insert(6, _T(' '));
ASSERT(n == str.GetLength());
_tprintf_s(_T("2: %s\n"), (LPCTSTR) str);

n = str.Insert(55, _T('!'));
ASSERT(n == str.GetLength());
_tprintf_s(_T("3: %s\n"), (LPCTSTR) str);

CStringT::Left

Extracts the leftmost nCount characters from this CStringT object and returns a copy of the extracted substring.

CStringT Left(int nCount) const;

Parameters

nCount
The number of characters to extract from this CStringT object.

Return Value

A CStringT object that contains a copy of the specified range of characters. The returned CStringT object may be empty.

Remarks

If nCount exceeds the string length, then the entire string is extracted. Left is similar to the Basic Left function.

For multi-byte character sets (MBCS), nCount treats each 8-bit sequence as a character, so that nCount returns the number of multi-byte characters multiplied by two.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.Left(2) == _T("ab"));

CStringT::LoadString

Reads a Windows string resource, identified by nID, into an existing CStringT object.

BOOL LoadString(HINSTANCE hInstance, UINT nID, WORD wLanguageID);
BOOL LoadString(HINSTANCE hInstance, UINT nID);
BOOL LoadString(UINT nID);

Parameters

hInstance
A handle to the instance of the module.

nID
A Windows string resource ID.

wLanguageID
The language of the string resource.

Return Value

Nonzero if resource load was successful; otherwise 0.

Remarks

Loads the string resource (nID) from the specified module (hInstance) using the specified language (wLanguage).

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s;
s.LoadString(IDS_APP_TITLE);

CStringT::MakeLower

Converts the CStringT object to a lowercase string.

CStringT& MakeLower();

Return Value

The resulting lowercase string.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("ABC"));

ASSERT(s.MakeLower() == _T("abc"));

CStringT::MakeReverse

Reverses the order of the characters in the CStringT object.

CStringT& MakeReverse();

Return Value

The resulting reversed string.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abc"));

ASSERT(s.MakeReverse() == _T("cba"));

CStringT::MakeUpper

Converts the CStringT object to an uppercase string.

CStringT& MakeUpper();

Return Value

The resulting uppercase string.

Remarks

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abc"));

ASSERT(s.MakeUpper() == _T("ABC"));

CStringT::Mid

Extracts a substring of length nCount characters from this CStringT object, starting at position iFirst (zero-based).

CStringT Mid(int iFirst, int nCount) const;
CStringT Mid(int iFirst) const;

Parameters

iFirst
The zero-based index of the first character in this CStringT object that is to be included in the extracted substring.

nCount
The number of characters to extract from this CStringT object. If this parameter isn't supplied, then the rest of the string is extracted.

Return Value

A CStringT object that contains a copy of the specified range of characters. The returned CStringT object may be empty.

Remarks

The function returns a copy of the extracted substring. Mid is similar to the Basic Mid function (except that indexes in Basic are one-based).

For multibyte character sets (MBCS), nCount refers to each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two characters.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.Mid(2, 3) == _T("cde"));

CStringT::OemToAnsi

Converts all the characters in this CStringT object from the OEM character set to the ANSI character set.

void OemToAnsi();

Remarks

This function isn't available if _UNICODE is defined.

Example

See the example for CStringT::AnsiToOem.

CStringT::operator =

Assigns a new value to the string.

CStringT& operator=(const CStringT& strSrc);

template<bool bMFCDLL>
CStringT& operator=(const CSimpleStringT<BaseType, bMFCDLL>& str);
CStringT& operator=(PCXSTR pszSrc);
CStringT& operator=(PCYSTR pszSrc);
CStringT& operator=(const unsigned char* pszSrc);
CStringT& operator=(XCHAR ch);
CStringT& operator=(YCHAR ch);
CStringT& operator=(const VARIANT& var);

Parameters

strSrc
A CStringT to assign to this string.

str
A reference to a CThisSimpleString object.

bMFCDLL
A boolean specifying whether the project is an MFC DLL or not.

BaseType
The string base type.

var
A variant object to assign to this string.

ch
An ANSI or Unicode character to assign to the string.

pszSrc
A pointer to the original string being assigned.

Remarks

The assignment operator accepts another CStringT object, a character pointer, or a single character. Memory exceptions can occur whenever you use this operator because new storage can be allocated.

For information on CThisSimpleString, see the Remarks section of CStringT::CStringT.

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.

CStringT::operator +

Concatenates two strings or a character and a string.

friend CStringT operator+(const CStringT& str1, const CStringT& str2);
friend CStringT operator+(const CStringT& str1, PCXSTR psz2);
friend CStringT operator+(PCXSTR psz1, const CStringT& str2,);
friend CStringT operator+(char ch1, const CStringT& str2,);
friend CStringT operator+(const CStringT& str1, char ch2);
friend CStringT operator+(const CStringT& str1, wchar_t ch2);
friend CStringT operator+(wchar_t ch1, const CStringT& str2,);

Parameters

ch1
An ANSI or Unicode character to concatenate with a string.

ch2
An ANSI or Unicode character to concatenate with a string.

str1
A CStringT to concatenate with a string or character.

str2
A CStringT to concatenate with a string or character.

psz1
A pointer to a null-terminated string to concatenate with a string or character.

psz2
A pointer to a string to concatenate with a string or character.

Remarks

There are seven overload forms of the CStringT::operator+ function. The first version concatenates two existing CStringT objects. The next two concatenate a CStringT object and a null-terminated string. The next two concatenate a CStringT object and an ANSI character. The last two concatenate a CStringT object and a Unicode character.

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.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("dog ")), s2(_T(" awake")), s3;  // Empty CAtlString objects

s1= _T("The ") + s1;
s3= s1 + _T('i');
s3= s3 + _T('s');
s3= s3 + s2;
ASSERT(s3 == _T("The dog is awake"));

CStringT::operator +=

Concatenates characters to the end of the string.

CStringT& operator+=(const CThisSimpleString& str);

template<bool bMFCDLL>
CStringT& operator+=(const const CSimpleStringT<BaseType, bMFCDLL>& str);

template<int t_nSize>
CStringT& operator+=(const CStaticString<XCHAR, t_nSize>& strSrc);
CStringT& operator+=(PCXSTR pszSrc);
CStringT& operator+=(PCYSTR pszSrc);
CStringT& operator+=(char ch);
CStringT& operator+=(unsigned char ch);
CStringT& operator+=(wchar_t ch);
CStringT& operator+=(const VARIANT& var);

Parameters

str
A reference to a CThisSimpleString object.

bMFCDLL
A boolean specifying whether the project is an MFC DLL or not.

BaseType
The string base type.

var
A variant object to concatenate to this string.

ch
An ANSI or Unicode character to concatenate with a string.

pszSrc
A pointer to the original string being concatenated.

strSrc
A CStringT to concatenate to this string.

Remarks

The operator accepts another CStringT object, a character pointer, or a single character. Memory exceptions can occur whenever you use this concatenation operator because new storage can be allocated for characters added to this CStringT object.

For information on CThisSimpleString, see the Remarks section of CStringT::CStringT.

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.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abc"));
ASSERT((s += _T("def")) == _T("abcdef"));

CStringT::operator ==

Determines whether two strings are logically equal.

friend bool operator==(const CStringT& str1, const CStringT& str2) throw();
friend bool operator==(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator==(const CStringT& str1, PCYSTR psz2) throw();
friend bool operator==(const CStringT& str1, XCHAR ch2) throw();
friend bool operator==(PCXSTR psz1, const CStringT& str2) throw();
friend bool operator==(PCYSTR psz1, const CStringT& str2,) throw();
friend bool operator==(XCHAR ch1, const CStringT& str2,) throw();

Parameters

ch1
An ANSI or Unicode character for comparison.

ch2
An ANSI or Unicode character for comparison.

str1
A CStringT for comparison.

str2
A CStringT for comparison.

psz1
A pointer to a null-terminated string for comparison.

psz2
A pointer to a null-terminated string for comparison.

Remarks

Tests whether a string or character on the left side is equal to a string or character on the right side, and returns TRUE or FALSE accordingly.

Example

// typedef CStringT< TCHAR, StrTraitATL< TCHAR > > CAtlString;
CAtlString s1(_T("dog")), s2(_T("f")), s3(_T("dog"));

ASSERT(s1 == _T("dog"));
ASSERT(s2 == _T('f'));
ASSERT(s1 == s3);

CStringT::operator !=

Determines whether two strings are logically not equal.

friend bool operator!=(const CStringT& str1, const CStringT& str2) throw();
friend bool operator!=(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator!=(const CStringT& str1, PCYSTR psz2) throw();
friend bool operator!=(const CStringT& str1, XCHAR ch2) throw();
friend bool operator!=(PCXSTR psz1, const CStringT& str2) throw();
friend bool operator!=(PCYSTR psz1, const CStringT& str2,) throw();
friend bool operator!=(XCHAR ch1, const CStringT& str2,) throw();

Parameters

ch1
An ANSI or Unicode character to concatenate with a string.

ch2
An ANSI or Unicode character to concatenate with a string.

str1
A CStringT for comparison.

str2
A CStringT for comparison.

psz1
A pointer to a null-terminated string for comparison.

psz2
A pointer to a null-terminated string for comparison.

Remarks

Tests if a string or character on the left side isn't equal to a string or character on the right side.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("f")), s3(_T("horse"));

ASSERT(s1 != _T("dog"));
ASSERT(s2 != _T('t'));
ASSERT(s1 != s2);

CStringT::operator <

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

friend bool operator<(const CStringT& str1, const CStringT& str2) throw();
friend bool operator<(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator<(PCXSTR psz1, const CStringT& str2) throw();

Parameters

str1
A CStringT for comparison.

str2
A CStringT for comparison.

psz1
A pointer to a null-terminated string for comparison.

psz2
A pointer to a null-terminated string for comparison.

Remarks

A lexicographical comparison between strings, character by character until:

  • It finds two corresponding characters unequal, and the result of their comparison is taken as the result of the comparison between the strings.

  • It finds no inequalities, but one string has more characters than the other, and the shorter string is considered less than the longer string.

  • It finds no inequalities and finds that the strings have the same number of characters, and so the strings are equal.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("cats")), s3(_T("dogs"));

ASSERT(s1 < _T("dog"));
ASSERT(s1 < _T("cats"));
ASSERT(s2 < _T("cats and dogs"));
ASSERT(s2 < s3);

CStringT::operator >

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

friend bool operator>(const CStringT& str1, const CStringT& str2) throw();
friend bool operator>(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator>(PCXSTR psz1, const CStringT& str2) throw();

Parameters

str1
A CStringT for comparison.

str2
A CStringT for comparison.

psz1
A pointer to a null-terminated string for comparison.

psz2
A pointer to a null-terminated string for comparison.

Remarks

A lexicographical comparison between strings, character by character until:

  • It finds two corresponding characters unequal, and the result of their comparison is taken as the result of the comparison between the strings.

  • It finds no inequalities, but one string has more characters than the other, and the shorter string is considered less than the longer string.

  • It finds no inequalities and finds that the strings have the same number of characters, so the strings are equal.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("cats")), s3(_T("dogs"));
ASSERT(_T("dog") > s1);
ASSERT(_T("cats") > s1);
ASSERT(_T("cats and dogs") > s2);
ASSERT(s3 > s2);

CStringT::operator <=

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

friend bool operator<=(const CStringT& str1, const CStringT& str2) throw();
friend bool operator<=(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator<=(PCXSTR psz1, const CStringT& str2) throw();

Parameters

str1
A CStringT for comparison.

str2
A CStringT for comparison.

psz1
A pointer to a null-terminated string for comparison.

psz2
A pointer to a null-terminated string for comparison.

Remarks

A lexicographical comparison between strings, character by character until:

  • It finds two corresponding characters unequal, and the result of their comparison is taken as the result of the comparison between the strings.

  • It finds no inequalities, but one string has more characters than the other, and the shorter string is considered less than the longer string.

  • It finds no inequalities and finds that the strings have the same number of characters, so the strings are equal.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("cats")), s3(_T("dogs"));

ASSERT(s1 <= _T("dog"));
ASSERT(s1 <= _T("cat"));
ASSERT(s3 <= _T("dogs and cats"));
ASSERT(s2 <= s3);

CStringT::operator >=

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

friend bool operator>=(const CStringT& str1, const CStringT& str2) throw();
friend bool operator>=(const CStringT& str1, PCXSTR psz2) throw();
friend bool operator>=(PCXSTR psz1, const CStringT& str2) throw();

Parameters

str1
A CStringT for comparison.

str2
A CStringT for comparison.

psz1
A pointer to a string for comparison.

psz2
A pointer to a string for comparison.

Remarks

A lexicographical comparison between strings, character by character until:

  • It finds two corresponding characters unequal, and the result of their comparison is taken as the result of the comparison between the strings.

  • It finds no inequalities, but one string has more characters than the other, and the shorter string is considered less than the longer string.

  • It finds no inequalities and finds that the strings have the same number of characters, so the strings are equal.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("cat")), s2(_T("cats")), s3(_T("dogs"));

ASSERT(_T("dog") >= s1);
ASSERT(_T("cats and dogs") >= s2);
ASSERT(s3 >= s2);

CStringT::Remove

Removes all instances of the specified character from the string.

int Remove(XCHAR chRemove);

Parameters

chRemove
The character to be removed from a string.

Return Value

The count of characters removed from the string. Zero if the string isn't changed.

Remarks

Comparisons for the character are case-sensitive.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("This is a test."));
int n = str.Remove(_T('t'));
ASSERT(n == 2);
ASSERT(str == _T("This is a es."));

CStringT::Replace

There are two versions of Replace. The first version replaces one or more copies of a substring by using another substring. Both substrings are null-terminated. The second version replaces one or more copies of a character by using another character. Both versions operate on the character data stored in CStringT.

int Replace(PCXSTR pszOld, PCXSTR pszNew);
int Replace(XCHAR chOld, XCHAR chNew);

Parameters

pszOld
A pointer to a null-terminated string to be replaced by pszNew.

pszNew
A pointer to a null-terminated string that replaces pszOld.

chOld
The character to be replaced by chNew.

chNew
The character replacing chOld.

Return Value

Returns the number of replaced instances of the character or substring, or zero if the string isn't changed.

Remarks

Replace can change the string length because pszNew and pszOld don't have to be the same length, and several copies of the old substring can be changed to the new one. The function does a case-sensitive match.

Examples of CStringT instances are CString, CStringA, and CStringW.

For CStringA, Replace works with ANSI or multibyte (MBCS) characters. For CStringW, Replace works with wide characters.

For CString, the character data type is selected at compile time, based on whether the constants in the following table are defined.

Defined Constant Character Data Type
_UNICODE Wide characters
_MBCS Multi-byte characters
Neither Single-byte characters
Both Undefined

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString strBang(_T("Everybody likes epee fencing"));
int n = strBang.Replace(_T("epee"), _T("foil"));
ASSERT(n == 1);

CStringT::ReverseFind

Searches this CStringT object for the last match of a character.

int ReverseFind(XCHAR ch) const throw();

Parameters

ch
The character to search for.

Return Value

The zero-based index of the last character in this CStringT object that matches the requested character, or -1 if the character isn't found.

Remarks

The function is similar to the run-time function strrchr.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcabc"));
ASSERT(s.ReverseFind(_T('b')) == 4);

Extracts the last (that is, rightmost) nCount characters from this CStringT object and returns a copy of the extracted substring.

CStringT Right(int nCount) const;

Parameters

nCount
The number of characters to extract from this CStringT object.

Return Value

A CStringT object that contains a copy of the specified range of characters. The returned CStringT object can be empty.

Remarks

If nCount exceeds the string length, then the entire string is extracted. Right is similar to the Basic Right function (except that indexes in Basic are zero-based).

For multibyte character sets (MBCS), nCount refers to each 8-bit character; that is, a lead and trail byte in one multibyte character are counted as two characters.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString s(_T("abcdef"));
ASSERT(s.Right(2) == _T("ef"));

CStringT::SetSysString

Reallocates the BSTR pointed to by pbstr and copies the contents of the CStringT object into it, including the NULL character.

BSTR SetSysString(BSTR* pbstr) const;

Parameters

pbstr
A pointer to a character string.

Return Value

The new string.

Remarks

Depending on the contents of the CStringT object, the value of the BSTR referenced by pbstr can change. The function throws a CMemoryException if insufficient memory exists.

This function is normally used to change the value of strings passed by reference for Automation.

Example

BSTR bstr = ::SysAllocString(L"Golf is fun!");

// create a CAtlString and change the OLE
// string to the contents of the BSTR
// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("Soccer is best!"));
BSTR bstr2 = str.SetSysString(&bstr);

// Now, both bstr and bstr2 reference a single instance of
// the "Soccer" string. The "Golf" string has been freed.
ASSERT(bstr2 == bstr);

CStringT::SpanExcluding

Extracts characters from the string, starting with the first character, that aren't in the set of characters identified by pszCharSet.

CStringT SpanExcluding(PCXSTR pszCharSet) const;

Parameters

pszCharSet
A string interpreted as a set of characters.

Return Value

A substring that contains characters in the string that aren't in pszCharSet, beginning with the first character in the string and ending with the first character found in the string that is also in pszCharSet (that is, starting with the first character in the string and up to but excluding the first character in the string that is found pszCharSet). It returns the entire string if no character in pszCharSet is found in the string.

Remarks

SpanExcluding extracts and returns all characters preceding the first occurrence of a character from pszCharSet (in other words, the character from pszCharSet and all characters following it in the string, aren't returned). If no character from pszCharSet is found in the string, then SpanExcluding returns the entire string.

Example

// The string can be delimited by a semicolon(;),
//  a comma(,), a period(.), a dash(-),
// or an apostrophe(').
// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString src(_T("abcdef"));

_tprintf_s(_T("%s"),src.SpanExcluding(_T(";,.-'")));

CStringT::SpanIncluding

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

CStringT SpanIncluding(PCXSTR pszCharSet) const;

Parameters

pszCharSet
A string interpreted as a set of characters.

Return Value

A substring that contains characters in the string that are in pszCharSet, beginning with the first character in the string and ending when a character is found in the string that isn't in pszCharSet. SpanIncluding returns an empty substring if the first character in the string isn't in the specified set.

Remarks

If the first character of the string isn't in the character set, then SpanIncluding returns an empty string. Otherwise, it returns a sequence of consecutive characters that are in the set.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str(_T("cabbage"));
CAtlString res = str.SpanIncluding(_T("abc"));
ASSERT(res == _T("cabba"));
res = str.SpanIncluding(_T("xyz"));
ASSERT(res.IsEmpty());

CStringT::Tokenize

Finds the next token in a target string

CStringT Tokenize(PCXSTR pszTokens, int& iStart) const;

Parameters

pszTokens
A string containing token delimiters. The order of these delimiters isn't important.

iStart
The zero-based index to begin the search.

Return Value

A CStringT object containing the current token value.

Remarks

The Tokenize function finds the next token in the target string. The set of characters in pszTokens specifies possible delimiters of the token to be found. On each call to Tokenize the function starts at iStart, skips leading delimiters, and returns a CStringT object containing the current token, which is the string of characters up to the next delimiter character. The value of iStart is updated to be the position following the ending delimiter character, or -1 if the end of the string was reached. More tokens can be broken out of the rest of the target string by a series of calls to Tokenize, using iStart to keep track of where in the string the next token is to be read. When there are no more tokens, the function will return an empty string and iStart will be set to -1.

Unlike the CRT tokenize functions like strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l, Tokenize doesn't modify the target string.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString str(_T("%First Second#Third"));
CAtlString resToken;
int curPos = 0;

resToken= str.Tokenize(_T("% #"),curPos);
while (resToken != _T(""))
{
   _tprintf_s(_T("Resulting token: %s\n"), resToken);
   resToken = str.Tokenize(_T("% #"), curPos);
};

The output from this example is as follows:

Resulting Token: First
Resulting Token: Second
Resulting Token: Third

CStringT::Trim

Trims leading and trailing characters from the string.

CStringT& Trim(XCHAR chTarget);
CStringT& Trim(PCXSTR pszTargets);
CStringT& Trim();

Parameters

chTarget
The target character to be trimmed.

pszTargets
A pointer to a string containing the target characters to be trimmed. All leading and trailing occurrences of characters in pszTargets will be trimmed from the CStringT object.

Return Value

Returns the trimmed string.

Remarks

Removes all leading and trailing occurrences of one of the following:

  • The character specified by chTarget.

  • All characters found in the string specified by pszTargets.

  • Whitespace.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str;
str = _T("******Soccer is best!?!?!?!?!");

_tprintf_s(_T("Before: \"%s\"\n"), (LPCTSTR)str);
_tprintf_s(_T("After : \"%s\"\n"), (LPCTSTR)str.Trim(_T("?!*")));

// Output:
// --------------------------
// Before: ******Soccer is best!?!?!?!?!
// After: Soccer is best

The output from this example is as follows:

Before: "******Soccer is best, but liquor is quicker!!!!!"
After : "Soccer is best, but liquor is quicker"

CStringT::TrimLeft

Trims leading characters from the string.

CStringT& TrimLeft(XCHAR chTarget);
CStringT& TrimLeft(PCXSTR pszTargets);
CStringT& TrimLeft();

Parameters

chTarget
The target character to be trimmed.

pszTargets
A pointer to a string containing the target characters to be trimmed. All leading occurrences of characters in pszTargets will be trimmed from the CStringT object.

Return Value

The resulting trimmed string.

Remarks

Removes all leading and trailing occurrences of one of the following:

  • The character specified by chTarget.

  • All characters found in the string specified by pszTargets.

  • Whitespace.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str;
str = _T("\t\t   ****Soccer is best!");

_tprintf_s(_T("Before: \"%s\"\n"), (LPCTSTR)str);
_tprintf_s(_T("After: \"%s\"\n"), (LPCTSTR)str.TrimLeft(_T("\t *")));

// Output:
// --------------------------
// Before:     ****Soccer is best!
// After: Soccer is best!

CStringT::TrimRight

Trims trailing characters from the string.

CStringT& TrimRight(XCHAR chTarget);
CStringT& TrimRight(PCXSTR pszTargets);
CStringT& TrimRight();

Parameters

chTarget
The target character to be trimmed.

pszTargets
A pointer to a string containing the target characters to be trimmed. All trailing occurrences of characters in pszTargets will be trimmed from the CStringT object.

Return Value

Returns the CStringT object that contains the trimmed string.

Remarks

Removes trailing occurrences of one of the following:

  • The character specified by chTarget.

  • All characters found in the string specified by pszTargets.

  • Whitespace.

The CStringT& TrimRight(XCHAR chTarget) version accepts one character parameter and removes all copies of that character from the end of CStringT string data. It starts from the end of the string and works toward the front. It stops when it finds a different character or when CStringT runs out of character data.

The CStringT& TrimRight(PCXSTR pszTargets) version accepts a null-terminated string that contains all the different characters to search for. It removes all copies of those characters in the CStringT object. It starts at the end of the string and works toward the front. It stops when it finds a character that isn't in the target string, or when CStringT runs out of character data. It doesn't try to match the whole target string to a substring at the end of CStringT.

The CStringT& TrimRight() version requires no parameters. It trims any trailing whitespace characters from the end of the CStringT string. Whitespace characters can be line breaks, spaces, or tabs.

Example

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;

CAtlString str;
str = _T("Soccer is best!?!?!?!?!");

_tprintf_s(_T("Before: \"%s\"\n"), (LPCTSTR)str);
_tprintf_s(_T("After : \"%s\"\n"), (LPCTSTR)str.TrimRight(_T("?!")));

// Output:
// --------------------------
// Before: Soccer is best!?!?!?!?!
// After: Soccer is best

See also

Hierarchy Chart
ATL/MFC Shared Classes
CSimpleStringT Class