std::vector insert() 方法

自 C++20 起

// prism-push-types:const_iterator,iterator,size_type
// (1) Non const version only
constexpr iterator insert( const_iterator pos, T const& value );

// (2) Non const version only
constexpr iterator insert( const_iterator pos, T&& value );

// (3) Non const version only
constexpr iterator insert( const_iterator pos, size_type count, T const& value );

// (4) Non const version only
template< class InputIt >
constexpr iterator insert( const_iterator pos, InputIt first, InputIt last );

// (5) Non const version only
constexpr iterator insert( const_iterator pos, std::initializer_list<T> ilist );

自 C++11 起

// prism-push-types:const_iterator,iterator,size_type
// (1) Non const version only
iterator insert( const_iterator pos, T const& value );

// (2) Non const version only
iterator insert( const_iterator pos, T&& value );

// (3) Non const version only
iterator insert( const_iterator pos, size_type count, T const& value );

// (4) Non const version only
template< class InputIt >
iterator insert( const_iterator pos, InputIt first, InputIt last );

// (5) Non const version only
iterator insert( const_iterator pos, std::initializer_list<T> ilist );

直到 C++11

// prism-push-types:iterator,size_type
// (1) Non const version only
iterator insert( iterator pos, T const& value );

// (3) Non const version only
void insert( iterator pos, size_type count, T const& value );

// (4) Non const version only
template< class InputIt >
void insert( iterator pos, InputIt first, InputIt last );

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

• (1-2) 在 pos 之前插入 value。

• (3) 在 pos 之前插入 count 个 value 副本。

• (4) 在 pos 之前插入范围 [ first, last ) 中的元素。

  自 C++11 起

  此重载仅在 InputIt 符合 LegacyInputIterator 条件时才参与重载解析，以避免与重载 (3) 产生歧义。

  直到 C++11

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

• (5) 在 pos 之前插入 initializer list ilist 中的元素。

重新分配

如果新的 size() 大于旧的 capacity()，则会导致重新分配。

失效

如果新的 size() 大于 capacity()，则所有迭代器和引用都将失效。

否则，只有插入点之前的迭代器和引用保持有效。

末尾迭代器也会失效。

参数

• pos - 将在其之前插入内容的迭代器。pos 可以是 end() 迭代器
• value - 要插入的元素值
• count - 要插入的元素数量
• first, last - 要插入的元素范围，不能是调用 insert 的容器的迭代器
• ilist - 要从中插入值的初始化列表

类型要求

T 是以下所有要求中容器的元素类型。

• (1) T 必须满足 CopyAssignable 和 CopyInsertable 的要求。

• (2) T 必须满足 MoveAssignable 和 MoveInsertable 的要求。

• (3) T 必须满足 CopyAssignable 和 CopyInsertable 的要求。

• (4,5) T 必须满足 EmplaceConstructible 的要求。

• 自 C++17 起

  (4-5) T 必须满足 Swappable、MoveAssignable、MoveConstructible 和 MoveInsertable 的要求。

  C++17 之前

  (4) 如果 InputIt 满足 LegacyInputIterator：T 必须满足 MoveAssignable 和 MoveInsertable 的要求。

返回值

• (1-2) 指向插入值的迭代器。
• (3) 指向插入的第一个元素的迭代器，如果 count == 0 则为 pos。
• (4) 指向插入的第一个元素的迭代器，如果 first == last 则为 pos。
• (5) 指向插入的第一个元素的迭代器，如果 ilist 为空则为 pos。

复杂度

• (1-2) 常数时间加上 pos 到容器末尾距离的线性时间 - O(std::distance(pos, end()))。
• (3) count 的线性时间加上 pos 到容器末尾距离的线性时间 - O(count + std::distance(pos, end()))。
• (4) std::distance(first, last) 的线性时间加上 pos 到容器末尾距离的线性时间 - O(std::distance(first, last) + std::distance(pos, end()))。
• (5) ilist.size() 的线性时间加上 pos 到容器末尾距离的线性时间 - O(ilist.size() + std::distance(pos, end()))。

异常

如果在末尾插入单个元素时抛出异常，并且 T 是 CopyInsertable 或 std::is_nothrow_move_constructible<T>::value 为 true，则没有副作用（强异常保证）。

示例

Main.cpp

#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` no longer valid, get a new one:
    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