`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`	取得以零起始的索引所指定之專案的位置。
`CList::GetAt`	取得位於指定位置的專案。
`CList::GetCount`	傳回此清單中的項目數目。
`CList::GetHead`	傳回清單的前端專案（不能空白）。
`CList::GetHeadPosition`	傳回清單的 head 元素位置。
`CList::GetNext`	取得反覆運算的下一個專案。
`CList::GetPrev`	取得上一個項目進行反覆運算。
`CList::GetSize`	傳回此清單中的項目數目。
`CList::GetTail`	傳回清單的 tail 元素（不能空白）。
`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 用途進行自定義。請參閱一節中的集合類別協助程式。

如需使用 CList的詳細資訊，請參閱集合一文。

範例

// 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
搜尋的開始位置。如果未指定任何值，搜尋會以 head 元素開頭。

傳回值

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
要找到之清單專案的以零起始的索引。

傳回值

POSITION值，可用於反覆專案或對象指標擷取;NULL如果 nIndex 為負數或太大。

備註

它會從清單的前端開始循序掃描，並在第 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`

取得位於指定位置的清單專案。

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

參數

TYPE
範本參數，指定清單中的物件類型。

position
要取得之項目清單中的位置。

傳回值

請參閱的 GetHead傳回值描述。

備註

GetAt 會傳回與指定位置相關聯的專案（或項目的參考）。它與索引不同，您無法自行操作 POSITION 值。類型的 POSITION 變數是清單的索引鍵。

您必須確定您的 POSITION 值代表清單中的有效位置。如果無效，則Microsoft基礎類別庫的偵錯版本判斷提示。

範例

請參閱 CList::GetHeadPosition 的範例。

`CList::GetCount`

取得此清單中的項目數目。

INT_PTR GetCount() const;

傳回值

包含項目計數的整數值。

備註

呼叫此方法會產生與 CList::GetSize 方法相同的結果。

範例

請參閱 CList::RemoveHead 的範例。

`CList::GetHead`

取得此清單的 head 元素（或 head 元素的參考）。

const TYPE& GetHead() const;

TYPE& GetHead();

參數

TYPE
範本參數，指定清單中的物件類型。

傳回值

如果清單是 const， GetHead 則會傳回清單前端的項目複本。這可讓函式只能在指派語句的右側使用，並保護清單不受修改。

如果清單不是 const， GetHead 則會傳回清單前端元素的參考。這可讓函式用於工作分派語句的任一端，因此允許修改清單專案。

備註

在呼叫 GetHead之前，您必須確定清單不是空的。如果清單是空的，則Microsoft基礎類別庫的偵錯版本判斷提示。使用 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在正向反覆運算循環中使用。

您必須確定您的 POSITION 值代表清單中的有效位置。如果無效，則Microsoft基礎類別庫的偵錯版本判斷提示。

如果擷取的專案是清單中的最後一個，則的新值 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 。

您必須確定您的 POSITION 值代表清單中的有效位置。如果無效，則Microsoft基礎類別庫的偵錯版本判斷提示。

如果擷取的專案是第一個清單中的專案，則的新值 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取得指標，表示這個清單的tail元素。

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

參數

TYPE
範本參數，指定清單中的項目類型。

傳回值

請參閱的 GetHead傳回值描述。

備註

在呼叫 GetTail之前，您必須確定清單不是空的。如果清單是空的，則Microsoft基礎類別庫的偵錯版本判斷提示。使用 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
指定清單項目類型的樣板參數。

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
POSITION先前GetNext、 GetPrev或 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。

範例

// 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
要從清單中移除之專案的位置。

備註

您必須確定您的 POSITION 值代表清單中的有效位置。如果無效，則Microsoft基礎類別庫的偵錯版本判斷提示。

範例

// 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基礎類別庫的偵錯版本判斷提示。使用 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基礎類別庫的偵錯版本判斷提示。使用 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 將專案寫入清單中指定的位置。

您必須確定您的 POSITION 值代表清單中的有效位置。如果無效，則Microsoft基礎類別庫的偵錯版本判斷提示。

範例

// 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);

另請參閱

MFC 範例 COLLECT
CObject 類
 階層架構圖表
 CMap 類
 CArray 類

共用方式為

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`