multiset::insert

發行項
06/09/2015

將某個元素或元素範圍插入 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 );

參數

參數	描述
Val	要插入至 multiset 的元素值。
Where	要開始搜尋正確的插入點的地方。 (若該點緊接於 Where 之前，則可能會在分攤常數時間插入，而不是對數時間)。
ValTy	範本參數，指定 multiset 可用於建構 value_type 的元素的引數類型，並將 Val 做為引數完美轉送。
First	要複製之第一個元素的位置。
Last	要複製之最一個元素後方的位置。
InputIterator	範本函式引數，符合輸入迭代器的需求，而迭代器會指向可用於建構 value_type 物件之類型的元素。
IList	要從中複製元素的 initializer_list。

傳回值

單一元素插入成員函式 (1) 和 (2)，會將迭代器傳回至在 multiset 中插入新元素的位置。

具有提示的單一元素成員函式 (3) 和 (4)，會傳回迭代器，其指向在 multiset 中插入新元素的位置。

備註

此函式不會使指標或參考無效，但是可能會使容器的所有迭代器無效。

在只插入一個元素的期間，若擲出例外狀況，則不會修改容器的狀態。在插入多個元素期間，若擲出例外狀況，則容器會處於未指定但有效的狀態。

容器的 value_type 是屬於容器的 typedef，而針對 set，multiset<V>::value_type 是類型 const V。

範圍成員函式 (5) 會將元素值序列插入至 multiset，而 multiset 對應至範圍 [First, Last) 中迭代器指定的每個元素；因此不會插入 Last。容器成員函式 end() 是指容器中最後一個元素後方的位置；例如，陳述式 s.insert(v.begin(), v.end()); 會將 v 的所有元素插入至 s。

初始設定式清單成員函式 (6) 使用 initializer_list 將元素複製到 multiset。

如需插入就地建構的元素 (換言之即為未執行複製或移動作業)，請參閱 multiset::emplace 及 multiset::emplace_hint。

範例

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

輸出

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)