CObList Class

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at 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]--brokenlink--(../Topic/not%20found.md#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](../Topic/CPtrList%20Class.md)|**POSITION AddHead( void\*** `newElement` **);**<br /><br /> **void AddHead( CPtrList\*** `pNewList` **);**|  
|[CStringList](../Topic/CStringList%20Class.md)|**POSITION AddHead(const CString&** `newElement` **);**<br /><br /> **POSITION AddHead(LPCTSTR** `newElement` **);**<br /><br /> **void AddHead(CStringList\*** `pNewList` **);**|  
  
### Remarks  
 The list can be empty before the operation.  
  
### Example  
  See [CObList::CObList](#coblist__coblist) for a listing of the `CAge` class.  
  
 [!CODE [NVC_MFCCollections#89](../CodeSnippet/VS_Snippets_Cpp/NVC_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`  
  
##  <a name="coblist__addtail"></a>  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.

         CObList list;
         list.AddTail(new CAge(21));
         list.AddTail(new CAge(40)); // List now contains (21, 40).
         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("AddTail example: ") << &list << _T("\n");
         #endif

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:

// Simple CObject-derived class for CObList and other examples
class CAge : public CObject
{
    DECLARE_SERIAL( CAge )
private:
    int   m_years;
public:
    CAge() { m_years = 0; }
    CAge(int age) { m_years = age; }
    CAge(const CAge& a) { m_years = a.m_years; } // Copy constructor
    void Serialize(CArchive& ar);
    void AssertValid() const;
    const CAge& operator=(const CAge& a)
    {
        m_years = a.m_years; return *this;
    }
    BOOL operator==(CAge a)
    {
        return m_years == a.m_years;
    }
#ifdef _DEBUG
    void Dump(CDumpContext& dc) const
    {
        CObject::Dump(dc);
        dc << m_years; 
    }
#endif
};

Below is an example of CObList constructor usage:

         CObList list(20);  // List on the stack with blocksize = 20.

         CObList* plist = new CObList; // List on the heap with default 
                                       // blocksize.

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.

         CObList list;
         CAge* pa1;
         CAge* pa2;
         POSITION pos;
         list.AddHead(pa1 = new CAge(21));
         list.AddHead(pa2 = new CAge(40));    // List now contains (40, 21).
         if ((pos = list.Find(pa1)) != NULL) // Hunt for pa1
         {                                  // starting at head by default.
             ASSERT(*(CAge*) list.GetAt(pos) == CAge(21));
         }

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.

         CObList list;
         POSITION pos;

         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         if ((pos = list.FindIndex(0)) != NULL)
         {
             ASSERT(*(CAge*) list.GetAt(pos) == CAge(40));
         }

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.

         CObList list;

         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         ASSERT(list.GetCount() == 2);

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.

         const CObList* cplist;

         CObList* plist = new CObList;
         CAge* page1 = new CAge(21);
         CAge* page2 = new CAge(30);
         CAge* page3 = new CAge(40);
         plist->AddHead(page1);
         plist->AddHead(page2);  // List now contains (30, 21).
         // The following statement REPLACES the head element.
         plist->GetHead() = page3; // List now contains (40, 21).
         ASSERT(*(CAge*) plist->GetHead() == CAge(40));
         cplist = plist;  // cplist is a pointer to a const list.
         // cplist->GetHead() = page3; // Error: can't assign a pointer to a const list
         ASSERT(*(CAge*) plist->GetHead() == CAge(40)); // OK

         delete page1;
         delete page2;
         delete page3;
         delete plist; // Cleans up memory.

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.

         CObList list;
         POSITION pos;

         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         if ((pos = list.GetHeadPosition()) != NULL)
         {
             ASSERT(*(CAge*) list.GetAt(pos) == CAge(40));
         }

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.

         CObList list;
         POSITION pos;
         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         // Iterate through the list in head-to-tail order.
         #ifdef _DEBUG
            for (pos = list.GetHeadPosition(); pos != NULL;)
            {
               afxDump << list.GetNext(pos) << _T("\n");
            }
         #endif

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.

         CObList list;
         POSITION pos;

         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         // Iterate through the list in tail-to-head order.
         for (pos = list.GetTailPosition(); pos != NULL;)
         {
         #ifdef _DEBUG
             afxDump << list.GetPrev(pos) << _T("\n");
         #endif
         }

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.

         CObList list;

         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         ASSERT(list.GetSize() == 2);

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.

         CObList list;

         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         ASSERT(*(CAge*) list.GetTail() == CAge(21));

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.

         CObList list;
         POSITION pos;

         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         if ((pos = list.GetTailPosition()) != NULL)
         {
             ASSERT(*(CAge*) list.GetAt(pos) == CAge(21));
         }

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.

         CObList list;
         POSITION pos1, pos2;
         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         if ((pos1 = list.GetHeadPosition()) != NULL)
         {
             pos2 = list.InsertAfter(pos1, new CAge(65));
         }
         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("InsertAfter example: ") << &list << _T("\n");
         #endif

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.

         CObList list;
         POSITION pos1, pos2;
         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         if ((pos1 = list.GetTailPosition()) != NULL)
         {
             pos2 = list.InsertBefore(pos1, new CAge(65));
         }
         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("InsertBefore example: ") << &list << _T("\n");
         #endif

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.

         CObList list;
         CAge* pa1;
         CAge* pa2;
         ASSERT(list.IsEmpty()); // Yes it is.
         list.AddHead(pa1 = new CAge(21));
         list.AddHead(pa2 = new CAge(40)); // List now contains (40, 21).
         ASSERT(!list.IsEmpty()); // No it isn't.
         list.RemoveAll(); // CAges aren't destroyed.
         ASSERT(list.IsEmpty()); // Yes it is.
         delete pa1;     // Now delete the CAge objects.
         delete pa2;

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.

         CObList list;
         POSITION pos1, pos2;
         CObject* pa;
         
         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40));
         list.AddHead(new CAge(65)); // List now contains (65 40, 21).
         for (pos1 = list.GetHeadPosition(); (pos2 = pos1) != NULL;)
         {
             if (*(CAge*) list.GetNext(pos1) == CAge(40))
             {
                 pa = list.GetAt(pos2); // Save the old pointer for
                                        //deletion.
                 list.RemoveAt(pos2);
                 delete pa; // Deletion avoids memory leak.
             }
         }
         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("RemoveAt example: ") << &list << _T("\n");
         #endif

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.

         CObList list;
         CAge* pa1;
         CAge* pa2;

         list.AddHead(pa1 = new CAge(21));
         list.AddHead(pa2 = new CAge(40)); // List now contains (40, 21).
         ASSERT(*(CAge*) list.RemoveHead() == CAge(40));  // Old head
         ASSERT(*(CAge*) list.GetHead() == CAge(21));  // New head
         delete pa1;
         delete pa2;

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.

         CObList list;
         CAge* pa1;
         CAge* pa2;

         list.AddHead(pa1 = new CAge(21));
         list.AddHead(pa2 = new CAge(40)); // List now contains (40, 21).
         ASSERT(*(CAge*) list.RemoveTail() == CAge(21));  // Old tail
         ASSERT(*(CAge*) list.GetTail() == CAge(40));  // New tail
         delete pa1;
         delete pa2; // Clean up memory.

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.

         CObList list;
         CObject* pa;
         POSITION pos;
         
         list.AddHead(new CAge(21));
         list.AddHead(new CAge(40)); // List now contains (40, 21).
         if ((pos = list.GetTailPosition()) != NULL)
         {
             pa = list.GetAt(pos); // Save the old pointer for 
                                   //deletion.
             list.SetAt(pos, new CAge(65));  // Replace the tail 
                                               //element.
             delete pa;  // Deletion avoids memory leak.
         }
         #ifdef _DEBUG
            afxDump.SetDepth(1);
            afxDump << _T("SetAt example: ") << &list << _T("\n");
         #endif

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

Share via

CObList Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CObList::AddHead

Parameters

Return Value

Remarks

Example

CObList::CObList

Parameters

Remarks

Example

CObList::Find

Parameters

Return Value

Remarks

Example

CObList::FindIndex

Parameters

Return Value

Remarks

Example

CObList::GetAt

Parameters

Return Value

Remarks

Example

CObList::GetCount

Return Value

Example

CObList::GetHead

Return Value

Remarks

Example

CObList::GetHeadPosition

Return Value

Example

CObList::GetNext

Parameters

Return Value

Remarks

Example

CObList::GetPrev

Parameters

Return Value

Remarks

Example

CObList::GetSize

Return Value

Remarks

Example

CObList::GetTail

Return Value

Remarks

Example

CObList::GetTailPosition

Return Value

Example

CObList::InsertAfter

Parameters

Return Value

Example

CObList::InsertBefore

Parameters

Return Value

Example

CObList::IsEmpty

Return Value

Example

CObList::RemoveAll

Remarks

Example

CObList::RemoveAt

Parameters