`CSimpleStringT` 类

项目
01/26/2024

此类表示 CSimpleStringT 对象。

语法

template <typename BaseType>
class CSimpleStringT

参数

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

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

成员

公共 Typedef

名称	描述
`CSimpleStringT::PCXSTR`	指向常量字符串的指针。
`CSimpleStringT::PXSTR`	指向字符串的指针。

公共构造函数

名称	描述
`CSimpleStringT::CSimpleStringT`	以各种方式构造 `CSimpleStringT` 对象。
`CSimpleStringT::~CSimpleStringT`	析构函数。

公共方法

名称	描述
`CSimpleStringT::Append`	将 `CSimpleStringT` 对象追加到现有 `CSimpleStringT` 对象。
`CSimpleStringT::AppendChar`	将字符追加到现有 `CSimpleStringT` 对象。
`CSimpleStringT::CopyChars`	将一个或多个字符复制到另一个字符串。
`CSimpleStringT::CopyCharsOverlapped`	将一个或多个字符复制到缓冲区重叠的另一个字符串。
`CSimpleStringT::Empty`	强制字符串使用零长度。
`CSimpleStringT::FreeExtra`	释放先前由字符串对象分配的任何额外内存。
`CSimpleStringT::GetAllocLength`	检索 `CSimpleStringT` 对象的分配长度。
`CSimpleStringT::GetAt`	返回位于给定位置的字符。
`CSimpleStringT::GetBuffer`	返回指向 `CSimpleStringT` 中字符的指针。
`CSimpleStringT::GetBufferSetLength`	返回指向 `CSimpleStringT` 中字符的指针，截断为指定的长度。
`CSimpleStringT::GetLength`	返回 `CSimpleStringT` 对象中的字符数。
`CSimpleStringT::GetManager`	检索 `CSimpleStringT` 对象的内存管理器。
`CSimpleStringT::GetString`	检索字符串
`CSimpleStringT::IsEmpty`	测试 `CSimpleStringT` 对象是否不包含字符。
`CSimpleStringT::LockBuffer`	禁用引用计数并保护缓冲区中的字符串。
`CSimpleStringT::Preallocate`	为字符缓冲区分配特定的内存量。
`CSimpleStringT::ReleaseBuffer`	释放 `GetBuffer` 返回的缓冲区的控制。
`CSimpleStringT::ReleaseBufferSetLength`	释放 `GetBuffer` 返回的缓冲区的控制。
`CSimpleStringT::SetAt`	在给定的位置设置字符。
`CSimpleStringT::SetManager`	设置 `CSimpleStringT` 对象的内存管理器。
`CSimpleStringT::SetString`	设置 `CSimpleStringT` 对象的字符串。
`CSimpleStringT::StringLength`	返回指定字符串中的字符数。
`CSimpleStringT::Truncate`	将字符串截断为指定的长度。
`CSimpleStringT::UnlockBuffer`	启用引用计数并释放缓冲区中的字符串。

公共运算符

“属性”	描述
`CSimpleStringT::operator PCXSTR`	直接访问作为 C 样式字符串存储在 `CSimpleStringT` 对象中的字符。
`CSimpleStringT::operator[]`	返回位于给定位置的字符 — `GetAt` 的运算符替换项。
`CSimpleStringT::operator +=`	将新字符串串联到现有字符串的末尾。
`CSimpleStringT::operator =`	为 `CSimpleStringT` 对象分配新值。

注解

CSimpleStringT 是 Visual C++ 支持的各种字符串类的基类。它为字符串对象的内存管理和基本的缓冲区操作提供最低程度的支持。有关更高级的字符串对象，请参阅 CStringT Class。

要求

标头atlsimpstr.h：

`CSimpleStringT::Append`

将 CSimpleStringT 对象追加到现有 CSimpleStringT 对象。

语法

void Append(const CSimpleStringT& strSrc);
void Append(PCXSTR pszSrc, int nLength);
void Append(PCXSTR pszSrc);

参数

strSrc
要追加的 CSimpleStringT 对象。

pszSrc
指向字符串的指针，该字符串包含要追加的字符。

nLength
要追加的字符数。

注解

调用此方法可将现有 CSimpleStringT 对象追加到另一个 CSimpleStringT 对象。

示例

以下示例演示了 CSimpleStringT::Append 的用法。

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str1(pMgr), str2(pMgr);
str1.SetString(_T("Soccer is"));
str2.SetString(_T(" an elegant game"));
str1.Append(str2);
ASSERT(_tcscmp(str1, _T("Soccer is an elegant game")) == 0);

`CSimpleStringT::AppendChar`

将字符追加到现有 CSimpleStringT 对象。

语法

void AppendChar(XCHAR ch);

参数

ch
要追加的字符

备注

调用此函数可将指定的字符追加到现有 CSimpleStringT 对象的末尾。

`CSimpleStringT::CopyChars`

将一个或多个字符复制到 CSimpleStringT 对象。

语法

static void CopyChars(
    XCHAR* pchDest,
    const XCHAR* pchSrc,
    int nChars) throw();
static void CopyChars(
    XCHAR* pchDest,
    size_t nDestLen,
    const XCHAR* pchSrc,
    int nChars) throw();

参数

pchDest
指向字符串的指针。

nDestLen
pchDest 的缓冲区大小

pchSrc
指向字符串的指针，该字符串包含要复制的字符。

nChars
要复制的 pchSrc 字符数。

备注

调用此方法可将 pchSrc 中的字符复制到 pchDest 字符串。

示例

以下示例演示了 CSimpleStringT::CopyChars 的用法。

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str(_T("xxxxxxxxxxxxxxxxxxx"), 20, pMgr);
const TCHAR* pszSrc = _T("Hello world!");
_tprintf_s(_T("%s\n"), str);
str.CopyChars(str.GetBuffer(), 20, pszSrc, 12);
_tprintf_s(_T("%s\n"), str);

此示例的输出如下所示：

xxxxxxxxxxxxxxxxxxx
Hello world!xxxxxxx

`CSimpleStringT::CopyCharsOverlapped`

将一个或多个字符复制到 CSimpleStringT 对象。

语法

static void CopyCharsOverlapped(
    XCHAR* pchDest,
    const XCHAR* pchSrc,
    int nChars) throw();

参数

pchDest
指向字符串的指针。

pchSrc
指向字符串的指针，该字符串包含要复制的字符。

nChars
要复制的 pchSrc 字符数。

备注

调用此方法可将 pchSrc 中的字符复制到 pchDest 字符串。与 CopyChars 不同，CopyCharsOverlapped 提供一种从可能重叠的字符缓冲区进行复制的安全方法。

示例

请参阅 CSimpleStringT::CopyChars 的示例或 CSimpleStringT::SetString 的源代码（在 atlsimpstr.h 中）。

`CSimpleStringT::CSimpleStringT`

构造 CSimpleStringT 对象。

语法

CSimpleStringT(const XCHAR* pchSrc, int nLength, IAtlStringMgr* pStringMgr);
CSimpleStringT(PCXSTR pszSrc, IAtlStringMgr* pStringMgr);
CSimpleStringT(const CSimpleStringT& strSrc);
explicit CSimpleStringT(IAtlStringMgr* pStringMgr) throw();

参数

strSrc
要复制到此 CSimpleStringT 对象中的现有 CSimpleStringT 对象。

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

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

nLength
pch 中的字符数。

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

备注

构造新的 CSimpleStringT 对象。由于构造函数将输入数据复制到新的已分配存储中，因此可能会导致内存异常。

示例

以下示例演示如何通过 ATL typedefCSimpleString 使用 CSimpleStringT::CSimpleStringT。 CSimpleString 是类模板 CSimpleStringT 的常用专用化。

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString s1(pMgr);
// Empty string
CSimpleString s2(_T("cat"), pMgr);
// From a C string literal

CSimpleString s3(s2);
// Copy constructor
CSimpleString s4(s2 + _T(" ") + s3);

// From a string expression
CSimpleString s5(_T("xxxxxx"), 6, pMgr);
// s5 = "xxxxxx"

`CSimpleStringT::Empty`

将此 CSimpleStringT 对象设为空字符串并相应地释放内存。

语法

void Empty() throw();

备注

有关详细信息，请参阅字符串：CString 异常清理。

示例

以下示例演示了 CSimpleStringT::Empty 的用法。

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString s(pMgr);
ASSERT(s.IsEmpty());

`CSimpleStringT::FreeExtra`

释放先前由字符串分配的但不再需要的任何额外内存。

语法

void FreeExtra();

备注

这应会降低字符串对象占用的内存开销。该方法将缓冲区重新分配为 GetLength 返回的确切长度。

示例

CAtlString basestr;
IAtlStringMgr* pMgr;

pMgr= basestr.GetManager();
ASSERT(pMgr != NULL);

// Create a CSimpleString with 28 characters
CSimpleString str(_T("Many sports are fun to play."), 28, pMgr);
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

// Assigning a smaller string won't cause CSimpleString to free its
// memory, because it assumes the string will grow again anyway.
str = _T("Soccer is best!");
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

// This call forces CSimpleString to release the extra
// memory it doesn't need.
str.FreeExtra();
_tprintf_s(_T("Alloc length is %d, String length is %d\n"),
   str.GetAllocLength(), str.GetLength());

此示例的输出如下所示：

Alloc length is 1031, String length is 1024
Alloc length is 1031, String length is 15
Alloc length is 15, String length is 15

`CSimpleStringT::GetAllocLength`

检索 CSimpleStringT 对象的分配长度。

语法

int GetAllocLength() const throw();

返回值

为此对象分配的字符数。

备注

调用此方法可确定为此 CSimpleStringT 对象分配的字符数。有关调用此函数的示例，请参阅 FreeExtra。

`CSimpleStringT::GetAt`

从 CSimpleStringT 对象返回一个字符。

语法

XCHAR GetAt(int iChar) const;

参数

iChar
CSimpleStringT 对象中字符的从零开始的索引。 iChar 参数必须大于或等于 0 且小于 GetLength 返回的值。否则，GetAt 将生成异常。

返回值

一个 XCHAR，其中包含位于字符串中指定位置的字符。

备注

调用此方法可返回 iChar 指定的一个字符。重载的下标 ([]) 运算符是 GetAt 的方便别名。可使用 GetAt 来寻址 null 终止符，而不会生成异常。但是，GetLength 不会统计该字符，返回的值为 0。

示例

以下示例演示如何使用 CSimpleStringT::GetAt。

CSimpleString s(_T("abcdef"), pMgr);
ASSERT(s.GetAt(2) == _T('c'));

`CSimpleStringT::GetBuffer`

返回指向 CSimpleStringT 对象的内部字符缓冲区的指针。

语法

PXSTR GetBuffer(int nMinBufferLength);
PXSTR GetBuffer();

参数

nMinBufferLength
字符缓冲区可以容纳的最小字符数。此值不包括 null 终止符的占用空间。

如果 nMinBufferLength 大于当前缓冲区的长度，则 GetBuffer 会销毁当前缓冲区，将其替换为所请求大小的缓冲区，并将对象引用计数重置为零。如果先前对此缓冲区调用了 LockBuffer，则会失去缓冲区锁。

返回值

指向对象的（以 null 结尾）字符缓冲区的 PXSTR 指针。

注解

调用此方法可返回 CSimpleStringT 对象的缓冲区内容。返回的 PXSTR 不是常量，因此允许直接修改 CSimpleStringT 内容。

如果使用 GetBuffer 返回的指针来更改字符串内容，则必须在使用任何其他 CSimpleStringT 方法之前调用 ReleaseBuffer 以更新 CSimpleStringT 的内部状态。

GetBuffer 返回的地址在调用 ReleaseBuffer 后可能无效，因为附加的 CSimpleStringT 操作可能导致重新分配 CSimpleStringT 缓冲区。如果不更改 CSimpleStringT 的长度，则不会重新分配缓冲区。

销毁 CSimpleStringT 对象时，会自动释放缓冲区内存。

如果你自行跟踪字符串长度，则不应追加结尾的 null 字符。但是，必须在使用 ReleaseBuffer 释放缓冲区时指定最终的字符串长度。如果确实追加了结尾的 null 字符，则应传递 -1（默认值）作为长度。然后 ReleaseBuffer 会确定缓冲区长度。

如果没有足够的内存来满足 GetBuffer 请求，则此方法会引发 CMemoryException*。

示例

CSimpleString s(_T("abcd"), pMgr);
LPTSTR pBuffer = s.GetBuffer(10);
int sizeOfBuffer = s.GetAllocLength();

// Directly access CSimpleString buffer
_tcscpy_s(pBuffer, sizeOfBuffer, _T("Hello"));
ASSERT(_tcscmp(s, _T("Hello")) == 0);
s.ReleaseBuffer();

`CSimpleStringT::GetBufferSetLength`

返回指向 CSimpleStringT 对象的内部字符缓冲区的指针，必要时截断或增加该缓冲区的长度，以完全匹配 nLength 中指定的长度。

语法

PXSTR GetBufferSetLength(int nLength);

参数

nLength
CSimpleStringT 字符缓冲区的确切大小，以字符为单位。

返回值

指向对象的（以 null 结尾）字符缓冲区的 PXSTR 指针。

注解

调用此方法可检索 CSimpleStringT 对象的内部缓冲区的指定长度。返回的 PXSTR 指针不是 const，因此允许直接修改 CSimpleStringT 内容。

如果使用 GetBufferSetLength 返回的指针来更改字符串内容，请在使用任何其他 CSimpleStringT 方法之前调用 ReleaseBuffer 以更新 CSimpleStringT 的内部状态。

GetBufferSetLength 返回的地址在调用 ReleaseBuffer 后可能无效，因为附加的 CSimpleStringT 操作可能导致重新分配 CSimpleStringT 缓冲区。如果不更改 CSimpleStringT 的长度，则不会重新分配缓冲区。

销毁 CSimpleStringT 对象时，会自动释放缓冲区内存。

如果你自行跟踪字符串长度，请不要追加结尾的 null 字符。必须在使用 ReleaseBuffer 释放缓冲区时指定最终的字符串长度。如果在调用 ReleaseBuffer 时确实追加了结尾的 null 字符，请将 -1（默认值）作为长度传递给 ReleaseBuffer，ReleaseBuffer 将对缓冲区执行 strlen 以确定其长度。

有关引用计数的详细信息，请参阅以下文章：

Windows SDK 中的通过引用计数管理对象生命周期。
Windows SDK 中的实现引用计数。
Windows SDK 中的用于管理引用计数的规则。

示例

以下示例演示了 CSimpleStringT::GetBufferSetLength 的用法。

CSimpleString str(pMgr);
LPTSTR pstr = str.GetBufferSetLength(3);
pstr[0] = _T('C');
pstr[1] = _T('u');
pstr[2] = _T('p');
str.ReleaseBuffer();

str += _T(" soccer is best!");
ASSERT(_tcscmp(str, _T("Cup soccer is best!")) == 0);

`CSimpleStringT::GetLength`

返回 CSimpleStringT 对象中的字符数。

语法

int GetLength() const throw();

返回值

字符串中的字符计数。

备注

调用此方法可返回对象中的字符数。该计数不包括 null 终止符。

对于多字节字符集 (MBCS)，GetLength 统计每个 8 位字符；即，一个多字节字符中的前导字节和尾部字节计为两个字节。有关调用此函数的示例，请参阅 FreeExtra。

`CSimpleStringT::GetManager`

检索 CSimpleStringT 对象的内存管理器。

语法

IAtlStringMgr* GetManager() const throw();

返回值

指向 CSimpleStringT 对象的内存管理器的指针。

注解

调用此方法可检索 CSimpleStringT 对象使用的内存管理器。有关内存管理器和字符串对象的详细信息，请参阅内存管理和 CStringT。

`CSimpleStringT::GetString`

检索字符串。

语法

PCXSTR GetString() const throw();

返回值

指向以 null 结尾的字符串的指针。

注解

调用此方法可检索与 CSimpleStringT 对象关联的字符串。

注意

返回的 PCXSTR 指针是 const，不允许直接修改 CSimpleStringT 内容。

示例

以下示例演示了 CSimpleStringT::GetString 的用法。

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();   
CSimpleString str(pMgr);
str += _T("Cup soccer is best!");
_tprintf_s(_T("%s"), str.GetString());

此示例的输出如下所示：

Cup soccer is best!

`CSimpleStringT::IsEmpty`

测试 CSimpleStringT 对象的空条件。

语法

bool IsEmpty() const throw();

返回值

如果 CSimpleStringT 对象的长度为 0，则返回 TRUE；否则返回 FALSE。

备注

调用此方法可确定对象是否包含空字符串。

示例

以下示例演示了 CSimpleStringT::IsEmpty 的用法。

CSimpleString s(pMgr);
ASSERT(s.IsEmpty());

`CSimpleStringT::LockBuffer`

禁用引用计数并保护缓冲区中的字符串。

语法

PXSTR LockBuffer();

返回值

指向 CSimpleStringT 对象或以 null 结尾的字符串的指针。

备注

调用此方法可锁定 CSimpleStringT 对象的缓冲区。可通过调用 LockBuffer 创建字符串的副本，-1 表示引用计数。当引用计数值为 -1 时，缓冲区中的字符串被视为处于“锁定”状态。以两种方式对处于锁定状态的字符串进行保护：

其他字符串都不可以获取对已锁定字符串中的数据的引用，即使该字符串已分配到锁定的字符串。
锁定的字符串永远不会引用另一个字符串，即使这另一个字符串已复制到锁定的字符串。

通过在缓冲区中锁定字符串，可以确保该字符串在缓冲区中的独占性保持不变。

完成 LockBuffer 后，调用 UnlockBuffer 将引用计数重置为 1。

注意

如果对锁定的缓冲区调用 GetBuffer 并将 GetBuffer 参数 nMinBufferLength 设置为大于当前缓冲区的长度，将会失去缓冲区锁。这种 GetBuffer 调用会销毁当前缓冲区，将其替换为所请求大小的缓冲区，并将引用计数重置为零。

有关引用计数的详细信息，请参阅以下文章：

示例

以下示例演示了 CSimpleStringT::LockBuffer 的用法。

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString str(_T("Hello"), pMgr);
TCHAR ch;

str.LockBuffer();
ch = str.GetAt(2);
_tprintf_s(_T("%c"), ch);
str.UnlockBuffer();

此示例的输出如下所示：

`CSimpleStringT::operator[]`

调用此函数可访问字符数组的单个字符。

语法

XCHAR operator[](int iChar) const;

参数

iChar
字符串中字符的从零开始的索引。

备注

重载的下标 ([]) 运算符返回 iChar 中的从零开始的索引指定的单个字符。此运算符是 GetAt 成员函数的方便替换项。

注意

可以使用下标 ([]) 运算符来获取 CSimpleStringT 中字符的值，但无法使用它来更改 CSimpleStringT 中字符的值。

示例

以下示例演示了 CSimpleStringT::operator [] 的用法。

CSimpleString s(_T("abc"), pMgr);
ASSERT(s[1] == _T('b'));

`CSimpleStringT::operator []`

调用此函数可访问字符数组的单个字符。

语法

XCHAR operator[](int iChar) const;

参数

iChar
字符串中字符的从零开始的索引。

备注

重载的下标 ([]) 运算符返回 iChar 中的从零开始的索引指定的单个字符。此运算符是 GetAt 成员函数的方便替换项。

注意

可以使用下标 ([]) 运算符来获取 CSimpleStringT 中字符的值，但无法使用它来更改 CSimpleStringT 中字符的值。

`CSimpleStringT::operator +=`

将新字符串或字符联接到现有字符串的末尾。

语法

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

参数

pszSrc
指向以 null 结尾的字符串的指针。

strSrc
指向现有 CSimpleStringT 对象的指针。

ch
要追加的字符。

备注

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

示例

以下示例演示了 CSimpleStringT::operator += 的用法。

CSimpleString str(_T("abc"), pMgr);
ASSERT(_tcscmp((str += _T("def")), _T("abcdef")) == 0);

`CSimpleStringT::operator =`

为 CSimpleStringT 对象分配新值。

语法

CSimpleStringT& operator =(PCXSTR pszSrc);
CSimpleStringT& operator =(const CSimpleStringT& strSrc);

参数

pszSrc
指向以 null 结尾的字符串的指针。

strSrc
指向现有 CSimpleStringT 对象的指针。

注解

如果目标字符串（左侧）已足够大，可以存储新数据，则不会执行新的内存分配。请注意，每当使用赋值运算符，都可能发生内存异常，因为通常会分配新的存储来保存生成的 CSimpleStringT 对象。

示例

以下示例演示了 CSimpleStringT::operator = 的用法。

CSimpleString s1(pMgr), s2(pMgr);
// Empty CSimpleStringT objects

s1 = _T("cat");
// s1 = "cat"
ASSERT(_tcscmp(s1, _T("cat")) == 0);

s2 = s1;               // s1 and s2 each = "cat"
ASSERT(_tcscmp(s2, _T("cat")) == 0);

s1 = _T("the ") + s1;
// Or expressions
ASSERT(_tcscmp(s1, _T("the cat")) == 0);

s1 = _T("x");
// Or just individual characters
ASSERT(_tcscmp(s1, _T("x")) == 0);

`CSimpleStringT::operator PCXSTR`

直接访问作为 C 样式字符串存储在 CSimpleStringT 对象中的字符。

语法

operator PCXSTR() const throw();

返回值

指向字符串数据的字符指针。

注解

不复制字符；只返回指针。请谨慎使用此运算符。如果在获取字符指针后更改 CString 对象，则可能会导致重新分配内存，从而使指针失效。

示例

以下示例演示了 CSimpleStringT::operator PCXSTR 的用法。

// If the prototype of a function is known to the compiler,
// the PCXSTR cast operator may be invoked implicitly.

CSimpleString strSports(L"Soccer is Best!", pMgr);
WCHAR sz[1024];

wcscpy_s(sz, strSports);

// If the prototype isn't known or is a va_arg prototype,
// you must invoke the cast operator explicitly. For example,
// the va_arg part of a call to swprintf_s() needs the cast:

swprintf_s(sz, 1024, L"I think that %s!\n", (PCWSTR)strSports);

// While the format parameter is known to be an PCXSTR and
// therefore doesn't need the cast:

swprintf_s(sz, 1024, strSports);

// Note that some situations are ambiguous. This line will
// put the address of the strSports object to stdout:

wcout << strSports;

// while this line will put the content of the string out:

wcout << (PCWSTR)strSports;

`CSimpleStringT::PCXSTR`

指向常量字符串的指针。

语法

typedef ChTraitsBase< BaseType >::PCXSTR PCXSTR;

`CSimpleStringT::Preallocate`

为 CSimpleStringT 对象分配特定数量的字节。

语法

void Preallocate( int nLength);

参数

nLength
CSimpleStringT 字符缓冲区的确切大小，以字符为单位。

注解

调用此方法可为 CSimpleStringT 对象分配特定的缓冲区大小。

如果无法为字符缓冲区分配空间，CSimpleStringT 将生成 STATUS_NO_MEMORY 异常。默认情况下，内存分配由 WIN32 API 函数 HeapAlloc 或 HeapReAlloc 执行。

示例

以下示例演示了 CSimpleStringT::Preallocate 的用法。

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();

CSimpleString str(pMgr);
_tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength());
str.Preallocate(100);
_tprintf_s(_T("Allocated length: %d\n"), str.GetAllocLength());

此示例的输出如下所示：

Allocated length: 0
Allocated length: 103

`CSimpleStringT::PXSTR`

指向字符串的指针。

语法

typedef ChTraitsBase< BaseType >::PXSTR PXSTR;

`CSimpleStringT::ReleaseBuffer`

释放 GetBuffer 分配的缓冲区的控制。

语法

void ReleaseBuffer(int nNewLength = -1);

参数

nNewLength
字符串的新长度（以字符为单位），不计算 null 终止符。如果字符串以 null 结尾，则默认值 -1 会将 CSimpleStringT 大小设置为字符串的当前长度。

注解

调用此方法可重新分配或释放字符串对象的缓冲区。如果你知道缓冲区中的字符串以 null 结尾，则可以省略 nNewLength 参数。如果字符串不以 null 结尾，请使用 nNewLength 指定其长度。 GetBuffer 返回的地址在调用 ReleaseBuffer 或任何其他 CSimpleStringT 操作后无效。

示例

以下示例演示了 CSimpleStringT::ReleaseBuffer 的用法。

const int bufferSize = 1024;
CSimpleString s(_T("abc"), pMgr);
LPTSTR p = s.GetBuffer(bufferSize);
_tcscpy_s(p, bufferSize, _T("abc"));

// use the buffer directly
ASSERT(s.GetLength() == 3);

// String length = 3
s.ReleaseBuffer();

// Surplus memory released, p is now invalid.
ASSERT(s.GetLength() == 3);

// Length still 3

`CSimpleStringT::ReleaseBufferSetLength`

释放 GetBuffer 分配的缓冲区的控制。

语法

void ReleaseBufferSetLength(int nNewLength);

参数

nNewLength
释放的字符串的长度

备注

此函数在功能上类似于 ReleaseBuffer，唯一的差别在于，必须传递字符串对象的有效长度。

`CSimpleStringT::SetAt`

设置 CSimpleStringT 对象中的单个字符。

语法

void SetAt(int iChar, XCHAR ch);

参数

iChar
CSimpleStringT 对象中字符的从零开始的索引。 iChar 参数必须大于或等于 0 且小于 GetLength 返回的值。

ch
新字符。

备注

调用此方法可覆盖位于 iChar 处的字符。如果 iChar 超出现有字符串的边界，则此方法不会放大字符串。

示例

以下示例演示了 CSimpleStringT::SetAt 的用法。

CSimpleString s(_T("abcdef"), pMgr);
s.SetAt(1, _T('a'));
ASSERT(_tcscmp(s, _T("aacdef")) == 0);

`CSimpleStringT::SetManager`

指定 CSimpleStringT 对象的内存管理器。

语法

void SetManager(IAtlStringMgr* pStringMgr);

参数

pStringMgr
指向新内存管理器的指针。

备注

调用此方法可指定 CSimpleStringT 对象使用的新内存管理器。有关内存管理器和字符串对象的详细信息，请参阅内存管理和 CStringT。

示例

以下示例演示了 CSimpleStringT::SetManager 的用法。

CSimpleString s(pMgr);
s.SetManager(pCustomMgr);

`CSimpleStringT::SetString`

设置 CSimpleStringT 对象的字符串。

语法

void SetString(PCXSTR pszSrc, int nLength);
void SetString(PCXSTR pszSrc);

参数

pszSrc
指向以 null 结尾的字符串的指针。

nLength
pszSrc 中的字符数。

注解

将字符串复制到 CSimpleStringT 对象中。 SetString 覆盖缓冲区中的较旧字符串数据。

SetString 的两个版本都检查 pszSrc 是否为 null 指针，如果是，则引发 E_INVALIDARG 错误。

SetString 的单参数版本要求 pszSrc 指向以 null 结尾的字符串。

SetString 的双参数版本也要求 pszSrc 是以 null 结尾的字符串。它使用 nLength 作为字符串长度，除非它首先遇到 null 终止符。

SetString 的双参数版本还会检查 pszSrc 是否指向 CSimpleStringT 中当前缓冲区内的某个位置。在这种特殊情况下，SetString 会使用内存复制功能，该功能在将字符串数据复制回其缓冲区时不会覆盖字符串数据。

示例

以下示例演示了 CSimpleStringT::SetString 的用法。

CSimpleString s(_T("abcdef"), pMgr);
ASSERT(_tcscmp(s, _T("abcdef")) == 0);
s.SetString(_T("Soccer"), 6);
ASSERT(_tcscmp(s, _T("Soccer")) == 0);

`CSimpleStringT::StringLength`

返回指定字符串中的字符数。

语法

ATL_NOINLINE static int StringLength(PCXSTR psz) throw();

参数

psz
指向以 null 结尾的字符串的指针。

返回值

psz 中的字符数；不计算 null 终止符。

备注

调用此方法可检索 psz 指向的字符串中的字符数。

示例

以下示例演示了 CSimpleStringT::StringLength 的用法。

ASSERT(CSimpleString::StringLength(_T("soccer")) == 6);

`CSimpleStringT::Truncate`

将字符串截断为新长度。

语法

void Truncate(int nNewLength);

参数

nNewLength
字符串的新长度。

注解

调用此方法可将字符串的内容截断为新长度。

注意

这不会影响缓冲区的分配长度。若要减小或增大当前缓冲区，请参阅 FreeExtra 和 Preallocate。

示例

以下示例演示了 CSimpleStringT::Truncate 的用法。

CAtlString basestr;
IAtlStringMgr* pMgr = basestr.GetManager();
CSimpleString str(_T("abcdefghi"), pMgr);
_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength());
_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str);
str.Truncate(4);
_tprintf_s(_T("String length: %d / Allocated length: %d\n"), str.GetLength(), str.GetAllocLength());
_tprintf_s(_T("Contents: %s\n"), (LPCTSTR)str);

此示例的输出为：

String length: 9 / Allocated length: 15
Contents: abcdefghi
String length: 4 / Allocated length: 15
Contents: abcd

`CSimpleStringT::UnlockBuffer`

解锁 CSimpleStringT 对象的缓冲区。

语法

void UnlockBuffer() throw();

备注

调用此方法可将字符串的引用计数重置为 1。

CSimpleStringT 析构函数自动调用 UnlockBuffer 来确保在调用该析构函数时不会锁定缓冲区。有关此方法的示例，请参阅 LockBuffer。

`CSimpleStringT::~CSimpleStringT`

销毁 CSimpleStringT 对象。

语法

~CSimpleStringT() throw();

备注

调用此方法可销毁 CSimpleStringT 对象。

另请参阅

层次结构图
 ATL/MFC 共享类

通过

CSimpleStringT 类

语法

参数

成员

公共 Typedef

公共构造函数

公共方法

公共运算符

注解

要求

CSimpleStringT::Append

语法

参数

注解

示例

CSimpleStringT::AppendChar

语法

参数

备注

CSimpleStringT::CopyChars

语法

参数

备注

示例

CSimpleStringT::CopyCharsOverlapped

语法

参数

备注

示例

CSimpleStringT::CSimpleStringT

语法

参数

备注

示例

CSimpleStringT::Empty

语法

备注

示例

CSimpleStringT::FreeExtra

语法

备注

示例

CSimpleStringT::GetAllocLength

语法

返回值

备注

CSimpleStringT::GetAt

语法

参数

返回值

备注

示例

CSimpleStringT::GetBuffer

语法

参数

返回值

注解

示例

CSimpleStringT::GetBufferSetLength

语法

参数

返回值

注解

示例

CSimpleStringT::GetLength

语法

返回值

备注

CSimpleStringT::GetManager

语法

返回值

注解

CSimpleStringT::GetString

语法

返回值

注解

示例

CSimpleStringT::IsEmpty

语法

`CSimpleStringT` 类

`CSimpleStringT::Append`

`CSimpleStringT::AppendChar`

`CSimpleStringT::CopyChars`

`CSimpleStringT::CopyCharsOverlapped`

`CSimpleStringT::CSimpleStringT`

`CSimpleStringT::Empty`

`CSimpleStringT::FreeExtra`

`CSimpleStringT::GetAllocLength`

`CSimpleStringT::GetAt`

`CSimpleStringT::GetBuffer`

`CSimpleStringT::GetBufferSetLength`

`CSimpleStringT::GetLength`

`CSimpleStringT::GetManager`

`CSimpleStringT::GetString`

`CSimpleStringT::IsEmpty`

`CSimpleStringT::LockBuffer`

`CSimpleStringT::operator[]`

`CSimpleStringT::operator []`

`CSimpleStringT::operator +=`

`CSimpleStringT::operator =`

`CSimpleStringT::operator PCXSTR`

`CSimpleStringT::PCXSTR`

`CSimpleStringT::Preallocate`

`CSimpleStringT::PXSTR`

`CSimpleStringT::ReleaseBuffer`

`CSimpleStringT::ReleaseBufferSetLength`

`CSimpleStringT::SetAt`

`CSimpleStringT::SetManager`

`CSimpleStringT::SetString`

`CSimpleStringT::StringLength`