CMapStringToOb 类
将唯一 CString 对象映射到 CObject 指针的字典集合类。
语法
class CMapStringToOb : public CObject
成员
公共构造函数
| 名称 | 描述 |
|---|---|
CMapStringToOb::CMapStringToOb |
构造函数。 |
公共方法
| 名称 | 描述 |
|---|---|
CMapStringToOb::GetCount |
返回此映射中的元素数目。 |
CMapStringToOb::GetHashTableSize |
确定哈希表中当前的元素数量。 |
CMapStringToOb::GetNextAssoc |
获取要迭代的下一个元素。 |
CMapStringToOb::GetSize |
返回此映射中的元素数目。 |
CMapStringToOb::GetStartPosition |
返回第一个元素的位置。 |
CMapStringToOb::HashKey |
计算指定键的哈希值。 |
CMapStringToOb::InitHashTable |
初始化哈希表。 |
CMapStringToOb::IsEmpty |
测试空映射条件（无元素）。 |
CMapStringToOb::Lookup |
根据 void 指针键查找 void 指针。 指针值（而不是它指向的实体）用于键比较。 |
CMapStringToOb::LookupKey |
返回对与指定键值关联的键的引用。 |
CMapStringToOb::RemoveAll |
从此映射中移除所有元素。 |
CMapStringToOb::RemoveKey |
移除键指定的元素。 |
CMapStringToOb::SetAt |
将元素插入映射；如果找到匹配键，则替换现有元素。 |
公共运算符
| “属性” | 描述 |
|---|---|
CMapStringToOb::operator [ ] |
将元素插入映射 - SetAt 的运算符替换。 |
注解
将 CString- CObject* 对（元素）插入映射后，可以使用字符串或 CString 值作为键有效地检索或删除该对。 还可以循环访问映射中的所有元素。
POSITION 类型的变量用于所有映射变体中的备用条目访问。 可以使用 POSITION 来“记住”一个条目并循环访问映射。 可能认为此迭代是按键值顺序排列的；而它不是。 检索的元素序列不确定。
CMapStringToOb 包括用于支持其元素序列化和转储的 IMPLEMENT_SERIAL 宏。 如果使用重载插入 (<<) 运算符或 Serialize 成员函数将映射存储到存档中，则将依次序列化每个元素。
如果需要对映射中的各个元素（CString 值和 CObject 内容）进行诊断转储，则必须将转储上下文的深度设置为等于或大于 1。
删除 CMapStringToOb 对象或移除其元素时，将移除 CString 对象和 CObject 指针。 CObject 指针引用的对象不会被销毁。
映射类派生类似于列表派生。 有关特殊用途列表类派生的说明，请参阅集合一文。
继承层次结构
CMapStringToOb
要求
标头afxcoll.h：
CMapStringToOb::CMapStringToOb
构造一个空的 CString 到 CObject* 映射。
CMapStringToOb(INT_PTR nBlockSize = 10);
参数
nBlockSize
指定用于扩展映射的内存分配粒度。
备注
随着映射的增长，内存将以 nBlockSize 条目为单位进行分配。
下表显示了与 CMapStringToOb:: CMapStringToOb 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
CMapPtrToPtr( INT_PTR nBlockSize = 10 ); |
CMapPtrToWord |
CMapPtrToWord( INT_PTR nBlockSize = 10 ); |
CMapStringToPtr |
CMapStringToPtr( INT_PTR nBlockSize = 10 ); |
CMapStringToString |
CMapStringToString( INT_PTR nBlockSize = 10 ); |
CMapWordToOb |
CMapWordToOb( INT_PTR nBlockSize = 10 ); |
CMapWordToPtr |
MapWordToPtr( INT_PTR nBlockSize = 10 ); |
示例
CMapStringToOb map(20); // Map on the stack with blocksize of 20
CMapStringToOb *pm = new CMapStringToOb; // Map on the heap
// with default blocksize
有关所有集合示例中使用的 CAge 类的列表，请参阅 CObList::CObList。
CMapStringToOb::GetCount
确定映射中的元素数量。
INT_PTR GetCount() const;
返回值
此映射中的元素数量。
注解
下表显示了与 CMapStringToOb::GetCount 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
INT_PTR GetCount() const; |
CMapPtrToWord |
INT_PTR GetCount() const; |
CMapStringToPtr |
INT_PTR GetCount() const; |
CMapStringToString |
INT_PTR GetCount() const; |
CMapWordToOb |
INT_PTR GetCount() const; |
CMapWordToPtr |
INT_PTR GetCount() const; |
示例
有关所有集合示例中使用的 CAge 类的列表，请参阅 CObList::CObList。
CMapStringToOb map;
map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Homer"), new CAge(36));
ASSERT(map.GetCount() == 2);
CMapStringToOb::GetHashTableSize
确定哈希表中当前的元素数量。
UINT GetHashTableSize() const;
返回值
返回哈希表中的元素数量。
备注
下表显示了与 CMapStringToOb::GetHashTableSize 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
UINT GetHashTableSize() const; |
CMapPtrToWord |
UINT GetHashTableSize() const; |
CMapStringToPtr |
UINT GetHashTableSize() const; |
CMapStringToString |
UINT GetHashTableSize() const; |
CMapWordToOb |
UINT GetHashTableSize() const; |
CMapWordToPtr |
UINT GetHashTableSize() const; |
CMapStringToOb::GetNextAssoc
检索 rNextPosition 处的映射元素，然后更新 rNextPosition 以引用映射中的下一个元素。
void GetNextAssoc(
POSITION& rNextPosition,
CString& rKey,
CObject*& rValue) const;
参数
rNextPosition
指定对先前 GetNextAssoc 或 GetStartPosition 调用返回的 POSITION 值的引用。
rKey
指定检索到的元素（字符串）的返回键。
rValue
指定检索到的元素（CObject 指针）的返回值。 有关此参数的详细信息，请参阅注解。
备注
此函数对于循环访问映射中的所有元素最有用。 请注意，位置序列不一定与键值序列相同。
如果检索到的元素是映射中的最后一个元素，则 rNextPosition 的新值设置为 NULL。
对于 rValue 参数，请务必将对象类型转换为 CObject*&，这是编译器需要的，如以下示例所示：
CObject *ob;
map.GetNextAssoc(pos, key, (CObject *&)ob);
这不适用于基于模板的映射的 GetNextAssoc。
下表显示了与 CMapStringToOb::GetNextAssoc 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
| CMapPtrToPtr | void GetNextAssoc( POSITION& rNextPosition , void*& rKey , void*& rValue ) const; |
| CMapPtrToWord | void GetNextAssoc( POSITION& rNextPosition , void*& rKey , WORD& rValue ) const; |
| CMapStringToPtr | void GetNextAssoc( POSITION& rNextPosition , CString& rKey , void*& rValue ) const; |
| CMapStringToString | void GetNextAssoc( POSITION& rNextPosition , CString& rKey , CString& rValue ) const; |
| CMapWordToOb | void GetNextAssoc( POSITION& rNextPosition , WORD& rKey , CObject*& rValue ) const; |
| CMapWordToPtr | void GetNextAssoc( POSITION& rNextPosition , WORD& rKey , void*& rValue ) const; |
示例
有关所有集合示例中使用的 CAge 类的列表，请参阅 CObList::CObList。
CMapStringToOb map;
POSITION pos;
CString key;
CAge *pa;
map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11));
map.SetAt(_T("Homer"), new CAge(36));
map.SetAt(_T("Marge"), new CAge(35));
// Iterate through the entire map, dumping both name and age.
for (pos = map.GetStartPosition(); pos != NULL;)
{
map.GetNextAssoc(pos, key, (CObject *&)pa);
#ifdef _DEBUG
afxDump << key << _T(" : ") << pa << _T("\n");
#endif
}
此程序的结果如下所示：
Lisa : a CAge at $4724 11
Marge : a CAge at $47A8 35
Homer : a CAge at $4766 36
Bart : a CAge at $45D4 13
CMapStringToOb::GetSize
返回映射元素的数量。
INT_PTR GetSize() const;
返回值
映射中的项数。
备注
调用此方法可检索映射中的元素数。
下表显示了与 CMapStringToOb::GetSize 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
INT_PTR GetSize() const; |
CMapPtrToWord |
INT_PTR GetSize() const; |
CMapStringToPtr |
INT_PTR GetSize() const; |
CMapStringToString |
INT_PTR GetSize() const; |
CMapWordToOb |
INT_PTR GetSize() const; |
CMapWordToPtr |
INT_PTR GetSize() const; |
示例
CMapStringToOb map;
map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Homer"), new CAge(36));
ASSERT(map.GetSize() == 2);
CMapStringToOb::GetStartPosition
通过返回可传递给 GetNextAssoc 调用的 POSITION 值来启动映射迭代。
POSITION GetStartPosition() const;
返回值
指示迭代映射的起始位置的 POSITION 值；如果映射为空，则为 NULL。
注解
迭代顺序是不可预测的；因此，“映射中的第一个元素”没有特殊意义。
下表显示了与 CMapStringToOb::GetStartPosition 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
POSITION GetStartPosition() const; |
CMapPtrToWord |
POSITION GetStartPosition() const; |
CMapStringToPtr |
POSITION GetStartPosition() const; |
CMapStringToString |
POSITION GetStartPosition() const; |
CMapWordToOb |
POSITION GetStartPosition() const; |
CMapWordToPtr |
POSITION GetStartPosition() const; |
示例
请参阅 CMapStringToOb::GetNextAssoc 的示例。
CMapStringToOb::HashKey
计算指定键的哈希值。
UINT HashKey(LPCTSTR key) const;
参数
key
要计算其哈希值的键。
返回值
键的哈希值
备注
下表显示了与 CMapStringToOb::HashKey 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
UINT HashKey( void *key ) const; |
CMapPtrToWord |
UINT HashKey( void *key ) const; |
CMapStringToString |
UINT HashKey( LPCTSTR key ) const; |
CMapStringToPtr |
UINT HashKey( LPCTSTR key ) const; |
CMapWordToOb |
UINT HashKey( WORD key ) const; |
CMapWordToPtr |
UINT HashKey( WORD key ) const; |
CMapStringToOb::InitHashTable
初始化哈希表。
void InitHashTable(
UINT hashSize,
BOOL bAllocNow = TRUE);
参数
hashSize
哈希表中的条目数。
bAllocNow
如果为 TRUE，则在初始化时分配哈希表；否则，在需要时分配表。
注解
为了获得最佳性能，哈希表大小应为质数。 为了最大程度地减少冲突，大小应比最大的预期数据集大约 20%。
下表显示了与 CMapStringToOb::InitHashTable 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE ); |
CMapPtrToWord |
void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE ); |
CMapStringToString |
void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE ); |
CMapStringToPtr |
void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE ); |
CMapWordToOb |
void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE ); |
CMapWordToPtr |
void InitHashTable( UINT hashSize , BOOL bAllocNow = TRUE ); |
CMapStringToOb::IsEmpty
确定映射是否为空。
BOOL IsEmpty() const;
返回值
如果映射不包含任何元素，则为非零；否则为 0。
示例
请参阅 RemoveAll 的示例。
注解
下表显示了与 CMapStringToOb:: IsEmpty 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
BOOL IsEmpty() const; |
CMapPtrToWord |
BOOL IsEmpty() const; |
CMapStringToPtr |
BOOL IsEmpty() const; |
CMapStringToString |
BOOL IsEmpty() const; |
CMapWordToOb |
BOOL IsEmpty() const; |
CMapWordToPtr |
BOOL IsEmpty() const; |
CMapStringToOb::Lookup
根据 CString 值返回 CObject 指针。
BOOL Lookup(
LPCTSTR key,
CObject*& rValue) const;
参数
key
指定标识要查找的元素的字符串键。
rValue
指定查找元素返回的值。
返回值
如果找到该元素，则为非零；否则为 0。
注解
Lookup 使用哈希算法快速找到键完全匹配（CString 值）的映射元素。
下表显示了与 CMapStringToOb::LookUp 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
BOOL Lookup( void *key , void*& rValue ) const; |
CMapPtrToWord |
BOOL Lookup( void *key , WORD& rValue ) const; |
CMapStringToPtr |
BOOL Lookup( LPCTSTR key , void*& rValue ) const; |
CMapStringToString |
BOOL Lookup( LPCTSTR key , CString& rValue ) const; |
CMapWordToOb |
BOOL Lookup( WORD key , CObject*& rValue ) const; |
CMapWordToPtr |
BOOL Lookup( WORD key , void*& rValue ) const; |
示例
有关所有集合示例中使用的 CAge 类的列表，请参阅 CObList::CObList。
CMapStringToOb map;
CAge *pa;
map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11));
map.SetAt(_T("Homer"), new CAge(36));
map.SetAt(_T("Marge"), new CAge(35));
ASSERT(map.Lookup(_T("Lisa"), (CObject *&)pa)); // Is "Lisa" in the map?
ASSERT(*pa == CAge(11)); // Is she 11?
CMapStringToOb::LookupKey
返回对与指定键值关联的键的引用。
BOOL LookupKey(
LPCTSTR key,
LPCTSTR& rKey) const;
参数
key
指定标识要查找的元素的字符串键。
rKey
对关联键的引用。
返回值
如果找到了该键，则为非零；否则为 0。
备注
如果在关联元素从映射中移除或映射被销毁后使用，则使用对键的引用是不安全的。
下表显示了与 CMapStringToOb:: LookupKey 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapStringToPtr |
BOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const; |
CMapStringToString |
BOOL LookupKey( LPCTSTR key , LPCTSTR& rKey ) const; |
CMapStringToOb::operator [ ]
SetAt 成员函数的方便替换项。
CObject*& operator[ ](lpctstr key);
返回值
对指向 CObject 对象的指针的引用；如果映射为空或 key 超出范围，则为 NULL。
备注
因此，它只能在赋值语句的左侧 (l-value) 使用。 如果没有具有指定键的映射元素，则会创建一个新元素。
没有等效于此运算符的“右侧”(r-value)，因为映射中可能找不到键。 使用 Lookup 成员函数进行元素检索。
下表显示了与 CMapStringToOb::operator [] 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
| CMapPtrToPtr | void*& operator[](void *key ); |
| CMapPtrToWord | WORD& operator[](void *key ); |
| CMapStringToPtr | void*& operator[](lpctstr key ); |
| CMapStringToString | CString& operator[](lpctstr key ); |
| CMapWordToOb | CObject*& operator[](word key ); |
| CMapWordToPtr | void*& operator[](word key ); |
示例
有关所有集合示例中使用的 CAge 类的列表，请参阅 CObList::CObList。
CMapStringToOb map;
map[_T("Bart")] = new CAge(13);
map[_T("Lisa")] = new CAge(11);
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("Operator [] example: ") << &map << _T("\n");
#endif
此程序的结果如下所示：
Operator [] example: A CMapStringToOb with 2 elements
[Lisa] = a CAge at $4A02 11
[Bart] = a CAge at $497E 13
CMapStringToOb::RemoveAll
从此映射中移除所有元素并销毁 CString 键对象。
void RemoveAll();
注解
每个键引用的 CObject 对象不会被销毁。 如果不能确保引用的 CObject 对象被销毁，RemoveAll 函数可能会导致内存泄漏。
如果映射已为空，则函数正常工作。
下表显示了与 CMapStringToOb::RemoveAll 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
void RemoveAll(); |
CMapPtrToWord |
void RemoveAll(); |
CMapStringToPtr |
void RemoveAll(); |
CMapStringToString |
void RemoveAll(); |
CMapWordToOb |
void RemoveAll(); |
CMapWordToPtr |
void RemoveAll(); |
示例
有关所有集合示例中使用的 CAge 类的列表，请参阅 CObList::CObList。
{
CMapStringToOb map;
CAge age1(13); // Two objects on the stack
CAge age2(36);
map.SetAt(_T("Bart"), &age1);
map.SetAt(_T("Homer"), &age2);
ASSERT(map.GetCount() == 2);
map.RemoveAll(); // CObject pointers removed; objects not removed.
ASSERT(map.GetCount() == 0);
ASSERT(map.IsEmpty());
} // The two CAge objects are deleted when they go out of scope.
CMapStringToOb::RemoveKey
查找与提供的键对应的映射条目；然后，如果找到键，则删除该条目。
BOOL RemoveKey(LPCTSTR key);
参数
key
指定用于映射查找的字符串。
返回值
如果找到并成功移除条目，则为非零；否则为 0。
备注
如果未在其他地方删除 CObject 对象，这可能会导致内存泄漏。
下表显示了与 CMapStringToOb::RemoveKey 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
BOOL RemoveKey( void *key ); |
CMapPtrToWord |
BOOL RemoveKey( void *key ); |
CMapStringToPtr |
BOOL RemoveKey( LPCTSTR key ); |
CMapStringToString |
BOOL RemoveKey( LPCTSTR key ); |
CMapWordToOb |
BOOL RemoveKey( WORD key ); |
CMapWordToPtr |
BOOL RemoveKey( WORD key ); |
示例
有关所有集合示例中使用的 CAge 类的列表，请参阅 CObList::CObList。
CMapStringToOb map;
map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11));
map.SetAt(_T("Homer"), new CAge(36));
map.SetAt(_T("Marge"), new CAge(35));
map.RemoveKey(_T("Lisa")); // Memory leak: CAge object not
// deleted.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("RemoveKey example: ") << &map << _T("\n");
#endif
此程序的结果如下所示：
RemoveKey example: A CMapStringToOb with 3 elements
[Marge] = a CAge at $49A0 35
[Homer] = a CAge at $495E 36
[Bart] = a CAge at $4634 13
CMapStringToOb::SetAt
主要方法是在映射中插入元素。
void SetAt(
LPCTSTR key,
CObject* newValue);
参数
key
指定作为新元素的键的字符串。
newValue
指定作为新元素的值的 CObject 指针。
备注
首先，查找键。 如果找到键，则更改相应的值；否则会创建一个新的键值元素。
下表显示了与 CMapStringToOb::SetAt 类似的其他成员函数。
| 类 | 成员函数 |
|---|---|
CMapPtrToPtr |
void SetAt( void *key , void *newValue ); |
CMapPtrToWord |
void SetAt( void *key , WORD newValue ); |
CMapStringToPtr |
void SetAt( LPCTSTR key , void *newValue ); |
CMapStringToString |
void SetAt( LPCTSTR key , LPCTSTR newValue ); |
CMapWordToOb |
void SetAt( WORD key , CObject *newValue ); |
CMapWordToPtr |
void SetAt( WORD key , void *newValue ); |
示例
有关所有集合示例中使用的 CAge 类的列表，请参阅 CObList::CObList。
CMapStringToOb map;
CAge *pa;
map.SetAt(_T("Bart"), new CAge(13));
map.SetAt(_T("Lisa"), new CAge(11)); // Map contains 2
// elements.
#ifdef _DEBUG
afxDump.SetDepth(1);
afxDump << _T("before Lisa's birthday: ") << &map << _T("\n");
#endif
if (map.Lookup(_T("Lisa"), (CObject *&)pa))
{ // CAge 12 pointer replaces CAge 11 pointer.
map.SetAt(_T("Lisa"), new CAge(12));
delete pa; // Must delete CAge 11 to avoid memory leak.
}
#ifdef _DEBUG
afxDump << _T("after Lisa's birthday: ") << &map << _T("\n");
#endif
此程序的结果如下所示：
before Lisa's birthday: A CMapStringToOb with 2 elements
[Lisa] = a CAge at $493C 11
[Bart] = a CAge at $4654 13
after Lisa's birthday: A CMapStringToOb with 2 elements
[Lisa] = a CAge at $49C0 12
[Bart] = a CAge at $4654 13
另请参阅
CObject 类
层次结构图
CMapPtrToPtr 类
CMapPtrToWord 类
CMapStringToPtr 类
CMapStringToString 类
CMapWordToOb 类
CMapWordToPtr 类
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈