CAtlList 類別

這個類別提供建立和管理清單物件的方法。

語法

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

參數

E
元素類型。

ETraits
用來複製或移動元素的程序代碼。 如需詳細資訊，請參閱 CElementTraits 類別 。

成員

公用 Typedefs

公用建構函式

公用方法

備註

類別 CAtlList 支援依序或依值存取的非統一物件排序列表。 CAtlList 清單的行為就像是連結的兩倍清單。 每個清單都有一個前端和一個尾端，而新的元素（在某些情況下，或清單）可以加入至清單的結尾，或在特定元素之前或之後插入。

CAtlList大部分的方法都會使用位置值。 此方法會使用這個值來參考儲存項目的實際記憶體位置，而且不應該直接計算或預測。 如果需要存取清單中的第 n個元素，CAtlList：：FindIndex 方法會傳回指定索引的對應位置值。 CAtlList：：GetNext 和 CAtlList：：GetPrev 方法可用來逐一查看清單中的物件。

如需有關 ATL 可用之集合類別的詳細資訊，請參閱 ATL 集合類別。

需求

標頭： atlcoll.h

CAtlList：：AddHead

呼叫這個方法，將專案新增至清單的標頭。

POSITION AddHead();
POSITION AddHead(INARGTYPE 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);

參數

元素
要加入的項目。

傳回值

傳回新加入專案的 POSITION。

備註

如果使用第一個版本，則會使用其預設建構函式來建立空白元素，而不是使用其複製建構函式。 元素會新增至清單結尾，因此它現在會變成尾端。 這個方法可以搭配空白清單使用。

範例

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

參數

元素
清單中要找到的專案。

posStartAfter
搜尋的開始位置。 如果未指定任何值，搜尋會以 head 元素開頭。

傳回值

如果找到，則傳回專案的 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 值。

元素
要插入的專案。

傳回值

傳回新專案的 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 值。

元素
要插入的專案。

傳回值

傳回新專案的 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();

傳回值

傳回清單尾端的專案。

備註

tail 元素會從清單中刪除，並釋放記憶體。 傳回項目的複本。 在偵錯組建中，如果清單是空的，就會發生判斷提示失敗。

範例

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

備註

tail 元素會從清單中刪除，並釋放記憶體。 在偵錯組建中，如果清單是空的，就會發生判斷提示失敗。

範例

請參閱 CAtlList：：IsEmpty 的範例。

CAtlList：：SetAt

呼叫這個方法，以在清單中指定位置設定專案的值。

void SetAt(POSITION pos, INARGTYPE element);

參數

pos
對應至要變更之專案的 POSITION 值。

元素
新的項目值。

備註

以專案取代現有的值。 在偵錯組建中，如果 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 類別
類別概觀