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 元素類型。