QList Class
template <typename T> class QListQList 类是一个提供动态数组的模板类。更多
Header: | #include <QList> |
CMake: | find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core) |
qmake: | QT += core |
继承于 |
- 所有成员(包括继承成员)列表
- 已废弃成员
- QList 属于隐式共享类。
注意:该类中的所有函数都是可重入的。
公共类型
公共函数
QList() | |
QList(qsizetypesize) | |
QList(std::initializer_list<T>args) | |
QList(第一个输入迭代器,最后一个输入迭代器) | |
QList(qsizetypesize, QList<T>::parameter_typevalue) | |
(since 6.8) | QList(qsizetypesize, Qt::Initialization) |
QList(const QList<T>&other) | |
QList(QList<T>&&other) | |
~QList() | |
void | append(QList<T>::parameter_typevalue) |
(since 6.0) void | append(QList<T>&&value) |
void | append(QList<T>::rvalue_refvalue) |
void | append(const QList<T>&value) |
(since 6.6) QList<T> & | assign(std::initializer_list<T>l) |
(since 6.6) QList<T> & | assign(InputIteratorfirst, InputIteratorlast) |
(since 6.6) QList<T> & | assign(qsizetypen, QList<T>::parameter_typet) |
QList<T>::const_reference | at(qsizetypei) 常量 |
QList<T>::reference | back() |
QList<T>::const_reference | back()常量 |
QList<T>::iterator | begin() |
QList<T>::const_iterator | begin()常量 |
Qsizetype | capacity()常数 |
QList<T>::const_iterator | cbegin常数 |
QList<T>::const_iterator | cend常数 |
void | clear() |
QList<T>::const_iterator | constBegin()常量 |
QList<T>::const_pointer | constData()常量 |
QList<T>::const_iterator | constEnd常数 |
const T & | constFirst常数 |
const T & | constLast() const |
bool | contains(const AT&value) const |
qsizetype | count(const AT&value) const |
qsizetype | count() const |
QList<T>::const_reverse_iterator | crbegin()常量 |
QList<T>::const_reverse_iterator | crend()常量 |
QList<T>::pointer | data() |
QList<T>::const_pointer | data()常量 |
QList<T>::iterator | emplace(qsizetypei,Args&&...args) |
QList<T>::iterator | emplace(QList<T>::const_iteratorbefore, Args &&...args) |
QList<T>::reference | emplaceBack(Args &&...args) |
QList<T>::reference | emplace_back(Args &&...args) |
bool | empty() 常量 |
QList<T>::iterator | end() |
QList<T>::const_iterator | end()常量 |
bool | endsWith(QList<T>::parameter_typevalue) const |
QList<T>::iterator | erase(QList<T>::const_iteratorpos) |
QList<T>::iterator | erase(QList<T>::const_iteratorbegin, QList<T>::const_iteratorend) |
QList<T> & | fill(QList<T>::parameter_typevalue, qsizetypesize= -1) |
T & | first() |
(since 6.0) QList<T | first(qsizetypen) const |
const T & | first() const |
QList<T>::reference | front() |
QList<T>::const_reference | front() 常量 |
qsizetype | indexOf(const AT&value, qsizetypefrom= 0) const |
QList<T>::iterator | insert(qsizetypei, QList<T>::parameter_typevalue) |
QList<T>::iterator | insert(qsizetypei, QList<T>::rvalue_refvalue) |
QList<T>::iterator | insert(QList<T>::const_iteratorbefore, qsizetypecount, QList<T>::parameter_typevalue) |
QList<T>::iterator | insert(QList<T>::const_iteratorbefore、QList<T>::parameter_typevalue) |
QList<T>::iterator | insert(QList<T>::const_iteratorbefore, QList<T>::rvalue_refvalue) |
QList<T>::iterator | insert(qsizetypei, qsizetypecount, QList<T>::parameter_typevalue) |
bool | isEmpty()常量 |
T & | last() |
(since 6.0) QList<T | last(qsizetypen) const |
const T & | last() const |
qsizetype | lastIndexOf(const AT&value, qsizetypefrom= -1) const |
qsizetype | length() const |
(since 6.8) qsizetype | max_size() const |
QList<T> | mid(qsizetypepos, qsizetypelength= -1) const |
void | move(qsizetypefrom, qsizetypeto) |
void | pop_back() |
void | pop_front() |
void | prepend(QList<T>::parameter_typevalue) |
void | prepend(QList<T>::rvalue_refvalue) |
void | push_back(QList<T>::parameter_typevalue) |
void (QList<T>::parameter_type value) | push_back(QList<T>::rvalue_refvalue) |
void | push_front(QList<T>::parameter_typevalue) |
void (QList<T>::parameter_type value) | push_front(QList<T>::rvalue_refvalue) |
QList<T>::reverse_iterator | rbegin() |
QList<T>::const_reverse_iterator | rbegin()常量 |
void | remove(qsizetypei, qsizetypen= 1) |
qsizetype | removeAll(const AT&t) |
无效 | removeAt(qsizetypei) |
void | removeFirst() |
(since 6.1) qsizetype | removeIf谓词 |
void | removeLast() |
bool | removeOne(const AT&t) |
QList<T>::reverse_iterator | rend() |
QList<T>::const_reverse_iterator | rend()常量 |
void | replace(qsizetypei, QList<T>::parameter_typevalue) |
(qsizetype i, QList<T>::parameter_type) | replace(qsizetypei, QList<T>::rvalue_refvalue) |
void | reserve(qsizetypesize) |
(since 6.0) 无效(QList<T>::rvalue_ref | resize(qsizetypesize) |
(since 6.0) void | resize(qsizetypesize, QList<T>::parameter_typec) |
(since 6.8) void | resizeForOverwrite(大小,QList<T>::参数类型) |
void | shrink_to_fit() |
qsizetype | size() const |
(since 6.0) QList<T> | sliced(qsizetypepos, qsizetypen) const |
(since 6.0) QList<T | sliced(qsizetypepos) const |
void | squeeze() |
bool | startsWith(QList<T>::parameter_typevalue) const |
void | swap(QList<T>&other) |
无效 | swapItemsAt(qsizetypei, qsizetypej) |
T | takeAt(qsizetypei) |
QList<T>::value_type | takeFirst() |
QList<T>::value_type | takeLast() |
T | value(qsizetypei) 常量 |
T | value(qsizetypei, QList<T>::parameter_typedefaultValue) const |
bool | operator!=(const QList<T>&other) const |
QList<T> | operator+(QList<T>&&other) && |
QList<T> | operator+(const QList<T>&other) && |
QList<T | operator+(QList<T>&&other) const & |
QList<T | operator+(const QList<T>&other) const & |
QList<T> & | operator+=(const QList<T>&other) |
(since 6.0) QList<T> & | operator+=(QList<T>&&other) |
QList<T> & | operator+=(QList<T>::parameter_typevalue) |
QList<T> & (QList<T>::parameter_type value) | operator+=(QList<T>::rvalue_refvalue) |
bool | operator<(const QList<T>&other) const |
QList<T> & | operator<<(QList<T>::parameter_typevalue) |
QList<T> & | operator<<(const QList<T>&other) |
(since 6.0) QList<T> & | operator<<(QList<T>&&other) |
QList<T> & | operator<<(QList<T>::rvalue_refvalue) |
bool | operator<=(const QList<T>&other) const |
QList<T> & | operator=(QList<T>&&other) |
QList<T> & | operator=(const QList<T>&other) |
QList<T> & | operator=(std::initializer_list<T>args) |
bool | operator==(const QList<T>&other) const |
bool | operator>(const QList<T>&other) const |
bool | operator>=(const QList<T>&other) const |
QList<T>::reference | operator[](qsizetypei) |
QList<T>::const_reference | operator[](qsizetypei) 常量 |
静态公共成员
(since 6.8) qsizetype | maxSize() |
相关非成员
(since 6.1) qsizetype | erase(QList<T> &list, const AT &t) |
(since 6.1) qsizetype | erase_if(QList<T> &list, Predicate pred) |
size_t | qHash(const QList<T> &key, size_t seed = 0) |
QDataStream & | operator<<(QDataStream &out, const QList<T> &list) |
(since 6.9) auto | operator<=>(const QList<T> &lhs, const QList<T> &rhs) |
QDataStream & | operator>>(QDataStream &in, QList<T> &list) |
详细说明
QList<T> 是 Qt 的通用容器类之一。它将项目存储在相邻的内存位置,并提供基于索引的快速访问。QVector<T> 在 Qt 5 中曾经是一个不同的类,但现在是 QList 的一个简单别名。
QList<T> 和QVarLengthArray<T> 提供了类似的 API 和功能。它们通常可以互换,但会影响性能。下面是用例概述:
- QList 应该是您的默认首选。
- QVarLengthArray QList 提供了一个数组,它在堆栈中保留了空间,但在需要时可以在堆上动态增长。它适用于通常较小的短时容器。
- 如果你需要一个真正的链接列表,它能保证在列表中间恒定时间插入,并使用迭代器而非索引来读取项,那就使用 std::list。
注: QList 和QVarLengthArray 都保证数组布局与 C 兼容。
注意: Qt 5 中的 QList 并不总是具有 C 兼容的数组布局,我们经常建议使用QVector 代替,以获得更可预测的性能。在 Qt 6 中情况不再如此,现在这两个类共享一个实现,可以互换使用。
下面是一个存储整数的 QList 和一个存储QString 值的 QList 的示例:
QList 将其项目存储在一个连续内存数组中。通常,创建的列表有一个初始大小。例如,以下代码构建了一个有 200 个元素的 QList:
元素会自动以默认值初始化。如果想用不同的值初始化列表,可将该值作为第二个参数传递给构造函数:
您也可以随时调用fill() 为列表填充值。
QList 使用基于 0 的索引,就像 C++ 数组一样。要访问特定索引位置上的项目,可以使用 operator[]()。在非const 列表中,operator[]() 返回一个指向项的引用,可用于赋值的左侧:
if (list[0] == "Liz") list[0] = "Elizabeth";
对于只读访问,另一种语法是使用at():
for (qsizetype i = 0; i < list.size(); ++i) { if (list.at(i) == "Alfonso") cout << "Found Alfonso at position " << i << endl; }
at() 比 operator[]() 更快,因为它不会导致深度复制。
访问 QList 中存储的数据的另一种方法是调用data()。该函数返回一个指向列表中第一个项目的指针。您可以使用该指针直接访问和修改存储在列表中的元素。如果需要将 QList 传递给接受纯 C++ 数组的函数,指针也很有用。
如果要查找列表中某个特定值的所有出现次数,请使用indexOf() 或lastIndexOf()。前者从给定的索引位置开始向前搜索,后者则向后搜索。如果找到了匹配项的索引,两者都会返回匹配项的索引,否则返回-1。例如
qsizetype i = list.indexOf("Harumi"); if (i != -1) cout << "First occurrence of Harumi is at position " << i << endl;
如果只想检查列表是否包含某个特定值,请使用contains()。如果想知道特定值在列表中出现的次数,请使用count() 。
QList 提供了用于添加、移动和删除项的基本函数:insert(),replace(),remove(),prepend(),append().除了append(),prepend() 和replace() 之外,这些函数对于大型列表来说可能很慢(线性时间),因为它们需要将列表中的许多项在内存中移动一个位置。如果你想要一个能在中间提供快速插入/移除的容器类,请使用 std::list 代替。
与普通 C++ 数组不同,QLists 可以随时通过调用resize() 来调整大小。如果新大小大于旧大小,QList 可能需要重新分配整个列表。QList 尝试通过预分配多达实际数据需求两倍的内存来减少重新分配的次数。
如果您正在逐步创建一个 QList,并预先知道它将包含大约多少个元素,您可以调用reserve() 要求 QList 预分配一定量的内存。您还可以调用capacity() 来了解 QList 实际分配了多少内存。
请注意,由于隐式共享,使用非const 运算符和函数可能会导致 QList 对数据进行深度复制。
QList 的值类型必须是可分配的数据类型。这涵盖了大多数常用的数据类型,但编译器不会让你存储QWidget 作为值,而是存储QWidget *。少数函数有额外要求,例如indexOf() 和lastIndexOf() 希望值类型支持operator==()
。这些要求按函数逐一记录。
关于对项进行迭代,请参阅对容器进行迭代。关于将 QList 与<algorithm>
header 中的函数(如std::sort()
,std::reverse()
, 和std::count_if()
)一起使用,请参阅Qt XML 容器和 std 算法。
除 QList 外,Qt 还提供了QVarLengthArray ,这是一个非常低级的类,功能很少,但为速度进行了优化。
使用 Qt 容器的更多信息
有关 Qt 容器之间以及 Qt 容器与 STL 容器之间比较的详细讨论,请参阅了解 Qt 容器。
最大大小和内存不足条件
QList 的最大大小取决于体系结构。大多数 64 位系统可分配超过 2 GB 的内存,典型限制为 2^63 字节。实际值还取决于管理数据块所需的开销。因此,在 32 位平台上,最大容量为 2 GB 减去开销,在 64 位平台上,最大容量为 2^63 字节减去开销。可存储在 QList 中的元素数就是这个最大大小除以存储元素的大小。
当内存分配失败时,QList 会使用Q_CHECK_PTR 宏,如果应用程序在编译时支持异常,该宏会抛出std::bad_alloc
异常。如果异常被禁用,那么内存不足就是未定义的行为。
请注意,操作系统可能会对持有大量已分配内存(尤其是大的连续内存块)的应用程序施加进一步限制。此类考虑、此类行为的配置或任何缓解措施都不在 Qt API 的范围之内。
成员类型文档
[alias]
QList::ConstIterator
QList::const_iterator 的 Qt-style 同义词。
[alias]
QList::Iterator
QList::iterator 的 Qt-style 同义词。
[alias]
QList::const_pointer
提供 STL 兼容性。
[alias]
QList::const_reference
提供 STL 兼容性。
[alias]
QList::const_reverse_iterator
QList::const_reverse_iterator 类型定义为QList 提供了 STL 风格的 const 反向迭代器。
警告: 隐式共享容器上的迭代器的工作方式与 STL-iterators 并不完全相同。当容器上的迭代器处于活动状态时,应避免复制该容器。更多信息,请阅读隐式共享迭代器问题。
警告: 当修改QList 时,迭代器将失效。默认情况下,所有迭代器都会失效。本规则的例外情况已明确记录在案。
另请参阅 QList::rbegin(),QList::rend(),QList::reverse_iterator, 和QList::const_iterator 。
[alias]
QList::difference_type
提供 STL 兼容性。
[alias]
QList::parameter_type
[alias]
QList::pointer
提供 STL 兼容性。
[alias]
QList::reference
提供 STL 兼容性。
[alias]
QList::reverse_iterator
QList::reverse_iterator 类型定义为QList 提供了 STL 风格的非const 反向迭代器。
警告: 隐式共享容器上的迭代器的工作方式与 STL-iterators 并不完全相同。当容器上的迭代器处于活动状态时,应避免复制该容器。更多信息,请阅读隐式共享迭代器问题。
警告: 当修改QList 时,迭代器将失效。默认情况下,所有迭代器都会失效。该规则的例外情况已明确记录在案。
另请参阅 QList::rbegin(),QList::rend(),QList::const_reverse_iterator, 和QList::iterator 。
[alias]
QList::rvalue_ref
[alias]
QList::size_type
提供 STL 兼容性。
[alias]
QList::value_type
为与 STL 兼容而提供。
成员函数文档
[since 6.0]
void QList::resize(qsizetype size)
[since 6.0]
void QList::resize(qsizetype size, QList<T>::parameter_type c)
将列表的大小设置为size 。如果size 大于当前大小,则将元素添加到末尾;新元素将以默认构造值或c 进行初始化。如果size 小于当前大小,则将元素从末尾移除。
如果该列表不是共享的,capacity() 将被保留。使用squeeze() 删除多余的容量。
该函数在 Qt 6.0 中引入。
另请参阅 size()。
在列表开头插入value 。
示例
QList<QString> list; list.prepend("one"); list.prepend("two"); list.prepend("three"); // list: ["three", "two", "one"]
这与 list.insert(0,value) 相同。
通常这种操作相对较快(摊销恒定时间)。QList 可以在列表数据的开头分配额外内存,并向该方向增长,而无需在每次操作时重新分配或移动数据。不过,如果你想要一个能保证在恒定时间内预添加的容器类,可以使用 std::list 代替,否则你会更喜欢QList 。
template <typename... Args> QList<T>::reference QList::emplaceBack(Args &&... args)
template <typename... Args> QList<T>::reference QList::emplace_back(Args &&... args)
在容器末尾添加一个新元素。新元素是使用args 作为参数就地构建的。
返回新元素的引用。
示例
QList<QString>list{"one", "two"}; list.emplaceBack(3, 'a');qDebug() << list; // list:["one", "two", "aaa"]
也可以使用返回的引用访问新创建的对象:
这与 list.emplace(list.size(),args) 相同。
另请参见 emplace 。
QList<T>::iterator QList::insert(qsizetype i, QList<T>::parameter_type value)
QList<T>::iterator QList::insert(qsizetype i, QList<T>::rvalue_ref value)
在列表中i 的索引位置插入value 。如果i 为 0,则将该值预输入到列表中。如果i 为size() ,则将该值添加到列表中。
举例说明
QList<QString> list = {"alpha", "beta", "delta"}; list.insert(2, "gamma"); // list: ["alpha", "beta", "gamma", "delta"]
对于大型列表,此操作可能会很慢(线性时间),因为它需要将索引i 及以上的所有项目在内存中移动一个位置。如果你想要一个提供快速insert() 函数的容器类,请使用 std::list 代替。
另请参见 append()、prepend() 和remove()。
QList<T>::iterator QList::insert(QList<T>::const_iterator before, QList<T>::parameter_type value)
QList<T>::iterator QList::insert(QList<T>::const_iterator before, QList<T>::rvalue_ref value)
这是一个重载函数。
在迭代器before 指向的项目前插入value 。返回指向插入项的迭代器。
void QList::replace(qsizetype i, QList<T>::parameter_type value)
void QList::replace(qsizetype i, QList<T>::rvalue_ref value)
用value 替换索引位置i 上的项目。
i 必须是列表中有效的索引位置(即 0 <= < () )。i size
另请参阅 operator[]() 和remove()。
void QList::push_front(QList<T>::parameter_type value)
void QList::push_front(QList<T>::rvalue_ref value)
提供此函数是为了与 STL 兼容。它等同于 prepend(value)。
[static constexpr, since 6.8]
qsizetype QList::maxSize()
[constexpr noexcept, since 6.8]
qsizetype QList::max_size() const
它返回列表理论上可容纳元素的最大数量。实际上,受系统可用内存量的限制,这个数字可能会小得多。
此函数在 Qt 6.8 中引入。
QList<T> QList::operator+(QList<T> &&other) &&
QList<T> QList::operator+(const QList<T> &other) &&
QList<T> QList::operator+(QList<T> &&other) const &
QList<T> QList::operator+(const QList<T> &other) const &
返回一个列表,其中包含此列表中的所有项目,然后是other 列表中的所有项目。
另请参阅 operator+=()。
[constexpr noexcept]
QList::QList()
构造一个空列表。
另请参阅 resize().
[explicit]
QList::QList(qsizetype size)
构造一个初始大小为size 的元素列表。
元素用默认构造值初始化。
另请参见 resize()。
QList::QList(std::initializer_list<T> args)
用args 给定的 std::initializer_list 构造一个 list。
template <typename InputIterator, QList<T>::if_input_iterator<InputIterator> = true> QList::QList(InputIterator first, InputIterator last)
构造一个内容在迭代器范围 [first,last) 内的列表。
InputIterator
的值类型必须可转换为T
。
限制条件
只有当InputIterator
满足LegacyInputIterator 的要求时,才会参与重载解析。
QList::QList(qsizetype size, QList<T>::parameter_type value)
构造一个初始大小为size 的 list。每个元素的初始化值为value 。
[since 6.8]
QList::QList(qsizetype size, Qt::Initialization)
构造一个初始大小为size 的元素的列表。
QList 将尝试不初始化元素。
具体来说
- 如果
T
的构造函数接受Qt::Uninitialized
,则将使用该构造函数初始化元素; - 否则,将默认构造每个元素。对于微不足道的可构造类型(如
int
,float
等),这等同于不初始化它们。
此函数在 Qt 6.8 中引入。
另请参阅 resizeForOverwrite().
[default]
QList::QList(const QList<T> &other)
构造other 的副本。
由于 QList 是隐式共享的,因此该操作耗时不变。这使得从函数返回 QList 的速度非常快。如果共享实例被修改,它将被复制(写时复制),这需要线性时间。
另请参见 operator=()。
[default]
QList::QList(QList<T> &&other)
Move-构建一个 QList 实例,使其指向other 所指向的同一对象。
[default]
QList::~QList()
销毁列表。
void QList::append(QList<T>::parameter_type value)
在列表末尾插入value 。
举例说明:
QList<QString> list; list.append("one"); list.append("two"); QString three = "three"; list.append(three); // list: ["one", "two", "three"] // three: "three"
这等同于调用 resize(size() + 1) 并将value 赋值给列表中新的最后一个元素。
这个操作相对较快,因为QList 分配的内存通常比需要的要多,所以每次无需重新分配整个列表就能实现增长。
另请参见 operator<<()、prepend() 和insert()。
[since 6.0]
void QList::append(QList<T> &&value)
这是一个重载函数。
将value 列表中的项目移至该列表的末尾。
此函数在 Qt 6.0 中引入。
另请参阅 operator<<() 和operator+=()。
void QList::append(QList<T>::rvalue_ref value)
这是一个重载函数。
示例
QList<QString> list; list.append("one"); list.append("two"); QString three = "three"; list.append(std::move(three)); // list: ["one", "two", "three"] // three: ""
void QList::append(const QList<T> &value)
这是一个重载函数。
将value 列表中的项目追加到此列表中。
另请参阅 operator<<() 和operator+=()。
[since 6.6]
QList<T> &QList::assign(std::initializer_list<T> l)
用l 中元素的副本替换此列表的内容。
该列表的大小等于l 中的元素数。
只有当l 中的元素数超过此列表的容量或此列表是共享的时,此函数才会分配内存。
此函数在 Qt 6.6 中引入。
[since 6.6]
template <typename InputIterator, QList<T>::if_input_iterator<InputIterator> = true> QList<T> &QList::assign(InputIterator first, InputIterator last)
将此列表的内容替换为迭代器范围 [first,last) 中元素的副本。
此列表的大小将等于范围 [first,last) 中的元素个数。
只有当范围中的元素数超过此列表的容量或此列表是共享的,此函数才会分配内存。
注意: 如果任一参数是进入 *this 的迭代器,则行为未定义。
限制条件
只有当InputIterator
符合LegacyInputIterator 的要求时,才会参与重载解析。
此函数在 Qt 6.6 中引入。
[since 6.6]
QList<T> &QList::assign(qsizetype n, QList<T>::parameter_type t)
将此列表的内容替换为n 的副本t 。
此列表的大小将等于n 。
该函数仅在n 超过列表容量或该列表是共享的情况下分配内存。
此函数在 Qt 6.6 中引入。
[noexcept]
QList<T>::const_reference QList::at(qsizetype i) const
返回列表中位于i 索引位置的项目。
i 必须是列表中有效的索引位置(即 0 <= < () )。i size
另请参阅 value() 和operator[]()。
QList<T>::reference QList::back()
提供此函数是为了与 STL 兼容。它等同于last()。
[noexcept]
QList<T>::const_reference QList::back() const
这是一个重载函数。
QList<T>::iterator QList::begin()
返回一个STL 样式的迭代器,指向列表中的第一个项目。
警告 返回的迭代器会在分离或修改QList 时失效。
另请参阅 constBegin() 和end()。
[noexcept]
QList<T>::const_iterator QList::begin() const
这是一个重载函数。
qsizetype QList::capacity() const
返回在不强制重新分配的情况下可存储在列表中的最大条目数。
该函数的唯一目的是提供一种微调QList 内存使用情况的方法。一般来说,您很少需要调用此函数。如果想知道列表中有多少项,请调用size() 。
注意: 静态分配的列表即使不是空的,也会报告容量为 0。
警告 已分配内存块中的可用空间位置是未定义的。换句话说,不应假设空闲内存总是位于列表的末尾。可以调用reserve() 来确保末尾有足够的空间。
[noexcept]
QList<T>::const_iterator QList::cbegin() const
返回指向列表中第一个项目的 ConstSTL 样式迭代器。
警告: 返回的迭代器会在分离或修改QList 时失效。
[noexcept]
QList<T>::const_iterator QList::cend() const
返回一个STL 样式的常量迭代器,指向列表中的最后一个项目。
警告: 返回的迭代器会在分离或修改QList 时失效。
void QList::clear()
删除列表中的所有元素。
如果该列表不是共享的,capacity() 将被保留。使用squeeze() 删除多余的容量。
[noexcept]
QList<T>::const_iterator QList::constBegin() const
返回指向列表中第一个项目的 ConstSTL 样式迭代器。
警告: 返回的迭代器会在分离或修改QList 时失效。
[noexcept]
QList<T>::const_pointer QList::constData() const
返回一个常量指针,指向存储在列表中的数据。该指针可用于访问列表中的项目。
警告 指针会在分离或修改QList 时失效。
该函数主要用于将列表传递给接受纯 C++ 数组的函数。
另请参阅 data() 和operator[]()。
[noexcept]
QList<T>::const_iterator QList::constEnd() const
返回一个STL 样式的常量迭代器,指向列表中的最后一个项目。
警告: 返回的迭代器会在分离或修改QList 时失效。
另请参阅 constBegin() 和end()。
[noexcept]
const T &QList::constFirst() const
返回列表中第一个项目的常量引用。此函数假定列表不是空的。
另请参阅 constLast()、isEmpty() 和first()。
[noexcept]
const T &QList::constLast() const
返回列表中最后一项的常量引用。此函数假定列表不是空的。
另请参阅 constFirst()、isEmpty() 和last()。
[noexcept]
template <typename AT> bool QList::contains(const AT &value) const
如果列表中包含value ,则返回true
;否则返回false
。
该函数要求值类型具有operator==()
的实现。
[noexcept]
template <typename AT = T> qsizetype QList::count(const AT &value) const
返回value 在列表中出现的次数。
该函数要求值类型具有operator==()
的实现。
[noexcept]
qsizetype QList::count() const
这是一个重载函数。
与size() 相同。
[noexcept]
QList<T>::const_reverse_iterator QList::crbegin() const
返回一个 ConstSTL 样式的反向迭代器,按相反顺序指向列表中的第一个项目。
警告: 返回的迭代器会在分离或修改QList 时失效。
另请参阅 begin()、rbegin() 和rend()。
[noexcept]
QList<T>::const_reverse_iterator QList::crend() const
返回一个 ConstSTL 样式的反向迭代器,以相反的顺序指向列表中最后一个项目之后。
警告: 返回的迭代器会在分离或修改QList 时失效。
QList<T>::pointer QList::data()
返回存储在列表中数据的指针。该指针可用于访问和修改列表中的项目。
示例
QList<int> list(10); int *data = list.data(); for (qsizetype i = 0; i < 10; ++i) data[i] = 2 * i;
警告: 指针在脱离时或修改QList 时失效。
该函数主要用于将列表传递给接受纯 C++ 数组的函数。
另请参阅 constData() 和operator[]()。
[noexcept]
QList<T>::const_pointer QList::data() const
这是一个重载函数。
template <typename... Args> QList<T>::iterator QList::emplace(qsizetype i, Args &&... args)
在i 位置插入一个新元素,从而扩展容器。新元素是使用args 作为参数就地构建的。
返回指向新元素的迭代器。
示例
注意: 该元素保证在开始时就地创建,但之后可能会被复制或移动到正确的位置。
另请参见 emplaceBack 。
template <typename... Args> QList<T>::iterator QList::emplace(QList<T>::const_iterator before, Args &&... args)
这是一个重载函数。
在迭代器before 指向的项目前创建一个新元素。这个新元素是使用args 作为参数就地创建的。
返回指向新元素的迭代器。
[noexcept]
bool QList::empty() const
该函数与 STL 兼容。它与isEmpty() 等价,如果列表为空,则返回true
;否则返回false
。
QList<T>::iterator QList::end()
返回一个STL 样式的迭代器,指向列表中的最后一个项目。
警告: 返回的迭代器会在分离或修改QList 时失效。
[noexcept]
QList<T>::const_iterator QList::end() const
这是一个重载函数。
bool QList::endsWith(QList<T>::parameter_type value) const
如果该列表不为空,且最后一项等于value ,则返回true
;否则返回false
。
QList<T>::iterator QList::erase(QList<T>::const_iterator pos)
从列表中移除迭代器pos 指向的项目,并返回指向列表中下一个项目的迭代器(可能是end() )。
移除元素将保留列表的容量,而不会减少分配的内存量。若要移除额外的容量并释放尽可能多的内存,请调用squeeze() 。
QList<T>::iterator QList::erase(QList<T>::const_iterator begin, QList<T>::const_iterator end)
这是一个重载函数。
删除begin 至end (但不包括 )的所有项目。返回一个迭代器,指向调用前end 所指向的同一项目。
元素移除将保留列表的容量,而不会减少分配的内存量。要删除额外的容量并释放尽可能多的内存,请调用squeeze() 。
QList<T> &QList::fill(QList<T>::parameter_type value, qsizetype size = -1)
为列表中的所有项目指定value 。如果size 与 -1 不同(默认值),则会事先将列表大小调整为size 。
示例:
QList<QString> list(3); list.fill("Yes"); // list: ["Yes", "Yes", "Yes"] list.fill("oh", 5); // list: ["oh", "oh", "oh", "oh", "oh"]
另请参阅 resize().
T &QList::first()
返回列表中第一个项目的引用。此函数假定列表不是空的。
另请参阅 last()、isEmpty() 和constFirst()。
[since 6.0]
QList<T> QList::first(qsizetype n) const
返回一个子列表,其中包含此列表的前n 个元素。
注意: 当n < 0 或n >size() 时,行为未定义。
此函数在 Qt 6.0 中引入。
[noexcept]
const T &QList::first() const
这是一个重载函数。
QList<T>::reference QList::front()
提供此函数是为了与 STL 兼容。它等同于first()。
[noexcept]
QList<T>::const_reference QList::front() const
这是一个重载函数。
[noexcept]
template <typename AT> qsizetype QList::indexOf(const AT &value, qsizetype from = 0) const
返回value 在列表中首次出现的索引位置,从索引位置from 开始向前搜索。如果没有匹配项,则返回-1。
示例
QList<QString> list{"A", "B", "C", "B", "A"}; list.indexOf("B"); // returns 1 list.indexOf("B", 1); // returns 1 list.indexOf("B", 2); // returns 3 list.indexOf("X"); // returns -1
此函数要求值类型具有operator==()
的实现。
另请参阅 lastIndexOf() 和contains()。
QList<T>::iterator QList::insert(QList<T>::const_iterator before, qsizetype count, QList<T>::parameter_type value)
在迭代器before 指向的项目前插入count value 的副本。返回指向第一个插入项的迭代器。
QList<T>::iterator QList::insert(qsizetype i, qsizetype count, QList<T>::parameter_type value)
这是一个重载函数。
在列表中的索引位置i 插入count value 的副本。
示例
QList<double> list = {2.718, 1.442, 0.4342}; list.insert(1, 3, 9.9); // list: [2.718, 9.9, 9.9, 9.9, 1.442, 0.4342]
[noexcept]
bool QList::isEmpty() const
如果列表大小为 0,则返回true
;否则返回false
。
T &QList::last()
返回列表中最后一项的引用。此函数假定列表不是空的。
另请参阅 first()、isEmpty() 和constLast()。
[since 6.0]
QList<T> QList::last(qsizetype n) const
返回包含此列表最后n 个元素的子列表。
注意: 当n < 0 或n >size() 时,行为未定义。
此函数在 Qt 6.0 中引入。
[noexcept]
const T &QList::last() const
这是一个重载函数。
[noexcept]
template <typename AT> qsizetype QList::lastIndexOf(const AT &value, qsizetype from = -1) const
从索引位置from 开始向后搜索,返回值value 在列表中最后出现的索引位置。如果from 为 -1(默认值),则从最后一个项目开始搜索。如果没有匹配项,则返回-1。
示例
QList<QString> list = {"A", "B", "C", "B", "A"}; list.lastIndexOf("B"); // returns 3 list.lastIndexOf("B", 3); // returns 3 list.lastIndexOf("B", 2); // returns 1 list.lastIndexOf("X"); // returns -1
此函数要求值类型具有operator==()
的实现。
另请参阅 indexOf() 。
[noexcept]
qsizetype QList::length() const
QList<T> QList::mid(qsizetype pos, qsizetype length = -1) const
返回一个子列表,其中包含该列表中从pos 位置开始的元素。如果length 为 -1(默认值),则会包含pos 之后的所有元素;否则会包含length 元素(或所有剩余元素,如果少于length 元素)。
void QList::move(qsizetype from, qsizetype to)
将索引位置from 上的项目移动到索引位置to 。
from
和 必须在界内。to
例如,将第一个项目移动到列表末尾:
[noexcept]
void QList::pop_back()
提供此函数是为了与 STL 兼容。它等同于removeLast()。
[noexcept]
void QList::pop_front()
提供此函数是为了与 STL 兼容。它等同于removeFirst()。
void QList::push_back(QList<T>::parameter_type value)
提供此函数是为了与 STL 兼容。它等同于 append(value)。
void QList::push_back(QList<T>::rvalue_ref value)
这是一个重载函数。
QList<T>::reverse_iterator QList::rbegin()
返回一个STL 样式的反向迭代器,按相反顺序指向列表中的第一个项目。
警告 返回的迭代器在分离或修改QList 时失效。
另请参阅 begin()、crbegin() 和rend()。
[noexcept]
QList<T>::const_reverse_iterator QList::rbegin() const
这是一个重载函数。
void QList::remove(qsizetype i, qsizetype n = 1)
从索引位置i 开始,删除n 列表中的元素。
删除元素将保留列表的容量,而不会减少分配的内存量。若要移除额外的容量并释放尽可能多的内存,请调用squeeze() 。
另请参阅 insert()、replace() 和fill()。
template <typename AT = T> qsizetype QList::removeAll(const AT &t)
删除列表中所有比较值等于t 的元素。如果有元素被移除,则返回被移除元素的数量。
元素移除将保留列表的容量,不会减少分配的内存量。要删除额外的容量并释放尽可能多的内存,请调用squeeze()。
另请参见 removeOne().
void QList::removeAt(qsizetype i)
删除索引位置i 上的元素。相当于
remove(i);
删除元素将保留列表的容量,而不会减少分配的内存量。要删除额外的容量并释放尽可能多的内存,请调用squeeze() 。
另请参见 remove()。
[noexcept]
void QList::removeFirst()
删除列表中的第一个项目。调用此函数等同于调用 remove(0)。列表不能为空。如果列表可以为空,请在调用此函数前调用isEmpty() 。
元素移除将保留列表的容量,而不会减少分配的内存量。要删除额外的容量并释放尽可能多的内存,请调用squeeze() 。
另请参阅 remove()、takeFirst() 和isEmpty()。
[since 6.1]
template <typename Predicate> qsizetype QList::removeIf(Predicate pred)
从列表中删除谓词pred 返回 true 的所有元素。如果有,则返回已移除元素的数目。
此函数在 Qt 6.1 中引入。
另请参阅 removeAll()。
[noexcept]
void QList::removeLast()
删除列表中的最后一个项目。调用此函数等同于调用 remove(size() - 1)。列表不能为空。如果列表可以为空,请在调用此函数前调用isEmpty() 。
元素移除将保留列表的容量,而不会减少分配的内存量。要删除额外的容量并释放尽可能多的内存,请调用squeeze() 。
另请参阅 remove()、takeLast()、removeFirst() 和isEmpty()。
template <typename AT = T> bool QList::removeOne(const AT &t)
从列表中删除第一个比较结果等于t 的元素。返回元素是否已被移除。
元素移除将保留列表的容量,不会减少分配的内存量。若要移除额外的容量并释放尽可能多的内存,请调用squeeze()。
另请参见 removeAll()。
QList<T>::reverse_iterator QList::rend()
返回一个STL 样式的反向迭代器,按相反顺序指向列表中最后一个项目之后。
警告 返回的迭代器会在分离或修改QList 时失效。
[noexcept]
QList<T>::const_reverse_iterator QList::rend() const
这是一个重载函数。
void QList::reserve(qsizetype size)
尝试为至少size 个元素分配内存。
如果事先知道列表有多大,就应该调用此函数,以防止重新分配和内存碎片。如果经常调整列表大小,还可能获得更好的性能。
如果对所需空间有疑问,通常最好使用一个上限作为size ,或者对最有可能的大小做一个较高的估计,如果严格的上限会比它大得多的话。如果size 是一个低估值,那么一旦超过预留大小,列表就会根据需要增长,这可能会导致比最佳高估值更大的分配,并会减慢触发操作的速度。
警告: reserve() 会保留内存,但不会改变列表的大小。访问超出当前列表末尾的数据是未定义的行为。如果需要访问超出列表当前末尾的内存,请使用resize() 。
另请参阅 squeeze()、capacity() 和resize()。
[since 6.8]
void QList::resizeForOverwrite(qsizetype size)
将列表的大小设置为size 。如果size 小于当前大小,则会从末尾删除元素。如果size 大于当前大小,则在末尾添加元素;QList 将尝试不初始化这些新元素。
具体来说
- 如果
T
有一个接受Qt::Uninitialized
的构造函数,则将使用该构造函数初始化元素; - 否则,将默认构造每个元素。对于微不足道的可构造类型(如
int
,float
等),这等同于不初始化它们。
此函数在 Qt 6.8 中引入。
void QList::shrink_to_fit()
提供此函数是为了与 STL 兼容。它等同于squeeze()。
[noexcept]
qsizetype QList::size() const
返回列表中的项目数。
[since 6.0]
QList<T> QList::sliced(qsizetype pos, qsizetype n) const
从位置pos 开始,返回一个包含n 此列表元素的子列表。
注意: 当pos < 0、n < 0 或pos +n >size() 时,行为未定义。
此函数在 Qt 6.0 中引入。
[since 6.0]
QList<T> QList::sliced(qsizetype pos) const
这是一个重载函数。
返回一个子列表,该子列表包含从pos 位置开始一直延伸到列表末尾的列表元素。
注意: 当pos < 0 或pos >size() 时,行为未定义。
此函数在 Qt 6.0 中引入。
void QList::squeeze()
释放存储项目所不需要的内存。
该函数的唯一目的是提供一种微调QList 内存使用情况的方法。一般来说,您很少需要调用此函数。
bool QList::startsWith(QList<T>::parameter_type value) const
如果该列表不为空,且其第一项等于value ,则返回true
;否则返回false
。
[noexcept]
void QList::swap(QList<T> &other)
将此列表与other 互换。该操作速度非常快,从未出现过故障。
void QList::swapItemsAt(qsizetype i, qsizetype j)
将索引位置i 上的项目与索引位置j 上的项目交换。该函数假定i 和j 至少为 0,但小于size()。为避免失败,请测试i 和j 是否都至少为 0 且小于size()。
T QList::takeAt(qsizetype i)
删除索引位置i 上的元素并返回。
等价于
T t = at(i); remove(i); return t;
QList<T>::value_type QList::takeFirst()
删除列表中的第一个项目并返回。该函数假定列表不是空的。为避免失败,请在调用此函数前调用isEmpty() 。
另请参阅 takeLast() 和removeFirst()。
QList<T>::value_type QList::takeLast()
删除列表中的最后一个项目并返回。此函数假定列表不为空。为避免失败,请在调用此函数前调用isEmpty() 。
如果不使用返回值,removeLast() 更有效。
另请参阅 takeFirst() 和removeLast()。
T QList::value(qsizetype i) const
返回列表中索引位置i 的值。
如果索引i 越界,函数将返回默认构造值。如果确定i 在界内,可以使用at() 代替,速度会稍快一些。
另请参阅 at() 和operator[]()。
T QList::value(qsizetype i, QList<T>::parameter_type defaultValue) const
这是一个重载函数。
如果索引i 越界,函数将返回defaultValue 。
bool QList::operator!=(const QList<T> &other) const
如果other 不等于此列表,则返回true
;否则返回false
。
如果两个列表以相同顺序包含相同的值,则视为相等。
此函数要求值类型具有operator==()
的实现。
另请参见 operator==()。
QList<T> &QList::operator+=(const QList<T> &other)
将other 列表中的项目追加到此列表,并返回此列表的引用。
[since 6.0]
QList<T> &QList::operator+=(QList<T> &&other)
这是一个重载函数。
该函数在 Qt 6.0 中引入。
QList<T> &QList::operator+=(QList<T>::parameter_type value)
这是一个重载函数。
将value 追加到列表中。
另请参阅 append() 和operator<<()。
QList<T> &QList::operator+=(QList<T>::rvalue_ref value)
这是一个重载函数。
另请参阅 append() 和operator<<()。
bool QList::operator<(const QList<T> &other) const
如果该列表在词法上小于 other ,则返回true
;否则返回false
。
该函数要求值类型具有operator<()
的实现。
QList<T> &QList::operator<<(QList<T>::parameter_type value)
将value 追加到列表中,并返回对该列表的引用。
另请参阅 append() 和operator+=()。
QList<T> &QList::operator<<(const QList<T> &other)
将other 追加到列表中,并返回列表引用。
[since 6.0]
QList<T> &QList::operator<<(QList<T> &&other)
这是一个重载函数。
该函数在 Qt 6.0 中引入。
QList<T> &QList::operator<<(QList<T>::rvalue_ref value)
这是一个重载函数。
另请参阅 append() 和operator+=()。
bool QList::operator<=(const QList<T> &other) const
如果该列表在词法上小于或等于 other ,则返回true
;否则返回false
。
该函数要求值类型具有operator<()
的实现。
[default]
QList<T> &QList::operator=(QList<T> &&other)
Move-assignsother 到此QList 实例。
[default]
QList<T> &QList::operator=(const QList<T> &other)
将other 赋值给此列表,并返回此列表的引用。
QList<T> &QList::operator=(std::initializer_list<T> args)
将args 中的值集合分配给此QList 实例。
bool QList::operator==(const QList<T> &other) const
如果other 与此列表相等,则返回true
;否则返回false
。
如果两个列表以相同顺序包含相同的值,则视为相等。
此函数要求值类型具有operator==()
的实现。
另请参见 operator!=()。
bool QList::operator>(const QList<T> &other) const
如果该列表在词法上大于 other ,则返回true
;否则返回false
。
该函数要求值类型具有operator<()
的实现。
bool QList::operator>=(const QList<T> &other) const
如果该列表在词法上大于或等于 other ,则返回true
;否则返回false
。
该函数要求值类型具有operator<()
的实现。
QList<T>::reference QList::operator[](qsizetype i)
以可修改引用的形式返回位于i 索引位置的项目。
i 必须是列表中有效的索引位置(即 0 <= < () )。i size
请注意,使用非const 操作符会导致QList 进行深度复制。
[noexcept]
QList<T>::const_reference QList::operator[](qsizetype i) const
这是一个重载函数。
与 at(i) 相同。
相关非会员
[since 6.1]
template <typename T, typename AT> qsizetype erase(QList<T> &list, const AT &t)
从列表list 中移除所有比较结果等于t 的元素。如果有,则返回移除元素的数量。
注意: 与QList::removeAll 不同,t 不允许引用list 中的元素。如果您不能确定情况并非如此,请复制一份t 并用该副本调用此函数。
此函数在 Qt 6.1 中引入。
另请参阅 QList::removeAll() 和erase_if 。
[since 6.1]
template <typename T, typename Predicate> qsizetype erase_if(QList<T> &list, Predicate pred)
从列表list 中删除谓词pred 返回 true 的所有元素。如果有,则返回已删除元素的数量。
此函数在 Qt 6.1 中引入。
另请参见 erase 。
[noexcept(...)]
template <typename T> size_t qHash(const QList<T> &key, size_t seed = 0)
返回key 的哈希值,使用seed 作为计算的种子。
qHash() 必须支持T
类型。
注: 当noexcept(qHashRange(key.cbegin(), key.cend(), seed))
为true
时,此函数为 noexcept。
template <typename T> QDataStream &operator<<(QDataStream &out, const QList<T> &list)
将列表list 写入流out 。
该函数要求值类型实现operator<<()
。
另请参阅 QDataStream 操作符的格式。
[since 6.9]
auto operator<=>(const QList<T> &lhs, const QList<T> &rhs)
按词法比较lhs 和rhs 的内容。如果operator<=>()
可用于T
类型,则返回适用类别类型最强的结果,即decltype(lhs[0] <=> rhs[0])
;否则返回std::weak_ordering
。
注: 此操作符仅在 C++20 模式下可用,且当底层类型T
模拟std::three_way_comparable
概念或提供operator<()
时可用。
此函数在 Qt 6.9 中引入。
template <typename T> QDataStream &operator>>(QDataStream &in, QList<T> &list)
从流in 中读取一个列表到list 中。
该函数要求值类型实现operator>>()
。
另请参阅 QDataStream 操作符的格式。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.