public member function
<unordered_set>

std::unordered_set::insert

(1)
pair<iterator,bool> insert ( const value_type& val );
(2)
pair<iterator,bool> 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_set.

Each element is inserted only if it is not equivalent to any other element already in the container (elements in an unordered_set have unique values).

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_set 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_set 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_set as an alias of the first template parameter (Key).

Return value

In versions (1) and (2), the function returns a pair object whose first element is an iterator pointing either to the newly inserted element in the container or to the element whose key is equivalent, and a bool value indicating whether the element was successfully inserted or not.

In versions (3) and (4), the function returns an iterator pointing either to the newly inserted element in the container or to the element whose key is equivalent.

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

Member type iterator is a forward iterator type.

All iterators in an unordered_set 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_set::insert
#include <iostream>
#include <string>
#include <array>
#include <unordered_set>

int main ()
{
  std::unordered_set<std::string> myset = {"yellow","green","blue"};
  std::array<std::string,2> myarray = {"black","white"};
  std::string mystring = "red";

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

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

  return 0;
}


Possible output:
myset contains: green blue reddish white yellow black 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_set container remain valid in all cases, even after a rehash.

See also

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

C++