共用方式為

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* （element） 插入對應之後，您可以使用字串或 CString 值作為索引鍵，有效率地擷取或刪除配對。 您也可以逐一查看地圖中的所有元素。

類型的 POSITION 變數用於所有對應變化中的替代專案存取。 您可以使用 POSITION 來「記住」專案，並逐一查看地圖。 您可能會認為此反復專案是依索引鍵值循序的;不是。 擷取的專案序列不確定。

CMapStringToOb 引入 IMPLEMENT_SERIAL 巨集，以支援其項目的序列化和傾印。 如果對應儲存至封存，則會使用多載插入 （ << ） 運算子或 Serialize 成員函式來序列化每個元素。

如果您需要對應中個別專案的診斷傾印（ CString 值和 CObject 內容），您必須將傾印內容的深度設定為 1 或更大。

CMapStringToOb刪除物件時，或移除其專案時，會 CString 移除物件和 CObject 指標。 指標所 CObject 參考的物件不會終結。

對應類別衍生類似于清單衍生。 如需特殊用途清單類別衍生的圖例，請參閱 Collections 一文 。

繼承階層架構

CObject

CMapStringToOb

需求

標頭：afxcoll.h

CMapStringToOb::CMapStringToOb

建構空 CString 的 -to- CObject* map。

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 的 map 元素，然後更新 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

傳回 POSITION 可傳遞至 GetNextAssoc 呼叫的值，以啟動地圖反復專案。

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 的參考;如果 NULL 對應是空的或 key 超出範圍，則為 。

備註

因此，它只能在工作分派語句 （an l-value ） 的左側使用。 如果沒有具有指定索引鍵的 map 元素，則會建立新的專案。

沒有與這個運算子相等的「右側」（ 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 類