map::erase

Removes an element or a range of elements in a map from specified positions or removes elements that match a specified key.

iterator erase(
   iterator _Where
);
iterator erase(
   iterator _First,
   iterator _Last
);
size_type erase(
   const key_type& _Key
);

Parameters

• _Where
  Position of the element to be removed from the map.

• _First
  Position of the first element removed from the map.

• _Last
  Position just beyond the last element removed from the map.

• _Key
  The key value of the elements to be removed from the map.

Return Value

For the first two methods, a bidirectional iterator that designates the first element remaining beyond the elements removed, or a pointer to the end of the map if no such element exists.

Note

This return type does not conform to the C++ standard.

For the third method, 1 if an element is removed from the map; 0 if no element is removed.

Remarks

The following example demonstrates the three overloads of map::erase.

   map<int, int> m;
    map<int, int>::iterator iter;

    // {0, 100} {1, 101} ... {5, 105} 
    for(int i = 0; i < 6; i+)
    {
        m[i] = i + 100;
    }

    // by iterator: erase the first element {0, 100}
    iter = m.begin();
    m.erase(iter);

    cout << "After erasing:" << endl;
    for(iter = m.begin(); iter != m.end(); iter+)
    {
        cout << iter->first << ", " << iter->second << endl;
    }

    // by range: erase all elements but first and last
    map<int, int>::iterator iter1 = ++m.begin();
    map<int, int>::iterator iter2 = --m.end();
    m.erase(iter1, iter2);

    cout << endl << "After erasing:" << endl;
    for(iter = m.begin(); iter != m.end(); iter+)
    {
        cout << iter->first << ", " << iter->second << endl;
    }

    // by key: erase {1, 101}
    m.erase(1);

    cout << endl << "After erasing:" << endl;
    for(iter = m.begin(); iter != m.end(); iter+)
    {
        cout << iter->first << ", " << iter->second << endl;
    }

    // Output: 
    // -------------------------- 
    // After erasing the first element: 
    // 1, 101 
    // 2, 102 
    // 3, 103 
    // 4, 104 
    // 5, 105 
    // 
    // After erasing: 
    // 1, 101 
    // 5, 105 
    // 
    // After erasing: 
    // 5, 105

When looping, this method throws an out_of_range exception if you do not assign the return value of the erase (the next valid iterator) to the looping iterator.

The following example demonstrates the correct usage of map::erase in a loop.

// when you call m.erase, iter becomes undefined 
    // you must assign the return value (the next valid iterator) to iter to continue looping 
    for(iter = m.begin(); iter != m.end(); )
    {
        // simply using m.erase(iter) causes the application to throw 
        // an unhandled exception on the next loop iteration
        iter = m.erase(iter);
    }

    if(m.empty())
    {
        cout << "m is empty" << endl;
    }

    // Output: 
    // -------------------------- 
    // m is empty

Requirements

Header: <map>

Namespace: std

See Also

Reference

map Class

map::max_size, map::clear, map::erase, and map::size

Standard Template Library

Other Resources

map Members

Change History

Date	History	Reason
July 2009	Cleaned up topic; rewrote code examples; added section on looping.	Customer feedback.