CAtlMap 类
此类提供用于创建和管理映射对象的方法。
语法
template <typename K,
typename V,
class KTraits = CElementTraits<K>,
class VTraits = CElementTraits<V>>
class CAtlMap
参数
K
键元素类型。
V
值元素类型。
KTraits
用于复制或移动键元素的代码。 有关更多详细信息，请参阅 CElementTraits 类。
VTraits
用于复制或移动值元素的代码。
成员
公共 Typedef
| 名称 | 描述 |
|---|---|
| CAtlMap::KINARGTYPE | 作为输入参数传递键时使用的类型 |
| CAtlMap::KOUTARGTYPE | 作为输出参数返回键时使用的类型。 |
| CAtlMap::VINARGTYPE | 作为输入参数传递值时使用的类型。 |
| CAtlMap::VOUTARGTYPE | 作为输出参数传递值时使用的类型。 |
公共类
| 名称 | 描述 |
|---|---|
| CAtlMap::CPair Class | 包含键和值元素的类。 |
CPair 数据成员
| 名称 | 描述 |
|---|---|
| CPair::m_key | 存储键元素的数据成员。 |
| CPair::m_value | 存储值元素的数据成员。 |
公共构造函数
| 名称 | 描述 |
|---|---|
| CAtlMap::CAtlMap | 构造函数。 |
| CAtlMap::~CAtlMap | 析构函数。 |
公共方法
| 名称 | 描述 |
|---|---|
| CAtlMap::AssertValid | 调用此方法可导致 ASSERT（如果 CAtlMap 无效）。 |
| CAtlMap::DisableAutoRehash | 调用此方法可禁用对象的 CAtlMap 自动重新哈希。 |
| CAtlMap::EnableAutoRehash | 调用此方法可启用对象的 CAtlMap 自动重写。 |
| CAtlMap::GetAt | 调用此方法可返回位于映射中指定位置的元素。 |
| CAtlMap::GetCount | 调用此方法可检索映射中的元素数。 |
| CAtlMap::GetHashTableSize | 调用此方法可确定映射的哈希表中的箱数。 |
| CAtlMap::GetKeyAt | 调用此方法可检索存储在 CAtlMap 对象中给定位置的键。 |
| CAtlMap::GetNext | 调用此方法可获取指向存储在 CAtlMap 对象中的下一个元素对的指针。 |
| CAtlMap::GetNextAssoc | 获取要迭代的下一个元素。 |
| CAtlMap::GetNextKey | 调用此方法可从 CAtlMap 对象中检索下一个键。 |
| CAtlMap::GetNextValue | 调用此方法可从 CAtlMap 对象中获取下一个值。 |
| CAtlMap::GetStartPosition | 调用此方法可启动映射迭代。 |
| CAtlMap::GetValueAt | 调用此方法可检索存储在 CAtlMap 对象中给定位置的值。 |
| CAtlMap::InitHashTable | 调用此方法可初始化哈希表。 |
| CAtlMap::IsEmpty | 调用此方法可测试空映射对象。 |
| CAtlMap::Lookup | 调用此方法可查找 CAtlMap 对象中的键或值。 |
| CAtlMap::Rehash | 调用此方法可重新哈希 CAtlMap 对象。 |
| CAtlMap::RemoveAll | 调用此方法可从 CAtlMap 对象中删除所有元素。 |
| CAtlMap::RemoveAtPos | 调用此方法可删除 CAtlMap 对象中给定位置处的元素。 |
| CAtlMap::RemoveKey | 调用此方法可在给定键的情况下从 CAtlMap 对象中删除元素。 |
| CAtlMap::SetAt | 调用此方法可将元素对插入映射中。 |
| CAtlMap::SetOptimalLoad | 调用此方法可设置 CAtlMap 对象的最佳负载。 |
| CAtlMap::SetValueAt | 调用此方法可更改存储在 CAtlMap 对象中给定位置的值。 |
公共运算符
| “属性” | 描述 |
|---|---|
| CAtlMap::operator[] | 在 CAtlMap 中替换元素或添加新元素。 |
备注
CAtlMap 支持任何给定类型的映射数组，可管理无序的键元素数组及其关联值。 元素（由键和值组成）使用哈希算法存储，从而可以有效地存储和检索大量数据。
KTraits 和 VTraits 参数是包含复制或移动元素所需的任何补充代码的特征类。
CRBMap 类提供了 CAtlMap 的替代方法。 CRBMap 也会存储键/值对，但表现出不同的性能特征。 插入项、查找键或从 CRBMap 对象中删除键所需的时间是 log(n) 对数，其中 n 是元素的数量。 对于 CAtlMap，所有这些操作通常需要一定的时间，但最糟糕的情况可能是对数 n。 因此，在典型情况下，CAtlMap 速度更快。
迭代存储的元素时，CRBMap 和 CAtlMap 之间的另一个区别变得明显。 在 CRBMap 中，按排序顺序访问元素。 在 CAtlMap 中，元素不排序，无法推断顺序。
需要存储少量元素时，请考虑改用 CSimpleMap 类。
有关详细信息，请参阅 ATL 集合类。
要求
标头：atlcoll.h
CAtlMap::AssertValid
调用此方法可导致 ASSERT（如果 CAtlMap 对象无效）。
void AssertValid() const;
注解
在调试版本中，如果 CAtlMap 对象无效，此方法将导致 ASSERT。
示例
请参阅 CAtlMap::CAtlMap 的示例。
CAtlMap::CAtlMap
构造函数。
CAtlMap(
UINT nBins = 17,
float fOptimalLoad = 0.75f,
float fLoThreshold = 0.25f,
float fHiThreshold = 2.25f,
UINT nBlockSize = 10) throw ();
参数
nBins
提供指向存储元素的指针的箱数。 有关箱的说明，请参阅本主题后面的备注。
fOptimalLoad
最佳负载比率。
fLoThreshold
负载比率的阈值下限。
fHiThreshold
负载比率的阈值上限。
nBlockSize
块大小。
备注
CAtlMap 首先对键使用哈希算法创建索引，以此来引用其所有存储的元素。 此索引引用包含指向存储元素的指针的“bin”。 如果箱已在使用中，则会创建链接列表以访问后续元素。 遍历列表要慢于直接访问正确元素，因此映射结构需要在存储要求与性能之间进行平衡。 大多数情况下，已选择默认参数以提供良好的结果。
负载比率是映射对象中箱数与存储元素数之比。 重新计算映射结构时，fOptimalLoad 参数值将用于计算所需的箱数。 可以使用 CAtlMap::SetOptimalLoad 方法更改此值。
fLoThreshold 参数是指负载比率可以达到的下限值，低于此值后，CAtlMap 将重新计算映射的最佳大小。
fLoThreshold 参数是指负载比率可以达到的上限值，高于此值后，CAtlMap 对象将重新计算映射的最佳大小。
默认情况下启用此重新计算过程（称为重新哈希）。 如果要禁用此过程，也许一次输入大量数据时，请调用 CAtlMap::DisableAutoRehash 方法。 使用 CAtlMap::EnableAutoRehash 方法重新激活。
nBlockSize 参数用于衡量在需要新元素时分配的内存量。 较大的块大小可减少对内存分配例程的调用，但会使用更多资源。
在存储任何数据之前，必须通过调用 CAtlMap::InitHashTable 来初始化哈希表。
示例
// Create a map which stores a double
// value using an integer key
CAtlMap<int, double> mySinTable;
int i;
// Initialize the Hash Table
mySinTable.InitHashTable(257);
// Add items to the map
for (i = 0; i < 90; i++)
mySinTable[i] = sin((double)i);
// Confirm the map is valid
mySinTable.AssertValid();
// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 90);
// Remove elements with even key values
for (i = 0; i < 90; i += 2)
mySinTable.RemoveKey(i);
// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 45);
// Walk through all the elements in the map.
// First, get start position.
POSITION pos;
int key;
double value;
pos = mySinTable.GetStartPosition();
// Now iterate the map, element by element
while (pos != NULL)
{
key = mySinTable.GetKeyAt(pos);
value = mySinTable.GetNextValue(pos);
}
CAtlMap::~CAtlMap
析构函数。
~CAtlMap() throw();
备注
释放任何已分配的资源。
CAtlMap::CPair 类
包含键和值元素的类。
class CPair : public __POSITION
备注
CAtlMap::GetNext 和 CAtlMap::Lookup 方法使用此类来访问存储在映射结构中的键和值元素。
CAtlMap::DisableAutoRehash
调用此方法可禁用对象的 CAtlMap 自动重新哈希。
void DisableAutoRehash() throw();
注解
在启用自动重新哈希的情况下（这是默认设置），如果负载值（箱数与数组中存储的元素数之比）超过最大值，将自动重新计算哈希表中的箱数或创建映射时指定的最小值。
在一次将大量元素添加到映射时 DisableAutoRehash 最有用。 不是其每次超出限制都会触发重新哈希过程，调用 DisableAutoRehash 更加高效，添加元素，最后调用 CAtlMap::EnableAutoRehash 更有效。
CAtlMap::EnableAutoRehash
调用此方法可启用对象的 CAtlMap 自动重写。
void EnableAutoRehash() throw();
备注
在启用自动重新哈希的情况下（这是默认设置），如果负载值（箱数与数组中存储的元素数之比）超过最大值，将自动重新计算哈希表中的箱数或创建映射时指定的最小值。
EnableAutoRefresh 大多数是在调用 CAtlMap::DisableAutoRehash 之后使用。
CAtlMap::GetAt
调用此方法可返回位于映射中指定位置的元素。
void GetAt(
POSITION pos,
KOUTARGTYPE key,
VOUTARGTYPE value) const;
CPair* GetAt(POSITION& pos) throw();
参数
pos
位置计数器，上一次调用 CAtlMap::GetNextAssoc 或 CAtlMap::GetStartPosition 返回。
键
指定映射键类型的模板参数。
value
指定映射键值的模板参数。
返回值
返回指向映射中存储的键/值元素的当前对的指针。
注解
在调试版本中，如果 pos 等于 NULL，则会发生断言错误。
CAtlMap::GetCount
调用此方法可检索映射中的元素数。
size_t GetCount() const throw();
返回值
返回映射对象中的元素数量。 单个元素是键/值对。
示例
请参阅 CAtlMap::CAtlMap 的示例。
CAtlMap::GetHashTableSize
调用此方法可确定映射的哈希表中的箱数。
UINT GetHashTableSize() const throw();
返回值
返回哈希表中的箱数。 有关说明，请参阅 CAtlMap::CAtlMap。
CAtlMap::GetKeyAt
调用此方法可检索存储在 CAtlMap 对象中给定位置的键。
const K& GetKeyAt(POSITION pos) const throw();
参数
pos
位置计数器，上一次调用 CAtlMap::GetNextAssoc 或 CAtlMap::GetStartPosition 返回。
返回值
返回对存储在 CAtlMap 对象中给定位置的键的引用。
示例
请参阅 CAtlMap::CAtlMap 的示例。
CAtlMap::GetNext
调用此方法可获取指向存储在 CAtlMap 对象中的下一个元素对的指针。
CPair* GetNext(POSITION& pos) throw();
const CPair* GetNext(POSITION& pos) const throw();
参数
pos
位置计数器，上一次调用 CAtlMap::GetNextAssoc 或 CAtlMap::GetStartPosition 返回。
返回值
返回指向映射中存储的键/值元素的下一对的指针。 在每次调用后都会更新 pos 位置计数器。 如果检索到的元素是映射中的最后一个元素，则将 pos 设置为 NULL。
CAtlMap::GetNextAssoc
获取要迭代的下一个元素。
void GetNextAssoc(
POSITION& pos,
KOUTARGTYPE key,
VOUTARGTYPE value) const;
参数
pos
位置计数器，上一次调用 CAtlMap::GetNextAssoc 或 CAtlMap::GetStartPosition 返回。
键
指定映射键类型的模板参数。
value
指定映射键值的模板参数。
备注
在每次调用后都会更新 pos 位置计数器。 如果检索到的元素是映射中的最后一个元素，则将 pos 设置为 NULL。
CAtlMap::GetNextKey
调用此方法可从 CAtlMap 对象中检索下一个键。
const K& GetNextKey(POSITION& pos) const throw();
参数
pos
位置计数器，上一次调用 CAtlMap::GetNextAssoc 或 CAtlMap::GetStartPosition 返回。
返回值
返回对映射中下一个键的引用。
备注
更新当前位置计数器 pos。如果映射中没有更多条目，则位置计数器设置为 NULL。
CAtlMap::GetNextValue
调用此方法可从 CAtlMap 对象中获取下一个值。
V& GetNextValue(POSITION& pos) throw();
const V& GetNextValue(POSITION& pos) const throw();
参数
pos
位置计数器，上一次调用 CAtlMap::GetNextAssoc 或 CAtlMap::GetStartPosition 返回。
返回值
返回对映射中下一个值的引用。
注解
更新当前位置计数器 pos。如果映射中没有更多条目，则位置计数器设置为 NULL。
示例
请参阅 CAtlMap::CAtlMap 的示例。
CAtlMap::GetStartPosition
调用此方法可启动映射迭代。
POSITION GetStartPosition() const throw();
返回值
返回开始位置；如果映射为空，则返回 NULL。
备注
调用此方法以通过返回可传递给 GetNextAssoc 方法的 POSITION 值来启动映射迭代。
注意
迭代序列不可预测
示例
请参阅 CAtlMap::CAtlMap 的示例。
CAtlMap::GetValueAt
调用此方法可检索存储在 CAtlMap 对象中给定位置的值。
V& GetValueAt(POSITION pos) throw();
const V& GetValueAt(POSITION pos) const throw();
参数
pos
位置计数器，上一次调用 CAtlMap::GetNextAssoc 或 CAtlMap::GetStartPosition 返回。
返回值
返回对存储在 CAtlMap 对象中给定位置的值的引用。
CAtlMap::InitHashTable
调用此方法可初始化哈希表。
bool InitHashTable(
UINT nBins,
bool bAllocNow = true);
参数
nBins
哈希表使用的箱数。 有关说明，请参阅 CAtlMap::CAtlMap。
bAllocNow
一个标志，指示何时应分配内存。
返回值
在成功初始化时返回 TRUE，失败时返回 FALSE。
备注
必须在任何元素存储到哈希表之前调用 InitHashTable。 如果没有显式调用此方法，它将在第一次使用 CAtlMap 构造函数指定的箱计数添加元素时自动调用。 否则，将使用 nBins 参数指定的新的箱计数初始化映射。
如果 bAllocNow 参数为 false，则在首次需要哈希表之前，将不会分配哈希表所需的内存。 在不确定是否使用映射的情况下，此参数非常有用。
示例
请参阅 CAtlMap::CAtlMap 的示例。
CAtlMap::IsEmpty
调用此方法可测试空映射对象。
bool IsEmpty() const throw();
返回值
如果映射为空，则返回 TRUE；否则返回 FALSE。
CAtlMap::KINARGTYPE
作为输入参数传递键时使用的类型。
typedef KTraits::INARGTYPE KINARGTYPE;
CAtlMap::KOUTARGTYPE
作为输出参数返回键时使用的类型。
typedef KTraits::OUTARGTYPE KOUTARGTYPE;
CAtlMap::Lookup
调用此方法可查找 CAtlMap 对象中的键或值。
bool Lookup(KINARGTYPE key, VOUTARGTYPE value) const;
const CPair* Lookup(KINARGTYPE key) const throw();
CPair* Lookup(KINARGTYPE key) throw();
参数
键
指定要查找的元素的键。
value
接收查找值的变量。
返回值
如果找到键，则该方法的第一种形式返回 true，否则为 false。 第二种和第三种形式返回一个指向 CPair 的指针，该指针可用作调用 CAtlMap::GetNext 方法等的位置。
备注
Lookup 使用散列算法快速找到一个映射元素，该元素包含与给定键参数完全匹配的键。
CAtlMap::operator []
在 CAtlMap 中替换元素或添加新元素。
V& operator[](kinargtype key) throw();
参数
键
要添加或替换的元素的键。
返回值
返回对与给定键关联的值的引用。
示例
如果键已存在，则替换元素。 如果键不存在，则添加一个新元素。 请参阅 CAtlMap::CAtlMap 的示例。
CAtlMap::Rehash
调用此方法可重新哈希 CAtlMap 对象。
void Rehash(UINT nBins = 0);
参数
nBins
哈希表中要使用的新箱数。 有关说明，请参阅 CAtlMap::CAtlMap。
备注
如果 nBins 为 0，则 CAtlMap 根据映射中的元素数和最佳负载设置计算合理的数字。 通常，重新哈希过程是自动化的，但如果已经调用了 CAtlMap::DisableAutoRehash，此方法将执行必要的调整大小。
CAtlMap::RemoveAll
调用此方法可从 CAtlMap 对象中删除所有元素。
void RemoveAll() throw();
备注
清除 CAtlMap 对象，释放用于存储元素的内存。
CAtlMap::RemoveAtPos
调用此方法可删除 CAtlMap 对象中给定位置处的元素。
void RemoveAtPos(POSITION pos) throw();
参数
pos
位置计数器，上一次调用 CAtlMap::GetNextAssoc 或 CAtlMap::GetStartPosition 返回。
注解
删除存储在指定位置的键/值对。 释放用于存储元素的内存。 pos 引用的 POSITION 变得无效，虽然 map 中任何其他元素的 POSITION 仍然有效，但它们不一定保持相同的顺序。
CAtlMap::RemoveKey
调用此方法可在给定键的情况下从 CAtlMap 对象中删除元素。
bool RemoveKey(KINARGTYPE key) throw();
参数
键
与要删除的元素对相对应的键。
返回值
如果找到并删除密钥，则返回 TRUE，失败时返回 FALSE。
示例
请参阅 CAtlMap::CAtlMap 的示例。
CAtlMap::SetAt
调用此方法可将元素对插入映射中。
POSITION SetAt(
KINARGTYPE key,
VINARGTYPE value);
参数
键
要添加到 CAtlMap 对象的键值。
value
要添加到 CAtlMap 的对象值。
返回值
返回 CAtlMap 对象中键/值元素对的位置。
备注
如果找到匹配的键，则 SetAt 替换现有元素。 如果未找到密钥，则会创建一个新的键/值对。
CAtlMap::SetOptimalLoad
调用此方法可设置 CAtlMap 对象的最佳负载。
void SetOptimalLoad(
float fOptimalLoad,
float fLoThreshold,
float fHiThreshold,
bool bRehashNow = false);
参数
fOptimalLoad
最佳负载比率。
fLoThreshold
负载比率的阈值下限。
fHiThreshold
负载比率的阈值上限。
bRehashNow
一个标志，指示是否应重新计算哈希表。
注解
此方法重新定义 CAtlMap 对象的最佳加载值。 有关各种参数的讨论，请参阅 CAtlMap::CAtlMap。 如果 bRehashNow 为 true，并且元素数超出最小值和最大值，则会重新计算哈希表。
CAtlMap::SetValueAt
调用此方法可更改存储在 CAtlMap 对象中给定位置的值。
void SetValueAt(
POSITION pos,
VINARGTYPE value);
参数
pos
位置计数器，上一次调用 CAtlMap::GetNextAssoc 或 CAtlMap::GetStartPosition 返回。
value
要添加到 CAtlMap 的对象值。
备注
更改存储在 CAtlMap 对象中给定位置的值元素。
CAtlMap::VINARGTYPE
作为输入参数传递值时使用的类型。
typedef VTraits::INARGTYPE VINARGTYPE;
CAtlMap::VOUTARGTYPE
作为输出参数传递值时使用的类型。
typedef VTraits::OUTARGTYPE VOUTARGTYPE;
CAtlMap::CPair::m_key
存储键元素的数据成员。
const K m_key;
参数
K
键元素类型。
CAtlMap::CPair::m_value
存储值元素的数据成员。
V m_value;
参数
V
值元素类型。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈