CAtlList 类
此类提供用于创建和管理列表对象的方法。
语法
template<typename E, class ETraits = CElementTraits<E>>
class CAtlList
参数
E
元素类型。
ETraits
用于复制或移动元素的代码。 有关更多详细信息，请参阅 CElementTraits 类。
成员
公共 Typedef
| 名称 | 描述 |
|---|---|
| CAtlList::INARGTYPE |
公共构造函数
| 名称 | 描述 |
|---|---|
| CAtlList::CAtlList | 构造函数。 |
| CAtlList::~CAtlList | 析构函数。 |
公共方法
| 名称 | 描述 |
|---|---|
| CAtlList::AddHead | 调用此方法可将元素添加到列表的头部。 |
| CAtlList::AddHeadList | 调用此方法可将现有列表添加到列表的头部。 |
| CAtlList::AddTail | 调用此方法可将元素添加到此列表的尾部。 |
| CAtlList::AddTailList | 调用此方法可将现有列表添加到此列表的尾部。 |
| CAtlList::AssertValid | 调用此方法可确认列表是否有效。 |
| CAtlList::Find | 调用此方法可在列表中搜索指定的元素。 |
| CAtlList::FindIndex | 在指定了索引值的情况下，调用此方法可获取元素的位置。 |
| CAtlList::GetAt | 调用此方法可返回位于列表中指定位置的元素。 |
| CAtlList::GetCount | 调用此方法可返回列表中的对象数。 |
| CAtlList::GetHead | 调用此方法可返回位于列表头部位置的元素。 |
| CAtlList::GetHeadPosition | 调用此方法可获取列表的头部位置。 |
| CAtlList::GetNext | 调用此方法可返回列表中的下一个元素。 |
| CAtlList::GetPrev | 调用此方法可返回列表中的上一个元素。 |
| CAtlList::GetTail | 调用此方法可返回位于列表尾部位置的元素。 |
| CAtlList::GetTailPosition | 调用此方法可获取列表的尾部位置。 |
| CAtlList::InsertAfter | 调用此方法可将新元素插入到列表中的指定位置之后。 |
| CAtlList::InsertBefore | 调用此方法可将新元素插入到列表中的指定位置之前。 |
| CAtlList::IsEmpty | 调用此方法可确定列表是否为空。 |
| CAtlList::MoveToHead | 调用此方法可将指定的元素移到列表的头部。 |
| CAtlList::MoveToTail | 调用此方法可将指定的元素移到列表的尾部。 |
| CAtlList::RemoveAll | 调用此方法可从列表中删除所有元素。 |
| CAtlList::RemoveAt | 调用此方法可从列表中删除单个元素。 |
| CAtlList::RemoveHead | 调用此方法可删除位于列表头部位置的元素。 |
| CAtlList::RemoveHeadNoReturn | 调用此方法可删除位于列表头部位置的元素且不返回值。 |
| CAtlList::RemoveTail | 调用此方法可删除位于列表尾部位置的元素。 |
| CAtlList::RemoveTailNoReturn | 调用此方法可删除位于列表尾部位置的元素且不返回值。 |
| CAtlList::SetAt | 调用此方法可在列表中的给定位置设置元素的值。 |
| CAtlList::SwapElements | 调用此方法可交换列表中的元素。 |
备注
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);
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈