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 |
- 所有成员的列表，包括继承的成员
- 已弃用的成员（官方不推荐使用）
- 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 | |
| ConstIterator | Qt样式的常量迭代器，与QList::const_iterator同义。 | |
| Iterator | Qt样式的常量非迭代器，与QList::iterator同义。 | |
| const_pointer | 提供了与STL的兼容性。 | |
| const_reference | 提供了与STL的兼容性。 | |
| const_reverse_iterator | 提供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) |
扫一扫
4773
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
