CAtlList Class

Article
12/18/2017

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

Share via

CAtlList Class

Syntax

Parameters

Members

Public Typedefs

Public Constructors

Public Methods

Remarks

Requirements

CAtlList::AddHead

Parameters

Return Value

Remarks

Example

CAtlList::AddHeadList

Parameters

Remarks

Example

CAtlList::AddTail

Parameters

Return Value

Remarks

Example

CAtlList::AddTailList

Parameters

Remarks

Example

CAtlList::AssertValid

Remarks

Example

CAtlList::CAtlList

Parameters

Remarks

Example

CAtlList::~CAtlList

Remarks

CAtlList::Find

Parameters

Return Value

Remarks

Example

CAtlList::FindIndex

Parameters

Return Value

Remarks

Example

CAtlList::GetAt

Parameters

Return Value

Remarks

Example

CAtlList::GetCount

Return Value

Example

CAtlList::GetHead

Return Value

Remarks

Example

CAtlList::GetHeadPosition

Return Value

Remarks

Example

CAtlList::GetNext

Parameters

Return Value

Remarks

Example

CAtlList::GetPrev

Parameters

Return Value

Remarks

Example

CAtlList::GetTail

Return Value

Remarks

Example

CAtlList::GetTailPosition

Return Value

Remarks