`CMap` 类

项目
10/12/2023

将唯一键映射到值的字典集合类。

语法

template<class KEY, class ARG_KEY, class VALUE, class ARG_VALUE>class CMap : public CObject

参数

KEY
用作映射键的对象的类。

ARG_KEY
用于 KEY 参数的数据类型；通常是对 KEY 的引用。

VALUE
映射中存储的对象的类。

ARG_VALUE
用于 VALUE 参数的数据类型；通常是对 VALUE 的引用。

成员

公共结构

名称	描述
`CMap::CPair`	包含键值和关联对象的值的嵌套结构。

公共构造函数

名称	描述
`CMap::CMap`	构造将键映射到值的集合。

公共方法

名称	描述
`CMap::GetCount`	返回此映射中的元素数目。
`CMap::GetHashTableSize`	返回哈希表中的元素数量。
`CMap::GetNextAssoc`	获取要迭代的下一个元素。
`CMap::GetSize`	返回此映射中的元素数目。
`CMap::GetStartPosition`	返回第一个元素的位置。
`CMap::InitHashTable`	初始化哈希表并指定其大小。
`CMap::IsEmpty`	测试空映射条件（无元素）。
`CMap::Lookup`	查找映射到给定键的值。
`CMap::PGetFirstAssoc`	返回指向第一个元素的指针。
`CMap::PGetNextAssoc`	获取指向用于迭代的下一个元素的指针。
`CMap::PLookup`	返回指向其值与指定值匹配的键的指针。
`CMap::RemoveAll`	从此映射中移除所有元素。
`CMap::RemoveKey`	移除键指定的元素。
`CMap::SetAt`	将元素插入映射；如果找到匹配键，则替换现有元素。

公共运算符

“属性”	描述
`CMap::operator [ ]`	将元素插入映射 - `SetAt` 的运算符替换。

注解

将键值对（元素）插入映射后，可使用键来访问它，从而有效地检索或删除该键值对。还可以循环访问映射中的所有元素。

POSITION 类型的变量用于对条目进行备用访问。可以使用 POSITION 来“记住”一个条目并循环访问映射。你可能会认为此迭代是按键值顺序排列的，但它不是。检索的元素序列不确定。

此类的某些成员函数调用全局帮助函数，这些函数必须针对 CMap 类的大多数用途进行自定义。请查看“MFC 参考”的“宏和全局函数”部分中的集合类帮助器。

CMap 替代了 CObject::Serialize 来支持其元素的序列化和转储。如果使用 Serialize 将映射存储到存档中，则每个映射元素都会依次序列化。 SerializeElements 帮助程序函数的默认实现执行按位写入。若要了解派生自 CObject 或其他用户定义的类型的指针集合项的序列化，请参阅如何：创建类型安全集合。

如果需要对映射中的各个元素（键和值）进行诊断转储，则必须将转储上下文的深度设置为等于或大于 1。

当删除 CMap 对象或其元素时，会同时移除键和值。

映射类派生类似于列表派生。有关特殊用途列表类派生的说明，请参阅集合一文。

继承层次结构

CObject

CMap

要求

标头：afxtempl.h

`CMap::CMap`

构造一个空映射。

CMap(INT_PTR nBlockSize = 10);

参数

nBlockSize
指定用于扩展映射的内存分配粒度。

备注

随着映射的增长，内存将以 nBlockSize 条目为单位进行分配。

示例

// declares a map of ints to points
CMap<int, int, CPoint, CPoint> myMap(16);

`CMap::CPair`

包含键值和关联对象的值。

备注

这是 CMap 类中的嵌套结构。

该结构由两个字段组成：

key：键类型的实际值。
value 关联对象的值。

它用于存储来自 CMap::PLookup、CMap::PGetFirstAssoc 和 CMap::PGetNextAssoc 的返回值。

示例

有关用法示例，请参阅 CMap::PLookup 的示例。

`CMap::GetCount`

检索映射中的元素数量。

INT_PTR GetCount() const;

返回值

元素数量。

示例

请参阅 CMap::Lookup 的示例。

`CMap::GetHashTableSize`

确定哈希表中映射的元素数目。

UINT GetHashTableSize() const;

返回值

哈希表中的元素数。

示例

CMap<int, int, CPoint, CPoint> myMap;

UINT uTableSize = myMap.GetHashTableSize();

`CMap::GetNextAssoc`

检索 rNextPosition 处的映射元素，然后更新 rNextPosition 以引用映射中的下一个元素。

void GetNextAssoc(
    POSITION& rNextPosition,
    KEY& rKey,
    VALUE& rValue) const;

参数

rNextPosition
指定对 POSITION 值的引用，该值由先前的 GetNextAssoc 或 GetStartPosition 调用返回。

KEY
指定映射键类型的模板参数。

rKey
指定检索到的元素的返回键。

VALUE
指定映射键值的模板参数。

rValue
指定检索到的元素的返回值。

备注

此函数对于循环访问映射中的所有元素最有用。请注意，位置序列不一定与键值序列相同。

如果检索到的元素是映射中的最后一个元素，则 rNextPosition 的新值设置为 NULL。

示例

请参阅 CMap::SetAt 的示例。

`CMap::GetSize`

返回映射元素的数量。

INT_PTR GetSize() const;

返回值

映射中的项数。

备注

调用此方法可检索映射中的元素数。

示例

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

`CMap::GetStartPosition`

通过返回可传递给 GetNextAssoc 调用的 POSITION 值来启动映射迭代。

POSITION GetStartPosition() const;

返回值

指示迭代映射的起始位置的 POSITION 值；如果映射为空，则为 NULL。

备注

迭代顺序是不可预测的；因此，“映射中的第一个元素”没有特殊意义。

示例

请参阅 CMap::SetAt 的示例。

`CMap::InitHashTable`

初始化哈希表。

void InitHashTable(UINT hashSize, BOOL  bAllocNow = TRUE);

参数

hashSize
哈希表中的条目数。

bAllocNow
如果为 TRUE，则在初始化时分配哈希表；否则，在需要时分配表。

注解

为了获得最佳性能，哈希表大小应为质数。为了最大程度地减少冲突，大小应比最大的预期数据集大约 20%。

示例

请参阅 CMap::Lookup 的示例。

`CMap::IsEmpty`

确定映射是否为空。

BOOL IsEmpty() const;

返回值

如果映射不包含任何元素，则为非零；否则为 0。

示例

请参阅 CMap::RemoveAll 的示例。

`CMap::Lookup`

查找映射到给定键的值。

BOOL Lookup(ARG_KEY key, VALUE& rValue) const;

参数

ARG_KEY
指定 key 值类型的模板参数。

key
指定要查找的元素的键。

VALUE
指定要查找的值的类型。

rValue
接收查找的值。

返回值

如果找到该元素，则为非零；否则为 0。

备注

Lookup 使用哈希算法快速查找包含与给定键完全匹配的键的映射元素。

示例

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

`CMap::operator [ ]`

SetAt 成员函数的方便替换项。

VALUE& operator[](arg_key key);

参数

VALUE
指定映射值类型的模板参数。

ARG_KEY
指定键值类型的模板参数。

key
用于从映射中检索值的键。

备注

因此，它只能在赋值语句的左侧 (l-value) 使用。如果没有具有指定键的映射元素，则会创建一个新元素。

因为映射中可能找不到键，所以没有等效于此运算符的“右侧”(r-value)。使用 Lookup 成员函数进行元素检索。

示例

请参阅 CMap::Lookup 的示例。

`CMap::PGetFirstAssoc`

返回映射对象的第一个条目。

const CPair* PGetFirstAssoc() const;
CPair* PGetFirstAssoc();

返回值

指向映射中第一个条目的指针；请参阅 CMap::CPair。如果映射不包含任何条目，则值为 NULL。

备注

调用此函数可返回映射对象中第一个元素的指针。

示例

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Print the element value with even key values.
int nKey = 0;
CPoint pt;
CMyMap::CPair *pCurVal;

pCurVal = myMap.PGetFirstAssoc();
while (pCurVal != NULL)
{
   if ((nKey % 2) == 0)
   {
      _tprintf_s(_T("Current key value at %d: %d,%d\n"),
                 pCurVal->key, pCurVal->value.x, pCurVal->value.y);
   }
   pCurVal = myMap.PGetNextAssoc(pCurVal);
   nKey++;
}

`CMap::PGetNextAssoc`

检索 pAssocRec 指向的映射元素。

const CPair *PGetNextAssoc(const CPair* pAssocRet) const;

CPair *PGetNextAssoc(const CPair* pAssocRet);

参数

pAssocRet
指向上一个 PGetNextAssoc 或 CMap::PGetFirstAssoc 调用返回的映射条目。

返回值

指向映射中下一个条目的指针；请参阅 CMap::CPair。如果元素是映射中的最后一个元素，则值为 NULL。

备注

调用此方法以循环访问映射中的所有元素。通过调用 PGetFirstAssoc 检索第一个元素，然后通过连续调用 PGetNextAssoc 循坏访问映射。

示例

请参阅 CMap::PGetFirstAssoc 的示例。

`CMap::PLookup`

查找映射到给定键的值。

const CPair* PLookup(ARG_KEY key) const;
CPair* PLookup(ARG_KEY key);

参数

key
要搜索的元素的键。

返回值

指向键结构的指针；请参阅 CMap::CPair。如果不找到任何匹配项，则 CMap::PLookup 返回 NULL。

备注

调用此方法可搜索具有与给定键完全匹配的键的映射元素。

示例

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap[i] = CPoint(i, i);

// Print the element values with even key values.
CMyMap::CPair *pCurVal;

for (int i = 0; i <= myMap.GetCount(); i += 2)
{
   pCurVal = myMap.PLookup(i);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              pCurVal->key, pCurVal->value.x, pCurVal->value.y);
}

`CMap::RemoveAll`

通过调用全局帮助程序函数 DestructElements，从此映射中移除所有值。

void RemoveAll();

备注

如果映射已为空，则函数正常工作。

示例

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

myMap.RemoveAll();

ASSERT(myMap.IsEmpty());

`CMap::RemoveKey`

查找与提供的键对应的映射条目；然后，如果找到键，则删除该条目。

BOOL RemoveKey(ARG_KEY key);

参数

ARG_KEY
指定键类型的模板参数。

key
要移除的元素的键。

返回值

如果找到并成功移除条目，则为非零；否则为 0。

备注

使用帮助程序函数 DestructElements 来移除条目。

示例

请参阅 CMap::SetAt 的示例。

`CMap::SetAt`

主要方法是在映射中插入元素。

void SetAt(ARG_KEY key, ARG_VALUE newValue);

参数

ARG_KEY
用于指定 key 参数的类型的模板参数。

key
指定新元素的键。

ARG_VALUE
用于指定 newValue 参数的类型的模板参数。

newValue
指定新元素的值。

注解

首先，查找键。如果找到键，则更改相应的值；否则会创建一个新的键值对。

示例

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Remove the elements with even key values.
POSITION pos = myMap.GetStartPosition();
int nKey;
CPoint pt;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);

   if ((nKey % 2) == 0)
      myMap.RemoveKey(nKey);
}

// Print the element values.
pos = myMap.GetStartPosition();
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              nKey, pt.x, pt.y);
}

另请参阅

MFC 示例 COLLECT
CObject 类
 层次结构图

通过

CMap 类

语法

参数

成员

公共结构

公共构造函数

公共方法

公共运算符

注解

继承层次结构

要求

CMap::CMap

参数

备注

示例

CMap::CPair

备注

示例

CMap::GetCount

返回值

示例

CMap::GetHashTableSize

返回值

示例

CMap::GetNextAssoc

参数

备注

示例

CMap::GetSize

返回值

备注

示例

CMap::GetStartPosition

返回值

备注

示例

CMap::InitHashTable

参数

注解

示例

CMap::IsEmpty

返回值

示例

CMap::Lookup

参数

返回值

备注

示例

CMap::operator [ ]

参数

备注

示例

CMap::PGetFirstAssoc

返回值

备注

示例

CMap::PGetNextAssoc

参数

返回值

备注

示例

CMap::PLookup

参数

返回值

备注

示例

CMap::RemoveAll

备注

示例

CMap::RemoveKey

参数

返回值

备注

示例

CMap::SetAt

参数

注解

示例

另请参阅

`CMap` 类

`CMap::CMap`

`CMap::CPair`

`CMap::GetCount`

`CMap::GetHashTableSize`

`CMap::GetNextAssoc`

`CMap::GetSize`

`CMap::GetStartPosition`

`CMap::InitHashTable`

`CMap::IsEmpty`

`CMap::Lookup`

`CMap::operator [ ]`

`CMap::PGetFirstAssoc`

`CMap::PGetNextAssoc`

`CMap::PLookup`

`CMap::RemoveAll`

`CMap::RemoveKey`

`CMap::SetAt`