pair<iterator,bool> insert ( const value_type& x );
           iterator insert ( iterator position, const value_type& x );
template <class InputIterator>
      void insert ( InputIterator first, InputIterator last );

Insert element

The set container is extended by inserting a single new element (if parameter x is used) or a sequence of elements (if input iterators are used).

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

Because set containers do not allow for duplicate values, the insertion operation checks for each element inserted whether another element exists already in the container with the same value, if so, the element is not inserted and -if the function returns a value- an iterator to it is returned.

For a similar container allowing for duplicate elements, see multiset.

Internally, set containers keep all their elements sorted following the criterion specified by its comparison object on construction. Each element is inserted in its respective position following this ordering.

Efficiency of this operation can be dramatically improved by providing the appropriate value as parameter position.

Parameters

x

Value to be used to initialize the inserted element.
value_type is a member type defined in set containers as an alias of Key, which is the first template parameter and the type of the elements stored in the container.

position

Position of the first element to be compared for the insertion operation.
Notice that this does not force the new element to be in that position within the set container (elements in a set always follow a specific ordering), but this is actually an indication of a possible insertion position in the container that, if set to the element that precedes the actual location where the element is inserted, makes for a very efficient insertion operation.
iterator is a member type, defined as a bidirectional iterator type.

first, last

Iterators specifying a range of elements. Copies of the elements in the range [first,last) are inserted in the set.
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 template type can be any type of input iterator.

Return value

The second version returns an iterator pointing to either the newly inserted element or to the element that already had its same value in the set.

iterator is a member type, defined as a bidirectional iterator type.

Example

// set::insert
#include <iostream>
#include <set>
using namespace std;

int main ()
{
  set<int> myset;
  set<int>::iterator it;
  pair<set<int>::iterator,bool> ret;

  // set some initial values:
  for (int i=1; i<=5; i++) myset.insert(i*10);    // set: 10 20 30 40 50

  ret = myset.insert(20);               // no new element inserted

  if (ret.second==false) it=ret.first;  // "it" now points to element 20

  myset.insert (it,25);                 // max efficiency inserting
  myset.insert (it,24);                 // max efficiency inserting
  myset.insert (it,26);                 // no max efficiency inserting

  int myints[]= {5,10,15};              // 10 already in set, not inserted
  myset.insert (myints,myints+3);

  cout << "myset contains:";
  for (it=myset.begin(); it!=myset.end(); it++)
    cout << " " << *it;
  cout << endl;

  return 0;
}

myset contains: 5 10 15 20 24 25 26 30 40 50

Complexity

See also