`CStringT` 類別

發行項
10/12/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`	`BSTR`從 `CStringT` 資料配置。
`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 Class 。由實作 CStringT 進階功能，例如字元操作、排序和搜尋。

注意

CStringT 物件能夠擲回例外狀況。當物件因任何原因而記憶體不足時 CStringT ，就會發生這種情況。

CStringT物件是由可變長度的字元序列所組成。 CStringT 提供與 Basic 類似的語法的函式和運算子。串連和比較運算子以及簡化的記憶體管理，可讓 CStringT 物件比一般字元陣列更容易使用。

注意

雖然可以建立 CStringT 包含內嵌 Null 字元的實例，但建議您加以反對。在包含內嵌 Null 字元的物件上 CStringT 呼叫方法和運算子，可能會產生非預期的結果。

藉由使用不同的和 StringTraits 參數組合 BaseType ， 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 物件視為實際字串，而不是字串的指標。
您可以自由取代 CStringT 函式引數的物件 PCXSTR 。
字串緩衝區的自訂記憶體管理。如需詳細資訊，請參閱記憶體管理和 CStringT 。

CStringT 預先定義的類型

因為 CStringT 使用範本引數來定義支援的字元類型（或 wchar_tchar ），因此方法參數類型有時可能會很複雜。為了簡化此問題，會定義並在整個類別中使用 CStringT 一組預先定義的類型。下表列出各種類型：

名稱	描述
`XCHAR`	與物件具有相同字元類型的 `CStringT` 單一字元（或）。 `wchar_t``char`
`YCHAR`	具有相反字元類型的單一字元（或 `wchar_t` ） `char` 做為 `CStringT` 物件。
`PXSTR`	與物件具有相同字元類型的字元字串指標（或 `wchar_t``char` ）。 `CStringT`
`PYSTR`	具有相反字元類型的字元字串指標（或 `wchar_t``char` ），做為 `CStringT` 物件。
`PCXSTR`	`const`與物件具有相同字元類型的 `CStringT` 字元字串指標（或 `char``wchar_t` ）。
`PCYSTR`	`const`具有相反字元類型的字元字串指標（或 `wchar_t``char` ），做為 `CStringT` 物件。

注意

先前使用之未記載方法 CString 的程式 AssignCopy 代碼必須取代為使用下列記載方法 CStringT 的程式碼（例如 GetBuffer 或 ReleaseBuffer ）。這些方法繼承自 CSimpleStringT 。

繼承階層架構

CSimpleStringT

CStringT

需求

標題	使用對象
`cstringt.h`	僅限 MFC 的字串物件
`atlstr.h`	非 MFC 字串物件

`CStringT::AllocSysString`

配置類型 BSTR 與自動化相容的字串，並將物件的內容 CStringT 複製到其中，包括終止的 Null 字元。

BSTR AllocSysString() const;

傳回值

新配置的字串。

備註

在 MFC 程式中，如果記憶體不足， CMemoryException 則會擲回類別。在 ATL 程式中， CAtlException 會擲回。此函式通常用來傳回自動化的字串。

通常，如果此字串以參數的形式傳遞至 COM 函 [in] 式，則這需要呼叫端釋放字串。這可以使用來完成 SysFreeString ，如 Windows SDK 中所述。如需詳細資訊，請參閱配置和釋放的 BSTR 記憶體。

如需 Windows 中 OLE 配置函式的詳細資訊，請參閱 SysAllocString Windows SDK 中的。

範例

下列範例示範 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
用於比較的其他字串。

傳回值

如果字串相同，則為零; < 如果這個物件小於 psz ，則為 0; > 如果這個 CStringTCStringT 物件大於 psz ，則為 0。

備註

泛型文字函 _tcscoll 式，定義于 TCHAR.H 中，會根據編譯時期定義的字元集，對應至 strcoll 、 wcscoll 或 _mbscoll 。每個函式會根據目前使用中的字碼頁，對字串執行區分大小寫的比較。如需詳細資訊，請參閱 strcoll 、、 wcscoll 、 _mbscoll_strcoll_l 、 _wcscoll_l 、_mbscoll_l 。

`CStringT::CollateNoCase`

使用泛型文字函 _tcscoll 式比較兩個字串。

int CollateNoCase(PCXSTR psz) const throw();

參數

psz
用於比較的其他字串。

傳回值

如果字串相同，則為零（忽略大小寫）、 < 如果這個物件小於 psz （忽略大小寫），則為 0; > 如果這個 CStringTCStringT 物件大於 psz （忽略大小寫則為 0）。

備註

泛型文字函 _tcscoll 式，定義于 TCHAR.H 中，會根據編譯時期定義的字元集，對應至 stricoll 、 wcsicoll 或 _mbsicoll 。根據目前使用中的字碼頁，每個函式都會對字串執行不區分大小寫的比較。如需詳細資訊，請參閱、、 wcscoll 、 _mbscoll_strcoll_l 、 _wcscoll_l 、 _mbscoll_l 。 strcoll

範例

// 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
用於比較的其他字串。

傳回值

如果字串相同，則為零; < 如果這個物件小於 psz ，則為 0; > 如果這個 CStringTCStringT 物件大於 psz ，則為 0。

備註

泛型文字函 _tcscmp 式，定義于 TCHAR.H 中，會根據編譯時期定義的字元集，對應至 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
用於比較的其他字串。

傳回值

備註

在中定義的泛型文字函 _tcsicmp 式會根據編譯時期定義的字元集，對應至 _stricmp 或 _wcsicmp_mbsicmp 。 TCHAR.H 每個函式都會對字串執行不區分大小寫的比較。比較取決於 LC_CTYPE 地區設定的層面，而不是 LC_COLLATE 。如需詳細資訊，請參閱、、 _wcsicmp 、 _mbsicmp_stricmp_l 、 _wcsicmp_l 、 _mbsicmp_l 。 _stricmp

範例

// 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 物件。如需和 CThisSimpleString 的詳細資訊 CThisString ，請參閱一節。

varSrc
要複製到這個 CStringT 物件的 Variant 物件。

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

char （適用于 ANSI 字元字串）。

wchar_t （適用于 Unicode 字元字串）。

TCHAR （適用于 ANSI 和 Unicode 字元字串）。

bMFCDLL
布林值，指定專案是否為 MFC DLL （ TRUE ）（ FALSE ）。

SystemString
必須是 System::String ，而且專案必須使用編譯 /clr 。

pString
物件的控制碼 CStringT 。

備註

由於建構函式會將輸入資料複製到新的配置儲存體中，因此記憶體例外狀況可能會造成。其中有些建構函式會做為轉換函式。這可讓您取代，例如， LPTSTRCStringT 預期物件的位置。

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宣告 Class 的 CSimpleStringT 實例，這是比類別小的內建功能 CStringT 較小的字串類別。

多載運算子 CSimpleStringT<>&() 會 CStringT 從 CSimpleStringT 宣告建構物件。

注意

範例

// 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 將資料格式化為 C 樣式字元陣列的相同方式， sprintf_s 將資料寫入。

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 嘗試為新格式化的字串配置系統記憶體。如果此嘗試失敗，系統會自動擲回記憶體例外狀況。

每個插入都必須在或 nFormatID 參數之後 pszFormat 有對應的參數。在郵件內文中，支援數個逸出序列，以動態方式格式化訊息。如需詳細資訊，請參閱 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
引數清單的指標。

備註

以將資料格式化為 C 樣式字元陣列的相同方式 vsprintf_s ，將格式化字串和引數 CStringT 清單寫入字串。

範例

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。

備註

從呼叫進程的環境區塊擷取指定變數的值。值的格式為以 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 大於字串的長度，則函式會串連目前的字串和或 psz 所提供的 ch 新資料。

範例

// 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 傳回多位元組字元數乘以兩。

範例

// 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 字串資源識別碼。

wLanguageID
字串資源的語言。

傳回值

如果資源載入成功，則為非零;否則為 0。

備註

使用指定的語言從指定的模組（）載入字串資源 nID （ hInstancewLanguage ）。

範例

// 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 中的索引是單一式的。

對於多位元組字元集（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
要指派給這個字串的 Variant 物件。

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
要串連至此字串的 Variant 物件。

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
取代之 Null 終止字串 pszOld 的指標。

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`

重新配置 BSTR 所 pbstr 指向的，並將物件的內容 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。使用來追蹤下一個權杖要讀取的字串位置，可以透過對的一系列呼叫 TokenizeiStart ，將更多權杖細分為目標字串的其餘部分。當沒有任何標記時，函式會傳回空字串，並將 iStart 設定為 -1。

不同于 CRT Tokenize 函式，例如 strtok_s 、 _strtok_s_l 、 wcstok_s 、 _wcstok_s_l 、 _mbstok_s_l_mbstok_s 、、 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 >=`