CAtlMap 类

项目
10/18/2023

此类提供用于创建和管理映射对象的方法。

语法

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
值元素类型。

另请参阅

Marquee 示例
 UpdatePV 示例
 类概述