Namespaces
Variants

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

From cppreference.net

C++
Containers library
std::deque
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) (C++26以降 constexpr)
iterator insert ( const_iterator pos, T && value ) ;
(2) (C++11以降)
(C++26以降 constexpr)
iterator insert ( const_iterator pos,
size_type count, const T & value ) ;
(3) (C++26以降 constexpr)
template < class InputIt >
iterator insert ( const_iterator pos, InputIt first, InputIt last ) ;
(4) (C++26以降 constexpr)
iterator insert ( const_iterator pos, std:: initializer_list < T > ilist ) ;
(5) (C++11以降)
(C++26以降 constexpr)

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

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 ( ) ) 。


すべてのイテレータ（ end() イテレータを含む）は無効化されます。参照も同様に無効化されますが、 pos == begin() または pos == end() の場合を除きます。これらのケースでは参照は無効化されません。

目次

翻訳のポイント： - 「Contents」を「目次」に翻訳 - C++関連の専門用語（Parameters, Return value, Complexity, Exceptions, Example, Defect reports, See also）は原文のまま保持 - HTMLタグ、属性、クラス名、ID、リンク先は一切変更せず - 数値と書式設定は完全に保持 - 技術文書としての正確性と専門性を維持

パラメータ

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

戻り値

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

計算量

挿入される要素の数に加えて、 std:: min ( std:: distance ( begin ( ) , pos ) , std:: distance ( pos, end ( ) ) ) の線形時間。

例外

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

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

この関数は効果を持ちません（強い例外保証）。

いずれかの端に単一要素を挿入する際に例外がスローされた場合、この関数は何も効果を持たない（強い例外保証）。そうでない場合、非- CopyInsertable T のムーブコンストラクタによって例外がスローされた場合、その効果は未規定である。

(C++11以降)

例

このコードを実行 
#include <iostream>
#include <iterator>
#include <string_view>
#include <deque>
namespace stq
{
    void println(std::string_view rem, const std::deque<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::deque<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をbeginにリセット:
    pos = c1.begin();
    std::deque<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 計算量は単一要素の挿入に対して
のみ規定されていた 		複数要素の挿入に対しても
規定する

関連項目

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