# std::map< _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_map.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
_Tp & | operator[] (const key_type &__k)
| Subscript ( [] ) access to map data. More...
pair< iterator, bool > | insert (const value_type &__x)
| Attempts to insert a std::pair into the map. More...
iterator | insert (iterator position, const value_type &__x)
| Attempts to insert a std::pair into the map. More...
template<class _InputIterator> void | insert (_InputIterator __first, _InputIterator __last)
| A template function that attemps to insert elements from another range (possibly another map). More...
void | erase (iterator __position)
| Erases an element from a map. 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 map. More...
void | clear ()
iterator | find (const key_type &__x)
| Tries to locate an element in a map. More...
const_iterator | find (const key_type &__x) const
| Tries to locate an element in a map. 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 = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
class std::map< _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. Example: MyMap["First"] would return the data associated with the key "First".

Definition at line 79 of file stl_map.h.

## Member Function Documentation

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
const_iterator std::map< _Key, _Tp, _Compare, _Alloc >::begin | ( |  | ) | const`[inline]`

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

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
iterator std::map< _Key, _Tp, _Compare, _Alloc >::begin | ( |  | ) | `[inline]`

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

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
void std::map< _Key, _Tp, _Compare, _Alloc >::clear | ( |  | ) | `[inline]`

| Erases all elements in a map. 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_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
size_type std::map< _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.

This function only makes sense for multimaps.

Definition at line 354 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
bool std::map< _Key, _Tp, _Compare, _Alloc >::empty | ( |  | ) | const`[inline]`

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

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
const_iterator std::map< _Key, _Tp, _Compare, _Alloc >::end | ( |  | ) | const`[inline]`

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

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
iterator std::map< _Key, _Tp, _Compare, _Alloc >::end | ( |  | ) | `[inline]`

| Returns a read/write iterator that points one past the last pair in the map. Iteration is done in ascending order according to the keys. Definition at line 169 of file stl_map.h. Referenced by std::map< _Key, _Tp, _Compare, _Alloc >::operator[]().

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
pair<const_iterator,const_iterator> std::map< _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().

This function only makes sense for multimaps.

Definition at line 443 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
pair<iterator,iterator> std::map< _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().

This function only makes sense for multimaps.

Definition at line 423 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
void std::map< _Key, _Tp, _Compare, _Alloc >::erase | ( | iterator | __first,
|  | iterator | __last
| ) | `[inline]`

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

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 map. 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 309 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
size_type std::map< _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 that match key? Only makes sense with multimap)

This function erases an element, located by the given key, from a map. 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_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
void std::map< _Key, _Tp, _Compare, _Alloc >::erase | ( | iterator | __position | ) | `[inline]`

Erases an element from a map.

Parameters:

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

This function erases an element, pointed to by the given iterator, from a map. 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_map.h.

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

Tries to locate an element in a map.

Parameters:

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

Returns:
  Read-only (constant) iterator pointing to sought-after 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_map.h.

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

Tries to locate an element in a map.

Parameters:

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

Returns:
  Iterator pointing to sought-after 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_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
template<class _InputIterator>
void std::map< _Key, _Tp, _Compare, _Alloc >::insert | ( | _InputIterator | __first,
|  | _InputIterator | __last
| ) | `[inline]`

A template function that attemps to insert elements from another range (possibly another map).

Parameters:

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

Definition at line 271 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
iterator std::map< _Key, _Tp, _Compare, _Alloc >::insert | ( | iterator | position,
|  | const value_type & | __x
| ) | `[inline]`

Attempts to insert a std::pair into the map.

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 is not concerned about whether the insertion took place or not and thus does not return a boolean like the single-argument insert() does. 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 261 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
pair<iterator,bool> std::map< _Key, _Tp, _Compare, _Alloc >::insert | ( | const value_type & | __x | ) | `[inline]`

Attempts to insert a std::pair into the map.

Parameters:

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

Returns:
  A pair of which the first element is an iterator that points to the possibly inserted pair, a second element of type bool to show if the pair was actually inserted.

This function attempts to insert a (key, value) pair into the map. A map relies on unique keys and thus a pair is only inserted if its first element (the key) is not already present in the map.

Definition at line 244 of file stl_map.h.

Referenced by std::map< _Key, _Tp, _Compare, _Alloc >::operator[]().

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
const_iterator std::map< _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 is useful only with std::multimap. It 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 382 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
iterator std::map< _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 is useful only with std::multimap. It 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 369 of file stl_map.h.

Referenced by std::map< _Key, _Tp, _Compare, _Alloc >::operator[]().

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
size_type std::map< _Key, _Tp, _Compare, _Alloc >::max_size | ( |  | ) | const`[inline]`

| Returns the maximum size of the map. Definition at line 210 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
_Tp& std::map< _Key, _Tp, _Compare, _Alloc >::operator[] | ( | const key_type & | __k | ) | `[inline]`

Subscript ( [] ) access to map data.

Parameters:

  k | The key for which data should be retrieved.

Allows for easy lookup with the subscript ( [] ) operator. Returns the data associated with the key specified in subscript. If the key does not exist a pair with that key is created with a default value, which is then returned.

Definition at line 221 of file stl_map.h.

References std::map< _Key, _Tp, _Compare, _Alloc >::end(), std::map< _Key, _Tp, _Compare, _Alloc >::insert(), and std::map< _Key, _Tp, _Compare, _Alloc >::lower_bound().

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
const_reverse_iterator std::map< _Key, _Tp, _Compare, _Alloc >::rbegin | ( |  | ) | const`[inline]`

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

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
reverse_iterator std::map< _Key, _Tp, _Compare, _Alloc >::rbegin | ( |  | ) | `[inline]`

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

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
const_reverse_iterator std::map< _Key, _Tp, _Compare, _Alloc >::rend | ( |  | ) | const`[inline]`

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

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
reverse_iterator std::map< _Key, _Tp, _Compare, _Alloc >::rend | ( |  | ) | `[inline]`

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

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
size_type std::map< _Key, _Tp, _Compare, _Alloc >::size | ( |  | ) | const`[inline]`

| Returns the size of the map. Definition at line 208 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
const_iterator std::map< _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.

This function only makes sense with multimaps.

Definition at line 403 of file stl_map.h.

template<class _Key, class _Tp, class _Compare = less<_Key>, class _Alloc = allocator<pair<const _Key, _Tp> >>
iterator std::map< _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.

This function only makes sense with multimaps.

Definition at line 393 of file stl_map.h.

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

- stl_map.h