CAtlMap 類別

這個類別提供建立和管理地圖物件的方法。

語法

template <typename K,
          typename V,
          class KTraits = CElementTraits<K>,
          class VTraits = CElementTraits<V>>
class CAtlMap

參數

K
索引鍵專案類型。

V
value 元素類型。

KTraits
用來複製或移動索引鍵元素的程式碼。 如需詳細資訊，請參閱 CElementTraits 類別 。

VTraits
用來複製或移動值元素的程式碼。

成員

公用 Typedefs

名稱	描述
CAtlMap：：KINARGTYPE	當金鑰當做輸入引數傳遞時所使用的類型
CAtlMap：：KOUTARGTYPE	當索引鍵當做輸出引數傳回時所使用的類型。
CAtlMap：：VINARGTYPE	當值當做輸入引數傳遞時所使用的類型。
CAtlMap：：VOUTARGTYPE	當值當做輸出引數傳遞時所使用的類型。

公用類別

名稱	描述
CAtlMap：：CPair 類別	類別，包含索引鍵和值專案。

CPair 資料成員

名稱	描述
CPair：：m_key	儲存索引鍵元素的資料成員。
CPair：：m_value	儲存 value 元素的資料成員。

公用建構函式

名稱	描述
CAtlMap：：CAtlMap	建構函式。
CAtlMap：：~CAtlMap	解構函式。

公用方法

名稱	描述
CAtlMap：：AssertValid	呼叫這個方法，以在 無效時 CAtlMap 造成 ASSERT。
CAtlMap：:D isableAutoRehash	呼叫此方法以停用物件的自動重新套用 CAtlMap 。
CAtlMap：：EnableAutoRehash	呼叫此方法以啟用物件的自動重新套用 CAtlMap 。
CAtlMap：：GetAt	呼叫這個方法，傳回位於地圖中指定位置的專案。
CAtlMap：：GetCount	呼叫此方法以擷取地圖中的專案數目。
CAtlMap：：GetHashTableSize	呼叫這個方法，以判斷對應雜湊表中的 bin 數目。
CAtlMap：：GetKeyAt	呼叫這個方法，以擷取儲存在 物件中指定位置的 CAtlMap 索引鍵。
CAtlMap：：GetNext	呼叫這個方法，以取得儲存在 物件中之下一個專案組的 CAtlMap 指標。
CAtlMap：：GetNextAssoc	取得反覆運算的下一個專案。
CAtlMap：：GetNextKey	呼叫這個方法，從 CAtlMap 物件擷取下一個索引鍵。
CAtlMap：：GetNextValue	呼叫這個方法以從 CAtlMap 物件取得下一個值。
CAtlMap：：GetStartPosition	呼叫此方法以啟動地圖反復專案。
CAtlMap：：GetValueAt	呼叫這個方法，以擷取儲存在 物件中指定位置的值 CAtlMap 。
CAtlMap：：InitHashTable	呼叫此方法以初始化雜湊表。
CAtlMap：：IsEmpty	呼叫此方法以測試空的地圖物件。
CAtlMap：：Lookup	呼叫此方法以查閱 物件中的 CAtlMap 索引鍵或值。
CAtlMap：：Rehash	呼叫此方法以重新叫用 CAtlMap 物件。
CAtlMap：：RemoveAll	呼叫這個方法，以移除 CAtlMap 物件中的所有專案。
CAtlMap：：RemoveAtPos	呼叫這個方法，以移除物件中指定位置的專案 CAtlMap 。
CAtlMap：：RemoveKey	呼叫這個方法，以從 CAtlMap 物件中移除專案，並指定索引鍵。
CAtlMap：：SetAt	呼叫這個方法，將專案組插入對應中。
CAtlMap：：SetOptimalLoad	呼叫這個方法以設定物件的最佳負載 CAtlMap 。
CAtlMap：：SetValueAt	呼叫這個方法，以變更儲存在 物件中指定位置的值 CAtlMap 。

公用運算子

名稱	描述
CAtlMap：：operator[]	將新的專案取代或加入至 CAtlMap 。

備註

CAtlMap 支援任何指定類型的對應陣列、管理索引鍵元素的未排序陣列及其相關聯的值。 元素（由索引鍵和值所組成）是使用雜湊演算法來儲存的，允許有效率地儲存和擷取大量資料。

KTraits 和 VTraits 參數是特性類別，其中包含複製或移動元素所需的任何補充程式碼。

CRBMap 類別提供 替代 CAtlMap 專案。 CRBMap 也會儲存索引鍵/值組，但表現出不同的效能特性。 插入專案、查閱索引鍵或刪除物件索引鍵 CRBMap 所花費的時間是 order log（n） ，其中 n 是元素數目。 針對 CAtlMap ，所有這些作業通常需要一段時間，不過最差的情況可能順序 為 n 。 因此，在一般情況下， CAtlMap 速度較快。

和 之間的 CRBMapCAtlMap 其他差異在逐一查看預存元素時變得明顯。 在 中 CRBMap ，會以排序次序流覽元素。 在 中 CAtlMap ，不會排序元素，而且無法推斷任何順序。

需要儲存少量的元素時，請考慮改用 CSimpleMap 類別。

如需詳細資訊，請參閱 ATL 集合類別 。

需求

標頭： atlcoll.h

CAtlMap：：AssertValid

呼叫這個方法，以在物件無效時 CAtlMap 造成 ASSERT。

void AssertValid() const;

備註

在偵錯組建中，如果 CAtlMap 物件無效，這個方法將會導致 ASSERT。

範例

請參閱 CAtlMap：：CAtlMap 的範例 。

CAtlMap：：CAtlMap

建構函式。

CAtlMap(
    UINT nBins = 17,
    float fOptimalLoad = 0.75f,
    float fLoThreshold = 0.25f,
    float fHiThreshold = 2.25f,
    UINT nBlockSize = 10) throw ();

參數

nBins
提供預存元素指標的 bin 數目。 如需 bin 的說明，請參閱本主題稍後的。

fOptimalLoad
最佳負載比率。

fLoThreshold
負載比率的下限。

fHiThreshold
負載比率的臨界值上限。

nBlockSize
區塊大小。

備註

CAtlMap 先使用索引鍵上的雜湊演算法建立索引，以參考其所有儲存的專案。 此索引會參考 「bin」，其中包含預存專案的指標。 如果 bin 已在使用中，則會建立連結清單來存取後續元素。 周遊清單的速度比直接存取正確的元素慢，因此對應結構需要平衡儲存體需求與效能。 在大部分情況下，已選擇預設參數來提供良好的結果。

負載比率是 bin 數目與 map 物件中儲存之元素數目的比率。 重新計算對應結構時， 將會使用 fOptimalLoad 參數值來計算所需的間隔數目。 您可以使用 CAtlMap：：SetOptimalLoad 方法變更 此值。

fLoThreshold 參數是負載比率可以達到的較低值，然後 CAtlMap 才會重新計算地圖的最佳大小。

fHiThreshold 參數是負載比率可以達到的上限值， CAtlMap 物件才會重新計算地圖的最佳大小。

預設會啟用此重新計算程式（稱為重新叫用）。 如果您想要停用此程式，或許一次輸入大量資料時，請呼叫 CAtlMap：:D isableAutoRehash 方法。 使用 CAtlMap：：EnableAutoRehash 方法重新啟用它。

nBlockSize 參數是需要新元素時所配置的記憶體數量量值。 較大的區塊大小可減少對記憶體配置常式的呼叫，但會使用更多資源。

在儲存任何資料之前，必須先使用 CAtlMap：：InitHashTable 的 呼叫來初始化雜湊表。

範例

// Create a map which stores a double
// value using an integer key

CAtlMap<int, double> mySinTable;
int i;

// Initialize the Hash Table
mySinTable.InitHashTable(257);

// Add items to the map
for (i = 0; i < 90; i++)
   mySinTable[i] = sin((double)i);

// Confirm the map is valid
mySinTable.AssertValid();

// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 90);

// Remove elements with even key values
for (i = 0; i < 90; i += 2)
   mySinTable.RemoveKey(i);

// Confirm the number of elements in the map
ATLASSERT(mySinTable.GetCount() == 45);

// Walk through all the elements in the map.
// First, get start position.
POSITION pos;
int key;
double value;
pos = mySinTable.GetStartPosition();

// Now iterate the map, element by element
while (pos != NULL) 
{
   key = mySinTable.GetKeyAt(pos);
   value = mySinTable.GetNextValue(pos);
}

CAtlMap：：~CAtlMap

解構函式。

~CAtlMap() throw();

備註

釋放任何已配置的資源。

CAtlMap：：CPair 類別

類別，包含索引鍵和值專案。

class CPair : public __POSITION

備註

CAtlMap：：GetNext 和 CAtlMap：：Lookup 方法 會使用此類別來存取儲存在對應結構中的索引鍵和值元素。

CAtlMap：:D isableAutoRehash

呼叫此方法以停用物件的自動重新套用 CAtlMap 。

void DisableAutoRehash() throw();

備註

啟用自動重新套用時（預設為這樣），如果載入值（間隔數目與陣列中儲存的專案數目的比例）超過對應建立時所指定的最大值或最小值，雜湊表中的 bin 數目將會自動重新計算。

DisableAutoRehash 當大量專案一次新增至地圖時，最有用。 每次超過限制時，不要觸發重新套用程式，而是更有效率地呼叫 DisableAutoRehash 、新增元素，最後呼叫 CAtlMap：：EnableAutoRehash 。

CAtlMap：：EnableAutoRehash

呼叫此方法以啟用物件的自動重新套用 CAtlMap 。

void EnableAutoRehash() throw();

備註

啟用自動重新套用時，如果載入值（間隔數目與儲存在陣列中的元素數目）超過建立對應時所指定的最大值或最小值，雜湊表中的 bin 數目就會自動重新計算。

EnableAutoRefresh 最常在呼叫 CAtlMap：:D isableAutoRehash 之後使用。

CAtlMap：：GetAt

呼叫這個方法，傳回位於地圖中指定位置的專案。

void GetAt(
    POSITION pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

CPair* GetAt(POSITION& pos) throw();

參數

pos
前一次呼叫 CAtlMap：：GetNextAssoc 或 CAtlMap：：GetStartPosition 所傳回的位置計數器。

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

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

傳回值

傳回對應中儲存之目前索引鍵/值專案組的指標。

備註

在偵錯組建中，如果 pos 等於 Null，就會發生判斷提示錯誤。

CAtlMap：：GetCount

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

size_t GetCount() const throw();

傳回值

傳回 map 物件中的專案數目。 單一元素是索引鍵/值組。

範例

請參閱 CAtlMap：：CAtlMap 的範例 。

CAtlMap：：GetHashTableSize

呼叫這個方法，以判斷對應雜湊表中的 bin 數目。

UINT GetHashTableSize() const throw();

傳回值

傳回雜湊表中的 bin 數目。 如需說明，請參閱 CAtlMap：：CAtlMap 。

CAtlMap：：GetKeyAt

呼叫這個方法，以擷取儲存在 物件中指定位置的 CAtlMap 索引鍵。

const K& GetKeyAt(POSITION pos) const throw();

參數

pos
前一次呼叫 CAtlMap：：GetNextAssoc 或 CAtlMap：：GetStartPosition 所傳回的位置計數器。

傳回值

傳回儲存在 物件中指定位置之索引鍵的 CAtlMap 參考。

範例

請參閱 CAtlMap：：CAtlMap 的範例 。

CAtlMap：：GetNext

呼叫這個方法，以取得儲存在 物件中之下一個專案組的 CAtlMap 指標。

CPair* GetNext(POSITION& pos) throw();
const CPair* GetNext(POSITION& pos) const throw();

參數

pos
前一次呼叫 CAtlMap：：GetNextAssoc 或 CAtlMap：：GetStartPosition 所傳回的位置計數器。

傳回值

傳回對應中儲存之下一組索引鍵/值元素的指標。 每次呼叫之後都會更新 pos 位置計數器。 如果擷取的專案是對應中的最後一個專案， pos 會設定為 Null。

CAtlMap：：GetNextAssoc

取得反覆運算的下一個專案。

void GetNextAssoc(
    POSITION& pos,
    KOUTARGTYPE key,
    VOUTARGTYPE value) const;

參數

pos
前一次呼叫 CAtlMap：：GetNextAssoc 或 CAtlMap：：GetStartPosition 所傳回的位置計數器。

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

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

備註

每次呼叫之後都會更新 pos 位置計數器。 如果擷取的專案是對應中的最後一個專案， pos 會設定為 Null。

CAtlMap：：GetNextKey

呼叫這個方法，從 CAtlMap 物件擷取下一個索引鍵。

const K& GetNextKey(POSITION& pos) const throw();

參數

pos
前一次呼叫 CAtlMap：：GetNextAssoc 或 CAtlMap：：GetStartPosition 所傳回的位置計數器。

傳回值

傳回對應中下一個索引鍵的參考。

備註

更新目前的位置計數器 pos 。如果地圖中沒有其他專案，則位置計數器會設定為 Null。

CAtlMap：：GetNextValue

呼叫這個方法以從 CAtlMap 物件取得下一個值。

V& GetNextValue(POSITION& pos) throw();
const V& GetNextValue(POSITION& pos) const throw();

參數

pos
前一次呼叫 CAtlMap：：GetNextAssoc 或 CAtlMap：：GetStartPosition 所傳回的位置計數器。

傳回值

傳回對應中下一個值的參考。

備註

更新目前的位置計數器 pos 。如果地圖中沒有其他專案，則位置計數器會設定為 Null。

範例

請參閱 CAtlMap：：CAtlMap 的範例 。

CAtlMap：：GetStartPosition

呼叫此方法以啟動地圖反復專案。

POSITION GetStartPosition() const throw();

傳回值

傳回開始位置，如果地圖是空的，則會傳回 Null。

備註

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

注意

反復專案序列無法預測

範例

請參閱 CAtlMap：：CAtlMap 的範例 。

CAtlMap：：GetValueAt

呼叫這個方法，以擷取儲存在 物件中指定位置的值 CAtlMap 。

V& GetValueAt(POSITION pos) throw();
const V& GetValueAt(POSITION pos) const throw();

參數

pos
前一次呼叫 CAtlMap：：GetNextAssoc 或 CAtlMap：：GetStartPosition 所傳回的位置計數器。

傳回值

傳回物件中指定位置 CAtlMap 所儲存值的參考。

CAtlMap：：InitHashTable

呼叫此方法以初始化雜湊表。

bool InitHashTable(
    UINT nBins,
    bool bAllocNow = true);

參數

nBins
雜湊表所使用的 bin 數目。 如需說明，請參閱 CAtlMap：：CAtlMap 。

bAllocNow
應配置記憶體的旗標指示。

傳回值

在成功初始化時傳回 TRUE，失敗時傳回 FALSE。

備註

InitHashTable 在雜湊表中儲存任何專案之前，必須先呼叫 。 如果未明確呼叫這個方法，則第一次使用建構函式指定的 CAtlMap bin 計數新增專案時，會自動呼叫此方法。 否則，將會使用 nBins 參數所 指定的新 bin 計數來初始化對應。

如果 bAllocNow 參數為 false，雜湊表所需的記憶體將不會配置，直到第一次需要為止。 如果不確定是否將使用地圖，這非常有用。

範例

請參閱 CAtlMap：：CAtlMap 的範例 。

CAtlMap：：IsEmpty

呼叫此方法以測試空的地圖物件。

bool IsEmpty() const throw();

傳回值

如果對應是空的，則傳回 TRUE，否則傳回 FALSE。

CAtlMap：：KINARGTYPE

當金鑰傳遞為輸入引數時所使用的類型。

typedef KTraits::INARGTYPE KINARGTYPE;

CAtlMap：：KOUTARGTYPE

當索引鍵當做輸出引數傳回時所使用的類型。

typedef KTraits::OUTARGTYPE KOUTARGTYPE;

CAtlMap：：Lookup

呼叫此方法以查閱 物件中的 CAtlMap 索引鍵或值。

bool Lookup(KINARGTYPE key, VOUTARGTYPE value) const;
const CPair* Lookup(KINARGTYPE key) const throw();
CPair* Lookup(KINARGTYPE key) throw();

參數

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

value
接收查閱值的變數。

傳回值

如果找到索引鍵，則方法的第一種形式會傳回 true，否則為 false。 第二個和第三個表單會傳回 CPair 的 指標，可用來做為 CAtlMap ：：GetNext 呼叫的位置等等。

備註

Lookup 會使用雜湊演算法快速尋找對應專案，其中包含完全符合指定索引鍵參數的索引鍵。

CAtlMap：：operator []

將新的專案取代或加入至 CAtlMap 。

V& operator[](kinargtype key) throw();

參數

key
要加入或取代之專案的索引鍵。

傳回值

傳回與指定索引鍵相關聯之值的參考。

範例

如果索引鍵已經存在，則會取代 專案。 如果索引鍵不存在，則會加入新的專案。 請參閱 CAtlMap：：CAtlMap 的範例 。

CAtlMap：：Rehash

呼叫此方法以重新叫用 CAtlMap 物件。

void Rehash(UINT nBins = 0);

參數

nBins
雜湊表中要使用的新間隔數目。 如需說明，請參閱 CAtlMap：：CAtlMap 。

備註

如果 nBins 為 0， CAtlMap 請根據地圖中的元素數目和最佳負載設定來計算合理的數位。 重新套用程式通常是自動的，但如果 已呼叫 CAtlMap：:D isableAutoRehash ，這個方法將會執行必要的調整大小。

CAtlMap：：RemoveAll

呼叫這個方法，以移除 CAtlMap 物件中的所有專案。

void RemoveAll() throw();

備註

CAtlMap清除 物件，釋放用來儲存元素的記憶體。

CAtlMap：：RemoveAtPos

呼叫這個方法，以移除物件中指定位置的專案 CAtlMap 。

void RemoveAtPos(POSITION pos) throw();

參數

pos
前一次呼叫 CAtlMap：：GetNextAssoc 或 CAtlMap：：GetStartPosition 所傳回的位置計數器。

備註

移除儲存在指定位置的索引鍵/值組。 用來儲存專案的記憶體會釋出。 pos 所 參考的 POSITION 會變成無效，而對應中任何其他元素的 POSITION 仍然有效時，它們不一定會保留相同的順序。

CAtlMap：：RemoveKey

呼叫這個方法，以從 CAtlMap 物件中移除專案，並指定索引鍵。

bool RemoveKey(KINARGTYPE key) throw();

參數

key
對應至您要移除之專案組的索引鍵。

傳回值

如果找到並移除索引鍵，則會傳回 TRUE，失敗時為 FALSE。

範例

請參閱 CAtlMap：：CAtlMap 的範例 。

CAtlMap：：SetAt

呼叫這個方法，將專案組插入對應中。

POSITION SetAt(
    KINARGTYPE key,
    VINARGTYPE value);

參數

key
要加入至 CAtlMap 物件的索引鍵值。

value
要加入至 CAtlMap 物件的值。

傳回值

傳回 物件中 CAtlMap 索引鍵/值專案組的位置。

備註

SetAt 如果找到相符的索引鍵，則會取代現有的專案。 如果找不到金鑰，則會建立新的索引鍵/值組。

CAtlMap：：SetOptimalLoad

呼叫這個方法以設定物件的最佳負載 CAtlMap 。

void SetOptimalLoad(
    float fOptimalLoad,
    float fLoThreshold,
    float fHiThreshold,
    bool bRehashNow = false);

參數

fOptimalLoad
最佳負載比率。

fLoThreshold
負載比率的下限。

fHiThreshold
負載比率的臨界值上限。

bRehashNow
指出是否應該重新計算雜湊表的旗標。

備註

這個方法會重新定義物件的最佳負載值 CAtlMap 。 如需各種參數的討論，請參閱 CAtlMap：：CAtlMap 。 如果 bRehashNow 為 true，且元素數目超出最小值和最大值，則會重新計算雜湊表。

CAtlMap：：SetValueAt

呼叫這個方法，以變更儲存在 物件中指定位置的值 CAtlMap 。

void SetValueAt(
    POSITION pos,
    VINARGTYPE value);

參數

pos
前一次呼叫 CAtlMap：：GetNextAssoc 或 CAtlMap：：GetStartPosition 所傳回的位置計數器。

value
要加入至 CAtlMap 物件的值。

備註

變更儲存在 物件中指定位置的值 CAtlMap 專案。

CAtlMap：：VINARGTYPE

當值當做輸入引數傳遞時所使用的類型。

typedef VTraits::INARGTYPE VINARGTYPE;

CAtlMap：：VOUTARGTYPE

當值當做輸出引數傳遞時所使用的類型。

typedef VTraits::OUTARGTYPE VOUTARGTYPE;

CAtlMap：：CPair：：m_key

儲存索引鍵元素的資料成員。

const K m_key;

參數

K
索引鍵專案類型。

CAtlMap：：CPair：：m_value

儲存 value 元素的資料成員。

V  m_value;

參數

V
value 元素類型。

另請參閱

選框範例
UpdatePV 範例
類別概觀