Partager via

CTypedPtrList Class

  • Article

 

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 CTypedPtrList Class.

Provides a type-safe "wrapper" for objects of class CPtrList.

Syntax

template<class BASE_CLASS, class TYPE>  
class CTypedPtrList : public BASE_CLASS

Parameters

BASE_CLASS
Base class of the typed pointer list class; must be a pointer list class ( CObList or CPtrList).

TYPE
Type of the elements stored in the base-class list.

Members

Public Methods

Name Description
CTypedPtrList::AddHead Adds an element (or all the elements in another list) to the head of the list (makes a new head).
CTypedPtrList::AddTail Adds an element (or all the elements in another list) to the tail of the list (makes a new tail).
CTypedPtrList::GetAt Gets the element at a given position.
CTypedPtrList::GetHead Returns the head element of the list (cannot be empty).
CTypedPtrList::GetNext Gets the next element for iterating.
CTypedPtrList::GetPrev Gets the previous element for iterating.
CTypedPtrList::GetTail Returns the tail element of the list (cannot be empty).
CTypedPtrList::RemoveHead Removes the element from the head of the list.
CTypedPtrList::RemoveTail Removes the element from the tail of the list.
CTypedPtrList::SetAt Sets the element at a given position.

Remarks

When you use CTypedPtrList rather than CObList or CPtrList, the C++ type-checking facility helps eliminate errors caused by mismatched pointer types.

In addition, the CTypedPtrList wrapper performs much of the casting that would be required if you used CObList or CPtrList.

Because all CTypedPtrList functions are inline, use of this template does not significantly affect the size or speed of your code.

Lists derived from CObList can be serialized, but those derived from CPtrList cannot.

When a CTypedPtrList object is deleted, or when its elements are removed, only the pointers are removed, not the entities they reference.

For more information on using CTypedPtrList, see the articles Collections and Template-Based Classes.

Example

This example creates an instance of CTypedPtrList, adds one object, serializes the list to disk, and then deletes the object:

         typedef CTypedPtrList<CObList, CMyObject*>  CMyList;
         CMyList ml;
         CMyObject* pMyObject = new CMyObject();
         ml.AddTail(pMyObject);

         CFileException e;
         CFile myFile; 
         myFile.Open(_T("CTypedPtrList_File.txt"), 
            CFile::modeCreate|CFile::modeWrite, &e);
         CArchive ar(&myFile, CArchive::store);
         ml.Serialize(ar);

         ar.Close();
         myFile.Close(); 

         while (!ml.IsEmpty())
         {
            delete ml.GetHead();
            ml.RemoveHead();
         }

class CMyObject : public CObject
{
public:
     int i;
     void Serialize(CArchive& ar);
     CMyObject() { i = 9876;}
protected:
     DECLARE_SERIAL(CMyObject)
};

IMPLEMENT_SERIAL(CMyObject, CObject, 0)  

void CMyObject::Serialize(CArchive& ar)
{
    CObject::Serialize(ar);
    if(ar.IsStoring())
         ar << i;
    else
         ar >> i;
}

Inheritance Hierarchy

BASE_CLASS

_CTypedPtrList

CTypedPtrList

Requirements

Header: afxtempl.h

CTypedPtrList::AddHead

This member function calls BASE_CLASS::AddHead.

POSITION AddHead(TYPE newElement);  
void AddHead(CTypedPtrList<BASE_CLASS, TYPE>* pNewList);
```  
  
### Parameters  
 *TYPE*  
 Type of the elements stored in the base-class list.  
  
 `newElement`  
 The object pointer to be added to this list. A **NULL** value is allowed.  
  
 `BASE_CLASS`  
 Base class of the typed pointer list class; must be a pointer list class ( [CObList](../Topic/CObList%20Class.md) or [CPtrList](../Topic/CPtrList%20Class.md)).  
  
 `pNewList`  
 A pointer to another [CTypedPtrList](../Topic/CTypedPtrList%20Class.md) object. 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 first version adds a new element before the head of the list. The second version adds another list of elements before the head.  
  
##  <a name="ctypedptrlist__addtail"></a>  CTypedPtrList::AddTail  
 This member function calls `BASE_CLASS`**::AddTail**.

POSITION AddTail(TYPE newElement);
void AddTail(CTypedPtrList<BASE_CLASS, TYPE>* pNewList); ```

Parameters

TYPE
Type of the elements stored in the base-class list.

newElement
The object pointer to be added to this list. A NULL value is allowed.

BASE_CLASS
Base class of the typed pointer list class; must be a pointer list class ( CObList or CPtrList).

pNewList
A pointer to another CTypedPtrList object. 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 first version adds a new element after the tail of the list. The second version adds another list of elements after the tail of the list.

CTypedPtrList::GetAt

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

TYPE& GetAt(POSITION position);  
TYPE GetAt(POSITION position) const;

Parameters

TYPE
Template parameter specifying the type of elements stored in the list.

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

Return Value

If the list is accessed through a pointer to a const CTypedPtrList, then GetAt returns a pointer of the type specified by the template parameter TYPE. 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 CTypedPtrList, then GetAt returns a reference to a pointer of the type specified by the template parameter TYPE. This allows the function to be used on either side of an assignment statement and thus allows the list entries to be modified.

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.

This inline function calls BASE_CLASS::GetAt.

CTypedPtrList::GetHead

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

TYPE& GetHead();  
TYPE GetHead() const;

Parameters

TYPE
Template parameter specifying the type of elements stored in the list.

Return Value

If the list is accessed through a pointer to a const CTypedPtrList, then GetHead returns a pointer of the type specified by the template parameter TYPE. 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 CTypedPtrList, then GetHead returns a reference to a pointer of the type specified by the template parameter TYPE. 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.

CTypedPtrList::GetNext

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

TYPE& GetNext(POSITION& rPosition);  
TYPE GetNext(POSITION& rPosition) const;

Parameters

TYPE
Template parameter specifying the type of elements contained in this list.

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

Return Value

If the list is accessed through a pointer to a const CTypedPtrList, then GetNext returns a pointer of the type specified by the template parameter TYPE. 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 CTypedPtrList, then GetNext returns a reference to a pointer of the type specified by the template parameter TYPE. This allows the function to be used on either side of an assignment statement and thus allows the list entries to be modified.

Remarks

You can use GetNext in a forward iteration loop if you establish the initial position with a call to GetHeadPosition or CPtrList::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 CObList::RemoveAt.

CTypedPtrList::GetPrev

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

TYPE& GetPrev(POSITION& rPosition);  
TYPE GetPrev(POSITION& rPosition) const;

Parameters

TYPE
Template parameter specifying the type of elements contained in this list.

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

Return Value

If the list is accessed through a pointer to a const CTypedPtrList, then GetPrev returns a pointer of the type specified by the template parameter TYPE. 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 CTypedPtrList, then GetPrev returns a reference to a pointer of the type specified by the template parameter TYPE. This allows the function to be used on either side of an assignment statement and thus allows the list entries to be modified.

Remarks

You can use GetPrev in a reverse iteration loop if you establish the initial position with a call to GetTailPosition or Find.

You must ensure that your POSITION value represents a valid position in the list. If it is invalid, then the Debug version of the Microsoft Foundation Class Library asserts.

If the retrieved element is the first in the list, then the new value of rPosition is set to NULL.

CTypedPtrList::GetTail

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

TYPE& GetTail();  
TYPE GetTail() const;

Parameters

TYPE
Template parameter specifying the type of elements stored in the list.

Return Value

If the list is accessed through a pointer to a const CTypedPtrList, then GetTail returns a pointer of the type specified by the template parameter TYPE. 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 CTypedPtrList, then GetTail returns a reference to a pointer of the type specified by the template parameter TYPE. 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 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.

CTypedPtrList::RemoveHead

Removes the element from the head of the list and returns it.

TYPE RemoveHead();

Parameters

TYPE
Template parameter specifying the type of elements stored in the list.

Return Value

The pointer previously at the head of the list. This pointer is of the type specified by the template parameter TYPE.

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.

CTypedPtrList::RemoveTail

Removes the element from the tail of the list and returns it.

TYPE RemoveTail();

Parameters

TYPE
Template parameter specifying the type of elements stored in the list.

Return Value

The pointer previously at the tail of the list. This pointer is of the type specified by the template parameter TYPE.

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.

CTypedPtrList::SetAt

This member function calls BASE_CLASS::SetAt.

void SetAt(POSITION pos, TYPE newElement);

Parameters

pos
The POSITION of the element to be set.

TYPE
Type of the elements stored in the base-class list.

newElement
The object 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 object 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.

For more detailed remarks, see CObList::SetAt.

See Also

MFC Sample COLLECT
Hierarchy Chart
CPtrList Class
CObList Class