# std::multimap< _Key, _Tp, _Compare, _Alloc > Class Template Reference

A standard container made up of pairs (see std::pair in <utility>) which can be retrieved based on a key. More...

`#include <stl_multimap.h>`

List of all members.

## Public Methods

iterator | begin ()
const_iterator | begin () const
iterator | end ()
const_iterator | end () const
reverse_iterator | rbegin ()
const_reverse_iterator | rbegin () const
reverse_iterator | rend ()
const_reverse_iterator | rend () const
bool | empty () const
size_type | size () const
size_type | max_size () const
iterator | insert (const value_type &__x)
| Inserts a std::pair into the multimap. More...
iterator | insert (iterator __position, const value_type &__x)
| Inserts a std::pair into the multimap. More...
template<class _InputIterator> void | insert (_InputIterator __first, _InputIterator __last)
| A template function that attemps to insert elements from another range (possibly another multimap or standard container). More...
void | erase (iterator __position)
| Erases an element from a multimap. More...
size_type | erase (const key_type &__x)
| Erases an element according to the provided key. More...
void | erase (iterator __first, iterator __last)
| Erases a [first,last) range of elements from a multimap. More...
void | clear ()
iterator | find (const key_type &__x)
| Tries to locate an element in a multimap. More...
const_iterator | find (const key_type &__x) const
| Tries to locate an element in a multimap. More...
size_type | count (const key_type &__x) const
| Finds the number of elements with given key. More...
iterator | lower_bound (const key_type &__x)
| Finds the beginning of a subsequence matching given key. More...
const_iterator | lower_bound (const key_type &__x) const
| Finds the beginning of a subsequence matching given key. More...
iterator | upper_bound (const key_type &__x)
| Finds the end of a subsequence matching given key. More...
const_iterator | upper_bound (const key_type &__x) const
| Finds the end of a subsequence matching given key. More...
pair< iterator, iterator > | equal_range (const key_type &__x)
| Finds a subsequence matching given key. More...
pair< const_iterator, const_iterator > | equal_range (const key_type &__x) const
| Finds a subsequence matching given key. More...

## Detailed Description

### template<class _Key, class _Tp, class _Compare, class _Alloc>
class std::multimap< _Key, _Tp, _Compare, _Alloc >

A standard container made up of pairs (see std::pair in <utility>) which can be retrieved based on a key.

This is an associative container. Values contained within it can be quickly retrieved through a key element. In contrast with a map a multimap can have multiple duplicate keys.

Definition at line 91 of file stl_multimap.h.

## Member Function Documentation

template<class _Key, class _Tp, class _Compare, class _Alloc>
const_iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::begin | ( |  | ) | const`[inline]`

| Returns a read-only (constant) iterator that points to the first pair in the multimap. Iteration is done in ascending order according to the keys. Definition at line 177 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::begin | ( |  | ) | `[inline]`

| Returns a read/write iterator that points to the first pair in the multimap. Iteration is done in ascending order according to the keys. Definition at line 170 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
void std::multimap< _Key, _Tp, _Compare, _Alloc >::clear | ( |  | ) | `[inline]`

| Erases all elements in a multimap. Note that this function only erases the elements, and that if the elements themselves are pointers, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibilty. Definition at line 317 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
size_type std::multimap< _Key, _Tp, _Compare, _Alloc >::count | ( | const key_type & | __x | ) | const`[inline]`

Finds the number of elements with given key.

Parameters:

  x | Key of (key, value) pairs to be located.

Returns:
  Number of elements with specified key.

Definition at line 352 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
bool std::multimap< _Key, _Tp, _Compare, _Alloc >::empty | ( |  | ) | const`[inline]`

| Returns true if the map is empty. (Thus begin() would equal end().) Definition at line 221 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
const_iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::end | ( |  | ) | const`[inline]`

| Returns a read-only (constant) iterator that points one past the last pair in the multimap. Iteration is done in ascending order according to the keys. Definition at line 190 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::end | ( |  | ) | `[inline]`

| Returns a read/write iterator that points one past the last pair in the multimap. Iteration is done in ascending order according to the keys. Definition at line 183 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
pair<const_iterator,const_iterator> std::multimap< _Key, _Tp, _Compare, _Alloc >::equal_range | ( | const key_type & | __x | ) | const`[inline]`

Finds a subsequence matching given key.

Parameters:

  x | Key of (key, value) pairs to be located.

Returns:
  Pair of read-only (constant) iterators that possibly points to the subsequence matching given key.

This function improves on lower_bound() and upper_bound() by giving a more elegant and efficient solution. It returns a pair of which the first element possibly points to the first element matching the given key and the second element possibly points to the last element matching the given key. If unsuccessful the first element of the returned pair will contain an iterator pointing to the next greatest element or, if no such a greater element exists, to end().

Definition at line 431 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
pair<iterator,iterator> std::multimap< _Key, _Tp, _Compare, _Alloc >::equal_range | ( | const key_type & | __x | ) | `[inline]`

Finds a subsequence matching given key.

Parameters:

  x | Key of (key, value) pairs to be located.

Returns:
  Pair of iterators that possibly points to the subsequence matching given key.

This function improves on lower_bound() and upper_bound() by giving a more elegant and efficient solution. It returns a pair of which the first element possibly points to the first element matching the given key and the second element possibly points to the last element matching the given key. If unsuccessful the first element of the returned pair will contain an iterator pointing to the next greatest element or, if no such greater element exists, to end().

Definition at line 413 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
void std::multimap< _Key, _Tp, _Compare, _Alloc >::erase | ( | iterator | __first,
|  | iterator | __last
| ) | `[inline]`

Erases a [first,last) range of elements from a multimap.

Parameters:

  first | Iterator pointing to the start of the range to be erased.
  last | Iterator pointing to the end of the range to be erased.

This function erases a sequence of elements from a multimap. Note that this function only erases the elements, and that if the elements themselves are pointers, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibilty.

Definition at line 309 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
size_type std::multimap< _Key, _Tp, _Compare, _Alloc >::erase | ( | const key_type & | __x | ) | `[inline]`

Erases an element according to the provided key.

Parameters:

  x | Key of element to be erased.

Returns:
  Doc me! (Number of elements erased?)

This function erases all elements, located by the given key, from a multimap. Note that this function only erases the element, and that if the element is itself a pointer, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibilty.

Definition at line 297 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
void std::multimap< _Key, _Tp, _Compare, _Alloc >::erase | ( | iterator | __position | ) | `[inline]`

Erases an element from a multimap.

Parameters:

  position | An iterator pointing to the element to be erased.

This function erases an element, pointed to by the given iterator, from a mutlimap. Note that this function only erases the element, and that if the element is itself a pointer, the pointed-to memory is not touched in any way. Managing the pointer is the user's responsibilty.

Definition at line 284 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
const_iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::find | ( | const key_type & | __x | ) | const`[inline]`

Tries to locate an element in a multimap.

Parameters:

  x | Key of (key, value) pair to be located.

Returns:
  Read-only (constant) iterator pointing to sought-after (first matching?) element, or end() if not found.

This function takes a key and tries to locate the element with which the key matches. If successful the function returns a constant iterator pointing to the sought after pair. If unsuccessful it returns the one past the end ( end() ) iterator.

Definition at line 345 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::find | ( | const key_type & | __x | ) | `[inline]`

Tries to locate an element in a multimap.

Parameters:

  x | Key of (key, value) pair to be located.

Returns:
  Iterator pointing to sought-after (first matching?) element, or end() if not found.

This function takes a key and tries to locate the element with which the key matches. If successful the function returns an iterator pointing to the sought after pair. If unsuccessful it returns the one past the end ( end() ) iterator.

Definition at line 332 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
template<class _InputIterator>
void std::multimap< _Key, _Tp, _Compare, _Alloc >::insert | ( | _InputIterator | __first,
|  | _InputIterator | __last
| ) | `[inline]`

A template function that attemps to insert elements from another range (possibly another multimap or standard container).

Parameters:

  first | Iterator pointing to the start of the range to be inserted.
  last | Iterator pointing to the end of the range to be inserted.

Definition at line 271 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::insert | ( | iterator | __position,
|  | const value_type & | __x
| ) | `[inline]`

Inserts a std::pair into the multimap.

Parameters:

  position | An iterator that serves as a hint as to where the pair should be inserted.
  x | Pair to be inserted (see std::make_pair for easy creation of pairs).

Returns:
  An iterator that points to the inserted (key,value) pair.

This function inserts a (key, value) pair into the multimap. Contrary to a std::map the multimap does not rely on unique keys and thus a multiple pairs with the same key can be inserted. Note that the first parameter is only a hint and can potentially improve the performance of the insertion process. A bad hint would cause no gains in efficiency.

Definition at line 259 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::insert | ( | const value_type & | __x | ) | `[inline]`

Inserts a std::pair into the multimap.

Parameters:

  x | Pair to be inserted (see std::make_pair for easy creation of pairs).

Returns:
  An iterator that points to the inserted (key,value) pair.

This function inserts a (key, value) pair into the multimap. Contrary to a std::map the multimap does not rely on unique keys and thus a multiple pairs with the same key can be inserted.

Definition at line 242 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
const_iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::lower_bound | ( | const key_type & | __x | ) | const`[inline]`

Finds the beginning of a subsequence matching given key.

Parameters:

  x | Key of (key, value) pair to be located.

Returns:
  Read-only (constant) iterator pointing to first element matching given key, or end() if not found.

This function returns the first element of a subsequence of elements that matches the given key. If unsuccessful the iterator will point to the next greatest element or, if no such greater element exists, to end().

Definition at line 378 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::lower_bound | ( | const key_type & | __x | ) | `[inline]`

Finds the beginning of a subsequence matching given key.

Parameters:

  x | Key of (key, value) pair to be located.

Returns:
  Iterator pointing to first element matching given key, or end() if not found.

This function returns the first element of a subsequence of elements that matches the given key. If unsuccessful it returns an iterator pointing to the first element that has a greater value than given key or end() if no such element exists.

Definition at line 365 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
size_type std::multimap< _Key, _Tp, _Compare, _Alloc >::max_size | ( |  | ) | const`[inline]`

| Returns the maximum size of the map. Definition at line 227 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
const_reverse_iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::rbegin | ( |  | ) | const`[inline]`

| Returns a read-only (constant) reverse iterator that points to the last pair in the multimap. Iteration is done in descending order according to the keys. Definition at line 204 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
reverse_iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::rbegin | ( |  | ) | `[inline]`

| Returns a read/write reverse iterator that points to the last pair in the multimap. Iteration is done in descending order according to the keys. Definition at line 197 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
const_reverse_iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::rend | ( |  | ) | const`[inline]`

| Returns a read-only (constant) reverse iterator that points to one before the first pair in the multimap. Iteration is done in descending order according to the keys. Definition at line 218 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
reverse_iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::rend | ( |  | ) | `[inline]`

| Returns a read/write reverse iterator that points to one before the first pair in the multimap. Iteration is done in descending order according to the keys. Definition at line 211 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
size_type std::multimap< _Key, _Tp, _Compare, _Alloc >::size | ( |  | ) | const`[inline]`

| Returns the size of the map. Definition at line 224 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
const_iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::upper_bound | ( | const key_type & | __x | ) | const`[inline]`

Finds the end of a subsequence matching given key.

Parameters:

  x | Key of (key, value) pair to be located.

Returns:
  Read-only (constant) iterator pointing to last element matching given key.

Definition at line 395 of file stl_multimap.h.

template<class _Key, class _Tp, class _Compare, class _Alloc>
iterator std::multimap< _Key, _Tp, _Compare, _Alloc >::upper_bound | ( | const key_type & | __x | ) | `[inline]`

Finds the end of a subsequence matching given key.

Parameters:

  x | Key of (key, value) pair to be located.

Returns:
  Iterator pointing to last element matching given key.

Definition at line 387 of file stl_multimap.h.

The documentation for this class was generated from the following file:

- stl_multimap.h