CAtlList Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

This class provides methods for creating and managing a list object.

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.

Public Typedefs

NameDescription
CAtlList::INARGTYPE

Public Constructors

NameDescription
CAtlList::CAtlListThe constructor.
CAtlList::~CAtlListThe destructor.

Public Methods

NameDescription
CAtlList::AddHeadCall this method to add an element to the head of the list.
CAtlList::AddHeadListCall this method to add an existing list to the head of the list.
CAtlList::AddTailCall this method to add an element to the tail of this list.
CAtlList::AddTailListCall this method to add an existing list to the tail of this list.
CAtlList::AssertValidCall this method to confirm the list is valid.
CAtlList::FindCall this method to search the list for the specified element.
CAtlList::FindIndexCall this method to obtain the position of an element, given an index value.
CAtlList::GetAtCall this method to return the element at a specified position in the list.
CAtlList::GetCountCall this method to return the number of objects in the list.
CAtlList::GetHeadCall this method to return the element at the head of the list.
CAtlList::GetHeadPositionCall this method to obtain the position of the head of the list.
CAtlList::GetNextCall this method to return the next element from the list.
CAtlList::GetPrevCall this method to return the previous element from the list.
CAtlList::GetTailCall this method to return the element at the tail of the list.
CAtlList::GetTailPositionCall this method to obtain the position of the tail of the list.
CAtlList::InsertAfterCall this method to insert a new element into the list after the specified position.
CAtlList::InsertBeforeCall this method to insert a new element into the list before the specified position.
CAtlList::IsEmptyCall this method to determine if the list is empty.
CAtlList::MoveToHeadCall this method to move the specified element to the head of the list.
CAtlList::MoveToTailCall this method to move the specified element to the tail of the list.
CAtlList::RemoveAllCall this method to remove all of the elements from the list.
CAtlList::RemoveAtCall this method to remove a single element from the list.
CAtlList::RemoveHeadCall this method to remove the element at the head of the list.
CAtlList::RemoveHeadNoReturnCall this method to remove the element at the head of the list without returning a value.
CAtlList::RemoveTailCall this method to remove the element at the tail of the list.
CAtlList::RemoveTailNoReturnCall this method to remove the element at the tail of the list without returning a value.
CAtlList::SetAtCall this method to set the value of the element at a given position in the list.
CAtlList::SwapElementsCall this method to swap elements in the list.

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.

Header: atlcoll.h

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

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   

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

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   

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   

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;   

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.

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

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

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.

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.

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.

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

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.

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.

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.

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

Type used when an element is passed as an input argument.

typedef ETraits::INARGTYPE INARGTYPE;

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

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

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

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

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.

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.

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

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

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.

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

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.

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

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

CList Class
Class Overview

Show: