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 ，因为任何动态分配的存储必须在同一常量表达式求值期间释放。

(since C++26)

目录

模板参数

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

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

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

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

成员类型

成员类型 定义
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

(until C++11)

std:: allocator_traits < Allocator > :: pointer

(since C++11)
const_pointer

Allocator::const_pointer

(until C++11)

std:: allocator_traits < Allocator > :: const_pointer

(since C++11)
iterator 指向 value_type 的 LegacyBidirectionalIterator 和 ConstexprIterator (since C++26)
const_iterator 指向 const value_type 的 LegacyBidirectionalIterator 和 ConstexprIterator (since C++26)
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++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++标准。

缺陷报告 适用范围 发布时行为 正确行为
LWG 230 C++98 T 未被要求为 CopyConstructible
（可能无法构造类型为 T 的元素） 		T 同时需要
是 CopyConstructible
LWG 276 C++98 T 始终被要求为 CopyAssignable 仅当 operator= 或
assign 被 T 实例化时才需要

参见

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