`CList` 类

项目
10/12/2023

支持可按顺序或值访问的不唯一对象的有序列表。

语法

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`	返回列表的尾部元素（不能为空）。
`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
搜索的起始位置。如果未指定任何值，则搜索从头部元素开始。

返回值

可用于迭代或对象指针检索的 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 值；如果 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`

获取给定位置的列表元素。

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`

获取此列表的头部元素（或对头部元素的引用）。

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 指针。

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`

获取此列表的尾部元素的位置；如果列表为空，则为 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
由以前的 GetNext、GetPrev 或 Find 成员函数调用返回的 POSITION 值。

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`