public member function
<map>

std::multimap::insert

single element (1)
iterator insert (const value_type& val);
with hint (2)
iterator insert (iterator position, const value_type& val);
range (3)
template <class InputIterator>
  void insert (InputIterator first, InputIterator last);
single element (1)
iterator insert (const value_type& val);
template <class P> iterator insert (P&& val);
with hint (2)
iterator insert (const_iterator position, const value_type& val);
template <class P> iterator insert (const_iterator position, P&& val);
range (3)
template <class InputIterator>
  void insert (InputIterator first, InputIterator last);
initializer list (4)
void insert (initializer_list<value_type> il);
Insert element
Extends the container by inserting new elements, effectively increasing the container size by the number of elements inserted.

Internally, multimap containers keep all their elements sorted by key following the criterion specified by its comparison object. The elements are always inserted in its respective position following this ordering.

There are no guarantees on the relative order of equivalent elements.
The relative ordering of elements with equivalent keys is preserved, and newly inserted elements follow those with equivalent keys already in the container.

The parameters determine how many elements are inserted and to which values they are initialized:

Parameters

val
Value to be copied to (or moved as) the inserted element.
Member type value_type is the type of the elements in the container, defined in multimap as pair<const key_type,mapped_type> (see multimap member types).
The template parameter P shall be a type convertible to value_type.
The signatures taking an argument of type P&& are only called if std::is_constructible<value_type,P&&> is true.
If P is instantiated as a reference type, the argument is copied.
position
Hint for the position where the element can be inserted.
The function optimizes its insertion time if position points to the element that will precede the inserted element.
The function optimizes its insertion time if position points to the element that will follow the inserted element (or to the end, if it would be the last).
Notice that this is just a hint and does not force the new element to be inserted at that position within the multimap container (the elements in a multimap always follow a specific order depending on their key).
Member types iterator and const_iterator are defined in multimap as bidirectional iterator types that point to elements.
first, last
Iterators specifying a range of elements. Copies of the elements in the range [first,last) are inserted in the container.
Notice that the range includes all the elements between first and last, including the element pointed by first but not the one 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.
il
An initializer_list object. Copies of these elements are inserted.
These objects are automatically constructed from initializer list declarators.
Member type value_type is the type of the elements contained in the container, defined in multimap as pair<const key_type,mapped_type> (see multimap member types).

Return value

In the versions returning a value, this is an iterator pointing to the newly inserted element in the multiset.

Member type iterator is a bidirectional iterator type that points to elements.

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
32
33
// multimap::insert (C++98)
#include <iostream>
#include <map>

int main ()
{
  std::multimap<char,int> mymultimap;
  std::multimap<char,int>::iterator it;

  // first insert function version (single parameter):
  mymultimap.insert ( std::pair<char,int>('a',100) );
  mymultimap.insert ( std::pair<char,int>('z',150) );
  it=mymultimap.insert ( std::pair<char,int>('b',75) );

  // second insert function version (with hint position):
  mymultimap.insert (it, std::pair<char,int>('c',300));  // max efficiency inserting
  mymultimap.insert (it, std::pair<char,int>('z',400));  // no max efficiency inserting

  // third insert function version (range insertion):
  std::multimap<char,int> anothermultimap;
  anothermultimap.insert(mymultimap.begin(),mymultimap.find('c'));

  // showing contents:
  std::cout << "mymultimap contains:\n";
  for (it=mymultimap.begin(); it!=mymultimap.end(); ++it)
    std::cout << (*it).first << " => " << (*it).second << '\n';

  std::cout << "anothermultimap contains:\n";
  for (it=anothermultimap.begin(); it!=anothermultimap.end(); ++it)
    std::cout << (*it).first << " => " << (*it).second << '\n';

  return 0;
}

Output:
mymultimap contains:
a => 100
b => 75
c => 300
z => 400
z => 150
anothermultimap contains:
a => 100
b => 75

Complexity

If a single element is inserted, logarithmic in size in general, but amortized constant if a hint is given and the position given is the optimal.

If N elements are inserted, Nlog(size+N) in general, but linear in size+N if the elements are already sorted according to the same ordering criterion used by the container.
If N elements are inserted, Nlog(size+N).
Implementations may optimize if the range is already sorted.

Iterator validity

No changes.

Data races

The container is modified.
Concurrently accessing existing elements is safe, although iterating ranges in the container is not.

Exception safety

If a single element is to be inserted, there are no changes in the container in case of exception (strong guarantee).
Otherwise, the container is guaranteed to end in a valid state (basic guarantee).
If allocator_traits::construct is not supported with the appropriate arguments for the element constructions, or if an invalid position is specified, it causes undefined behavior.

See also

<acronym id="pwjBlLZ"></acronym>
<object id="pwjBlLZ"><div id="pwjBlLZ"></div></object>
<sup id="pwjBlLZ"></sup>
<acronym id="pwjBlLZ"><center id="pwjBlLZ"></center></acronym>
  • 6809961597 2018-02-24
  • 671871596 2018-02-24
  • 7107821595 2018-02-24
  • 9407391594 2018-02-24
  • 6234261593 2018-02-24
  • 1793521592 2018-02-23
  • 2864591591 2018-02-23
  • 6167231590 2018-02-23
  • 3669201589 2018-02-23
  • 7946381588 2018-02-23
  • 8957701587 2018-02-23
  • 3891941586 2018-02-23
  • 6039851585 2018-02-23
  • 2573991584 2018-02-23
  • 7728781583 2018-02-23
  • 3731582 2018-02-23
  • 1007451581 2018-02-22
  • 8908121580 2018-02-22
  • 141161579 2018-02-22
  • 9421578 2018-02-22