set::insert
Inserta un elemento o un intervalo de elementos en un conjunto.
// (1) single element pair<iterator, bool> insert( const value_type& Val ); // (2) single element, perfect forwarded template<class ValTy> pair<iterator, bool> insert( ValTy&& Val ); // (3) single element with hint iterator insert( const_iterator Where, const value_type& Val ); // (4) single element, perfect forwarded, with hint template<class ValTy> iterator insert( const_iterator Where, ValTy&& Val ); // (5) range template<class InputIterator> void insert( InputIterator First, InputIterator Last ); // (6) initializer list void insert( initializer_list<value_type> IList );
Parámetros
Parámetro |
Descripción |
Val |
Valor de un elemento que se va a insertar en el conjunto a menos que ya contenga un elemento cuyo valor se ordena de forma equivalente. |
Where |
Lugar donde se va a iniciar la búsqueda del punto de inserción correcto. (Si ese punto precede inmediatamente a Where, la inserción se puede realizar en tiempo constante amortizado en lugar de en tiempo logarítmico). |
ValTy |
Parámetro de plantilla que especifica el tipo de argumento que el conjunto puede utilizar para construir un elemento de value_type y realiza un reenvío directo de Val como argumento. |
First |
Posición del primer elemento que se va a copiar. |
Last |
Posición situada más allá del último elemento que se va a copiar. |
InputIterator |
Argumento de la función de plantilla que cumple los requisitos de un iterador de entrada que apunta a elementos de un tipo que se puede utilizar para crear objetos value_type. |
IList |
initializer_list de la que se van a copiar los elementos. |
Valor devuelto
Las funciones miembro de un solo elemento, (1) y (2), devuelven un pair cuyo componente bool es true si se realizó una inserción y false si el conjunto ya contenía un elemento de valor equivalente en la ordenación. El componente de iterador del par de valor devuelto apunta al elemento recién insertado si el componente bool es true, o al elemento existente si el componente bool es false.
Las funciones miembro un solo elemento con sugerencia, (3) y (4), devuelven un iterador que apunta a la posición donde se insertó el nuevo elemento en el conjunto, o bien, si ya existe un elemento con una clave equivalente, al elemento existente.
Comentarios
Esta función no invalida ningún iterador, puntero o referencia.
Durante la inserción de un solo elemento, si se produce una excepción, no se modifica el estado del contenedor. Durante la inserción de varios elementos, si se produce una excepción, el contenedor se deja en un estado sin especificar pero válido.
Para tener acceso al componente de iterador de un pair pr devuelto por la función miembro de un único elemento, utilice pr.first; para desreferenciar el iterador dentro del par devuelto, utilice *pr.first, especificando un elemento. Para tener acceso al componente bool, utilice pr.second. Para obtener un ejemplo, vea el código de ejemplo que se muestra más adelante en este artículo.
El value_type de un contenedor es un typedef que pertenece al contenedor y, para un conjunto, set<V>::value_type es de tipo const V.
La función miembro de intervalo (5) inserta la secuencia de valores de elemento en un conjunto que corresponde a cada elemento direccionado por un iterador en el intervalo [First, Last); por tanto, Last no se inserta. La función miembro de contenedor end() hace referencia a la posición situada justo después del último elemento del contenedor; por ejemplo, la instrucción s.insert(v.begin(), v.end()); intenta insertar todos los elementos de v en s. Solo se insertan los elementos que tienen valores únicos en el intervalo; se omiten los duplicados. Para observar qué elementos se rechazan, utilice las versiones de un solo elemento de insert.
La función miembro de lista de inicializadores (6) utiliza una initializer_list para copiar los elementos al conjunto.
Para la inserción de un elemento construido en contexto (es decir, no se realiza ninguna operación de copia o movimiento), vea set::emplace y set::emplace_hint.
Ejemplo
// set_insert.cpp
// compile with: /EHsc
#include <set>
#include <iostream>
#include <string>
#include <vector>
using namespace std;
template <typename S> void print(const S& s) {
cout << s.size() << " elements: ";
for (const auto& p : s) {
cout << "(" << p << ") ";
}
cout << endl;
}
int main()
{
// insert single values
set<int> s1;
// call insert(const value_type&) version
s1.insert({ 1, 10 });
// call insert(ValTy&&) version
s1.insert(20);
cout << "The original set values of s1 are:" << endl;
print(s1);
// intentionally attempt a duplicate, single element
auto ret = s1.insert(1);
if (!ret.second){
auto elem = *ret.first;
cout << "Insert failed, element with value 1 already exists."
<< endl << " The existing element is (" << elem << ")"
<< endl;
}
else{
cout << "The modified set values of s1 are:" << endl;
print(s1);
}
cout << endl;
// single element, with hint
s1.insert(s1.end(), 30);
cout << "The modified set values of s1 are:" << endl;
print(s1);
cout << endl;
// The templatized version inserting a jumbled range
set<int> s2;
vector<int> v;
v.push_back(43);
v.push_back(294);
v.push_back(41);
v.push_back(330);
v.push_back(42);
v.push_back(45);
cout << "Inserting the following vector data into s2:" << endl;
print(v);
s2.insert(v.begin(), v.end());
cout << "The modified set values of s2 are:" << endl;
print(s2);
cout << endl;
// The templatized versions move-constructing elements
set<string> s3;
string str1("blue"), str2("green");
// single element
s3.insert(move(str1));
cout << "After the first move insertion, s3 contains:" << endl;
print(s3);
// single element with hint
s3.insert(s3.end(), move(str2));
cout << "After the second move insertion, s3 contains:" << endl;
print(s3);
cout << endl;
set<int> s4;
// Insert the elements from an initializer_list
s4.insert({ 4, 44, 2, 22, 3, 33, 1, 11, 5, 55 });
cout << "After initializer_list insertion, s4 contains:" << endl;
print(s4);
cout << endl;
}
Salida
The original set values of s1 are:
3 elements: (1) (10) (20)
Insert failed, element with value 1 already exists.
The existing element is (1)
The modified set values of s1 are:
4 elements: (1) (10) (20) (30)
Inserting the following vector data into s2:
6 elements: (43) (294) (41) (330) (42) (45)
The modified set values of s2 are:
6 elements: (41) (42) (43) (45) (294) (330)
After the first move insertion, s3 contains:
1 elements: (blue)
After the second move insertion, s3 contains:
2 elements: (blue) (green)
After initializer_list insertion, s4 contains:
10 elements: (1) (2) (3) (4) (5) (11) (22) (33) (44) (55)
Requisitos
Encabezado: <set>
Espacio de nombres: std