共用方式為


CMap 類別

字典集合類別,這個類別會將唯一索引鍵對應至值。

語法

template<class KEY, class ARG_KEY, class VALUE, class ARG_VALUE>class CMap : public CObject

參數

KEY
做為對應索引鍵的物件類別。

ARG_KEY
用於 KEY 自變數的數據類型;通常是 的 KEY參考。

VALUE
儲存在地圖中之對象的類別。

ARG_VALUE
用於 VALUE 自變數的數據類型;通常是 的 VALUE參考。

成員

公用結構

名稱 描述
CMap::CPair 巢狀結構,包含索引鍵值和相關聯物件的值。

公用建構函式

名稱 描述
CMap::CMap 建構將索引鍵對應至值的集合。

公用方法

名稱 描述
CMap::GetCount 傳回此對應中的項目數目。
CMap::GetHashTableSize 傳回哈希表中的項目數。
CMap::GetNextAssoc 取得反覆運算的下一個專案。
CMap::GetSize 傳回此對應中的項目數目。
CMap::GetStartPosition 傳回第一個專案的位置。
CMap::InitHashTable 初始化哈希表並指定其大小。
CMap::IsEmpty 測試空白對應條件 (沒有元素)。
CMap::Lookup 查閱對應至指定索引鍵的值。
CMap::PGetFirstAssoc 傳回第一個專案的指標。
CMap::PGetNextAssoc 取得下一個專案的指標以進行反覆運算。
CMap::PLookup 傳回索引鍵的指標,其值符合指定的值。
CMap::RemoveAll 從這個對應中移除所有元素。
CMap::RemoveKey 拿掉索引鍵所指定的專案。
CMap::SetAt 將專案插入對應中;如果找到相符的索引鍵,則會取代現有的專案。

公用運算子

名稱 描述
CMap::operator [ ] 將專案插入對應中, 運算子取代 SetAt

備註

將索引鍵/值組 (element) 插入對應之後,您就可以使用索引鍵有效地擷取或刪除配對來存取它。 您也可以逐一查看地圖中的所有元素。

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

這個類別的某些成員函式會呼叫全域協助程式函式,這些函式必須針對類別的大部分 CMap 用途進行自定義。 請參閱 MFC 參考的宏和全域一節中的集合類別協助程式

CMapCObject::Serialize覆寫以支援其元素的串行化和傾印。 如果使用 將地圖儲存至封存 Serialize,則會接著串行化每個對應專案。 協助程式函式的預設實作 SerializeElements 會進行位寫入。 如需衍生自 CObject 或其他使用者定義型別之指標集合專案串行化的相關信息,請參閱 如何:建立型別安全集合

如果您需要對應中個別項目的診斷傾印(索引鍵和值),您必須將傾印內容的深度設定為 1 或更大。

CMap刪除物件時,或移除其專案時,會移除索引鍵和值。

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

繼承階層架構

CObject

CMap

需求

標頭: afxtempl.h

CMap::CMap

建構空的對應。

CMap(INT_PTR nBlockSize = 10);

參數

nBlockSize
指定擴充地圖的記憶體配置粒度。

備註

隨著對應成長,記憶體會以專案單位 nBlockSize 配置。

範例

// declares a map of ints to points
CMap<int, int, CPoint, CPoint> myMap(16);

CMap::CPair

包含索引鍵值和相關聯物件的值。

備註

這是類別 CMap內的巢狀結構。

結構是由兩個字段所組成:

  • key 索引鍵類型的實際值。

  • value 相關聯物件的值。

它用來儲存、 CMap::PLookupCMap::PGetFirstAssocCMap::PGetNextAssoc的傳回值。

範例

如需使用方式的範例,請參閱 的 CMap::PLookup範例。

CMap::GetCount

擷取對應中的項目數目。

INT_PTR GetCount() const;

傳回值

項目的數目。

範例

請參閱 CMap::Lookup 的範例。

CMap::GetHashTableSize

決定對應之哈希表中的項目數目。

UINT GetHashTableSize() const;

傳回值

哈希表中的項目數目。

範例

CMap<int, int, CPoint, CPoint> myMap;

UINT uTableSize = myMap.GetHashTableSize();

CMap::GetNextAssoc

擷取位於 rNextPosition的 map 元素,然後更新 rNextPosition 以參考對應中的下一個專案。

void GetNextAssoc(
    POSITION& rNextPosition,
    KEY& rKey,
    VALUE& rValue) const;

參數

rNextPosition
指定先前GetNextAssocGetStartPosition呼叫所傳回值的參考POSITION

KEY
指定對應索引鍵類型的樣板參數。

rKey
指定所擷取項目的傳回索引鍵。

VALUE
指定地圖值類型的樣板參數。

rValue
指定擷取之項目的傳回值。

備註

此函式最適合逐一查看對應中的所有元素。 請注意,位置序列不一定與索引鍵值序列相同。

如果擷取的項目是對應中的最後一個,則的新值 rNextPosition 會設定為 NULL

範例

請參閱 CMap::SetAt 的範例。

CMap::GetSize

傳回對應項目的數目。

INT_PTR GetSize() const;

傳回值

地圖中的項目數目。

備註

呼叫此方法以擷取地圖中的項目數目。

範例

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

CMap::GetStartPosition

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

POSITION GetStartPosition() const;

傳回值

POSITION值,表示用於反覆運算地圖的起始位置;如果NULL地圖是空的,則為 。

備註

反覆專案序列無法預測;因此,「地圖中的第一個專案」沒有特殊意義。

範例

請參閱 CMap::SetAt 的範例。

CMap::InitHashTable

初始化哈希表。

void InitHashTable(UINT hashSize, BOOL  bAllocNow = TRUE);

參數

hashSize
哈希表中的項目數。

bAllocNow
如果 TRUE為 ,則會在初始化時配置哈希表,否則會視需要配置數據表。

備註

為了獲得最佳效能,哈希表大小應該是質數。 若要將衝突降到最低,大小應該比預期的數據集大約 20%。

範例

請參閱 CMap::Lookup 的範例。

CMap::IsEmpty

判斷地圖是否為空白。

BOOL IsEmpty() const;

傳回值

如果此對應不包含任何元素,則為非零;否則為 0。

範例

請參閱 CMap::RemoveAll 的範例。

CMap::Lookup

查閱對應至指定索引鍵的值。

BOOL Lookup(ARG_KEY key, VALUE& rValue) const;

參數

ARG_KEY
指定值類型的 key 樣板參數。

key
指定要查閱之專案的索引鍵。

VALUE
指定要查閱之值的型別。

rValue
接收查閱的值。

傳回值

如果找到專案,則為非零;否則為 0。

備註

Lookup 使用哈希演算法,快速尋找對應元素,其索引鍵完全符合指定的索引鍵。

範例

CMap<int, int, CPoint, CPoint> myMap;

myMap.InitHashTable(257);

// Add 200 elements to the map.
for (int i = 0; i < 200; i++)
{
   myMap[i] = CPoint(i, i);
}

// Remove the elements with even key values.
CPoint pt;
for (int i = 0; myMap.Lookup(i, pt); i += 2)
{
   myMap.RemoveKey(i);
}

ASSERT(myMap.GetSize() == 100);
TRACE(_T("myMap with %d elements:\n"), myMap.GetCount());
POSITION pos = myMap.GetStartPosition();
int iKey;
CPoint ptVal;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, iKey, ptVal);
   TRACE(_T("\t[%d] = (%d,%d)\n"), iKey, ptVal.x, ptVal.y);
}

CMap::operator [ ]

方便取代 SetAt 成員函式。

VALUE& operator[](arg_key key);

參數

VALUE
指定地圖值的型別的樣板參數。

ARG_KEY
指定索引鍵值類型的樣板參數。

key
用來從地圖擷取值的索引鍵。

備註

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

沒有與這個運算符相等的「右側」(r-value),因為有可能在對應中找不到索引鍵。 Lookup使用成員函式來擷取專案。

範例

請參閱 CMap::Lookup 的範例。

CMap::PGetFirstAssoc

傳回 map 物件的第一個專案。

const CPair* PGetFirstAssoc() const;
CPair* PGetFirstAssoc();

傳回值

對應中第一個專案的指標;請參閱 CMap::CPair。 如果對應未包含任何專案,則值為 NULL

備註

呼叫此函式以傳回 map 物件中第一個專案的指標。

範例

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Print the element value with even key values.
int nKey = 0;
CPoint pt;
CMyMap::CPair *pCurVal;

pCurVal = myMap.PGetFirstAssoc();
while (pCurVal != NULL)
{
   if ((nKey % 2) == 0)
   {
      _tprintf_s(_T("Current key value at %d: %d,%d\n"),
                 pCurVal->key, pCurVal->value.x, pCurVal->value.y);
   }
   pCurVal = myMap.PGetNextAssoc(pCurVal);
   nKey++;
}

CMap::PGetNextAssoc

擷取 所指向的 pAssocRec對應專案。

const CPair *PGetNextAssoc(const CPair* pAssocRet) const;

CPair *PGetNextAssoc(const CPair* pAssocRet);

參數

pAssocRet
指向上 PGetNextAssoc 一個或 CMap::PGetFirstAssoc 呼叫傳回的對應專案。

傳回值

對應中下一個專案的指標;請參閱 CMap::CPair。 如果元素是對應的最後一個元素, 則值為 NULL

備註

呼叫此方法以逐一查看地圖中的所有專案。 擷取第一個具有 呼叫 PGetFirstAssoc 的項目,然後使用對的後續呼叫 PGetNextAssoc逐一查看對應。

範例

請參閱 CMap::PGetFirstAssoc 的範例。

CMap::PLookup

尋找對應至指定索引鍵的值。

const CPair* PLookup(ARG_KEY key) const;
CPair* PLookup(ARG_KEY key);

參數

key
要搜尋之專案的索引鍵。

傳回值

索引鍵結構的指標;請參閱 CMap::CPair。 如果找不到相符專案, CMap::PLookup 則傳 NULL回 。

備註

呼叫此方法,以搜尋具有完全符合指定索引鍵的對應專案。

範例

typedef CMap<int, int, CPoint, CPoint> CMyMap;
CMyMap myMap;

myMap.InitHashTable(257);

// Add 10 elements to the map.
for (int i = 0; i <= 10; i++)
   myMap[i] = CPoint(i, i);

// Print the element values with even key values.
CMyMap::CPair *pCurVal;

for (int i = 0; i <= myMap.GetCount(); i += 2)
{
   pCurVal = myMap.PLookup(i);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              pCurVal->key, pCurVal->value.x, pCurVal->value.y);
}

CMap::RemoveAll

藉由呼叫全域協助程式函式 DestructElements,從這個對應中移除所有值。

void RemoveAll();

備註

如果對應已經是空的,函式就會正常運作。

範例

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

myMap.RemoveAll();

ASSERT(myMap.IsEmpty());

CMap::RemoveKey

查閱對應至所提供索引鍵的對應專案;然後,如果找到索引鍵,則會移除專案。

BOOL RemoveKey(ARG_KEY key);

參數

ARG_KEY
指定索引鍵類型的範本參數。

key
要移除之專案的索引鍵。

傳回值

如果找到並成功移除專案,則為非零;否則為 0。

備註

協助 DestructElements 程式函式是用來移除專案。

範例

請參閱 CMap::SetAt 的範例。

CMap::SetAt

主要表示在對應中插入專案。

void SetAt(ARG_KEY key, ARG_VALUE newValue);

參數

ARG_KEY
指定參數類型的 key 範本參數。

key
指定新專案的索引鍵。

ARG_VALUE
指定參數類型的 newValue 範本參數。

newValue
指定新元素的值。

備註

首先,會查閱金鑰。 如果找到索引鍵,則會變更對應的值;否則會建立新的機碼/值組。

範例

CMap<int, int, CPoint, CPoint> myMap;

// Add 10 elements to the map.
for (int i = 0; i < 10; i++)
   myMap.SetAt(i, CPoint(i, i));

// Remove the elements with even key values.
POSITION pos = myMap.GetStartPosition();
int nKey;
CPoint pt;
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);

   if ((nKey % 2) == 0)
      myMap.RemoveKey(nKey);
}

// Print the element values.
pos = myMap.GetStartPosition();
while (pos != NULL)
{
   myMap.GetNextAssoc(pos, nKey, pt);
   _tprintf_s(_T("Current key value at %d: %d,%d\n"),
              nKey, pt.x, pt.y);
}

另請參閱

MFC 範例 COLLECT
CObject
階層架構圖表