QList类

关注

原创 2024-02-19 18:53:47 1.4k 阅读 AI 写同款· GEO 优化 ›

AI权益加码！Claude Code、Cursor等20+工具免费用！购周边限时加赠Coding Plan Lite，畅享主流AI工具！学习进阶更高效！阅读详情

QList 类是提供动态数组的模板类。

Header:	#include <QList>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake:	QT += core
Inherited By:	QBluetoothServiceInfo::Alternative QBluetoothServiceInfo::Sequence QByteArrayList QItemSelection QMqttUserProperties QNdefMessage QPolygon QPolygonF QQueue QSignalSpy QStack QStringList QTestEventList QVector QVulkanInfoVector QXmlStreamAttributes

所有成员的列表，包括继承的成员
已弃用的成员（官方不推荐使用）
QList 是隐式共享类的一部分。

Note: 此类中的所有函数都是可重入的。

【详细描述】

QList<T>是Qt的通用容器类。它将其项目存储在相邻的内存位置，并提供基于索引的快速访问。QVector<T>曾经是 Qt 5 中的一个不同类，但现在是 QList 的简单别名。

QList<T> 和 QVarLengthArray<T> 提供类似的 API 和功能。它们通常是可以互换的，但会带来性能后果。以下是用例概述：

QList 应该是您的默认首选。
QVarLengthArray提供一个数组，该数组在堆栈上预留空间，但可以在需要时动态增长到堆上。它非常适合用于通常很小的短寿命容器。
如果您需要一个真正的链表，它保证在列表中间持续插入，并使用迭代器而不是索引，请使用标准库std::list。

注意： QList和QVarLengthArray都保证了c兼容的阵列布局。Qt5中的QList并不总是具有与c兼容的数组布局，我们经常建议使用QVector来获得更可预测的性能。在Qt 6中已经不再是这样了，这两个类现在共享一个实现，可以互换使用。

下面是一个存储整数的QList和一个存储QString值的QList的例子：

QList<int> integerList;
QList<QString> stringList;

QList 将其项目存储在连续内存数组中。通常，列表是以初始大小创建的。例如，以下代码构造具有 200 个元素的 QList：

QList<QString> list(200);

这些元素会自动使用迭代容器default-constructed value。如果要使用其他值初始化列表，请将该值作为第二个参数传递给构造函数：

QList<QString> list(200, "Pass");

您也可以随时调用fill()来使用值填充列表。QList 使用从 0 开始的索引，就像 C++ 数组一样。若要访问特定索引位置的项，可以使用 operator[]()。在非常量列表上，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[]()快，因为它永远不会导致深拷贝 deep copy 发生。

访问存储在 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()之外，对于大型列表，这些函数（线性时间linear time）可能会很慢，因为它们需要将列表中的许多项目在内存中移动一个位置。如果您想要一个在中间提供快速插入/删除的容器类，请改用 std::list。

与普通 C++ 数组不同，QList 可以随时通过调用resize()来调整大小。如果新大小大于旧大小，则 QList 可能需要重新分配整个列表。QList 试图通过预分配两倍于实际数据需求的内存来减少重新分配的次数。

如果你正在逐步构建一个 QList，并且提前知道它将包含大约多少个元素，你可以调用reserve()，要求 QList 预分配一定数量的内存。您还可以调用capacity()来了解 QList 实际分配了多少内存。

请注意，因为隐式共享implicit sharing，使用非常量运算符和函数可能会导致 QList 对数据进行深度复制。

QList 的值类型必须是assignable data type（可分配数据类型），这涵盖了大多数常用的数据类型。

编译器不允许您将QWidget存储为值；但可以存储QWidget *。一些函数有额外的要求，例如indexOf() 和 lastIndexOf() 期望值类型支持operator==()。这些需求是根据功能来记录的。

有关遍历这些项的信息，请参见Iterating over Containers。

除了QList之外，Qt还提供了QVarLengthArray，这是一个非常低级的类，几乎没有针对速度进行优化的功能。

有关将 Qt 容器与 STL 容器进行比较的讨论，请参阅：Understand the Qt Containers。

最大空间和内存不足的情况

QList 的最大空间取决于体系结构。大多数 64 位系统可以分配超过 2 GB 的内存，典型限制为 2^63 字节。实际值还取决于管理数据块所需的开销。因此，在 32 位平台上，最大大小为 2 GB 减去开销，在 64 位平台上，最大大小为 2^63 字节减去开销。QList 中可以存储的元素数是此最大空间除以存储元素的尺寸。

当内存分配失败时，QList 使用宏Q_CHECK_PTR ，如果应用程序在异常std::bad_alloc支持下编译，则会引发异常。如果禁用异常，则内存不足是未定义的行为。

请注意，操作系统可能会对持有大量分配内存的应用程序施加进一步的限制，尤其是大型连续块。这些细节和任何缓解措施都超出了Qt API考虑的范围。

【公共类型】

class	const_iterator	为QList和QStack提供STL样式的常量迭代器。
class	iterator	为QList和QStack提供STL样式的非常量迭代器。
	ConstIterator	Qt样式的常量迭代器，与QList::const_iterator同义。
	Iterator	Qt样式的常量非迭代器，与QList::iterator同义。
	const_pointer	提供了与STL的兼容性。
	const_reference	提供了与STL的兼容性。
	const_reverse_iterator	提供STL 样式的常量反向迭代器。警告：隐式共享容器上迭代器的工作方式与 STL 迭代器不同。应避免迭代器在容器上处于活动状态时复制该容器。
	difference_type	提供了与STL的兼容性。
	parameter_type	/
	pointer	提供了与STL的兼容性。
	reference	提供了与STL的兼容性。
	reverse_iterator	提供STL 样式的非常量反向迭代器。（警告同上）
	rvalue_ref	/
	size_type	提供了与STL的兼容性。
	value_type	提供了与STL的兼容性。

【公有函数】

特别说明：

1. 以下函数中，返回的指针或迭代器在分离时或修改时会失效。

2. 涉及比较的函数（例如:搜索）要求值类型具有operator==()的实现。

3. QList为兼容STL提供了功能等价的函数，以下备注为：STL兼容。

4. 涉及元素删除的函数，都不会减少分配的内存量，要减少额外的容量和尽可能多的内存，调用 squeeze()。

空QList。	QList()
size个元素的QList。	QList(qsizetype size)
size个元素都用value初始化。	QList(qsizetype size, QList::parameter_type value)
args是std::initializer_list，用它初始化QList。	QList(std::initializer_list<T> args)
用迭代器范围[first, last)内的元素构造QList。	QList(InputIterator first, InputIterator last)
构造other的副本。返回非常快，因为QList 是隐式共享的，如果修改共享实例，才在写入时真正复制该实例，这需要线性时间。	QList(const QList<T> &other)
移动构造一个QList实例，使其与other指向同一对象。	QList(QList<T> &&other)
析构。	~QList()
void	append(QList::parameter_type value)
在QList末尾插入value。与调用 resize(size() + 1)并在最后写入新值相同，因为通常分配的内存比需要的多，所以操作速度较快。
void	append(QList::rvalue_ref value)
同上。
void	append(const QList<T> &value)
将value列表的项追加到此列表的末尾。
void	append(QList<T> &&value)
将value列表的项移动到此列表的末尾。
QList<T> &	assign(qsizetype n, QList::parameter_type t)
用n个t的副本替换此QList的内容，此时QList的大小将等于n。当n超过QList的容量或QList被共享时，此函数才会分配内存。
QList<T> &	assign(InputIterator first, InputIterator last)
将OList的内容替换为迭代器范围 [first, last)内元素的副本，此时QList的大小等于[first, last)范围内的元素。当范围内的元素数量超过QList的容量或QList被共享时，此函数才会分配内存。
QList<T> &	assign(std::initializer_list<T> l)
用/元素的副本替换QList的内容，QList大小将等于/中的元素数量。当/内的元素数量超过QList的容量或QList被共享时，此函数才会分配内存。
QList::const_reference	at(qsizetype i) const
返回QList索引位置 i 的项 (0 <= i < size())。
QList::reference	back()
STL兼容。等价于 last()。
QList::const_reference	back() const
重载的常版本。
QList::iterator	begin()
返回指向QList第一项的STL-style iterator。
QList::const_iterator	begin() const
重载的常版本。
qsizetype	capacity() const
无需强制重新分配内存前提下，返回可以在QList中存储的最大项数。这个函数的唯一目的是提供一种微调内存使用的方法。通常很少需要调用此函数。
QList::const_iterator	cbegin() const
返回指向QList第一项的常量STL-style iterator。
QList::const_iterator	cend() const
返回指向QList最后一项的常量STL-style iterator。
void	clear()
从QList删除所有元素。如果未共享此QList，则保留 capacity() ，使用squeeze()来减少多余的容量。注意：5.7之前的 Qt 版本中，此函数释放了QList使用的内存，而不是保留容量。
QList::const_iterator	constBegin() const
返回指向QList第一项的常量STL-style iterator。
QList::const_pointer	constData() const
返回指向QList存储的数据的常量指针。这个指针可用于访问QList中的项。此函数最常见的用法的是将QList传递给接受普通C++数组的函数。
QList::const_iterator	constEnd() const
返回一个指向QList最后一项的常量 STL-style iterator。
const T &	constFirst() const
返回对QList第一项的常量引用。此函数假定列表不为空。
const T &	constLast() const
返回对QList最后一项的常量引用。此函数假定列表不为空。
bool	contains(const AT &value) const
如果QList包含value返回true，否则返回false。
qsizetype	count(const AT &value) const
返回QList中value出现的次数。
qsizetype	count() const
重载，返回元素个数，等价于size()。
QList::const_reverse_iterator	crbegin() const
返回一个STL样式的常量反向迭代器，该迭代器以相反的顺序指向QList的第一项。
QList::const_reverse_iterator	crend() const
返回一个STL样式的常量反向迭代器，该迭代器以相反的顺序指向QList的最后一项之后。
QList::pointer	data()
返回指向存储在QList中的数据的指针。指针可用于访问和修改列表中的项。此函数常见用途是将QList传递给接受普通 C++ 数组的函数。
QList::const_pointer	data() const
重载的常版本。
QList::iterator	emplace(qsizetype i, Args &&... args)
使用args作为构造的参数，在 i 位置插入新元素来扩展容器，这个新元素是就地构造的，返回新元素的迭代器。
QList::iterator	emplace(QList::const_iterator before, Args &&... args)
在 before 迭代器指向的项前面创建一个新元素。这个新元素是就地构造的，args 用作其构造的参数。返回新元素的迭代器。
QList::reference	emplaceBack(Args &&... args)
QList::reference	emplace_back(Args &&... args)
将一个新元素添加到QList容器的末尾。这个新元素是就地构造的，args用作其构造的参数。
bool	empty() const
STL兼容。等价于 isEmpty()，如果列表为空则返回true，否则返回false。
QList::iterator	end()
返回列表中最后一项之后（尾后）的指针。
QList::const_iterator	end() const
这是一个重载函数。
bool	endsWith(QList::parameter_type value) const
如果QList不为空，并且其最后一项等于value，则返回true，否则返回false。
QList::iterator	erase(QList::const_iterator pos)
从QList删除迭代器pos指向的项，并返回QList中的下一项（可能是end()）的迭代器。注意：当QList没有隐式共享时，此函数只使指定位置或之后的迭代器无效。
QList::iterator	erase(QList::const_iterator begin, QList::const_iterator end)
删除begin—end（但不包括）中的所有元素。返回调用之前end项的相同迭代器。注意：同上。
QList<T> &	fill(QList::parameter_type value, qsizetype size = -1)
分配value值给QList的所有项目。如果size不是默认值 -1，则列表大小将提前调整为size。
T &	first()
返回对QList第一项的引用。此函数假定QList不为空。
const T &	first() const
重载的常版本。
QList<T>	first(qsizetype n) const
返回一个包含该QList前n个元素的子列表。注意：n < 0 或 n > size()的行为未定义。
QList::reference	front()
STL兼容。等价于first()。
QList::const_reference	front() const
重载的常版本。
qsizetype	indexOf(const AT &value, qsizetype from = 0) const
返回QList中第一个出现的value值的索引位置，从中的索引位置from向前搜索。如果没有项匹配，则返回-1。
QList::iterator	insert(qsizetype i, QList::parameter_type value)
QList::iterator	insert(qsizetype i, QList::rvalue_ref value)
在QList的索引位置 i 处插入value值的副本。如果 i 为 0，则该值将追加到列表前面。如果 i 为size()，则该值将追加到列表中。对于大型列表，此操作可能很慢（线性时间），因为它需要将索引处和之后的所有项在内存中再移动一个位置。如果需要提供快速 insert() 函数的容器类，请改用std::list。
QList::iterator	insert(qsizetype i, qsizetype count, QList::parameter_type value)
在QList的索引位置 i 处插入count个value值的副本。
QList::iterator	insert(QList::const_iterator before, qsizetype count, QList::parameter_type value)
在迭代器before指向的项前面插入count个value值的副本。返回指向第一个插入项的迭代器。
QList::iterator	insert(QList::const_iterator before, QList::rvalue_ref value)
QList::iterator	insert(QList::const_iterator before, QList::parameter_type value)
插入value到迭代器before指向的项前面。返回指向插入项的迭代器。
bool	isEmpty() const
QList大小为 0返回true，否则返回false。
T &	last()
返回对QList最后一项的引用。此函数假定QList不为空。
const T &	last() const
重载的常版本。
QList<T>	last(qsizetype n) const
返回包含QList最后n个元素的子列表。 n < 0或n > size()的行为未定义。
qsizetype	lastIndexOf(const AT &value, qsizetype from = -1) const
返回QList中value值的索引位置，从from开始向前搜索，如果 from为-1（默认），搜索从最后一项开始。如果没有找到匹配项，则返回-1。
qsizetype	length() const
与size() 和count()相同。
QList<T>	mid(qsizetype pos, qsizetype length = -1) const
返回一个子列表，其中包含QList中的元素，从位置pos开始。如果长度为-1（默认值），则包含pos之后的所有元素；否则包括length个元素（或小于length的所有剩余元素）。
void	move(qsizetype from, qsizetype to)
将索引位置from处的项目从索引位置移动到to。
void	pop_back()
STL兼容。等价于removeLast()。
void	pop_front()
STL兼容。等价于removeFirst()。
void	prepend(QList::rvalue_ref value)
void	prepend(QList::parameter_type value)
插入到QList的开头，等价于list.insert(0, value)。通常此操作相对较快（摊销固定时间），QList能够在列表数据的开头分配额外的内存，并沿着这个方向增长，而此无需重新分配或移动每个操作上的数据。如果您想要一个保证恒定时间开销的容器，请使用std::list，否则QList更佳。
void	push_back(QList::parameter_type value)
void	push_back(QList::rvalue_ref value)
STL兼容。它等效于 append()。
void	push_front(QList::rvalue_ref value)
void	push_front(QList::parameter_type value)
STL兼容。等价于 prepend()。
QList::reverse_iterator	rbegin()
返回指向列表中第一项的Stl样式的反向迭代器。
QList::const_reverse_iterator	rbegin() const
重载的常版本。
void	remove(qsizetype i, qsizetype n = 1)
从QList中删除n个元素，从索引位置i开始。
qsizetype	removeAll(const AT &t)
从QList中删除所有值等于t的元素。返回删除元素的数量。
void	removeAt(qsizetype i)
删除索引位置 i 的元素。相当于 remove(i);
void	removeFirst()
删除QList中的第一项。此函数等效于remove(i)。该列表不能为空，如果列表可能为空，请在此函数之前调用isEmpty()检查。
qsizetype	removeIf(Predicate pred)
从列表中删除谓词 pred 返回 true 的所有元素。返回删除的元素数量（如果有）。
void	removeLast()
删除QList中的最后一项。此函数等效于remove(size() - 1)。该列表不能为空，如果列表可能为空，请在此函数之前调用isEmpty()检查。
bool	removeOne(const AT &t)
从QList中删除等于 t 的第一个元素。返回是否有元素被删除。
QList::reverse_iterator	rend()
返回一个STL-style的反向迭代器，该迭代器指向列表中的最后一项之后。
QList::const_reverse_iterator	rend() const
重载的常版本。
void	replace(qsizetype i, QList::parameter_type value)

void	replace(qsizetype i, QList::rvalue_ref value)

void	reserve(qsizetype size)
尝试分配size个元素的内存。如果事先知道QList将有多大，则应该调用这个函数，以防止重新分配和内存碎片。如果您经常调整QList大小，也可以通过这个函数获得更好的性能。如果对需要多少空间有疑问，通常最好使用一个上限作为大小，或者使用高于最有可能的大小。如果大小被低估，一旦超过保留大小，QList将根据需要增长，这可能导致比您高估的尺寸更大的内存分配，并花费额外的时间。警告：reserve()仅分配内存，但不会更改QList的size。
void	resize(qsizetype size)
void	resize(qsizetype size, QList::parameter_type c)
将列表的大小设置为 size 。如果大于当前大小，则将原有元素添加到末尾，新元素使用默认构造值default-constructed value或 c 进行初始化。如果小于当前大小，则从末尾删除元素。
void	shrink_to_fit()
STL兼容。等价于释放冗余内存 squeeze()。
qsizetype	size() const
返回QList的项数。
QList<T>	sliced(qsizetype pos, qsizetype n) const
返回一个包含n个元素的子列表，从位置pos开始。pos < 0, n < 0或 pos + n > size()的行为未定义。
QList<T>	sliced(qsizetype pos) const
返回一个子列表，从位置pos开始直到最后。pos < 0或 pos > size()的行为未定义。
void	squeeze()
释放存储项不需要的冗余内存。这个函数的唯一目的是提供一种微调内存使用的方法。通常很少需要调用此函数。
bool	startsWith(QList::parameter_type value) const
如果此列表不为空，并且其第一项等于value，则返回true，否则返回false。
void	swap(QList<T> &other)
交换other列表与此列表。此操作非常快且不会失败。
void	swapItemsAt(qsizetype i, qsizetype j)
将i位置的项与j位置的项交换。此函数假定i和j都大于等于0并小于size。为避免失败，使用前请测试i,j。
T	takeAt(qsizetype i)
删除索引位置 i 的元素并返回它。相当于：T t = at(i); remove(i); return t;
QList::value_type	takeFirst()
删除列表中的第一项并返回它。此函数假定列表不为空。为避免失败，请在调用此函数之前调用isEmpty()。
QList::value_type	takeLast()
删除列表中的最后一项并返回它。此函数假定列表不为空。为避免失败，请在调用此函数之前调用isEmpty()。如果不使用返回值，则removeLast() 效率更高。
T	value(qsizetype i) const
返回列表中索引 i 位置的值。如果索引越界，则该函数返回一个 default-constructed value（默认构造值），如果您确定在边界内，则可以改用at()，这会快一些。
T	value(qsizetype i, QList::parameter_type defaultValue) const
重载的常版本。如果索引越界，则该函数返回未定义的值。
bool	operator!=(const QList<T> &other) const
QList<T>	operator+(const QList<T> &other) const &
QList<T>	operator+(const QList<T> &other) &&
QList<T>	operator+(QList<T> &&other) const &
QList<T>	operator+(QList<T> &&other) &&
QList<T> &	operator+=(const QList<T> &other)
QList<T> &	operator+=(QList<T> &&other)
QList<T> &	operator+=(QList::parameter_type value)
QList<T> &	operator+=(QList::rvalue_ref value)
bool	operator<(const QList<T> &other) const
QList<T> &	operator<<(QList::parameter_type value)
QList<T> &	operator<<(const QList<T> &other)
QList<T> &	operator<<(QList<T> &&other)
QList<T> &	operator<<(QList::rvalue_ref value)
bool	operator<=(const QList<T> &other) const
QList<T> &	operator=(std::initializer_list<T> args)
QList<T> &	operator=(const QList<T> &other)
QList<T> &	operator=(QList<T> &&other)
bool	operator==(const QList<T> &other) const
bool	operator>(const QList<T> &other) const
bool	operator>=(const QList<T> &other) const
QList::reference	operator[](qsizetype i)
QList::const_reference	operator[](qsizetype i) const

qsizetype	erase(QList<T> &list, const AT &t)
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)
QDataStream &	operator>>(QDataStream &in, QList<T> &list)