The object allocates and frees storage for the sequence it controls as individual nodes. It inserts elements into a (nearly) balanced tree that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements.
The object orders the sequence it controls by calling a stored delegate object of type multimap::key_compare (STL/CLR). You can specify the stored delegate object when you construct the multimap; if you specify no delegate object, the default is the comparison operator<(key_type, key_type). You access this stored object by calling the member function multimap::key_comp (STL/CLR)().
Such a delegate object must impose a strict weak ordering on keys of type multimap::key_type (STL/CLR). That means, for any two keys X and Y:
key_comp()(X, Y) returns the same Boolean result on every call.
If key_comp()(X, Y) is true, then key_comp()(Y, X) must be false.
If key_comp()(X, Y) is true, then X is said to be ordered before Y.
If !key_comp()(X, Y) && !key_comp()(Y, X) is true, then X and Y are said to have equivalent ordering.
For any element X that precedes Y in the controlled sequence, key_comp()(Y, X) is false. (For the default delegate object, keys never decrease in value.) Unlike template class map (STL/CLR), an object of template class multimap does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.)
Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations proportional to the logarithm of the number of elements in the sequence (logarithmic time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element.
A multimap supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by multimap::end (STL/CLR)(). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a multimap iterator to reach the head node, and it will then compare equal to end(). But you cannot dereference the iterator returned by end().
Note that you cannot refer to a multimap element directly given its numerical position -- that requires a random-access iterator.
A multimap iterator stores a handle to its associated multimap node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A multimap iterator remains valid so long as its associated multimap node is associated with some multimap. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to end().
Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does not destroy its elements.