Namespaces
Variants

std::vector<T,Allocator>:: insert

From cppreference.net

C++
Containers library
std::vector
Member types
Member functions
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
Deduction guides (C++17)
iterator insert ( const_iterator pos, const T & value ) ;
(1) (constexpr since C++20)
iterator insert ( const_iterator pos, T && value ) ;
(2) (since C++11)
(constexpr since C++20)
iterator insert ( const_iterator pos,
size_type count, const T & value ) ;
(3) (constexpr since C++20)
template < class InputIt >
iterator insert ( const_iterator pos, InputIt first, InputIt last ) ;
(4) (constexpr since C++20)
iterator insert ( const_iterator pos, std:: initializer_list < T > ilist ) ;
(5) (since C++11)
(constexpr since C++20)

コンテナの指定された位置に要素を挿入します。

1) pos の前に value のコピーを挿入します。
以下のいずれかの条件が満たされる場合、動作は未定義です：
(C++11以降)
2) value を pos の前に挿入します。ムーブセマンティクスを使用する可能性があります。
以下のいずれかの条件が満たされる場合、動作は未定義です：
3) count 個の value のコピーを pos の前に挿入します。
以下のいずれかの条件が満たされる場合、動作は未定義です：
(C++11以降)
4) 範囲 [ first , last ) から要素を pos の前に挿入します。

このオーバーロードは、 InputIt が整数型の場合、オーバーロード (3) と同じ効果を持ちます。

(C++11以前)

このオーバーロードは、 InputIt が LegacyInputIterator の要件を満たす場合にのみ、オーバーロード解決に参加します。

(C++11以降)
以下のいずれかの条件が満たされる場合、動作は未定義です：
(C++11以降)
  • first または last が * this へのイテレータである場合。
5) 初期化子リストから要素を挿入 ilist を pos の前に挿入します。
次と同等： insert ( pos, ilist. begin ( ) , ilist. end ( ) ) 。


操作後に新しい size() が古い capacity() を超える場合、再割り当てが発生し、その場合すべてのイテレータ（ end() イテレータを含む）と要素へのすべての参照が無効化されます。それ以外の場合、挿入ポイントより前のイテレータと参照のみが有効なままです。

目次

パラメータ

pos - コンテンツが挿入される前のイテレータ
value - 挿入する要素の値
count - 挿入する要素の数
first, last - 挿入する要素の 範囲 を定義するイテレータのペア
ilist - std::initializer_list から値を挿入

戻り値

1,2) 挿入された value を指すイテレータ。
3-5) 挿入された最初の要素を指すイテレータ、または要素が挿入されなかった場合は pos を指すイテレータ。

計算量

再割り当てが発生する場合、挿入後の vector の要素数に対して線形時間。 それ以外の場合、挿入された要素数に加えて std:: distance ( pos, end ( ) ) の線形時間。

例外

例外が以下のもの以外によってスローされた場合

  • T のコピーコンストラクタ,
  • T のムーブコンストラクタ、
(C++11以降)
  • T のコピー代入演算子、
  • T のムーブ代入演算子、
(C++11以降)
  • any InputIt operation,

これらの関数は効果を持ちません（ strong exception safety guarantee ）。

末尾への単一要素挿入時に例外がスローされ、かつ T が CopyInsertable であるか、 std:: is_nothrow_move_constructible < T > :: value が true である場合、この関数は何も効果を持たない（強い例外保証）。それ以外の場合、非 CopyInsertable T のムーブコンストラクタによって例外がスローされた場合、その効果は未規定である。

(C++11以降)

例

このコードを実行 
#include <iostream>
#include <iterator>
#include <string_view>
#include <vector>
namespace stq
{
    void println(std::string_view rem, const std::vector<int>& container)
    {
        std::cout << rem.substr(0, rem.size() - 2) << '[';
        bool first{true};
        for (const int x : container)
            std::cout << (first ? first = false, "" : ", ") << x;
        std::cout << "]\n";
    }
}
int main()
{
    std::vector<int> c1(3, 100);
    stq::println("1. {}", c1);
    auto pos = c1.begin();
    pos = c1.insert(pos, 200); // オーバーロード (1)
    stq::println("2. {}", c1);
    c1.insert(pos, 2, 300); // オーバーロード (3)
    stq::println("3. {}", c1);
    // posは無効になったため、新しいものを取得:
    pos = c1.begin();
    std::vector<int> c2(2, 400);
    c1.insert(std::next(pos, 2), c2.begin(), c2.end()); // オーバーロード (4)
    stq::println("4. {}", c1);
    int arr[] = {501, 502, 503};
    c1.insert(c1.begin(), arr, arr + std::size(arr)); // オーバーロード (4)
    stq::println("5. {}", c1);
    c1.insert(c1.end(), {601, 602, 603}); // オーバーロード (5)
    stq::println("6. {}", c1);
}

出力: 

1. [100, 100, 100]
2. [200, 100, 100, 100]
3. [300, 300, 200, 100, 100, 100]
4. [300, 300, 400, 400, 200, 100, 100, 100]
5. [501, 502, 503, 300, 300, 400, 400, 200, 100, 100, 100]
6. [501, 502, 503, 300, 300, 400, 400, 200, 100, 100, 100, 601, 602, 603]

欠陥報告

以下の動作変更の欠陥報告書は、以前に公開されたC++規格に対して遡及的に適用されました。

DR 適用バージョン 公開時の仕様 修正後の仕様
LWG 149 C++98 オーバーロード ( 3 ) と ( 4 ) は何も返さなかった イテレータを返す
LWG 247 C++98 計算量の規定がオーバーロード ( 3 ) のみだった 全オーバーロードで規定
LWG 406 C++98 強い例外保証が
InputIt 操作で例外が発生した場合にも適用された 		この場合の保証はなし

関連項目

(C++11)
要素をその場で構築する
(公開メンバ関数)
末尾に要素を追加する
(公開メンバ関数)
引数から推論された型の std::insert_iterator を作成する
(関数テンプレート)