Namespaces
Variants

std::map<Key,T,Compare,Allocator>:: insert

From cppreference.net
C++
Containers library
std::map
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)
template < class P >
std:: pair < iterator, bool > insert ( P && value ) ;
(2) (desde C++11)
std:: pair < iterator, bool > insert ( value_type && value ) ;
(3) (desde C++17)
(4)
iterator insert ( iterator pos, const value_type & value ) ;
(hasta C++11)
iterator insert ( const_iterator pos, const value_type & value ) ;
(desde C++11)
template < class P >
iterator insert ( const_iterator pos, P && value ) ;
(5) (desde C++11)
iterator insert ( const_iterator pos, value_type && value ) ;
(6) (desde C++17)
template < class InputIt >
void insert ( InputIt first, InputIt last ) ;
(7)
void insert ( std:: initializer_list < value_type > ilist ) ;
(8) (desde C++11)
insert_return_type insert ( node_type && nh ) ;
(9) (desde C++17)
iterator insert ( const_iterator pos, node_type && nh ) ;
(10) (desde C++17)

Inserta elemento(s) en el contenedor, si el contenedor aún no contiene un elemento con una clave equivalente.

1-3) Inserta value .
La sobrecarga (2) es equivalente a emplace ( std:: forward < P > ( value ) ) y solo participa en la resolución de sobrecarga si std:: is_constructible < value_type, P && > :: value == true .
4-6) Inserta value en la posición más cercana posible a la posición inmediatamente anterior a pos .
La sobrecarga (5) es equivalente a emplace_hint ( pos, std:: forward < P > ( value ) ) y solo participa en la resolución de sobrecarga si std:: is_constructible < value_type, P && > :: value == true .
7) Inserta elementos del rango [ first , last ) . Si múltiples elementos en el rango tienen claves que son equivalentes, no está especificado qué elemento se inserta (pendiente de LWG2844 ).
8) Inserta elementos desde la lista de inicialización ilist . Si múltiples elementos en el rango tienen claves que comparan equivalentes, no está especificado qué elemento se inserta (pendiente de LWG2844 ).
9) 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 ( ) .
10) 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 no contiene ya 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 ( ) .

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 se vuelven 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 de elementos a insertar
ilist - lista de inicializadores de la cual insertar los valores
nh - un manejador de nodo compatible
Requisitos de tipo
-
InputIt debe cumplir con los requisitos de LegacyInputIterator .

Valor de retorno

1-3) 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.
4-6) Un iterador al elemento insertado, o al elemento que impidió la inserción.
7,8) (ninguno)
9) 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 ( ) .
10) Iterador final si nh estaba vacío, iterador apuntando al elemento insertado si la inserción tuvo lugar, e iterador apuntando a un elemento con una clave equivalente a nh. key ( ) si falló.

Excepciones

1-6) Si se lanza una excepción por cualquier operación, la inserción no tiene efecto.
Esta sección está incompleta
Motivo: casos 7-10

Complejidad

1-3) Logarítmico en el tamaño del contenedor, O(log(size())) .
4-6) Amortizado constante si la inserción ocurre en la posición justo después (until C++11) antes (since C++11) pos , logarítmico en el tamaño del contenedor en caso contrario.
7,8) O(N·log(size() + N)) , donde N es el número de elementos a insertar.
9) Logarítmico en el tamaño del contenedor, O(log(size())) .
10) Constante amortizado si la inserción ocurre en la posición justo antes pos , logarítmico en el tamaño del contenedor en caso contrario.

Notas

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

Ejemplo

Ejecutar este código 
#include <iomanip>
#include <iostream>
#include <map>
#include <string>
using namespace std::literals;
template<typename It>
void print_insertion_status(It it, bool success)
{
    std::cout << "Inserción de " << it->first
              << (success ? " succeeded\n" : " falló\n");
}
int main()
{
    std::map<std::string, float> heights;
    // Sobrecarga 3: insertar desde referencia a valor temporal
    const auto [it_hinata, success] = heights.insert({"Hinata"s, 162.8});
    print_insertion_status(it_hinata, success);
    {
        // Sobrecarga 1: insertar desde referencia lvalue
        const auto [it, success2] = heights.insert(*it_hinata);
        print_insertion_status(it, success2);
    }
    {
        // Sobrecarga 2: inserción mediante reenvío a emplace
        const auto [it, success] = heights.insert(std::pair{"Kageyama", 180.6});
        print_insertion_status(it, success);
    }
    {
        // Sobrecarga 6: inserción desde referencia a valor R con sugerencia posicional
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, {"Azumane"s, 184.7});
        print_insertion_status(it, std::size(heights) != n);
    }
    {
        // Sobrecarga 4: inserción desde referencia lvalue con sugerencia posicional
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, *it_hinata);
        print_insertion_status(it, std::size(heights) != n);
    }
    {
        // Sobrecarga 5: inserción mediante reenvío a emplace con sugerencia posicional
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, std::pair{"Tsukishima", 188.3});
        print_insertion_status(it, std::size(heights) != n);
    }
    auto node_hinata = heights.extract(it_hinata);
    std::map<std::string, float> heights2;
    // Sobrecarga 7: inserción desde rango de iteradores
    heights2.insert(std::begin(heights), std::end(heights));
    // Sobrecarga 8: inserción desde initializer_list
    heights2.insert({{"Kozume"s, 169.2}, {"Kuroo", 187.7}});
    // Sobrecarga 9: insertar nodo
    const auto status = heights2.insert(std::move(node_hinata));
    print_insertion_status(status.position, status.insertado);
    node_hinata = heights2.extract(status.position);
    {
        // Sobrecarga 10: insertar nodo con sugerencia posicional
        const std::size_t n = std::size(heights2);
        const auto it = heights2.insert(std::begin(heights2), std::move(node_hinata));
        print_insertion_status(it, std::size(heights2) != n);
    }
    // Imprimir mapa resultante
    std::cout << std::left << '\n';
    for (const auto& [name, height] : heights2)
        std::cout << std::setw(10) << name << " | " << height << "cm\n";
}

Salida: 

Inserción de Hinata exitosa
Inserción de Hinata fallida
Inserción de Kageyama exitosa
Inserción de Azumane exitosa
Inserción de Hinata fallida
Inserción de Tsukishima exitosa
Inserción de Hinata exitosa
Inserción de Hinata exitosa
Azumane    | 184.7cm
Hinata     | 162.8cm
Kageyama   | 180.6cm
Kozume     | 169.2cm
Kuroo      | 187.7cm
Tsukishima | 188.3cm

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 ignorada completamente se requiere que la inserción
sea lo más cercana posible a la
posición justo antes de pos
LWG 264 C++98 la complejidad de la sobrecarga ( 7 ) se requería que fuera 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
LWG 2005 C++11 las sobrecargas ( 2 ) y ( 5 ) estaban descritas deficientemente se mejoró la descripción

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)
(C++17)
inserta un elemento o asigna al elemento actual si la clave ya existe
(función miembro pública)
crea un std::insert_iterator del tipo inferido del argumento
(plantilla de función)