map::insert
Insere um elemento ou um intervalo de elementos em um mapa.
// (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 |
Descrição |
Val |
O valor de um elemento a ser inserido no mapa, a menos que ele já contenha um elemento cuja chave seja ordenada de maneira equivalente. |
Where |
O local a partir do qual se começa a procurar pelo ponto de inserção correto. (Se esse ponto preceder imediatamente Where, a inserção poderá ocorrer em um tempo constante amortizado, em vez de no tempo logarítmico.) |
ValTy |
O parâmetro de modelo que especifica o tipo de argumento que o mapa pode usar para construir um elemento de value_type e perfect-forwards Val como um argumento. |
First |
A posição do primeiro elemento a ser copiado. |
Last |
A posição imediatamente após o último elemento a ser copiado. |
InputIterator |
Argumento da função de modelo que atende aos requisitos de um iterador de entrada que aponta para elementos de um tipo que pode ser usado para construir objetos value_type. |
IList |
A initializer_list da qual os elementos serão copiados. |
Valor de retorno
As funções de membro de elemento único, (1) e (2), retornam um par cujo bool componente é verdadeiro se uma inserção tiver sido feita, e falso se o mapa já contiver um elemento cuja chave possua um valor equivalente na ordenação. O componente do iterador do par de valores retornados apontará para o elemento recém-inserido, se o componente bool for verdadeiro, ou para o elemento existente, se o componente bool for falso.
As funções do membro de elemento único com dica, (3) e (4), retornam um iterador que aponta para a posição em que o novo elemento foi inserido no mapa ou, se um elemento com uma chave equivalente já existir, para o elemento existente.
Comentários
Nenhum iterador, ponteiro ou referência é invalidado por essa função.
Durante a inserção de apenas um elemento, se uma exceção for lançada, o estado do contêiner não será modificado. Durante a inserção de vários elementos, se uma exceção for lançada, o contêiner será deixado em um estado não especificado, mas válido.
Para acessar o componente do iterador de um pair pr que é retornado pelas funções do membro de elemento único, consulte pr.first; para desreferenciar o iterador dentro do par retornado, use *pr.first, que oferece um elemento. Para acessar o componente bool, use pr.second. Para obter um exemplo, consulte o código de amostra mais adiante neste artigo.
O value_type de um contêiner é um typedef que pertence ao contêiner, e para o mapa, map<K, V>::value_type é pair<const K, V>. O valor de um elemento é um par ordenado no qual o primeiro componente é igual ao valor chave e o segundo componente é igual ao valor dos dados do elemento.
A função do membro de intervalo (5) insere a sequência de valores de elemento em um mapa que corresponde a cada elemento tratado por um iterador no intervalo [First, Last); portanto, Last não é inserido. A função de membro do contêiner end() faz referência à posição imediatamente após o último elemento no contêiner; por exemplo, a instrução m.insert(v.begin(), v.end()); tenta inserir todos os elementos de v em m. Apenas elementos com valores únicos no intervalo são inseridos; as duplicatas são ignoradas. Para observar quais elementos são rejeitados, use as versões de elemento único de insert.
A função do membro da lista do inicializador (6) usa um initializer_list para copiar elementos em um mapa.
Para inserir um elemento construído no lugar (ou seja, sem a realização de operação de cópia ou movimentação), consulte map::emplace e map::emplace_hint.
Exemplo
// 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;
}
Saída
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
Cabeçalho: <map>
Namespace: std