map::insert
Inserta un elemento o un intervalo de elementos en una asignación.
// (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 la asignación a menos que ya contenga un elemento cuya clave 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 la asignación 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 la asignación ya contenía un elemento cuya clave tenía un 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 de un solo elemento con sugerencia, (3) y (4), devuelven un iterador que apunta a la posición donde se insertó el nuevo elemento en la asignación o, 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 las funciones miembro de un solo elemento, use pr.first; para desreferenciar el iterador dentro del par devuelto, use *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 objeto value_type de un contenedor es un typedef que pertenece al contenedor y, para una asignación, map<K, V>::value_type es de tipo pair<const K, V>. El valor de un elemento es un par ordenado en el que el primer componente es igual al valor de clave y el segundo componente es igual al valor de datos del elemento.
La función miembro de intervalo (5) inserta la secuencia de valores de elemento en una asignación que corresponde a cada elemento direccionado por un iterador en el intervalo [First, Last); por lo 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 m.insert(v.begin(), v.end()); intenta insertar todos los elementos de v en m. 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) usa una initializer_list para copiar elementos en la asignación.
Para la inserción de un elemento construido en contexto (es decir, no se realiza ninguna operación de copia o movimiento), vea map::emplace y map::emplace_hint.
Ejemplo
// map_insert.cpp
// compile with: /EHsc
#include <map>
#include <iostream>
#include <string>
#include <vector>
#include <utility> // make_pair()
using namespace std;
template <typename M> void print(const M& m) {
cout << m.size() << " elements: ";
for (const auto& p : m) {
cout << "(" << p.first << ", " << p.second << ") ";
}
cout << endl;
}
int main()
{
// insert single values
map<int, int> m1;
// call insert(const value_type&) version
m1.insert({ 1, 10 });
// call insert(ValTy&&) version
m1.insert(make_pair(2, 20));
cout << "The original key and mapped values of m1 are:" << endl;
print(m1);
// intentionally attempt a duplicate, single element
auto ret = m1.insert(make_pair(1, 111));
if (!ret.second){
auto pr = *ret.first;
cout << "Insert failed, element with key value 1 already exists."
<< endl << " The existing element is (" << pr.first << ", " << pr.second << ")"
<< endl;
}
else{
cout << "The modified key and mapped values of m1 are:" << endl;
print(m1);
}
cout << endl;
// single element, with hint
m1.insert(m1.end(), make_pair(3, 30));
cout << "The modified key and mapped values of m1 are:" << endl;
print(m1);
cout << endl;
// The templatized version inserting a jumbled range
map<int, int> m2;
vector<pair<int, int>> v;
v.push_back(make_pair(43, 294));
v.push_back(make_pair(41, 262));
v.push_back(make_pair(45, 330));
v.push_back(make_pair(42, 277));
v.push_back(make_pair(44, 311));
cout << "Inserting the following vector data into m2:" << endl;
print(v);
m2.insert(v.begin(), v.end());
cout << "The modified key and mapped values of m2 are:" << endl;
print(m2);
cout << endl;
// The templatized versions move-constructing elements
map<int, string> m3;
pair<int, string> ip1(475, "blue"), ip2(510, "green");
// single element
m3.insert(move(ip1));
cout << "After the first move insertion, m3 contains:" << endl;
print(m3);
// single element with hint
m3.insert(m3.end(), move(ip2));
cout << "After the second move insertion, m3 contains:" << endl;
print(m3);
cout << endl;
map<int, int> m4;
// Insert the elements from an initializer_list
m4.insert({ { 4, 44 }, { 2, 22 }, { 3, 33 }, { 1, 11 }, { 5, 55 } });
cout << "After initializer_list insertion, m4 contains:" << endl;
print(m4);
cout << endl;
}
Salida
The original key and mapped values of m1 are:
2 elements: (1, 10) (2, 20)
Insert failed, element with key value 1 already exists.
The existing element is (1, 10)
The modified key and mapped values of m1 are:
3 elements: (1, 10) (2, 20) (3, 30)
Inserting the following vector data into m2:
5 elements: (43, 294) (41, 262) (45, 330) (42, 277) (44, 311)
The modified key and mapped values of m2 are:
5 elements: (41, 262) (42, 277) (43, 294) (44, 311) (45, 330)
After the first move insertion, m3 contains:
1 elements: (475, blue)
After the second move insertion, m3 contains:
2 elements: (475, blue) (510, green)
After initializer_list insertion, m4 contains:
5 elements: (1, 11) (2, 22) (3, 33) (4, 44) (5, 55)
Requisitos
Encabezado: <map>
Espacio de nombres: std