通过

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 指针引用的对象不会被销毁。

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

继承层次结构

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 类