共用方式為


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::GetNextCAtlList::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 值。

傳回值

項目的參考或複本。

備註

如果清單是 constGetAt 則會傳回 項目的複本。 這可讓方法只在指派語句的右側使用,並保護清單不受修改。

如果清單不是 constGetAt 則會傳回項目的參考。 這可讓 方法用於指派語句的任一端,因此允許修改清單專案。

在偵錯組建中,如果 pos 等於 NULL,就會發生判斷提示失敗。

範例

請參閱 CAtlList::FindIndex範例。

CAtlList::GetCount

呼叫此方法可傳回清單中的物件數目。

size_t GetCount() const throw();

傳回值

傳回清單中項目的數目。

範例

請參閱 CAtlList::Find範例。

CAtlList::GetHead

呼叫這個方法可傳回清單前端的專案。

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

傳回值

傳回清單前端元素的參考或複本。

備註

如果清單是 constGetHead 則會傳回清單前端的項目複本。 這可讓方法只在指派語句的右側使用,並保護清單不受修改。

如果清單不是 constGetHead 則會傳回清單前端元素的參考。 這可讓 方法用於指派語句的任一端,因此允許修改清單專案。

在偵錯組建中,如果清單的前端指向 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
由先前呼叫 GetNextCAtlList::GetHeadPosition 或其他 CAtlList 方法所傳回的 POSITION 值。

傳回值

如果清單是 constGetNext 則會傳回清單下一個項目的複本。 這可讓方法只在指派語句的右側使用,並保護清單不受修改。

如果清單不是 constGetNext 則會傳回清單下一個項目的參考。 這可讓 方法用於指派語句的任一端,因此允許修改清單專案。

備註

POSITION 計數器 pos 會更新為指向清單中的下一個專案,如果沒有其他元素,則為 NULL。 在偵錯組建中,如果 pos 等於 NULL,就會發生判斷提示失敗。

範例

請參閱 CAtlList::GetHeadPosition範例。

CAtlList::GetPrev

呼叫這個方法,以從清單中傳回上一個專案。

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

參數

pos
由先前呼叫 GetPrevCAtlList::GetTailPosition 或其他 CAtlList 方法所傳回的 POSITION 值。

傳回值

如果清單是 constGetPrev 則會傳回清單項目的複本。 這可讓方法只在指派語句的右側使用,並保護清單不受修改。

如果清單不是 constGetPrev 則會傳回清單項目的參考。 這可讓 方法用於指派語句的任一端,因此允許修改清單專案。

備註

POSITION 計數器 pos 會更新為指向清單中的上一個專案,如果沒有其他元素,則為 NULL。 在偵錯組建中,如果 pos 等於 NULL,就會發生判斷提示失敗。

範例

請參閱 CAtlList::GetTailPosition範例。

CAtlList::GetTail

呼叫這個方法,以傳回清單尾端的專案。

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

傳回值

傳回清單尾端項目的參考或複本。

備註

如果清單是 constGetTail 則會傳回清單前端的項目複本。 這可讓方法只在指派語句的右側使用,並保護清單不受修改。

如果清單不是 constGetTail 則會傳回清單前端元素的參考。 這可讓 方法用於指派語句的任一端,因此允許修改清單專案。

在偵錯組建中,如果清單結尾指向 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 類別
類別概觀