`CStringT` 类

项目
04/03/2023

此类表示 CStringT 对象。

语法

template<typename BaseType, class StringTraits>
class CStringT :
    public CSimpleStringT<BaseType,
        _CSTRING_IMPL_::_MFCDLLTraitsCheck<BaseType, StringTraits>::c_bIsMFCDLLTraits>

参数

BaseType
字符串类的字符类型。可以是以下值之一：

char（适用于 ANSI 字符串）。
wchar_t（适用于 Unicode 字符串）。
TCHAR（适用于 ANSI 和 Unicode 字符串）。

StringTraits
确定字符串类是否需要 C 运行时 (CRT) 库支持以及字符串资源所在的位置。可以是以下值之一：

StrTraitATL<wchar_t | char | TCHAR, ChTraitsCRT<wchar_t | char | TCHAR>>

该类需要 CRT 支持，它在 m_hInstResource（应用程序模块类的成员）指定的模块中搜索资源字符串。
StrTraitATL<wchar_t | char | TCHAR, ChTraitsOS<wchar_t | char |TCHAR>>

该类不需要 CRT 支持，它在 m_hInstResource（应用程序模块类的成员）指定的模块中搜索资源字符串。
StrTraitMFC<wchar_t | char | TCHAR, ChTraitsCRT<wchar_t | char | TCHAR>>

该类需要 CRT 支持，它使用标准 MFC 搜索算法搜索资源字符串。
StrTraitMFC<wchar_t | char | TCHAR, ChTraitsOS<wchar_t | char | TCHAR>>

该类不需要 CRT 支持，它使用标准 MFC 搜索算法搜索资源字符串。

成员

公共构造函数

名称	描述
`CStringT::CStringT`	以各种方式构造 `CStringT` 对象。
`CStringT::~CStringT`	销毁 `CStringT` 对象。

公共方法

名称	描述
`CStringT::AllocSysString`	从 `CStringT` 数据分配 `BSTR`。
`CStringT::AnsiToOem`	将 ANSI 字符集就地转换为 OEM 字符集。
`CStringT::AppendFormat`	将带格式的数据追加到现有 `CStringT` 对象。
`CStringT::Collate`	比较两个字符串（区分大小写，使用特定于区域设置的信息）。
`CStringT::CollateNoCase`	比较两个字符串（不区分大小写，使用特定于区域设置的信息）。
`CStringT::Compare`	比较两个字符串（区分大小写）。
`CStringT::CompareNoCase`	比较两个字符串（不区分大小写）。
`CStringT::Delete`	从字符串中删除一个或多个字符。
`CStringT::Find`	在较大的字符串中查找字符或子字符串。
`CStringT::FindOneOf`	在集中查找第一个匹配的字符。
`CStringT::Format`	像 `sprintf` 那样设置字符串的格式。
`CStringT::FormatMessage`	设置消息字符串的格式。
`CStringT::FormatMessageV`	使用变量参数列表设置消息字符串的格式。
`CStringT::FormatV`	使用参数变量列表设置字符串的格式。
`CStringT::GetEnvironmentVariable`	将字符串设置为指定的环境变量的值。
`CStringT::Insert`	在字符串中的给定索引处插入单个字符或子字符串。
`CStringT::Left`	提取字符串的左侧部分。
`CStringT::LoadString`	从 Windows 资源加载现有的 `CStringT` 对象。
`CStringT::MakeLower`	将此字符串中的所有字符转换为小写字符。
`CStringT::MakeReverse`	反转字符串。
`CStringT::MakeUpper`	将此字符串中的所有字符转换为大写字符。
`CStringT::Mid`	提取字符串的中间部分。
`CStringT::OemToAnsi`	将 OEM 字符集就地转换为 ANSI 字符集。
`CStringT::Remove`	从字符串中删除指定的字符。
`CStringT::Replace`	将指定的字符替换为其他字符。
`CStringT::ReverseFind`	在较大的字符串中查找字符；从末尾开始。
`CStringT::Right`	提取字符串的右侧部分。
`CStringT::SetSysString`	使用 `CStringT` 对象中的数据设置现有 `BSTR` 对象。
`CStringT::SpanExcluding`	从字符串中提取不在 `pszCharSet` 标识的字符集中的字符，从第一个字符开始。
`CStringT::SpanIncluding`	提取仅包含集中的字符的子字符串。
`CStringT::Tokenize`	提取目标字符串中的指定标记。
`CStringT::Trim`	从字符串中剪裁掉所有前导和尾部空白字符。
`CStringT::TrimLeft`	从字符串中剪裁掉前导空白字符。
`CStringT::TrimRight`	从字符串中剪裁掉尾部空白字符。

运算符

名称	描述
`CStringT::operator =`	为 `CStringT` 对象分配新值。
`CStringT::operator +`	串联两个字符串，或串联一个字符和一个字符串。
`CStringT::operator +=`	将新字符串串联到现有字符串的末尾。
`CStringT::operator ==`	确定两个字符串在逻辑上是否相等。
`CStringT::operator !=`	确定两个字符串在逻辑上是否不相等。
`CStringT::operator <`	确定运算符左侧的字符串是否小于右侧的字符串。
`CStringT::operator >`	确定运算符左侧的字符串是否大于右侧的字符串。
`CStringT::operator <=`	确定运算符左侧的字符串是否小于等于右侧的字符串。
`CStringT::operator >=`	确定运算符左侧的字符串是否大于等于右侧的字符串。

注解

CStringT 继承自 CSimpleStringT 类。字符操作、排序和搜索等高级功能由 CStringT 实现。

注意

CStringT 对象能够引发异常。当 CStringT 对象因任何原因而耗尽内存时会发生这种情况。

CStringT 对象由可变长度的字符序列组成。 CStringT 使用类似于 Basic 的语法提供函数和运算符。串联和比较运算符以及简化的内存管理相结合，使 CStringT 对象比普通字符数组更易于使用。

注意

尽管可以创建包含嵌入式 null 字符的 CStringT 实例，但我们建议不要这样做。对包含嵌入式 null 空字符的 CStringT 对象调用方法和运算符可能会生成意外的结果。

通过 BaseType 和 StringTraits 参数的不同组合，CStringT 对象可以采用 ATL 库预定义的以下类型。

如果在 ATL 应用程序中使用：

CString、CStringA 和 CStringW 是从 MFC DLL (MFC90.DLL) 导出的，而永远不会从用户 DLL 导出。这样做是为了防止多次定义 CStringT。

注意

如果代码包含使用 CStringT 导出字符串类中所述的链接器错误解决方法，应该删除该代码。不再需要它。

以下字符串类型在基于 MFC 的应用程序中可用：

CStringT 类型	声明
`CStringA`	支持 CRT 的 ANSI 字符类型字符串。
`CStringW`	支持 CRT 的 Unicode 字符类型字符串。
`CString`	支持 CRT 的 ANSI 和 Unicode 字符类型。

以下字符串类型在定义了 ATL_CSTRING_NO_CRT 的项目中可用：

CStringT 类型	声明
`CAtlStringA`	不支持 CRT 的 ANSI 字符类型字符串。
`CAtlStringW`	不支持 CRT 的 Unicode 字符类型字符串。
`CAtlString`	不支持 CRT 的 ANSI 和 Unicode 字符类型。

以下字符串类型在未定义 ATL_CSTRING_NO_CRT 的项目中可用：

CStringT 类型	声明
`CAtlStringA`	支持 CRT 的 ANSI 字符类型字符串。
`CAtlStringW`	支持 CRT 的 Unicode 字符类型字符串。
`CAtlString`	支持 CRT 的 ANSI 和 Unicode 字符类型。

CString 对象还具有以下特征：

CStringT 对象可以因串联操作而扩展。
CStringT 对象遵循“值语义”。将 CStringT 对象视为实际字符串，而不是指向字符串的指针。
可以任意将 PCXSTR 函数参数替换为 CStringT 对象。
字符串缓冲区的自定义内存管理。有关详细信息，请参阅内存管理和 CStringT。

CStringT 预定义类型

由于 CStringT 使用模板参数来定义支持的字符类型（wchar_t 或 char），因此方法参数类型有时很复杂。为了简化此问题，可以定义一组预定义类型并在整个 CStringT 类中使用。下表列出了各种类型：

名称	描述
`XCHAR`	与 `CStringT` 对象具有相同字符类型的单个字符（`wchar_t` 或 `char`）。
`YCHAR`	与 `CStringT` 对象具有相反字符类型的单个字符（`wchar_t` 或 `char`）。
`PXSTR`	指向与 `CStringT` 对象具有相同字符类型的字符串（`wchar_t` 或 `char`）的指针。
`PYSTR`	指向与 `CStringT` 对象具有相反字符类型的字符串（`wchar_t` 或 `char`）的指针。
`PCXSTR`	指向与 `CStringT` 对象具有相同字符类型的 `const` 字符串（`wchar_t` 或 `char`）的指针。
`PCYSTR`	指向与 `CStringT` 对象具有相反字符类型的 `const` 字符串（`wchar_t` 或 `char`）的指针。

注意

以前使用未记录的 CString 方法（例如 AssignCopy）的代码必须替换为使用以下记录的 CStringT 方法（例如 GetBuffer 或 ReleaseBuffer）的代码。这些方法继承自 CSimpleStringT。

继承层次结构

CSimpleStringT

CStringT

要求

Header	用于
`cstringt.h`	仅限 MFC 的字符串对象
`atlstr.h`	非 MFC 字符串对象

`CStringT::AllocSysString`

分配 BSTR 类型的自动化兼容字符串，并将 CStringT 对象的内容（包括结尾的 null 字符）复制到其中。

BSTR AllocSysString() const;

返回值

新分配的字符串。

注解

在 MFC 程序中，如果内存不足，将引发 CMemoryException 类。在 ATL 程序中，将引发 CAtlException。此函数通常用于返回自动化的字符串。

通常，如果将此字符串作为 [in] 参数传递给 COM 函数，则需要调用方释放该字符串。可以按照 Windows SDK 中所述使用 SysFreeString 来完成此操作。有关详细信息，请参阅为 BSTR 分配和释放内存。

有关 Windows 中 OLE 分配函数的详细信息，请参阅 Windows SDK 中的 SysAllocString。

示例

以下示例演示了 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`

将此 CStringT 对象中的所有字符从 ANSI 字符集转换为 OEM 字符集。

void AnsiToOem();

注解

如果定义了 _UNICODE，则该函数不可用。

示例

// 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`

将带格式的数据追加到现有 CStringT 对象。

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

参数

pszFormat
格式控件字符串

nFormatID
包含格式控制字符串的字符串资源标识符。

argument
可选参数。

注解

此函数设置一系列字符和值的格式并将其追加到 CStringT 中。每个可选参数（如果有）将根据 pszFormat 中的相应格式规范或者从 nFormatID 标识的字符串资源进行转换和追加。

示例

// 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`

使用泛型文本函数 _tcscoll 比较两个字符串。

int Collate(PCXSTR psz) const throw();

参数

psz
用于比较的另一个字符串。

返回值

如果字符串相同，则为 0；如果此 CStringT 对象小于 psz，则 < 0；如果此 CStringT 对象大于 psz，则 > 0。

备注

在 TCHAR.H 中定义的泛型文本函数 _tcscoll 将映射到 strcoll、wcscoll 或 _mbscoll，具体取决于在编译时定义的字符集。每个函数根据当前使用的代码页对字符串执行区分大小写的比较。有关详细信息，请参阅 strcoll、wcscoll、_mbscoll、_strcoll_l、_wcscoll_l、_mbscoll_l。

`CStringT::CollateNoCase`

使用泛型文本函数 _tcscoll 比较两个字符串。

int CollateNoCase(PCXSTR psz) const throw();

参数

psz
用于比较的另一个字符串。

返回值

如果字符串相同，则为 0（忽略大小写）；如果此 CStringT 对象小于 psz（忽略大小写），则 < 0；如果此 CStringT 对象大于 psz（忽略大小写），则 > 0。

注解

在 TCHAR.H 中定义的泛型文本函数 _tcscoll 将映射到 stricoll、wcsicoll 或 _mbsicoll，具体取决于在编译时定义的字符集。每个函数根据当前使用的代码页对字符串执行不区分大小写的比较。有关详细信息，请参阅 strcoll、wcscoll、_mbscoll、_strcoll_l、_wcscoll_l、_mbscoll_l。

示例

// 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`

比较两个字符串（区分大小写）。

int Compare(PCXSTR psz) const;

参数

psz
用于比较的另一个字符串。

返回值

如果字符串相同，则为 0；如果此 CStringT 对象小于 psz，则 < 0；如果此 CStringT 对象大于 psz，则 > 0。

备注

在 TCHAR.H 中定义的泛型文本函数 _tcscmp 将映射到 strcmp、wcscmp 或 _mbscmp，具体取决于在编译时定义的字符集。每个函数对字符串执行区分大小写的比较，并且不受区域设置的影响。有关详细信息，请参阅 strcmp、wcscmp、_mbscmp。

如果字符串包含嵌入的 null 值，则在比较时，该字符串将被视为在第一个嵌入的 null 字符处截断。

示例

以下示例演示了 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`

比较两个字符串（不区分大小写）。

int CompareNoCase(PCXSTR psz) const throw();

参数

psz
用于比较的另一个字符串。

返回值

如果字符串相同，则为 0（忽略大小写）；如果此 CStringT 对象小于 psz（忽略大小写），则 <0；如果此 CStringT 对象大于 psz（忽略大小写），则 >0。

备注

在 TCHAR.H 中定义的泛型文本函数 _tcsicmp 将映射到 _stricmp、_wcsicmp 或 _mbsicmp，具体取决于在编译时定义的字符集。每个函数对字符串执行不区分大小写的比较。比较取决于区域设置的 LC_CTYPE 方面而不是 LC_COLLATE。有关详细信息，请参阅 _stricmp、_wcsicmp、_mbsicmp、_stricmp_l、_wcsicmp_l、_mbsicmp_l。

示例

// 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`

构造 CStringT 对象。

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

参数

pch
指向长度为 nLength 的字符（不以 null 结尾）数组的指针。

nLength
pch 中的字符数。

ch
单个字符。

pszSrc
要复制到此 CStringT 对象的以 null 结尾的字符串。

pStringMgr
指向 CStringT 对象的内存管理器的指针。有关 IAtlStringMgr 以及 CStringT 内存管理的详细信息，请参阅内存管理和 CStringT。

strSrc
要复制到此 CStringT 对象中的现有 CStringT 对象。有关 CThisString 和 CThisSimpleString 的详细信息，请参阅“备注”部分。

varSrc
要复制到此 CStringT 对象的变体对象。

BaseType
字符串类的字符类型。可以是以下值之一：

char（适用于 ANSI 字符串）。

wchar_t（适用于 Unicode 字符串）。

TCHAR（适用于 ANSI 和 Unicode 字符串）。

bMFCDLL
指定项目是 MFC DLL (TRUE) 或者不是 MFC DLL (FALSE) 的布尔值。

SystemString
必须是 System::String，并且必须使用 /clr 编译项目。

pString
CStringT 对象的句柄。

备注

由于构造函数将输入数据复制到新的已分配存储中，因此可能会导致内存异常。其中一些构造函数充当转换函数。例如，它允许替换需要 CStringT 对象的 LPTSTR。

CStringT (LPCSTRlpsz)：从 ANSI 字符串构造 Unicode CStringT。还可以使用此构造函数来加载字符串资源，如以下示例所示。
CStringT(LPCWSTRlpsz)：从 Unicode 字符串构造 CStringT。
CStringT (const unsigned char*psz)：允许从指向 unsigned char 的指针构造 CStringT。

注意

定义 _CSTRING_DISABLE_NARROW_WIDE_CONVERSION 宏以关闭 ANSI 和 Unicode 字符串之间的隐式字符串转换。该宏从支持转换的编译构造函数中排除。

strSrc 参数可以是 CStringT 或 CThisSimpleString 对象。对于 CStringT，请使用其默认实例化之一（CString、CStringA 或 CStringW）；对于 CThisSimpleString，请使用 this 指针。 CThisSimpleString 声明 CSimpleStringT 类的实例，该类是一个较小的字符串类，其内置功能比 CStringT 类少。

重载运算符 CSimpleStringT<>&() 从 CSimpleStringT 声明构造 CStringT 对象。

注意

示例

// 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`

销毁 CStringT 对象。

~CStringT() throw();

备注

销毁 CStringT 对象。

`CStringT::Delete`

删除字符串中的一个或多个字符，从给定索引处的字符开始删除。

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

参数

iIndex
CStringT 对象中要删除的第一个字符的从零开始的索引。

nCount
要删除的字符数。

返回值

更改后的字符串的长度。

注解

如果 nCount 比该字符串更长，则会删除该字符串的其余部分。

示例

// 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`

在此字符串中搜索某个字符或子字符串的第一个匹配项。

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

参数

pszSub
要搜索的子字符串。

iStart
字符串中要开始搜索的字符的索引，或者为 0（表示从头开始搜索）。

ch
要搜索的单个字符。

返回值

此 CStringT 对象中与请求的子字符串或字符匹配的第一个字符的从零开始的索引；如果找不到该子字符串或字符，则返回 -1。

备注

该函数将重载以接受单个字符（类似于运行时函数 strchr）和字符串（类似于 strstr）。

示例

// 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`

在此字符串中搜索与 pszCharSet 中包含的任何字符匹配的第一个字符。

int FindOneOf(PCXSTR pszCharSet) const throw();

参数

pszCharSet
包含要匹配的字符的字符串。

返回值

既在此字符串中，也在 pszCharSet 中的第一个字符的从零开始的索引；如果没有匹配项，则返回 -1。

备注

查找 pszCharSet 中首次出现的任何字符。

示例

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

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

`CStringT::Format`

将带格式的数据写入 CStringT，如同 sprintf_s 将数据格式设置为 C 样式字符数组一样。

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

参数

nFormatID
包含格式控制字符串的字符串资源标识符。

pszFormat
格式控件字符串

argument
可选参数。

注解

此函数设置一系列字符和值的格式并将其存储在 CStringT 中。每个可选参数（如果有）将根据 pszFormat 中的相应格式规范或者从 nFormatID 标识的字符串资源进行转换和输出。

如果将字符串对象本身作为参数提供给 Format，则调用将会失败。例如，以下代码会导致不可预知的结果：

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

有关详细信息，请参阅格式规范语法：printf 和 wprintf 函数。

示例

// 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`

设置消息字符串的格式。

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

参数

nFormatID
包含无格式消息文本的字符串资源标识符。

pszFormat
指向格式控制字符串。将扫描它以进行插入并相应地设置格式。格式字符串类似于运行时函数 printf 样式的格式字符串，不同之处在于它允许以任意顺序插入参数。

argument
可选参数。

注解

该函数要求提供一个消息定义作为输入。该消息定义由 pszFormat 确定，或者由 nFormatID 标识的字符串资源确定。该函数将带格式的消息文本复制到 CStringT 对象，并根据请求处理任何嵌入的插入序列。

注意

FormatMessage 尝试为带格式的新字符串分配系统内存。如果此尝试失败，则会自动引发内存异常。

每个插入必须在 pszFormat 或 nFormatID 参数之后具有相应的参数。在消息文本中，支持多个用于动态设置消息格式的转义序列。有关详细信息，请参阅 Windows SDK 中的 Windows FormatMessage 函数。

示例

// 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`

使用变量参数列表设置消息字符串的格式。

void FormatMessageV(PCXSTR pszFormat, va_list* pArgList);

参数

pszFormat
指向格式控制字符串。将扫描它以进行插入并相应地设置格式。格式字符串类似于运行时函数 printf 样式的格式字符串，不同之处在于它允许以任意顺序插入参数。

pArgList
指向参数列表的指针。

注解

该函数要求提供一个消息定义作为输入（由 pszFormat 确定）。该函数将带格式的消息文本和参数变量列表复制到 CStringT 对象，并根据请求处理任何嵌入的插入序列。

注意

FormatMessageV 调用 CStringT::FormatMessage，后者尝试为带格式的新字符串分配系统内存。如果此尝试失败，则会自动引发内存异常。

有关详细信息，请参阅 Windows SDK 中的 Windows FormatMessage 函数。

`CStringT::FormatV`

使用变量参数列表设置消息字符串的格式。

void FormatV(PCXSTR pszFormat, va_list args);

参数

args
指向参数列表的指针。

备注

将带格式的字符串和参数变量列表写入 CStringT 字符串，如同 vsprintf_s 将数据格式设置为 C 样式字符数组一样。

示例

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`

将字符串设置为指定的环境变量的值。

BOOL GetEnvironmentVariable(PCXSTR pszVar);

参数

pszVar
指向用于指定环境变量的 null 结尾字符串的指针。

返回值

如果成功，则不为 0；否则为 0。

备注

从调用进程的环境块中检索指定变量的值。该值采用 null 结尾的字符串形式。

示例

// 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`

在字符串中的给定索引处插入单个字符或子字符串。

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

参数

iIndex
将在其前面执行插入的字符的索引。

psz
指向要插入的子字符串的指针。

ch
要插入的字符。

返回值

更改后的字符串的长度。

备注

iIndex 参数标识要移动的、以便为字符或子字符串腾出空间的第一个字符。如果 nIndex 为零，则插入将发生在整个字符串之前。如果 nIndex 大于字符串的长度，该函数将串联当前字符串和 ch 或 psz 提供的新材料。

示例

// 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`

从此 CStringT 对象中提取最左侧 nCount 字符并返回已提取的子字符串的副本。

CStringT Left(int nCount) const;

参数

nCount
从此 CStringT 对象中提取的字符的数量。

返回值

包含指定范围内的字符的副本的 CStringT 对象。返回的 CStringT 对象可以为空。

备注

如果 nCount 超过字符串长度，则提取整个字符串。 Left 类似于 Basic Left 函数。

对于多字节字符集 (MBCS)，nCount 将每 8 位序列视为一个字符，以便让 nCount 返回多字节字符的数目乘以 2。

示例

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

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

`CStringT::LoadString`

将 nID 标识的 Windows 字符串资源读入现有的 CStringT 对象。

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

参数

hInstance
模块实例的句柄。

nID
Windows 字符串资源 ID。

wLanguageID
字符串资源的语言。

返回值

如果资源加载成功，则返回非零值；否则返回 0。

备注

使用指定的语言 (wLanguage) 从指定的模块 (hInstance) 加载字符串资源 (nID)。

示例

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

CAtlString s;
s.LoadString(IDS_APP_TITLE);

`CStringT::MakeLower`

将 CStringT 对象转换为小写字符串。

CStringT& MakeLower();

返回值

生成的小写字符串。

示例

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

CAtlString s(_T("ABC"));

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

`CStringT::MakeReverse`

反转 CStringT 对象中的字符顺序。

CStringT& MakeReverse();

返回值

生成的反转字符串。

示例

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

CAtlString s(_T("abc"));

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

`CStringT::MakeUpper`

将 CStringT 对象转换为大写字符串。

CStringT& MakeUpper();

返回值

生成的大写字符串。

注解

示例

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

CAtlString s(_T("abc"));

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

`CStringT::Mid`

从此 CStringT 对象中提取长度为 nCount 个字符的子字符串，从位置 iFirst 处开始（从零开始）。

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

参数

iFirst
此 CStringT 对象中的、要包含在提取的子字符串中的第一个字符的从零开始的索引。

nCount
从此 CStringT 对象中提取的字符的数量。如果未提供此参数，则提取字符串的其余部分。

返回值

包含指定范围内的字符的副本的 CStringT 对象。返回的 CStringT 对象可以为空。

备注

该函数返回提取的子字符串的副本。 Mid 类似于 Basic Mid 函数（只不过在 Basic 中，索引从 1 开始）。

对于多字节字符集 (MBCS)，nCount 指的是每个 8 位字符；即，一个多字节字符中的前导字节和尾部字节计为两个字符。

示例

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

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

`CStringT::OemToAnsi`

将此 CStringT 对象中的所有字符从 OEM 字符集转换为 ANSI 字符集。

void OemToAnsi();

注解

如果定义了 _UNICODE，则此函数不可用。

示例

请参阅 CStringT::AnsiToOem 的示例。

`CStringT::operator =`

为字符串分配新值。

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

参数

strSrc
分配到此字符串的 CStringT。

str
对 CThisSimpleString 对象的引用。

bMFCDLL
一个布尔值，指定项目是否为 MFC DLL。

BaseType
字符串基类型。

var
要分配到此字符串的变体对象。

ch
要分配到该字符串的 ANSI 或 Unicode 字符。

pszSrc
指向被分配的原始字符串的指针。

备注

赋值运算符接受另一个 CStringT 对象、字符指针或单个字符。每当使用此运算符，都可能发生内存异常，因为可以分配新存储。

有关 CThisSimpleString 的信息，请参阅 CStringT::CStringT 的“备注”部分。

注意

`CStringT::operator +`

串联两个字符串，或串联一个字符和一个字符串。

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,);

参数

ch1
要与字符串串联的 ANSI 或 Unicode 字符。

ch2
要与字符串串联的 ANSI 或 Unicode 字符。

str1
要与字符串或字符串联的 CStringT。

str2
要与字符串或字符串联的 CStringT。

psz1
指向要与字符串或字符串联的 null 结尾字符串的指针。

psz2
指向要与字符串或字符串联的字符串的指针。

备注

CStringT::operator+ 函数有七种重载形式。第一个版本串联两个现有的 CStringT 对象。接下来的两个版本串联一个 CStringT 对象和一个 null 结尾的字符串。接下来的两个版本串联一个 CStringT 对象和一个 ANSI 字符。最后两个版本串联一个 CStringT 对象和一个 Unicode 字符。

注意

示例

// 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 +=`

将字符串联到字符串的末尾。

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

参数

str
对 CThisSimpleString 对象的引用。

bMFCDLL
一个布尔值，指定项目是否为 MFC DLL。

BaseType
字符串基类型。

var
要串联到此字符串的变体对象。

ch
要与字符串串联的 ANSI 或 Unicode 字符。

pszSrc
指向被串联的原始字符串的指针。

strSrc
要串联到此字符串的 CStringT。

备注

运算符接受另一个 CStringT 对象、字符指针或单个字符。每当使用此串联运算符，都可能发生内存异常，因为可为添加到此 CStringT 对象的字符分配新存储。

有关 CThisSimpleString 的信息，请参阅 CStringT::CStringT 的“备注”部分。

注意

示例

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

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

`CStringT::operator ==`

确定两个字符串在逻辑上是否相等。

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();

参数

ch1
用于比较的 ANSI 或 Unicode 字符。

ch2
用于比较的 ANSI 或 Unicode 字符。

str1
用于比较的 CStringT。

str2
用于比较的 CStringT。

psz1
指向用于比较的 null 结尾字符串的指针。

psz2
指向用于比较的 null 结尾字符串的指针。

注解

测试左侧的字符串或字符是否等于右侧的字符串或字符，并相应地返回 TRUE 或 FALSE。

示例

// 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 !=`

确定两个字符串在逻辑上是否不相等。

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();

参数

ch1
要与字符串串联的 ANSI 或 Unicode 字符。

ch2
要与字符串串联的 ANSI 或 Unicode 字符。

str1
用于比较的 CStringT。

str2
用于比较的 CStringT。

psz1
指向用于比较的 null 结尾字符串的指针。

psz2
指向用于比较的 null 结尾字符串的指针。

注解

测试左侧的字符串或字符是否不等于右侧的字符串或字符。

示例

// 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 <`

确定运算符左侧的字符串是否小于右侧的字符串。

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();

参数

str1
用于比较的 CStringT。

str2
用于比较的 CStringT。

psz1
指向用于比较的 null 结尾字符串的指针。

psz2
指向用于比较的 null 结尾字符串的指针。

备注

按字典顺序逐字符比较字符串：

如果找到两个不相等的相应字符，则将比较结果作为字符串之间比较的结果。
如果找到的所有字符完全相同，但其中一个字符串的字符数要多于另一个字符串的字符数，则将较短的字符串视为小于较长的字符串。
如果找到的所有字符完全相同且字符串的字符数也相同，则这两个字符串视为相等。

示例

// 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 >`

确定运算符左侧的字符串是否大于右侧的字符串。

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();

参数

str1
用于比较的 CStringT。

str2
用于比较的 CStringT。

psz1
指向用于比较的 null 结尾字符串的指针。

psz2
指向用于比较的 null 结尾字符串的指针。

注解

按字典顺序逐字符比较字符串：

如果找到两个不相等的相应字符，则将比较结果作为字符串之间比较的结果。
如果找到的所有字符完全相同，但其中一个字符串的字符数要多于另一个字符串的字符数，则将较短的字符串视为小于较长的字符串。
它没找到任何不相等的字符且字符串具有相同数量的字符，则字符串视为相等。

示例

// 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 <=`

确定运算符左侧的字符串是否小于等于右侧的字符串。

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();

参数

str1
用于比较的 CStringT。

str2
用于比较的 CStringT。

psz1
指向用于比较的 null 结尾字符串的指针。

psz2
指向用于比较的 null 结尾字符串的指针。

注解

按字典顺序逐字符比较字符串：

如果找到两个不相等的相应字符，则将比较结果作为字符串之间比较的结果。
如果找到的所有字符完全相同，但其中一个字符串的字符数要多于另一个字符串的字符数，则将较短的字符串视为小于较长的字符串。
它没找到任何不相等的字符且字符串具有相同数量的字符，则字符串视为相等。

示例

// 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 >=`

确定运算符左侧的字符串是否大于等于右侧的字符串。

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();

参数

str1
用于比较的 CStringT。

str2
用于比较的 CStringT。

psz1
指向用于比较的字符串的指针。

psz2
指向用于比较的字符串的指针。

备注

按字典顺序逐字符比较字符串：

如果找到两个不相等的相应字符，则将比较结果作为字符串之间比较的结果。
如果找到的所有字符完全相同，但其中一个字符串的字符数要多于另一个字符串的字符数，则将较短的字符串视为小于较长的字符串。
它没找到任何不相等的字符且字符串具有相同数量的字符，则字符串视为相等。

示例

// 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`

从字符串中删除指定字符的所有实例。

int Remove(XCHAR chRemove);

参数

chRemove
要从字符串中删除的字符。

返回值

从字符串中删除的字符数。如果字符串未更改，则为返回零。

备注

字符比较区分大小写。

示例

// 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`

Replace 有两个版本。第一个版本使用另一个子字符串替换一个或多个子字符串副本。两个子字符串都以 null 结尾。第二个版本使用另一个字符替换一个或多个字符副本。这两个版本都对存储在 CStringT 中的字符数据执行操作。

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

参数

pszOld
指向要替换为 pszNew 的 null 结尾字符串的指针。

pszNew
指向要替换 pszOld 的 null 结尾字符串的指针。

chOld
要替换为 chNew 的字符。

chNew
要替换 chOld 的字符。

返回值

返回字符或子字符串的被替换实例数；如果字符串未更改，则返回零。

备注

Replace 可以更改字符串长度，因为 pszNew 和 pszOld 的长度不必相同，并且可将旧子字符串的多个副本更改为新的子字符串。该函数执行区分大小写的匹配。

CStringT 实例的示例为 CString、CStringA 和 CStringW。

对于 CStringA，Replace 使用 ANSI 或多字节 (MBCS) 字符。对于 CStringW，Replace 使用宽字符。

对于 CString，将在编译时根据是否定义了下表中的常量来选择字符数据类型。

定义常量	字符数据类型
`_UNICODE`	宽字符
`_MBCS`	多字节字符
两者均未选中	单字节字符
两者	未定义

示例

// 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`

在此 CStringT 对象中搜索字符的最后一个匹配项。

int ReverseFind(XCHAR ch) const throw();

参数

ch
要搜索的字符。

返回值

此 CStringT 对象中的、与请求的字符匹配的最后一个字符的从零开始的索引，如果找不到该字符，则返回 -1。

备注

该函数类似于运行时函数 strrchr。

示例

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

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

`CStringT::Right`

从此 CStringT 对象中提取最后一个（即最右侧的）nCount 字符并返回已提取的子字符串的副本。

CStringT Right(int nCount) const;

参数

nCount
从此 CStringT 对象中提取的字符的数量。

返回值

包含指定范围内的字符的副本的 CStringT 对象。返回的 CStringT 对象可以为空。

备注

如果 nCount 超过字符串长度，则提取整个字符串。 Right 类似于 Basic Right 函数（只不过在 Basic 中，索引从零开始）。

对于多字节字符集 (MBCS)，nCount 指的是每个 8 位字符；即，一个多字节字符中的前导字节和尾部字节计为两个字符。

示例

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

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

`CStringT::SetSysString`

重新分配 pbstr 指向的 BSTR 并将 CStringT 对象的内容（包括 NULL 字符）复制到其中。

BSTR SetSysString(BSTR* pbstr) const;

参数

pbstr
指向字符串的指针。

返回值

新字符串。

备注

根据 CStringT 对象的内容，pbstr 引用的 BSTR 的值可能会更改。如果内存不足，该函数将引发 CMemoryException。

此函数通常用于更改通过引用传递给自动化的字符串的值。

示例

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`

从字符串中提取不在 pszCharSet 标识的字符集中的字符，从第一个字符开始。

CStringT SpanExcluding(PCXSTR pszCharSet) const;

参数

pszCharSet
解释为一组字符的字符串。

返回值

一个子字符串，它包含该字符串中的、但不在 pszCharSet 中的字符，并以该字符串中的第一个字符开头，以同时在该字符串和 pszCharSet 中找到的第一个字符结尾（即，以该字符串中的第一个字符开头，后面是在 pszCharSet 中找到的字符串的第一个字符，但不包括该字符）。如果在该字符串中找不到 pszCharSet 中的字符，则返回整个字符串。

备注

SpanExcluding 提取并返回首次出现 pszCharSet 中的字符之前的所有字符（换言之，不返回 pszCharSet 中的字符，以及该字符串中该字符后面的所有字符）。如果在该字符串中找不到 pszCharSet 中的字符，则 SpanExcluding 返回整个字符串。

示例

// 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("World Cup '98"));

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

`CStringT::SpanIncluding`

从字符串中提取在 pszCharSet 标识的字符集中的字符，从第一个字符开始。

CStringT SpanIncluding(PCXSTR pszCharSet) const;

参数

pszCharSet
解释为一组字符的字符串。

返回值

一个子字符串，它包含该字符串以及 pszCharSet 中的字符，以该字符串中的第一个字符开头，以在该字符串中找到的、但无法在 pszCharSet 中找到的字符结尾。如果该字符串中的第一个字符不在指定的集中，SpanIncluding 将返回空子字符串。

注解

如果该字符串的第一个字符不在字符集中，则 SpanIncluding 将返回空字符串。否则，它将返回该集中的一系列连续字符。

示例

// 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`

在目标字符串中查找下一个标记

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

参数

pszTokens
包含标记分隔符的字符串。这些分隔符的顺序并不重要。

iStart
从其开始进行搜索的从零开始的索引。

返回值

包含当前标记值的 CStringT 对象。

注解

Tokenize 函数在目标字符串中查找下一个标记。 pszTokens 中的字符集指定要查找的标记的可能分隔符。每次调用 Tokenize 时，该函数都从 iStart 开始，跳过前导分隔符，并返回一个包含当前标记的 CStringT 对象，该标记是下一个分隔符前面的字符串。 iStart 的值将更新为结束分隔符之后的位置；如果到达字符串的末尾，则为 -1。通过对 Tokenize 发出一系列调用，可以从目标字符串的其余部分分解出更多标记。可以使用 iStart 来跟踪字符串中要读取下一个标记的位置。如果没有更多标记，该函数将返回一个空字符串，并且 iStart 将设置为 -1。

与 strtok_s、_strtok_s_l、wcstok_s、_wcstok_s_l、_mbstok_s、_mbstok_s_l 等 CRT 标记化函数不同，Tokenize 不会修改目标字符串。

示例

// 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);
};

此示例的输出如下所示：

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

`CStringT::Trim`

剪裁掉字符串中的前导和尾部字符。

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

参数

chTarget
要剪裁的目标字符。

pszTargets
指向包含要剪裁的目标字符的字符串的指针。 pszTargets 中出现在头部和尾部的所有字符都将从 CStringT 对象中剪裁掉。

返回值

返回已剪裁的字符串。

备注

删除出现在头部和尾部的下列所有字符之一：

chTarget 指定的字符。
在 pszTargets 指定的字符串中找到的所有字符。
空白字符。

示例

// 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

此示例的输出如下所示：

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

`CStringT::TrimLeft`

剪裁掉字符串中的前导字符。

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

参数

chTarget
要剪裁的目标字符。

pszTargets
指向包含要剪裁的目标字符的字符串的指针。 pszTargets 中出现在头部所有字符都将从 CStringT 对象中剪裁掉。

返回值

最终的已剪裁字符串。

注解

删除出现在头部和尾部的下列所有字符之一：

chTarget 指定的字符。
在 pszTargets 指定的字符串中找到的所有字符。
空白字符。

示例

// 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`

剪裁掉字符串中的尾部字符。

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

参数

chTarget
要剪裁的目标字符。

pszTargets
指向包含要剪裁的目标字符的字符串的指针。 pszTargets 中出现在尾部所有字符都将从 CStringT 对象中剪裁掉。

返回值

返回包含已剪裁的字符串的 CStringT 对象。

备注

删除出现在尾部的下列字符之一：

chTarget 指定的字符。
在 pszTargets 指定的字符串中找到的所有字符。
空白字符。

CStringT& TrimRight(XCHAR chTarget) 版本接受一个字符参数，并从 CStringT 字符串数据的末尾删除该字符的所有副本。它从该字符串的末尾开始一直向前面进行处理。当找到不同的字符或者当 CStringT 处理完字符数据时，它将会停止。

CStringT& TrimRight(PCXSTR pszTargets) 版本接受以 null 结尾的字符串，其中包含要搜索的所有不同字符。它会删除 CStringT 对象中这些字符的所有副本。它从该字符串的末尾开始一直向前面进行处理。当找到一个不在目标字符串中的字符，或者当 CStringT 处理完字符数据时，它将会停止。它不会尝试将整个目标字符串与 CStringT 末尾的子字符串进行匹配。

CStringT& TrimRight() 版本不需要参数。它会从 CStringT 字符串的末尾剪裁掉任何尾部空白字符。空白字符可以是换行符、空格或制表符。

示例

// 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

另请参阅

层次结构图
 ATL/MFC 共享类
 CSimpleStringT 类

CStringT 类

语法

参数

成员

公共构造函数

公共方法

运算符

注解

CStringT 预定义类型

继承层次结构

要求

CStringT::AllocSysString

返回值

注解

示例

CStringT::AnsiToOem

注解

示例

CStringT::AppendFormat

参数

注解

示例

CStringT::Collate

参数

返回值

备注

CStringT::CollateNoCase

参数

返回值

注解

示例

CStringT::Compare

参数

返回值

备注

示例

CStringT::CompareNoCase

参数

返回值

备注

示例

CStringT::CStringT

参数

备注

示例

CStringT::~CStringT

备注

CStringT::Delete

参数

返回值

注解

示例

CStringT::Find

参数

返回值

备注

示例

CStringT::FindOneOf

参数

返回值

备注

示例

CStringT::Format

参数

注解

示例

CStringT::FormatMessage

参数

注解

示例

CStringT::FormatMessageV

参数

注解

CStringT::FormatV

参数

备注

示例

CStringT::GetEnvironmentVariable

参数

返回值

`CStringT` 类

`CStringT::AllocSysString`

`CStringT::AnsiToOem`

`CStringT::AppendFormat`

`CStringT::Collate`

`CStringT::CollateNoCase`

`CStringT::Compare`

`CStringT::CompareNoCase`

`CStringT::CStringT`

`CStringT::~CStringT`

`CStringT::Delete`

`CStringT::Find`

`CStringT::FindOneOf`

`CStringT::Format`

`CStringT::FormatMessage`

`CStringT::FormatMessageV`

`CStringT::FormatV`

`CStringT::GetEnvironmentVariable`

`CStringT::Insert`

`CStringT::Left`

`CStringT::LoadString`

`CStringT::MakeLower`

`CStringT::MakeReverse`

`CStringT::MakeUpper`

`CStringT::Mid`

`CStringT::OemToAnsi`

`CStringT::operator =`

`CStringT::operator +`

`CStringT::operator +=`

`CStringT::operator ==`

`CStringT::operator !=`

`CStringT::operator <`

`CStringT::operator >`

`CStringT::operator <=`

`CStringT::operator >=`