`CList` クラス

[アーティクル]
07/05/2024

オブジェクト (重複あり) を順に並べたリストをサポートします。このリストには、シーケンシャルアクセスまたは値指定によるアクセスを行うことができます。

構文

template<class TYPE, class ARG_TYPE = const TYPE&>
class CList : public CObject

メンバー

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

名前	説明
`CList::CList`	空の順序付きリストを構築します。

パブリックメソッド

名前	説明
`CList::AddHead`	要素 (または別のリスト内のすべての要素) をリストの先頭に追加します (新しい先頭を作成します)。
`CList::AddTail`	リストの末尾に要素 (または別のリストのすべての要素) を追加します (新しい末尾を作成します)。
`CList::Find`	ポインター値で指定された要素の位置を取得します。
`CList::FindIndex`	0 から始まるインデックスで指定された要素の位置を取得します。
`CList::GetAt`	指定した位置にある要素を取得します。
`CList::GetCount`	このリスト内の要素の数を返します。
`CList::GetHead`	リストのヘッド要素を返します (空にすることはできません)。
`CList::GetHeadPosition`	リストのヘッド要素の位置を返します。
`CList::GetNext`	次に反復処理の対象となる要素が取得されます。
`CList::GetPrev`	反復する前の要素を取得します。
`CList::GetSize`	このリスト内の要素の数を返します。
`CList::GetTail`	リストの末尾要素を返します (空にすることはできません)。
`CList::GetTailPosition`	リストの末尾要素の位置を返します。
`CList::InsertAfter`	指定した位置の後に新しい要素を挿入します。
`CList::InsertBefore`	指定した位置の前に新しい要素を挿入します。
`CList::IsEmpty`	空のリスト条件 (要素なし) をテストします。
`CList::RemoveAll`	このリストからすべての要素を削除します。
`CList::RemoveAt`	位置で指定された要素をこのリストから削除します。
`CList::RemoveHead`	リストの先頭から要素を削除します。
`CList::RemoveTail`	リストの末尾から要素を削除します。
`CList::SetAt`	特定の位置に要素を設定します。

パラメーター

TYPE
リストに格納されているオブジェクトの種類。

ARG_TYPE
リストに格納されているオブジェクトを参照するために使用される型。参照を指定できます。

解説

CList リストは、二重にリンクされたリストのように動作します。

POSITION型の変数は、リストのキーです。 POSITION変数を反復子として使用して、リストを順番に走査したり、場所を保持するブックマークとして使用したりできます。ただし、位置はインデックスと同じではありません。

要素の挿入は、リストヘッド、末尾、既知の POSITIONで非常に高速です。要素を値またはインデックスで検索するには、シーケンシャル検索が必要です。リストが長い場合、この検索は遅くなる可能性があります。

リスト内の個々の要素のダンプが必要な場合は、ダンプコンテキストの深さを 1 以上に設定する必要があります。

このクラスの特定のメンバー関数は、 CList クラスのほとんどの用途に合わせてカスタマイズする必要があるグローバルヘルパー関数を呼び出します。「マクロとグローバル」セクションの「 Collection クラスヘルパーを参照してください。

CListの使用方法の詳細については、Collectionsに関する記事を参照してください。

例

// CList is a template class that takes two template arguments.
// The first argument is type stored internally by the list, the
// second argument is the type used in the arguments for the
// CList methods.

// This code defines a list of ints.
CList<int, int> myIntList;

// This code defines a list of CStrings
CList<CString, CString &> myStringList;

// This code defines a list of MYTYPEs,
// NOTE: MYTYPE could be any struct, class or type definition
CList<MYTYPE, MYTYPE &> myTypeList;

継承階層

CObject

CList

要件

ヘッダー: afxtempl.h

`CList::AddHead`

このリストの先頭に新しい要素または要素のリストを追加します。

POSITION AddHead(ARG_TYPE newElement);
void AddHead(CList* pNewList);

パラメーター

ARG_TYPE
一覧の要素の型を指定するテンプレートパラメーター (参照を使用できます)。

newElement
新しい要素。

pNewList
別の CList リストへのポインター。 pNewList内の要素がこの一覧に追加されます。

戻り値

最初のバージョンは、新しく挿入された要素の POSITION 値を返します。

解説

操作の前にリストを空にすることができます。

例

// Declarations of the variables used in the example
CList<CString, CString &> myList;
CList<CString, CString &> myList2;

// There are two versions of CList::AddHead: one adds a single
// element to the front of the list, the second adds another list
// to the front.

// This adds the string "ABC" to the front of myList.
// myList is a list of CStrings (ie defined as CList<CString,CString&>).
myList.AddHead(CString(_T("ABC")));

// This adds the elements of myList2 to the front of myList.
myList.AddHead(&myList2);

`CList::AddTail`

このリストの末尾に新しい要素または要素のリストを追加します。

POSITION AddTail(ARG_TYPE newElement);
void AddTail(CList* pNewList);

パラメーター

ARG_TYPE
一覧の要素の型を指定するテンプレートパラメーター (参照を使用できます)。

newElement
この一覧に追加する要素。

pNewList
別の CList リストへのポインター。 pNewList内の要素がこの一覧に追加されます。

戻り値

最初のバージョンは、新しく挿入された要素の POSITION 値を返します。

解説

操作の前にリストを空にすることができます。

例

// Define myList and myList2.
CList<CString, CString &> myList;
CList<CString, CString &> myList2;

// Add elements to the end of myList and myList2.
myList.AddTail(CString(_T("A")));
myList.AddTail(CString(_T("B")));
myList2.AddTail(CString(_T("C")));
myList2.AddTail(CString(_T("D")));

// There are two versions of CList::AddTail: one adds a single
// element to the end of the list, the second adds another list
// to the end.

// This adds the string "ABC" to the end of myList.
// myList is a list of CStrings (ie defined as CList<CString,CString&>).
myList.AddTail(CString(_T("ABC")));
ASSERT(CString(_T("ABC")) == myList.GetTail());

// This adds the elements of myList2 to the end of myList.
myList.AddTail(&myList2);

`CList::CList`

空の順序付きリストを構築します。

CList(INT_PTR nBlockSize = 10);

パラメーター

nBlockSize
リストを拡張するためのメモリ割り当ての粒度。

解説

一覧が大きくなると、メモリは nBlockSize エントリの単位で割り当てられます。

例

// This code defines myList as a list of strings
// such that memory gets allocated in chunks of
// 16 strings.
CList<CString, CString &> myList(16);

// This code defines myList2 as a list of ints
// such that memory gets allocated in chunks of
// 128 ints.
CList<int, int> myList2(128);

`CList::Find`

リストを順番に検索して、指定した searchValueに一致する最初の要素を検索します。

POSITION Find(
    ARG_TYPE searchValue,
    POSITION startAfter = NULL) const;

パラメーター

ARG_TYPE
一覧の要素の型を指定するテンプレートパラメーター (参照を使用できます)。

searchValue
リスト内で見つかる値。

startAfter
検索の開始位置。値が指定されていない場合、検索は先頭の要素から検索が開始されます。

戻り値

反復処理またはオブジェクトポインターの取得に使用できる POSITION 値。オブジェクトが見つからない場合に NULL 。

例

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddHead(CString(_T("XYZ")));
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Find a specific element.
POSITION pos = myList.Find(CString(_T("XYZ")));
ASSERT(CString(_T("XYZ")) == myList.GetAt(pos));

`CList::FindIndex`

nIndexの値をリストのインデックスとして使用します。

POSITION FindIndex(INT_PTR nIndex) const;

パラメーター

nIndex
検索するリスト要素の 0 から始まるインデックス。

戻り値

反復処理またはオブジェクトポインターの取得に使用できるPOSITION値。nIndexが負の値または大きすぎる場合にNULL。

解説

リストの先頭からシーケンシャルスキャンを開始し、 n 番目の要素で停止。

例

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Verify the first element (index 0).
ASSERT(CString(_T("XYZ")) == myList.GetAt(myList.FindIndex(0)));

// Verify the third element (index 2).
ASSERT(CString(_T("123")) == myList.GetAt(myList.FindIndex(2)));

`CList::GetAt`

指定した位置にある list 要素を取得します。

TYPE& GetAt(POSITION position);
const TYPE& GetAt(POSITION position) const;

パラメーター

TYPE
リスト内のオブジェクトの種類を指定するテンプレートパラメーター。

position
取得する要素のリスト内の位置。

戻り値

GetHeadの戻り値の説明を参照してください。

解説

GetAt は、特定の位置に関連付けられている要素 (または要素への参照) を返します。インデックスと同じではなく、 POSITION 値を自分で操作することはできません。 POSITION型の変数は、リストのキーです。

POSITION値がリスト内の有効な位置を表していることを確認する必要があります。無効な場合は、Microsoft Foundation クラスライブラリのデバッグバージョンがアサートされます。

例

CList::GetHeadPosition の例を参照してください。

`CList::GetCount`

このリスト内の要素の数を取得します。

INT_PTR GetCount() const;

戻り値

要素数を含む整数値。

解説

このメソッドを呼び出すと、 CList::GetSize メソッドと同じ結果が生成されます。

例

CList::RemoveHead の例を参照してください。

`CList::GetHead`

このリストのヘッド要素 (またはヘッド要素への参照) を取得します。

const TYPE& GetHead() const;

TYPE& GetHead();

パラメーター

TYPE
リスト内のオブジェクトの種類を指定するテンプレートパラメーター。

戻り値

リストが const の場合、GetHead は、リストの先頭にある要素のコピーを返します。これにより、関数は代入ステートメントの右側でのみ使用でき、リストが変更されないように保護されます。

リストが const ではない場合、GetHead は、リストの先頭にある要素への参照を返します。これにより、代入ステートメントの両側で関数を使用できるため、リストエントリを変更できます。

解説

GetHeadを呼び出す前に、リストが空でないことを確認する必要があります。リストが空の場合、Microsoft Foundation クラスライブラリのデバッグバージョンがアサートされます。 IsEmptyを使用して、リストに要素が含まれていることを確認します。

例

// Define myList.
CList<CString, CString &> myList;

// Add an element to the front of the list.
myList.AddHead(CString(_T("ABC")));

// Verify the element was added to the front of the list.
ASSERT(CString(_T("ABC")) == myList.GetHead());

`CList::GetHeadPosition`

このリストのヘッド要素の位置を取得します。

POSITION GetHeadPosition() const;

戻り値

反復処理またはオブジェクトポインターの取得に使用できる POSITION 値。リストが空の場合に NULL 。

例

// Define myList.
CList<CString, CString &> myList;

// Add an element to the front of the list.
myList.AddHead(CString(_T("ABC")));

// Verify the element at the head position
// is the one added.
POSITION pos = myList.GetHeadPosition();
ASSERT(CString(_T("ABC")) == myList.GetAt(pos));

`CList::GetNext`

rPositionで識別されるリスト要素を取得し、rPositionリスト内の次のエントリのPOSITION値に設定します。

TYPE& GetNext(POSITION& rPosition);
const TYPE& GetNext(POSITION& rPosition) const;

パラメーター

TYPE
リスト内の要素の型を指定するテンプレートパラメーター。

rPosition
前のGetNext、GetHeadPosition、またはその他のメンバー関数呼び出しによって返されるPOSITION値への参照。

戻り値

リストが const の場合、GetNext はリスト内の要素のコピーを返します。これにより、関数は代入ステートメントの右側でのみ使用でき、リストが変更されないように保護されます。

リストが constでない場合、GetNext はリスト内の要素への参照を返します。これにより、代入ステートメントの両側で関数を使用できるため、リストエントリを変更できます。

解説

GetHeadPositionまたはFindの呼び出しで初期位置を確立する場合は、前方反復ループでGetNextを使用できます。

取得した要素がリストの最後の要素である場合、 rPosition の新しい値は NULL に設定されます。

例

// Define myList.
// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Dump the list elements to the debug window.
POSITION pos = myList.GetHeadPosition();
for (int i = 0; i < myList.GetCount(); i++)
{
   TRACE(_T("%s\r\n"), (LPCTSTR)myList.GetNext(pos));
}

`CList::GetPrev`

rPositionで識別されるリスト要素を取得し、rPositionリスト内の前のエントリのPOSITION値に設定します。

TYPE& GetPrev(POSITION& rPosition);
const TYPE& GetPrev(POSITION& rPosition) const;

パラメーター

TYPE
リスト内の要素の型を指定するテンプレートパラメーター。

rPosition
前のGetPrevまたはその他のメンバー関数呼び出しによって返されるPOSITION値への参照。

戻り値

リストが const の場合、GetPrev は、リストの先頭にある要素のコピーを返します。これにより、関数は代入ステートメントの右側でのみ使用でき、リストが変更されないように保護されます。

リストが constでない場合、GetPrev はリスト内の要素への参照を返します。これにより、代入ステートメントの両側で関数を使用できるため、リストエントリを変更できます。

解説

GetTailPositionまたはFindの呼び出しで初期位置を確立する場合は、逆反復ループでGetPrevを使用できます。

取得した要素がリストの最初の要素である場合、 rPosition の新しい値は NULLに設定されます。

例

// Define myList.
CList<CString,CString&> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Dump the list elements to the debug window,
// in reverse order.
POSITION pos = myList.GetTailPosition();
for (int i = 0; i < myList.GetCount(); i++)
{
   TRACE(_T("%s\r\n"), (LPCTSTR)myList.GetPrev(pos));
}

`CList::GetSize`

リスト要素の数を返します。

INT_PTR GetSize() const;

戻り値

リスト内の項目数。

解説

リスト内の要素の数を取得するには、このメソッドを呼び出します。このメソッドを呼び出すと、 CList::GetCount メソッドと同じ結果が生成されます。

例

// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Remove the head element and verify the list.
// NOTE: once the head is removed, the number of
// elements in the list will be one.
CString strHead = myList.RemoveHead();
ASSERT((CString(_T("123")) == strHead) && (myList.GetSize() == 1) &&
       (CString(_T("ABC")) == myList.GetHead()));

`CList::GetTail`

このリストの末尾要素を表す CObject ポインターを取得します。

TYPE& GetTail();
const TYPE& GetTail() const;

パラメーター

TYPE
リスト内の要素の型を指定するテンプレートパラメーター。

戻り値

GetHeadの戻り値の説明を参照してください。

解説

GetTailを呼び出す前に、リストが空でないことを確認する必要があります。リストが空の場合、Microsoft Foundation クラスライブラリのデバッグバージョンがアサートされます。 IsEmptyを使用して、リストに要素が含まれていることを確認します。

例

// Define myList.
CList<CString, CString &> myList;

// Add an element to the end of the list.
myList.AddTail(CString(_T("ABC")));

// Verify the element was added to the end of the list.
ASSERT(CString(_T("ABC")) == myList.GetTail());

`CList::GetTailPosition`

このリストの tail 要素の位置を取得します。リストが空の場合に NULL します。

POSITION GetTailPosition() const;

戻り値

反復処理またはオブジェクトポインターの取得に使用できる POSITION 値。リストが空の場合に NULL 。

例

// Define myList.
CList<CString,CString&> myList;

// Add an element to the end of the list.
myList.AddTail(CString(_T("ABC")));

// Verify the element at the end position
// is the one added.
POSITION pos = myList.GetTailPosition();
ASSERT(CString(_T("ABC")) == myList.GetAt(pos));

`CList::InsertAfter`

指定した位置の要素の後に、このリストに要素を追加します。

POSITION InsertAfter(POSITION position, ARG_TYPE newElement);

パラメーター

position
前の GetNext、 GetPrev、またはメンバー関数呼び出しによって返 Find POSITION 値。

ARG_TYPE
list 要素の型を指定するテンプレートパラメーター。

newElement
この一覧に追加する要素。

戻り値

反復処理またはリスト要素の取得に使用できる POSITION 値。

例

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
POSITION pos = myList.AddHead(CString(_T("XYZ")));
pos = myList.InsertAfter(pos, CString(_T("ABC")));
pos = myList.InsertAfter(pos, CString(_T("123")));

// Verify the tail element is what's expected.
ASSERT(CString(_T("123")) == myList.GetTail());

`CList::InsertBefore`

一覧の指定した位置にある要素の前に要素を追加します。

POSITION InsertBefore(POSITION position, ARG_TYPE newElement);

パラメーター

position
前のGetNext、GetPrev、またはメンバー関数呼び出しによって返されるPOSITION値Find。

ARG_TYPE
一覧の要素の型を指定するテンプレートパラメーター (参照を使用できます)。

newElement
この一覧に追加する要素。

戻り値

反復処理またはリスト要素の取得に使用できる POSITION 値。

解説

positionがNULL場合、要素はリストの先頭に挿入されます。

例

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
POSITION pos = myList.AddHead(CString(_T("XYZ")));
pos = myList.InsertBefore(pos, CString(_T("ABC")));
pos = myList.InsertBefore(pos, CString(_T("123")));

// Verify the head element is what's expected.
ASSERT(CString(_T("123")) == myList.GetHead());

`CList::IsEmpty`

このリストに要素が含まれているかどうかを示します。

BOOL IsEmpty() const;

戻り値

このリストが空の場合は 0 以外。それ以外の場合は 0。

例

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove the head element until the list is empty.
CString str;
while (!myList.IsEmpty())
{
   str = myList.RemoveHead();
   TRACE(_T("%s\r\n"), (LPCTSTR)str);
}

`CList::RemoveAll`

このリストからすべての要素を削除し、関連付けられているメモリを解放します。

void RemoveAll();

解説

リストが既に空の場合、エラーは生成されません。

例

// Define myList.
CList<CString, CString&> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove all of the elements in the list.
myList.RemoveAll();

// Verify the list is empty.
ASSERT(myList.IsEmpty());

`CList::RemoveAt`

指定した要素をこのリストから削除します。

void RemoveAt(POSITION position);

パラメーター

position
リストから削除する要素の位置。

解説

例

// Define myList.
CList<CString, CString&> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove CString("ABC") from the list.
myList.RemoveAt(myList.FindIndex(1));

// Verify CString("ABC") is not in the list.
ASSERT(myList.Find(CString(_T("ABC"))) == NULL);

`CList::RemoveHead`

リストの先頭から要素を削除し、その要素へのポインターを返します。

TYPE RemoveHead();

パラメーター

TYPE
リスト内の要素の型を指定するテンプレートパラメーター。

戻り値

以前にリストの先頭にある要素。

解説

RemoveHeadを呼び出す前に、リストが空でないことを確認する必要があります。リストが空の場合、Microsoft Foundation クラスライブラリのデバッグバージョンがアサートされます。 IsEmptyを使用して、リストに要素が含まれていることを確認します。

例

// Define myList.
CList<CString, CString&> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Remove the head element and verify the list.
// NOTE: once the head is removed, the number of
// elements in the list will be one.
CString strHead = myList.RemoveHead();
ASSERT((CString(_T("123")) == strHead) && (myList.GetCount() == 1) &&
(CString(_T("ABC")) == myList.GetHead()));

`CList::RemoveTail`

リストの末尾から要素を削除し、その要素へのポインターを返します。

TYPE RemoveTail();

パラメーター

TYPE
リスト内の要素の型を指定するテンプレートパラメーター。

戻り値

リストの末尾にあった要素。

解説

RemoveTailを呼び出す前に、リストが空でないことを確認する必要があります。リストが空の場合、Microsoft Foundation クラスライブラリのデバッグバージョンがアサートされます。 IsEmptyを使用して、リストに要素が含まれていることを確認します。

例

// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove the tail element and verify the list.
// NOTE: once the tail is removed, the number of
// elements in the list will be one.
CString strTail = myList.RemoveTail();
ASSERT((CString(_T("123")) == strTail) && (myList.GetCount() == 1) &&
       (CString(_T("ABC")) == myList.GetTail()));

`CList::SetAt`

POSITION型の変数は、リストのキーです。

void SetAt(POSITION pos, ARG_TYPE newElement);

パラメーター

pos
設定する要素の POSITION 。

ARG_TYPE
一覧の要素の型を指定するテンプレートパラメーター (参照を使用できます)。

newElement
リストに追加する要素。

解説

インデックスと同じではなく、 POSITION 値を自分で操作することはできません。 SetAt は、リスト内の指定した位置に要素を書き込みます。

例

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Replace CString("ABC") with CString("CBA")
POSITION pos = myList.Find(CString(_T("ABC")));
myList.SetAt(pos, CString(_T("CBA")));

// Verify CString("ABC") is not in the list.
ASSERT(myList.Find(CString(_T("ABC"))) == NULL);

次の方法で共有

CList クラス

構文

メンバー

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

パブリック メソッド

パラメーター

解説

例

継承階層

要件

CList::AddHead

パラメーター

戻り値

解説

例

CList::AddTail

パラメーター

戻り値

解説

例

CList::CList

パラメーター

解説

例

CList::Find

パラメーター

戻り値

例

CList::FindIndex

パラメーター

戻り値

解説

例

CList::GetAt

パラメーター

戻り値

解説

例

CList::GetCount

戻り値

解説

例

CList::GetHead

パラメーター

戻り値

解説

例

CList::GetHeadPosition

戻り値

例

CList::GetNext

パラメーター

戻り値

解説

例

CList::GetPrev

パラメーター

戻り値

解説

例

CList::GetSize

戻り値

解説

例

CList::GetTail

パラメーター

戻り値

解説

例

CList::GetTailPosition

戻り値

例

CList::InsertAfter

パラメーター

戻り値

例

CList::InsertBefore

パラメーター

戻り値

`CList` クラス

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

パブリックメソッド

`CList::AddHead`

`CList::AddTail`

`CList::CList`

`CList::Find`

`CList::FindIndex`

`CList::GetAt`

`CList::GetCount`

`CList::GetHead`

`CList::GetHeadPosition`

`CList::GetNext`

`CList::GetPrev`

`CList::GetSize`

`CList::GetTail`

`CList::GetTailPosition`

`CList::InsertAfter`

`CList::InsertBefore`

`CList::IsEmpty`

`CList::RemoveAll`

`CList::RemoveAt`

`CList::RemoveHead`

`CList::RemoveTail`

`CList::SetAt`