std::set<Key,Compare,Allocator>::insert
(constexpr since C++26)
(constexpr since C++26)
void insert( InputIt first, InputIt last );
(constexpr since C++26)
(constexpr since C++26)
std::pair <iterator, bool> insert( K&& x );
(constexpr since C++26)
iterator insert( const_iterator pos, K&& x );
(constexpr since C++26)
Attempts to insert element(s) into *this.
- If *this already contain an element with an equivalent key, does nothing.
- Otherwise, inserts the element(s) into *this.
[
first,
last)
.-
value_type
is not EmplaceConstructible intoset
from *first.
- first or last is an iterator into *this.
value_type
with std::forward <K>(x) and then inserts u into *this. The existence of the equivalent key is determined transparently using x before constructing u.-
value_type
is not EmplaceConstructible intoset
from std::forward <K>(x). - equal_range(u) == equal_range(x) is false.
-
Compare
is transparent. - std::is_convertible_v <K&&, const_iterator> is false.
- std::is_convertible_v <K&&, iterator> is false.
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)
Contents
[edit] Parameters
InputIt
must meet the requirements of LegacyInputIterator.
[edit] Return value
insert_return_type
with the members initialized as follows:
- If nh is empty,
inserted
is false,position
is end(), andnode
is empty. - Otherwise if the insertion took place,
inserted
is true,position
points to the inserted element, andnode
is empty. - If the insertion failed,
inserted
is false,node
has the previous value of nh, andposition
points to an element with a key equivalent to nh.key().
[edit] Exceptions
If an exception is thrown by any operation during the insertion of a single element, the insertion has no effect.
[edit] Complexity
Given \(\scriptsize N\)N as size():
[edit] Notes
The hinted insert
((3,4), (8) and (10))
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.
If multiple elements in the range have keys that compare equivalent, it is unspecified which element is inserted (pending LWG2844).
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_lib_associative_heterogeneous_insertion |
202311L |
(C++26) | Heterogeneous overloads for the remaining member functions in ordered and unordered associative containers. (9,10) |
[edit] 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"; }
Output:
insert done no insertion
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
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 to be as close as possible to the position just prior to pos |
LWG 264 | C++98 | the complexity of overload (5) was required to be linear if the range [ first, last) is sorted according to Compare
|
removed the linear requirement in this special case |
LWG 316 | C++98 | in the return value of overload (1), it was not specified which bool value indicates a successful insertion |
success is indicated by true |