Namespaces
Variants

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

From cppreference.net

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

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

1) pos の前に value のコピーを挿入します。

T が list に CopyInsertable でない場合、動作は未定義です。

(C++11以降)
2) value を pos の前に挿入します（ムーブセマンティクスを使用する可能性があります）。
T が MoveInsertable でない場合、動作は未定義です。
3) pos の前に value の count 個のコピーを挿入します。
以下のいずれかの条件が満たされる場合、動作は未定義です：
(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 ( ) ) 。


イテレータおよび参照は無効化されません。

目次

翻訳のポイント： - 「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 を指すイテレータ。

計算量

挿入される要素の数に対して線形。

例外

何らかの理由で例外がスローされた場合、これらの関数は何も効果を持ちません（ strong exception safety guarantee ）。

例

このコードを実行 
#include <iostream>
#include <iterator>
#include <string_view>
#include <list>
namespace stq
{
    void println(std::string_view rem, const std::list<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::list<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::list<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 ) は何も返さなかった イテレータを返す

関連項目

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