std::set<Key,Compare,Allocator>::insert

std::pair<iterator, bool> insert( const value_type& value );

std::pair<iterator, bool> insert( value_type&& value );

iterator insert( iterator pos, const value_type& value );

iterator insert( const_iterator pos, const value_type& value );

iterator insert( const_iterator pos, value_type&& value );

template< class InputIt >
void insert( InputIt first, InputIt last );

void insert( std::initializer_list<value_type> ilist );

insert_return_type insert( node_type&& nh );

iterator insert( const_iterator pos, node_type&& nh );

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

No iterators or references are invalidated. If the insertion is successful, pointers and references to the element obtained while it is held in the node handle are invalidated, and pointers and references obtained to that element before it was extracted become valid. (since C++17).

Parameters

Return value

bool

• If nh is empty, inserted is false, position is end(), and node is empty.
• Otherwise if the insertion took place, inserted is true, position points to the inserted element, and node is empty.
• If the insertion failed, inserted is false, node has the previous value of nh, and position points to an element with a key equivalent to nh.key().

Exceptions

Complexity

Notes

The hinted insert (3,4) does not return a boolean in order to be signature-compatible with positional insert on sequential containers, such as std::vector::insert. This makes it possible to create generic inserters such as std::inserter. One way to check success of a hinted insert is to compare size() before and after.

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.

Example

#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 is 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";
}

insert done
no insertion

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

See also