Namespaces
Variants

std:: list

From cppreference.net
C++
Containers library
std::list
Member functions
Non-member functions
(until C++20) (until C++20) (until C++20) (until C++20) (until C++20)
Deduction guides (C++17)
定义于头文件 <list>
template <

class T,
class Allocator = std:: allocator < T >

> class list ;
(1)
namespace pmr {

template < class T >
using list = std :: list < T, std:: pmr :: polymorphic_allocator < T >> ;

}
(2) (C++17 起)

std::list 是一个支持在容器任意位置进行常量时间元素插入和删除的容器。不支持快速随机访问。它通常被实现为双向链表。与 std::forward_list 相比，该容器提供了双向迭代能力，但空间效率较低。

在列表内或跨多个列表添加、移除和移动元素不会使迭代器或引用失效。仅当对应元素被删除时，迭代器才会失效。

std::list 满足 Container 、 AllocatorAwareContainer 、 SequenceContainer 及 ReversibleContainer 的要求。

std::list 的所有成员函数均为 constexpr ：可以在常量表达式的求值过程中创建和使用 std::list 对象。

然而， std::list 对象通常不能是 constexpr ，因为任何动态分配的存储必须在同一常量表达式求值期间释放。

(C++26 起)

目录

模板参数

T - 元素的类型。
T 必须满足 CopyConstructible 的要求。 若 list::operator= 或 list::assign 以 T 实例化，则 T 必须满足 CopyAssignable 的要求。 (C++11 前)
对元素的要求取决于容器实际执行的操作。通常要求元素类型为完整类型并满足 Erasable 的要求，但许多成员函数会施加更严格的要求。 (C++11 起)
(C++17 前)

对元素的要求取决于容器实际执行的操作。通常要求元素类型满足 Erasable 的要求，但许多成员函数会施加更严格的要求。若分配器满足 分配器完整性要求 ，则可以使用不完整元素类型实例化此容器（但非其成员）。

功能测试 宏 值 标准 功能
__cpp_lib_incomplete_container_elements 201505L (C++17) 最小不完整类型支持
(C++17 起)

分配器 - 用于获取/释放内存及构造/销毁其中元素的分配器。该类型必须满足 Allocator 的要求。 若 (C++20 前) 若 (C++20 起) Allocator::value_type 与 T 不同，则 行为未定义 程序非良构 。

成员类型

成员类型 定义
value_type T
allocator_type Allocator
size_type 无符号整数类型（通常为 std::size_t ）
difference_type 有符号整数类型（通常为 std::ptrdiff_t ）
reference value_type &
const_reference const value_type &
pointer

Allocator::pointer

(C++11 前)

std:: allocator_traits < Allocator > :: pointer

(C++11 起)
const_pointer

Allocator::const_pointer

(C++11 前)

std:: allocator_traits < Allocator > :: const_pointer

(C++11 起)
iterator LegacyBidirectionalIterator 和 ConstexprIterator (C++26 起) 指向 value_type
const_iterator LegacyBidirectionalIterator 和 ConstexprIterator (C++26 起) 指向 const value_type
reverse_iterator std:: reverse_iterator < iterator >
const_reverse_iterator std:: reverse_iterator < const_iterator >

成员函数

构造 list
(公开成员函数)
析构 list
(公开成员函数)
为容器赋值
（公开成员函数）
为容器赋值
（公开成员函数）
(C++23)
将值范围赋值给容器
(公开成员函数)
返回关联的分配器
（公开成员函数）
元素访问
访问首元素
（公开成员函数）
访问最后一个元素
（公开成员函数）
迭代器
(C++11)
返回指向起始位置的迭代器
（公开成员函数）
(C++11)
返回指向末尾的迭代器
(公开成员函数)
(C++11)
返回指向起始位置的反向迭代器
（公开成员函数）
(C++11)
返回指向末尾的反向迭代器
(公开成员函数)
容量
检查容器是否为空
(公开成员函数)
返回元素数量
（公开成员函数）
返回可能容纳的最大元素数量
（公开成员函数）
修饰符
清空内容
（公开成员函数）
插入元素
（公开成员函数）
(C++23)
插入元素范围
(公开成员函数)
(C++11)
原地构造元素
(公开成员函数)
擦除元素
（公开成员函数）
在末尾添加元素
（公开成员函数）
(C++11)
在容器末尾就地构造元素
(公开成员函数)
(C++23)
将元素范围添加到末尾
(公开成员函数)
移除末尾元素
（公开成员函数）
在开头插入元素
（公开成员函数）
(C++11)
在容器起始处就地构造元素
(公开成员函数)
(C++23)
在开头添加一系列元素
(公开成员函数)
移除首元素
（公开成员函数）
改变存储的元素数量
(公开成员函数)
交换内容
（公开成员函数）
操作
合并两个已排序的列表
（公开成员函数）
从另一个 list 转移元素
（公开成员函数）
移除满足特定条件的元素
（公开成员函数）
反转元素的顺序
（公开成员函数）
移除连续重复元素
（公开成员函数）
对元素进行排序
（公开成员函数）

非成员函数

(C++20中移除) (C++20中移除) (C++20中移除) (C++20中移除) (C++20中移除) (C++20)
按字典序比较两个 list 的值
(函数模板)
特化 std::swap 算法
(函数模板)
(C++20)
擦除满足特定条件的所有元素
(函数模板)

推导指引

(C++17 起)

注释

功能测试 宏 值 标准 功能
__cpp_lib_containers_ranges 202202L (C++23) 容器的范围构造与插入
__cpp_lib_constexpr_list 202502L (C++26) constexpr std::list

示例

运行此代码 
#include <algorithm>
#include <iostream>
#include <list>
int main()
{
    // 创建包含整数的列表
    std::list<int> l = {7, 5, 16, 8};
    // 在列表前端添加整数
    l.push_front(25);
    // 在列表末尾添加整数
    l.push_back(13);
    // 通过搜索在16之前插入整数
    auto it = std::find(l.begin(), l.end(), 16);
    if (it != l.end())
        l.insert(it, 42);
    // 输出列表内容
    std::cout << "l = { ";
    for (int n : l)
        std::cout << n << ", ";
    std::cout << "};\n";
}

输出： 

l = { 25, 7, 5, 42, 16, 8, 13, };

缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的C++标准。

DR 适用版本 发布行为 正确行为
LWG 230 C++98 T 未被要求满足 CopyConstructible
（可能无法构造 T 类型的元素） 		T 同时被要求
满足 CopyConstructible
LWG 276 C++98 T 始终被要求满足 CopyAssignable 仅在使用 T 实例化 operator= 或
assign 时才需要满足

另请参阅

(C++11)
单向链表
(类模板)