`CList` Class

Article
08/03/2021

Supports ordered lists of nonunique objects accessible sequentially or by value.

Syntax

template<class TYPE, class ARG_TYPE = const TYPE&>
class CList : public CObject

Members

Public Constructors

Name	Description
`CList::CList`	Constructs an empty ordered list.

Public Methods

Name	Description
`CList::AddHead`	Adds an element (or all the elements in another list) to the head of the list (makes a new head).
`CList::AddTail`	Adds an element (or all the elements in another list) to the tail of the list (makes a new tail).
`CList::Find`	Gets the position of an element specified by pointer value.
`CList::FindIndex`	Gets the position of an element specified by a zero-based index.
`CList::GetAt`	Gets the element at a given position.
`CList::GetCount`	Returns the number of elements in this list.
`CList::GetHead`	Returns the head element of the list (cannot be empty).
`CList::GetHeadPosition`	Returns the position of the head element of the list.
`CList::GetNext`	Gets the next element for iterating.
`CList::GetPrev`	Gets the previous element for iterating.
`CList::GetSize`	Returns the number of elements in this list.
`CList::GetTail`	Returns the tail element of the list (cannot be empty).
`CList::GetTailPosition`	Returns the position of the tail element of the list.
`CList::InsertAfter`	Inserts a new element after a given position.
`CList::InsertBefore`	Inserts a new element before a given position.
`CList::IsEmpty`	Tests for the empty list condition (no elements).
`CList::RemoveAll`	Removes all the elements from this list.
`CList::RemoveAt`	Removes an element from this list, specified by position.
`CList::RemoveHead`	Removes the element from the head of the list.
`CList::RemoveTail`	Removes the element from the tail of the list.
`CList::SetAt`	Sets the element at a given position.

Parameters

TYPE
Type of object stored in the list.

ARG_TYPE
Type used to reference objects stored in the list. Can be a reference.

Remarks

CList lists behave like doubly-linked lists.

A variable of type POSITION is a key for the list. You can use a POSITION variable as an iterator to traverse a list sequentially and as a bookmark to hold a place. A position is not the same as an index, however.

Element insertion is very fast at the list head, at the tail, and at a known POSITION. A sequential search is necessary to look up an element by value or index. This search can be slow if the list is long.

If you need a dump of individual elements in the list, you must set the depth of the dump context to 1 or greater.

Certain member functions of this class call global helper functions that must be customized for most uses of the CList class. See Collection Class Helpers in the "Macros and Globals" section.

For more information on using CList, see the article Collections.

Example

// CList is a template class that takes two template arguments.
// The first argument is type stored internally by the list, the
// second argument is the type used in the arguments for the
// CList methods.

// This code defines a list of ints.
CList<int, int> myIntList;

// This code defines a list of CStrings
CList<CString, CString &> myStringList;

// This code defines a list of MYTYPEs,
// NOTE: MYTYPE could be any struct, class or type definition
CList<MYTYPE, MYTYPE &> myTypeList;

Inheritance Hierarchy

CObject

CList

Requirements

Header: afxtempl.h

`CList::AddHead`

Adds a new element or list of elements to the head of this list.

POSITION AddHead(ARG_TYPE newElement);
void AddHead(CList* pNewList);

Parameters

ARG_TYPE
Template parameter specifying the type of the list element (can be a reference).

newElement
The new element.

pNewList
A pointer to another CList list. The elements in pNewList will be added to this list.

Return Value

The first version returns the POSITION value of the newly inserted element.

Remarks

The list can be empty before the operation.

Example

// Declarations of the variables used in the example
CList<CString, CString &> myList;
CList<CString, CString &> myList2;

// There are two versions of CList::AddHead: one adds a single
// element to the front of the list, the second adds another list
// to the front.

// This adds the string "ABC" to the front of myList.
// myList is a list of CStrings (ie defined as CList<CString,CString&>).
myList.AddHead(CString(_T("ABC")));

// This adds the elements of myList2 to the front of myList.
myList.AddHead(&myList2);

`CList::AddTail`

Adds a new element or list of elements to the tail of this list.

POSITION AddTail(ARG_TYPE newElement);
void AddTail(CList* pNewList);

Parameters

ARG_TYPE
Template parameter specifying the type of the list element (can be a reference).

newElement
The element to be added to this list.

pNewList
A pointer to another CList list. The elements in pNewList will be added to this list.

Return Value

The first version returns the POSITION value of the newly inserted element.

Remarks

The list can be empty before the operation.

Example

// Define myList and myList2.
CList<CString, CString &> myList;
CList<CString, CString &> myList2;

// Add elements to the end of myList and myList2.
myList.AddTail(CString(_T("A")));
myList.AddTail(CString(_T("B")));
myList2.AddTail(CString(_T("C")));
myList2.AddTail(CString(_T("D")));

// There are two versions of CList::AddTail: one adds a single
// element to the end of the list, the second adds another list
// to the end.

// This adds the string "ABC" to the end of myList.
// myList is a list of CStrings (ie defined as CList<CString,CString&>).
myList.AddTail(CString(_T("ABC")));
ASSERT(CString(_T("ABC")) == myList.GetTail());

// This adds the elements of myList2 to the end of myList.
myList.AddTail(&myList2);

`CList::CList`

Constructs an empty ordered list.

CList(INT_PTR nBlockSize = 10);

Parameters

nBlockSize
The memory-allocation granularity for extending the list.

Remarks

As the list grows, memory is allocated in units of nBlockSize entries.

Example

// This code defines myList as a list of strings
// such that memory gets allocated in chunks of
// 16 strings.
CList<CString, CString &> myList(16);

// This code defines myList2 as a list of ints
// such that memory gets allocated in chunks of
// 128 ints.
CList<int, int> myList2(128);

`CList::Find`

Searches the list sequentially to find the first element matching the specified searchValue.

POSITION Find(
    ARG_TYPE searchValue,
    POSITION startAfter = NULL) const;

Parameters

ARG_TYPE
Template parameter specifying the type of the list element (can be a reference).

searchValue
The value to be found in the list.

startAfter
The start position for the search. If no value is specified, the search begins with the head element.

Return Value

A POSITION value that can be used for iteration or object pointer retrieval; NULL if the object is not found.

Example

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddHead(CString(_T("XYZ")));
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Find a specific element.
POSITION pos = myList.Find(CString(_T("XYZ")));
ASSERT(CString(_T("XYZ")) == myList.GetAt(pos));

`CList::FindIndex`

Uses the value of nIndex as an index into the list.

POSITION FindIndex(INT_PTR nIndex) const;

Parameters

nIndex
The zero-based index of the list element to be found.

Return Value

A POSITION value that can be used for iteration or object pointer retrieval; NULL if nIndex is negative or too large.

Remarks

It starts a sequential scan from the head of the list, stopping on the nth element.

Example

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Verify the first element (index 0).
ASSERT(CString(_T("XYZ")) == myList.GetAt(myList.FindIndex(0)));

// Verify the third element (index 2).
ASSERT(CString(_T("123")) == myList.GetAt(myList.FindIndex(2)));

`CList::GetAt`

Gets the list element at a given position.

TYPE& GetAt(POSITION position);
const TYPE& GetAt(POSITION position) const;

Parameters

TYPE
Template parameter specifying the type of object in the list.

position
The position in the list of the element to get.

Return Value

See the return value description for GetHead.

Remarks

GetAt returns the element (or a reference to the element) associated with a given position. It is not the same as an index, and you cannot operate on a POSITION value yourself. A variable of type POSITION is a key for the list.

You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts.

Example

See the example for CList::GetHeadPosition.

`CList::GetCount`

Gets the number of elements in this list.

INT_PTR GetCount() const;

Return Value

An integer value containing the element count.

Remarks

Calling this method will generate the same result as the CList::GetSize method.

Example

See the example for CList::RemoveHead.

`CList::GetHead`

Gets the head element (or a reference to the head element) of this list.

const TYPE& GetHead() const;

TYPE& GetHead();

Parameters

TYPE
Template parameter specifying the type of object in the list.

Return Value

If the list is const, GetHead returns a copy of the element at the head of the list. This allows the function 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 function to be used on either side of an assignment statement and thus allows the list entries to be modified.

Remarks

You must ensure that the list is not empty before calling GetHead. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use IsEmpty to verify that the list contains elements.

Example

// Define myList.
CList<CString, CString &> myList;

// Add an element to the front of the list.
myList.AddHead(CString(_T("ABC")));

// Verify the element was added to the front of the list.
ASSERT(CString(_T("ABC")) == myList.GetHead());

`CList::GetHeadPosition`

Gets the position of the head element of this list.

POSITION GetHeadPosition() const;

Return Value

A POSITION value that can be used for iteration or object pointer retrieval; NULL if the list is empty.

Example

// Define myList.
CList<CString, CString &> myList;

// Add an element to the front of the list.
myList.AddHead(CString(_T("ABC")));

// Verify the element at the head position
// is the one added.
POSITION pos = myList.GetHeadPosition();
ASSERT(CString(_T("ABC")) == myList.GetAt(pos));

`CList::GetNext`

Gets the list element identified by rPosition, then sets rPosition to the POSITION value of the next entry in the list.

TYPE& GetNext(POSITION& rPosition);
const TYPE& GetNext(POSITION& rPosition) const;

Parameters

TYPE
Template parameter specifying the type of the elements in the list.

rPosition
A reference to a POSITION value returned by a previous GetNext, GetHeadPosition, or other member function call.

Return Value

If the list is const, GetNext returns a copy of an element of the list. This allows the function 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 an element of the list. This allows the function to be used on either side of an assignment statement and thus allows the list entries to be modified.

Remarks

You can use GetNext in a forward iteration loop if you establish the initial position with a call to GetHeadPosition or Find.

You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts.

If the retrieved element is the last in the list, then the new value of rPosition is set to NULL.

Example

// Define myList.
// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Dump the list elements to the debug window.
POSITION pos = myList.GetHeadPosition();
for (int i = 0; i < myList.GetCount(); i++)
{
   TRACE(_T("%s\r\n"), (LPCTSTR)myList.GetNext(pos));
}

`CList::GetPrev`

Gets the list element identified by rPosition, then sets rPosition to the POSITION value of the previous entry in the list.

TYPE& GetPrev(POSITION& rPosition);
const TYPE& GetPrev(POSITION& rPosition) const;

Parameters

TYPE
Template parameter specifying the type of the elements in the list.

rPosition
A reference to a POSITION value returned by a previous GetPrev or other member function call.

Return Value

If the list is const, GetPrev returns a copy of the element at the head of the list. This allows the function 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 function to be used on either side of an assignment statement and thus allows the list entries to be modified.

Remarks

You can use GetPrev in a reverse iteration loop if you establish the initial position with a call to GetTailPosition or Find.

You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts.

If the retrieved element is the first in the list, then the new value of rPosition is set to NULL.

Example

// Define myList.
CList<CString,CString&> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Dump the list elements to the debug window,
// in reverse order.
POSITION pos = myList.GetTailPosition();
for (int i = 0; i < myList.GetCount(); i++)
{
   TRACE(_T("%s\r\n"), (LPCTSTR)myList.GetPrev(pos));
}

`CList::GetSize`

Returns the number of list elements.

INT_PTR GetSize() const;

Return Value

The number of items in the list.

Remarks

Call this method to retrieve the number of elements in the list. Calling this method will generate the same result as the CList::GetCount method.

Example

// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Remove the head element and verify the list.
// NOTE: once the head is removed, the number of
// elements in the list will be one.
CString strHead = myList.RemoveHead();
ASSERT((CString(_T("123")) == strHead) && (myList.GetSize() == 1) &&
       (CString(_T("ABC")) == myList.GetHead()));

`CList::GetTail`

Gets the CObject pointer that represents the tail element of this list.

TYPE& GetTail();
const TYPE& GetTail() const;

Parameters

TYPE
Template parameter specifying the type of elements in the list.

Return Value

See the return value description for GetHead.

Remarks

You must ensure that the list is not empty before calling GetTail. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use IsEmpty to verify that the list contains elements.

Example

// Define myList.
CList<CString, CString &> myList;

// Add an element to the end of the list.
myList.AddTail(CString(_T("ABC")));

// Verify the element was added to the end of the list.
ASSERT(CString(_T("ABC")) == myList.GetTail());

`CList::GetTailPosition`

Gets the position of the tail element of this list; NULL if the list is empty.

POSITION GetTailPosition() const;

Return Value

A POSITION value that can be used for iteration or object pointer retrieval; NULL if the list is empty.

Example

// Define myList.
CList<CString,CString&> myList;

// Add an element to the end of the list.
myList.AddTail(CString(_T("ABC")));

// Verify the element at the end position
// is the one added.
POSITION pos = myList.GetTailPosition();
ASSERT(CString(_T("ABC")) == myList.GetAt(pos));

`CList::InsertAfter`

Adds an element to this list after the element at the specified position.

POSITION InsertAfter(POSITION position, ARG_TYPE newElement);

Parameters

position
A POSITION value returned by a previous GetNext, GetPrev, or Find member function call.

ARG_TYPE
Template parameter specifying the type of the list element.

newElement
The element to be added to this list.

Return Value

A POSITION value that can be used for iteration or list element retrieval.

Example

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
POSITION pos = myList.AddHead(CString(_T("XYZ")));
pos = myList.InsertAfter(pos, CString(_T("ABC")));
pos = myList.InsertAfter(pos, CString(_T("123")));

// Verify the tail element is what's expected.
ASSERT(CString(_T("123")) == myList.GetTail());

`CList::InsertBefore`

Adds an element to this list before the element at the specified position.

POSITION InsertBefore(POSITION position, ARG_TYPE newElement);

Parameters

position
A POSITION value returned by a previous GetNext, GetPrev, or Find member function call.

ARG_TYPE
Template parameter specifying the type of the list element (can be a reference).

newElement
The element to be added to this list.

Return Value

A POSITION value that can be used for iteration or list element retrieval.

Remarks

If position is NULL, the element is inserted at the head of the list.

Example

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
POSITION pos = myList.AddHead(CString(_T("XYZ")));
pos = myList.InsertBefore(pos, CString(_T("ABC")));
pos = myList.InsertBefore(pos, CString(_T("123")));

// Verify the head element is what's expected.
ASSERT(CString(_T("123")) == myList.GetHead());

`CList::IsEmpty`

Indicates whether this list contains no elements.

BOOL IsEmpty() const;

Return Value

Nonzero if this list is empty; otherwise 0.

Example

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove the head element until the list is empty.
CString str;
while (!myList.IsEmpty())
{
   str = myList.RemoveHead();
   TRACE(_T("%s\r\n"), (LPCTSTR)str);
}

`CList::RemoveAll`

Removes all the elements from this list and frees the associated memory.

void RemoveAll();

Remarks

No error is generated if the list is already empty.

Example

// Define myList.
CList<CString, CString&> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove all of the elements in the list.
myList.RemoveAll();

// Verify the list is empty.
ASSERT(myList.IsEmpty());

`CList::RemoveAt`

Removes the specified element from this list.

void RemoveAt(POSITION position);

Parameters

position
The position of the element to be removed from the list.

Remarks

You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts.

Example

// Define myList.
CList<CString, CString&> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove CString("ABC") from the list.
myList.RemoveAt(myList.FindIndex(1));

// Verify CString("ABC") is not in the list.
ASSERT(myList.Find(CString(_T("ABC"))) == NULL);

`CList::RemoveHead`

Removes the element from the head of the list and returns a pointer to it.

TYPE RemoveHead();

Parameters

TYPE
Template parameter specifying the type of elements in the list.

Return Value

The element previously at the head of the list.

Remarks

You must ensure that the list is not empty before calling RemoveHead. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use IsEmpty to verify that the list contains elements.

Example

// Define myList.
CList<CString, CString&> myList;

// Add two elements to the list.
myList.AddHead(CString(_T("ABC")));
myList.AddHead(CString(_T("123")));

// Remove the head element and verify the list.
// NOTE: once the head is removed, the number of
// elements in the list will be one.
CString strHead = myList.RemoveHead();
ASSERT((CString(_T("123")) == strHead) && (myList.GetCount() == 1) &&
(CString(_T("ABC")) == myList.GetHead()));

`CList::RemoveTail`

Removes the element from the tail of the list and returns a pointer to it.

TYPE RemoveTail();

Parameters

TYPE
Template parameter specifying the type of elements in the list.

Return Value

The element that was at the tail of the list.

Remarks

You must ensure that the list is not empty before calling RemoveTail. If the list is empty, then the Debug version of the Microsoft Foundation Class Library asserts. Use IsEmpty to verify that the list contains elements.

Example

// Define myList.
CList<CString, CString &> myList;

// Add two elements to the list.
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Remove the tail element and verify the list.
// NOTE: once the tail is removed, the number of
// elements in the list will be one.
CString strTail = myList.RemoveTail();
ASSERT((CString(_T("123")) == strTail) && (myList.GetCount() == 1) &&
       (CString(_T("ABC")) == myList.GetTail()));

`CList::SetAt`

A variable of type POSITION is a key for the list.

void SetAt(POSITION pos, ARG_TYPE newElement);

Parameters

pos
The POSITION of the element to be set.

ARG_TYPE
Template parameter specifying the type of the list element (can be a reference).

newElement
The element to be added to the list.

Remarks

It is not the same as an index, and you cannot operate on a POSITION value yourself. SetAt writes the element to the specified position in the list.

You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts.

Example

// Define myList.
CList<CString, CString &> myList;

// Add three elements to the list.
myList.AddTail(CString(_T("XYZ")));
myList.AddTail(CString(_T("ABC")));
myList.AddTail(CString(_T("123")));

// Replace CString("ABC") with CString("CBA")
POSITION pos = myList.Find(CString(_T("ABC")));
myList.SetAt(pos, CString(_T("CBA")));

// Verify CString("ABC") is not in the list.
ASSERT(myList.Find(CString(_T("ABC"))) == NULL);

Share via

CList Class

Syntax

Members

Public Constructors

Public Methods

Parameters

Remarks

Example

Inheritance Hierarchy

Requirements

CList::AddHead

Parameters

Return Value

Remarks

Example

CList::AddTail

Parameters

Return Value

Remarks

Example

CList::CList

Parameters

Remarks

Example

CList::Find

Parameters

Return Value

Example

CList::FindIndex

Parameters

Return Value

Remarks

Example

CList::GetAt

Parameters

Return Value

Remarks

Example

CList::GetCount

Return Value

Remarks

Example

CList::GetHead

Parameters

Return Value

Remarks

Example

CList::GetHeadPosition

Return Value

Example

CList::GetNext

Parameters

Return Value

Remarks

Example

CList::GetPrev

Parameters

Return Value

Remarks

Example

CList::GetSize

Return Value

Remarks

Example

CList::GetTail

Parameters

Return Value

Remarks

Example

CList::GetTailPosition

Return Value

Example

CList::InsertAfter

Parameters

Return Value

Example

CList::InsertBefore

Parameters

Return Value

`CList` Class

`CList::AddHead`

`CList::AddTail`

`CList::CList`

`CList::Find`

`CList::FindIndex`

`CList::GetAt`

`CList::GetCount`

`CList::GetHead`

`CList::GetHeadPosition`

`CList::GetNext`

`CList::GetPrev`

`CList::GetSize`

`CList::GetTail`

`CList::GetTailPosition`

`CList::InsertAfter`

`CList::InsertBefore`

`CList::IsEmpty`

`CList::RemoveAll`

`CList::RemoveAt`

`CList::RemoveHead`

`CList::RemoveTail`

`CList::SetAt`