std::set<Key,Compare,Allocator>::insert
Inserts element(s) into the container, if the container doesn’t already contain an element with an equivalent key.
# Declarations
std::pair<iterator, bool> insert( const value_type& value );
std::pair<iterator, bool> insert( value_type&& value );
(since C++11)
iterator insert( iterator pos, const value_type& value );
(until C++11)
iterator insert( const_iterator pos, const value_type& value );
(since C++11)
iterator insert( const_iterator pos, value_type&& value );
(since C++11)
template< class InputIt >
void insert( InputIt first, InputIt last );
void insert( std::initializer_list<value_type> ilist );
(since C++11)
insert_return_type insert( node_type&& nh );
(since C++17)
iterator insert( const_iterator pos, node_type&& nh );
(since C++17)
template< class K >
std::pair<iterator, bool> insert( K&& x );
(since C++23)
template< class K >
iterator insert( const_iterator pos, K&& x );
(since C++23)
# Parameters
pos: iterator to the position before which the new element will be insertedvalue: element value to insertfirst, last: range of elements to insertilist: initializer list to insert the values fromnh: a compatible node handlex: a value of any type that can be transparently compared with a key
# 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 std::set) whose smallest element is greater than the last element in *this.
# Example
#include <cassert>
#include <iostream>
#include <set>
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";
}
# Defect reports
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 233 | C++98 | pos was just a hint, it could be totally ignored | the insertion is required tobe as close as possible to theposition just prior to pos |
| LWG 264 | C++98 | the complexity of overload (5) was required to be linear ifthe range [first, last) is sorted according to Compare | removed the linear requirementin this special case |
| LWG 316 | C++98 | in the return value of overload (1), it was not specifiedwhich bool value indicates a successful insertion | success isindicated by true |