CAtlList 類別
這個類別提供建立和管理清單物件的方法。
語法
template<typename E, class ETraits = CElementTraits<E>>
class CAtlList
參數
E
元素類型。
ETraits
用來複製或移動元素的程序代碼。 如需詳細資訊,請參閱 CElementTraits 類別 。
成員
公用 Typedefs
名稱 | 描述 |
---|---|
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);
參數
元素
新專案。
傳回值
傳回新加入專案的位置。
備註
如果使用第一個版本,則會使用其預設建構函式來建立空白元素,而不是使用其複製建構函式。
範例
// 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);