A multimap is an associative container that manages a set of ordered key/value pairs. More than one value can be associated with a particular key. The pairs are ordered by key, based on a user-supplied comparator function.

The underlying data structure in a multimap efficiently finds all the values associated with a particular key, ensuring that items implement the operations required by the comparator. For example, the less function object requires an operator< to compare items.

A hash_multimap is similar to a multimap , except a hash_multimap uses a hashing mechanism to store and retrieve items. The interface of hash_multimap is nearly identical to that of multimap. Hash containers are only a proposed addition to the ANSI/ISO Standard Template Library, and have not been accepted for inclusion in the final specification. Hash containers are included in Standards<ToolKit> to provide the latest STL technology available.

Iterator Type

A multimap has bidirectional iterators. A hash_multimap has forward iterators.

I mplementation

A multimap is implemented using a red-black binary search tree with nodes holding the

pair<
const Key, Value >

objects. The comparator object is used to order the pairs based only on their keys.

Some compilers do not compile const templates correctly; in these cases, a multimap tree holds pair< Key, Value > objects.

A hash_multimap is implemented as a hash table. A user-specified hash function positions and retrieves item nodes. Like multimap , each node holds a pair< const Key, Value > object.

I nsertion Notes

When inserting a single item, the copy constructor is called once. When inserting multiple items, the copy constructor is called once for each item inserted. Insertion does not affect iterators or references to elements.

Erasure Notes

When erasing a single item, the destructor is called once. When erasing a range of items, the destructor is called once for each item in the range. Erasure only invalidates the iterators and references to the erased elements.

Common Uses

Both multimap and hash_multimap are useful for implementing a collection of one-to-many mappings.

Interface

Following is a list of the most basic multimap operations that insert, find, count, and erase key/value pairs. To avoid redundancy, the interface for hash_multimap is not repeated.

The following example uses a multimap to associate two different values with the letter `X'. The find() method is used to locate the first pair with a key equal to `X' and then all pair objects are displayed from that point to the end.

Example <ospace/osstd/examples/mmap1.cpp>


  #include <iostream>
#include <functional>
#include <map>
#include <utility>

void
main()
  {
  multimap< char, int, less< char > >::iterator i;
  multimap< char, int, less< char > > m;
  cout << "count( `X' ) = " << m.count( `X' ) << "\n";

  m.insert( pair< const char, int >( `X', 10 ) ); // Standard way.
  cout << "count( `X' ) = " << m.count( `X' ) << "\n";

  m.insert( `X', 20 ); // Non-standard, but very convenient!
  cout << "count( `X' ) = " << m.count( `X' ) << "\n";

  m.insert( `Y', 32 );
  i = m.find( `X' );
  while ( i != m.end() ) // Loop until end is reached.
    {
    cout << ( *i ).first << " -> " << ( *i ).second << "\n";
    ++i;
    }

  int count = m.erase( `X' );
  cout << "Erased " << count << " items\n";
  }

count( `X' ) = 0
count( `X' ) = 1
count( `X' ) = 2
X -> 10
X -> 20
Y -> 32
Erased 2 items.

Below is the same example using a hash_multimap instead of a multimap .

Example <ospace/osstd/examples/hmmap1.cpp>


  #include <iostream>
#include <functional>
#include <utility>
#include <ospace/osstd/hashmap.h>

typedef hash_multimap< char, int, hash< char >, equal_to< char > >

void
main()
  {
  hash_multimap< char, int, hash<char>, equal_to<char> >::iterator i;
  hash_multimap< char, int, hash<char>, equal_to<char> > m;
  cout << "count( 'X' ) = " << m.count( 'X' ) << "\n";

  m.insert( pair< char, int >( char, int )( 'X', 10 ) ); // Standard way.
  cout << "count( 'X' ) = " << m.count( 'X' ) << "\n";

  m.insert( pair< char, int >( char, int )( 'X', 20 ) ); // Standard way.
  cout << "count( 'X' ) = " << m.count( 'X' ) << "\n";

  m.insert( pair< char, int >( char, int )( 'Y', 32 ) ); // Standard way.
  i = m.find( 'X' ); // Find first match.
  while ( i != m.end() ) // Loop until end is reached.
    {
    cout << ( *i ).first << " -> " << ( *i ).second << "\n";
    ++i;
    }

  int count = m.erase( 'X' );
  cout << "Erased " << count << " items\n";
  }

count( `X' ) = 0
count( `X' ) = 1
count( `X' ) = 2
X -> 10
X -> 20
Y -> 32
Erased 2 items.

Like all STL collections, a multimap defines a constructor. Therefore a constructor can be initialized with a sequence of values.

Constructor

multimap( const_iterator first , const_iterator last )

Constructs a multimap containing copies of the key/value pairs in the range between first and last , including first but not last , using the compare function specified when the multimap template was instantiated.

Similarly, a multimap supports the bounds operators common to all STL associative containers.

lower_bound

iterator
    lower_bound( const Key&

key )

Returns an iterator positioned at the first location where a pair with key could be inserted without violating the ordering criteria. If no such location is found, returns an iterator positioned at end() .

upper_bound

iterator
    upper_bound( const Key&

key )

Returns an iterator positioned at the last location where a pair with key could be inserted without violating the ordering criteria. If no such location is found, returns an iterator positioned at end() .

equal_range

pair<
    iterator, iterator > equal_range( const Key&

key )

Returns a pair of iterators whose first element is equal to
lower_bound( key ) and whose second element is equal to upper_bound( key ) .

The following example illustrates the features just described, and has an analogous version in the section describing multiset .

Example <ospace/osstd/examples/mmap2.cpp>


  #include <iostream>
#include <functional>
#include <map>
#include <utility>

typedef multimap< int, char, less< int > >  maptype;
typedef pair< int, char > pair_type;

pair_type p1( 3, `c' );
pair_type p2( 6, `f' );
pair_type p3( 1, `a' );
pair_type p4( 2, `b' );
pair_type p5( 3, `x' );
pair_type p6( 6, `f' );
pair_type array[] = { p1, p2, p3, p4, p5, p6 };

void
main()
  {
  maptype m( array + 0, array + 6 );
  maptype::iterator i;

  // Return location of first element that is not less than 3
  i = m.lower_bound( 3 );
  cout << "lower bound:\n";
  cout << ( *i ).first << " -> " << ( *i ).second << "\n";

  // Return location of first element that is greater than 3
  i = m.upper_bound( 3 );
  cout << "upper bound:\n";
  cout << ( *i ).first << " -> " << ( *i ).second << "\n";
  }

lower bound:
3 -> c
upper bound:
6 -> f

In a manner similar to set , multimap specifies an instance of comparator object during construction.

Constructor

multimap(
    const Compare&

compare )

Constructs an empty multimap that orders its keys using the compare function compare .

Constructor

multimap(
    const_iterator

first

,
    const_iterator

last

,
    const Compare&

compare )

Constructs a multimap that contain copies of the key/value pairs in the range between first and last , including first but not last, using compare to order the keys.

Likewise, the following functions obtain copies of the comparator object for a multimap .

key_comp

key_compare
    key_comp() const

Returns the comparison object used for comparing the keys.

value_comp

value_compare
    value_comp() const

Returns the comparison object used for comparing the key/value pairs.

multimap , hash_multimap

Iterator Type

I mplementation

I nsertion Notes

Erasure Notes

Common Uses

Interface

Example <ospace/osstd/examples/mmap1.cpp>

Example <ospace/osstd/examples/hmmap1.cpp>

Example <ospace/osstd/examples/mmap2.cpp>