multiset::insert

Articolo
06/09/2015

Inserisce un elemento o un intervallo di elementi in un multiset.

// (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 );

Parametri

Parametro	Descrizione
Val	Valore di un elemento da inserire nel multiset.
Where	Posizione in cui iniziare a cercare il punto di inserimento corretto. Se tale punto è immediatamente seguito da Where, l'inserimento può avvenire in tempo costante ammortizzato anziché in tempo logaritmico.
ValTy	Parametro di modello che specifica il tipo di argomenti che può essere usato dal multiset per costruire un elemento di value_type e che esegue l'inoltro perfetto di Val come argomento.
First	Posizione del primo elemento da copiare.
Last	Posizione immediatamente dopo l'ultimo elemento da copiare.
InputIterator	Argomento della funzione di modello che soddisfa i requisiti di un iteratore di input che fa riferimento agli elementi di un tipo che possono essere usati per costruire oggetti value_type.
IList	Oggetto initializer_list da cui copiare gli elementi.

Valore restituito

Le funzioni membro di inserimento a elemento singolo, (1) e (2), restituiscono un iteratore alla posizione in cui il nuovo elemento è stato inserito nel multiset.

Le funzioni membro a elemento singolo con suggerimento, (3) e (4), restituiscono un iteratore che punta alla posizione in cui il nuovo elemento è stato inserito nel multiset.

Note

Questa funzione non invalida alcun puntatore o riferimento, ma potrebbe invalidare tutti gli iteratori per il contenitore.

Se viene generata un'eccezione durante l'inserimento di un solo elemento, ma l'eccezione non si manifesta nella funzione hash del contenitore, lo stato del contenitore non verrà modificato. Se viene generata un'eccezione durante l'inserimento di più elementi, il contenitore viene lasciato in uno stato non specificato ma comunque valido.

Il value_type di un contenitore è un typedef appartenente al contenitore e, per il set, multiset<V>::value_type è il tipo const V.

La funzione membro di intervallo (5) inserisce la sequenza di valori di elemento in un multiset che corrisponde a ogni elemento interessato da un iteratore nell'intervallo [First, Last). Non viene quindi inserito Last. La funzione membro di contenitore end() fa riferimento alla posizione immediatamente dopo l'ultimo elemento nel contenitore. L'istruzione s.insert(v.begin(), v.end());, ad esempio, inserisce tutti gli elementi di v in s.

La funzione membro di elenco dell'inizializzatore (6) usa un initializer_list per copiare gli elementi nel multiset.

Per l'inserimento di un elemento creato sul posto, ovvero senza esecuzione di operazioni di copia o spostamento, vedere multiset::emplace e multiset::emplace_hint.

Esempio

// multiset_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 
    multiset<int> s1;
    // call insert(const value_type&) version
    s1.insert({ 1, 10 });
    // call insert(ValTy&&) version 
    s1.insert(20);

    cout << "The original multiset values of s1 are:" << endl;
    print(s1);

    // intentionally attempt a duplicate, single element
    s1.insert(1);
    cout << "The modified multiset values of s1 are:" << endl;
    print(s1);
    cout << endl;

    // single element, with hint
    s1.insert(s1.end(), 30);
    cout << "The modified multiset values of s1 are:" << endl;
    print(s1);
    cout << endl;


    // The templatized version inserting a jumbled range
    multiset<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 multiset values of s2 are:" << endl;
    print(s2);
    cout << endl;

    // The templatized versions move-constructing elements
    multiset<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;

    multiset<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;
}

Output

The original multiset values of s1 are:
3 elements: (1) (10) (20)
The modified multiset values of s1 are:
4 elements: (1) (1) (10) (20)

The modified multiset values of s1 are:
5 elements: (1) (1) (10) (20) (30)

Inserting the following vector data into s2:
6 elements: (43) (294) (41) (330) (42) (45)
The modified multiset 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)