public member function
<map>

std::multimap::multimap

empty (1)
explicit multimap (const key_compare& comp = key_compare(),
                   const allocator_type& alloc = allocator_type());
range (2)
template <class InputIterator>
  multimap (InputIterator first, InputIterator last,
            const key_compare& comp = key_compare(),
            const allocator_type& alloc = allocator_type());
copy (3)
multimap (const multimap& x);
empty (1)
explicit multimap (const key_compare& comp = key_compare(),
                   const allocator_type& alloc = allocator_type());
explicit multimap (const allocator_type& alloc);
range (2)
template <class InputIterator>
  multimap (InputIterator first, InputIterator last,
       const key_compare& comp = key_compare(),
       const allocator_type& = allocator_type());
copy (3)
multimap (const multimap& x);
multimap (const multimap& x, const allocator_type& alloc);
move (4)
multimap (multimap&& x);
multimap (multimap&& x, const allocator_type& alloc);
initializer list (5)
multimap (initializer_list<value_type> il,
     const key_compare& comp = key_compare(),
     const allocator_type& alloc = allocator_type());
empty (1)
multimap();
explicit multimap (const key_compare& comp,
                   const allocator_type& alloc = allocator_type());
explicit multimap (const allocator_type& alloc);
range (2)
template <class InputIterator>
  multimap (InputIterator first, InputIterator last,
       const key_compare& comp = key_compare(),
       const allocator_type& = allocator_type());
template <class InputIterator>
  multimap (InputIterator first, InputIterator last,
       const allocator_type& = allocator_type());
copy (3)
multimap (const multimap& x);
multimap (const multimap& x, const allocator_type& alloc);
move (4)
multimap (multimap&& x);
multimap (multimap&& x, const allocator_type& alloc);
initializer list (5)
multimap (initializer_list<value_type> il,
     const key_compare& comp = key_compare(),
     const allocator_type& alloc = allocator_type());
multimap (initializer_list<value_type> il,
     const allocator_type& alloc = allocator_type());
Construct multimap
Constructs a multimap container object, initializing its contents depending on the constructor version used:

(1) empty container constructor (default constructor)
Constructs an empty container, with no elements.
(2) range constructor
Constructs a container with as many elements as the range [first,last), with each element constructed from its corresponding element in that range.
(3) copy constructor
Constructs a container with a copy of each of the elements in x.

The container keeps an internal copy of alloc and comp, which are used to allocate storage and to sort the elements throughout its lifetime.
The copy constructor (3) creates a container that keeps and uses copies of x's allocator and comparison object.

The storage for the elements is allocated using this internal allocator.

The elements are sorted according to the comparison object.
(1) empty container constructors (default constructor)
Constructs an empty container, with no elements.
(2) range constructor
Constructs a container with as many elements as the range [first,last), with each element emplace-constructed from its corresponding element in that range.
(3) copy constructor (and copying with allocator)
Constructs a container with a copy of each of the elements in x.
(4) move constructor (and moving with allocator)
Constructs a container that acquires the elements of x.
If alloc is specified and is different from x's allocator, the elements are moved. Otherwise, no elements are constructed (their ownership is directly transferred).
x is left in an unspecified but valid state.
(5) initializer list constructor
Constructs a container with a copy of each of the elements in il.

The container keeps an internal copy of alloc, which is used to allocate and deallocate storage for its elements, and to construct and destroy them (as specified by its allocator_traits). If no alloc argument is passed to the constructor, a default-constructed allocator is used, except in the following cases:
- The copy constructor (3, first signature) creates a container that keeps and uses a copy of the allocator returned by calling the appropriate selected_on_container_copy_construction trait on x's allocator.
- The move constructor (4, first signature) acquires x's allocator.

The container also keeps an internal copy of comp (or x's comparison object), which is used to establish the order of the elements in the container and to check for elements with equivalent keys.

All elements are copied, moved or otherwise constructed by calling allocator_traits::construct with the appropriate arguments.

The elements are sorted according to the comparison object. If elements with equivalent keys are passed to the constructor, their relative order is preserved.

Parameters

comp
Binary predicate that, taking two element keys as argument, returns true if the first argument goes before the second argument in the strict weak ordering it defines, and false otherwise.
This shall be a function pointer or a function object.
Member type key_compare is the internal comparison object type used by the container, defined in multimap as an alias of its third template parameter (Compare).
If key_compare uses the default less (which has no state), this parameter is not relevant.
alloc
Allocator object.
The container keeps and uses an internal copy of this allocator.
Member type allocator_type is the internal allocator type used by the container, defined in multimap as an alias of its fourth template parameter (Alloc).
If allocator_type is an instantiation of the default allocator (which has no state), this parameter is not relevant.
first, last
Input iterators to the initial and final positions in a range. The range used is [first,last), which includes all the elements between first and last, including the element pointed by first but not the element pointed by last.
The function template argument InputIterator shall be an input iterator type that points to elements of a type from which value_type objects can be constructed (in multimap, value_type is an alias of pair<const key_type, mapped_type>)
x
Another multimap object of the same type (with the same class template arguments Key, T, Compare and Alloc), whose contents are either copied or acquired.
il
An initializer_list object.
These objects are automatically constructed from initializer list declarators.
Member type value_type is the type of the elements in the container, defined in multimap as an alias of pair<const key_type, mapped_type> (see multimap types).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
 
// constructing multimaps
#include <iostream>
#include <map>

bool fncomp (char lhs, char rhs) {return lhs<rhs;}

struct classcomp {
  bool operator() (const char& lhs, const char& rhs) const
  {return lhs<rhs;}
};

int main ()
{
  std::multimap<char,int> first;

  first.insert(std::pair<char,int>('a',10));
  first.insert(std::pair<char,int>('b',15));
  first.insert(std::pair<char,int>('b',20));
  first.insert(std::pair<char,int>('c',25));

  std::multimap<char,int> second (first.begin(),first.end());

  std::multimap<char,int> third (second);

  std::multimap<char,int,classcomp> fourth;                 // class as Compare

  bool(*fn_pt)(char,char) = fncomp;
  std::multimap<char,int,bool(*)(char,char)> fifth (fn_pt); // function pointer as comp

  return 0;
}


The code does not produce any output, but demonstrates some ways in which a multimap container can be constructed.

Complexity

Constant for the empty constructors (1), and for the move constructors (4) (unless alloc is different from x's allocator).
For all other cases, linear in the distance between the iterators (copy constructions) if the elements are already sorted according to the same criterion. For unsorted sequences, linearithmic (N*logN) in that distance (sorting,copy constructions).

Iterator validity

The move constructors (4), invalidate all iterators, pointers and references related to x if the elements are moved.

Data races

All copied elements are accessed.
The move constructors (4) modify x.

Exception safety

Strong guarantee: no effects in case an exception is thrown.
If allocator_traits::construct is not supported with the appropriate arguments for the element constructions, or if the range specified by [first,last) is not valid, it causes undefined behavior.

See also

multimap::operator=
Copy container content (public member function )
multimap::insert
Insert element (public member function )

C++