QList 类

成员函数文档

将列表的大小设置为 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 能够在列表数据的前端分配额外的内存，并在该方向上增长，而无需在每个操作中进行重新分配或移动数据。但是，如果您想使用保证 常数时间 prepend 的容器类，请使用 std::list，否则请使用 QList。

另请参阅 append() 和 insert。

为容器添加一个新元素到末尾。此新元素将使用 args 作为其构造的参数就地构造。

返回对新元素的双重引用。

示例

QList<QString> list{"one", "two"};
list.emplaceBack(3, 'a');
qDebug() << list;
// list: ["one", "two", "aaa"]

您还可以通过使用返回的双重引用来访问新创建的对象

QList<QString> list;
auto &ref = list.emplaceBack();
ref = "one";
// list: ["one"]

这相当于 list.emplace(list.size(), args)。

另请参阅 emplace。

在列表中的索引位置 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()。

这是一个重载函数。

在由迭代器 before 指向的项之前插入 value。返回指向插入项的迭代器。

用 value 代替索引位置 i 上的项。

i 必须是该列表中有效的索引位置（即，0 <= i < size()）。

另请参阅 operator[]() 和 remove()。

此函数提供了 STL 兼容性。它与 prepend(value) 等效。

返回一个列表，其中包含此列表中的所有项，后跟 other 列表中的所有项。

另请参阅 operator+=()。

QList::QList()

构造一个空列表。

另请参阅 resize()。

[显式] QList::QList(qsizetype size)

用大小为 size 的元素构造一个列表。

元素使用默认构造值初始化。

另请参阅 resize()。

QList::QList(qsizetype size, QList<T>::parameter_type value)

构建一个初始大小为size的列表。每个元素使用value初始化。

另请参阅resize() 和 fill().

QList::QList(std::initializer_list<T> args)

从由args给定的 std::initializer_list 构建一个列表。

template <typename InputIterator, QList<T>::if_input_iterator= true> QList::QList(InputIterator first, InputIterator last)

构建一个列表，其内容位于迭代器范围 [first, last] 中。

InputIterator的值类型必须可转换为T。

[默认] QList::QList(const QList<T> &other)

构建other的副本。

此操作需要常数时间，因为QList是隐式共享的。这使得从函数返回QList非常快。如果共享实例被修改，则将其复制（写时复制），这需要线性时间。

另请参阅operator=().

[默认] QList::QList(QList<T> &&other)

移动构造QList实例，使其指向other所指向的同一对象。

[默认] 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().

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+=().

[自6.0起] void QList::append(QList<T> &&value)

这是一个重载函数。

将value列表中的项目移动到本列表的末尾。

此功能是在 Qt 6.0 中引入的。

另请参阅operator<<() 和 operator+=().

[自6.6起] QList<T> &QList::assign(qsizetype n, QList<T>::parameter_type t)

使用t的n个副本替换本列表的内容。

本列表的大小将与n相等。

如果n超过列表的容量或此列表被共享，此函数将仅分配内存。

此函数是在Qt 6.6中引入的。

[自6.6起] 模板 <typename InputIterator, QList<T>::if_input_iterator= true> QList<T> &QList::assign(InputIterator first, InputIterator last)

使用迭代器范围 [first, last] 中的元素副本替换本列表的内容。

本列表的大小将与范围 [first, last] 中的元素数量相等。

如果范围内的元素数量超出本列表的容量或此列表被共享，此函数将仅分配内存。

此函数是在Qt 6.6中引入的。

[自6.6起] QList<T> &QList::assign(std::initializer_list<T> l)

使用l的元素副本替换本列表的内容。

本列表的大小将与l中的元素数量相等。

如果l中的元素数量超出本列表的容量或此列表被共享，此函数将仅分配内存。

此函数是在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样式迭代器。

另请参阅：constBegin() 和 end()。

[noexcept] QList<T>::const_iterator QList::begin() const

这是一个重载函数。

qsizetype QList::capacity() const

返回列表在不强制重新分配的情况下能存储的最大项目数。

该函数的唯一目的是提供对 QList 内存使用进行微调的手段。通常，您很少需要调用此函数。如果您想知道列表中有多少个项目，请调用 size。

另请参阅 reserve() 和 squeeze。

[noexcept] QList<T>::const_iterator QList::cbegin() const

返回指向列表中的第一个项目的常量 STL-style iterator。

另请参阅 begin() 和 cend。

[noexcept] QList<T>::const_iterator QList::cend() const

返回指向列表中最后一个项目之后的常量 STL-style iterator。

另请参阅 cbegin() 和 end。

void QList::clear()

从列表中删除所有元素。

如果此列表未共享，则保留 capacity()。使用 squeeze() 来释放多余容量。

另请参阅 resize() 和 squeeze。

[noexcept] QList<T>::const_iterator QList::constBegin() const

返回指向列表中的第一个项目的常量 STL-style iterator。

另请参阅 begin() 和 constEnd。

[noexcept] QList<T>::const_pointer QList::constData() const

返回指向列表中存储的数据的常量指针。该指针可以用来访问列表中的项。

此函数主要用于将列表传递给接受纯C++数组的函数。

另请参阅 data() 和 operator[]。

[noexcept] QList<T>::const_iterator QList::constEnd() const

返回指向列表中最后一个项目之后的常量 STL-style iterator。

另请参阅：constBegin() 和 end()。

[noexcept] const T &QList::constFirst() const

返回列表中第一个元素的const引用。此函数假定列表不为空。

另请参阅constLast，isEmpty和first。

[noexcept] const T &QList::constLast() const

返回列表中最后一个元素的const引用。此函数假定列表不为空。

另请参阅constFirst，isEmpty和last。

[noexcept] template <typename AT> bool QList::contains(const AT &value) const

如果列表包含value的实例，则返回true；否则返回false。

此函数需要值类型实现operator==()操作符。

另请参阅indexOf和count。

[noexcept] template <typename AT = T> qsizetype QList::count(const AT &value) const

返回列表中value出现的次数。

此函数需要值类型实现operator==()操作符。

另请参阅contains和indexOf。

[noexcept] qsizetype QList::count() const

这是一个重载函数。

与size相同。

[noexcept] QList<T>::const_reverse_iterator QList::crbegin() const

返回一个指向列表中第一个元素（逆序）的const STL-style反迭代器。

另请参阅begin，rbegin和rend。

[noexcept] QList<T>::const_reverse_iterator QList::crend() const

返回一个指向列表中最后一个元素之后（逆序）的const STL-style反迭代器。

另请参阅end，rend和rbegin。

QList<T>::pointer QList::data()

返回指向列表中存储数据的指针。该指针可用于访问和修改列表中的项。

示例

QList<int> list(10);
int *data = list.data();
for (qsizetype i = 0; i < 10; ++i)
    data[i] = 2 * i;

此函数主要用于将列表传递给接受纯C++数组的函数。

另请参阅constData和operator[]。

[noexcept] QList<T>::const_pointer QList::data() const

这是一个重载函数。

模板 <typename... Args> QList<T>::iterator QList::emplace(qsizetype i, Args &&... args)

通过在位置 i 插入新元素，扩展容器。此新元素使用 args 作为其构造参数就地构建。

返回新元素的迭代器。

示例

QList<QString> list{"a", "ccc"};
list.emplace(1, 2, 'b');
// list: ["a", "bb", "ccc"]

另请参阅：emplaceBack。

模板 <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风格迭代器。

另请参阅 begin() 和 constEnd。

[noexcept] QList<T>::const_iterator QList::end() const

这是一个重载函数。

bool QList::endsWith(QList<T>::parameter_type value) const

如果此列表不为空且其最后一个元素等于 value，则返回 true；否则返回 false。

另请参阅：isEmpty() 和 last。

QList<T>::iterator QList::erase(QList<T>::const_iterator pos)

从列表中移除由迭代器 pos 指向的元素，并返回列表中下一个元素的迭代器（这可能指向 end()）。

元素移除将保留列表的容量，并且不会减少分配的内存量。要释放额外的容量，并尽可能地释放内存，请调用 squeeze()。

另请参阅：insert() 和 remove。

QList<T>::iterator QList::erase(QList<T>::const_iterator begin, QList<T>::const_iterator 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()。

[noexcept] const T &QList::first() const

这是一个重载函数。

[since 6.0] QList<T> QList::first(qsizetype n) const

返回一个子列表，包含本列表的前 n 个元素。

此功能是在 Qt 6.0 中引入的。

另请参阅 last() 和 sliced()。

QList<T>::reference QList::front()

此函数提供以与 STL 兼容。它与 first() 相等。

[noexcept] QList<T>::const_preference QList::front() const

这是一个重载函数。

[noexcept] 模板 <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(qsizetype i, qsizetype count, QList<T>::parameter_type value)

这是一个重载函数。

在列表中索引位置 i 插入 value 的 count 个副本。

示例

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]

QList<T>::iterator QList::insert(QList<T>::const_iterator before, qsizetype count, QList<T>::parameter_type value)

在迭代器 before 指向的项之前插入 value 的 count 个副本。返回指向插入的第一个项的迭代器。

[noexcept] bool QList::isEmpty() const

如果列表大小为 0，则返回 true；否则返回 false。

另请参阅 size() 和 resize()。

T &QList::last()

返回列表中最后一个元素的引用。此函数假设列表不为空。

另请参见 first()，isEmpty() 和 constLast。

[noexcept] const T &QList::last() const

这是一个重载函数。

[since 6.0] QList<T> QList::last(qsizetype n) const

返回一个包含此列表最后 n 个元素的子列表。

此功能是在 Qt 6.0 中引入的。

另请参见 first() 和 sliced。

[noexcept] template <typename AT> qsizetype QList::lastIndexOf(const AT &value, qsizetype from = -1) const

返回值 value 在列表中的最后一个出现的位置索引，从索引位置 from 向后搜索。如果 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

相同于 size() 和 count。

另请参见 size() 和 count。

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。

[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风格的反向迭代器，元素顺序相反。

另请参阅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风格的反向迭代器，元素顺序相反。

另请参阅end()，crend()和rbegin()。

[无异常] QList<T>::const_reverse_iterator QList::rend() const

这是一个重载函数。

void QList::reserve(qsizetype size)

尝试为至少size个元素分配内存。

如果您事先知道列表的大小，应该调用此函数以防止重新分配和内存碎片化。如果您经常调整列表的大小，也可能会获得更好的性能。

如果不确定需要多少空间，通常最好将上界作为size，或者一个较高估计的预期大小，如果严格的界限会大得多。如果size低估，一旦超出预留的大小，列表将按需增长，这可能导致比最佳上估还要大的分配，并减慢触发它的操作。

另请参阅：squeeze()、capacity() 和 resize()。

void QList::shrink_to_fit()

此函数提供以与STL兼容。它等价于squeeze()。

[自6.0起] QList<T> QList::sliced(qsizetype pos, qsizetype n) const

返回列表中的元素数量。

另请参阅：isEmpty() 和 resize()。

[自6.0起] QList<T> QList::sliced(qsizetype pos) const

返回一个包含当前位置pos开始的列表中的n个元素的子列表。

此功能是在 Qt 6.0 中引入的。

另请参阅：first() 和 last()。

[自6.0起] QList<T> QList::sliced(qsizetype pos) const

这是一个重载函数。

返回一个包含从当前位置pos开始到最后一个元素的子列表。

此功能是在 Qt 6.0 中引入的。

另请参阅：first() 和 last()。

void QList::squeeze()

释放存储项目所不需要的任何内存。

此函数的唯一目的是提供一个用于微调QList内存使用的手段。通常，您几乎不需要调用此函数。

另请参阅：reserve() 和 capacity()。

bool QList::startsWith(QList<T>::parameter_type value) const

如果此列表不为空且其第一个项目等于 value，则返回 true；否则返回 false。

另请参阅 isEmpty() 和 first()。

[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;

另请参阅 takeFirst() 和 takeLast()。

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==()操作符。

另请参阅运算符==()。

QList<T> &QList::operator+=(const QList<T> &other)

将 other 列表中的项目添加到此列表中，并返回对此列表的引用。

另请参阅运算符+() 和 append()。

[自 6.0 版起] QList<T> &QList::operator+=(QList<T> &&other)

这是一个重载函数。

此功能是在 Qt 6.0 中引入的。

另请参阅运算符+() 和 append()。

QList<T> &QList::operator+=(QList<T>::parameter_type value)

这是一个重载函数。

将 value 添加到列表中。

另请参阅append() 和 运算符<<()。

QList<T> &QList::operator+=(QList<T>::rvalue_ref value)

这是一个重载函数。

另请参阅append() 和 运算符<<()。

bool QList::operator<(const QList<T> &other) const

如果此列表在字典序上小于 other，则返回 true；否则返回 false。

此函数要求值类型实现 operator<()。

QList<T> &QList::operator<<(QList<T>::parameter_type value)

将 value 添加到列表中，并返回对此列表的引用。

另请参阅append() 和 运算符+=()。

QList<T> &QList::operator<<(const QList<T> &other)

将 other 添加到列表中，并返回对此列表的引用。

[自 6.0 版起] QList<T> &QList::operator<<(QList<T> &&other)

这是一个重载函数。

此功能是在 Qt 6.0 中引入的。

QList<T> &QList::operator<<(QList<T>::rvalue_ref value)

这是一个重载函数。

另请参阅append() 和 运算符+=()。

bool QList::operator<=(const QList<T> &other) const

如果此列表在字典序上小于或等于 other，则返回 true；否则返回 false。

此函数要求值类型实现 operator<()。

QList<T> &QList::operator=(std::initializer_list<T> args)

将 args 中的值集合分配给此 QList 实例。

[默认] QList<T> &QList::operator=(const QList<T> &other)

将other赋值给当前列表，并返回当前列表的引用。

[默认] QList<T> &QList::operator=(QList<T> &&other)

将other移动赋值给当前QList实例。

bool QList::operator==(const QList<T> &other) const

如果other与当前列表相等，则返回true；否则返回false。

如果两个列表包含相同顺序的相同值，则认为它们相等。

此函数需要值类型实现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 Operator可能会导致当前QList执行深度复制。

另请参阅at()和value。

[noexcept] QList<T>::const_reference QList::operator[](qsizetype i) const

这是一个重载函数。

与at(i)相同。