CTypedPtrList 类

  • 项目

为 CPtrList类的对象提供安全类型“包装器”。

语法

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

参数

BASE_CLASS
类型化指针列表类的基类；必须是指针列表类（CObList 或 CPtrList）。

TYPE
存储在基类列表中的元素类型。

成员

公共方法

名称 描述
CTypedPtrList::AddHead 将一个元素（或另一个列表中的所有元素）添加到列表的头部（创建新的头部）。
CTypedPtrList::AddTail 将一个元素（或另一个列表中的所有元素）添加到列表的末尾（创建新的尾部）。
CTypedPtrList::GetAt 获取位于给定位置的元素。
CTypedPtrList::GetHead 返回列表的头部元素（不能为空）。
CTypedPtrList::GetNext 获取要迭代的下一个元素。
CTypedPtrList::GetPrev 获取要进行迭代的上一个元素。
CTypedPtrList::GetTail 返回列表的尾部元素（不能为空）。
CTypedPtrList::RemoveHead 从列表的头部移除元素。
CTypedPtrList::RemoveTail 从列表的尾部移除元素。
CTypedPtrList::SetAt 设置位于给定位置的元素。

注解

使用 CTypedPtrList 而非 CObList 或 CPtrList 时，C++ 类型检查设备可帮助消除由不匹配的指针类型引起的错误。

此外，如果使用 CObList 或 CPtrList，则 CTypedPtrList 包装器需要执行大量强制转换。

由于所有 CTypedPtrList 函数都是内联函数，因此使用此模板不会显著影响代码的大小或速度。

派生 CObList 自的列表可以串行化，但派生自 CPtrList 的列表不能。

当删除 CTypedPtrList 对象或其元素时，仅删除指针而不是指针引用的实体。

有关使用 CTypedPtrList 的详细信息，请参阅文章：集合和基于模板的类。

示例

此示例创建 CTypedPtrList 的实例，添加一个对象，将列表串行化到磁盘，然后删除该对象：

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;
}

继承层次结构

BASE_CLASS

_CTypedPtrList

CTypedPtrList

要求

标头： afxtempl.h

CTypedPtrList::AddHead

此成员函数调用 BASE_CLASS::AddHead。

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

参数

TYPE
存储在基类列表中的元素类型。

newElement
要添加到此列表的对象指针。 允许 NULL 值。

BASE_CLASS
类型化指针列表类的基类；必须是指针列表类（CObList 或 CPtrList）。

pNewList
指向另一个 CTypedPtrList 对象的指针。 pNewList 中的元素将添加到此列表中。

返回值

第一个版本返回新插入元素的 POSITION 值。

备注

第一个版本在列表头前面添加新元素。 第二个版本在头前面添加另一个元素列表。

CTypedPtrList::AddTail

此成员函数调用 BASE_CLASS::AddTail。

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

参数

TYPE
存储在基类列表中的元素类型。

newElement
要添加到此列表的对象指针。 允许 NULL 值。

BASE_CLASS
类型化指针列表类的基类；必须是指针列表类（CObList 或 CPtrList）。

pNewList
指向另一个 CTypedPtrList 对象的指针。 pNewList 中的元素将添加到此列表中。

返回值

第一个版本返回新插入元素的 POSITION 值。

备注

第一个版本在列表尾部后面添加新元素。 第二个版本在列表尾部后面添加另一个元素列表。

CTypedPtrList::GetAt

POSITION 类型的变量是列表的键。

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

参数

TYPE
指定存储在列表中的元素类型的模板参数。

position
一个由之前的 GetHeadPosition 或 Find 成员函数调用返回的 POSITION 值。

返回值

如果通过指向 const CTypedPtrList 的指针访问列表，则 GetAt 返回指向模板参数 TYPE 所指定类型的指针。 这允许仅在赋值语句的右侧使用该函数，因此还能防止修改列表。

如果直接访问列表通过指向 CTypedPtrList 的指针访问列表，则 GetAt 返回相关引用（即对指向模板参数 TYPE 所指定类型的指针的引用）。 这允许在赋值语句的任一侧使用该函数，从而允许修改列表条目。

注解

它与索引不同，你不能自己对 POSITION 值进行操作。 GetAt 检索与给定位置关联的 CObject 指针。

必须确保 POSITION 值代表列表中的有效位置。 如果该值无效，则 Microsoft 基础类库的调试版本会断言。

此内联函数调用 BASE_CLASS::GetAt。

CTypedPtrList::GetHead

获取表示此列表的头元素的 指针。

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

参数

TYPE
指定存储在列表中的元素类型的模板参数。

返回值

如果通过指向 const CTypedPtrList 的指针访问列表，则 GetHead 返回指向模板参数 TYPE 所指定类型的指针。 这允许仅在赋值语句的右侧使用该函数，因此还能防止修改列表。

如果直接访问列表通过指向 CTypedPtrList 的指针访问列表，则 GetHead 返回相关引用（即对指向模板参数 TYPE 所指定类型的指针的引用）。 这允许在赋值语句的任一侧使用该函数，从而允许修改列表条目。

备注

在调用 GetHead 之前，必须确保列表不为空。 如果该列表为空，则 Microsoft 基础类库的调试版本会断言。 使用 IsEmpty 验证列表是否包含元素。

CTypedPtrList::GetNext

获取由 rPosition 标识的列表元素，然后将 rPosition 设置为列表中下一个条目的 POSITION 值。

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

参数

TYPE
指定此列表中包含的元素类型的模板参数。

rPosition
对由以前的 GetNext、GetHeadPosition 或其他成员函数调用返回的 POSITION 值的引用。

返回值

如果通过指向 const CTypedPtrList 的指针访问列表，则 GetNext 返回指向模板参数 TYPE 所指定类型的指针。 这允许仅在赋值语句的右侧使用该函数，因此还能防止修改列表。

如果直接访问列表通过指向 CTypedPtrList 的指针访问列表，则 GetNext 返回相关引用（即对指向模板参数 TYPE 所指定类型的指针的引用）。 这允许在赋值语句的任一侧使用该函数，从而允许修改列表条目。

备注

如果通过调用 GetHeadPosition 或 CPtrList::Find 建立初始位置，则可以在正向迭代循环中使用 GetNext。

必须确保 POSITION 值代表列表中的有效位置。 如果该值无效，则 Microsoft 基础类库的调试版本会断言。

如果检索到的元素是列表中的最后一个元素，则 rPosition 的新值会设置为 NULL。

可以在迭代期间移除元素。 请参阅 CObList::RemoveAt 的示例。

CTypedPtrList::GetPrev

获取由 rPosition 标识的列表元素，然后将 rPosition 设置为列表中上一个条目的 POSITION 值。

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

参数

TYPE
指定此列表中包含的元素类型的模板参数。

rPosition
对由以前的 GetPrev 或其他成员函数调用返回的 POSITION 值的引用。

返回值

如果通过指向 const CTypedPtrList 的指针访问列表，则 GetPrev 返回指向模板参数 TYPE 所指定类型的指针。 这允许仅在赋值语句的右侧使用该函数，因此还能防止修改列表。

如果直接访问列表通过指向 CTypedPtrList 的指针访问列表，则 GetPrev 返回相关引用（即对指向模板参数 TYPE 所指定类型的指针的引用）。 这允许在赋值语句的任一侧使用该函数，从而允许修改列表条目。

备注

如果通过调用 GetTailPosition 或 Find 建立初始位置，则可以在反向迭代循环中使用 GetPrev。

必须确保 POSITION 值代表列表中的有效位置。 如果该值无效，则 Microsoft 基础类库的调试版本会断言。

如果检索到的元素是列表中的第一个元素，则 rPosition 的新值会设置为 NULL。

CTypedPtrList::GetTail

获取表示此列表的头元素的 指针。

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

参数

TYPE
指定存储在列表中的元素类型的模板参数。

返回值

如果通过指向 const CTypedPtrList 的指针访问列表，则 GetTail 返回指向模板参数 TYPE 所指定类型的指针。 这允许仅在赋值语句的右侧使用该函数，因此还能防止修改列表。

如果直接访问列表通过指向 CTypedPtrList 的指针访问列表，则 GetTail 返回相关引用（即对指向模板参数 TYPE 所指定类型的指针的引用）。 这允许在赋值语句的任一侧使用该函数，从而允许修改列表条目。

备注

在调用 GetTail 之前，必须确保列表不为空。 如果该列表为空，则 Microsoft 基础类库的调试版本会断言。 使用 IsEmpty 验证列表是否包含元素。

CTypedPtrList::RemoveHead

从列表的头部删除元素，并返回该元素。

TYPE RemoveHead();

参数

TYPE
指定存储在列表中的元素类型的模板参数。

返回值

之前位于列表头部的 指针。 此指针属于模板参数 TYPE 指定的类型。

备注

在调用 RemoveHead 之前，必须确保列表不为空。 如果该列表为空，则 Microsoft 基础类库的调试版本会断言。 使用 IsEmpty 验证列表是否包含元素。

CTypedPtrList::RemoveTail

从列表的尾部删除元素，并返回该元素。

TYPE RemoveTail();

参数

TYPE
指定存储在列表中的元素类型的模板参数。

返回值

之前位于列表尾部的指标。 此指针属于模板参数 TYPE 指定的类型。

备注

在调用 RemoveTail 之前，必须确保列表不为空。 如果该列表为空，则 Microsoft 基础类库的调试版本会断言。 使用 IsEmpty 验证列表是否包含元素。

CTypedPtrList::SetAt

此成员函数调用 BASE_CLASS::SetAt。

void SetAt(POSITION pos, TYPE newElement);

参数

pos
要设置的元素的 POSITION。

TYPE
存储在基类列表中的元素类型。

newElement
要写入列表的对象指针。

注解

POSITION 类型的变量是列表的键。 它与索引不同，你不能自己对 POSITION 值进行操作。 SetAt 将对象指针写入列表中的指定位置。

必须确保 POSITION 值代表列表中的有效位置。 如果该值无效，则 Microsoft 基础类库的调试版本会断言。

有关更详细的说明，请参阅 CObList::SetAt。

另请参阅

MFC 示例 COLLECT
层次结构图
CPtrList 类
CObList 类