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

来自cppreference.com
< cpp‎ | container‎ | vector

 
C++
 
容器库
 
std::vector
成员类型
成员类型
(C++23)
元素访问
迭代器
(C++11)
(C++11)
(C++11)
(C++11)
容量
(DR*)
修改器
vector::insert
(C++11)
(C++23)
(C++11)
(C++23)
非成员函数
(C++20)(C++20)
(C++20 前)(C++20 前)(C++20 前)(C++20 前)(C++20 前)(C++20)
推导指引(C++17)
 
(1)
iterator insert( const_iterator pos, const T& value );
 (C++20 前)
constexpr iterator insert( const_iterator pos, const T& value );
 (C++20 起)
(2)
iterator insert( const_iterator pos, T&& value );
 (C++11 起)
(C++20 前)
constexpr iterator insert( const_iterator pos, T&& value );
 (C++20 起)
(3)
iterator insert( const_iterator pos, size_type count, const T& value );
 (C++20 前)
constexpr iterator
    insert( const_iterator pos, size_type count, const T& value );
 (C++20 起)
(4)
template< class InputIt >
iterator insert( const_iterator pos, InputIt first, InputIt last );
 (C++20 前)
template< class InputIt >
constexpr iterator insert( const_iterator pos, InputIt first, InputIt last );
 (C++20 起)
(5)
iterator insert( const_iterator pos, std::initializer_list<T> ilist );
 (C++11 起)
(C++20 前)
constexpr iterator insert( const_iterator pos,
                           std::initializer_list<T> ilist );
 (C++20 起)

插入元素到容器中的指定位置。

1-2) 在 pos 前插入 value。
3) 在 pos 前插入 value 的 count 个副本。
4) 在 pos 前插入来自范围 [first, last) 的元素。

如果 InputIt 是整数类型，那么此重载与重载 (3) 的效果相同。

(C++11 前)

此重载只有在InputIt 足以为老式输入迭代器 (LegacyInputIterator) 时才会参与重载决议，以避免与重载 (3) 有歧义。

(C++11 起)
如果 first 和 last 是指向 *this 中的迭代器，那么行为未定义。
5) 在 pos 前插入来自 initializer_list ilist 的元素。

如果新 size() 大于旧 capacity() 就会导致重分配。 如果新的 size() 大于 capacity()，那么所有迭代器和引用都会失效。否则，只有在插入点前的迭代器和引用会保持有效。end() 迭代器也会失效。

参数

pos - 将内容插入到它前面的迭代器。pos 可以是 end() 迭代器
value - 要插入的元素值
first, last - 要插入的元素范围，不能是指向调用 insert 所用的容器中的迭代器
ilist - 要插入的值来源的 initializer_list
类型要求
-
为使用重载 (1)， T 必须符合可复制赋值 (CopyAssignable) 和 可复制插入 (CopyInsertable) 的要求。
-
为使用重载 (2)， T 必须符合可移动赋值 (MoveAssignable) 和 可移动插入 (MoveInsertable) 的要求。
-
为使用重载 (3)， T 必须符合可复制赋值 (CopyAssignable) 和 可复制插入 (CopyInsertable) 的要求。
-
为使用重载 (4,5)， T 必须符合可就位构造 (EmplaceConstructible) 的要求。
-
为使用重载 (4)， T 必须符合可移动赋值 (MoveAssignable) 和 可移动插入 (MoveInsertable) 的要求。只有在 InputIt 满足老式输入迭代器 (LegacyInputIterator) 但不满足老式向前迭代器 (LegacyForwardIterator) 时才要求。(C++17 前)
-
为使用重载 (4,5)， T 必须符合可交换 (Swappable) 、可移动赋值 (MoveAssignable) 、可移动构造 (MoveConstructible) 和 可移动插入 (MoveInsertable) 的要求。(C++17 起)

返回值

1-2) 指向被插入 value 的迭代器。
3) 指向首个被插入元素的迭代器，或者在 count == 0 时返回 pos。
4) 指向首个被插入元素的迭代器，或者在 first == last 时返回 pos。
5) 指向首个被插入元素的迭代器，或者在 ilist 为空时返回 pos。

复杂度

1-2) 常数，加上 pos 与容器结尾的距离成线性。
3) 与 count 成线性，加上 pos 与容器结尾的距离成线性。
4) 与 std::distance(first, last) 成线性，加上 pos 与容器结尾的距离成线性。
5) 与 ilist.size() 成线性，加上 pos 与容器结尾的距离成线性。

异常

如果从以下场合以外抛出异常，那么此函数没有效果（强异常保证）：

  • T 的复制构造函数
  • T 的移动构造函数
(C++11 起)
  • T 的复制赋值运算符
  • T 的赋值运算符
(C++11 起)
  • 任意 InputIt 操作


如果在尾端插入单个元素时抛出异常，且 T 是可复制插入 (CopyInsertable) 的或 std::is_nothrow_move_constructible<T>::value 是 true，那么此函数没有效果（强异常保证）。否则，如果异常从不可复制插入 (CopyInsertable) 的 T 的移动构造函数抛出，那么不会指定此函数的效果。

(C++11 起)

示例

运行此代码
#include <iostream>
#include <iterator>
#include <vector>
 
void print(int id, const std::vector<int>& container)
{
    std::cout << id << ". ";
    for (const int x: container)
        std::cout << x << ' ';
    std::cout << '\n';
}
 
int main ()
{
    std::vector<int> c1(3, 100);
    print(1, c1);
 
    auto it = c1.begin();
    it = c1.insert(it, 200);
    print(2, c1);
 
    c1.insert(it, 2, 300);
    print(3, c1);
 
    // it 已经失效，提供新迭代器
    it = c1.begin();
 
    std::vector<int> c2(2, 400);
    c1.insert(std::next(it, 2), c2.begin(), c2.end());
    print(4, c1);
 
    int arr[] = {501, 502, 503};
    c1.insert(c1.begin(), arr, arr + std::size(arr));
    print(5, c1);
 
    c1.insert(c1.end(), {601, 602, 603});
    print(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
(函数模板)
来自“https://zh.cppreference.com/mwiki/index.php?title=cpp/container/vector/insert&oldid=46553”