`CSimpleStringT` 類別

發行項
01/30/2024

這個類別代表 CSimpleStringT 物件。

語法

template <typename BaseType>
class CSimpleStringT

參數

BaseType
字串類別的字元類型。可以是下列其中一項：

char （適用於 ANSI 字元字串）。
wchar_t （適用於 Unicode 字元字串）。
TCHAR （適用於 ANSI 和 Unicode 字元字串）。

成員

公用 Typedefs

名稱	描述
`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`	直接存取儲存在物件中的 `CSimpleStringT` 字元做為 C 樣式字串。
`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 字元數。

備註

呼叫這個方法，將字元從 pchSrcpchDest 複製到字串。

範例

下列範例示範 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 字元數。

備註

呼叫這個方法，將字元從 pchSrcpchDest 複製到字串。不同於 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 指標。如需和記憶體管理的詳細資訊，請參閱記憶體管理和 CStringTIAtlStringMgrCSimpleStringT

備註

建構新的 CSimpleStringT 物件。由於建構函式會將輸入資料複製到新的配置記憶體中，因此記憶體例外狀況可能會造成。

範例

下列範例示範 CSimpleStringT::CSimpleStringT 如何使用 ATL typedefCSimpleString。 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便利別名。 Null 終止符可尋址，而不使用 GetAt產生例外狀況。不過，它不會由 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 過，您會失去緩衝區鎖定。

傳回值

PXSTR物件的字元緩衝區指標（以 Null 結束的）字元緩衝區。

備註

呼叫這個方法可傳回物件的緩衝區內容 CSimpleStringT 。傳 PXSTR 回的不是常數，因此允許直接修改 CSimpleStringT 內容。

如果您使用所 GetBuffer 傳回的指標來變更字串內容，您必須先呼叫 ReleaseBuffer 來更新的內部狀態 CSimpleStringT ，才能使用任何其他 CSimpleStringT 方法。

在呼叫之後傳GetBuffer回的位址可能無效，因為其他CSimpleStringT作業可能會導致CSimpleStringT重新配置ReleaseBuffer緩衝區。如果您未變更的 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 確切大小，以字元為單位。

傳回值

PXSTR物件的字元緩衝區指標（以 Null 結束的）字元緩衝區。

備註

呼叫這個方法，以擷取對象內部緩衝區的 CSimpleStringT 指定長度。傳回的 PXSTR 指標不是 const ，因此允許直接修改 CSimpleStringT 內容。

如果您使用所GetBufferSetLength傳回的指標來變更字串內容，請在使用任何其他CSimpleStringT方法之前，呼叫 ReleaseBuffer 以更新的內部狀態CSimpleStringT。

在呼叫之後傳GetBufferSetLength回的位址可能無效，因為其他CSimpleStringT作業可能會導致CSimpleStringT重新配置ReleaseBuffer緩衝區。如果您未變更的 CSimpleStringT長度，則不會重新指派緩衝區。

當物件終結時 CSimpleStringT ，會自動釋放緩衝區內存。

如果您自行追蹤字串長度，請勿附加終止的 Null 字元。當您使用 ReleaseBuffer釋放緩衝區時，必須指定最終字串長度。如果您在呼叫 ReleaseBuffer時附加終止的 Null 字元，請將長度 ReleaseBuffer的 -1 （預設值）傳遞給，並在 ReleaseBuffer 緩衝區上執行 strlen ，以判斷其長度。

如需參考計數的詳細資訊，請參閱下列文章：

範例

下列範例示範 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 ，並將參數nMinBufferLength設定GetBuffer為大於目前緩衝區的長度，您將失去緩衝區鎖定。這類呼叫 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`

直接存取儲存在物件中的 CSimpleStringT 字元做為 C 樣式字串。

語法

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 。

CSimpleStringTSTATUS_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 來指定其長度。在呼叫 ReleaseBuffer 或任何其他CSimpleStringT作業之後，所GetBuffer傳回的地址無效。

範例

下列範例示範 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 終止的字串。除非它第一次遇到 Null 終止符，否則它會使用 nLength 做為字串長度。

的雙參數版本 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 類別

語法

參數

成員

公用 Typedefs

公用建構函式

公用方法

公用運算子

備註

需求

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`