=====insert=====
Syntax:

<code>
    #include <map>
    iterator insert( iterator i, const TYPE& pair );
    void insert( input_iterator start, input_iterator end );
    pair<iterator,bool> insert( const TYPE& pair );
</code>

The function insert() either:

  * inserts pair after the element at pos (where pos is really just a suggestion as to where pair should go, since sets and maps are ordered), and returns an iterator to that element.
  * inserts a range of elements from start to end.
  * inserts pair<key,val>, but only if no element with key key already exists. The return value is an iterator to the element inserted (or an existing pair with key key), and a boolean which is true if an insertion took place.

For example, the following code uses the insert() function (along with the
make_pair() function) to insert some data into a map and then displays that
data:

<code>
    map<string,int> theMap;
    theMap.insert( make_pair( "Key 1", -1 ) );
    theMap.insert( make_pair( "Another key!", 32 ) );
    theMap.insert( make_pair( "Key the Three", 66667 ) );

    map<string,int>::iterator iter;
    for( iter = theMap.begin(); iter != theMap.end(); ++iter ) {
      cout << "Key: '" << iter->first << "', Value: " << iter->second << endl;
    }
</code>

When run, the above code displays this output:

<code terminal>
    Key: 'Another key!', Value: 32
    Key: 'Key 1', Value: -1
    Key: 'Key the Three', Value: 66667
</code>

Note that because maps are sorted containers, the output is sorted by the key
value. In this case, since the map key data type is string, the map is sorted
alphabetically by key.

Related Topics: [[map_operators|[] operator]]