hash_multimap 類別

發行項
06/09/2015

注意事項
這個 API 已經過時。替代案例是 unordered_multimap 類別。

容器類別 hash_multimap 是標準樣板程式庫的擴充，為了從集合作資料儲存和快速擷取每個項目使用，集合中每一個項目都為一對分別為不需要是唯一的排序鍵値和相關的資料値。

template <
   class Key, 
   class Type, 
   class Traits=hash_compare<Key, less<Key> >, 
   class Allocator=allocator<pair <const Key, Type> > 
>
class hash_multimap

參數

Key
要存放在 hash_multimap 中的索引鍵資料類型。
Type
要存放在 hash_multimap 中的元素資料類型。
Traits
包含兩個函式物件的類型，而類別 Traits 來比較兩個項目值做為排序鍵來判斷其相對順序和對應項目的索引鍵值一元的述詞與型別 size_t 不帶正負號的整數的雜湊函式。此引數是選擇性的，而且預設值是 hash_compare<Key, less<Key> >。
Allocator
代表預存配置器物件 (此物件會封裝有關 hash_multimap 的配置和解除配置記憶體的詳細資訊) 的類型。此引數是選擇性的，而且預設值是 allocator<pair <const Key, Type> >。

備註

hash_multimap 如下:

關聯的容器，可變大小容器支援項目值是以關聯的索引鍵值有效的擷取。
可逆轉的，因為它提供雙向的迭代器以存取其項目。
可雜湊的，因為它的項目是根據雜湊函式值的套用至雜湊桶元素的索引鍵值分組。
倍數，因為它的項目不需要有唯一索引鍵，因此，一個鍵值可以有多個資料值與它相關。
一個成對關聯的容器，因為其元素的值和其索引鍵值是不同的。
樣板類別，因為它提供的功能是泛型和很獨立的做為項目或索引鍵包含資料的特定型別。套用至項目和索引鍵的資料型別，和比較函式和配置器一起被指定為類別樣板的參數。

雜湊的主要好處在排序是較大的效率；成功的雜湊中常數的平均時間執行插入、刪除和尋找時間比較比例與項目數目的對數容器中的排序方式。可以直接變更在 hash_multimap 的項目的值，除了沒有關聯的索引鍵值。因此，與舊項目相關聯的索引鍵值必須刪除，而必須為新項目插入新的索引鍵值。

選擇容器型別時，應根據應用程式所需的搜尋和插入的型別。雜湊關聯的容器最適合進行搜尋、插入和移除作業。明確支援這些作業的成員函式很有效率，當搭配設計完善的雜湊函式，執行它們在期間平均常數和不相依於項目數目的容器。設計良好的雜湊函式產生雜湊值的制式散發並降低衝突數，此衝突發生於獨特索引鍵值會對應至相同雜湊值時。在最壞的情況下，最壞的雜湊函式，作業數目與項目數目成正比順序 (線性時間)。

表示滿足應用程式的關聯值的條件與其索引鍵時，hash_multimap 應是相關的容器。這種結構的模型是索引鍵的排序清單與提供的關聯字串値，為定義，而這不總是被唯一定義的。如果，相反地，關鍵字唯一定義，使索引鍵是唯一的，則 hash_map 是選擇的容器。另一方面，如果儲存文字清單，則 hash_set 是無效的容器。如果文字的多個事件允許，則 hash_multiset 是適當的容器結構。

藉由呼叫型別為 value_compare的雜湊 Traits 物件以控制 hash_multimap 的排序序列。這個儲存物件可以透過呼叫成員函式 key_comp 存取。這類函式物件必須與類別 hash_compare<Key, less<Key> > 有相同的運作。具體來說，所有為型別 Key的值 Key ，呼叫 Traits (Key) 產生型別 size_t 的值的分布。

通常，項目必須是小於比較才能排序，因此若提供了兩個項目，可以判斷它們相等 (任一個都不小於另一個的意義)，或者一個小於另一個。這會導致在非對等元件之間的排序在一個技術提示，比較函式是產生在標準數學概念的嚴格弱式順序的二元述詞。二進位述詞 f(x, y) 是有兩個引數 x 和 y 和回傳值 true 或 false 的函式物件。如果二進位述詞是非反身屬性、非對稱的、可傳遞的，且如果等價是傳遞性的，其中兩個物件的 x 和 y 定義相等，當兩個 f(x, y) 和 f(x, y) 是 false 的，則給 hash_multimap 安排嚴格弱式順序。如果索引鍵之間相等的更強狀況取代原本的相等，則該定序變得全部 (也就是所有項目的排序將有關於其他項目)，因此相符索引鍵的項目與其他項目將難以辨別。

項目實際順序在受控制序列中取決於雜湊函式、排序函式及容器物件儲存的雜湊資料表的目前大小。您無法判斷雜湊資料表的目前大小，因此，您無法預測一般項目順序是在受控制序列的。插入項目不會使任何迭代器無效，移除項目則僅會使特別指向被移除的項目的迭代器無效。

hash_multimap 類別提供的迭代器是雙向的迭代器，不過類別成員函式 insert 和 hash_multimap 擁有以樣板參數作為較弱的輸入迭代器之版本，其功能要求較雙向迭代器的類別少。不同的迭代器概念因其功能的修改而有關聯性。每個迭代器概念有自己的 hash_multimap 需求，因此，使用它們需要限制其假定對要求的演算法由該迭代器提供。可能會假設輸入迭代器可能已取值參考物件的陣列，而且可能會加入至序列中的下一個迭代器。這是最小的 hash_multimap 功能，不過，它是足夠可以在成員函式中有意義地溝通有關迭代器 [First, Last) 範圍。

在 Visual C++ .NET 2003 中， <hash_map> 和 <hash_set> 標頭檔的成員不在 std 命名空間中，而是移至 stdext 命名空間。如需詳細資訊，請參閱 stdext 命名空間。

建構函式

hash_multimap

建構特定大小的清單，或具有特定值之項目的清單，或具有特定 allocator 的清單，或是做為其他 hash_multimap 對應的複本。

Typedef

allocator_type	表示hash_multimap 物件的allocator 類別。
const_iterator	提供雙向迭代器的類型可以讀取 hash_multimap 中的任何 const 項目。
const_pointer	提供 hash_multimap 中 const 項目之指標的類型。
const_reference	類型，其提供儲存在 hash_multimap 中供讀取和執行 const 作業之 const 項目的參考。
const_reverse_iterator	提供雙向迭代器的類型可以讀取 hash_multimap 中的任何 const 項目。
difference_type	可以用來表示 hash_multimap 之項目的數目在某個範圍的項目之間的帶正負號的整數類資料型別指向迭代器。
Iterator	提供隨機存取雙向迭代器的型別，可以讀取或修改 hash_multimap 物件中的任何項目。
key_compare	可比較兩個排序鍵以判斷兩個項目在 hash_multimap 中的相對順序的函式物件之型別。
key_type	型別描述構成 hash_multimap的每個元素的排序鍵物件。
mapped_type	表示儲存在 hash_multimap 的資料型別。
指標	提供 hash_multimap 中一個元素的指標。
參照	提供 hash_multimap 中一個元素的參考。
reverse_iterator	提供隨機存取迭代器型別，可以讀取或修改 hash_multimap 物件中的任何項目。
size_type	可以表示 hash_multimap中的項目數不帶正負號的整數類資料型別。
value_type	可比較兩個排序鍵以判斷兩個項目在 hash_multimap 中的相對順序的函式物件之型別。

成員函式

begin	傳回迭代器，為 hash_multimap 中的第一個項目定址。
hash_multimap::cbegin	傳回常數迭代器，為 hash_multimap 中的第一個項目定址。
hash_multimap::cend	傳回常數迭代器，為 hash_multimap 中最後一個項目的下一個位置定址。
clear	清除 hash_multimap 的所有元素。
count	傳回 hash_multimap 的項目數其索引鍵符合參數。
hash_multimap::crbegin	傳回常數迭代器，為反轉 hash_multimap 中的第一個項目定址。
hash_multimap::crend	傳回常數迭代器，為反轉 hash_multimap 中最後一個項目的下一個位置定址。
hash_multimap::emplace	將建構的項目插入 hash_multimap 中。
hash_multimap::emplace_hint	依放置提示，將建構的項目插入 hash_multimap 中。
empty	測試，如果 hash_multimap 是空的。
end	傳回迭代器，為 hash_multimap 中最後一個項目的下一個位置定址。
equal_range	傳回迭代器，為 hash_multimap 中最後一個項目的下一個位置定址。
清除	從 hash_multimap 的指定位置移除一個元素或一個範圍內的元素。
find	傳回迭代器有金鑰對應至指定索引鍵的項目hash_multimap 之位置的位址。
get_allocator	傳回用來建構 hash_multimap 的 allocator 物件複本。
插入	在 hash_multimap 中的指定位置插入項目或某個項目範圍。
key_comp	擷取 hash_multimap用來命令索引值比較物件的複本。
lower_bound	傳回指向 hash_multimap 中第一個項目的迭代器，此項目擁有等於或大於特定值的索引鍵。
max_size	傳回 hash_multimap 的最大長度
rbegin	傳回迭代器，指向反轉 hash_multimap 中的第一個項目。
rend	傳回迭代器，為反轉 hash_multimap 中最後一個項目的下一個位置定址。
size	指定 hash_multimap 的新大小。
交換	交換兩個 hash_multimap 的元素。
upper_bound	傳回指向 hash_multimap 中第一個項目的迭代器，此項目擁有大於特定值的索引鍵。
value_comp	擷取 hash_multimap用來命令項目值比較物件的複本。