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) 在 pos 之前插入 value ，可能使用移动语义。
若满足以下任一条件，则行为未定义：
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 ( ) ) 。


所有迭代器（包括 end() 迭代器）都会失效。引用同样会失效，除非 pos == begin() 或 pos == end() ，此时引用不会失效。

目录

参数

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 的移动构造函数，
(since C++11)
  • T 的拷贝赋值运算符，
  • T 的移动赋值运算符，
(since C++11)

此函数不产生任何效果（强异常保证）。

如果在任一端插入单个元素时抛出异常，则该函数不产生任何效果（强异常保证）。否则，如果由非 CopyInsertable 类型 T 的移动构造函数抛出异常，其影响是未指定的。

(since 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 重置到起始位置：
    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++ 标准。

缺陷报告 适用范围 发布时行为 正确行为
LWG 149 C++98 重载版本 ( 3 ) 和 ( 4 ) 无返回值 返回迭代器
LWG 247 C++98 仅规定了插入单个元素的复杂度 同时规定了插入多个元素的复杂度

参见

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