std::set::insert - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::set::insert

From cppreference.com
< cpp‎ | container‎ | set

std::pair<iterator,bool> insert( const value_type& value ); | (1) |
std::pair<iterator,bool> insert( value_type&& value ); | (2) | (since C++11)
| (3) |
iterator insert( iterator hint, const value_type& value ); |  | (until C++11)
iterator insert( const_iterator hint, const value_type& value ); |  | (since C++11)
iterator insert( const_iterator hint, value_type&& value ); | (4) | (since C++11)
template< class InputIt > void insert( InputIt first, InputIt last ); | (5) |
void insert( std::initializer_list<value_type> ilist ); | (6) | (since C++11)

Inserts element(s) into the container, if the container doesn't already contain an element with an equivalent key.

1-2) inserts `value`.
3-4) inserts `value` in the position as close as possible, just prior(since C++11), to `hint`.
5) Inserts elements from range `[first, last)`.
6) Inserts elements from initializer list `ilist`.

No iterators or references are invalidated.

### [edit] Parameters

hint | - | iterator, used as a suggestion as to where to insert the content
value | - | element value to insert
first, last | - | range of elements to insert
ilist | - | initializer list to insert the values from
Type requirements
- `InputIt` must meet the requirements of `InputIterator`.

### [edit] Return value

1-2) Returns a pair consisting of an iterator to the inserted element (or to the element that prevented the insertion) and a bool denoting whether the insertion took place.
3-4) Returns an iterator to the inserted element, or to the element that prevented the insertion.
5-6) (none)

### [edit] Exceptions

1-4) If an exception is thrown by any operation, the insertion has no effect.

| This section is incomplete Reason: cases 5-6

### [edit] Complexity

1-2) Logarithmic in the size of the container, `O(log(size()))`.

3-4) Amortized constant if the insertion happens in the position just after the hint, logarithmic in the size of the container otherwise. | (until C++11)
3-4) Amortized constant if the insertion happens in the position just before the hint, logarithmic in the size of the container otherwise. | (since C++11)

5-6) `O(N*log(size() + N))`, where N is the number of elements to insert.

### [edit] Notes

The overloads (5-6) are often implemented as a loop that calls the overload (3) with end() as the hint; they are optimized for appending a sorted sequence (such as another set) whose smallest element is greater than the last element in *this

### [edit] Example

Run this code

    #include <set>
    #include <cassert>
    #include <iostream>

    int main()
    {
      std::set<int> set;

      auto result_1 = set.insert(3);
      assert(result_1.first != set.end()); // it's a valid iterator
      assert(*result_1.first == 3);
      if (result_1.second)
        std::cout << "insert done\n";

      auto result_2 = set.insert(3);
      assert(result_2.first == result_1.first); // same iterator
      assert(*result_2.first == 3);
      if (!result_2.second)
        std::cout << "no insertion\n";
    }

Output:

    insert done
    no insertion

### [edit] See also

emplace (C++11) | constructs element in-place (public member function) [edit]
emplace_hint (C++11) | constructs elements in-place using a hint (public member function) [edit]

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/container/set/insert&oldid=68001"
Category:

- Todo with reason