`multimap` クラス

[アーティクル]
06/16/2023

C++ 標準ライブラリの multimap クラスは、各要素がデータ値と並べ替えキーのペアであるコレクションのデータを格納および取得するために使用されます。キーの値は一意である必要がなく、データを自動的に並べ替えるために使用されます。 multimap の要素の値 (関連するキー値ではありません) は、直接変更できます。この場合、変更前の要素に関連付けられていたキー値を削除し、新しい要素に関連付けられる新しいキー値を挿入する必要があります。

構文

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

パラメーター

Key
multimap に格納されるキーのデータ型。

Type
multimap に格納される要素のデータ型。

Traits
2 つの要素の値を並べ替えキーとして比較して、multimap 内の要素の相対順序を決定できる関数オブジェクトを提供する型。二項述語 less<Key> が既定値です。

C++ 14 では、型パラメーターを使用せずに std::less<> 述語または std::greater<> 述語を指定することで、異種ルックアップを有効にすることができます。詳細については、「連想コンテナーの異種ルックアップ」をご覧ください。

Allocator
メモリの map の割り当てと解放に関する詳細をカプセル化する、格納されたアロケーターオブジェクトを表す型。この引数は省略可能であり、既定値は allocator<pair <const Key, Type> > です。

解説

C++ 標準ライブラリ multimap クラスには下記の特徴があります。

hash_map は連想コンテナーであり、関連付けられたキー値に基づいて要素の値を効率的に取得できるようにする可変サイズのコンテナーとして機能します。
反転することができます。これは、要素にアクセスするための双方向反復子が用意されているためです。
並べ替えが実行されます。これは、指定した比較関数に従ってコンテナー内のキー値によって要素に順序が設定されるためです。
複数対応です。要素は一意のキーを持つ必要がないので、関連する多くの要素データ値を 1 つのキー値が持つことができるためです。
ペアを保持する連想コンテナーです。これは、要素のデータ値とキー値が分かれているためです。
クラステンプレートとして機能します。これは、このクラスに用意されている機能が汎用的な機能であり、要素またはキーとして保持されているデータの特定の型に依存しないためです。要素やキーに使用されているデータ型は、クラステンプレートで比較関数やアロケーターと共にパラメーターとして指定されます。

map クラスによって提供される反復子は双方向反復子ですが、クラスメンバー関数 insert は multimap 、テンプレートパラメーターとして弱い入力反復子を受け取るバージョンを持ちます。その機能要件は、双方向反復子のクラスによって保証されるものよりも最小限です。これらの反復子の機能に差異があるのは、反復子の概念が異なっているためです。反復子の各概念には、反復子独自の一連の要件が含まれています。また、それらの要件を使用するアルゴリズムでは、反復子の種類ごとに指定されている要件に対して、前提を絞り込む必要があります。たとえば、一部のオブジェクトを参照するために入力反復子が逆参照される可能性があることを前提とする場合があります。さらに、シーケンス内にある次の反復子に対して逆参照が増加する可能性があることを前提とする場合もあります。このことは、最小限実施することですが、クラスのメンバー関数のコンテキストに含まれる反復子の範囲 [First, Last) について明確にすることも重要です。

一般的に、コンテナー型の選択は、アプリケーションにおいて必要な検索および挿入の種類に基づいている必要があります。連想コンテナーは、検索、挿入、削除の各操作用に最適化されています。これらの操作を明示的にサポートするメンバー関数は効率的であり、処理時間は平均的にコンテナー内にある要素の数の対数に比例します。要素を挿入しても反復子の有効性は失われません。また、要素を削除した場合は、削除された要素を指していた反復子だけが無効化されます。

値とキーを関連付ける条件をアプリケーションが満たしている場合、multimap は最適な連想コンテナーとなっている必要があります。この種類の構造体のモデルとなるのは、キーワードとそれに関連する文字列値 (たとえば定義) の順序付きリストです。キーワードは常に一意に定義されるわけではありません。そうではなくて、キーワードが一意に定義され、キーが一意になる場合は、map が最適なコンテナーです。また、キーワードのリストだけが格納される場合は、set が適切なコンテナーとなります。キーワードを複数設定できる場合は、multiset が適切なコンテナー構造体となります。

multimap では、key_compare 型の格納されている関数オブジェクトを呼び出すことで、制御するシーケンスを並べ替えます。この格納されているオブジェクトは比較関数であり、メンバー関数 key_comp を呼び出してアクセスできます。通常、要素は、この順序を確立するために小なり比較だけを実行できる必要があります。これにより、2 つの要素が指定されたときに、それらの要素が等しいか (どちらか一方が小さくはない)、または一方が他方より小さいかを判断できます。この結果、等価でない複数の要素間で順序が付けられます。テクニカルノートでは、比較関数は、数学上の標準的な意味で厳密弱順序を発生させる二項述語であると示されています。二項述語 f(x,y) は、2 つの引数オブジェクト (x および y) と戻り値 (true または false) を持つ関数オブジェクトです。 set に適用される順序付けは、二項述語が非再帰、反対称、推移的であり、等価性が推移的である (2 つのオブジェクト x と y が、f(x,y) と f(y,x) の両方が false の場合に等価になるように定義されている) 場合、厳密弱順序になります。 2 つのキーの等値に関する条件が等価性の条件よりも厳しく、優先される場合、順序付けは完全な順序付け (すべての要素が相互の値に基づいて並べ替えられる) となり、一致するそれぞれのキーを識別するのが難しくなります。

メンバー

コンストラクター

コンストラクター	説明
`multimap`	空の `multimap`、または他の `multimap` の全体または一部のコピーである hash_multiset を構築します。

Typedefs

型名	説明
`allocator_type`	`allocator` オブジェクトの `multimap` クラスを表す型。
`const_iterator`	`const` 内の 1 つの `multimap` 要素を読み取ることができる双方向反復子を提供する型。
`const_pointer`	`const` 内の `multimap` 要素へのポインターを提供する型。
`const_reference`	読み取りと `const` 操作を実行するために、`multimap` に格納された `const` 要素への参照を提供する型。
`const_reverse_iterator`	`const` 内の任意の `multimap` 要素を読み取ることができる双方向反復子を提供する型。
`difference_type`	`multimap` の要素の数を、反復子が指す要素の範囲に基づいて表すために使用できる符号付き整数型。
`iterator`	同じ `multimap` 内の要素を参照する 2 つの反復子の違いを提供する型。
`key_compare`	2 つの並べ替えキーを比較して、`multimap` 内の 2 つの要素の相対順序を決定できる関数オブジェクトを提供する型。
`key_type`	`multimap` の各要素を構成する並べ替えキーオブジェクトを表す型。
`mapped_type`	`multimap` に格納されているデータ型を表す型。
`pointer`	`const` 内の `multimap` 要素へのポインターを提供する型。
`reference`	`multimap` に格納されている要素への参照を提供する型。
`reverse_iterator`	反転された `multimap` 内の 1 つの要素を読み取り、または変更できる双方向反復子を提供する型。
`size_type`	`const` 内の `multimap` 要素へのポインターを提供する符号なし整数型。
`value_type`	2 つの要素を並べ替えキーとして比較して、`multimap` 内の要素の相対順序を決定できる関数オブジェクトを提供する型。

メンバー関数

メンバー関数	説明
`begin`	`multimap` 内の最初の要素を指す反復子を返します。
`cbegin`	`multimap` 内の最初の要素を指す `const` 反復子を返します。
`cend`	`multimap` 内の最後の要素の次の位置を指す `const` 反復子を返します。
`clear`	`multimap` のすべての要素を消去します。
`contains`^C++20	`multimap` 内に指定されたキーを持つ要素があるかどうかを確認します。
`count`	パラメーター指定したキーに一致するキーを持つ、`multimap` 内の要素の数を返します。
`crbegin`	反転された `multimap` 内の最初の要素を指す `const` 反復子を返します。
`crend`	反転された `multimap` 内の最後の要素の次の位置を指す `const` 反復子を返します。
`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`	2 つの `multimap` の要素を交換します。
`upper_bound`	指定したキーよりも大きいキーを持つ、`multimap` 内の最初の要素を指す反復子を返します。
`value_comp`	このメンバー関数は、キー値の比較によって `multimap` の要素の順序を決定する関数オブジェクトを返します。

Operator	説明
`operator=`	別の `multimap` のコピーで `multimap` の要素を置き換えます。

必要条件

ヘッダー:<map>

名前空間std:

(key, value) のペアは、pair 型のオブジェクトとして 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 が const と begin() をサポートする任意の種類の変更可能な (非 cbegin()) コンテナーであると見なします。

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 が const と end() をサポートする任意の種類の変更可能な (非 cend()) コンテナーであると見なします。

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 内の 1 つの multimap 要素を読み取ることができる双方向反復子を提供する型。

typedef implementation-defined const_iterator;

解説

const_iterator 型で要素の値を変更することはできません。

multimap によって定義される const_iterator は、value_type のオブジェクトを指します。これは pair<const Key, Type> 型です。キーの値はペアの 1 番目のメンバー、マップされた要素の値はペアの 2 番目のメンバーを介して取得できます。

multimap 内の要素を指す const_iteratorcIter を逆参照するには、-> 演算子を使用します。

要素のキーの値にアクセスするには、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 型で要素の値を変更することはできません。

ほとんどの場合、multimap オブジェクト内の要素にアクセスするには、iterator を使用する必要があります。

`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 を反復処理するために使用します。

multimap によって定義される const_reverse_iterator は、value_type のオブジェクトを指します。これは pair<const Key, Type> 型です。キーの値はペアの 1 番目のメンバー、マップされた要素の値はペアの 2 番目のメンバーを介して取得できます。

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`

反転された multimap 内の最初の要素を指す const 反復子を返します。

const_reverse_iterator crbegin() const;

戻り値

逆順の multimap 内の最初の要素を指す const 逆順双方向反復子 (または通常の順序の multimap 内の最後の要素だったものを指す定数逆順双方向反復子)。

解説

crbegin は、begin が multimap で使用されるのと同様に、反転された multimap で使用されます。

戻り値が 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`

反転された multimap 内の最後の要素の次の位置を指す const 反復子を返します。

const_reverse_iterator crend() const;

戻り値

逆順の multimap 内の最後の要素の次の場所 (通常の順序の multimap 内の最初の要素の前の場所) を指す const 逆順双方向反復子。

解説

crend は、multimap::end が multimap で使用されるのと同様に、反転された multimap で使用されます。

戻り値が 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 の間にある要素の数を表すために使用され、first が指す要素と、last が指す要素の 1 つ前までの範囲の要素を含みます。

difference_type は、入力反復子の要件を満たすすべての反復子 (set などの反転可能なコンテナーによってサポートされる双方向反復子のクラスを含む) に対して使用できますが、反復子間の減算は、vector などのランダムアクセスコンテナーによって提供される、ランダムアクセス反復子によってのみサポートされます。

例

// 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 はペアです。最初のコンポーネントがキー値と等しく、2 番目のコンポーネントが要素のデータ値と等しくなるよう、要素の値が順序付けされたペアになります。

例

// 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 の直前にある場合、挿入処理は対数時間ではなく償却定数時間で実行できます)。

戻り値

新しく挿入される要素を指す反復子。

解説

この関数では、コンテナー要素を指す参照は無効になりません。ただし、コンテナーを指すすべての反復子が無効になる場合があります。

配置の実行中、例外がスローされるとコンテナーの状態は変更されません。

コード例については、「map::emplace_hint」を参照してください。

`multimap::empty`

multimap が空かどうかをテストします。

bool empty() const;

戻り値

multimap が空の場合は true。multimap が空でない場合は false。

例

// 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`

末尾超え反復子を返します。

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 内の要素の並べ替えキーと比較される引数キー。

戻り値

1 番目がそのキーの lower_bound、2 番目がそのキーの upper_bound である、反復子のペア。

メンバー関数によって返されたペア pr の 1 つめの反復子にアクセスするには pr.first を使用し、下限の反復子を逆参照するには *(pr.first) を使用します。メンバー関数によって返されたペア pr の 2 番目の反復子にアクセスするには 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
削除する要素のキー。

戻り値

最初の 2 つのメンバー関数の場合は、削除された要素の後の最初の残存要素、またはマップの最後の要素 (このような要素が存在しない場合) を指定する双方向反復子。

3 番目のメンバー関数の場合は、multimap から削除された要素の数を返します。

解説

コード例については、「map::erase」を参照してください。

`multimap::find`

指定したキーと等価のキーを持つ、multimap 内の要素の最初の位置を参照する反復子を返します。

iterator find(const Key& key);

const_iterator find(const Key& key) const;

パラメーター

key
検索対象の multimap 内の要素の並べ替えキーによって照合されるキー値。

戻り値

指定したキーを持つ要素の位置を参照する反復子。キーの一致が検出されない場合は、set 内の最後の要素の次の位置 multimap (multimap::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++ における高度な作業の 1 つです。

例

// 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
map が value_type の要素を構築するために使用できる引数の型を指定し、Val を引数として完全転送するテンプレートパラメーター。

First
コピーされる最初の要素の位置。

Last
コピーされる最後の要素の次の位置。

InputIterator
input 反復子の要件を満たすテンプレート関数の引数。これは、value_type オブジェクトの構築に使用できる型の要素を指し示します。

IList
要素のコピー元の initializer_list。

戻り値

単一要素の insert メンバー関数 (1) と (2) は、新しい要素が multimap に挿入された位置を指す反復子を返します。

単一要素とヒントのメンバー関数 (3) と (4) は、新しい要素が multimap に挿入された位置を指す反復子を返します。

解説

この関数では、ポインターや参照は無効になりません。ただし、コンテナーを指すすべての反復子が無効になる場合があります。

要素を 1 つだけ挿入するとき、例外がスローされるとコンテナーの状態は変更されません。複数の要素を挿入するときに例外がスローされた場合、コンテナーの状態は未指定ですが、有効な状態になっています。

コンテナーの value_type はそのコンテナーに属する typedef であり、map の場合、multimap<K, V>::value_type は pair<const K, V> です。要素の値は順序付けされたペアになり、このペアの最初のコンポーネントはキー値と同じで、2 番目のコンポーネントは要素のデータ値と同じになります。

範囲を指定したメンバー関数 (5) は、範囲 [First, Last) の反復子によってアドレス指定された各要素に対応する multimap に要素値のシーケンスを挿入します。したがって、Last は挿入されません。コンテナーのメンバー関数 end() は、コンテナー内にある最後の要素の直後の位置を参照します。たとえば、ステートメント m.insert(v.begin(), v.end()); は、v のすべての要素を m に挿入します。

初期化子リストのメンバー関数 (6) は、initializer_list を使用して map に要素をコピーします。

インプレースで構築された (つまり、コピーまたは移動操作が実行されない) 要素の挿入については、「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;

解説

multimap によって定義される iterator は、value_type のオブジェクトを指します。これは pair<const Key, Type> 型です。キーの値はペアの 1 番目のメンバー、マップされた要素の値はペアの 2 番目のメンバーを介して取得できます。

multimap 内の要素を指す iteratorIter を逆参照するには、-> 演算子を使用します。

要素のキーの値にアクセスするには、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`

2 つの並べ替えキーを比較して、multimap 内の 2 つの要素の相対順序を決定できる関数オブジェクトを提供する型。

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 内の要素の並べ替えキーと比較される引数キー。

戻り値

引数キー以上のキーを持つ multimap 内の要素の位置を指す、または、キーの一致が検出されない場合は multimap 内の最後の要素の次の位置を指す、反復子または const_iterator。

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 の全体または一部のコピーである hash_multiset を構築します。

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 の比較関数。既定では Traits です。

Right
構築される map のコピー元となる map。

First
コピーする要素範囲内の最初の要素の位置。

Last
コピーする要素範囲を超える最初の要素の位置。

IList
要素のコピー元の initializer_list。

解説

すべてのコンストラクターは、アロケーターオブジェクトの型を格納します。このオブジェクトは multimap のメモリストレージを管理し、後で get_allocator を呼び出して取得することができます。代替アロケーターの代わりに使用されるクラス宣言やプリプロセスマクロでは、アロケーターのパラメーターが省略される場合があります。

すべてのコンストラクターは、それぞれの multimap を初期化します。

すべてのコンストラクターは、Traits 型の関数オブジェクトを格納します。このオブジェクトは multimap のキーの順序を確立するために使用され、後で key_comp を呼び出して取得することができます。

最初の 3 つのコンストラクターは、空の初期 multimap を指定します。2 番目のコンストラクターは要素の順序を確立するために使用する比較関数の型 (Comp) を指定し、3 番目のコンストラクターは使用するアロケーターの型 (Al) を明示的に指定します。キーワード explicit は、特定の種類の自動型変換が実行されないようにします。

4 番目のコンストラクターは、multimapRight のコピーを指定します。

5 つ目のコンストラクターは、Right を移動することによる multimap のコピーを指定します。

6 番目、7 番目、8 番目のコンストラクターは、initializer_list のメンバーをコピーします。

次の 3 つのコンストラクターは、map の範囲 [First, Last) をコピーします。下のコンストラクターになるほど、より明確に Traits クラスの比較関数と Allocator の型が指定されています。

例

// 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 は要素の値の変更に使用できます。

ほとんどの場合、multimap オブジェクト内の要素にアクセスするには、iterator を使用する必要があります。

`multimap::rbegin`

反転された multimap 内の最初の要素を指す反復子を返します。

const_reverse_iterator rbegin() const;

reverse_iterator rbegin();

戻り値

逆順の multimap 内の最初の要素を指す逆順双方向反復子 (または通常の順序の multimap 内の最後の要素だったものを指す定数逆順双方向反復子)。

解説

rbegin は、begin が multimap で使用されるのと同様に、反転された multimap で使用されます。

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 は、end が multimap で使用されるのと同様に、反転された multimap で使用されます。

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 内の 1 つの要素を読み取り、または変更できる双方向反復子を提供する型。

typedef std::reverse_iterator<iterator> reverse_iterator;

解説

型 reverse_iterator は、逆の順序で multimap を反復処理するために使用します。

multimap によって定義される reverse_iterator は、value_type のオブジェクトを指します。これは pair<const Key, Type> 型です。キーの値はペアの 1 番目のメンバー、マップされた要素の値はペアの 2 番目のメンバーを介して取得できます。

multimap 内の要素を指す reverse_iteratorrIter を逆参照するには、-> 演算子を使用します。

要素のキーの値にアクセスするには、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_type の宣言や使用の方法の例については、size の例を参照してください

`multimap::swap`

2 つの multimap の要素を交換します。

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

パラメーター

right
交換する要素を提供する multimap (multimapleft と要素を交換する multimap)。

解説

このメンバー関数が、要素を交換する 2 つの 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`

指定したキーよりも大きいキーを持つ、multimap 内の最初の要素を指す iterator を返します。

iterator upper_bound(const Key& key);

const_iterator upper_bound(const Key& key) const;

パラメーター

key
検索対象の multimap 内の要素の並べ替えキーと比較される引数キー。

戻り値

引数キーより大きいキーを持つ multimap 内の要素の位置を指す、または、キーの一致が検出されない場合は multimap 内の最後の要素の次の位置を指す、iterator または const_iterator。

戻り値が 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 の場合、2 つの要素 e1(k1, d1) と e2(k2, d2) が value_type 型のオブジェクトであり、k1 と k2 が 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.