CObList Class

 

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

For the latest documentation on Visual Studio 2017, see CObList Class on docs.microsoft.com. fSupports ordered lists of nonunique CObject pointers accessible sequentially or by pointer value.

class CObList : public CObject  

Public Constructors

NameDescription
CObList::CObListConstructs an empty list for CObject pointers.

Public Methods

NameDescription
CObList::AddHeadAdds an element (or all the elements in another list) to the head of the list (makes a new head).
CObList::AddTailAdds an element (or all the elements in another list) to the tail of the list (makes a new tail).
CObList::FindGets the position of an element specified by pointer value.
CObList::FindIndexGets the position of an element specified by a zero-based index.
CObList::GetAtGets the element at a given position.
CObList::GetCountReturns the number of elements in this list.
CObList::GetHeadReturns the head element of the list (cannot be empty).
CObList::GetHeadPositionReturns the position of the head element of the list.
CObList::GetNextGets the next element for iterating.
CObList::GetPrevGets the previous element for iterating.
CObList::GetSizeReturns the number of elements in this list.
CObList::GetTailReturns the tail element of the list (cannot be empty).
CObList::GetTailPositionReturns the position of the tail element of the list.
CObList::InsertAfterInserts a new element after a given position.
CObList::InsertBeforeInserts a new element before a given position.
CObList::IsEmptyTests for the empty list condition (no elements).
CObList::RemoveAllRemoves all the elements from this list.
CObList::RemoveAtRemoves an element from this list, specified by position.
CObList::RemoveHeadRemoves the element from the head of the list.
CObList::RemoveTailRemoves the element from the tail of the list.
CObList::SetAtSets the element at a given position.

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.

System_CAPS_ICON_note.jpg 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.

CObject

CObList

Header: afxcoll.h

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.

ClassMember Function
CPtrListPOSITION AddTail( void* newElement );

 void AddTail( CPtrList* pNewList );
CStringListPOSITION 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

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.

ClassMember Function
CPtrListCPtrList( INT_PTR nBlockSize = 10 );
CStringListCStringList( 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.         

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.

ClassMember Function
CPtrListPOSITION Find( void* searchValue , POSITION startAfter = NULL ) const;
CStringListPOSITION 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));
         }    

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.

ClassMember Function
CPtrListPOSITION FindIndex( INT_PTR nIndex ) const;
CStringListPOSITION 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));
         }    

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.

ClassMember Function
CPtrListconst void*& GetAt( POSITION position ) const;

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

 CString& GetAt( POSITION position );

Example

See the example for FindIndex.

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.

ClassMember Function
CPtrListINT_PTR GetCount( ) const;
CStringListINT_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);      

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.

ClassMember Function
CPtrListconst void*& GetHead( ) const; void*& GetHead( );
CStringListconst 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.      

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.

ClassMember Function
CPtrListPOSITION GetHeadPosition( ) const;
CStringListPOSITION 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));
         }    

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.

System_CAPS_ICON_note.jpg 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.

ClassMember Function
CPtrListvoid*& GetNext( POSITION& rPosition );

 const void* GetNext( POSITION& rPosition ) const;
CStringListCString& 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

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.

System_CAPS_ICON_note.jpg 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.

ClassMember Function
CPtrListvoid*& GetPrev( POSITION& rPosition );

 const void* GetPrev( POSITION& rPosition ) const;
CStringListCString& 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

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.

ClassMember Function
CPtrListINT_PTR GetSize( ) const;
CStringListINT_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);      

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.

ClassMember Function
CPtrListconst void*& GetTail( ) const; void*& GetTail( );
CStringListconst 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));      

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.

ClassMember Function
CPtrListPOSITION GetTailPosition( ) const;
CStringListPOSITION 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));
         }     

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.

ClassMember Function
CPtrListPOSITION InsertAfter( POSITION position , void* newElement );
CStringListPOSITION 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

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.

ClassMember Function
CPtrListPOSITION InsertBefore( POSITION position , void* newElement );
CStringListPOSITION 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

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.

ClassMember Function
CPtrListBOOL IsEmpty( ) const;
CStringListBOOL IsEmpty( ) const;

Example

See the example for 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.

ClassMember Function
CPtrListvoid RemoveAll( );
CStringListvoid 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;      

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.

ClassMember Function
CPtrListvoid RemoveAt( POSITION position );
CStringListvoid 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

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.

ClassMember Function
CPtrListvoid* RemoveHead( );
CStringListCString 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;      

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.

ClassMember Function
CPtrListvoid* RemoveTail( );
CStringListCString 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.      

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.

ClassMember Function
CPtrListvoid SetAt( POSITION pos , const CString& newElement );
CStringListvoid 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

CObject Class
Hierarchy Chart
CStringList Class
CPtrList Class

Show: