Skip to content

Latest commit

 

History

History
653 lines (389 loc) · 19.9 KB

clist-class.md

File metadata and controls

653 lines (389 loc) · 19.9 KB
Raw
description title ms.date f1_keywords helpviewer_keywords ms.assetid
Learn more about: CList Class
CList Class
11/04/2016
CList
AFXTEMPL/CList
AFXTEMPL/CList::CList
AFXTEMPL/CList::AddHead
AFXTEMPL/CList::AddTail
AFXTEMPL/CList::Find
AFXTEMPL/CList::FindIndex
AFXTEMPL/CList::GetAt
AFXTEMPL/CList::GetCount
AFXTEMPL/CList::GetHead
AFXTEMPL/CList::GetHeadPosition
AFXTEMPL/CList::GetNext
AFXTEMPL/CList::GetPrev
AFXTEMPL/CList::GetSize
AFXTEMPL/CList::GetTail
AFXTEMPL/CList::GetTailPosition
AFXTEMPL/CList::InsertAfter
AFXTEMPL/CList::InsertBefore
AFXTEMPL/CList::IsEmpty
AFXTEMPL/CList::RemoveAll
AFXTEMPL/CList::RemoveAt
AFXTEMPL/CList::RemoveHead
AFXTEMPL/CList::RemoveTail
AFXTEMPL/CList::SetAt
CList [MFC], CList
CList [MFC], AddHead
CList [MFC], AddTail
CList [MFC], Find
CList [MFC], FindIndex
CList [MFC], GetAt
CList [MFC], GetCount
CList [MFC], GetHead
CList [MFC], GetHeadPosition
CList [MFC], GetNext
CList [MFC], GetPrev
CList [MFC], GetSize
CList [MFC], GetTail
CList [MFC], GetTailPosition
CList [MFC], InsertAfter
CList [MFC], InsertBefore
CList [MFC], IsEmpty
CList [MFC], RemoveAll
CList [MFC], RemoveAt
CList [MFC], RemoveHead
CList [MFC], RemoveTail
CList [MFC], SetAt
6f6273c3-c8f6-47f5-ac2a-0a950379ae5d

CList Class

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

[!code-cppNVC_MFCCollections#35]

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

[!code-cppNVC_MFCCollections#36]

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

[!code-cppNVC_MFCCollections#37]

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

[!code-cppNVC_MFCCollections#38]

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

[!code-cppNVC_MFCCollections#39]

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

[!code-cppNVC_MFCCollections#40]

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

[!code-cppNVC_MFCCollections#41]

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

[!code-cppNVC_MFCCollections#42]

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

[!code-cppNVC_MFCCollections#43]

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

[!code-cppNVC_MFCCollections#44]

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

[!code-cppNVC_MFCCollections#45]

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

[!code-cppNVC_MFCCollections#46]

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

[!code-cppNVC_MFCCollections#47]

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

[!code-cppNVC_MFCCollections#48]

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

[!code-cppNVC_MFCCollections#49]

CList::IsEmpty

Indicates whether this list contains no elements.

BOOL IsEmpty() const;

Return Value

Nonzero if this list is empty; otherwise 0.

Example

[!code-cppNVC_MFCCollections#50]

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

[!code-cppNVC_MFCCollections#51]

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

[!code-cppNVC_MFCCollections#52]

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

[!code-cppNVC_MFCCollections#53]

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

[!code-cppNVC_MFCCollections#54]

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

[!code-cppNVC_MFCCollections#55]

See also

MFC Sample COLLECT
CObject Class
Hierarchy Chart
CMap Class
CArray Class