public member function
<unordered_set>

std::unordered_multiset::insert

(1)
iterator insert ( const value_type& val );
(2)
iterator insert ( value_type&& val );
(3)
iterator insert ( const_iterator hint, const value_type& val );
(4)
iterator insert ( const_iterator hint, value_type&& val );
(5)
template <class InputIterator>
    void insert ( InputIterator first, InputIterator last );
(6)
void insert ( initializer_list<value_type> il );
Insert elements
Inserts new elements in the unordered_multiset.

This effectively increases the container size by the number of elements inserted.

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

Parameters

val
Object to be copied to (or moved as) the value of the new element.
Versions (1) and (3) copy the element (i.e., val preserves its contents, the container keeps a copy).
Versions (2) and (4) move the element (i.e., val loses its content, which is acquired by the new element in the container).
Member type value_type is the type of the elements in the container, defined in unordered_multiset as an alias of the first template parameter (Key).
hint
Iterator to a position suggested as a hint on where to start the search for the proper insertion point. This value may or may not be used by the container to optimize the operation. The element will be stored in its corresponding bucket, no matter what is passed as hint.
Member type const_iterator is a forward iterator type.
first, last
Iterators specifying a range of elements. Copies of the elements in the range [first,last) are inserted in the unordered_multiset 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.
Neither first nor last shall be iterators in the destination container.
The template type can be any type of input iterator.
il
An initializer_list object. The compiler will automatically construct such objects from initializer list declarators.
Member type value_type is the type of the elements contained in the container, defined in unordered_multiset as an alias of the first template parameter (Key).

Return value

In the versions returning a value ((1),(2),(3) and (4)), the function returns an iterator to the newly inserted element.

Versions (5) and (6) return no value.

Member type iterator is a forward iterator type.

All iterators in an unordered_multiset have const access to the elements: Elements can be inserted or removed, but not modified while in the container.

The storage for the new element is allocated using allocator_traits<allocator_type>::construct(), which may throw exceptions on failure (for the default allocator, bad_alloc is thrown if the allocation request does not succeed).

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
// unordered_multiset::insert
#include <iostream>
#include <string>
#include <array>
#include <unordered_set>

int main ()
{
  std::unordered_multiset<std::string> myums = {"red","green","blue"};
  std::array<std::string,2> myarray = {"red","yellow"};
  std::string mystring = "red";

  myums.insert (mystring);                        // copy insertion
  myums.insert (mystring+"dish");                 // move insertion
  myums.insert (myarray.begin(), myarray.end());  // range insertion
  myums.insert ( {"purple","orange"} );           // initializer list insertion

  std::cout << "myums contains:";
  for (const std::string& x: myums) std::cout << " " << x;
  std::cout <<  std::endl;

  return 0;
}


Possible output:
myums contains: green blue reddish yellow red red red orange purple

Complexity

Single element insertions:
Average case: constant.
Worst case: linear in container size.
Multiple elements insertion:
Average case: linear in the number of elements inserted.
Worst case: N*(size+1): number of elements inserted times the container size plus one.
May trigger a rehash (not included).

Iterator validity

On most cases, all iterators in the container remain valid after the insertion. The only exception being when the growth of the container forces a rehash. In this case, all iterators in the container are invalidated.

A rehash is forced if the new container size after the insertion operation would increase above its capacity threshold (calculated as the container's bucket_count multiplied by its max_load_factor).

References to elements in the unordered_multiset container remain valid in all cases, even after a rehash.

See also

unordered_multiset::emplace
Construct and insert element (public member function)
unordered_multiset::emplace_hint
Construct and insert element with hint (public member function)
unordered_multiset::operator=
Assign content (public member function )
unordered_multiset::erase
Erase elements (public member function )

C++