`CObList` Class

Article
10/17/2022

Supports 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 (can't 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 (can't 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 isn't 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 isn't 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.

CObList list;
list.AddHead(new CAge(21)); // 21 is now at head.
list.AddHead(new CAge(40)); // 40 replaces 21 at head.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("AddHead example: ") << &list << _T("\n");
#endif

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.

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 isn't 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 isn't the same as an index, and you can't 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's 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 isn't 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's 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's 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's 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 isn't 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 that 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's 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 isn't 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 isn't 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 isn't the same as an index, and you can't 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's 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

CObList Class

Syntax

Members

Public Constructors

Public Methods

Remarks

Inheritance Hierarchy

Requirements

CObList::AddHead

Parameters

Return Value

Remarks

Example

CObList::AddTail

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

`CObList` Class

`CObList::AddHead`

`CObList::AddTail`

`CObList::CObList`

`CObList::Find`

`CObList::FindIndex`

`CObList::GetAt`

`CObList::GetCount`

`CObList::GetHead`

`CObList::GetHeadPosition`

`CObList::GetNext`

`CObList::GetPrev`

`CObList::GetSize`

`CObList::GetTail`

`CObList::GetTailPosition`

`CObList::InsertAfter`

`CObList::InsertBefore`

`CObList::IsEmpty`

`CObList::RemoveAll`

`CObList::RemoveAt`

`CObList::RemoveHead`

`CObList::RemoveTail`

`CObList::SetAt`