Namespaces
Variants

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

From cppreference.net
C++
Containers library
std::set
Member functions
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
Deduction guides (C++17)
std:: pair < iterator, bool > insert ( const value_type & value ) ;
(1) (constexpr desde C++26)
std:: pair < iterator, bool > insert ( value_type && value ) ;
(2) (desde C++11)
(constexpr desde C++26)
(3)
iterator insert ( iterator pos, const value_type & value ) ;
(hasta C++11)
iterator insert ( const_iterator pos, const value_type & value ) ;
(desde C++11)
(constexpr desde C++26)
iterator insert ( const_iterator pos, value_type && value ) ;
(4) (desde C++11)
(constexpr desde C++26)
template < class InputIt >
void insert ( InputIt first, InputIt last ) ;
(5) (constexpr desde C++26)
void insert ( std:: initializer_list < value_type > ilist ) ;
(6) (desde C++11)
(constexpr desde C++26)
insert_return_type insert ( node_type && nh ) ;
(7) (desde C++17)
(constexpr desde C++26)
iterator insert ( const_iterator pos, node_type && nh ) ;
(8) (desde C++17)
(constexpr desde C++26)
template < class K >
std:: pair < iterator, bool > insert ( K && x ) ;
(9) (desde C++23)
(constexpr desde C++26)
template < class K >
iterator insert ( const_iterator pos, K && x ) ;
(10) (desde C++23)
(constexpr desde C++26)

Intenta insertar elemento(s) en * this .

  • Si * this ya contiene un elemento con una clave equivalente, no hace nada.
  • En caso contrario, inserta el(los) elemento(s) en * this .
1-4) Inserta value . Si se proporciona pos , value se insertará lo más cerca posible de la posición inmediatamente anterior a pos .
1,3) Si value_type no es CopyInsertable en set , el comportamiento es indefinido.
2,4) Si value_type no es MoveInsertable en set , el comportamiento es indefinido.
(since C++11)
5) Inserta elementos del rango [ first , last ) .
Si se satisface cualquiera de las siguientes condiciones, el comportamiento es indefinido:
(desde C++11)
  • first o last es un iterador que apunta a * this .
6) Inserta elementos desde la lista de inicialización ilist .
Equivalente a insert ( ilist. begin ( ) , ilist. end ( ) ) .
7) Si nh es un node handle vacío, no hace nada. De lo contrario, inserta el elemento poseído por nh en el contenedor, si el contenedor aún no contiene un elemento con una clave equivalente a nh. key ( ) . El comportamiento es indefinido si nh no está vacío y get_allocator ( ) ! = nh. get_allocator ( ) .
8) Si nh es un node handle vacío, no hace nada y retorna el iterador final. De lo contrario, inserta el elemento poseído por nh en el contenedor, si el contenedor aún no contiene un elemento con una clave equivalente a nh. key ( ) , y retorna el iterador que apunta al elemento con clave equivalente a nh. key ( ) (independientemente de si la inserción tuvo éxito o falló). Si la inserción tiene éxito, nh es movido, de lo contrario conserva la propiedad del elemento. El elemento se inserta tan cerca como sea posible de la posición inmediatamente anterior a pos . El comportamiento es indefinido si nh no está vacío y get_allocator ( ) ! = nh. get_allocator ( ) .
9,10) Construye un objeto u de tipo value_type con std:: forward < K > ( x ) y luego inserta u en * this . La existencia de la clave equivalente se determina de forma transparente usando x antes de construir u .
Si se satisface cualquiera de las siguientes condiciones, el comportamiento es indefinido:
9) Esta sobrecarga participa en la resolución de sobrecarga solo si Compare es transparent .
10) u será insertado lo más cerca posible de la posición inmediatamente anterior a pos .
Esta sobrecarga participa en la resolución de sobrecarga solo si se cumplen todas las siguientes condiciones:

No se invalidan iteradores ni referencias. Si la inserción es exitosa, se invalidan los punteros y referencias al elemento obtenidos mientras se mantiene en el node handle, y los punteros y referencias obtenidos para ese elemento antes de ser extraído pasan a ser válidos. (desde C++17)

Contenidos

Parámetros

pos - iterador a la posición antes de la cual se insertará el nuevo elemento
value - valor del elemento a insertar
first, last - el par de iteradores que define el rango fuente de elementos a insertar
ilist - lista de inicializadores de la cual insertar los valores
nh - un node handle compatible
x - un valor de cualquier tipo que pueda compararse transparentemente con una clave
Requisitos de tipo
-
InputIt debe cumplir con los requisitos de LegacyInputIterator .

Valor de retorno

1,2) Un par que consiste en un iterador al elemento insertado (o al elemento que impidió la inserción) y un valor bool establecido en true si y solo si la inserción tuvo lugar.
3,4) Un iterador al elemento insertado, o al elemento que impidió la inserción.
7) Un objeto de insert_return_type con los miembros inicializados de la siguiente manera:
  • Si nh está vacío, inserted es false , position es end ( ) , y node está vacío.
  • De lo contrario, si la inserción tuvo lugar, inserted es true , position apunta al elemento insertado, y node está vacío.
  • Si la inserción falló, inserted es false , node tiene el valor previo de nh , y position apunta a un elemento con una clave equivalente a nh. key ( ) .
8) Iterador final si nh estaba vacío, iterador que apunta al elemento insertado si la inserción tuvo lugar, e iterador que apunta a un elemento con una clave equivalente a nh. key ( ) si falló.
9) Un par que consiste en un iterador al elemento insertado (o al elemento que impidió la inserción) y un valor bool establecido en true si y solo si la inserción tuvo lugar.
10) Un iterador al elemento insertado, o al elemento que impidió la inserción.

Excepciones

Si se lanza una excepción por cualquier operación durante la inserción de un solo elemento, la inserción no tiene efecto.

Complejidad

Dado N como size ( ) :

1,2) log(N)
3,4) Amortizado constante si la inserción ocurre en la posición justo después (until C++11) antes (since C++11) pos , log(N) en caso contrario.
5,6) log(N+M) , donde M es el número de elementos a insertar.
7) log(N)
8) Constante amortizado si la inserción ocurre en la posición inmediatamente anterior a pos , log(N) en caso contrario.
9) log(N)
10) Constante amortizado si la inserción ocurre en la posición justo antes de pos , log(N) en caso contrario.

Notas

La inserción con sugerencia ( ( 3,4 ) , ( 8 ) y ( 10 ) ) no devuelve un booleano para ser compatible en firma con la inserción posicional en contenedores secuenciales, como std::vector::insert . Esto hace posible crear insertores genéricos como std::inserter . Una forma de verificar el éxito de una inserción con sugerencia es comparar size() antes y después.

Las sobrecargas ( 5,6 ) frecuentemente se implementan como un bucle que llama a la sobrecarga ( 3 ) con end() como sugerencia; están optimizadas para añadir una secuencia ordenada (como otro std::set ) cuyo elemento más pequeño es mayor que el último elemento en * this .

Si múltiples elementos en el rango tienen claves que son equivalentes al comparar, no está especificado qué elemento se inserta (pendiente de LWG2844 ).

Macro de prueba de características Valor Estándar Característica
__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) Sobrecargas heterogéneas para las funciones miembro restantes en contenedores asociativos ordenados y contenedores asociativos no ordenados. ( 9,10 )

Ejemplo

Ejecutar este código 
#include <cassert>
#include <iostream>
#include <set>
int main()
{
    std::set<int> set;
    auto result_1 = set.insert(3);
    assert(result_1.first != set.end()); // es un iterador válido
    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); // mismo iterador
    assert(*result_2.first == 3);
    if (!result_2.second)
        std::cout << "no insertion\n";
}

Salida: 

insert done
no insertion

Informes de defectos

Los siguientes informes de defectos que modifican el comportamiento se aplicaron retroactivamente a los estándares de C++ publicados anteriormente.

DR Aplicado a Comportamiento publicado Comportamiento correcto
LWG 233 C++98 pos era solo una sugerencia, podía ser completamente ignorada la inserción debe realizarse
lo más cerca posible de la
posición inmediatamente anterior a pos
LWG 264 C++98 la complejidad de la sobrecarga ( 5 ) debía ser lineal si
el rango [ first , last ) está ordenado según Compare 		se eliminó el requisito lineal
en este caso especial
LWG 316 C++98 en el valor de retorno de la sobrecarga ( 1 ) , no se especificaba
qué valor bool indicaba una inserción exitosa 		el éxito se indica con true

Véase también

(C++11)
construye elemento in situ
(función miembro pública)
(C++11)
construye elementos in situ usando una pista
(función miembro pública)
crea un std::insert_iterator del tipo inferido del argumento
(plantilla de función)