#include <map>
  iterator begin();
  const_iterator begin() const;

   // Create a list of characters
   list<char> charList;
   for( int i=0; i < 10; i++ ) {
     charList.push_front( i + 65 );
   }
   // Display the list
   list<char>::iterator theIterator;
   for( theIterator = charList.begin(); theIterator != charList.end(); theIterator++ ) {
     cout << *theIterator;
   }            

  #include <map>
  void clear();

The function clear() deletes all of the elements in the multimap. clear() runs in linear time.

  #include <map>
  size_type count( const key_type& key );

The function count() returns the number of occurrences of key in the multimap.

count() should run in logarithmic time.

  #include <map>
  bool empty() const;

The empty() function returns true if the multimap has no elements, false otherwise.

For example, the following code uses empty() as the stopping condition on a (C/C++ Keywords) while loop to clear a multimap and display its contents in reverse order:

 vector<int> v;
 for( int i = 0; i < 5; i++ ) {
   v.push_back(i);
 }
 while( !v.empty() ) {
   cout << v.back() << endl;
   v.pop_back();
 }              

  #include <map>
  iterator end();
  const_iterator end() const;

The end() function returns an iterator just past the end of the multimap.

Note that before you can access the last element of the multimap using an iterator that you get from a call to end(), you'll have to decrement the iterator first.

For example, the following code uses begin() and end() to iterate through all of the members of a vector:

 vector<int> v1( 5, 789 );
 vector<int>::iterator it;
 for( it = v1.begin(); it != v1.end(); it++ ) {
   cout << *it << endl;
 }              

The iterator is initialized with a call to begin(). After the body of the loop has been executed, the iterator is incremented and tested to see if it is equal to the result of calling end(). Since end() returns an iterator pointing to an element just after the last element of the vector, the loop will only stop once all of the elements of the vector have been displayed.

end() runs in constant time.

  #include <map>
  pair<iterator, iterator> equal_range( const key_type& key );

The function equal_range() returns two iterators - one to the first element that contains key, another to a point just after the last element that contains key.

For example, here is a hypothetical input-configuration loader using multimaps, strings and equal_range():

  multimap<string,pair<int,int> > input_config;
  
  // read configuration from file "input.conf" to input_config
  readConfigFile( input_config, "input.conf" ); 
  
  pair<multimap<string,pair<int,int> >::iterator,multimap<string,pair<int,int> >::iterator> ii;
  multimap<string,pair<int,int> >::iterator i;
  
  ii = input_config.equal_range("key");         // keyboard key-bindings
  // we can iterate over a range just like with begin() and end()  
  for( i = ii.first; i != ii.second; ++i ) {
    // add a key binding with this key and output
    bindkey(i->second.first, i->second.second); 
  }

  ii = input_config.equal_range("joyb");        // joystick button key-bindings
  for( i = ii.first; i != ii.second; ++i ) {
    // add a key binding with this joystick button and output
    bindjoyb(i->second.first, i->second.second);
  }
  

  #include <map>
  void erase( iterator pos );
  void erase( iterator start, iterator end );
  size_type erase( const key_type& key );

The erase function() either erases the element at pos, erases the elements between start and end, or erases all elements that have the value of key.

  #include <map>
  iterator find( const key_type& key );

The find() function returns an iterator to key, or an iterator to the end of the multimap if key is not found.

find() runs in logarithmic time.

  #include <map>
  iterator insert( iterator pos, const TYPE& val );
  iterator insert( const TYPE& val );
  void insert( input_iterator start, input_iterator end );

The function insert() either:

• inserts val after the element at pos (where pos is really just a suggestion as to where val should go, since multimaps are ordered), and returns an iterator to that element.
• inserts val into the multimap, returning an iterator to the element inserted.
• inserts a range of elements from start to end.

For example, the following code uses the insert() function to add several <name,ID> pairs to a employee multimap:

  multimap<string,int> m;

  int employeeID = 0;
  m.insert( pair<string,int>("Bob Smith",employeeID++) );
  m.insert( pair<string,int>("Bob Thompson",employeeID++) );
  m.insert( pair<string,int>("Bob Smithey",employeeID++) );
  m.insert( pair<string,int>("Bob Smith",employeeID++) );

  cout << "Number of employees named 'Bob Smith': " << m.count("Bob Smith") << endl;
  cout << "Number of employees named 'Bob Thompson': " << m.count("Bob Thompson") << endl;
  cout << "Number of employees named 'Bob Smithey': " << m.count("Bob Smithey") << endl;

  cout << "Employee list: " << endl;
  for( multimap<string, int>::iterator iter = m.begin(); iter != m.end(); ++iter ) {
    cout << " Name: " << iter->first << ", ID #" << iter->second << endl;
  }

When run, the above code produces the following output:

  Number of employees named 'Bob Smith': 2
  Number of employees named 'Bob Thompson': 1
  Number of employees named 'Bob Smithey': 1
  Employee list:
   Name: Bob Smith, ID #0
   Name: Bob Smith, ID #3
   Name: Bob Smithey, ID #2
   Name: Bob Thompson, ID #1

  #include <map>
  key_compare key_comp() const;

The function key_comp() returns the function that compares keys.

key_comp() runs in constant time.

  #include <map>
  iterator lower_bound( const key_type& key );

The lower_bound() function returns an iterator to the first element which has a value greater than or equal to key.

lower_bound() runs in logarithmic time.

  #include <map>
  size_type max_size() const;

The max_size() function returns the maximum number of elements that the multimap can hold. The max_size() function should not be confused with the size() or (C++ Strings) capacity() functions, which return the number of elements currently in the multimap and the the number of elements that the multimap will be able to hold before more memory will have to be allocated, respectively.

  #include <map>
  multimap();
  multimap( const multimap& c );
  multimap( iterator begin, iterator end,
            const key_compare& cmp = Compare(), const allocator& alloc = Allocator() );
  ~multimap();

Multimaps have several constructors:

• The default constructor takes no arguments, creates a new instance of that multimap, and runs in constant time.
• The default copy constructor runs in linear time and can be used to create a new multimap that is a copy of the given multimap c.
• Multimaps can also be created from a range of elements defined by begin and end. When using this constructor, an optional comparison function cmp and allocator alloc can also be provided.

The default destructor is called when the multimap should be destroyed.

The template definition of multimaps requires that both a key type and value type be supplied. For example, you can instantiate a multimap that maps strings to integers with this statement:

  multimap<string,int> m;

You can also supply a comparison function and an allocator in the template:

  multimap<string,int,myComp,myAlloc> m;

For example, the following code uses a multimap to associate a series of employee names with numerical IDs:

  multimap<string,int> m;

  int employeeID = 0;
  m.insert( pair<string,int>("Bob Smith",employeeID++) );
  m.insert( pair<string,int>("Bob Thompson",employeeID++) );
  m.insert( pair<string,int>("Bob Smithey",employeeID++) );
  m.insert( pair<string,int>("Bob Smith",employeeID++) );

  cout << "Number of employees named 'Bob Smith': " << m.count("Bob Smith") << endl;
  cout << "Number of employees named 'Bob Thompson': " << m.count("Bob Thompson") << endl;
  cout << "Number of employees named 'Bob Smithey': " << m.count("Bob Smithey") << endl;

  cout << "Employee list: " << endl;
  for( multimap<string, int>::iterator iter = m.begin(); iter != m.end(); ++iter ) {
    cout << " Name: " << iter->first << ", ID #" << iter->second << endl;
  }

When run, the above code produces the following output. Note that the employee list is displayed in alphabetical order, because multimaps are sorted associative containers:

  Number of employees named 'Bob Smith': 2
  Number of employees named 'Bob Thompson': 1
  Number of employees named 'Bob Smithey': 1
  Employee list:
   Name: Bob Smith, ID #0
   Name: Bob Smith, ID #3
   Name: Bob Smithey, ID #2
   Name: Bob Thompson, ID #1

  #include <map>
  multimap operator=(const multimap& c2);
  bool operator==(const multimap& c1, const multimap& c2);
  bool operator!=(const multimap& c1, const multimap& c2);
  bool operator<(const multimap& c1, const multimap& c2);
  bool operator>(const multimap& c1, const multimap& c2);
  bool operator<=(const multimap& c1, const multimap& c2);
  bool operator>=(const multimap& c1, const multimap& c2);

All of the C++ containers can be compared and assigned with the standard comparison operators: ==, !=, <=, >=, <, >, and =. Performing a comparison or assigning one multimap to another takes linear time.

Two multimaps are equal if:

1. Their size is the same, and
2. Each member in location i in one multimap is equal to the the member in location i in the other multimap.

Comparisons among multimaps are done lexicographically.

  #include <map>
  reverse_iterator rbegin();
  const_reverse_iterator rbegin() const;

The rbegin() function returns a reverse_iterator to the end of the current multimap.

rbegin() runs in constant time.

  #include <map>
  reverse_iterator rend();
  const_reverse_iterator rend() const;

The function rend() returns a reverse_iterator to the beginning of the current multimap.

rend() runs in constant time.

  #include <map>
  size_type size() const;

The size() function returns the number of elements in the current multimap.

  #include <map>
  void swap( container& from );

The swap() function exchanges the elements of the current multimap with those of from. This function operates in constant time.

For example, the following code uses the swap() function to exchange the values of two strings:

   string first( "This comes first" );
   string second( "And this is second" );
   first.swap( second );
   cout << first << endl;
   cout << second << endl;          

The above code displays:

   And this is second
   This comes first             

  #include <map>
  iterator upper_bound( const key_type& key );

The function upper_bound() returns an iterator to the first element in the multimap with a key greater than key.

  #include <map>
  value_compare value_comp() const;

The value_comp() function returns the function that compares values.

value_comp() runs in constant time.