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.
value
. value
in the position as close as possible, just prior(since C++11), to hint
. [first, last)
.ilist
.No iterators or references are invalidated.
Parameters
hint | - |
| ||||
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 . |
Return value
bool
denoting whether the insertion took place.Exceptions
Complexity
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) |
O(N*log(size() + N))
, where N is the number of elements to insert.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'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
See also
(C++11) | constructs element in-place (public member function) |
(C++11) | constructs elements in-place using a hint (public member function) |
Please login to continue.