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 iterator
s 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.
multimap
.Constructs a new multimap
. This is the default constructor.
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>
.
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.
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.
Returns the number of keys in the multimap
that match the specified key.
multimap
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
.
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.
Removes all elements from the multimap
.
Returns the number of elements stored in the multimap
.
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 iterator
s act as pointers to pair<const KeyType, ValueType>
.
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.
multimap
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>
.
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.
Returns an iterator to the first key/value pair whose key compares strictly greater than the parameter.
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.
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
.
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.
Returns a reverse_iterator
to the last element of the multimap
. reverse_iterator
s are like regular iterators except that they traverse in the opposite direction. Check for the end-of-container condition of reverse_iterator
s with 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.
multimaps
sExchanges the contents of this multimap
and another multimap
.