`multimap` 類別

發行項
10/12/2023

C++ 標準程式庫 multimap 類別用於從集合中儲存和擷取資料，其中每個元素都是具有資料值和排序索引鍵的配對。索引鍵的值不需要是唯一的，而且用來自動排序資料。多重對應中項目的值可以直接變更，但其關聯的索引鍵值不可以直接變更。相反地，與舊項目相關聯的索引鍵值必須刪除，然後插入與新項目相關聯的新索引鍵值。

語法

template <class Key,
    class Type,
    class Traits=less <Key>,
    class Allocator=allocator <pair  <const Key, Type>>>
class multimap;

參數

Key
要存放在多重對應中的索引鍵資料類型。

Type
要存放在多重對應中的項目資料類型。

Traits
類型，提供可以將兩個項目值做為排序鍵進行比較的函式物件，以判斷項目在多重對應中的相對順序。二元述詞 less<Key> 是預設值。

在 C++14 中，指定沒有類型參數的 std::less<> 或 std::greater<> 述詞，即可啟用異質查閱。如需詳細資訊，請參閱關聯容器中的異質查閱

Allocator
代表預存配置器物件的類型，封裝有關對應之記憶體配置和解除配置的詳細資訊。這個引數是選擇性的，而且預設值是 allocator<pair <const Key, Type> >。

備註

「C++ 標準程式庫」multimap 類別是：

關聯的容器，為可變大小容器，支援項目值以關聯的索引鍵值為基礎、有效率的擷取。
可逆轉的，因為它提供雙向的迭代器以存取其項目。
已排序，因為其項目是依據指定的比較函式，由容器內的索引鍵值排序。
多個，因為其元素不需要有唯一索引鍵，因此一個索引鍵值可能會有許多與其相關聯的元素資料值。
一個成對關聯的容器，因為其項目資料值和其索引鍵值是不同的。
類別範本，因為它所提供的功能是泛型的，因此與專案或索引鍵所包含的特定資料類型無關。用於項目或索引鍵的資料類型是在類別樣板中指定為參數 (和比較函式與配置器一起指定)。

map 類別所提供的反覆運算器是雙向反覆運算器，但類別成員函 insert 式和 multimap 具有採用範本參數的較弱輸入反覆運算器的版本，其功能需求比雙向反覆運算器類別所保證的功能需求要小得多。不同的迭代器概念因其功能的修改而形成關聯的系列。每個迭代器概念有自己的一組需求，因此，使用它們的演算法必須將其假設限制為該迭代器類型的需求。可假設輸入迭代器可能已取值來參考某個物件，而且可能會遞增為序列中的下一個迭代器。這是最小的一組功能，不過，已足以在類別成員函式的內容中有意義地溝通有關迭代器範圍 [First, Last)。

選擇容器類型時，通常應根據應用程式所需的搜尋和插入類型。關聯的容器已針對查閱、插入和移除作業最佳化。明確支援這些作業的成員函式很有效率，以與容器中的項目數目之對數成正比的平均時間執行它們。插入專案不會使反覆運算器失效，而移除元素只會使指向已移除元素的反覆運算器失效。

multimap當應用程式滿足將值與其索引鍵建立關聯的條件時，應該是所選擇的關聯容器。這種結構的模型是關鍵字的排序清單，其具有相關字串值的排序清單，例如，定義，其中文字不一定是唯一定義的。如果關鍵字是唯一定義，因此索引鍵是唯一的，則對應是首選容器。另一方面，如果只儲存文字清單，則集合是正確的容器。如果允許多個字組出現，則 multiset 會是適當的容器結構。

會 multimap 藉由呼叫類型的 key_compare 預存函式物件來排序它所控制的順序。這個預存物件是可藉由呼叫成員函式來存取的比較函式 key_comp 。通常，項目必須是小於比較才能建立此順序：因此若提供了兩個項目，可以判斷它們相等 (任一個都不小於另一個的意義)，或者一個小於另一個。這會導致非對等元件之間的排序。一個技術提示，比較函式是在標準數學概念上產生嚴格弱式順序的二元述詞。二進位述詞 f(x,y) 是具有兩個引數物件的函式物件 x ，以及 y 或 false 的 true 傳回值。如果二元述詞不具彈性、反對稱和可轉移性，而且等價是可轉移的，則對集合所加的排序是嚴格的弱式排序，其中兩個物件 xy 和定義在兩者 f(x,y)f(y,x)false 皆為時相等。如果更強的索引鍵相等條件取代等價條件，順序會變成總計 (也就是所有項目彼此相關的排序)，因此相符的索引鍵之間將難以辨別。

在 C++14 中，指定沒有類型參數的 std::less<> 或 std::greater<> 述詞，即可啟用異質查閱。如需詳細資訊，請參閱關聯容器中的異質查閱。

成員

建構函式

建構函式	描述
`multimap`	建構一個空的 `multimap`，或是其他 `multimap` 的全部或部分複本。

Typedefs

類型名稱	描述
`allocator_type`	類型，表示 `allocator` 物件的 `multimap` 類別。
`const_iterator`	提供雙向迭代器的類型，這個迭代器可以讀取 `const` 中的 `multimap` 項目。
`const_pointer`	類型，提供 `const` 中 `multimap` 項目之指標。
`const_reference`	類型，提供儲存在 `const` 中供讀取和執行 `multimap` 作業之 `const` 項目的參考。
`const_reverse_iterator`	提供雙向迭代器的類型，這個迭代器可以讀取 `const` 中的任何 `multimap` 項目。
`difference_type`	帶正負號的整數類型，可以用來表示範圍 (介於迭代器所指的項目) 中 `multimap` 的項目數。
`iterator`	類型，提供兩個參考相同 `multimap` 內項目的迭代器之間的差異。
`key_compare`	類型，提供可以比較兩個排序鍵的函式物件，以判斷兩個項目在 `multimap` 中的相對順序。
`key_type`	型別，描述組成每個專案的 `multimap` 排序索引鍵物件。
`mapped_type`	類型，表示儲存在 `multimap` 中的資料類型。
`pointer`	類型，提供 `const` 中 `multimap` 項目之指標。
`reference`	類型，提供儲存在 `multimap` 中之項目的參考。
`reverse_iterator`	類型，提供可以讀取或修改反轉 `multimap` 中之項目的雙向迭代器。
`size_type`	不帶正負號的整數類型，提供 `const` 中 `multimap` 項目之指標。
`value_type`	類型，提供可將兩個項目做為排序鍵進行比較之函式物件，以判斷項目在 `multimap` 中的相對順序。

成員函式

成員函數	描述
`begin`	傳回迭代器，為 `multimap` 中的第一個項目定址。
`cbegin`	傳 `const` 回反覆運算器，定址中的 `multimap` 第一個專案。
`cend`	`const`傳回反覆運算器，定址物件是中最後一個專案 `multimap` 之後的位置。
`clear`	清除 `multimap` 的所有項目。
`contains`^C++20	檢查中是否有具有指定索引鍵 `multimap` 的專案。
`count`	傳回 `multimap` 中索引鍵符合參數指定之索引鍵的項目數目。
`crbegin`	`const`傳回反覆運算器，定址反轉 `multimap` 中的第一個專案。
`crend`	傳 `const` 回反覆運算器，定址物件是反轉 `multimap` 中最後一個專案之後的位置。
`emplace`	將就地建構的項目插入 `multimap` 中。
`emplace_hint`	將就地建構的項目 (含位置提示) 插入 `multimap` 中。
`empty`	測試 `multimap` 是否為空白。
`end`	傳回迭代器，為 `multimap` 中最後一個項目的下一個位置定址。
`equal_range`	尋找項目索引鍵符合指定值的項目範圍。
`erase`	從指定的位置移除 `multimap` 中的項目或項目範圍，或移除符合指定之索引鍵的項目。
`find`	傳回迭代器，定址 `multimap` 中索引鍵等於指定索引鍵之項目的第一個位置。
`get_allocator`	傳回用來建構 `allocator` 的 `multimap` 物件複本。
`insert`	將項目或項目範圍插入至 `multimap`。
`key_comp`	擷取 `multimap` 中用來排序索引鍵的比較物件之複本。
`lower_bound`	傳回迭代器，指向 `multimap` 中索引鍵等於或大於特定索引鍵的第一個項目。
`max_size`	傳回 `multimap` 的最大長度。
`rbegin`	傳回迭代器，為反轉 `multimap` 中的第一個項目定址。
`rend`	傳回迭代器，為反轉 `multimap` 中最後一個項目的下一個位置定址。
`size`	傳回 `multimap` 中項目的數目。
`swap`	交換兩個 `multimap` 的項目。
`upper_bound`	傳回迭代器，指向 `multimap` 中索引鍵大於特定索引鍵的第一個項目。
`value_comp`	成員函式傳回函式物件，可藉由比較其索引鍵值判斷 `multimap` 中項目的順序。

運算子	描述
`operator=`	用另一個 `multimap` 的複本取代 `multimap` 的項目。

需求

標頭：<map>

命名空間：std

（ 索引鍵 、值）組會儲存在 multimap 中做為型 pair 別的物件。配對類別需要標頭，此標頭 <utility> 會自動 <map> 包含。

`multimap::allocator_type`

型別，表示物件的配置器類別 multimap 。

typedef Allocator allocator_type;

範例

如需使用 allocator_type 的範例 get_allocator ，請參閱範例。

`multimap::begin`

傳回迭代器，為 multimap 中的第一個項目定址。

const_iterator begin() const;

iterator begin();

傳回值

雙向反覆運算器，定址中第一個專案 multimap ，或位置接替空 multimap 的。

範例

// multimap_begin.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: iterator m1_Iter;
   multimap <int, int> :: const_iterator m1_cIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 0, 0 ) );
   m1.insert ( Int_Pair ( 1, 1 ) );
   m1.insert ( Int_Pair ( 2, 4 ) );

   m1_cIter = m1.begin ( );
   cout << "The first element of m1 is " << m1_cIter -> first << endl;

   m1_Iter = m1.begin ( );
   m1.erase ( m1_Iter );

   // The following 2 lines would err as the iterator is const
   // m1_cIter = m1.begin ( );
   // m1.erase ( m1_cIter );

   m1_cIter = m1.begin( );
   cout << "First element of m1 is now " << m1_cIter -> first << endl;
}

The first element of m1 is 0
First element of m1 is now 1

`multimap::cbegin`

傳回 const 迭代器，為範圍中的第一個項目定址。

const_iterator cbegin() const;

傳回值

const 雙向存取迭代器，指向範圍的第一個項目，或指向空白範圍結尾 (空白範圍 cbegin() == cend()) 之外的位置。

備註

使用的 cbegin 傳回值，就無法修改範圍中的專案。

您可以使用此成員函式取代 begin() 成員函式，以確保傳回值是 const_iterator。一般而言，它會與類型推算關鍵字搭配 auto 使用，如下列範例所示。在此範例中，請考慮將 Container 視為任何支援 begin() 和 cbegin() 且可修改 (非 const) 的容器類型。

auto i1 = Container.begin();
// i1 is Container<T>::iterator
auto i2 = Container.cbegin();

// i2 is Container<T>::const_iterator

`multimap::cend`

傳回 const 迭代器，為範圍中最後一個項目之外的位置定址。

const_iterator cend() const;

傳回值

指向範圍結尾之外的 const 雙向存取迭代器。

備註

cend 用來測試迭代器是否已超過其範圍結尾。

您可以使用此成員函式取代 end() 成員函式，以確保傳回值是 const_iterator。一般而言，它會與類型推算關鍵字搭配 auto 使用，如下列範例所示。在此範例中，請考慮將 Container 視為任何支援 end() 和 cend() 且可修改 (非 const) 的容器類型。

auto i1 = Container.end();
// i1 is Container<T>::iterator
auto i2 = Container.cend();

// i2 is Container<T>::const_iterator

所 cend 傳回的值不應該取值。

`multimap::clear`

清除 multimap 的所有項目。

void clear();

範例

下列範例示範如何使用 multimap::clear 成員函式。

// multimap_clear.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap<int, int> m1;
   multimap<int, int>::size_type i;
   typedef pair<int, int> Int_Pair;

   m1.insert(Int_Pair(1, 1));
   m1.insert(Int_Pair(2, 4));

   i = m1.size();
   cout << "The size of the multimap is initially "
        << i << "." << endl;

   m1.clear();
   i = m1.size();
   cout << "The size of the multimap after clearing is "
        << i << "." << endl;
}

The size of the multimap is initially 2.
The size of the multimap after clearing is 0.

`multimap::const_iterator`

提供雙向迭代器的類型，這個迭代器可以讀取 const 中的 multimap 項目。

typedef implementation-defined const_iterator;

備註

類型 const_iterator 無法用來修改專案的值。

const_iterator所 multimap 定義的，指向型 value_type 別為的 pair<const Key, Type> 物件。透過該配對的第一個成員，即可取得此索引鍵的值，而透過該配對的第二個成員，則可取得所對應元素的值。

若要取值 const_iteratorcIter 指向中的 multimap 專案，請使用 -> 運算子。

若要存取專案的索引鍵值，請使用 cIter->first(*cIter).first 相當於的。若要存取專案的對應日期值，請使用 cIter->second(*cIter).second 相當於的。

範例

如需使用 const_iterator 的範例 begin ，請參閱範例。

`multimap::const_pointer`

類型，提供 const 中 multimap 項目之指標。

typedef typename allocator_type::const_pointer const_pointer;

備註

類型 const_pointer 無法用來修改專案的值。

在大部分情況下， iterator 應該使用來存取物件中的 multimap 專案。

`multimap::const_reference`

類型，提供儲存在 const 中供讀取和執行 multimap 作業之 const 項目的參考。

typedef typename allocator_type::const_reference const_reference;

範例

// multimap_const_ref.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );

   // Declare and initialize a const_reference &Ref1
   // to the key of the first element
   const int &Ref1 = ( m1.begin( ) -> first );

   // The following line would cause an error because the
   // non-const_reference can't be used to access the key
   // int &Ref1 = ( m1.begin( ) -> first );

   cout << "The key of the first element in the multimap is "
        << Ref1 << "." << endl;

   // Declare and initialize a reference &Ref2
   // to the data value of the first element
   int &Ref2 = ( m1.begin( ) -> second );

   cout << "The data value of the first element in the multimap is "
        << Ref2 << "." << endl;
}

The key of the first element in the multimap is 1.
The data value of the first element in the multimap is 10.

`multimap::const_reverse_iterator`

提供雙向迭代器的類型，這個迭代器可以讀取 const 中的任何 multimap 項目。

typedef std::reverse_iterator<const_iterator> const_reverse_iterator;

備註

型 const_reverse_iterator 別無法修改專案的值，並用來反向逐一查看 multimap 。

const_reverse_iterator所 multimap 定義的，指向型 value_type 別為的 pair<const Key, Type> 物件。透過該配對的第一個成員，即可取得此索引鍵的值，而透過該配對的第二個成員，則可取得所對應元素的值。

若要對指向 multimap 中某個元素的 const_reverse_iteratorcrIter 進行取值，請使用 -> 運算子。

若要存取專案的索引鍵值，請使用 crIter->first(*crIter).first 相當於的。若要存取專案的對應日期值，請使用 crIter->second(*crIter).first 相當於的。

範例

如需如何宣告和使用 const_reverse_iterator 的範例 rend ，請參閱範例。

`multimap::contains`

檢查中 multimap 是否有具有指定索引鍵的專案。

bool contains(const Key& key) const;
template<class K> bool contains(const K& key) const;

參數

K
索引鍵的類型。

key
要尋找的專案索引鍵值。

傳回值

true 如果在容器中找到專案，則為 ; false 否則。

備註

contains() 是 C++20 的新功能。若要使用它，請指定 /std:c++20 或更新版本的編譯器選項。

template<class K> bool contains(const K& key) const 只有在透明時 key_compare 才會參與多載解析。如需詳細資訊，請參閱關聯容器中的異質查閱。

範例

// Requires /std:c++20 or /std:c++latest
#include <map>
#include <string>
#include <iostream>
#include <functional>

int main()
{
    std::multimap<int, bool> m = {{0, false}, {1, true}};

    std::cout << std::boolalpha; // so booleans show as 'true' or 'false'
    std::cout << m.contains(1) << '\n';
    std::cout << m.contains(2) << '\n';

    // call template function
    std::multimap<std::string, int, std::less<>> m2 = {{"ten", 10}, {"twenty", 20}, {"thirty", 30}};
    std::cout << m2.contains("ten");

    return 0;
}

true
false
true

`multimap::count`

傳回中索引鍵符合參數指定索引鍵的專案 multimap 數。

size_type count(const Key& key) const;

參數

key
要從 multimap 中比對之項目的索引鍵。

傳回值

排序索引鍵符合參數索引鍵的項目數。如果 multimap 不含具有相符索引鍵的項目則為 0。

備註

成員函式會傳回範圍中的項目數

lower_bound(key), upper_bound(key)

中索引鍵值為 key 的項目數。

範例

下列範例示範如何使用 multimap::count 成員函式。

// multimap_count.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
    using namespace std;
    multimap<int, int> m1;
    multimap<int, int>::size_type i;
    typedef pair<int, int> Int_Pair;

    m1.insert(Int_Pair(1, 1));
    m1.insert(Int_Pair(2, 1));
    m1.insert(Int_Pair(1, 4));
    m1.insert(Int_Pair(2, 1));

    // Elements don't need to have unique keys in multimap,
    // so duplicates are allowed and counted
    i = m1.count(1);
    cout << "The number of elements in m1 with a sort key of 1 is: "
         << i << "." << endl;

    i = m1.count(2);
    cout << "The number of elements in m1 with a sort key of 2 is: "
         << i << "." << endl;

    i = m1.count(3);
    cout << "The number of elements in m1 with a sort key of 3 is: "
         << i << "." << endl;
}

The number of elements in m1 with a sort key of 1 is: 2.
The number of elements in m1 with a sort key of 2 is: 2.
The number of elements in m1 with a sort key of 3 is: 0.

`multimap::crbegin`

const傳回反覆運算器，定址反轉 multimap 中的第一個專案。

const_reverse_iterator crbegin() const;

傳回值

const反向雙向反覆運算器，定址反 multimap 轉中的第一個專案，或定址未反 multimap 轉中的最後一個專案。

備註

crbegin與反轉 multimap 搭配使用，就像搭配使用一 multimap 樣 begin 。

使用的 crbegin 傳回值， multimap 就無法修改物件。

crbegin 可用來向後逐一查看 multimap。

範例

// multimap_crbegin.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: const_reverse_iterator m1_crIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_crIter = m1.crbegin( );
   cout << "The first element of the reversed multimap m1 is "
        << m1_crIter -> first << "." << endl;
}

The first element of the reversed multimap m1 is 3.

`multimap::crend`

傳 const 回反覆運算器，定址物件是反轉 multimap 中最後一個專案之後的位置。

const_reverse_iterator crend() const;

傳回值

const反向雙向反覆運算器，定址物件是反轉中最後一個專案之後的位置（在未反 multimap 轉 multimap 的第一個元素之前的位置）。

備註

crend與反轉 multimap 搭配使用，就像搭配使用一 multimap 樣 multimap::end 。

使用的 crend 傳回值， multimap 就無法修改物件。

crend 可以用來測試反轉迭代器是否已到達其 multimap 的結尾。

所 crend 傳回的值不應該取值。

範例

// multimap_crend.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: const_reverse_iterator m1_crIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_crIter = m1.crend( );
   m1_crIter--;
   cout << "The last element of the reversed multimap m1 is "
        << m1_crIter -> first << "." << endl;
}

The last element of the reversed multimap m1 is 1.

`multimap::difference_type`

帶正負號的整數類型，可以用來表示範圍 (介於迭代器所指的項目) 中 multimap 的項目數。

typedef typename allocator_type::difference_type difference_type;

備註

difference_type 是透過容器的迭代器減去或遞增時會傳回的類型。 difference_type通常用來表示反覆運算器 first 與 last 之間範圍 [ first ， last ] 中的專案數目，包括所指向的元素以及專案範圍，但不包括所指向 firstlast 的專案。

雖然 difference_type 適用于所有符合輸入反覆運算器需求的反覆運算器，其中包含可逆容器所支援的雙向反覆運算器類別，例如 set，但反覆運算器之間的減法僅受隨機存取反覆運算器所提供的隨機存取反覆運算器支援，例如向量。

範例

// multimap_diff_type.cpp
// compile with: /EHsc
#include <iostream>
#include <map>
#include <algorithm>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 3, 20 ) );

   // The following will insert as multimap keys are not unique
   m1.insert ( Int_Pair ( 2, 30 ) );

   multimap <int, int>::iterator m1_Iter, m1_bIter, m1_eIter;
   m1_bIter = m1.begin( );
   m1_eIter = m1.end( );

   // Count the number of elements in a multimap
   multimap <int, int>::difference_type  df_count = 0;
   m1_Iter = m1.begin( );
   while ( m1_Iter != m1_eIter )
   {
      df_count++;
      m1_Iter++;
   }

   cout << "The number of elements in the multimap m1 is: "
        << df_count << "." << endl;
}

The number of elements in the multimap m1 is: 4.

`multimap::emplace`

插入就地建構 (未執行任何複製或移動作業) 的項目。

template <class... Args>
iterator emplace(Args&&... args);

參數

args
轉送的引數，用來建構要插入至的專案 multimap 。

傳回值

指向新插入之元素的迭代器。

備註

此函式不會使容器元素的參考無效，但是可能會使容器的所有迭代器無效。

如果在插入時擲回例外狀況，就會將容器保持不變，並重新擲回例外狀況。

value_type專案的是一對，因此元素的值會是排序的配對，第一個元件等於索引鍵值，而第二個元件等於專案的資料值。

範例

// multimap_emplace.cpp
// compile with: /EHsc
#include <map>
#include <string>
#include <iostream>

using namespace std;

template <typename M> void print(const M& m) {
    cout << m.size() << " elements: " << endl;

    for (const auto& p : m) {
        cout << "(" << p.first <<  "," << p.second << ") ";
    }

    cout << endl;
}

int main()
{
    multimap<string, string> m1;

    m1.emplace("Anna", "Accounting");
    m1.emplace("Bob", "Accounting");
    m1.emplace("Carmine", "Engineering");

    cout << "multimap modified, now contains ";
    print(m1);
    cout << endl;

    m1.emplace("Bob", "Engineering");

    cout << "multimap modified, now contains ";
    print(m1);
    cout << endl;
}

`multimap::emplace_hint`

將就地建構 (未執行任何複製或移動作業) 的元素連同位置提示一起插入。

template <class... Args>
iterator emplace_hint(
    const_iterator where,
    Args&&... args);

參數

args
轉送的引數，用來建構要插入至的專案 multimap 。

where
要開始搜尋正確的插入點的地方。 (若該點緊接於 where 之前，則可能會在分攤常數時間插入，而不是對數時間)。

傳回值

指向新插入之元素的迭代器。

備註

此函式不會使容器元素的參考無效，但是可能會使容器的所有迭代器無效。

在定位期間，如果擲回例外狀況，則不會修改容器的狀態。

value_type專案的是一對，因此元素的值會是排序的配對，第一個元件等於索引鍵值，而第二個元件等於專案的資料值。

如需程式碼範例，請參閱map::emplace_hint。

`multimap::empty`

測試 multimap 是否為空白。

bool empty() const;

傳回值

true 如果是空的 multimap ，則為， false 如果為空，則 multimap 為。

範例

// multimap_empty.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1, m2;

   typedef pair <int, int> Int_Pair;
   m1.insert ( Int_Pair ( 1, 1 ) );

   if ( m1.empty( ) )
      cout << "The multimap m1 is empty." << endl;
   else
      cout << "The multimap m1 is not empty." << endl;

   if ( m2.empty( ) )
      cout << "The multimap m2 is empty." << endl;
   else
      cout << "The multimap m2 is not empty." << endl;
}

The multimap m1 is not empty.
The multimap m2 is empty.

`multimap::end`

傳回超出結尾 (past-the-end) 迭代器。

const_iterator end() const;

iterator end();

傳回值

超出結尾迭代器。如果 multimap 是空的，則 multimap::end() == multimap::begin()。

備註

end 是用來測試反覆運算器是否已通過其 multimap 結尾。

所 end 傳回的值不應該取值。

如需程式碼範例，請參閱multimap::find。

`multimap::equal_range`

尋找項目索引鍵符合指定值的項目範圍。

pair <const_iterator, const_iterator> equal_range (const Key& key) const;

pair <iterator, iterator> equal_range (const Key& key);

參數

key
要與所搜尋專案排序索引鍵比較的 multimap 引數索引鍵。

傳回值

一對反覆運算器，讓第一個是 lower_bound 索引鍵的，而第二個則是 upper_bound 索引鍵的。

若要存取成員函式所傳回之配對 pr 的第一個反覆運算器，請使用 pr.first 和來取值下限反覆運算器，請使用 *(pr.first) 。若要存取成員函式所傳回之配對 pr 的第二個反覆運算器，請使用 pr.second 和來取值上限反覆運算器，請使用 *(pr.second) 。

範例

// multimap_equal_range.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   typedef multimap <int, int, less<int> > IntMMap;
   IntMMap m1;
   multimap <int, int> :: const_iterator m1_RcIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   pair <IntMMap::const_iterator, IntMMap::const_iterator> p1, p2;
   p1 = m1.equal_range( 2 );

   cout << "The lower bound of the element with "
        << "a key of 2 in the multimap m1 is: "
        << p1.first -> second << "." << endl;

   cout << "The upper bound of the element with "
        << "a key of 2 in the multimap m1 is: "
        << p1.second -> second << "." << endl;

   // Compare the upper_bound called directly
   m1_RcIter = m1.upper_bound( 2 );

   cout << "A direct call of upper_bound( 2 ) gives "
        << m1_RcIter -> second << "," << endl
        << "matching the 2nd element of the pair "
        << "returned by equal_range( 2 )." << endl;

   p2 = m1.equal_range( 4 );

   // If no match is found for the key,
   // both elements of the pair return end( )
   if ( ( p2.first == m1.end( ) ) && ( p2.second == m1.end( ) ) )
      cout << "The multimap m1 doesn't have an element "
           << "with a key less than 4." << endl;
   else
      cout << "The element of multimap m1 with a key >= 40 is: "
           << p1.first -> first << "." << endl;
}

The lower bound of the element with a key of 2 in the multimap m1 is: 20.
The upper bound of the element with a key of 2 in the multimap m1 is: 30.
A direct call of upper_bound( 2 ) gives 30,
matching the 2nd element of the pair returned by equal_range( 2 ).
The multimap m1 doesn't have an element with a key less than 4.

`multimap::erase`

從指定的位置移除 multimap 中的項目或項目範圍，或移除符合指定之索引鍵的項目。

iterator erase(
    const_iterator Where);

iterator erase(
    const_iterator First,
    const_iterator Last);

size_type erase(
    const key_type& Key);

參數

Where
要移除之項目的位置。

First
要移除之第一個項目的位置。

Last
緊接在要移除之最後一個項目後面的位置。

Key
要移除之元素的索引鍵。

傳回值

針對前兩個成員函式，會傳回雙向迭代器，其中指定任何移除之元素後剩餘的第一個元素，或如果沒有這類元素，則傳回 map 結尾的元素。

針對第三個成員函式，傳回已從 multimap 中移除的專案數目。

備註

如需程式碼範例，請參閱map::erase。

`multimap::find`

傳回反覆運算器，這個反覆運算器參考中專案的第 multimap 一個位置，其索引鍵相當於指定的索引鍵。

iterator find(const Key& key);

const_iterator find(const Key& key) const;

參數

key
要與所搜尋專案排序索引鍵相符的 multimap 索引鍵值。

傳回值

反覆運算器，參考具有指定索引鍵之專案的位置，如果找不到索引鍵相符專案，則為（）中 multimapmultimap::end() 最後一個專案後置的位置。

備註

成員函式會傳回反覆運算器，其 multimap 排序索引鍵相當於二元述詞下的引數索引鍵，根據小於可比較性關聯來引發排序。

如果的傳回值 find 指派給 const_iterator ， multimap 則無法修改物件。如果將的 find 傳回值指派給 iterator ， multimap 則可以修改物件。

範例

// compile with: /EHsc /W4 /MTd
#include <map>
#include <iostream>
#include <vector>
#include <string>
#include <utility>  // make_pair()

using namespace std;

template <typename A, typename B> void print_elem(const pair<A, B>& p) {
    cout << "(" << p.first << ", " << p.second << ") ";
}

template <typename T> void print_collection(const T& t) {
    cout << t.size() << " elements: ";

    for (const auto& p : t) {
        print_elem(p);
    }
    cout << endl;
}

template <typename C, class T> void findit(const C& c, T val) {
    cout << "Trying find() on value " << val << endl;
    auto result = c.find(val);
    if (result != c.end()) {
        cout << "Element found: "; print_elem(*result); cout << endl;
    } else {
        cout << "Element not found." << endl;
    }
}

int main()
{
    multimap<int, string> m1({ { 40, "Zr" }, { 45, "Rh" } });
    cout << "The starting multimap m1 is (key, value):" << endl;
    print_collection(m1);

    vector<pair<int, string>> v;
    v.push_back(make_pair(43, "Tc"));
    v.push_back(make_pair(41, "Nb"));
    v.push_back(make_pair(46, "Pd"));
    v.push_back(make_pair(42, "Mo"));
    v.push_back(make_pair(44, "Ru"));
    v.push_back(make_pair(44, "Ru")); // attempt a duplicate

    cout << "Inserting the following vector data into m1:" << endl;
    print_collection(v);

    m1.insert(v.begin(), v.end());

    cout << "The modified multimap m1 is (key, value):" << endl;
    print_collection(m1);
    cout << endl;
    findit(m1, 45);
    findit(m1, 6);
}

`multimap::get_allocator`

傳回用來建構 multimap 的配置器物件的複本。

allocator_type get_allocator() const;

傳回值

所使用的 multimap 配置器。

備註

類別的配置 multimap 器會指定類別管理儲存體的方式。 C++ 標準程式庫容器類別隨附的預設配置器，足以滿足大多數程式設計需求。撰寫和使用您自己的配置器類別是進階 C++ 主題。

範例

// multimap_get_allocator.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int>::allocator_type m1_Alloc;
   multimap <int, int>::allocator_type m2_Alloc;
   multimap <int, double>::allocator_type m3_Alloc;
   multimap <int, int>::allocator_type m4_Alloc;

   // The following lines declare objects
   // that use the default allocator.
   multimap <int, int> m1;
   multimap <int, int, allocator<int> > m2;
   multimap <int, double, allocator<double> > m3;

   m1_Alloc = m1.get_allocator( );
   m2_Alloc = m2.get_allocator( );
   m3_Alloc = m3.get_allocator( );

   cout << "The number of integers that can be allocated"
        << endl << "before free memory is exhausted: "
        << m2.max_size( ) << ".\n" << endl;

   cout << "The number of doubles that can be allocated"
        << endl << "before free memory is exhausted: "
        << m3.max_size( ) <<  ".\n" << endl;

   // The following line creates a multimap m4
   // with the allocator of multimap m1.
   map <int, int> m4( less<int>( ), m1_Alloc );

   m4_Alloc = m4.get_allocator( );

   // Two allocators are interchangeable if
   // storage allocated from each can be
   // deallocated via the other
   if( m1_Alloc == m4_Alloc )
   {
      cout << "The allocators are interchangeable."
           << endl;
   }
   else
   {
      cout << "The allocators are not interchangeable."
           << endl;
   }
}

`multimap::insert`

將項目或項目範圍插入至 multimap。

// (1) single element
pair<iterator, bool> insert(
    const value_type& Val);

// (2) single element, perfect forwarded
template <class ValTy>
pair<iterator, bool>
insert(
    ValTy&& Val);

// (3) single element with hint
iterator insert(
    const_iterator Where,
    const value_type& Val);

// (4) single element, perfect forwarded, with hint
template <class ValTy>
iterator insert(
    const_iterator Where,
    ValTy&& Val);

// (5) range
template <class InputIterator>
void insert(
    InputIterator First,
    InputIterator Last);

// (6) initializer list
void insert(
    initializer_list<value_type>
IList);

參數

Val
要插入至的專案 multimap 值。

Where
要開始搜尋正確的插入點的地方。 (若該點緊接於 Where 之前，則可能會在分攤常數時間插入，而不是對數時間)。

ValTy
樣板參數，指定對應可用來建構的元素的 value_type 引數類型，並以完美轉送 Val 做為引數。

First
要複製之第一個元素的位置。

Last
要複製之最一個元素後方的位置。

InputIterator
符合反覆運算器需求的 input 樣板函式引數，指向可用來建構 value_type 物件之型別的專案。

IList
initializer_list要從中複製專案的。

傳回值

單一元素插入成員函式（1）和（2），會將反覆運算器傳回插入新專案的位置 multimap 。

單一元素與提示成員函式（3）和（4），會傳回反覆運算器，指向插入 multimap 新元素的位置。

備註

此函式不會使指標或參考無效，但是可能會使容器的所有迭代器無效。

在只插入一個元素的期間，若擲出例外狀況，則不會修改容器的狀態。在插入多個元素期間，若擲出例外狀況，則容器會處於未指定但有效的狀態。

value_type容器的是屬於容器的 typedef，而對應 multimap<K, V>::value_type 則為 pair<const K, V> 。元素的值是已排序的配對，其中第一個元件等於索引鍵值，而第二個元件等於元素的資料值。

範圍成員函式（5）會將專案值序列插入對應至 multimap 範圍 [First, Last) 中反覆運算器所定址的每個元素，因此 Last 不會插入。容器成員函式 end() 是指容器中最後一個元素後方的位置；例如，陳述式 m.insert(v.begin(), v.end()); 會將 v 的所有元素插入至 m。

初始化運算式清單成員函式（6）會使用 initializer_list 將專案複製到對應中。

若要插入就地建構的專案，也就是不會執行任何複製或移動作業，請參閱 multimap::emplace 和 multimap::emplace_hint 。

範例

// multimap_insert.cpp
// compile with: /EHsc
#include <map>
#include <iostream>
#include <string>
#include <vector>
#include <utility>  // make_pair()

using namespace std;

template <typename M> void print(const M& m) {
    cout << m.size() << " elements: ";

    for (const auto& p : m) {
        cout << "(" << p.first << ", " << p.second << ") ";
    }

    cout << endl;
}

int main()
{
    // insert single values
    multimap<int, int> m1;
    // call insert(const value_type&) version
    m1.insert({ 1, 10 });
    // call insert(ValTy&&) version
    m1.insert(make_pair(2, 20));

    cout << "The original key and mapped values of m1 are:" << endl;
    print(m1);

    // intentionally attempt a duplicate, single element
    m1.insert(make_pair(1, 111));

    cout << "The modified key and mapped values of m1 are:" << endl;
    print(m1);

    // single element, with hint
    m1.insert(m1.end(), make_pair(3, 30));
    cout << "The modified key and mapped values of m1 are:" << endl;
    print(m1);
    cout << endl;

    // The templatized version inserting a jumbled range
    multimap<int, int> m2;
    vector<pair<int, int>> v;
    v.push_back(make_pair(43, 294));
    v.push_back(make_pair(41, 262));
    v.push_back(make_pair(45, 330));
    v.push_back(make_pair(42, 277));
    v.push_back(make_pair(44, 311));

    cout << "Inserting the following vector data into m2:" << endl;
    print(v);

    m2.insert(v.begin(), v.end());

    cout << "The modified key and mapped values of m2 are:" << endl;
    print(m2);
    cout << endl;

    // The templatized versions move-constructing elements
    multimap<int, string>  m3;
    pair<int, string> ip1(475, "blue"), ip2(510, "green");

    // single element
    m3.insert(move(ip1));
    cout << "After the first move insertion, m3 contains:" << endl;
    print(m3);

    // single element with hint
    m3.insert(m3.end(), move(ip2));
    cout << "After the second move insertion, m3 contains:" << endl;
    print(m3);
    cout << endl;

    multimap<int, int> m4;
    // Insert the elements from an initializer_list
    m4.insert({ { 4, 44 }, { 2, 22 }, { 3, 33 }, { 1, 11 }, { 5, 55 } });
    cout << "After initializer_list insertion, m4 contains:" << endl;
    print(m4);
    cout << endl;
}

`multimap::iterator`

類型，其提供可讀取或修改 multimap 中任何項目的雙向迭代器。

typedef implementation-defined iterator;

備註

iterator所 multimap 定義的，指向型 value_type 別為的 pair<const Key, Type> 物件。透過該配對的第一個成員，即可取得此索引鍵的值，而透過該配對的第二個成員，則可取得所對應元素的值。

若要取值 iteratorIter 指向中的 multimap 專案，請使用 -> 運算子。

若要存取專案的索引鍵值，請使用 Iter->first(*Iter).first 相當於的。若要存取專案的對應日期值，請使用 Iter->second(*Iter).second 相當於的。

型 iterator 別可用來修改專案的值。

範例

如需如何宣告和使用 iterator 的範例 begin ，請參閱範例。

`multimap::key_comp`

擷取 multimap 中用來排序索引鍵的比較物件之複本。

key_compare key_comp() const;

傳回值

傳回用來排序其專案的函式物件 multimap 。

備註

預存物件會定義成員函式

bool operator( const Key& x, const Key& y);

如果 x 嚴格在排序次序之前 y ，則會傳回 true。

範例

// multimap_key_comp.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;

   multimap <int, int, less<int> > m1;
   multimap <int, int, less<int> >::key_compare kc1 = m1.key_comp( ) ;
   bool result1 = kc1( 2, 3 ) ;
   if( result1 == true )
   {
      cout << "kc1( 2,3 ) returns value of true, "
           << "where kc1 is the function object of m1."
           << endl;
   }
   else
   {
      cout << "kc1( 2,3 ) returns value of false "
           << "where kc1 is the function object of m1."
           << endl;
   }

   multimap <int, int, greater<int> > m2;
   multimap <int, int, greater<int> >::key_compare kc2 = m2.key_comp( );
   bool result2 = kc2( 2, 3 ) ;
   if( result2 == true )
   {
      cout << "kc2( 2,3 ) returns value of true, "
           << "where kc2 is the function object of m2."
           << endl;
   }
   else
   {
      cout << "kc2( 2,3 ) returns value of false, "
           << "where kc2 is the function object of m2."
           << endl;
   }
}

kc1( 2,3 ) returns value of true, where kc1 is the function object of m1.
kc2( 2,3 ) returns value of false, where kc2 is the function object of m2.

`multimap::key_compare`

類型，提供可以比較兩個排序鍵的函式物件，以判斷兩個項目在 multimap 中的相對順序。

typedef Traits key_compare;

備註

key_compare 與樣板參數 Traits 同義。

如需的詳細資訊 Traits ，請參閱 multimap 類別主題。

範例

如需如何宣告和使用 key_compare 的範例 key_comp ，請參閱範例。

`multimap::key_type`

類型，描述構成 multimap 每個元素的排序鍵物件。

typedef Key key_type;

備註

key_type 與樣板參數 Key 同義。

如需的詳細資訊 Key ，請參閱類別主題的 multimap 一節。

範例

如需如何宣告和使用 key_type 的範例 value_type ，請參閱範例。

`multimap::lower_bound`

傳回迭代器，指向 multimap 中索引鍵等於或大於特定索引鍵的第一個項目。

iterator lower_bound(const Key& key);

const_iterator lower_bound(const Key& key) const;

參數

key
要與所搜尋專案排序索引鍵比較的 multimap 引數索引鍵。

傳回值

反覆運算器或 const_iterator ，定址物件是索引鍵等於或大於引數索引鍵之中 multimap 元素的位置，如果找不到索引鍵相符專案，則定址中最後 multimap 一個專案之後的位置。

如果的傳回值 lower_bound 指派給 const_iterator ， multimap 則無法修改物件。如果的傳回值 lower_bound 指派給 反覆運算器 ， multimap 則可以修改物件。

範例

// multimap_lower_bound.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   multimap <int, int> :: const_iterator m1_AcIter, m1_RcIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_RcIter = m1.lower_bound( 2 );
   cout << "The element of multimap m1 with a key of 2 is: "
        << m1_RcIter -> second << "." << endl;

   m1_RcIter = m1.lower_bound( 3 );
   cout << "The first element of multimap m1 with a key of 3 is: "
        << m1_RcIter -> second << "." << endl;

   // If no match is found for the key, end( ) is returned
   m1_RcIter = m1.lower_bound( 4 );

   if ( m1_RcIter == m1.end( ) )
      cout << "The multimap m1 doesn't have an element "
              << "with a key of 4." << endl;
   else
      cout << "The element of multimap m1 with a key of 4 is: "
                << m1_RcIter -> second << "." << endl;

   // The element at a specific location in the multimap can be
   // found using a dereferenced iterator addressing the location
   m1_AcIter = m1.end( );
   m1_AcIter--;
   m1_RcIter = m1.lower_bound( m1_AcIter -> first );
   cout << "The first element of m1 with a key matching\n"
        << "that of the last element is: "
        << m1_RcIter -> second << "." << endl;

   // Note that the first element with a key equal to
   // the key of the last element is not the last element
   if ( m1_RcIter == --m1.end( ) )
      cout << "This is the last element of multimap m1."
           << endl;
   else
      cout << "This is not the last element of multimap m1."
           << endl;
}

The element of multimap m1 with a key of 2 is: 20.
The first element of multimap m1 with a key of 3 is: 20.
The multimap m1 doesn't have an element with a key of 4.
The first element of m1 with a key matching
that of the last element is: 20.
This is not the last element of multimap m1.

`multimap::mapped_type`

類型，表示儲存在 multimap 中的資料類型。

typedef Type mapped_type;

備註

mapped_type 與樣板參數 Type 同義。

如需的詳細資訊 Type ，請參閱 multimap 類別主題。

範例

如需如何宣告和使用 key_type 的範例 value_type ，請參閱範例。

`multimap::max_size`

傳回 multimap 的最大長度。

size_type max_size() const;

傳回值

的最大可能長度 multimap 。

範例

// multimap_max_size.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   multimap <int, int> :: size_type i;

   i = m1.max_size( );
   cout << "The maximum possible length "
        << "of the multimap is " << i << "." << endl;
}

`multimap::multimap`

建構一個空的 multimap，或是其他 multimap 的全部或部分複本。

multimap();

explicit multimap(
    const Traits& Comp);

multimap(
    const Traits& Comp,
    const Allocator& Al);

map(
    const multimap& Right);

multimap(
    multimap&& Right);

multimap(
    initializer_list<value_type> IList);

multimap(
    initializer_list<value_type> IList,
    const Compare& Comp);

multimap(
    initializer_list<value_type> IList,
    const Compare& Comp,
    const Allocator& Al);

template <class InputIterator>
multimap(
    InputIterator First,
    InputIterator Last);

template <class InputIterator>
multimap(
    InputIterator First,
    InputIterator Last,
    const Traits& Comp);

template <class InputIterator>
multimap(
    InputIterator First,
    InputIterator Last,
    const Traits& Comp,
    const Allocator& Al);

參數

Al
要用於此 multimap 物件的儲存體配置器類別，預設為 Allocator。

Comp
類型為 constTraits 並用來排序 map 中元素的比較函式，預設為 Traits。

Right
要從中複製所建構之集合的對應。

First
要複製的元素範圍中第一個元素的位置。

Last
超出要複製之元素範圍的第一個元素的位置。

IList
從中複製項目的 initializer_list。

備註

所有建構函式都會儲存一種配置器物件類型，該物件會管理的 multimap 記憶體儲存體，且稍後可藉由呼叫 get_allocator 傳回。在類別宣告以及用來取代替代配置器的前置處理巨集中，經常會省略 allocator 參數。

所有建構函式都會初始化其 multimap 。

所有建構函式都會儲存型 Traits 別的函式物件，用來在的 multimap 索引鍵之間建立順序，稍後可藉由呼叫 key_comp 傳回。

前三個建構函式會指定空的初始 multimap ，第二個建構函式會指定要用於建立專案順序的比較函式類型 Comp ，第三個建構函式會明確指定要使用的配置器類型（ Al ）。關鍵字 explicit 會隱藏某些類型的自動類型轉換。

第四個建構函式會指定的 multimapRight 複本。

第五個建構函式會藉由移動 Right 來指定的 multimap 複本。

第 6、7 和 8 個建構函式會複製的成員 initializer_list 。

接下來的三個建構函式會複製 map 的範圍 [First, Last)，其中會以越來越明確的方式指定類別 Traits 的比較函式及配置器的類型。

範例

// multimap_ctor.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main()
{
    using namespace std;
    typedef pair <int, int> Int_Pair;

    // Create an empty multimap m0 of key type integer
    multimap <int, int> m0;

    // Create an empty multimap m1 with the key comparison
    // function of less than, then insert 4 elements
    multimap <int, int, less<int> > m1;
    m1.insert(Int_Pair(1, 10));
    m1.insert(Int_Pair(2, 20));
    m1.insert(Int_Pair(3, 30));
    m1.insert(Int_Pair(4, 40));

    // Create an empty multimap m2 with the key comparison
    // function of greater than, then insert 2 elements
    multimap <int, int, less<int> > m2;
    m2.insert(Int_Pair(1, 10));
    m2.insert(Int_Pair(2, 20));

    // Create a multimap m3 with the
    // allocator of multimap m1
    multimap <int, int>::allocator_type m1_Alloc;
    m1_Alloc = m1.get_allocator();
    multimap <int, int> m3(less<int>(), m1_Alloc);
    m3.insert(Int_Pair(3, 30));

    // Create a copy, multimap m4, of multimap m1
    multimap <int, int> m4(m1);

    // Create a multimap m5 by copying the range m1[ first,  last)
    multimap <int, int>::const_iterator m1_bcIter, m1_ecIter;
    m1_bcIter = m1.begin();
    m1_ecIter = m1.begin();
    m1_ecIter++;
    m1_ecIter++;
    multimap <int, int> m5(m1_bcIter, m1_ecIter);

    // Create a multimap m6 by copying the range m4[ first,  last)
    // and with the allocator of multimap m2
    multimap <int, int>::allocator_type m2_Alloc;
    m2_Alloc = m2.get_allocator();
    multimap <int, int> m6(m4.begin(), ++m4.begin(), less<int>(), m2_Alloc);

    cout << "m1 =";
    for (auto i : m1)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m2 =";
    for (auto i : m2)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m3 =";
    for (auto i : m3)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m4 =";
    for (auto i : m4)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m5 =";
    for (auto i : m5)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    cout << "m6 =";
    for (auto i : m6)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    // Create a multimap m8 by copying in an initializer_list
    multimap<int, int> m8{ { { 1, 1 }, { 2, 2 }, { 3, 3 }, { 4, 4 } } };
    cout << "m8: = ";
    for (auto i : m8)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    // Create a multimap m9 with an initializer_list and a comparator
    multimap<int, int> m9({ { 5, 5 }, { 6, 6 }, { 7, 7 }, { 8, 8 } }, less<int>());
    cout << "m9: = ";
    for (auto i : m9)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

    // Create a multimap m10 with an initializer_list, a comparator, and an allocator
    multimap<int, int> m10({ { 9, 9 }, { 10, 10 }, { 11, 11 }, { 12, 12 } }, less<int>(), m9.get_allocator());
    cout << "m10: = ";
    for (auto i : m10)
        cout << i.first << " " << i.second << ", ";
    cout << endl;

}

`multimap::operator=`

用另一個 multimap 的複本取代 multimap 的項目。

multimap& operator=(const multimap& right);

multimap& operator=(multimap&& right);

參數

right
multimap要複製到的 multimap 。

備註

清除 multimap 中的任何現有項目之後，operator= 會將 right 的內容複製或移到 multimap 中。

範例

// multimap_operator_as.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
   {
   using namespace std;
   multimap<int, int> v1, v2, v3;
   multimap<int, int>::iterator iter;

   v1.insert(pair<int, int>(1, 10));

   cout << "v1 = " ;
   for (iter = v1.begin(); iter != v1.end(); iter++)
      cout << iter->second << " ";
   cout << endl;

   v2 = v1;
   cout << "v2 = ";
   for (iter = v2.begin(); iter != v2.end(); iter++)
      cout << iter->second << " ";
   cout << endl;

// move v1 into v2
   v2.clear();
   v2 = move(v1);
   cout << "v2 = ";
   for (iter = v2.begin(); iter != v2.end(); iter++)
      cout << iter->second << " ";
   cout << endl;
   }

`multimap::pointer`

類型，其提供 multimap 中項目的指標。

typedef typename allocator_type::pointer pointer;

備註

型 pointer 別可用來修改專案的值。

在大部分情況下， iterator 應該使用來存取物件中的 multimap 專案。

`multimap::rbegin`

傳回迭代器，為反轉 multimap 中的第一個項目定址。

const_reverse_iterator rbegin() const;

reverse_iterator rbegin();

傳回值

反向雙向反覆運算器，定址反 multimap 轉中的第一個專案，或定址未反 multimap 轉中的最後一個專案。

備註

rbegin與反轉 multimap 搭配使用，就像搭配使用一 multimap 樣 begin 。

如果的傳回值 rbegin 指派給 const_reverse_iterator ，則 multimap 無法修改物件。如果的 rbegin 傳回值指派給 reverse_iterator ， multimap 則可以修改物件。

rbegin 可用來向後逐一查看 multimap。

範例

// multimap_rbegin.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: iterator m1_Iter;
   multimap <int, int> :: reverse_iterator m1_rIter;
   multimap <int, int> :: const_reverse_iterator m1_crIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_rIter = m1.rbegin( );
   cout << "The first element of the reversed multimap m1 is "
        << m1_rIter -> first << "." << endl;

   // begin can be used to start an iteration
   // through a multimap in a forward order
   cout << "The multimap is: ";
   for ( m1_Iter = m1.begin( ) ; m1_Iter != m1.end( ); m1_Iter++)
      cout << m1_Iter -> first << " ";
      cout << "." << endl;

   // rbegin can be used to start an iteration
   // through a multimap in a reverse order
   cout << "The reversed multimap is: ";
   for ( m1_rIter = m1.rbegin( ) ; m1_rIter != m1.rend( ); m1_rIter++)
      cout << m1_rIter -> first << " ";
      cout << "." << endl;

   // A multimap element can be erased by dereferencing its key
   m1_rIter = m1.rbegin( );
   m1.erase ( m1_rIter -> first );

   m1_rIter = m1.rbegin( );
   cout << "After the erasure, the first element "
        << "in the reversed multimap is "
        << m1_rIter -> first << "." << endl;
}

The first element of the reversed multimap m1 is 3.
The multimap is: 1 2 3 .
The reversed multimap is: 3 2 1 .
After the erasure, the first element in the reversed multimap is 2.

`multimap::reference`

類型，提供儲存在 multimap 中之項目的參考。

typedef typename allocator_type::reference reference;

範例

// multimap_ref.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );

   // Declare and initialize a const_reference &Ref1
   // to the key of the first element
   const int &Ref1 = ( m1.begin( ) -> first );

   // The following line would cause an error because the
   // non-const_reference can't be used to access the key
   // int &Ref1 = ( m1.begin( ) -> first );

   cout << "The key of first element in the multimap is "
        << Ref1 << "." << endl;

   // Declare and initialize a reference &Ref2
   // to the data value of the first element
   int &Ref2 = ( m1.begin( ) -> second );

   cout << "The data value of first element in the multimap is "
        << Ref2 << "." << endl;

   // The non-const_reference can be used to modify the
   // data value of the first element
   Ref2 = Ref2 + 5;
   cout << "The modified data value of first element is "
        << Ref2 << "." << endl;
}

The key of first element in the multimap is 1.
The data value of first element in the multimap is 10.
The modified data value of first element is 15.

`multimap::rend`

傳回迭代器，為反轉 multimap 中最後一個項目的下一個位置定址。

const_reverse_iterator rend() const;

reverse_iterator rend();

傳回值

反向雙向反覆運算器，定址物件是反轉中最後一個專案之後的位置（在未反 multimap 轉 multimap 的第一個元素之前的位置）。

備註

rend與反轉 multimap 搭配使用，就像搭配使用一 multimap 樣 end 。

如果的傳回值 rend 指派給 const_reverse_iterator ，則 multimap 無法修改物件。如果的 rend 傳回值指派給 reverse_iterator ， multimap 則可以修改物件。

rend 可用來測試反向反覆運算器是否已到達其 multimap 結尾。

所 rend 傳回的值不應該取值。

範例

// multimap_rend.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;

   multimap <int, int> :: iterator m1_Iter;
   multimap <int, int> :: reverse_iterator m1_rIter;
   multimap <int, int> :: const_reverse_iterator m1_crIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );

   m1_rIter = m1.rend( );
   m1_rIter--;
   cout << "The last element of the reversed multimap m1 is "
        << m1_rIter -> first << "." << endl;

   // begin can be used to start an iteration
   // through a multimap in a forward order
   cout << "The multimap is: ";
   for ( m1_Iter = m1.begin( ) ; m1_Iter != m1.end( ); m1_Iter++)
      cout << m1_Iter -> first << " ";
      cout << "." << endl;

   // rbegin can be used to start an iteration
   // through a multimap in a reverse order
   cout << "The reversed multimap is: ";
   for ( m1_rIter = m1.rbegin( ) ; m1_rIter != m1.rend( ); m1_rIter++)
      cout << m1_rIter -> first << " ";
      cout << "." << endl;

   // A multimap element can be erased by dereferencing to its key
   m1_rIter = --m1.rend( );
   m1.erase ( m1_rIter -> first );

   m1_rIter = m1.rend( );
   m1_rIter--;
   cout << "After the erasure, the last element "
        << "in the reversed multimap is "
        << m1_rIter -> first << "." << endl;
}

The last element of the reversed multimap m1 is 1.
The multimap is: 1 2 3 .
The reversed multimap is: 3 2 1 .
After the erasure, the last element in the reversed multimap is 2.

`multimap::reverse_iterator`

類型，提供可以讀取或修改反轉 multimap 中之項目的雙向迭代器。

typedef std::reverse_iterator<iterator> reverse_iterator;

備註

類型 reverse_iterator 是用來反向逐一查看 multimap 。

reverse_iterator所 multimap 定義的，指向型 value_type 別為的 pair<const Key, Type> 物件。透過該配對的第一個成員，即可取得此索引鍵的值，而透過該配對的第二個成員，則可取得所對應元素的值。

若要取值 reverse_iteratorrIter 指向中的 multimap 專案，請使用 -> 運算子。

若要存取專案的索引鍵值，請使用 rIter->first(*rIter).first 相當於的。若要存取專案的對應日期值，請使用 rIter->second(*rIter).second 相當於的。

範例

如需如何宣告和使用 reverse_iterator 的範例 rbegin ，請參閱範例。

`multimap::size`

傳回 multimap 中項目的數目。

size_type size() const;

傳回值

的目前長度 multimap 。

範例

下列範例示範如何使用 multimap::size 成員函式。

// multimap_size.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main()
{
    using namespace std;
    multimap<int, int> m1, m2;
    multimap<int, int>::size_type i;
    typedef pair<int, int> Int_Pair;

    m1.insert(Int_Pair(1, 1));
    i = m1.size();
    cout << "The multimap length is " << i << "." << endl;

    m1.insert(Int_Pair(2, 4));
    i = m1.size();
    cout << "The multimap length is now " << i << "." << endl;
}

The multimap length is 1.
The multimap length is now 2.

`multimap::size_type`

不帶正負號的整數類型，可計算中的 multimap 專案數目。

typedef typename allocator_type::size_type size_type;

範例

size如需如何宣告和使用範例，請參閱範例size_type

`multimap::swap`

交換兩個 multimap 的項目。

void swap(
    multimap<Key, Type, Traits, Allocator>& right);

參數

right
提供 multimap 要交換的專案，或 multimap 要與的 multimapleft 元素交換的。

備註

成員函式不會使任何參考、指標或反覆運算器失效，這些反覆運算器會指定正在交換其專案之兩 multimap 個中的元素。

範例

// multimap_swap.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1, m2, m3;
   multimap <int, int>::iterator m1_Iter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );
   m2.insert ( Int_Pair ( 10, 100 ) );
   m2.insert ( Int_Pair ( 20, 200 ) );
   m3.insert ( Int_Pair ( 30, 300 ) );

   cout << "The original multimap m1 is:";
   for ( m1_Iter = m1.begin( ); m1_Iter != m1.end( ); m1_Iter++ )
      cout << " " << m1_Iter -> second;
   cout   << "." << endl;

   // This is the member function version of swap
   m1.swap( m2 );

   cout << "After swapping with m2, multimap m1 is:";
   for ( m1_Iter = m1.begin( ); m1_Iter != m1.end( ); m1_Iter++ )
      cout << " " << m1_Iter -> second;
   cout  << "." << endl;

   // This is the specialized template version of swap
   swap( m1, m3 );

   cout << "After swapping with m3, multimap m1 is:";
   for ( m1_Iter = m1.begin( ); m1_Iter != m1.end( ); m1_Iter++ )
      cout << " " << m1_Iter -> second;
   cout   << "." << endl;
}

The original multimap m1 is: 10 20 30.
After swapping with m2, multimap m1 is: 100 200.
After swapping with m3, multimap m1 is: 300.

`multimap::upper_bound`

將 iterator 傳回至中索引鍵大於指定索引鍵之中的 multimap 第一個專案。

iterator upper_bound(const Key& key);

const_iterator upper_bound(const Key& key) const;

參數

key
要與所搜尋專案排序索引鍵比較的 multimap 引數索引鍵。

傳回值

iterator或 const_iterator ，其定址物件為索引鍵大於引數索引鍵之中 multimap 專案的位置，如果找不到索引鍵相符專案，則定址中最後一 multimap 個專案之後的位置。

如果傳回值指派給 const_iterator ， multimap 則無法修改物件。如果傳回值指派給 iterator ， multimap 則可以修改物件。

範例

// multimap_upper_bound.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   multimap <int, int> m1;
   multimap <int, int> :: const_iterator m1_AcIter, m1_RcIter;
   typedef pair <int, int> Int_Pair;

   m1.insert ( Int_Pair ( 1, 10 ) );
   m1.insert ( Int_Pair ( 2, 20 ) );
   m1.insert ( Int_Pair ( 3, 30 ) );
   m1.insert ( Int_Pair ( 3, 40 ) );

   m1_RcIter = m1.upper_bound( 1 );
   cout << "The 1st element of multimap m1 with "
        << "a key greater than 1 is: "
        << m1_RcIter -> second << "." << endl;

   m1_RcIter = m1.upper_bound( 2 );
   cout << "The first element of multimap m1 with a key "
        << " greater than 2 is: "
        << m1_RcIter -> second << "." << endl;

   // If no match is found for the key, end( ) is returned
   m1_RcIter = m1.lower_bound( 4 );

   if ( m1_RcIter == m1.end( ) )
      cout << "The multimap m1 doesn't have an element "
           << "with a key of 4." << endl;
   else
      cout << "The element of multimap m1 with a key of 4 is: "
           << m1_RcIter -> second << "." << endl;

   // The element at a specific location in the multimap can be
   // found using a dereferenced iterator addressing the location
   m1_AcIter = m1.begin( );
   m1_RcIter = m1.upper_bound( m1_AcIter -> first );
   cout << "The first element of m1 with a key greater than\n"
        << "that of the initial element of m1 is: "
        << m1_RcIter -> second << "." << endl;
}

The 1st element of multimap m1 with a key greater than 1 is: 20.
The first element of multimap m1 with a key  greater than 2 is: 30.
The multimap m1 doesn't have an element with a key of 4.
The first element of m1 with a key greater than
that of the initial element of m1 is: 20.

`multimap::value_comp`

成員函式傳回函式物件，可藉由比較其索引鍵值判斷 multimap 中項目的順序。

value_compare value_comp() const;

傳回值

傳回用來排序其專案的比較函式物件 multimap 。

備註

multimapm 如果是，如果兩 e1(k1, d1) 個專案和是型 value_type 別的物件，其中 k1 和 k2e2(k2, d2) 是型別的 key_type 索引鍵， d1 而且 d2 是其型 mapped_type 別的資料，則 m.value_comp(e1, e2) 相當於 m.key_comp(k1, k2) 。

範例

// multimap_value_comp.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;

   multimap <int, int, less<int> > m1;
   multimap <int, int, less<int> >::value_compare vc1 = m1.value_comp( );
   multimap<int,int>::iterator Iter1, Iter2;

   Iter1= m1.insert ( multimap <int, int> :: value_type ( 1, 10 ) );
   Iter2= m1.insert ( multimap <int, int> :: value_type ( 2, 5 ) );

   if( vc1( *Iter1, *Iter2 ) == true )
   {
      cout << "The element ( 1,10 ) precedes the element ( 2,5 )."
           << endl;
   }
   else
   {
      cout << "The element ( 1,10 ) does "
           << "not precede the element ( 2,5 )."
           << endl;
   }

   if( vc1( *Iter2, *Iter1 ) == true )
   {
      cout << "The element ( 2,5 ) precedes the element ( 1,10 )."
           << endl;
   }
   else
   {
      cout << "The element ( 2,5 ) does "
           << "not precede the element ( 1,10 )."
           << endl;
   }
}

The element ( 1,10 ) precedes the element ( 2,5 ).
The element ( 2,5 ) does not precede the element ( 1,10 ).

`multimap::value_type`

一種類型，代表以元素形式儲存在 map 中的物件類型。

typedef pair<const Key, Type> value_type;

範例

// multimap_value_type.cpp
// compile with: /EHsc
#include <map>
#include <iostream>

int main( )
{
   using namespace std;
   typedef pair <const int, int> cInt2Int;
   multimap <int, int> m1;
   multimap <int, int> :: key_type key1;
   multimap <int, int> :: mapped_type mapped1;
   multimap <int, int> :: value_type value1;
   multimap <int, int> :: iterator pIter;

   // value_type can be used to pass the correct type
   // explicitly to avoid implicit type conversion
   m1.insert ( multimap <int, int> :: value_type ( 1, 10 ) );

   // Compare another way to insert objects into a hash_multimap
   m1.insert ( cInt2Int ( 2, 20 ) );

   // Initializing key1 and mapped1
   key1 = ( m1.begin( ) -> first );
   mapped1 = ( m1.begin( ) -> second );

   cout << "The key of first element in the multimap is "
        << key1 << "." << endl;

   cout << "The data value of first element in the multimap is "
        << mapped1 << "." << endl;

   // The following line would cause an error because
   // the value_type is not assignable
   // value1 = cInt2Int ( 4, 40 );

   cout  << "The keys of the mapped elements are:";
   for ( pIter = m1.begin( ) ; pIter != m1.end( ) ; pIter++ )
      cout << " " << pIter -> first;
   cout << "." << endl;

   cout  << "The values of the mapped elements are:";
   for ( pIter = m1.begin( ) ; pIter != m1.end( ) ; pIter++ )
      cout << " " << pIter -> second;
   cout << "." << endl;
}

The key of first element in the multimap is 1.
The data value of first element in the multimap is 10.
The keys of the mapped elements are: 1 2.
The values of the mapped elements are: 10 20.

另請參閱

容器
 C++ 標準程式庫中的執行緒安全
 C++ 標準程式庫參考