hash_multimap::insert

Inserts an element or a range of elements into a hash_multimap.

iterator insert(
   const value_type& _Val
);
iterator insert(
   const_iterator _Where,
   const value_type& _Val
);
template<class InputIterator> 
   void insert(
      InputIterator _First,
      InputIterator _Last
);
template<class ValTy>
    iterator insert(
        ValTy&& _Val
);
template<class ValTy>
    iterator insert(
        const_iterator _Where,
        ValTy&& _Val
);

Parameters

Parameter	Description
_Val	The value of an element to be inserted into the hash_multimap unless the hash_multimap already contains that element or, more generally, an element whose key is equivalently ordered.
_Where	A hint regarding the place to start searching for the correct point of insertion.
_First	The position of the first element to be copied from a map.
_Last	The position just beyond the last element to be copied from a map.

Return Value

The first two insert member functions return an iterator that points to the position where the new element was inserted.

The last two insert member functions behave the same as the first two, except that they move construct the inserted value.

Remarks

The value_type of an element is a pair, so that the value of an element will be an ordered pair with the first component equal to the key value and the second component equal to the data value of the element.

Insertion can occur in amortized constant time for the hint version of insert, instead of logarithmic time, if the insertion point immediately follows _Where.

The third member function inserts the sequence of element values into a map corresponding to each element addressed by an iterator of in the range [_First, _Last) of a specified set.

Example

// hash_multimap_insert.cpp
// compile with: /EHsc
#include <hash_map>
#include <iostream>
#include <string>

int main( )
{
   using namespace std;
   using namespace stdext;
   hash_multimap <int, int>::iterator hm1_pIter, hm2_pIter;

   hash_multimap <int, int> hm1, hm2;
   typedef pair <int, int> Int_Pair;

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

   cout << "The original key values of hm1 =";
   for ( hm1_pIter = hm1.begin( ); hm1_pIter != hm1.end( );
      hm1_pIter++ )
      cout << " " << hm1_pIter -> first;
   cout << "." << endl;

   cout << "The original mapped values of hm1 =";
   for ( hm1_pIter = hm1.begin( ); hm1_pIter != hm1.end( ); 
      hm1_pIter++ )
      cout << " " << hm1_pIter -> second;
   cout << "." << endl;

   hm1.insert ( Int_Pair ( 1, 10 ) );

   // The hint version of insert
   hm1.insert( --hm1.end( ), Int_Pair ( 4, 40 )  );

   cout << "After the insertions, the key values of hm1 =";
   for ( hm1_pIter = hm1.begin( ); hm1_pIter != hm1.end( ); 
      hm1_pIter++ )
      cout << " " << hm1_pIter -> first;
   cout << "," << endl;

   cout << " and the mapped values of hm1 =";
   for ( hm1_pIter = hm1.begin( ); hm1_pIter != hm1.end( ); 
      hm1_pIter++ )
      cout << " " << hm1_pIter -> second;
   cout << "." << endl;

   hm2.insert ( Int_Pair ( 10, 100 ) );

   // The templatized version inserting a range
   hm2.insert( ++hm1.begin( ), --hm1.end( ) );

   cout << "After the insertions, the key values of hm2 =";
   for ( hm2_pIter = hm2.begin( ); hm2_pIter != hm2.end( ); 
      hm2_pIter++ )
      cout << " " << hm2_pIter -> first;
   cout << "," << endl;

   cout << " and the mapped values of hm2 =";
   for ( hm2_pIter = hm2.begin( ); hm2_pIter != hm2.end( ); 
      hm2_pIter++ )
      cout << " " << hm2_pIter -> second;
   cout << "." << endl;

    // The templatized versions move constructing elements
    hash_multimap<int, string> hm3, hm4;
    pair<int, string> is1(1, "a"), is2(2, "b");

    hm3.insert(move(is1));
    cout << "After the move insertion, hm3 contains:" << endl
      << " " << hm3.begin()->first
      << " => " << hm3.begin()->second
      << endl;

    hm4.insert(hm4.begin(), move(is2));
    cout << "After the move insertion, hm4 contains:" << endl
      << " " << hm4.begin()->first
      << " => " << hm4.begin()->second
      << endl;
}

The original key values of hm1 = 1 2 3.
The original mapped values of hm1 = 10 20 30.
After the insertions, the key values of hm1 = 1 1 2 3 4,
 and the mapped values of hm1 = 10 10 20 30 40.
After the insertions, the key values of hm2 = 1 2 10 3,
 and the mapped values of hm2 = 10 20 100 30.
After the move insertion, hm3 contains:
 1 => a
After the move insertion, hm4 contains:
 2 => b

Requirements

Header: <hash_map>

Namespace: stdext

See Also

Reference

hash_multimap Class

Standard Template Library

Other Resources

hash_multimap Members