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

See Also

CList Class
Class Overview