multimap<KeyType, ValueType>

Like the map, the STL multimap represents a collection of key/value pairs. However, unlike map, the keys in a multimap need not be unique.

Like the map, multimap iterators act as pointers to objects of type pair<const KeyType, ValueType>, meaning that when iterating over a multimap, access the first field to get the key and the second field to get the value.

By default, the multimap uses operator < to order the keys behind the scenes. To use an alternative comparison function, parametrize the multimap as multimap<KeyType, ValueType, CompareFunctorType>.

Note that, unlike the map, multimap does not support the brackets operator ([]) for element access, since there might be several different keys with the same value.

Common multimap<KeyType, ValueType> Member Functions

Constructor: multimap<KeyType, ValueType> ()

Constructs a new empty multimap.

multimap<string, int> myMultimap; // Constructs a new, empty multimap.

Constructs a new multimap. This is the default constructor.

pair<iterator, bool> insert(const pair<const KeyType, ValueType> &elem)

void insert(InputIterator start, InputIterator stop)

Insert key/value pairs

myMultimap.insert(make_pair(string("C++ is awesome!", true))); // Insert key "C++ is awesome!" with value true

myMultimap.insert(myOtherContainer.begin(), myOtherContainer.end()); // Insert key-value pairs from another iterator range.

Inserts new elements into the multimap. insert is perhaps the most complicated STL function you will routinely encounter in practice. The first version of insert inserts a new key/value pair into the multimap, accepting a pair<const KeyType, ValueType> as a parameter. You can create this pair explicitly, or can use the utility function make_pair instead. insert returns a pair<iterator, bool>, where the first field of the pair is an iterator to the element and the second field is a bool that is always true.

The second version of this function inserts a range of elements into the multimap. The elements in the range [start, stop) must be of type pair<KeyType, ValueType>.

iterator find(const KeyType &key)

const_iterator find(const KeyType &key) const

Return iterator to element

if(myMultimap.find("C++ is awesome!") == myMultimap.end()) // "C++ is awesome!" is not a key

Returns an iterator to the first key/value pair with the specified key, if it exists, and the result of the multimap's end function otherwise. Since this might not be the only key/value pair in the multimap with the specified key, you might want to consider using equal_range instead.

pair<iterator, iterator> equal_range(const KeyType &key)

pair<const_iterator, const_iterator> equal_range(const KeyType &key) const

Get all elements with specified key

pair<multimap<string, int>::iterator, multimap<string, int>::iterator> equal = myMultimap.equal_range("C++!");

Returns a pair of iterators representing the range of elements in the multimap with the specified key. This function is ideal for iterating over all elements with the same key in a for loop.

size_type count(const KeyType &key) const

Count number of matches

int numCopies = myMultimap.count("C++"); // Returns number of key/value pairs with key "C++"

Returns the number of keys in the multimap that match the specified key.

size_type erase(const KeyType &key)

void erase(iterator elem)

void erase(iterator start, iterator stop)

Remove elements from the multimap

myMultimap.erase("C++ is not awesome!"); // Remove ALL entries with key "C++ is not awesome!"

myMultimap.erase(myItr); // Erase the element pointed at by myItr

myMultimap.erase(myMultimap.begin(), myMultimap.end()); // Remove all elements from the container

Removes elements from the multimap. The first version removes all elements with the specified key from the multimap, returning the number of elements that were erased. The second version removes from the multimap the element pointed at by the specified iterator. The third version removes all elements in the range [start, stop) from the multimap.

bool empty() const

Is container empty?

if(myMultimap.empty()) { ... }

Returns whether the multimap is empty. It's considered good practice to call empty to determine whether the multimap is empty rather than checking whether size() returns zero.

void clear()

Empty container

myMultimap.clear();

Removes all elements from the multimap.

size_type size() const

Get container size

int numElems = myMultimap.size();

Returns the number of elements stored in the multimap.

iterator begin()

const_iterator begin() const

Get start iterator.

for(multimap<string, int>::iterator itr = myMultimap.begin(); /* ... */)

Returns an iterator to the first element in the multimap. Elements in a multimap are stored in sorted order by key, so the elements returned by iterating over the multimap will be sorted. Remember that multimap iterators act as pointers to pair<const KeyType, ValueType>.

iterator end()

const_iterator end() const

Get stop iterator.

for(/* ... */ itr != myMultimap.end(); /* ... */)

Returns an iterator to the element one past the end of the multimap. This iterator does not point to a valid element, so do not dereference it.

Other multimap<KeyType, ValueType> Member Functions

Constructor: multimap<KeyType, ValueType> (InputIterator begin, InputIterator end)

Constructs a pre-initialized multimap

multimap<string, int> myMultimap(otherContainer.begin(), otherContainer.end()); // Copy elements from the range otherContainer.begin(), otherContainer.end() into this multimap

Constructs a new multimap whose elements are equal to the elements defined in the range [begin, end). These iterators need not come from another multimap, but they must be of the form pair<KeyType, ValueType>.

iterator lower_bound(const KeyType &key)

const_iterator lower_bound(const KeyType &key) const

Get first element with specified key.

for(multimap<string, int>::iterator itr = myMultimap.lower_bound("b"); /* ... */)

Returns an iterator to the first key/value pair whose key compares greater than or equal to the parameter. For example, lower_bound(14) would return an iterator to the first element of a multimap<int, string> whose key was strictly greater than or equal to 14.

iterator upper_bound(const KeyType &key)

const_iterator upper_bound(const KeyType &key) const

Get first element strictly greater than

multimap<string, int>::iterator itr = myMultimap.upper_bound("b"); // Get iterator to one past the last element less than or equal to "b"

Returns an iterator to the first key/value pair whose key compares strictly greater than the parameter.

size_type max_size() const

Get maximum container size

multimap<string, int>::size_type maxElems = myMultimap.max_size()

Returns the maximum number of elements the multimap can hold, which is usually the number of unique memory addresses divided by the size of the elements stored in the container.

BinaryFunction key_comp() const

Get key comparison function

if(myMultimap.keyComp()(myKey1, myKey2)) // Key myKey1 compares less than myKey2

Returns the multimap's internal comparison function used to compare two keys. You can use this function to compare two keys in the same way as the multimap.

BinaryFunction value_comp() const

Get key/value pair comparison function

if(myMultimap.keyComp()(*itr1, *itr2)) // Element referenced by first iterator comes before element referenced by second iterator

Returns the multimap's internal comparison function used to compare two key/value pairs. That is, given two pair<const KeyType, ValueType>s, you can use value_comp to determine which one precedes the other in the multimap's internal ordering. Note that, despite the name, this function does not compare two values.

reverse_iterator begin()

const_reverse_iterator begin() const

Get start reverse iterator

for(multimap<string, int>::reverse_iterator itr = myMultimap.rbegin(); /* ... */)

Returns a reverse_iterator to the last element of the multimap. reverse_iterators are like regular iterators except that they traverse in the opposite direction. Check for the end-of-container condition of reverse_iterators with rend.

reverse_iterator end()

const_reverse_iterator end() const

Get stop reverse iterator.

for(/* ... */ itr != myMultimap.rend(); /* ... */)

Returns a reverse_iterator to the element one element before the start of the array. Like end, the iterator returned by rend does not actually reference a real element of the multimap and you should take care not to actually dereference it.

void swap(multimap<KeyType, ValueType> &other)

Exchange two multimapss

myMultimap.swap(myOtherMultimap); // Exchanges the two multimaps

Exchanges the contents of this multimap and another multimap.