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

< cpp‎ | container‎ | vector

| (1) |
iterator insert( iterator pos, const T& value ); |  | (C++11 前)
iterator insert( const_iterator pos, const T& value ); |  | (C++11 起) (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) |
void insert( iterator pos, size_type count, const T& value ); |  | (C++11 前)
iterator insert( const_iterator pos, size_type count, const T& value ); |  | (C++11 起) (C++20 前)
constexpr iterator insert( const_iterator pos, size_type count, const T& value ); |  | (C++20 起)
| (4) |
template< class InputIt > void insert( iterator pos, InputIt first, InputIt last); |  | (C++11 前)
template< class InputIt > iterator insert( const_iterator pos, InputIt first, InputIt last ); |  | (C++11 起) (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() ，则所有迭代器和引用都被非法化。否则，仅在插入点前的迭代器和引用保持合法。尾后迭代器亦被非法化。

### 参数

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 为可复制插入 (CopyInsertable) 或 std::is_nothrow_move_constructible<T>::value 为 true ，则无效果（强异常保证）。

### 示例

    #include <iostream>
    #include <vector>

    void print_vec(const std::vector<int>& vec)
    {
        for (auto x: vec) {
             std::cout << ' ' << x;
        }
        std::cout << '\n';
    }

    int main ()
    {
        std::vector<int> vec(3,100);
        print_vec(vec);

        auto it = vec.begin();
        it = vec.insert(it, 200);
        print_vec(vec);

        vec.insert(it,2,300);
        print_vec(vec);

        // "it" 不再合法，获取新值：
        it = vec.begin();

        std::vector<int> vec2(2,400);
        vec.insert(it+2, vec2.begin(), vec2.end());
        print_vec(vec);

        int arr[] = { 501,502,503 };
        vec.insert(vec.begin(), arr, arr+3);
        print_vec(vec);
    }

输出：

    100 100 100
    200 100 100 100
    300 300 200 100 100 100
    300 300 400 400 200 100 100 100
    501 502 503 300 300 400 400 200 100 100 100

### 参阅

emplace (C++11) | 原位构造元素 (公开成员函数)
push_back | 将元素添加到容器末尾 (公开成员函数)