# std::map<Key,T,Compare,Allocator>::erase

> C++ Atlas: `cppatlas.com/w/cpp/container/map/erase` | Source: https://en.cppreference.com/w/cpp/container/map/erase | Domain: Containers | Standards: C++11, C++23

Removes specified elements from the container.

## Official Specification Summary (cppreference)

```cpp
iterator erase( iterator pos ); // (1)

iterator erase( const_iterator pos ); // (2) (since C++11)

iterator erase( iterator first, iterator last ); // (3) (until C++11)

iterator erase( const_iterator first, const_iterator last ); // (3) (since C++11)

size_type erase( const Key& key ); // (4)

template< class K >
size_type erase( K&& x ); // (5) (since C++23)
```

Removes specified elements from the container.

1,2) Removes the element at `pos`.

3) Removes the elements in the range `[first,` `last)`, which must be a valid range in `*this`.

4) Removes the element (if one exists) with the key equivalent to `key`.

5) Removes all elements with key that compares *equivalent* to the value `x`. This overload participates in overload resolution only if the qualified-id `Compare::is_transparent` is valid and denotes a type, and neither `iterator` nor `const_iterator` is implicitly convertible from `K`. It allows calling this function without constructing an instance of `Key`.

References and iterators to the erased elements are invalidated. Other references and iterators are not affected.

The iterator `pos` must be valid and dereferenceable. Thus the `end()` iterator (which is valid, but is not dereferenceable) cannot be used as a value for `pos`.

### Parameters

- `pos` - iterator to the element to remove
- `first, last` - range of elements to remove
- `key` - key value of the elements to remove
- `x` - a value of any type that can be transparently compared with a key denoting the elements to remove

### Return value

1-3) Iterator following the last removed element.

4) Number of elements removed (0 or 1).

5) Number of elements removed.

### Exceptions

1-3) Throws nothing.

4,5) Any exceptions thrown by the `Compare` object.

### Complexity

Given an instance `c` of `map`:

1,2) Amortized constant

3) `log(c.size()) + std::distance(first, last)`

4) `log(c.size()) + c.count(key)`

5) `log(c.size()) + c.count(x)`

### Notes

| Feature-test macro | Value | Std | Feature |
| --- | --- | --- | --- |
| `__cpp_lib_associative_heterogeneous_erasure` | `202110L` | (C++23) | Heterogeneous erasure in associative containers and unordered associative containers; overload (5) |

### Example

```cpp
#include <map>
#include <iostream>

int main()
{
    std::map<int, std::string> c =
    {
        {1, "one"}, {2, "two"}, {3, "three"},
        {4, "four"}, {5, "five"}, {6, "six"}
    };

    // erase all odd numbers from c
    for (auto it = c.begin(); it != c.end();)
    {
        if (it->first % 2 != 0)
            it = c.erase(it);
        else
            ++it;
    }

    for (auto& p : c)
        std::cout << p.second << ' ';
    std::cout << '\n';
}
```

Output:

```text
two four six
```

### Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

| DR | Applied to | Behavior as published | Correct behavior |
| --- | --- | --- | --- |
| LWG 130 | C++98 | the return type of overloads (1) and (3) was `void` (it is not consistent with the `erase()` requirement on sequence containers) | corrected to `iterator` |
| LWG 2059 | C++11 | replacing overload (1) with overload (2) introduced new ambiguity | added overload (1) back |

### See also

- [`clear`](https://en.cppreference.com/w/cpp/container/map/clear): clears the contents (public member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/container/map/erase (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.