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) (自 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 的副本。

如果 T 不满足 CopyInsertable 到 list 的要求，则行为未定义。

(自 C++11 起)
2) 在 pos 之前插入 value ，可能使用移动语义。
如果 T 不满足 MoveInsertable 到 list 的要求，则行为未定义。
3) 在 pos 前插入 count 个 value 的副本。
若满足以下任意条件，则行为未定义：
(C++11 起)
4) 在 pos 之前插入范围 [ first , last ) 中的元素。

若 InputIt 是整数类型，此重载与重载 (3) 效果相同。

(C++11 前)

仅当 InputIt 满足 LegacyInputIterator 要求时，此重载才参与重载决议。

(C++11 起)
若满足以下任一条件，则行为未定义：
(since C++11)
  • first 或 last 是指向 * this 的迭代器。
5) 在 pos 之前插入来自初始化列表 ilist 的元素。
等价于 insert ( pos, ilist. begin ( ) , ilist. end ( ) ) 。


不会使任何迭代器或引用失效。

目录

参数

pos - 插入内容前的迭代器位置
value - 要插入的元素值
count - 要插入的元素数量
first, last - 定义要插入元素范围的迭代器对
ilist - std::initializer_list 从中插入值

返回值

1,2) 指向插入的 value 的迭代器。
3-5) 指向首个被插入元素的迭代器，若未插入任何元素则返回 pos 。

复杂度

与插入元素数量呈线性关系。

异常

若因任何原因抛出异常，这些函数将不产生任何效果（ 强异常安全保证 ）。

示例

运行此代码 
#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++标准。

缺陷报告 适用范围 发布时行为 正确行为
LWG 149 C++98 重载版本 ( 3 ) 和 ( 4 ) 无返回值 返回迭代器

参见

(C++11)
原地构造元素
(公开成员函数)
在起始处插入元素
(公开成员函数)
在末尾添加元素
(公开成员函数)
创建从参数推断类型的 std::insert_iterator
(函数模板)