Rediger

Del via

CList Class

  • Artikkel

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

See also

MFC Sample COLLECT
CObject Class
Hierarchy Chart
CMap Class
CArray Class