CStringT クラス

  • [アーティクル]

このクラスは CStringT オブジェクトを表します。

構文

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

パラメーター

BaseType
文字列クラスの文字型。 以下のいずれかを指定できます。

  • char (ANSI 文字列の場合)。

  • wchar_t (Unicode 文字列の場合)。

  • TCHAR (ANSI と Unicode 両方の文字列の場合)。

StringTraits
文字列クラスに C ランタイム (CRT) ライブラリのサポートが必要かどうか、および文字列リソースがある場所を決定します。 以下のいずれかを指定できます。

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

    クラスは、CRT のサポートが必要であり、m_hInstResource (アプリケーションのモジュール クラスのメンバー) で指定されたモジュールでリソース文字列を検索します。

  • StrTraitATL<wchar_t | char | TCHAR, ChTraitsOS<wchar_t | char |TCHAR>>

    クラスは、CRT のサポートが必要ではなく、m_hInstResource (アプリケーションのモジュール クラスのメンバー) で指定されたモジュールでリソース文字列を検索します。

  • StrTraitMFC<wchar_t | char | TCHAR, ChTraitsCRT<wchar_t | char | TCHAR>>

    クラスは、CRT のサポートが必要であり、標準の MFC 検索アルゴリズムを使用してリソース文字列を検索します。

  • StrTraitMFC<wchar_t | char | TCHAR, ChTraitsOS<wchar_t | char | TCHAR>>

    クラスは、CRT のサポートが必要ではなく、標準の MFC 検索アルゴリズムを使用してリソース文字列を検索します。

メンバー

パブリック コンストラクター

名前 説明
CStringT::CStringT さまざまな方法で CStringT オブジェクトを作成します。
CStringT::~CStringT CStringT オブジェクトを破棄します。

パブリック メソッド

名前 説明
CStringT::AllocSysString CStringT データから BSTR を割り当てます。
CStringT::AnsiToOem ANSI 文字セットから OEM 文字セットへのインプレース変換を行います。
CStringT::AppendFormat 書式設定されたデータを既存の CStringT オブジェクトの後に追加します。
CStringT::Collate 2 つの文字列を比較します (大文字と小文字を区別し、ロケール固有の情報を使用します)。
CStringT::CollateNoCase 2 つの文字列を比較します (大文字と小文字を区別せず、ロケール固有の情報を使用します)。
CStringT::Compare 2 つの文字列を比較します (大文字と小文字を区別します)。
CStringT::CompareNoCase 2 つの文字列を比較します (大文字と小文字を区別しません)。
CStringT::Delete 文字列から 1 つまたは複数の文字を削除します。
CStringT::Find 大きな文字列内の文字または部分文字列を検索します。
CStringT::FindOneOf セットから最初に一致する文字を検索します。
CStringT::Format sprintf で行われるように文字列を書式設定します。
CStringT::FormatMessage メッセージ文字列を書式設定します。
CStringT::FormatMessageV 変数引数リストを使用してメッセージ文字列を書式設定します。
CStringT::FormatV 引数の変数リストを使用して文字列を書式設定します。
CStringT::GetEnvironmentVariable 文字列を、指定した環境変数の値に設定します。
CStringT::Insert 文字列内の指定したインデックスに 1 文字または部分文字列を挿入します。
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 既存の BSTR オブジェクトを、CStringT オブジェクトのデータで設定します。
CStringT::SpanExcluding 最初の文字から始めて、pszCharSet によって示される文字のセット内に含まれない文字を文字列から抽出します。
CStringT::SpanIncluding セット内の文字のみを含む部分文字列を抽出します。
CStringT::Tokenize ターゲット文字列内の指定したトークンを抽出します。
CStringT::Trim 文字列から先頭と末尾にあるすべての空白文字をトリミングします。
CStringT::TrimLeft 文字列から先頭にある空白文字をトリミングします。
CStringT::TrimRight 文字列から末尾にある空白文字をトリミングします。

演算子

名前 説明
CStringT::operator = 新しい値を CStringT オブジェクトに代入します。
CStringT::operator + 2 つの文字列または文字と文字列を連結します。
CStringT::operator += 既存の文字列の末尾に新しい文字列を連結します。
CStringT::operator == 2 つの文字列が論理的に等しいかどうかを判断します。
CStringT::operator != 2 つの文字列が論理的に等しくないかどうかを判断します。
CStringT::operator < 演算子の左辺の文字列が右辺の文字列より小さいかどうかを判断します。
CStringT::operator > 演算子の左辺の文字列が右辺の文字列より大きいかどうかを判断します。
CStringT::operator <= 演算子の左辺の文字列が右辺の文字列より小さいか、または等しいかどうかを判断します。
CStringT::operator >= 演算子の左辺の文字列が右辺の文字列より大きいか、または等しいかどうかを判断します。

解説

CStringT は CSimpleStringT クラスから継承します。 文字操作、順序付け、検索などの高度な機能は、CStringT によって実装されます。

Note

CStringT オブジェクトは例外をスローできます。 これは、何らかの理由で CStringT オブジェクトがメモリを使い切った場合に発生します。

CStringT オブジェクトは、文字の可変長のシーケンスで構成されます。 CStringT は、Basic と同様の構文を使用する関数と演算子を提供します。 連結演算子と比較演算子および簡素化されたメモリ管理により、CStringT オブジェクトを通常の文字配列より使いやすくなっています。

Note

埋め込まれた null 文字が含まれる CStringT インスタンスを作成することはできますが、推奨されません。 埋め込まれた null 文字が含まれる CStringT オブジェクトでメソッドと演算子を呼び出すと、意図しない結果になる可能性があります。

BaseType パラメーターと StringTraits パラメーターの異なる組み合わせを使用することで、CStringT オブジェクトは、ATL ライブラリによって事前に定義されている次の型になります。

ATL アプリケーションで使用する場合:

CString、CStringA、CStringW は、ユーザーの DLL からではなく、MFC DLL (MFC90.DLL) からエクスポートされます。 これは、CStringT が複数回定義されるのを防ぐために行われます。

Note

「CStringT を使用した文字列クラスのエクスポート」で説明されているリンカー エラーの回避策がコードに含まれている場合は、そのコードを削除する必要があります。 これは不要になりました。

MFC ベースのアプリケーションでは、次の文字列型を使用できます。

CStringT 型 宣言
CStringA CRT をサポートする ANSI 文字型の文字列。
CStringW CRT をサポートする Unicode 文字型の文字列。
CString CRT をサポートする ANSI と Unicode 両方の文字型。

ATL_CSTRING_NO_CRT が定義されているプロジェクトでは、次の文字列型を使用できます。

CStringT 型 宣言
CAtlStringA CRT をサポートしない ANSI 文字型の文字列。
CAtlStringW CRT をサポートしない Unicode 文字型の文字列。
CAtlString CRT をサポートしない ANSI と Unicode 両方の文字型。

ATL_CSTRING_NO_CRT が定義されていないプロジェクトでは、次の文字列型を使用できます。

CStringT 型 宣言
CAtlStringA CRT をサポートする ANSI 文字型の文字列。
CAtlStringW CRT をサポートする Unicode 文字型の文字列。
CAtlString CRT をサポートする ANSI と Unicode 両方の文字型。

CString オブジェクトには、次のような特徴があります。

  • CStringT オブジェクトは、連結操作のために拡大する可能性があります。

  • CStringT オブジェクトは "値のセマンティクス" に従います。 CStringT オブジェクトは、文字列へのポインターとしてではなく、実際の文字列と考える必要があります。

  • PCXSTR 関数の引数を CStringT オブジェクトに自由に置き換えることができます。

  • 文字列バッファーのカスタム メモリ管理。 詳細については、メモリ管理と CStringT に関する記事を参照してください。

CStringT の定義済みの型

CStringT ではテンプレート引数を使用して、サポートされている文字型 (wchar_t または char) を定義するため、メソッドのパラメーターの型が複雑になる場合があります。 この問題を簡単にするため、定義済みの型のセットが定義されており、CStringT クラス全体で使用されます。 次の表は、さまざまな型の一覧です。

名前 説明
XCHAR CStringT オブジェクトと同じ文字型の 1 文字 (wchar_t または char)。
YCHAR CStringT オブジェクトと逆の文字型の 1 文字 (wchar_t または char)。
PXSTR CStringT オブジェクトと同じ文字型の文字列 (wchar_t または char) へのポインター。
PYSTR CStringT オブジェクトと逆の文字型の文字列 (wchar_t または char) へのポインター。
PCXSTR CStringT オブジェクトと同じ文字型の const 文字列 (wchar_t または char) へのポインター。
PCYSTR CStringT オブジェクトと逆の文字型の const 文字列 (wchar_t または char) へのポインター。

Note

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 がスローされます。 この関数は、通常、オートメーション用の文字列を返すために使用されます。

一般に、この文字列を [in] パラメーターとして COM 関数に渡す場合、呼び出し元は文字列を解放する必要があります。 これは、Windows SDK で説明されているように、SysFreeString を使用して行うことができます。 詳細については、「BSTR のメモリの割り当てと解放」を参照してください。

Windows での OLE 割り当て関数の詳細については、Windows SDK の SysAllocString を参照してください。

例

次の例は、CStringT::AllocSysString の使い方を示しています。

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString str(_T("This is a test string!"));
BSTR bstr = str.AllocSysString();

// bstr now contains "This is a test string!", and can be
// passed to any OLE function requiring a BSTR.
// Normally, if you pass the BSTR, you will
// need to free the string after returning from the function call.

CStringT::AnsiToOem

この CStringT オブジェクトのすべての文字を、ANSI 文字セットから OEM 文字セットに変換します。

void AnsiToOem();

解説

この関数は、_UNICODE が定義されている場合は使用できません。

例

// OEM character 252 on most IBM-compatible computers in
// many countries/regions is superscript n, as in 2^n.
// Converting it to the ANSI English charset results in a
// normal character 'n', which is the closest possible
// representation.

CStringT<char, StrTraitATL<char, ChTraitsCRT<char>>> str((WCHAR)252);
str.OemToAnsi();
ASSERT(str[0] == 'n');

// Be aware that in OEM to ANSI conversion the 'n'
// from the previous result cannot be converted back to
// a supsercript n because the system does not know what
// the character's value truly was.
str.AnsiToOem();
ASSERT(str[0] != 252);
ASSERT(str[0] == 'n');

CStringT::AppendFormat

書式設定されたデータを既存の CStringT オブジェクトの後に追加します。

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

パラメーター

pszFormat
書式制御文字列。

nFormatID
書式制御文字列を含む文字列リソース識別子。

argument
省略可能な引数。

解説

この関数は、一連の文字と値の書式を設定して CStringT に追加します。 省略可能な各引数 (存在する場合) は、pszFormat 内の、または nFormatID によって示される文字列リソースからの、対応する書式指定に従って変換されて追加されます。

例

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

CAtlString str = _T("Some data:\t");

str.AppendFormat(_T("X value = %.2f\n"), 12345.12345);
_tprintf_s(_T("%s"), (LPCTSTR) str);

CStringT::Collate

汎用テキスト関数 _tcscoll を使用して、2 つの文字列を比較します。

int Collate(PCXSTR psz) const throw();

パラメーター

psz
比較に使用される他の文字列。

戻り値

文字列が同一の場合は 0、この CStringT オブジェクトが psz より小さい場合は < 0、この CStringT オブジェクトが psz より大きい場合は > 0。

解説

TCHAR.H で定義されている汎用テキスト関数 _tcscoll は、コンパイル時に定義されている文字セットに応じて、strcoll、wcscoll、または _mbscoll にマップされます。 各関数では、現在使用されているコード ページに従って、大文字と小文字を区別する文字列の比較が行われます。 詳細については、「strcoll、wcscoll、_mbscoll、_strcoll_l、_wcscoll_l、_mbscoll_l」を参照してください。

CStringT::CollateNoCase

汎用テキスト関数 _tcscoll を使用して、2 つの文字列を比較します。

int CollateNoCase(PCXSTR psz) const throw();

パラメーター

psz
比較に使用される他の文字列。

戻り値

文字列が同一の場合は 0 (大文字と小文字を無視)、この CStringT オブジェクトが psz より小さい場合は < 0 (大文字と小文字を無視)、この CStringT オブジェクトが psz より大きい場合は > 0 (大文字と小文字を無視)。

解説

TCHAR.H で定義されている汎用テキスト関数 _tcscoll は、コンパイル時に定義されている文字セットに応じて、stricoll、wcsicoll、または _mbsicoll にマップされます。 各関数では、現在使用されているコード ページに従って、大文字と小文字を区別しない文字列の比較が行われます。 詳細については、「strcoll、wcscoll、_mbscoll、_strcoll_l、_wcscoll_l、_mbscoll_l」を参照してください。

例

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

CAtlString str1 = _T("Co-Op");
CAtlString str2 = _T("con");

int n;

// Collation uses language rules, such as ignoring dashes.
// NoCase version ignores case.
n = str1.CollateNoCase(str2);
ASSERT(n < 0);

// Comparison is a strict ASCII comparison with no language rules
// but still ignores case in NoCase version.
n = str1.CompareNoCase(str2);
ASSERT(n < 0);

CStringT::Compare

2 つの文字列を比較します (大文字と小文字を区別します)。

int Compare(PCXSTR psz) const;

パラメーター

psz
比較に使用される他の文字列。

戻り値

文字列が同一の場合は 0、この CStringT オブジェクトが psz より小さい場合は < 0、この CStringT オブジェクトが psz より大きい場合は > 0。

解説

TCHAR.H で定義されている汎用テキスト関数 _tcscmp は、コンパイル時に定義されている文字セットに応じて、strcmp、wcscmp、または _mbscmp にマップされます。 各関数では、大文字と小文字を区別して文字列の比較が行われ、ロケールによる影響は受けません。 詳細については、strcmp、wcscmp、_mbscmp に関する記事を参照してください。

文字列に埋め込まれた null が含まれる場合は、比較のため、文字列は埋め込まれた最初の null 文字で切り捨てられるものと見なされます。

例

次の例は、CStringT::Compare の使い方を示しています。

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

CAtlString s1(_T("abc"));
CAtlString s2(_T("abd"));
ASSERT(s1.Compare(s2) < 0);    // Compare with another CAtlString.
ASSERT(s1.Compare(_T("abe")) < 0); // Compare with LPTSTR string.

CStringT::CompareNoCase

2 つの文字列を比較します (大文字と小文字を区別しません)。

int CompareNoCase(PCXSTR psz) const throw();

パラメーター

psz
比較に使用される他の文字列。

戻り値

文字列が同一の場合は 0 (大文字と小文字を無視)、この CStringT オブジェクトが psz より小さい場合は < 0 (大文字と小文字を無視)、この CStringT オブジェクトが psz より大きい場合は > 0 (大文字と小文字を無視)。

解説

TCHAR.H で定義されている汎用テキスト関数 _tcsicmp は、コンパイル時に定義されている文字セットに応じて、_stricmp、_wcsicmp、または _mbsicmp にマップされます。 各関数では、大文字と小文字を区別しない文字列の比較が行われます。 比較は、ロケールの LC_CTYPE の部分には依存しますが、LC_COLLATE には依存しません。 詳細については、「_stricmp、_wcsicmp、_mbsicmp、_stricmp_l、_wcsicmp_l、_mbsicmp_l」を参照してください。

例

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

CAtlString s1(_T("abc"));
CAtlString s2(_T("ABD"));
ASSERT(s1.CompareNoCase(s2) < 0); // Compare with a CAtlString.
ASSERT(s1.CompareNoCase(_T("ABE")) < 0); // Compare with LPTSTR string.

CStringT::CStringT

CStringT オブジェクトを構築します。

CStringT() throw() :
    CThisSimpleString(StringTraits::GetDefaultManager());

explicit CStringT(IAtlStringMgr* pStringMgr) throw() :
    CThisSimpleString( pStringMgr);

CStringT(const VARIANT& varSrc);

CStringT(const VARIANT& varSrc, IAtlStringMgr* pStringMgr);

CStringT(const CStringT& strSrc) :
    CThisSimpleString( strSrc);

operator CSimpleStringT<
                    BaseType,
                    !_CSTRING_IMPL_::_MFCDLLTraitsCheck<BaseType, StringTraits>
                    :: c_bIsMFCDLLTraits> &()

template <bool bMFCDLL>
CStringT(const CSimpleStringT<BaseType, bMFCDLL>& strSrc) :
    CThisSimpleString( strSrc);

template <class SystemString>
CStringT(SystemString^ pString) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const XCHAR* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(const YCHAR* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(LPCSTR pszSrc, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

CStringT(LPCWSTR pszSrc, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

CSTRING_EXPLICIT CStringT(const unsigned char* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

/*CSTRING_EXPLICIT*/ CStringT(char* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(unsigned char* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(wchar_t* pszSrc) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const unsigned char* pszSrc, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

CSTRING_EXPLICIT CStringT(char ch, int nLength = 1) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CSTRING_EXPLICIT CStringT(wchar_t ch, int nLength = 1) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const XCHAR* pch, int nLength) :
    CThisSimpleString( pch, nLength, StringTraits::GetDefaultManager());

CStringT(const YCHAR* pch, int nLength) :
    CThisSimpleString( StringTraits::GetDefaultManager());

CStringT(const XCHAR* pch, int nLength, AtlStringMgr* pStringMgr) :
    CThisSimpleString( pch, nLength, pStringMgr);

CStringT(const YCHAR* pch, int nLength, IAtlStringMgr* pStringMgr) :
    CThisSimpleString( pStringMgr);

パラメーター

pch
null で終了していない、長さが nLength の文字の配列へのポインター。

nLength
pch 内の文字数。

ch
1 つの文字。

pszSrc
この CStringT オブジェクトにコピーする、null で終了している文字列。

pStringMgr
CStringT オブジェクトのメモリ マネージャーへのポインター。 IAtlStringMgr と、CStringT のメモリ管理の詳細については、「CStringT でのメモリ管理」を参照してください。

strSrc
この CStringT オブジェクトにコピーする既存の CStringT オブジェクト。 CThisString と CThisSimpleString の詳細については、「解説」セクションを参照してください。

varSrc
この CStringT オブジェクトにコピーするバリアント オブジェクト。

BaseType
文字列クラスの文字型。 以下のいずれかを指定できます。

char (ANSI 文字列の場合)。

wchar_t (Unicode 文字列の場合)。

TCHAR (ANSI と Unicode 両方の文字列の場合)。

bMFCDLL
プロジェクトが MFC DLL か (TRUE)、そうではないか (FALSE) を指定するブール値。

SystemString
System::String である必要があり、プロジェクトは /clr でコンパイルされている必要があります。

pString
CStringT オブジェクトのハンドル。

解説

コンストラクターによって入力データが割り当てられた新しいストレージにコピーされるので、メモリ例外が発生する可能性があります。 これらのコンストラクターの一部は、変換関数として機能します。 これにより、たとえば、CStringT オブジェクトが必要な LPTSTR を置き換えることができます。

  • CStringT( LPCSTR lpsz ): ANSI 文字列から Unicode CStringT を構築します。 次の例に示すように、このコンストラクターを使用して文字列リソースを読み込むこともできます。

  • CStringT(LPCWSTR lpsz): Unicode 文字列からCStringTを構築します。

  • CStringT( const unsigned char* psz ): unsigned charへのポインターからCStringTを構築できます。

Note

ANSI 文字列と Unicode 文字列の間の暗黙的な文字列変換を無効にするには、_CSTRING_DISABLE_NARROW_WIDE_CONVERSION マクロを定義します。 このマクロは、変換をサポートするコンパイル コンストラクターを除外します。

strSrc パラメーターには、CStringT または CThisSimpleString オブジェクトを指定できます。 CStringT の場合は、既定のインスタンス化 (CString、CStringA、または CStringW) のいずれかを使用します。CThisSimpleString の場合は、this ポインターを使用します。 CThisSimpleString では、CSimpleStringT クラスのインスタンスが宣言されています。これは、CStringT クラスより組み込み機能が少ない小さな文字列クラスです。

オーバーロード演算子 CSimpleStringT<>&() は、CSimpleStringT の宣言から CStringT オブジェクトを作成します。

Note

埋め込まれた null 文字が含まれる CStringT インスタンスを作成することはできますが、推奨されません。 埋め込まれた null 文字が含まれる CStringT オブジェクトでメソッドと演算子を呼び出すと、意図しない結果になる可能性があります。

例

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

CAtlString s1;                    // Empty string
CAtlString s2(_T("cat"));           // From a C string literal
CAtlString s3 = s2;               // Copy constructor
CAtlString s4(s2 + _T(" ") + s3);   // From a string expression

CAtlString s5(_T('x'));             // s5 = "x"
CAtlString s6(_T('x'), 6);          // s6 = "xxxxxx"

CAtlString s7((LPCSTR)ID_FILE_NEW); // s7 = "Create a new document"

VARIANT var;
V_VT(&var) = VT_BSTR;
V_BSTR(&var) = ::SysAllocString(L"Football is a fun sport.");
CAtlString s8(var); // s8 = "Football is a fun sport."

// The following statement does not call the assignment operator.
// The compiler considers the following statement equivalent to
// CAtlString city("Paris")
CAtlString city = _T("Paris");

CStringT::~CStringT

CStringT オブジェクトを破棄します。

~CStringT() throw();

解説

CStringT オブジェクトを破棄します。

CStringT::Delete

指定したインデックス位置の文字で始まる文字列から、1 つまたは複数の文字を削除します。

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

パラメーター

iIndex
CStringT オブジェクト内の削除する最初の文字の 0 から始まるインデックス。

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
検索する 1 文字。

戻り値

この CStringT オブジェクト内で、要求した部分文字列または文字と一致する最初の文字の 0 から始るインデックス。部分文字列または文字が見つからない場合は -1。

解説

関数は、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 にも含まれる最初の文字の 0 から始るインデックス。一致がない場合は -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

sprintf_s が C スタイルの文字配列にデータを書式設定するのと同じ方法で、書式設定されたデータを CStringT に書き込みます。

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 オブジェクトにコピーし、要求されている場合は、埋め込まれる挿入シーケンスを処理します。

Note

FormatMessage は、新しく書式設定される文字列へのシステム メモリの割り当てを試みます。 この試みが失敗すると、メモリ例外が自動的にスローされます。

各挿入には、pszFormat または nFormatID パラメーターの後に対応するパラメーターが必要です。 メッセージ テキスト内では、メッセージを動的に書式設定するための複数のエスケープ シーケンスがサポートされています。 詳細については、Windows SDK で Windows の FormatMessage 関数を参照してください。

例

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

CAtlString str;
int nAsked = 5;
int nAgree = 4;

str.FormatMessage(_T("%1!d! of %2!d! writers agree: Soccer is %3%!"), 
   nAgree, nAsked, _T("Best"));
ASSERT(str == _T("4 of 5 writers agree: Soccer is Best!"));

CStringT::FormatMessageV

変数引数リストを使用してメッセージ文字列を書式設定します。

void FormatMessageV(PCXSTR pszFormat, va_list* pArgList);

パラメーター

pszFormat
書式制御文字列を指します。 挿入がスキャンされ、それに従って書式設定されます。 書式指定文字列は、パラメーターを任意の順序で挿入できる点を除き、ランタイム関数 printf のスタイルの書式指定文字列に似ています。

pArgList
引数のリストへのポインター。

解説

この関数には、入力として pszFormat によって決定されるメッセージ定義が必要です。 この関数は、書式設定されたメッセージ テキストと引数の変数リストを CStringT オブジェクトにコピーし、要求されている場合は、埋め込まれる挿入シーケンスを処理します。

Note

FormatMessageV は CStringT::FormatMessage を呼び出して、新しく書式設定される文字列へのシステム メモリの割り当てを試みます。 この試みが失敗すると、メモリ例外が自動的にスローされます。

詳細については、Windows SDK で Windows の FormatMessage 関数を参照してください。

CStringT::FormatV

変数引数リストを使用してメッセージ文字列を書式設定します。

void FormatV(PCXSTR pszFormat, va_list args);

パラメーター

pszFormat
書式制御文字列を指します。 挿入がスキャンされ、それに従って書式設定されます。 書式指定文字列は、パラメーターを任意の順序で挿入できる点を除き、ランタイム関数 printf のスタイルの書式指定文字列に似ています。

args
引数のリストへのポインター。

解説

vsprintf_s が C スタイルの文字配列にデータを書式設定するのと同じ方法で、書式設定された文字列と引数の変数リストを 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 以外を返します。それ以外の場合は 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

文字列内の指定したインデックスに 1 文字または部分文字列を挿入します。

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

パラメーター

iIndex
挿入位置の直後にある文字のインデックス。

psz
挿入する部分文字列へのポインター。

ch
挿入する文字。

戻り値

変更後の文字列の長さ。

解説

iIndex パラメーターは、文字または部分文字列のためのスペースを空けるために移動される最初の文字を示します。 nIndex が 0 の場合、文字列全体の前に挿入されます。 nIndex が文字列の長さを超える場合、関数は現在の文字列と、ch または psz によって提供される新しい文字または部分文字列を連結します。

例

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

CAtlString str(_T("SoccerBest"));
int n = str.Insert(6, _T("is "));
ASSERT(n == str.GetLength());
_tprintf_s(_T("1: %s\n"), (LPCTSTR) str);

n = str.Insert(6, _T(' '));
ASSERT(n == str.GetLength());
_tprintf_s(_T("2: %s\n"), (LPCTSTR) str);

n = str.Insert(55, _T('!'));
ASSERT(n == str.GetLength());
_tprintf_s(_T("3: %s\n"), (LPCTSTR) str);

CStringT::Left

この CStringT オブジェクトから左端の nCount 文字を抽出し、抽出された部分文字列のコピーを返します。

CStringT Left(int nCount) const;

パラメーター

nCount
この CStringT オブジェクトから抽出する文字数。

戻り値

指定の文字範囲のコピーを含む CStringT オブジェクト。 返された CStringT オブジェクトは空の場合があります。

解説

nCount が文字列の長さより大きい場合は、文字列全体が抽出されます。 Left は、Basic Left 関数に類似します。

マルチバイト文字セット (MBCS) では、nCount は 8 ビットの各並びを文字として処理します。したがって、nCount では 2 倍のマルチバイト文字数が返されます。

例

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

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

CStringT::LoadString

nID によって示される Windows 文字列リソースを、既存の CStringT オブジェクトに読み取ります。

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

パラメーター

hInstance
モジュールのインスタンスへのハンドル。

nID
Windows 文字列リソース ID。

wLanguageID
文字列リソースの言語。

戻り値

リソースの読み込みが成功した場合は 0 以外。それ以外の場合は 0。

解説

指定した言語 (wLanguage) を使用して、指定したモジュール (hInstance) から文字列リソース (nID) を読み込みます。

例

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

CAtlString s;
s.LoadString(IDS_APP_TITLE);

CStringT::MakeLower

CStringT オブジェクトを小文字の文字列に変換します。

CStringT& MakeLower();

戻り値

結果の小文字の文字列。

例

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

CAtlString s(_T("ABC"));

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

CStringT::MakeReverse

CStringT オブジェクト内の文字の順序を反転します。

CStringT& MakeReverse();

戻り値

結果の反転された文字列。

例

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

CAtlString s(_T("abc"));

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

CStringT::MakeUpper

CStringT オブジェクトを大文字の文字列に変換します。

CStringT& MakeUpper();

戻り値

結果の大文字の文字列。

解説

例

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

CAtlString s(_T("abc"));

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

CStringT::Mid

この CStringT オブジェクトの、開始位置 iFirst (0 から始まる) から、nCount 文字の長さの部分文字列を抽出します。

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

パラメーター

iFirst
抽出された部分文字列に含める、この CStringT オブジェクトの最初の文字の、0 から始まるインデックス。

nCount
この CStringT オブジェクトから抽出する文字数。 このパラメーターを指定しないと、文字列の残りの部分が抽出されます。

戻り値

指定の文字範囲のコピーを含む CStringT オブジェクト。 返された CStringT オブジェクトは空の場合があります。

解説

関数からは、抽出された部分文字列のコピーが返されます。 Mid は、Basic の Mid 関数に似ています (ただし、Basic のインデックスは 1 から始まります)。

マルチバイト文字セット (MBCS) の場合、nCount は各 8 ビット文字を参照します。つまり、1 つのマルチバイト文字の先行バイトと後続バイトは 2 文字としてカウントされます。

例

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

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

CStringT::OemToAnsi

この CStringT オブジェクトのすべての文字を、OEM 文字セットから ANSI 文字セットに変換します。

void OemToAnsi();

解説

この関数は、_UNICODE が定義されている場合は使用できません。

例

CStringT::AnsiToOem の例を参照してください。

CStringT::operator =

文字列に新しい値を割り当てます。

CStringT& operator=(const CStringT& strSrc);

template<bool bMFCDLL>
CStringT& operator=(const CSimpleStringT<BaseType, bMFCDLL>& str);
CStringT& operator=(PCXSTR pszSrc);
CStringT& operator=(PCYSTR pszSrc);
CStringT& operator=(const unsigned char* pszSrc);
CStringT& operator=(XCHAR ch);
CStringT& operator=(YCHAR ch);
CStringT& operator=(const VARIANT& var);

パラメーター

strSrc
この文字列に割り当てる CStringT。

str
CThisSimpleString オブジェクトへの参照です。

bMFCDLL
プロジェクトが MFC DLL かどうかを指定するブール値。

BaseType
文字列の基本データ型。

var
この文字列に割り当てるバリアント オブジェクト。

ch
文字列に割り当てる ANSI または Unicode 文字。

pszSrc
割り当てられる元の文字列へのポインター。

解説

この代入演算子は、別の CStringT オブジェクト、文字ポインター、または 1 文字を受け付けます。 この演算子を使用するたびに、新しいストレージが割り当てられる場合があるので、メモリ例外が発生する可能性があります。

CThisSimpleString の詳細については、CStringT::CStringT の「解説」セクションを参照してください。

Note

埋め込まれた null 文字が含まれる CStringT インスタンスを作成することはできますが、推奨されません。 埋め込まれた null 文字が含まれる CStringT オブジェクトでメソッドと演算子を呼び出すと、意図しない結果になる可能性があります。

CStringT::operator +

2 つの文字列または文字と文字列を連結します。

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+ 関数には 7 つのオーバーロード形式があります。 1 つ目のバージョンは、2 つの既存の CStringT オブジェクトを連結します。 次の 2 つは、CStringT オブジェクトと null で終わる文字列を連結します。 次の 2 つは、CStringT オブジェクトと ANSI 文字を連結します。 最後の 2 つは、CStringT オブジェクトと Unicode 文字を連結します。

Note

埋め込まれた null 文字が含まれる CStringT インスタンスを作成することはできますが、推奨されません。 埋め込まれた null 文字が含まれる CStringT オブジェクトでメソッドと演算子を呼び出すと、意図しない結果になる可能性があります。

例

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString s1(_T("dog ")), s2(_T(" awake")), s3;  // Empty CAtlString objects

s1= _T("The ") + s1;
s3= s1 + _T('i');
s3= s3 + _T('s');
s3= s3 + s2;
ASSERT(s3 == _T("The dog is awake"));

CStringT::operator +=

文字列の末尾に文字を連結します。

CStringT& operator+=(const CThisSimpleString& str);

template<bool bMFCDLL>
CStringT& operator+=(const const CSimpleStringT<BaseType, bMFCDLL>& str);

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

パラメーター

str
CThisSimpleString オブジェクトへの参照です。

bMFCDLL
プロジェクトが MFC DLL かどうかを指定するブール値。

BaseType
文字列の基本データ型。

var
この文字列に連結するバリアント オブジェクト。

ch
文字列と連結する ANSI または Unicode の文字。

pszSrc
連結される元の文字列へのポインター。

strSrc
この文字列に連結する CStringT。

解説

この演算子は、別の CStringT オブジェクト、文字ポインター、または 1 文字を受け付けます。 この連結演算子を使用するたびに、この CStringT オブジェクトに追加される文字のために新しいストレージが割り当てられる場合があるので、メモリ例外が発生する可能性があります。

CThisSimpleString の詳細については、CStringT::CStringT の「解説」セクションを参照してください。

Note

埋め込まれた null 文字が含まれる CStringT インスタンスを作成することはできますが、推奨されません。 埋め込まれた null 文字が含まれる CStringT オブジェクトでメソッドと演算子を呼び出すと、意図しない結果になる可能性があります。

例

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

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

CStringT::operator ==

2 つの文字列が論理的に等しいかどうかを判断します。

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

2 つの文字列が論理的に等しくないかどうかを判断します。

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 で終わる文字列へのポインター。

解説

次の条件が満たされるまで 1 文字ずつ行われる文字列間の辞書順比較:

  • 2 つの対応する文字が等しくない場合、比較の結果は文字列間の比較の結果として取得されます。

  • 不等が見つからなくても、1 つの文字列に他より多くの文字がある場合、短い文字列は長い文字列より小さいと見なされます。

  • 不等が見つからず、各文字列の文字数が同じである場合、文字列が等しくなります。

例

// 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 で終わる文字列へのポインター。

解説

次の条件が満たされるまで 1 文字ずつ行われる文字列間の辞書順比較:

  • 2 つの対応する文字が等しくない場合、比較の結果は文字列間の比較の結果として取得されます。

  • 不等が見つからなくても、1 つの文字列に他より多くの文字がある場合、短い文字列は長い文字列より小さいと見なされます。

  • 不等が見つからず、各文字列の文字数が同じである場合、文字列が等しくなります。

例

// 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 で終わる文字列へのポインター。

解説

次の条件が満たされるまで 1 文字ずつ行われる文字列間の辞書順比較:

  • 2 つの対応する文字が等しくない場合、比較の結果は文字列間の比較の結果として取得されます。

  • 不等が見つからなくても、1 つの文字列に他より多くの文字がある場合、短い文字列は長い文字列より小さいと見なされます。

  • 不等が見つからず、各文字列の文字数が同じである場合、文字列が等しくなります。

例

// 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
比較対象の文字列へのポインター。

解説

次の条件が満たされるまで 1 文字ずつ行われる文字列間の辞書順比較:

  • 2 つの対応する文字が等しくない場合、比較の結果は文字列間の比較の結果として取得されます。

  • 不等が見つからなくても、1 つの文字列に他より多くの文字がある場合、短い文字列は長い文字列より小さいと見なされます。

  • 不等が見つからず、各文字列の文字数が同じである場合、文字列が等しくなります。

例

// 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
文字列から削除する文字。

戻り値

文字列から削除された文字数。 文字列が変更されていない場合は 0。

解説

文字の比較では、大文字と小文字が区別されます。

例

// 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 には 2 つのバージョンがあります。 1 つ目のバージョンは、部分文字列の 1 つ以上のコピーを、別の部分文字列を使用して置き換えます。 どちらの部分文字列も null で終わります。 2 つ目のバージョンは、文字の 1 つ以上のコピーを、別の文字を使用して置き換えます。 どちらのバージョンも、CStringT に格納されている文字データを処理します。

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

パラメーター

pszOld
pszNew で置き換えられる null で終わる文字列へのポインター。

pszNew
pszOld を置き換える null で終わる文字列へのポインター。

chOld
chNew で置き換えられ文字。

chNew
chOld を置き換える文字。

戻り値

置き換えられた文字または部分文字列のインスタンスの数を返します。文字列が変更されていない場合は 0 です。

解説

pszNew と pszOld は同じ長さである必要はなく、古い部分文字列の複数のコピーが新しいものに変更される場合があるため、Replace では文字列の長さが変化する可能性があります。 この関数では、大文字と小文字を区別した一致が行われます。

CStringT のインスタンスの例としては、CString、CStringA、CStringW などがあります。

CStringA の場合、Replace は ANSI またはマルチバイト (MBCS) 文字を処理します。 CStringW の場合、Replace はワイド文字を処理します。

CString の場合、次の表の定数が定義されているかどうかを基に、コンパイル時に文字データ型が選択されます。

定義されている定数 文字のデータ型
_UNICODE ワイド文字
_MBCS マルチバイト文字セットを使用する
どちらもオフ 1 バイト文字
両方 Undefined

例

// 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 オブジェクト内で、要求した文字と一致する最後の文字の 0 から始るインデックス。文字が見つからない場合は -1。

解説

この関数は、ランタイム関数 strrchr に似ています。

例

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

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

この CStringT オブジェクトから最後 (つまり右端) の nCount 文字を抽出し、抽出された部分文字列のコピーを返します。

CStringT Right(int nCount) const;

パラメーター

nCount
この CStringT オブジェクトから抽出する文字数。

戻り値

指定の文字範囲のコピーを含む CStringT オブジェクト。 返される CStringT オブジェクトは空の場合があります。

解説

nCount が文字列の長さより大きい場合は、文字列全体が抽出されます。 Right は、Basic の Right 関数に似ています (ただし、Basic のインデックスは 0 から始まります)。

マルチバイト文字セット (MBCS) の場合、nCount は各 8 ビット文字を参照します。つまり、1 つのマルチバイト文字の先行バイトと後続バイトは 2 文字としてカウントされます。

例

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

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

CStringT::SetSysString

pbstr によって指し示されている BSTR を割り当て直し、CStringT オブジェクトの内容を、NULL 文字も含めて、それにコピーします。

BSTR SetSysString(BSTR* pbstr) const;

パラメーター

pbstr
文字列へのポインター。

戻り値

新しい文字列。

解説

CStringT オブジェクトの内容によっては、pbstr によって参照されている BSTR の値が変化する可能性があります。 メモリが不足している場合、この関数は CMemoryException をスローします。

この関数は、通常、Automation の参照によって渡される文字列の値を変更するために使用されます。

例

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
検索を開始する 0 から始まるインデックス。

戻り値

現在のトークン値が含まれる CStringT オブジェクト。

解説

Tokenize 関数は、ターゲット文字列内で次のトークンを検索します。 pszTokens の文字セットは、検索対象のトークンの使用可能な区切り記号を指定します。 Tokenize を呼び出すたびに、関数は iStart から開始し、先頭の区切り記号をスキップして、現在のトークンを含む CStringT オブジェクトを返します。これは、次の区切り記号文字までの文字列です。 iStart の値は、終了区切り記号文字の後の位置に更新されます。文字列の末尾に達した場合は -1 になります。 iStart を使用して文字列で次のトークンを読み取る位置を追跡しながら、Tokenize を続けて呼び出すことにより、ターゲット文字列の残りの部分からさらにトークンを抽出できます。 それ以上トークンがない場合、関数からは空の文字列が返され、iStart は -1 に設定されます。

、strtok_s、_strtok_s_l、wcstok_s、_wcstok_s_l、_mbstok_s、_mbstok_s_l のような CRT のトークン化関数とは異なり、Tokenize ではターゲット文字列は変更されません。

例

// typedef CStringT<TCHAR, StrTraitATL<TCHAR, ChTraitsCRT<TCHAR>>> CAtlString;
CAtlString str(_T("%First Second#Third"));
CAtlString resToken;
int curPos = 0;

resToken= str.Tokenize(_T("% #"),curPos);
while (resToken != _T(""))
{
   _tprintf_s(_T("Resulting token: %s\n"), resToken);
   resToken = str.Tokenize(_T("% #"), curPos);
};

この例からの出力は次のようになります。

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

CStringT::Trim

文字列の先頭と末尾の文字をトリミングします。

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

パラメーター

chTarget
トリミング対象の文字。

pszTargets
トリミング対象の文字が含まれる文字列へのポインター。 先頭と末尾に出現する pszTargets のすべての文字が、CStringT オブジェクトからトリミングされます。

戻り値

トリミングされた文字列を返します。

解説

先頭と末尾に出現する次のいずれかが、すべて削除されます。

  • chTarget で指定されている文字。

  • pszTargets で指定されている文字列内のすべての文字。

  • 空白文字。

例

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

CAtlString str;
str = _T("******Soccer is best!?!?!?!?!");

_tprintf_s(_T("Before: \"%s\"\n"), (LPCTSTR)str);
_tprintf_s(_T("After : \"%s\"\n"), (LPCTSTR)str.Trim(_T("?!*")));

// Output:
// --------------------------
// Before: ******Soccer is best!?!?!?!?!
// After: Soccer is best

この例からの出力は次のようになります。

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

CStringT::TrimLeft

文字列から先頭の文字をトリミングします。

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

パラメーター

chTarget
トリミング対象の文字。

pszTargets
トリミング対象の文字が含まれる文字列へのポインター。 先頭に出現する pszTargets のすべての文字が、CStringT オブジェクトからトリミングされます。

戻り値

結果のトリミングされた文字列。

解説

先頭と末尾に出現する次のいずれかが、すべて削除されます。

  • chTarget で指定されている文字。

  • pszTargets で指定されている文字列内のすべての文字。

  • 空白文字。

例

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

CAtlString str;
str = _T("\t\t   ****Soccer is best!");

_tprintf_s(_T("Before: \"%s\"\n"), (LPCTSTR)str);
_tprintf_s(_T("After: \"%s\"\n"), (LPCTSTR)str.TrimLeft(_T("\t *")));

// Output:
// --------------------------
// Before:     ****Soccer is best!
// After: Soccer is best!

CStringT::TrimRight

文字列から末尾にある文字をトリミングします。

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

パラメーター

chTarget
トリミング対象の文字。

pszTargets
トリミング対象の文字が含まれる文字列へのポインター。 末尾に出現する pszTargets のすべての文字が、CStringT オブジェクトからトリミングされます。

戻り値

トリミングされた後の文字列を含む CStringT オブジェクトを返します。

解説

末尾に出現する次のいずれかが削除されます。

  • chTarget で指定されている文字。

  • pszTargets で指定されている文字列内のすべての文字。

  • 空白文字。

CStringT& TrimRight(XCHAR chTarget) バージョンは、1 つの文字パラメーターを受け取り、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 クラス