CSimpleStringT クラス

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

構文

template <typename BaseType>
class CSimpleStringT

パラメーター

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

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

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

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

メンバー

パブリック typedef

名前	説明
CSimpleStringT::PCXSTR	定数文字列へのポインター。
CSimpleStringT::PXSTR	文字列へのポインター。

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

名前	説明
CSimpleStringT::CSimpleStringT	さまざまな方法で CSimpleStringT オブジェクトを作成します。
CSimpleStringT::~CSimpleStringT	デストラクターです。

パブリック メソッド

名前	説明
CSimpleStringT::Append	CSimpleStringT オブジェクトを既存の CSimpleStringT オブジェクトに追加します。
CSimpleStringT::AppendChar	文字を既存の CSimpleStringT オブジェクトに追加します。
CSimpleStringT::CopyChars	1 つ以上の文字を別の文字列にコピーします。
CSimpleStringT::CopyCharsOverlapped	1 つ以上の文字を、バッファーが重複している別の文字列にコピーします。
CSimpleStringT::Empty	文字列の長さを強制的に 0 に設定します。
CSimpleStringT::FreeExtra	文字列オブジェクトによって以前に割り当てられた余分なメモリを解放します。
CSimpleStringT::GetAllocLength	CSimpleStringT オブジェクトの割り当て済みの長さを取得します。
CSimpleStringT::GetAt	特定の位置にある文字を返します。
CSimpleStringT::GetBuffer	CSimpleStringT 内の文字へのポインターを返します。
CSimpleStringT::GetBufferSetLength	CSimpleStringT 内の文字へのポインターを返し、指定した長さに切り捨てます。
CSimpleStringT::GetLength	CSimpleStringT オブジェクト内の文字数を返します。
CSimpleStringT::GetManager	CSimpleStringT オブジェクトのメモリ マネージャーを取得します。
CSimpleStringT::GetString	文字列を取得します。
CSimpleStringT::IsEmpty	CSimpleStringT オブジェクトに文字が含まれていないかどうかをテストします。
CSimpleStringT::LockBuffer	参照カウントを無効にし、バッファー内の文字列を保護します。
CSimpleStringT::Preallocate	文字バッファーに特定の量のメモリを割り当てます。
CSimpleStringT::ReleaseBuffer	GetBuffer によって返されるバッファーの制御を解放します。
CSimpleStringT::ReleaseBufferSetLength	GetBuffer によって返されるバッファーの制御を解放します。
CSimpleStringT::SetAt	特定の位置の文字を設定します。
CSimpleStringT::SetManager	CSimpleStringT オブジェクトのメモリ マネージャーを設定します。
CSimpleStringT::SetString	CSimpleStringT オブジェクトの文字列を設定します。
CSimpleStringT::StringLength	指定した文字列内の文字数を返します。
CSimpleStringT::Truncate	文字列を、指定した長さに切り捨てます。
CSimpleStringT::UnlockBuffer	参照カウントを有効にし、バッファー内の文字列を解放します。

パブリック演算子

名前	説明
CSimpleStringT::operator PCXSTR	C スタイルの文字列として CSimpleStringT オブジェクトに格納されている文字に直接アクセスします。
CSimpleStringT::operator[]	指定した位置にある文字を返します (GetAt の代替演算子)。
CSimpleStringT::operator +=	既存の文字列の末尾に新しい文字列を連結します。
CSimpleStringT::operator =	新しい値を CSimpleStringT オブジェクトに代入します。

解説

CSimpleStringT は、Visual C++ でサポートされるさまざまな文字列クラスの基本クラスです。 これにより、文字列オブジェクトのメモリ管理と基本的なバッファー操作に対する最小限のサポートが提供されます。 より高度な文字列オブジェクトについては、「CStringT Class」を参照してください。

要件

ヘッダー: atlsimpstr.h

CSimpleStringT::Append

CSimpleStringT オブジェクトを既存の CSimpleStringT オブジェクトに追加します。

構文

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

パラメーター

strSrc
追加する CSimpleStringT オブジェクト。

pszSrc
追加する文字が含まれている文字列へのポインター。

nLength
追加する文字数。

解説

既存の CSimpleStringT オブジェクトを別の CSimpleStringT オブジェクトに追加するには、このメソッドを呼び出します。

例

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

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

CSimpleStringT::AppendChar

文字を既存の CSimpleStringT オブジェクトに追加します。

構文

void AppendChar(XCHAR ch);

パラメーター

ch
追加する文字。

解説

指定した文字を既存の CSimpleStringT オブジェクトの末尾に追加するには、この関数を呼び出します。

CSimpleStringT::CopyChars

1 つ以上の文字を 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

1 つ以上の文字を CSimpleStringT オブジェクトにコピーします。

構文

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

パラメーター

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

pchSrc
コピーする文字が含まれている文字列へのポインター。

nChars
コピーする pchSrc 文字の数。

解説

pchSrc 文字列から pchDest 文字列に文字をコピーするには、このメソッドを呼び出します。 CopyChars とは異なり、CopyCharsOverlapped では、重複する可能性のある文字バッファーからコピーする安全な方法が提供されます。

例

CSimpleStringT::CopyChars の例、または CSimpleStringT::SetString のソース コード (atlsimpstr.h 内にあります) を参照してください。

CSimpleStringT::CSimpleStringT

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

構文

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

パラメーター

strSrc
この CSimpleStringT オブジェクトにコピーする既存の CSimpleStringT オブジェクト。

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

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

nLength
pch 内の文字数。

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

解説

新しい CSimpleStringT オブジェクトを構築します。 コンストラクターによって入力データが割り当てられた新しいストレージにコピーされるので、メモリ例外が発生する可能性があります。

例

次の例では、ATL typedef CSimpleStringを使用したCSimpleStringT::CSimpleStringTの使用を示します。 CSimpleString は、広く使用されているクラス テンプレート CSimpleStringT の特殊化です。

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

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

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

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

CSimpleStringT::Empty

必要に応じて、この CSimpleStringT オブジェクトを空の文字列にし、メモリを解放します。

構文

void Empty() throw();

解説

詳細については、文字列: CString 例外のクリーンアップに関するページを参照してください。

例

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

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

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

CSimpleStringT::FreeExtra

文字列によって以前に割り当てられたが、不要になった余分なメモリを解放します。

構文

void FreeExtra();

解説

これにより、文字列オブジェクトによって消費されるメモリのオーバーヘッドが軽減されます。 このメソッドでは、GetLength によって返される正確な長さにバッファーを再割り当てします。

例

CAtlString basestr;
IAtlStringMgr* pMgr;

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

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

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

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

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

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

CSimpleStringT::GetAllocLength

CSimpleStringT オブジェクトの割り当て済みの長さを取得します。

構文

int GetAllocLength() const throw();

戻り値

このオブジェクトに割り当てられた文字数。

解説

この CSimpleStringT オブジェクトに割り当てられた文字数を確認するには、このメソッドを呼び出します。 この関数を呼び出す例については、FreeExtra に関するページを参照してください。

CSimpleStringT::GetAt

CSimpleStringT オブジェクトから 1 つの文字を返します。

構文

XCHAR GetAt(int iChar) const;

パラメーター

iChar
CSimpleStringT オブジェクト内の文字の 0 から始まるインデックス。 iChar パラメーターは、0 以上、かつ GetLength によって返される値未満にする必要があります。 それ以外の場合は、GetAt によって例外が生成されます。

戻り値

文字列内の指定した位置に文字が含まれている XCHAR。

解説

iChar によって指定された 1 つの文字を返すには、このメソッドを呼び出します。 オーバーロードされた添字 ([]) 演算子は、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 により、現在のバッファーが破棄されて、要求されたサイズのバッファーに置き換えられ、オブジェクト参照カウントが 0 にリセットされます。 このバッファーで以前に LockBuffer を呼び出していた場合、バッファー ロックが失われます。

戻り値

オブジェクトの (null 終端) 文字バッファーへの PXSTR ポインター。

解説

CSimpleStringT オブジェクトのバッファーの内容を返すには、このメソッドを呼び出します。 返される PXSTR は定数ではないため、CSimpleStringT の内容を直接変更できます。

GetBufferによって返されるポインターを使用して文字列の内容を変更する場合は、他のCSimpleStringTメソッドを使用する前に、ReleaseBufferを呼び出してCSimpleStringTの内部状態を更新する必要があります。

GetBuffer によって返されるアドレスは、ReleaseBuffer を呼び出した後に無効になる可能性があります。これは、追加の CSimpleStringT の操作によって CSimpleStringT バッファーが再割り当てされる場合があるためです。 CSimpleStringT の長さを変更しない場合、バッファーは再割り当てされません。

バッファー メモリは、CSimpleStringT オブジェクトが破棄されると自動的に解放されます。

文字列の長さを自分で追跡する場合は、終端の null 文字を追加しないでください。 ただし、ReleaseBuffer を使用してバッファーを解放する場合は、最終的な文字列長を指定する必要があります。 終端の null 文字を追加する場合は、長さとして-1 (既定値) を渡す必要があります。 次に、ReleaseBuffer によってバッファーの長さが決定されます。

メモリが不足しているため GetBuffer 要求を満たせない場合、このメソッドは CMemoryException* をスローします。

例

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

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

CSimpleStringT::GetBufferSetLength

CSimpleStringT オブジェクトの内部文字バッファーへのポインターを返します。必要に応じて、nLength で指定した長さと正確に一致するように、長さを切り捨てるか延長します。

構文

PXSTR GetBufferSetLength(int nLength);

パラメーター

nLength
CSimpleStringT 文字バッファーの正確なサイズ (文字数)。

戻り値

オブジェクトの (null 終端) 文字バッファーへの PXSTR ポインター。

解説

CSimpleStringT オブジェクトの内部バッファーの指定の長さを取得するには、このメソッドを呼び出します。 返される PXSTR ポインターは const ではないため、CSimpleStringT の内容を直接変更できます。

GetBufferSetLength によって返されるポインターを使用して文字列の内容を変更する場合は、他の CSimpleStringT メソッドを使用する前に、ReleaseBuffer を呼び出して CSimpleStringT の内部状態を更新します。

GetBufferSetLength によって返されるアドレスは、ReleaseBuffer を呼び出した後に無効になる可能性があります。これは、追加の CSimpleStringT の操作によって CSimpleStringT バッファーが再割り当てされる場合があるためです。 CSimpleStringT の長さを変更しない場合、バッファーは再割り当てされません。

バッファー メモリは、CSimpleStringT オブジェクトが破棄されると自動的に解放されます。

文字列の長さを自分で追跡する場合は、終端の null 文字を追加しないでください。 ReleaseBuffer を使用してバッファーを解放する場合は、最終的な文字列長を指定する必要があります。 ReleaseBuffer を呼び出すときに終端の null 文字を追加する場合は、長さとして -1 (既定値) を ReleaseBuffer に渡します。次に、ReleaseBuffer によってバッファーに対して strlen が実行され、その長さが決定されます。

参照カウントの詳細については、次の記事を参照してください。

• Windows SDK での参照カウントによるオブジェクトの有効期間の管理
• Windows SDK での参照カウントの実装
• Windows SDK での参照カウントの管理ルール

例

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

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

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

CSimpleStringT::GetLength

CSimpleStringT オブジェクト内の文字数を返します。

構文

int GetLength() const throw();

戻り値

文字列内の文字数。

解説

オブジェクト内の文字数を返すには、このメソッドを呼び出します。 カウントには null 終端文字は含まれません。

マルチバイト文字セット (MBCS) の場合、GetLength によって各 8 ビット文字がカウントされます。つまり、1 つのマルチバイト文字の先頭のバイトと末尾のバイトは 2 バイトとしてカウントされます。 この関数を呼び出す例については、FreeExtra に関するページを参照してください。

CSimpleStringT::GetManager

CSimpleStringT オブジェクトのメモリ マネージャーを取得します。

構文

IAtlStringMgr* GetManager() const throw();

戻り値

CSimpleStringT オブジェクトのメモリ マネージャーへのポインター。

解説

CSimpleStringT オブジェクトによって使用されるメモリ マネージャーを取得するには、このメソッドを呼び出します。 メモリ マネージャーと文字列オブジェクトの詳細については、メモリ管理と CStringT に関するページを参照してください。

CSimpleStringT::GetString

文字列を取得します。

構文

PCXSTR GetString() const throw();

戻り値

null 終端文字列へのポインター。

解説

CSimpleStringT オブジェクトに関連付けられた文字列を取得するには、このメソッドを呼び出します。

Note

返される 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 の場合、バッファー内の文字列は "ロック" 状態であると見なされます。 ロック状態の間、文字列は次の 2 つの方法で保護されます。

• ロックされた文字列に他の文字列が割り当てられている場合でも、その文字列から、ロックされた文字列内のデータを参照することはできません。

• ロックされた文字列に別の文字列がコピーされた場合でも、ロックされた文字列によってその文字列が参照されることはありません。

バッファー内の文字列をロックすることで、バッファーでその文字列が排他的に保持され続けます。

LockBuffer の使用が終了したら、UnlockBuffer を呼び出して、参照カウントを 1 にリセットします。

Note

ロックされたバッファーで GetBuffer を呼び出し、GetBuffer パラメーター nMinBufferLength を現在のバッファーの長さよりも大きい値に設定した場合、バッファー ロックが失われます。 GetBuffer へのこのような呼び出しを行うと、現在のバッファーが破棄され、要求されたサイズのバッファーに置き換えられて、参照カウントが 0 にリセットされます。

参照カウントの詳細については、次の記事を参照してください。

• Windows SDK での参照カウントによるオブジェクトの有効期間の管理

• Windows SDK での参照カウントの実装

• Windows SDK での参照カウントの管理ルール

例

次の例は、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[]

文字配列の 1 つの文字にアクセスするには、この関数を呼び出します。

構文

XCHAR operator[](int iChar) const;

パラメーター

iChar
文字列内の文字の 0 から始るインデックス。

解説

オーバーロードされた添字 ([]) 演算子は、iChar 内の 0 から始るインデックスで指定された 1 つの文字を返します。 これは、GetAt メンバー関数に代わる便利な演算子です。

Note

添字 ([]) 演算子を使用すると、CSimpleStringT 内の文字の値を取得できますが、それを使用して CSimpleStringT 内の文字の値を変更することはできません。

例

次の例は、CSimpleStringT::operator [] の使い方を示しています。

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

CSimpleStringT::operator []

文字配列の 1 つの文字にアクセスするには、この関数を呼び出します。

構文

XCHAR operator[](int iChar) const;

パラメーター

iChar
文字列内の文字の 0 から始るインデックス。

解説

オーバーロードされた添字 ([]) 演算子は、iChar 内の 0 から始るインデックスで指定された 1 つの文字を返します。 これは、GetAt メンバー関数に代わる便利な演算子です。

Note

添字 ([]) 演算子を使用すると、CSimpleStringT 内の文字の値を取得できますが、それを使用して CSimpleStringT 内の文字の値を変更することはできません。

CSimpleStringT::operator +=

新しい文字列または文字を既存の文字列の末尾に結合します。

構文

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

パラメーター

pszSrc
null 終端文字列へのポインター。

strSrc
既存の CSimpleStringT オブジェクトへのポインター。

ch
追加される文字。

解説

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

例

次の例は、CSimpleStringT::operator += の使い方を示しています。

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

CSimpleStringT::operator =

新しい値を CSimpleStringT オブジェクトに代入します。

構文

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

パラメーター

pszSrc
null 終端文字列へのポインター。

strSrc
既存の CSimpleStringT オブジェクトへのポインター。

解説

代入先の文字列 (左側) が、新しいデータを格納するのに既に十分な大きさである場合、新しいメモリの割り当ては行われません。 代入演算子を使用するたびに、メモリの例外が発生する可能性があります。これは、多くの場合、結果として得られる CSimpleStringT オブジェクトを保持するために新しいストレージが割り当てられるためです。

例

次の例は、CSimpleStringT::operator = の使い方を示しています。

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

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

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

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

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

CSimpleStringT::operator PCXSTR

C スタイルの文字列として CSimpleStringT オブジェクトに格納されている文字に直接アクセスします。

構文

operator PCXSTR() const throw();

戻り値

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

解説

文字はコピーされません。ポインターだけが返されます。 この演算子には注意してください。 文字ポインターを取得した後に CString オブジェクトを変更すると、メモリの再割り当てが行われてポインターが無効になる可能性があります。

例

次の例は、CSimpleStringT::operator PCXSTR の使い方を示しています。

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

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

wcscpy_s(sz, strSports);

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

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

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

swprintf_s(sz, 1024, strSports);

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

wcout << strSports;

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

wcout << (PCWSTR)strSports;

CSimpleStringT::PCXSTR

定数文字列へのポインター。

構文

typedef ChTraitsBase< BaseType >::PCXSTR PCXSTR;

CSimpleStringT::Preallocate

CSimpleStringT オブジェクトの特定の量のバイトを割り当てます。

構文

void Preallocate( int nLength);

パラメーター

nLength
CSimpleStringT 文字バッファーの正確なサイズ (文字数)。

解説

CSimpleStringT オブジェクトの特定のバッファー サイズを割り当てるには、このメソッドを呼び出します。

CSimpleStringT では、文字バッファーにスペースを割り当てできない場合、STATUS_NO_MEMORY 例外が生成されます。 既定では、メモリの割り当ては WIN32 API 関数 HeapAlloc または HeapReAlloc によって実行されます。

例

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

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

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

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

Allocated length: 0
Allocated length: 103

CSimpleStringT::PXSTR

文字列へのポインター。

構文

typedef ChTraitsBase< BaseType >::PXSTR PXSTR;

CSimpleStringT::ReleaseBuffer

GetBuffer によって割り当てられるバッファーの制御を解放します。

構文

void ReleaseBuffer(int nNewLength = -1);

パラメーター

nNewLength
文字列の新しい長さ (文字数)。null 終端文字はカウントされません。 文字列が null で終了した場合、既定値 -1 により、CSimpleStringT サイズが文字列の現在の長さに設定されます。

解説

文字列オブジェクトのバッファーを再割り当てまたは解放するには、このメソッドを呼び出します。 バッファー内の文字列が null で終了したことがわかっている場合は、nNewLength 引数を省略できます。 文字列が null で終了していない場合は、nNewLength を使用してその長さを指定します。 GetBuffer によって返されるアドレスは、ReleaseBuffer またはその他の CSimpleStringT 操作の呼び出し後に無効になります。

例

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

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

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

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

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

// Length still 3

CSimpleStringT::ReleaseBufferSetLength

GetBuffer によって割り当てられるバッファーの制御を解放します。

構文

void ReleaseBufferSetLength(int nNewLength);

パラメーター

nNewLength
解放される文字列の長さ。

解説

この関数は機能上 ReleaseBuffer に似ていますが、文字列オブジェクトの有効な長さを渡す必要がある点が異なります。

CSimpleStringT::SetAt

CSimpleStringT オブジェクトからの 1 つの文字を設定します。

構文

void SetAt(int iChar, XCHAR ch);

パラメーター

iChar
CSimpleStringT オブジェクト内の文字の 0 から始まるインデックス。 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 エラーがスローされます。

1 パラメーター バージョンの SetString では、pszSrc が null 終端文字列を指すことが想定されています。

2 パラメーター バージョンの SetString では、pszSrc が null 終端文字列であることが想定されています。 最初に null 終端文字が検出されない限り、nLength は文字列の長さとして使用されます。

2 パラメーター バージョンの 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
文字列の新しい長さ。

解説

文字列の内容を新しい長さに切り捨てるには、このメソッドを呼び出します。

Note

これは、割り当てられたバッファーの長さには影響を与えません。 現在のバッファーを増減するには、FreeExtra と Preallocate に関するページを参照してください。

例

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

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

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

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

CSimpleStringT::UnlockBuffer

CSimpleStringT オブジェクトのバッファーのロックを解除します。

構文

void UnlockBuffer() throw();

解説

文字列の参照カウントを 1 にリセットするには、このメソッドを呼び出します。

CSimpleStringT デストラクターでは、デストラクターの呼び出し時にバッファーがロックされていないことを確認するために、UnlockBuffer が自動的に呼び出されます。 このメソッドの例については、LockBuffer に関するページを参照してください。

CSimpleStringT::~CSimpleStringT

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

構文

~CSimpleStringT() throw();

解説

CSimpleStringT オブジェクトを破棄するには、このメソッドを呼び出します。

関連項目

階層図
ATL/MFC 共有クラス