map::insert

map::insert

Switch on low bandwidth view

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

Visual C++ Standard Library

map::insert

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

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

Parameters

_Val: The value of an element to be inserted into the map unless the map 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 insert member function returns a pair whose bool component returns true if an insertion was made and false if the map already contained an element whose key had an equivalent value in the ordering, and whose iterator component returns the address where a new element was inserted or where the element was already located.

To access the iterator component of a pair pr returned by this member function, use pr.first, and to dereference it, use *(pr.first). To access the bool component of a pair pr returned by this member function, use pr.second.

The second insert member function, the hint version, returns an iterator that points to the position where the new element was inserted into the map.

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

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

int main( ) {
   using namespace std;
   map <int, int>::iterator m1_pIter, m2_pIter;

   map <int, int> m1, m2;
   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 ( 4, 40 ) );

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

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

   pair< map<int,int>::iterator, bool > pr;
   pr = m1.insert ( Int_Pair ( 1, 10 ) );

   if( pr.second == true ) {
      cout << "The element 10 was inserted in m1 successfully." << endl;
   }
   else {
      cout << "Key number 1 already exists in m1\n"
           << "with an associated value of ( (pr.first) -> second ) = " 
           << ( pr.first ) -> second 
           << "." << endl;
   }

   // The hint version of insert
   m1.insert( --m1.end( ), Int_Pair ( 5, 50 ) );

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

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

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

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

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

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

Output

The original key values of m1 = 1 2 3 4.
The original mapped values of m1 = 10 20 30 40.
Key number 1 already exists in m1
with an associated value of ( (pr.first) -> second ) = 10.
After the insertions, the key values of m1 = 1 2 3 4 5,
and the mapped values of m1 = 10 20 30 40 50.
After the insertions, the key values of m2 = 2 3 4 10,
and the mapped values of m2 = 20 30 40 100.

Requirements

Header: <map>

Namespace: std

Reference

map Class

map::insert, map::find, and map::end

Standard Template Library

Other Resources

map Members