CList 类

注释

Microsoft基础类(MFC)库将继续受到支持。 但是,我们不再添加功能或更新文档。

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

语法

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 值;如果 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

获取此列表的头部元素(或对头部元素的引用)。

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
对由以前的 POSITION、GetNext 或其他成员函数调用返回的 GetHeadPosition 值的引用。

返回值

如果列表为 const,则 GetNext 返回列表的某个元素的副本。 这允许仅在赋值语句的右侧使用该函数并防止修改列表。

如果列表不为 const,则 GetNext 返回对列表的某个元素的引用。 这允许在赋值语句的任一侧使用该函数,从而允许修改列表条目。

备注

如果通过调用 GetNext 或 GetHeadPosition 建立初始位置,则可以在正向迭代循环中使用 Find。

必须确保 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
对由以前的 POSITION 或其他成员函数调用返回的 GetPrev 值的引用。

返回值

如果列表为 const,则 GetPrev 返回位于列表头部位置的元素的副本。 这允许仅在赋值语句的右侧使用该函数并防止修改列表。

如果列表不为 const,则 GetPrev 返回对列表的某个元素的引用。 这允许在赋值语句的任一侧使用该函数,从而允许修改列表条目。

备注

如果通过调用 GetPrev 或 GetTailPosition 建立初始位置,则可以在反向迭代循环中使用 Find。

必须确保 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
由以前的 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 类