CAtlList Class
The latest version of this topic can be found at CAtlList Class.
This class provides methods for creating and managing a list object.
Syntax
template<typename E, class ETraits = CElementTraits<E>>
class CAtlList
Parameters
E
The element type.
ETraits
The code used to copy or move elements. See CElementTraits Class for more details.
Members
Public Typedefs
| Name | Description |
|---|---|
| CAtlList::INARGTYPE |
Public Constructors
| Name | Description |
|---|---|
| CAtlList::CAtlList | The constructor. |
| CAtlList::~CAtlList | The destructor. |
Public Methods
| Name | Description |
|---|---|
| CAtlList::AddHead | Call this method to add an element to the head of the list. |
| CAtlList::AddHeadList | Call this method to add an existing list to the head of the list. |
| CAtlList::AddTail | Call this method to add an element to the tail of this list. |
| CAtlList::AddTailList | Call this method to add an existing list to the tail of this list. |
| CAtlList::AssertValid | Call this method to confirm the list is valid. |
| CAtlList::Find | Call this method to search the list for the specified element. |
| CAtlList::FindIndex | Call this method to obtain the position of an element, given an index value. |
| CAtlList::GetAt | Call this method to return the element at a specified position in the list. |
| CAtlList::GetCount | Call this method to return the number of objects in the list. |
| CAtlList::GetHead | Call this method to return the element at the head of the list. |
| CAtlList::GetHeadPosition | Call this method to obtain the position of the head of the list. |
| CAtlList::GetNext | Call this method to return the next element from the list. |
| CAtlList::GetPrev | Call this method to return the previous element from the list. |
| CAtlList::GetTail | Call this method to return the element at the tail of the list. |
| CAtlList::GetTailPosition | Call this method to obtain the position of the tail of the list. |
| CAtlList::InsertAfter | Call this method to insert a new element into the list after the specified position. |
| CAtlList::InsertBefore | Call this method to insert a new element into the list before the specified position. |
| CAtlList::IsEmpty | Call this method to determine if the list is empty. |
| CAtlList::MoveToHead | Call this method to move the specified element to the head of the list. |
| CAtlList::MoveToTail | Call this method to move the specified element to the tail of the list. |
| CAtlList::RemoveAll | Call this method to remove all of the elements from the list. |
| CAtlList::RemoveAt | Call this method to remove a single element from the list. |
| CAtlList::RemoveHead | Call this method to remove the element at the head of the list. |
| CAtlList::RemoveHeadNoReturn | Call this method to remove the element at the head of the list without returning a value. |
| CAtlList::RemoveTail | Call this method to remove the element at the tail of the list. |
| CAtlList::RemoveTailNoReturn | Call this method to remove the element at the tail of the list without returning a value. |
| CAtlList::SetAt | Call this method to set the value of the element at a given position in the list. |
| CAtlList::SwapElements | Call this method to swap elements in the list. |
Remarks
The CAtlList class supports ordered lists of nonunique objects accessible sequentially or by value. CAtlList lists behave like doubly linked lists. Each list has a head and a tail, and new elements (or lists in some cases) can be added to either end of the list, or inserted before or after specific elements.
Most of the CAtlList methods make use of a position value. This value is used by the methods to reference the actual memory location where the elements are stored, and should not be calculated or predicted directly. If it is necessary to access the nth element in the list, the method CAtlList::FindIndex will return the corresponding position value for a given index. The methods CAtlList::GetNext and CAtlList::GetPrev can be used to iterate through the objects in the list.
For more information regarding the collection classes available with ATL, see ATL Collection Classes.
Requirements
Header: atlcoll.h
CAtlList::AddHead
Call this method to add an element to the head of the list.
POSITION AddHead();
POSITION AddHead(INARGTYPE element);
Parameters
element
The new element.
Return Value
Returns the position of the newly added element.
Remarks
If the first version is used, an empty element is created using its default constructor, rather than its copy constructor.
Example
// 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
Call this method to add an existing list to the head of the list.
void AddHeadList(const CAtlList<E, ETraits>* plNew);
Parameters
plNew
The list to be added.
Remarks
The list pointed to by plNew is inserted at the start of the existing list. In debug builds, an assertion failure will occur if plNew is equal to NULL.
Example
// 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
Call this method to add an element to the tail of this list.
POSITION AddTail();
POSITION AddTail(INARGTYPE element);
Parameters
element
The element to add.
Return Value
Returns the POSITION of the newly added element.
Remarks
If the first version is used, an empty element is created using its default constructor, rather than its copy constructor. The element is added to the end of the list, and so it now becomes the tail. This method can be used with an empty list.
Example
// 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
Call this method to add an existing list to the tail of this list.
void AddTailList(const CAtlList<E, ETraits>* plNew);
Parameters
plNew
The list to be added.
Remarks
The list pointed to by plNew is inserted after the last element (if any) in the list object. The last element in the plNew list therefore becomes the tail. In debug builds, an assertion failure will occur if plNew is equal to NULL.
Example
// 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
Call this method to confirm the list is valid.
void AssertValid() const;
Remarks
In debug builds, an assertion failure will occur if the list object is not valid. To be valid, an empty list must have both the head and tail pointing to NULL, and a list that is not empty must have both the head and tail pointing to valid addresses.
Example
// Define the list
CAtlList<int> myList;
// AssertValid only exists in debug builds
#ifdef _DEBUG
myList.AssertValid();
#endif
CAtlList::CAtlList
The constructor.
CAtlList(UINT nBlockSize = 10) throw();
Parameters
nBlockSize
The block size.
Remarks
The constructor for the CAtlList object. The block size is a measure of the amount of memory allocated when a new element is required. Larger block sizes reduce calls to memory allocation routines, but use more resources.
Example
// Define two lists
CAtlList<int> myList1;
CAtlList<double> myList2;
CAtlList::~CAtlList
The destructor.
~CAtlList() throw();
Remarks
Frees all allocated resources, including a call to CAtlList::RemoveAll to remove all elements from the list.
In debug builds, an assertion failure will occur if the list still contains some elements after the call to RemoveAll.
CAtlList::Find
Call this method to search the list for the specified element.
POSITION Find(INARGTYPE element, POSITION posStartAfter = NULL) const throw();
Parameters
element
The element to be found in the list.
posStartAfter
The start position for the search. If no value is specified, the search begins with the head element.
Return Value
Returns the POSITION value of the element if found, otherwise returns NULL.
Remarks
In debug builds, an assertion failure will occur if the list object is not valid, or if the posStartAfter value is out of range.
Example
// 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
Call this method to obtain the position of an element, given an index value.
POSITION FindIndex(size_t iElement) const throw();
Parameters
iElement
The zero-based index of the required list element.
Return Value
Returns the corresponding POSITION value, or NULL if iElement is out of range.
Remarks
This method returns the POSITION corresponding to a given index value, allowing access to the nth element in the list.
In debug builds, an assertion failure will occur if the list object is not valid.
Example
// 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
Call this method to return the element at a specified position in the list.
E& GetAt(POSITION pos) throw();
const E& GetAt(POSITION pos) const throw();
Parameters
pos
The POSITION value specifying a particular element.
Return Value
A reference to, or copy of, the element.
Remarks
If the list is const, GetAt returns a copy of the element. This allows the method to be used only on the right side of an assignment statement and protects the list from modification.
If the list is not const, GetAt returns a reference to the element. This allows the method to be used on either side of an assignment statement and thus allows the list entries to be modified.
In debug builds, an assertion failure will occur if pos is equal to NULL.
Example
See the example for CAtlList::FindIndex.
CAtlList::GetCount
Call this method to return the number of objects in the list.
size_t GetCount() const throw();
Return Value
Returns the number of elements in the list.
Example
See the example for CAtlList::Find.
CAtlList::GetHead
Call this method to return the element at the head of the list.
E& GetHead() throw();
const E& GetHead() const throw();
Return Value
Returns a reference to, or a copy of, the element at the head of the list.
Remarks
If the list is const, GetHead returns a copy of the element at the head of the list. This allows the method to be used only on the right side of an assignment statement and protects the list from modification.
If the list is not const, GetHead returns a reference to the element at the head of the list. This allows the method to be used on either side of an assignment statement and thus allows the list entries to be modified.
In debug builds, an assertion failure will occur if the head of the list points to NULL.
Example
See the example for CAtlList::AddHead.
CAtlList::GetHeadPosition
Call this method to obtain the position of the head of the list.
POSITION GetHeadPosition() const throw();
Return Value
Returns the POSITION value corresponding to the element at the head of the list.
Remarks
If the list is empty, the value returned is NULL.
Example
// 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
Call this method to return the next element from the list.
E& GetNext(POSITION& pos) throw();
const E& GetNext(POSITION& pos) const throw();
Parameters
pos
A POSITION value, returned by a previous call to GetNext, CAtlList::GetHeadPosition, or other CAtlList method.
Return Value
If the list is const, GetNext returns a copy of the next element of the list. This allows the method to be used only on the right side of an assignment statement and protects the list from modification.
If the list is not const, GetNext returns a reference to the next element of the list. This allows the method to be used on either side of an assignment statement and thus allows the list entries to be modified.
Remarks
The POSITION counter, pos, is updated to point to the next element in the list, or NULL if there are no more elements. In debug builds, an assertion failure will occur if pos is equal to NULL.
Example
See the example for CAtlList::GetHeadPosition.
CAtlList::GetPrev
Call this method to return the previous element from the list.
E& GetPrev(POSITION& pos) throw();
const E& GetPrev(POSITION& pos) const throw();
Parameters
pos
A POSITION value, returned by a previous call to GetPrev, CAtlList::GetTailPosition, or other CAtlList method.
Return Value
If the list is const, GetPrev returns a copy of an element of the list. This allows the method to be used only on the right side of an assignment statement and protects the list from modification.
If the list is not const, GetPrev returns a reference to an element of the list. This allows the method to be used on either side of an assignment statement and thus allows the list entries to be modified.
Remarks
The POSITION counter, pos, is updated to point to the previous element in the list, or NULL if there are no more elements. In debug builds, an assertion failure will occur if pos is equal to NULL.
Example
See the example for CAtlList::GetTailPosition.
CAtlList::GetTail
Call this method to return the element at the tail of the list.
E& GetTail() throw();
const E& GetTail() const throw();
Return Value
Returns a reference to, or a copy of, the element at the tail of the list.
Remarks
If the list is const, GetTail returns a copy of the element at the head of the list. This allows the method to be used only on the right side of an assignment statement and protects the list from modification.
If the list is not const, GetTail returns a reference to the element at the head of the list. This allows the method to be used on either side of an assignment statement and thus allows the list entries to be modified.
In debug builds, an assertion failure will occur if the tail of the list points to NULL.
Example
See the example for CAtlList::AddTail.
CAtlList::GetTailPosition
Call this method to obtain the position of the tail of the list.
POSITION GetTailPosition() const throw();
Return Value
Returns the POSITION value corresponding to the element at the tail of the list.
Remarks
If the list is empty, the value returned is NULL.
Example
// 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
Type used when an element is passed as an input argument.
typedef ETraits::INARGTYPE INARGTYPE;
CAtlList::InsertAfter
Call this method to insert a new element into the list after the specified position.
POSITION InsertAfter(POSITION pos, INARGTYPE element);
Parameters
pos
The POSITION value after which the new element will be inserted.
element
The element to be inserted.
Return Value
Returns the POSITION value of the new element.
Remarks
In debug builds, an assertion failure will occur if the list isn't valid, if the insert fails, or if an attempt is made to insert the element after the tail.
Example
// 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
Call this method to insert a new element into the list before the specified position.
POSITION InsertBefore(POSITION pos, INARGTYPE element);
Parameters
pos
The new element will be inserted into the list before this POSITION value.
element
The element to be inserted.
Return Value
Returns the POSITION value of the new element.
Remarks
In debug builds, an assertion failure will occur if the list isn't valid, if the insert fails, or if an attempt is made to insert the element before the head.
Example
// 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
Call this method to determine if the list is empty.
bool IsEmpty() const throw();
Return Value
Returns true if the list contains no objects, otherwise false.
Example
// 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
Call this method to move the specified element to the head of the list.
void MoveToHead(POSITION pos) throw();
Parameters
pos
The POSITION value of the element to move.
Remarks
The specified element is moved from its current position to the head of the list. In debug builds, an assertion failure will occur if pos is equal to NULL.
Example
// 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
Call this method to move the specified element to the tail of the list.
void MoveToTail(POSITION pos) throw();
Parameters
pos
The POSITION value of the element to move.
Remarks
The specified element is moved from its current position to the tail of the list. In debug builds, an assertion failure will occur if pos is equal to NULL.
Example
See the example for CAtlList::MoveToHead.
CAtlList::RemoveAll
Call this method to remove all of the elements from the list.
void RemoveAll() throw();
Remarks
This method removes all of the elements from the list and frees the allocated memory. In debugs builds, an ATLASSERT will be raised if all elements aren't deleted or if the list structure has become corrupted.
Example
See the example for CAtlList::IsEmpty.
CAtlList::RemoveAt
Call this method to remove a single element from the list.
void RemoveAt(POSITION pos) throw();
Parameters
pos
The POSITION value of the element to remove.
Remarks
The element referenced by pos is removed, and memory is freed. It is acceptable to use RemoveAt to remove the head or tail of the list.
In debug builds, an assertion failure will occur if the list is not valid or if removing the element causes the list to access memory which isn't part of the list structure.
Example
// 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
Call this method to remove the element at the head of the list.
E RemoveHead();
Return Value
Returns the element at the head of the list.
Remarks
The head element is deleted from the list, and memory is freed. A copy of the element is returned. In debug builds, an assertion failure will occur if the list is empty.
Example
// 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
Call this method to remove the element at the head of the list without returning a value.
void RemoveHeadNoReturn() throw();
Remarks
The head element is deleted from the list, and memory is freed. In debug builds, an assertion failure will occur if the list is empty.
Example
See the example for CAtlList::IsEmpty.
CAtlList::RemoveTail
Call this method to remove the element at the tail of the list.
E RemoveTail();
Return Value
Returns the element at the tail of the list.
Remarks
The tail element is deleted from the list, and memory is freed. A copy of the element is returned. In debug builds, an assertion failure will occur if the list is empty.
Example
// 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
Call this method to remove the element at the tail of the list without returning a value.
void RemoveTailNoReturn() throw();
Remarks
The tail element is deleted from the list, and memory is freed. In debug builds, an assertion failure will occur if the list is empty.
Example
See the example for CAtlList::IsEmpty.
CAtlList::SetAt
Call this method to set the value of the element at a given position in the list.
void SetAt(POSITION pos, INARGTYPE element);
Parameters
pos
The POSITION value corresponding to the element to change.
element
The new element value.
Remarks
Replaces the existing value with element. In debug builds, an assertion failure will occur if pos is equal to NULL.
Example
// 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
Call this method to swap elements in the list.
void SwapElements(POSITION pos1, POSITION pos2) throw();
Parameters
pos1
The first POSITION value.
pos2
The second POSITION value.
Remarks
Swaps the elements at the two positions specified. In debug builds, an assertion failure will occur if either position value is equal to NULL.
Example
// 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);