命名空间
变体
操作

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

来自 cppreference.com
< cpp‎ | container‎ | list
 
 
 
 
iterator insert( const_iterator pos, const T& value );
(1)
iterator insert( const_iterator pos, T&& value );
(2) (自 C++11 起)
iterator insert( const_iterator pos,
                 size_type count, const T& value );
(3)
template< class InputIt >
iterator insert( const_iterator pos, InputIt first, InputIt last );
(4)
iterator insert( const_iterator pos, std::initializer_list<T> ilist );
(5) (自 C++11 起)

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

1)pos 之前插入 value 的副本。
2)pos 之前插入 value,可能使用移动语义。
3)pos 之前插入 countvalue 的副本。
4)pos 之前插入范围 [firstlast) 中的元素。

如果 InputIt 是一个整数类型,此重载的效果与重载 (3) 相同。

(直到 C++11)

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

(自 C++11 起)
如果 firstlast 是指向 *this 的迭代器,则行为未定义。
5)pos 之前插入来自初始化列表 ilist 的元素。

不会使任何迭代器或引用失效。

内容

[编辑] 参数

pos - 在它之前插入内容的迭代器(pos 可以是 end() 迭代器)
value - 要插入的元素值
count - 要插入的元素数量
first, last - 要插入的元素范围,不能是调用 insert 的容器的迭代器
ilist - std::initializer_list,从中插入值
类型要求
-
T 必须满足 CopyInsertable 的要求才能使用重载 (1)。
-
T 必须满足 MoveInsertable 的要求才能使用重载 (2)。
-
T 必须满足 CopyAssignableCopyInsertable 的要求才能使用重载 (3)。
-
T 必须满足 EmplaceConstructible 的要求才能使用重载 (4,5)。


[编辑] 返回值

1,2) 指向插入的 value 的迭代器。
3) 指向插入的第一个元素的迭代器,或者如果 count == 0,则指向 pos
4) 指向插入的第一个元素的迭代器,或者如果 first == last,则指向 pos
5) 指向插入的第一个元素的迭代器,或者如果 ilist 为空,则指向 pos

[编辑] 复杂度

1,2) 常量。
3) 线性于 count
4) 线性于 std::distance(first, last)
5) 线性于 ilist.size()

[编辑] 异常

如果由于任何原因抛出异常,这些函数将没有效果(强异常安全保证)。

示例

#include <iostream>
#include <iterator>
#include <string_view>
#include <list>
 
namespace stq {
void println(std::string_view rem, const std::list<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::list<int> c1(3, 100);
    stq::println("1. {}", c1);
 
    auto pos = c1.begin();
    pos = c1.insert(pos, 200); // overload (1)
    stq::println("2. {}", c1);
 
    c1.insert(pos, 2, 300); // overload (3)
    stq::println("3. {}", c1);
 
    // reset pos to the begin:
    pos = c1.begin();
 
    std::list<int> c2(2, 400);
    c1.insert(std::next(pos, 2), c2.begin(), c2.end()); // overload (4)
    stq::println("4. {}", c1);
 
    int arr[] = {501, 502, 503};
    c1.insert(c1.begin(), arr, arr + std::size(arr)); // overload (4)
    stq::println("5. {}", c1);
 
    c1.insert(c1.end(), {601, 602, 603}); // overload (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++ 标准。

DR 应用于 已发布的行为 正确行为
LWG 149 C++98 重载 (3)(4) 没有返回任何内容 返回一个迭代器

[编辑] 另请参见

(C++11)
在原地构造元素
(公共成员函数) [编辑]
在开头插入元素
(公共成员函数) [编辑]
在结尾添加元素
(公共成员函数) [编辑]
创建一个 std::insert_iterator,类型由参数推断
(函数模板) [编辑]