CAtlList 类

此类提供用于创建和管理列表对象的方法。

语法

template<typename E, class ETraits = CElementTraits<E>>
class CAtlList

参数

E
元素类型。

ETraits
用于复制或移动元素的代码。 有关更多详细信息，请参阅 CElementTraits 类。

成员

公共 Typedef

公共构造函数

公共方法

备注

CAtlList 类支持可按顺序或值访问的不唯一对象的有序列表。 CAtlList 列表的行为类似于双重链接列表。 每个列表具有一个头部和一个尾部，新元素（或某些情况下为列表）可以添加到列表的任一端，或者插入到特定元素的前面或后面。

大多数 CAtlList 方法使用位置值。 方法使用此值来引用存储元素的实际内存位置，不应直接计算或预测。 如果需要访问列表中的第 n 个元素，方法 CAtlList::FindIndex 将返回给定索引的相应位置值。 方法 CAtlList::GetNext 和 CAtlList::GetPrev 可用于迭代列表中的对象。

有关可用于 ATL 的集合类的详细信息，请参阅 ATL 集合类。

要求

标头：atlcoll.h

CAtlList::AddHead

调用此方法可将元素添加到列表的头部。

POSITION AddHead();
POSITION AddHead(INARGTYPE element);

参数

element
新元素。

返回值

返回新添加的元素的位置。

备注

如果使用第一个版本，则会使用其默认构造函数而不是复制构造函数来创建一个空元素。

示例

// Declare a list of integers
CAtlList<int> myList;

// Add some elements, each to the head of the list.
// As each new element is added, the previous head is
// pushed down the list.
myList.AddHead(42);
myList.AddHead(49);

// Confirm the value currently at the head of the list
ATLASSERT(myList.GetHead() == 49);

// Confirm the value currently at the tail of the list
ATLASSERT(myList.GetTail() == 42);   

CAtlList::AddHeadList

调用此方法可将现有列表添加到列表的头部。

void AddHeadList(const CAtlList<E, ETraits>* plNew);

参数

plNew
要添加的列表。

备注

plNew 指向的列表将插入到现有列表的开头。 在调试版本中，如果 plNew 等于 NULL，将发生断言失败。

示例

// Define two lists of integers
CAtlList<int> myList1;
CAtlList<int> myList2;

// Fill up the first list
myList1.AddTail(1);
myList1.AddTail(2);
myList1.AddTail(3);

// Add an element to the second list
myList2.AddTail(4);

// Insert the first list into the second
myList2.AddHeadList(&myList1);

// The second list now contains:
// 1, 2, 3, 4   

CAtlList::AddTail

调用此方法可将元素添加到此列表的尾部。

POSITION AddTail();
POSITION AddTail(INARGTYPE element);

参数

element
要添加的元素。

返回值

返回新添加的元素的位置。

备注

如果使用第一个版本，则会使用其默认构造函数而不是复制构造函数来创建一个空元素。 该元素将添加到列表的末尾，因此它现在成了尾部。 此方法可用于空列表。

示例

// Define the list
CAtlList<int> myList;

// Add elements to the tail
myList.AddTail(1);
myList.AddTail(2);
myList.AddTail(3);

// Confirm the current head of the list
ATLASSERT(myList.GetHead() == 1);

// Confirm the current tail of the list
ATLASSERT(myList.GetTail() == 3);   

CAtlList::AddTailList

调用此方法可将现有列表添加到此列表的尾部。

void AddTailList(const CAtlList<E, ETraits>* plNew);

参数

plNew
要添加的列表。

备注

plNew 指向的列表将插入到列表对象中最后一个元素（如果有）的后面。 plNew 列表中的最后一个元素因此成了尾部。 在调试版本中，如果 plNew 等于 NULL，将发生断言失败。

示例

// Define two integer lists
CAtlList<int> myList1;
CAtlList<int> myList2;

// Fill up the first list
myList1.AddTail(1);
myList1.AddTail(2);
myList1.AddTail(3);

// Add an element to the second list
myList2.AddTail(4);

// Insert the first list into the second
myList2.AddTailList(&myList1);

// The second list now contains:
// 4, 1, 2, 3   

CAtlList::AssertValid

调用此方法可确认列表是否有效。

void AssertValid() const;

备注

在调试版本中，如果列表对象无效，则会发生断言失败。 要使列表对象有效，空列表的头部和尾部都必须指向 NULL，而非空列表的头部和尾部必须都指向有效地址。

示例

// Define the list
CAtlList<int> myList;

// AssertValid only exists in debug builds
#ifdef _DEBUG
myList.AssertValid();
#endif   

CAtlList::CAtlList

构造函数。

CAtlList(UINT nBlockSize = 10) throw();

参数

nBlockSize
块大小。

注解

CAtlList 对象的构造函数。 块大小用于衡量在需要新元素时分配的内存量。 较大的块大小可减少对内存分配例程的调用，但会使用更多资源。

示例

// Define two lists
CAtlList<int> myList1;
CAtlList<double> myList2;   

CAtlList::~CAtlList

析构函数。

~CAtlList() throw();

备注

释放所有已分配的资源，包括调用 CAtlList::RemoveAll 以从列表中删除所有元素。

在调试版本中，如果列表在调用 RemoveAll 后仍包含某些元素，则会发生断言失败。

CAtlList::Find

调用此方法可在列表中搜索指定的元素。

POSITION Find(INARGTYPE element, POSITION posStartAfter = NULL) const throw();

参数

element
要在列表中查找的元素。

posStartAfter
搜索的起始位置。 如果未指定任何值，则搜索从头部元素开始。

返回值

如果找到，则返回元素的 POSITION 值，否则返回 NULL。

备注

在调试版本中，如果列表对象无效或 posStartAfter 值超出范围，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);
myList.AddTail(300);
myList.AddTail(400);

// Find the '300' element in the list,
// starting from the list head.
POSITION myPos = myList.Find(300);

// Confirm that the element was found
ATLASSERT(myList.GetAt(myPos) == 300);   

CAtlList::FindIndex

在指定了索引值的情况下，调用此方法可获取元素的位置。

POSITION FindIndex(size_t iElement) const throw();

参数

iElement
所需列表元素的从零开始的索引。

返回值

返回相应的 POSITION 值，如果 iElement 超出范围，则返回 NULL。

注解

此方法返回对应于给定索引值的 POSITION，以便可以访问列表中的第 n 个元素。

在调试版本中，如果列表对象无效，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
for (int i = 0; i < 100; i++)
{
   myList.AddTail(i);
}

// Iterate through the entire list
for (size_t j = 0; j < myList.GetCount(); j++)
{
   size_t i = myList.GetAt(myList.FindIndex(j));
   ATLASSERT(i == j);
}   

CAtlList::GetAt

调用此方法可返回位于列表中指定位置的元素。

E& GetAt(POSITION pos) throw();
const E& GetAt(POSITION pos) const throw();

参数

pos
用于指定特定元素的 POSITION 值。

返回值

对元素或其副本的引用。

备注

如果列表为 const，则 GetAt 返回元素的副本。 允许仅对赋值语句的右侧使用该方法并防止修改列表。

如果列表不为 const，则 GetAt 返回对元素的引用。 允许对赋值语句的任一侧使用该方法，从而允许修改列表条目。

在调试版本中，如果 pos 等于 NULL，则会发生断言失败。

示例

请参阅 CAtlList::FindIndex 的示例。

CAtlList::GetCount

调用此方法可返回列表中的对象数。

size_t GetCount() const throw();

返回值

返回列表中元素的数目。

示例

请参阅 CAtlList::Find 的示例。

CAtlList::GetHead

调用此方法可返回位于列表头部位置的元素。

E& GetHead() throw();
const E& GetHead() const throw();

返回值

返回对位于列表头部位置的元素或其副本的引用。

备注

如果列表为 const，则 GetHead 返回位于列表头部位置的元素的副本。 允许仅对赋值语句的右侧使用该方法并防止修改列表。

如果列表不为 const，则 GetHead 返回对位于列表头部位置的元素的引用。 允许对赋值语句的任一侧使用该方法，从而允许修改列表条目。

在调试版本中，如果列表的头部指向 NULL，则会发生断言失败。

示例

请参阅 CAtlList::AddHead 的示例。

CAtlList::GetHeadPosition

调用此方法可获取列表的头部位置。

POSITION GetHeadPosition() const throw();

返回值

返回与位于列表头部位置的元素对应的 POSITION 值。

备注

如果列表为空，则返回的值为 NULL。

示例

// Define the integer list
CAtlList<int> myList;
int i;

// Populate the list
for (i = 0; i < 100; i++)
{
   myList.AddTail(i);
}

// Get the starting position value
POSITION myPos = myList.GetHeadPosition();

// Iterate through the entire list
i = 0;
int j;

do {
   j = myList.GetNext(myPos);
   ATLASSERT(i == j);
   i++;
} while (myPos != NULL);   

CAtlList::GetNext

调用此方法可返回列表中的下一个元素。

E& GetNext(POSITION& pos) throw();
const E& GetNext(POSITION& pos) const throw();

参数

pos
先前的 GetNext 调用、CAtlList::GetHeadPosition 或其他 CAtlList 方法返回的 POSITION 值。

返回值

如果列表为 const，则 GetNext 返回列表的下一个元素的副本。 允许仅对赋值语句的右侧使用该方法并防止修改列表。

如果列表不为 const，则 GetNext 返回对列表的下一个元素的引用。 允许对赋值语句的任一侧使用该方法，从而允许修改列表条目。

备注

POSITION 计数器 pos 将更新为指向列表中的下一个元素，如果没有其他元素，则为 NULL。 在调试版本中，如果 pos 等于 NULL，则会发生断言失败。

示例

请参阅 CAtlList::GetHeadPosition 的示例。

CAtlList::GetPrev

调用此方法可返回列表中的上一个元素。

E& GetPrev(POSITION& pos) throw();
const E& GetPrev(POSITION& pos) const throw();

参数

pos
先前的 GetPrev 调用、CAtlList::GetTailPosition 或其他 CAtlList 方法返回的 POSITION 值。

返回值

如果列表为 const，则 GetPrev 返回列表的某个元素的副本。 允许仅对赋值语句的右侧使用该方法并防止修改列表。

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

备注

POSITION 计数器 pos 将更新为指向列表中的上一个元素，如果没有其他元素，则为 NULL。 在调试版本中，如果 pos 等于 NULL，则会发生断言失败。

示例

请参阅 CAtlList::GetTailPosition 的示例。

CAtlList::GetTail

调用此方法可返回位于列表尾部位置的元素。

E& GetTail() throw();
const E& GetTail() const throw();

返回值

返回对位于列表尾部位置的元素或其副本的引用。

备注

如果列表为 const，则 GetTail 返回位于列表头部位置的元素的副本。 允许仅对赋值语句的右侧使用该方法并防止修改列表。

如果列表不为 const，则 GetTail 返回对位于列表头部位置的元素的引用。 允许对赋值语句的任一侧使用该方法，从而允许修改列表条目。

在调试版本中，如果列表的尾部指向 NULL，则会发生断言失败。

示例

请参阅 CAtlList::AddTail 的示例。

CAtlList::GetTailPosition

调用此方法可获取列表的尾部位置。

POSITION GetTailPosition() const throw();

返回值

返回与位于列表尾部位置的元素对应的 POSITION 值。

注解

如果列表为空，则返回的值为 NULL。

示例

// Define the integer list
CAtlList<int> myList;
int i;

// Populate the list
for (i = 0; i < 100; i++)
{
   myList.AddHead(i);
}

// Get the starting position value
POSITION myP = myList.GetTailPosition();

// Iterate through the entire list
i = 0;
int j;

do {
   j = myList.GetPrev(myP);
   ATLASSERT(i == j);
   i++;
} while (myP != NULL);   

CAtlList::INARGTYPE

作为输入参数传递元素时使用的类型。

typedef ETraits::INARGTYPE INARGTYPE;

CAtlList::InsertAfter

调用此方法可将新元素插入到列表中的指定位置之后。

POSITION InsertAfter(POSITION pos, INARGTYPE element);

参数

pos
要在其后插入新元素的 POSITION 值。

element
要插入的元素。

返回值

返回新元素的 POSITION 值。

备注

在调试版本中，如果列表无效、插入失败或尝试在尾部之后插入元素，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
POSITION myPos = myList.AddHead(1);
myPos = myList.InsertAfter(myPos, 2);
myPos = myList.InsertAfter(myPos, 3);

// Confirm the tail value is as expected
ATLASSERT(myList.GetTail() == 3);   

CAtlList::InsertBefore

调用此方法可将新元素插入到列表中的指定位置之前。

POSITION InsertBefore(POSITION pos, INARGTYPE element);

参数

pos
新元素将插入到列表中此 POSITION 值之前。

element
要插入的元素。

返回值

返回新元素的 POSITION 值。

备注

在调试版本中，如果列表无效、插入失败或尝试在头部之前插入元素，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
POSITION myPos = myList.AddHead(1);
myPos = myList.InsertBefore(myPos, 2);
myPos = myList.InsertBefore(myPos, 3);

// Confirm the head value is as expected
ATLASSERT(myList.GetHead() == 3);  

CAtlList::IsEmpty

调用此方法可确定列表是否为空。

bool IsEmpty() const throw();

返回值

如果列表不包含任何对象，则返回 true，否则返回 false。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(1);
myList.AddTail(2);
myList.AddTail(3);
myList.AddTail(4);

// Confirm not empty
ATLASSERT(myList.IsEmpty() == false);

// Remove the tail element
myList.RemoveTailNoReturn();

// Confirm not empty
ATLASSERT(myList.IsEmpty() == false);

// Remove the head element
myList.RemoveHeadNoReturn();

// Confirm not empty
ATLASSERT(myList.IsEmpty() == false);

// Remove all remaining elements
myList.RemoveAll();

// Confirm empty
ATLASSERT(myList.IsEmpty() == true);   

CAtlList::MoveToHead

调用此方法可将指定的元素移到列表的头部。

void MoveToHead(POSITION pos) throw();

参数

pos
要移动的元素的 POSITION 值。

备注

指定的元素将从其当前位置移到列表的头部。 在调试版本中，如果 pos 等于 NULL，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(1);
myList.AddTail(2);
myList.AddTail(3);
myList.AddTail(4);

// Move the tail element to the head
myList.MoveToHead(myList.GetTailPosition());

// Confirm the head is as expected
ATLASSERT(myList.GetHead() == 4);

// Move the head element to the tail
myList.MoveToTail(myList.GetHeadPosition());

// Confirm the tail is as expected
ATLASSERT(myList.GetTail() == 4);   

CAtlList::MoveToTail

调用此方法可将指定的元素移到列表的尾部。

void MoveToTail(POSITION pos) throw();

参数

pos
要移动的元素的 POSITION 值。

备注

指定的元素将从其当前位置移到列表的尾部。 在调试版本中，如果 pos 等于 NULL，则会发生断言失败。

示例

请参阅 CAtlList::MoveToHead 的示例。

CAtlList::RemoveAll

调用此方法可从列表中删除所有元素。

void RemoveAll() throw();

备注

此方法从列表中删除所有元素并释放已分配的内存。 在调试版本中，如果未删除所有元素或列表结构已损坏，则会引发 ATLASSERT。

示例

请参阅 CAtlList::IsEmpty 的示例。

CAtlList::RemoveAt

调用此方法可从列表中删除单个元素。

void RemoveAt(POSITION pos) throw();

参数

pos
要删除的元素的 POSITION 值。

备注

将删除 pos 引用的元素并释放内存。 可以使用 RemoveAt 删除列表的头部或尾部。

在调试版本中，如果列表无效或删除元素会导致列表访问不属于列表结构的内存，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);
myList.AddTail(300);

// Use RemoveAt to remove elements one by one
myList.RemoveAt(myList.Find(100));
myList.RemoveAt(myList.Find(200));
myList.RemoveAt(myList.Find(300));

// Confirm all have been deleted
ATLASSERT(myList.IsEmpty() == true);   

CAtlList::RemoveHead

调用此方法可删除位于列表头部位置的元素。

E RemoveHead();

返回值

返回位于列表头部位置的元素。

备注

从列表中删除头部元素并释放内存。 返回元素的副本。 在调试版本中，如果列表为空，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);
myList.AddTail(300);

// Confirm the head of the list
ATLASSERT(myList.GetHead() == 100);

// Remove the head of the list
ATLASSERT(myList.RemoveHead() == 100);

// Confirm the new head of the list
ATLASSERT(myList.GetHead() == 200);   

CAtlList::RemoveHeadNoReturn

调用此方法可删除位于列表头部位置的元素且不返回值。

void RemoveHeadNoReturn() throw();

备注

从列表中删除头部元素并释放内存。 在调试版本中，如果列表为空，则会发生断言失败。

示例

请参阅 CAtlList::IsEmpty 的示例。

CAtlList::RemoveTail

调用此方法可删除位于列表尾部位置的元素。

E RemoveTail();

返回值

返回位于列表尾部位置的元素。

备注

从列表中删除尾部元素并释放内存。 返回元素的副本。 在调试版本中，如果列表为空，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);
myList.AddTail(300);

// Confirm the tail of the list
ATLASSERT(myList.GetTail() == 300);

// Remove the tail of the list
ATLASSERT(myList.RemoveTail() == 300);

// Confirm the new tail of the list
ATLASSERT(myList.GetTail() == 200);   

CAtlList::RemoveTailNoReturn

调用此方法可删除位于列表尾部位置的元素且不返回值。

void RemoveTailNoReturn() throw();

注解

从列表中删除尾部元素并释放内存。 在调试版本中，如果列表为空，则会发生断言失败。

示例

请参阅 CAtlList::IsEmpty 的示例。

CAtlList::SetAt

调用此方法可在列表中的给定位置设置元素的值。

void SetAt(POSITION pos, INARGTYPE element);

参数

pos
与要更改的元素对应的 POSITION 值。

element
新元素值。

备注

将现有值替换为 element。 在调试版本中，如果 pos 等于 NULL，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
myList.AddTail(100);
myList.AddTail(200);

// Use SetAt to change the values stored in the head and
// tail of the list
myList.SetAt(myList.GetHeadPosition(), myList.GetHead() * 10);
myList.SetAt(myList.GetTailPosition(), myList.GetTail() * 10);

// Confirm the values
ATLASSERT(myList.GetHead() == 1000);
ATLASSERT(myList.GetTail() == 2000);   

CAtlList::SwapElements

调用此方法可交换列表中的元素。

void SwapElements(POSITION pos1, POSITION pos2) throw();

参数

pos1
第一个 POSITION 值。

pos2
第二个 POSITION 值。

注解

交换位于两个指定位置的元素。 在调试版本中，如果任一位置值等于 NULL，则会发生断言失败。

示例

// Define the integer list
CAtlList<int> myList;

// Populate the list
for (int i = 0; i < 100; i++)
{
   myList.AddHead(i);
}

// Order is: 99, 98, 97, 96...
ATLASSERT(myList.GetHead() == 99);
ATLASSERT(myList.GetTail() == 0);

// Perform a crude bubble sort
for (int j = 0; j < 100; j++)
{
   for(int i = 0; i < 99; i++)
   {
      if (myList.GetAt(myList.FindIndex(i)) > 
         myList.GetAt(myList.FindIndex(i+1)))
      {
         myList.SwapElements(myList.FindIndex(i), myList.FindIndex(i+1));
      }
   }
}

// Order is: 0, 1, 2, 3...
ATLASSERT(myList.GetHead() == 0);
ATLASSERT(myList.GetTail() == 99);   

另请参阅

CList 类
类概述