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) (自 C++20 起为 constexpr)
iterator insert ( const_iterator pos, T && value ) ;
(2) (自 C++11 起)
(自 C++20 起为 constexpr)
iterator insert ( const_iterator pos,
size_type count, const T & value ) ;
(3) (自 C++20 起为 constexpr)
template < class InputIt >
iterator insert ( const_iterator pos, InputIt first, InputIt last ) ;
(4) (自 C++20 起为 constexpr)
iterator insert ( const_iterator pos, std:: initializer_list < T > ilist ) ;
(5) (自 C++11 起)
(自 C++20 起为 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 起)
若满足以下任意条件，则行为未定义：
(C++11 起)
  • first 或 last 是指向 * this 的迭代器。
5) 在 pos 之前插入来自初始化列表 ilist 的元素。
等价于 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 的移动构造函数，
(since C++11)
  • T 的拷贝赋值运算符，
  • T 的移动赋值运算符，
(since C++11)
  • 任何 InputIt 操作，

这些函数没有任何效果（ 强异常安全保证 ）。

若在末端插入单个元素时抛出异常，且 T 可被复制插入到 * this 中，或 std:: is_nothrow_move_constructible < T > :: value 为 true ，则此函数无任何效果（强异常保证）。否则，若非 CopyInsertable 类型 T 的移动构造函数抛出异常，则效果未指定。

(since 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++标准。

缺陷报告 适用标准 发布时行为 正确行为
LWG 149 C++98 重载版本 ( 3 ) 和 ( 4 ) 无返回值 返回迭代器
LWG 247 C++98 仅对重载版本 ( 3 ) 指定了复杂度 对所有重载版本均指定复杂度
LWG 406 C++98 强异常保证同样适用于
InputIt 操作抛出异常的情况 		此情况下不提供保证

参见

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