共用方式為


CSimpleStringT 類別

這個類別代表 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 字元數。

備註

呼叫這個方法,將字元從 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 複製到字串。 不同於 CopyCharsCopyCharsOverlapped 提供安全的方法可從可能重疊的字元緩衝區複製。

範例

請參閱 的 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 指標。 如需和記憶體管理的詳細資訊,請參閱記憶體管理和 CStringTIAtlStringMgr CSimpleStringT

備註

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

範例

下列範例示範 CSimpleStringT::CSimpleStringT 如何使用 ATL typedef CSimpleStringCSimpleString 是類別範本 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();

此範例的輸出如下所示:

l

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
字串的新長度。

備註

呼叫這個方法,將字串的內容截斷為新的長度。

注意

這不會影響緩衝區的配置長度。 若要減少或增加目前的緩衝區,請參閱 FreeExtraPreallocate

範例

下列範例示範 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 共享類別