Skip to content

Files

Latest commit

mikeblomeColin Robertson
mikeblome
and
Colin Robertson
merging recent PRs into live (MicrosoftDocs#398)
Oct 20, 2017
fa0eef7 · Oct 20, 2017

History

History
789 lines (539 loc) · 33.3 KB

coblist-class.md

File metadata and controls

789 lines (539 loc) · 33.3 KB
title ms.custom ms.date ms.reviewer ms.suite ms.technology ms.tgt_pltfrm ms.topic f1_keywords dev_langs helpviewer_keywords ms.assetid caps.latest.revision author ms.author manager
CObList Class | Microsoft Docs
11/04/2016
cpp-windows
reference
CObList
AFXCOLL/CObList
AFXCOLL/CObList::CObList
AFXCOLL/CObList::AddHead
AFXCOLL/CObList::AddTail
AFXCOLL/CObList::Find
AFXCOLL/CObList::FindIndex
AFXCOLL/CObList::GetAt
AFXCOLL/CObList::GetCount
AFXCOLL/CObList::GetHead
AFXCOLL/CObList::GetHeadPosition
AFXCOLL/CObList::GetNext
AFXCOLL/CObList::GetPrev
AFXCOLL/CObList::GetSize
AFXCOLL/CObList::GetTail
AFXCOLL/CObList::GetTailPosition
AFXCOLL/CObList::InsertAfter
AFXCOLL/CObList::InsertBefore
AFXCOLL/CObList::IsEmpty
AFXCOLL/CObList::RemoveAll
AFXCOLL/CObList::RemoveAt
AFXCOLL/CObList::RemoveHead
AFXCOLL/CObList::RemoveTail
AFXCOLL/CObList::SetAt
C++
CObList [MFC], CObList
CObList [MFC], AddHead
CObList [MFC], AddTail
CObList [MFC], Find
CObList [MFC], FindIndex
CObList [MFC], GetAt
CObList [MFC], GetCount
CObList [MFC], GetHead
CObList [MFC], GetHeadPosition
CObList [MFC], GetNext
CObList [MFC], GetPrev
CObList [MFC], GetSize
CObList [MFC], GetTail
CObList [MFC], GetTailPosition
CObList [MFC], InsertAfter
CObList [MFC], InsertBefore
CObList [MFC], IsEmpty
CObList [MFC], RemoveAll
CObList [MFC], RemoveAt
CObList [MFC], RemoveHead
CObList [MFC], RemoveTail
CObList [MFC], SetAt
80699c93-33d8-4f8b-b8cf-7b58aeab64ca
20
mikeblome
mblome
ghogen

CObList Class

fSupports ordered lists of nonunique CObject pointers accessible sequentially or by pointer value.

Syntax

class CObList : public CObject

Members

Public Constructors

Name Description
CObList::CObList Constructs an empty list for CObject pointers.

Public Methods

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

Remarks

CObList lists behave like doubly-linked lists.

A variable of type POSITION is a key for the list. You can use a POSITION variable both 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.

CObList incorporates the IMPLEMENT_SERIAL macro to support serialization and dumping of its elements. If a list of CObject pointers is stored to an archive, either with an overloaded insertion operator or with the Serialize member function, each CObject element is serialized in turn.

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

When a CObList object is deleted, or when its elements are removed, only the CObject pointers are removed, not the objects they reference.

You can derive your own classes from CObList. Your new list class, designed to hold pointers to objects derived from CObject, adds new data members and new member functions. Note that the resulting list is not strictly type safe, because it allows insertion of any CObject pointer.

Note

You must use the IMPLEMENT_SERIAL macro in the implementation of your derived class if you intend to serialize the list.

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

Inheritance Hierarchy

CObject

CObList

Requirements

Header: afxcoll.h

CObList::AddHead

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

POSITION AddHead(CObject* newElement);  
void AddHead(CObList* pNewList);

Parameters

newElement
The CObject pointer to be added to this list.

pNewList
A pointer to another CObList 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.

The following table shows other member functions that are similar to CObList::AddHead.

Class Member Function
CPtrList POSITION AddHead( void* newElement );

void AddHead( CPtrList* pNewList );
CStringList POSITION AddHead(const CString& newElement );

POSITION AddHead(LPCTSTR newElement );

void AddHead(CStringList* pNewList );

Remarks

The list can be empty before the operation.

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#89]

The results from this program are as follows:

AddHead example: A CObList with 2 elements

a CAge at $44A8 40

a CAge at $442A 21

CObList::AddTail

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

POSITION AddTail(CObject* newElement);  
void AddTail(CObList* pNewList);

Parameters

newElement
The CObject pointer to be added to this list.

pNewList
A pointer to another CObList 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.

The following table shows other member functions that are similar to CObList::AddTail.

Class Member Function
CPtrList POSITION AddTail( void* newElement );

void AddTail( CPtrList* pNewList );
CStringList POSITION AddTail( const CString& newElement );

POSITION AddTail( LPCTSTR newElement );

void AddTail( CStringList* pNewList );

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#90]

The results from this program are as follows:

AddTail example: A CObList with 2 elements

a CAge at $444A 21

a CAge at $4526 40

CObList::CObList

Constructs an empty CObject pointer list.

CObList(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. If a memory allocation fails, a CMemoryException is thrown.

The following table shows other member functions that are similar to CObList::CObList.

Class Member Function
CPtrList CPtrList( INT_PTR nBlockSize = 10 );
CStringList CStringList( INT_PTR nBlockSize = 10 );

Example

Below is a listing of the CObject-derived class CAge used in all the collection examples:

[!code-cppNVC_MFCCollections#91]

Below is an example of CObList constructor usage:

[!code-cppNVC_MFCCollections#92]

CObList::Find

Searches the list sequentially to find the first CObject pointer matching the specified CObject pointer.

POSITION Find(
    CObject* searchValue,  
    POSITION startAfter = NULL) const;

Parameters

searchValue
The object pointer to be found in this list.

startAfter
The start position for the search.

Return Value

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

Remarks

Note that the pointer values are compared, not the contents of the objects.

The following table shows other member functions that are similar to CObList::Find.

Class Member Function
CPtrList POSITION Find( void* searchValue , POSITION startAfter = NULL ) const;
CStringList POSITION Find( LPCTSTR searchValue , POSITION startAfter = NULL ) const;

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#93]

CObList::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 too large. (The framework generates an assertion if nIndex is negative.)

Remarks

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

The following table shows other member functions that are similar to CObList::FindIndex.

Class Member Function
CPtrList POSITION FindIndex( INT_PTR nIndex ) const;
CStringList POSITION FindIndex( INT_PTR nIndex ) const;

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#94]

CObList::GetAt

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

CObject*& GetAt(POSITION position);  
const CObject*& GetAt(POSITION position) const;

Parameters

position
A POSITION value returned by a previous GetHeadPosition or Find member function call.

Return Value

See the return value description for GetHead.

Remarks

It is not the same as an index, and you cannot operate on a POSITION value yourself. GetAt retrieves the CObject pointer associated with a given position.

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.

The following table shows other member functions that are similar to CObList::GetAt.

Class Member Function
CPtrList const void*& GetAt( POSITION position ) const;

void*& GetAt( POSITION position );
CStringList const CString& GetAt( POSITION position ) const;

CString& GetAt( POSITION position );

Example

See the example for FindIndex.

CObList::GetCount

Gets the number of elements in this list.

INT_PTR GetCount() const;

Return Value

An integer value containing the element count.

The following table shows other member functions that are similar to CObList::GetCount.

Class Member Function
CPtrList INT_PTR GetCount( ) const;
CStringList INT_PTR GetCount( ) const;

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#95]

CObList::GetHead

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

CObject*& GetHead();  
const CObject*& GetHead() const;

Return Value

If the list is accessed through a pointer to a const CObList, then GetHead returns a CObject pointer. This allows the function to be used only on the right side of an assignment statement and thus protects the list from modification.

If the list is accessed directly or through a pointer to a CObList, then GetHead returns a reference to a CObject pointer. 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.

The following table shows other member functions that are similar to CObList::GetHead.

Class Member Function
CPtrList const void*& GetHead( ) const; void*& GetHead( );
CStringList const CString& GetHead( ) const; CString& GetHead( );

Example

See CObList::CObList for a listing of the CAge class.

The following example illustrates the use of GetHead on the left side of an assignment statement.

[!code-cppNVC_MFCCollections#96]

CObList::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.

The following table shows other member functions that are similar to CObList::GetHeadPosition.

Class Member Function
CPtrList POSITION GetHeadPosition( ) const;
CStringList POSITION GetHeadPosition( ) const;

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#97]

CObList::GetNext

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

CObject*& GetNext(POSITION& rPosition);  
const CObject* GetNext(POSITION& rPosition) const;

Parameters

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

Return Value

See the return value description for GetHead.

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.

It is possible to remove an element during an iteration. See the example for RemoveAt.

Note

As of MFC 8.0 the const version of this method has changed to return const CObject* instead of const CObject*&. This change was made to bring the compiler into conformance with the C++ standard.

The following table shows other member functions that are similar to CObList::GetNext.

Class Member Function
CPtrList void*& GetNext( POSITION& rPosition );

const void* GetNext( POSITION& rPosition ) const;
CStringList CString& GetNext( POSITION& rPosition );

const CString& GetNext( POSITION& rPosition ) const;

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#98]

The results from this program are as follows:

a CAge at $479C 40

a CAge at $46C0 21

CObList::GetPrev

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

CObject*& GetPrev(POSITION& rPosition);  
const CObject* GetPrev(POSITION& rPosition) const;

Parameters

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

Return Value

See the return value description for GetHead.

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.

Note

As of MFC 8.0 the const version of this method has changed to return const CObject* instead of const CObject*&. This change was made to bring the compiler into conformance with the C++ standard.

The following table shows other member functions that are similar to CObList::GetPrev.

Class Member Function
CPtrList void*& GetPrev( POSITION& rPosition );

const void* GetPrev( POSITION& rPosition ) const;
CStringList CString& GetPrev( POSITION& rPosition );

const CString& GetPrev( POSITION& rPosition ) const;

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#99]

The results from this program are as follows:

a CAge at $421C 21

a CAge at $421C 40

CObList::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.

The following table shows other member functions that are similar to CObList::GetSize.

Class Member Function
CPtrList INT_PTR GetSize( ) const;
CStringList INT_PTR GetSize( ) const;

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#100]

CObList::GetTail

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

CObject*& GetTail();  
const CObject*& GetTail() const;

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.

The following table shows other member functions that are similar to CObList::GetTail.

Class Member Function
CPtrList const void*& GetTail( ) const; void*& GetTail( );
CStringList const CString& GetTail( ) const; CString& GetTail( );

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#101]

CObList::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.

The following table shows other member functions that are similar to CObList::GetTailPosition.

Class Member Function
CPtrList POSITION GetTailPosition( ) const;
CStringList POSITION GetTailPosition( ) const;

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#102]

CObList::InsertAfter

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

POSITION InsertAfter(
    POSITION position,  
    CObject* newElement);

Parameters

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

newElement
The object pointer to be added to this list.

The following table shows other member functions that are similar to CObList::InsertAfter.

Class Member Function
CPtrList POSITION InsertAfter( POSITION position , void* newElement );
CStringList POSITION InsertAfter( POSITION position , const CString& newElement );

POSITION InsertAfter( POSITION position , LPCTSTR newElement );

Return Value

A POSITION value which is the same as the position parameter.

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#103]

The results from this program are as follows:

InsertAfter example: A CObList with 3 elements

a CAge at $4A44 40

a CAge at $4A64 65

a CAge at $4968 21

CObList::InsertBefore

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

POSITION InsertBefore(
    POSITION position,  
    CObject* newElement);

Parameters

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

newElement
The object pointer to be added to this list.

Return Value

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

The following table shows other member functions that are similar to CObList::InsertBefore.

Class Member Function
CPtrList POSITION InsertBefore( POSITION position , void* newElement );
CStringList POSITION InsertBefore( POSITION position , const CString& newElement );

POSITION InsertBefore( POSITION position , LPCTSTR newElement );

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#104]

The results from this program are as follows:

InsertBefore example: A CObList with 3 elements

a CAge at $4AE2 40

a CAge at $4B02 65

a CAge at $49E6 21

CObList::IsEmpty

Indicates whether this list contains no elements.

BOOL IsEmpty() const;

Return Value

Nonzero if this list is empty; otherwise 0.

The following table shows other member functions that are similar to CObList::IsEmpty.

Class Member Function
CPtrList BOOL IsEmpty( ) const;
CStringList BOOL IsEmpty( ) const;

Example

See the example for RemoveAll.

CObList::RemoveAll

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

void RemoveAll();

Remarks

No error is generated if the list is already empty.

When you remove elements from a CObList, you remove the object pointers from the list. It is your responsibility to delete the objects themselves.

The following table shows other member functions that are similar to CObList::RemoveAll.

Class Member Function
CPtrList void RemoveAll( );
CStringList void RemoveAll( );

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#105]

CObList::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

When you remove an element from a CObList, you remove the object pointer from the list. It is your responsibility to delete the objects themselves.

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.

The following table shows other member functions that are similar to CObList::RemoveAt.

Class Member Function
CPtrList void RemoveAt( POSITION position );
CStringList void RemoveAt( POSITION position );

Example

Be careful when removing an element during a list iteration. The following example shows a removal technique that guarantees a valid POSITION value for GetNext.

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#106]

The results from this program are as follows:

RemoveAt example: A CObList with 2 elements

a CAge at $4C1E 65

a CAge at $4B22 21

CObList::RemoveHead

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

CObject* RemoveHead();

Return Value

The CObject pointer 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.

The following table shows other member functions that are similar to CObList::RemoveHead.

Class Member Function
CPtrList void* RemoveHead( );
CStringList CString RemoveHead( );

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#107]

CObList::RemoveTail

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

CObject* RemoveTail();

Return Value

A pointer to the object 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.

The following table shows other member functions that are similar to CObList::RemoveTail.

Class Member Function
CPtrList void* RemoveTail( );
CStringList CString RemoveTail( );

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#108]

CObList::SetAt

Sets the element at a given position.

void SetAt(
    POSITION pos,  
    CObject* newElement);

Parameters

pos
The POSITION of the element to be set.

newElement
The CObject pointer to be written to the list.

Remarks

A variable of type POSITION is a key for the list. It is not the same as an index, and you cannot operate on a POSITION value yourself. SetAt writes the CObject pointer 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.

The following table shows other member functions that are similar to CObList::SetAt.

Class Member Function
CPtrList void SetAt( POSITION pos , const CString& newElement );
CStringList void SetAt( POSITION pos , LPCTSTR newElement );

Example

See CObList::CObList for a listing of the CAge class.

[!code-cppNVC_MFCCollections#109]

The results from this program are as follows:

SetAt example: A CObList with 2 elements

a CAge at $4D98 40

a CAge at $4DB8 65

See Also

CObject Class
Hierarchy Chart
CStringList Class
CPtrList Class