map

http://www.cplusplus.com/reference/stl/map/

<map>

Map

Maps are a kind of associative container that stores elements formed by the combination of akey value and a mapped value.

In a map, the key value is generally used to uniquely identify the element, while themapped value is some sort of value associated to this key. Types ofkey and mapped value may differ. For example, a typical example of a map is a telephone guide where the name is thekey and the telephone number is the mapped value.

Internally, the elements in the map are sorted from lower to higher key value following a specific strict weak ordering criterion set on construction.

As associative containers, they are especially designed to be efficient accessing its elements by theirkey (unlike sequence containers, which are more efficient accessing elements by their relative or absolute position).

Therefore, the main characteristics of a map as an associative container are:

• Unique key values: no two elements in the map have keys that compare equal to each other. For a similar associative container allowing for multiple elements with equivalent keys, seemultimap.
• Each element is composed of a key and a mapped value. For a simpler associative container where the element value itself is its key, seeset.
• Elements follow a strict weak ordering at all times. Unordered associative arrays, likeunordered_map, are available in implementations following TR1.

Maps are also unique among associative containers in that they implement the direct access operator (operator[]) which allows for direct access of the mapped value.

In their implementation in the C++ Standard Template Library, map containers take four template parameters:

12

template < class Key, class T, class Compare = less<Key>,           class Allocator = allocator<pair<const Key,T> > > class map;

Where the template parameters have the following meanings:

• Key: Type of the key values. Each element in a map is uniquely identified by its key value.
• T: Type of the mapped value. Each element in a map is used to store some data as its mapped value.
• Compare: Comparison class: A class that takes two arguments of thekey type and returns a bool. The expression comp(a,b), wherecomp is an object of this comparison class and a and b are key values, shall returntrue if a is to be placed at an earlier position than b in a strict weak ordering operation. This can either be a class implementing afunction call operator or a pointer to a function (see constructor for an example). This defaults to less<Key>, which returns the same as applying theless-than operator (a<b).
  The map object uses this expression to determine the position of the elements in the container. All elements in amap container are ordered following this rule at all times.
• Allocator: Type of the allocator object used to define the storage allocation model. By default, theallocator class template is used, which defines the simplest memory allocation model and is value-independent.

In the reference for the map member functions, these same names (Key,T, Compare and Allocator) are assumed for the template parameters.

This container class supports bidirectional iterators.
Iterators to elements of map containers access to both the key and themapped value. For this, the class defines what is called its value_type, which is apair class with its first value corresponding to theconst version of the key type (template parameter Key) and itssecond value corresponding to the mapped value (template parameterT):

typedef pair<const Key, T> value_type;

Iterators of a map container point to elements of this value_type. Thus, for an iterator calledit that points to an element of a map, its key and mapped value can be accessed respectively with:

1234

map<Key,T>::iterator it;(*it).first;             // the key value (of type Key)(*it).second;            // the mapped value (of type T)(*it);                   // the "element value" (of type pair<const Key,T>) 

Naturally, any other direct access operator, such as -> or [] can be used, for example:

12

it->first;               // same as (*it).first   (the key value)it->second;              // same as (*it).second  (the mapped value) 

Member functions

(constructor)

Construct map (public member function)

(destructor)

Map destructor (public member function)

operator=

Copy container content (public member function)

Iterators:

begin

Return iterator to beginning (public member function)

end

Return iterator to end (public member function)

rbegin

Return reverse iterator to reverse beginning (public member function)

rend

Return reverse iterator to reverse end (public member function)

Capacity:

empty

Test whether container is empty (public member function)

size

Return container size (public member function)

max_size

Return maximum size (public member function)

Element access:

operator[]

Access element (public member function )

Modifiers:

insert

Insert elements (public member function )

erase

Erase elements (public member function)

swap

Swap content (public member function)

clear

Clear content (public member function)

Observers:

key_comp

Return key comparison object (public member function)

value_comp

Return value comparison object (public member function)

Operations:

find

Get iterator to element (public member function )

count

Count elements with a specific key (public member function)

lower_bound

Return iterator to lower bound (public member function)

upper_bound

Return iterator to upper bound (public member function)

equal_range

Get range of equal elements (public member function)

Allocator:

get_allocator

Get allocator (public member function )

Member types

of template <class Key, class T, class Compare=less<Key>, class Allocator=allocator<pair <const Key, T> > > class map;
member typedefinitionkey_typeKeymapped_typeTvalue_typepair<const Key,T>key_compareComparevalue_compareNested class to compare elements (see member function value_comp)allocator_typeAllocatorreferenceAllocator::referenceconst_referenceAllocator::const_referenceiteratorBidirectional iteratorconst_iteratorConstant bidirectional iteratorsize_typeUnsigned integral type (usually same as size_t)difference_typeSigned integral type (usually same as ptrdiff_t)pointerAllocator::pointerconst_pointerAllocator::const_pointerreverse_iteratorreverse_iterator<iterator>const_reverse_iteratorreverse_iterator<const_iterator>