`CMap` 類別

發行項
07/05/2024

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

語法

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::PGetFirstAssoc和 CMap::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
指定先前GetNextAssoc或GetStartPosition呼叫所傳回值的參考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 類
 階層架構圖表

共用方式為

CMap 類別

語法

參數

成員

公用結構

公用建構函式

公用方法

公用運算子

備註

繼承階層架構

需求

CMap::CMap

參數

備註

範例

CMap::CPair

備註

範例

CMap::GetCount

傳回值

範例

CMap::GetHashTableSize

傳回值

範例

CMap::GetNextAssoc

參數

備註

範例

CMap::GetSize

傳回值

備註

範例

CMap::GetStartPosition

傳回值

備註

範例

CMap::InitHashTable

參數

備註

範例

CMap::IsEmpty

傳回值

範例

CMap::Lookup

參數

傳回值

備註

範例

CMap::operator [ ]

參數

備註

範例

CMap::PGetFirstAssoc

傳回值

備註

範例

CMap::PGetNextAssoc

參數

傳回值

備註

範例

CMap::PLookup

參數

傳回值

備註

範例

CMap::RemoveAll

備註

範例

CMap::RemoveKey

參數

傳回值

備註

範例

CMap::SetAt

參數

備註

範例

另請參閱

`CMap` 類別

`CMap::CMap`

`CMap::CPair`

`CMap::GetCount`

`CMap::GetHashTableSize`

`CMap::GetNextAssoc`

`CMap::GetSize`

`CMap::GetStartPosition`

`CMap::InitHashTable`

`CMap::IsEmpty`

`CMap::Lookup`

`CMap::operator [ ]`

`CMap::PGetFirstAssoc`

`CMap::PGetNextAssoc`

`CMap::PLookup`

`CMap::RemoveAll`

`CMap::RemoveKey`

`CMap::SetAt`