Класс QList

Класс QList — это шаблонный класс, предоставляющий динамический массив. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются повторно-входными.

Типы

Публичные функции

Статические публичные члены

Связанные нечлены

Подробное описание

QList<T> — это один из обобщённых классов контейнеров Qt. Он хранит свои элементы в смежных областях памяти и обеспечивает быстрый доступ по индексу. QVector<T> раньше был отдельным классом в Qt 5, но теперь является простым псевдонимом QList.

QList<T> и QVarLengthArray<T> предоставляют схожие API и функциональность. Часто они взаимозаменяемы, но существуют последствия для производительности. Вот обзор вариантов использования:

• QList — ваш первый выбор по умолчанию.
• QVarLengthArray предоставляет массив, который резервирует память в стеке, но может динамически увеличиваться в куче при необходимости. Это хорошо подходит для контейнеров, которые существуют недолго и обычно небольшие.
• Если вам нужна настоящая связанный список, который гарантирует постоянное время вставок в середину списка и использует итераторы к элементам, а не индексы, используйте std::list.

Примечание: QList и QVarLengthArray оба гарантируют совместимость с массивами C.

Примечание: QList в Qt 5 не всегда имел совместимость с массивами C, и мы часто рекомендовали использовать QVector вместо этого для более предсказуемой производительности. Это больше не актуально в Qt 6, где оба класса теперь используют одну реализацию и могут использоваться взаимозаменяемо.

Вот пример QList, хранящий целые числа, и QList, хранящий значения QString:

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

QList хранит свои элементы в массиве непрерывной памяти. Обычно списки создаются с начальным размером. Например, следующий код создаёт QList с 200 элементами:

QList<QString> list(200);

Элементы автоматически инициализируются с значением по умолчанию. Если вы хотите инициализировать список другим значением, передайте это значение в качестве второго аргумента конструктору:

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

Также можно в любой момент вызвать fill() для заполнения списка значением.

QList использует индексы с нуля, как и массивы C++. Для доступа к элементу по определённому индексу можно использовать оператор[](). Для неконстантных списков оператор[]() возвращает ссылку на элемент, который можно использовать слева от оператора присваивания:

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 << Qt::endl;
}

at() может быть быстрее, чем оператор[](), потому что он никогда не вызывает глубокую копию.

Ещё один способ доступа к данным в QList — вызвать data(). Функция возвращает указатель на первый элемент в списке. Указатель можно использовать для прямого доступа и изменения элементов, хранящихся в списке. Указатель также полезен, если нужно передать QList в функцию, которая принимает обычный массив C++.

Если нужно найти все вхождения определённого значения в список, используйте indexOf() или lastIndexOf(). Первый ищет вперёд, начиная с заданного индекса, второй — назад. Оба возвращают индекс совпадающего элемента, если он найден; в противном случае возвращают -1. Например:

qsizetype i = list.indexOf("Harumi");
if (i != -1)
    cout << "First occurrence of Harumi is at position " << i << Qt::endl;

Если нужно просто проверить, содержит ли список определённое значение, используйте contains(). Если нужно узнать, сколько раз встречается определённое значение в списке, используйте count().

QList предоставляет эти основные функции для добавления, перемещения и удаления элементов: insert(), replace(), remove(), prepend(), append(). За исключением append(), prepend() и replace(), эти функции могут быть медленными (линейное время) для больших списков, так как они требуют перемещения многих элементов в списке на одну позицию в памяти. Если нужен класс контейнера, который обеспечивает быструю вставку/удаление посередине, используйте std::list.

В отличие от обычных массивов C++, размер QList можно изменять в любой момент, вызывая resize(). Если новый размер больше старого, QList может потребовать перераспределения всего списка. QList пытается уменьшить количество перераспределений, предварительно выделяя до дважды больше памяти, чем необходимо для фактических данных.

Если вы постепенно создаёте QList и заранее знаете приблизительное количество элементов, можно вызвать reserve(), попросив QList предварительно выделить определённое количество памяти. Также можно вызвать capacity() для получения информации о фактически выделенной памяти QList.

Обратите внимание, что использование неконстантных операторов и функций может привести к тому, что QList выполнит глубокую копию данных из-за неявного совместного использования.

Тип значения QList должен быть типом, допускающим присваивание. Это охватывает большинство типов данных, которые обычно используются, но компилятор не позволит, например, хранить QWidget как значение; вместо этого храните QWidget *. Некоторые функции имеют дополнительные требования; например, indexOf() и lastIndexOf() ожидают, что тип значения поддерживает operator==(). Эти требования документированы для каждой функции.

Как и другие классы контейнеров, QList предоставляет итераторы в стиле Java (QListIterator и QMutableListIterator) и итераторы в стиле STL (QList::const_iterator и QList::iterator). На практике итераторы полезны при работе с общими алгоритмами, предоставляемыми Qt и стандартной библиотекой C++. Итераторы в стиле Java предоставляются для обратной совместимости, предпочитайте итераторы в стиле STL при написании кода C++.

Примечание: Итераторы над QList, а также ссылки на отдельные элементы внутри него, не гарантируют сохранение корректности после вызова любой неконстантной функции QList. Обращение к такому итератору или ссылке после вызова неконстантной функции приводит к неопределённому поведению. Если требуется стабильность функциональности типа итератора, используйте индексы вместо итераторов, так как они не привязаны к внутреннему состоянию QList и, следовательно, не становятся недействительными.

Помимо QList, Qt также предоставляет QVarLengthArray, очень низкоуровневый класс с небольшим функционалом, оптимизированный для скорости.

Дополнительная информация об использовании контейнеров Qt

Для подробного обсуждения сравнения контейнеров Qt друг с другом и с контейнерами STL см. Понимание контейнеров Qt.

Максимальный размер и условия недостатка памяти

Максимальный размер QList зависит от архитектуры. Большинство 64-битных систем могут выделять более 2 ГБ памяти, с типичным пределом в 2^63 байта. Фактическое значение также зависит от накладных расходов, необходимых для управления блоком данных. В результате можно ожидать максимальный размер 2 ГБ за вычетом накладных расходов на 32-битных платформах и 2^63 байта за вычетом накладных расходов на 64-битных платформах. Количество элементов, которые могут быть сохранены в QList, равно максимальному размеру, делённому на размер хранимого элемента.

При сбое выделения памяти QList использует макрос Q_CHECK_PTR, который выбрасывает исключение std::bad_alloc если приложение компилируется с поддержкой исключений. Если исключения отключены, исчерпание памяти является неопределённым поведением.

Обратите внимание, что операционная система может накладывать дополнительные ограничения на приложения, удерживающие много выделенной памяти, особенно большие непрерывные блоки. Такие соображения, конфигурация такого поведения или любые меры по смягчению не входят в сферу применения API Qt.

Документация по типам членов

[alias] QList::ConstIterator

Синоним в стиле Qt для QList::const_iterator.

[alias] QList::Iterator

Синоним в стиле Qt для QList::iterator.

[alias] QList::const_pointer

Предоставлено для совместимости со STL.

[alias] QList::const_reference

Предоставлено для совместимости со STL.

[alias, since 5.6] QList::const_reverse_iterator

QList::const_reverse_iterator предоставляет итератор обратного перебора в стиле STL для QList.

Предупреждение: Итераторы неявно совместно используемых контейнеров не работают точно как итераторы STL. Следует избегать копирования контейнера, пока активны итераторы над этим контейнером. Подробнее см. Проблема с итераторами при неявном совместном использовании.

Предупреждение: Итераторы становятся недействительными при изменении QList. Учитывайте, что все итераторы становятся недействительными по умолчанию. Исключения из этого правила документированы явно.

Этот псевдоним был введён в Qt 5.6.

См. также 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, since 5.6] QList::reverse_iterator

Тип QList::reverse_iterator предоставляет итератор обратного обхода (непостоянный) в стиле STL для QList.

Предупреждение: Итераторы в неявных общих контейнерах не работают точно как STL-итераторы. Следует избегать копирования контейнера, пока итераторы активны в этом контейнере. Для получения дополнительной информации прочитайте Проблему итератора неявного совместного использования.

Предупреждение: Итераторы становятся недействительными при изменении QList. Помните, что все итераторы по умолчанию становятся недействительными. Исключения из этого правила документированы отдельно.

Этот typedef был введен в Qt 5.6.

См. также QList::rbegin(), QList::rend(), QList::const_reverse_iterator и QList::iterator.

[alias] QList::rvalue_ref

[alias] QList::size_type

Предоставлено для совместимости со STL.

[alias] QList::value_type

Предоставлено для совместимости со STL.

Документация по членам-функциям

Эта функция предоставлена для совместимости со STL. Она эквивалентна prepend(value).

Заменяет элемент с индексом i значением value.

i должен быть допустимым индексом в списке (т.е., 0 <= i < size()).

См. также operator[]() и remove().

Это перегруженная функция.

Вставляет value перед элементом, на который указывает итератор before. Возвращает итератор, указывающий на вставленный элемент.

Вставляет value в позицию с индексом i в списке. Если i равно 0, значение вставляется в начало списка. Если i равно size(), значение вставляется в конец списка.

Пример:

QList<QString> list;
list << "alpha" << "beta" << "delta";
list.insert(2, "gamma");
// list: ["alpha", "beta", "gamma", "delta"]

Для больших списков эта операция может быть медленной (линейное время), так как требует перемещения всех элементов с индексами i и выше на одну позицию дальше в памяти. Если вам нужен класс контейнера, который предоставляет быструю функцию insert(), используйте std::list вместо него.

См. также append(), prepend() и remove().

Добавляет новый элемент в конец контейнера. Новый элемент создается на месте с использованием 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.

Вставляет 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().

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

Создаёт копию other.

Эта операция занимает постоянное время, так как QList является неявно-совместным. Это делает возвращение QList из функции очень быстрым. Если изменён общий экземпляр, он будет скопирован (copy-on-write), что занимает линейное время.

См. также operator=().

[default, since 5.2] QList::QList(QList<T> &&other)

Создаёт QList из other с перемещением, указывая на тот же объект, на который указывал other.

Эта функция была введена в Qt 5.2.

[since 5.14] template <typename InputIterator> QList::QList(InputIterator first, InputIterator last)

Создаёт список с содержимым в диапазоне итераторов [first, last).

Тип значения InputIterator должен быть преобразуем в T.

Эта функция была введена в Qt 5.14.

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

Создаёт список из std::initializer_list, заданной args.

QList::QList(qsizetype size, QList::parameter_type value)

Создаёт список с начальным размером size элементов. Каждый элемент инициализируется значением value.

См. также resize() и fill().

QList::QList(qsizetype size)

Создаёт список с начальным размером size элементов.

Элементы инициализируются с помощью значения по умолчанию.

См. также resize().

QList::QList()

Создаёт пустой список.

См. также resize().

[default, since 5.2] QList<T> &QList::operator=(QList<T> &&other)

Присваивает other этому экземпляру QList с перемещением.

Эта функция была введена в Qt 5.2.

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

Присваивает other этому списку и возвращает ссылку на этот список.

[default] QList::~QList()

Удаляет список.

void QList::append(QList::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 5.6] void QList::append(QList::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: ""

Этот метод был добавлен в Qt 5.6.

[since 5.5] void QList::append(const QList<T> &value)

Это перегруженный метод.

Добавляет элементы списка value в конец этого списка.

Этот метод был добавлен в Qt 5.5.

См. также operator<<() и operator+=().

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

Это перегруженный метод.

Перемещает элементы списка value в конец этого списка.

Этот метод был добавлен в Qt 6.0.

См. также operator<<() и operator+=().

QList::const_reference QList::at(qsizetype i) const

Возвращает элемент по индексу i в списке.

i должен быть допустимым индексом в списке (т.е., 0 <= i < size()).

См. также value() и operator[]().

QList::reference QList::back()

Этот метод предоставлен для совместимости со STL. Он эквивалентен last().

QList::const_reference QList::back() const

Это перегруженный метод.

QList::iterator QList::begin()

Возвращает итератор STL, указывающий на первый элемент в списке.

Предупреждение: Итератор становится недействительным при отсоединении или модификации списка QList.

См. также constBegin() и end().

QList::const_iterator QList::begin() const

Это перегруженный метод.

qsizetype QList::capacity() const

Возвращает максимальное количество элементов, которое может храниться в списке без принудительной переаллокации.

Этот метод предназначен только для тонкой настройки использования памяти в QList. Обычно вы не будете использовать этот метод. Если вам нужно узнать, сколько элементов в списке, используйте size().

Примечание: Статически выделенный список сообщит емкость 0, даже если он не пустой.

Примечание: Позиция свободного места в блоке выделенной памяти не определена. Другими словами, не следует предполагать, что свободная память всегда расположена после инициализированных элементов.

См. также reserve() и squeeze().

[since 5.0] QList::const_iterator QList::cbegin() const

Возвращает константный итератор STL, указывающий на первый элемент в списке.

Предупреждение: Итератор становится недействительным при отсоединении или модификации списка QList.

Этот метод был добавлен в Qt 5.0.

См. также begin() и cend().

[since 5.0] QList::const_iterator QList::cend() const

Возвращает константный итератор STL, указывающий сразу после последнего элемента в списке.

Предупреждение: Итератор становится недействительным при отсоединении или модификации списка QList.

Этот метод был добавлен в Qt 5.0.

См. также cbegin() и end().

void QList::clear()

Удаляет все элементы из списка.

Примечание: До Qt 5.6, это также освобождало память, используемую списком. С Qt 5.7 емкость сохраняется. Чтобы освободить всю емкость, выполните swap со списком, созданным по умолчанию:

QList<T> l ...;
QList<T>().swap(l);
Q_ASSERT(l.capacity() == 0);

или вызовите squeeze().

См. также squeeze().

QList::const_iterator QList::constBegin() const

Возвращает константный итератор STL, указывающий на первый элемент в списке.

Предупреждение: Итератор становится недействительным при отсоединении или модификации списка QList.

См. также begin() и constEnd().

QList::const_pointer QList::constData() const

Возвращает константный указатель на данные, хранящиеся в списке. Указатель может быть использован для доступа к элементам в списке.

Предупреждение: Указатель становится недействительным при отсоединении или модификации списка QList.

Этот метод в основном полезен для передачи списка в функцию, принимающую обычный массив C++.

См. также data() и operator[]().

QList::const_iterator QList::constEnd() const

Возвращает константный итератор STL, указывающий сразу после последнего элемента в списке.

Предупреждение: Итератор становится недействительным при отсоединении или модификации списка QList.

См. также constBegin() и end().

[since 5.6] const T &QList::constFirst() const

Возвращает константную ссылку на первый элемент в списке. Предполагается, что список не пустой.

Этот метод был добавлен в Qt 5.6.

См. также constLast(), isEmpty() и first().

[since 5.6] const T &QList::constLast() const

Возвращает константную ссылку на последний элемент в списке. Предполагается, что список не пустой.

Этот метод был добавлен в Qt 5.6.

См. также constFirst(), isEmpty() и last().

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

Возвращает true если список содержит вхождение value; в противном случае возвращает false.

Для этого метода тип значения должен иметь реализацию operator==().

См. также indexOf() и count().

template <typename AT> qsizetype QList::count(const AT &value) const

Возвращает количество вхождений value в списке.

Для этого метода тип значения должен иметь реализацию operator==().

См. также contains() и indexOf().

qsizetype QList::count() const

Это перегруженный метод.

То же самое, что и size().

[since 5.6] QList::const_reverse_iterator QList::crbegin() const

Возвращает константный обратный итератор STL, указывающий на первый элемент в списке в обратном порядке.

Предупреждение: Итератор становится недействительным при отсоединении или модификации списка QList.

Этот метод был добавлен в Qt 5.6.

См. также begin(), rbegin() и rend().

[since 5.6] QList::const_reverse_iterator QList::crend() const

Возвращает константный обратный итератор STL, указывающий сразу после последнего элемента в списке в обратном порядке.

Предупреждение: Итератор становится недействительным при отсоединении или модификации списка QList.

Этот метод был добавлен в Qt 5.6.

См. также end(), rend() и rbegin().

QList::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[]().

QList::const_pointer QList::data() const

Это перегруженный метод.

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

Расширяет контейнер, вставляя новый элемент в позицию i. Новый элемент создается на месте с использованием args в качестве аргументов для его создания.

Возвращает итератор на новый элемент.

Пример:

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

Примечание: Гарантируется, что элемент будет создан на месте в начале, но после этого он может быть скопирован или перемещен в правильную позицию.

См. также emplaceBack.

template <typename Args> QList::iterator QList::emplace(QList::const_iterator before, Args &&... args)

Это перегруженный метод.

Создаёт новый элемент перед элементом, на который указывает итератор before. Новый элемент конструируется на месте с использованием args в качестве аргументов для его создания.

Возвращает итератор на новый элемент.

bool QList::empty() const

Этот метод предоставлен для совместимости со STL. Он эквивалентен методу isEmpty(), возвращая true если список пустой, иначе возвращает false.

QList::iterator QList::end()

Возвращает итератор STL, указывающий сразу после последнего элемента в списке.

Предупреждение: Возвращённый итератор становится недействительным при отсоединении или при изменении списка QList.

См. также begin() и constEnd().

QList::const_iterator QList::end() const

Это перегруженный метод.

bool QList::endsWith(QList::parameter_type value) const

Возвращает true если список не пустой и его последний элемент равен value; иначе возвращает false.

См. также isEmpty() и last().

QList::iterator QList::erase(QList::const_iterator pos)

Удаляет элемент, на который указывает итератор pos из списка и возвращает итератор на следующий элемент в списке (который может быть end()).

Удаление элементов сохранит ёмкость списка и не уменьшит выделенную память. Чтобы освободить избыточную ёмкость и освободить как можно больше памяти, вызовите squeeze().

Примечание: Когда QList не является неявно разделяемым, этот метод делает недействительными только итераторы, стоящие на позиции, равной или большей заданной.

См. также insert() и remove().

QList::iterator QList::erase(QList::const_iterator begin, QList::const_iterator end)

Это перегруженный метод.

Удаляет все элементы от begin до (но не включая) end. Возвращает итератор, указывающий на тот же элемент, на который указывает end до вызова.

Удаление элементов сохранит ёмкость списка и не уменьшит выделенную память. Чтобы освободить избыточную ёмкость и освободить как можно больше памяти, вызовите squeeze().

Примечание: Когда QList не является неявно разделяемым, этот метод делает недействительными только итераторы, стоящие на позиции, равной или большей заданной.

QList<T> &QList::fill(QList::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().

const T &QList::first() const

Это перегруженный метод.

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

Возвращает подсписок, содержащий первые n элементов этого списка.

Примечание: Поведение не определено, когда n < 0 или n > size().

Этот метод был введён в Qt 6.0.

См. также last() и sliced().

QList::reference QList::front()

Этот метод предоставлен для совместимости со STL. Он эквивалентен методу first().

QList::const_reference QList::front() const

Это перегруженный метод.

template <typename AT> qsizetype QList::indexOf(const AT &value, qsizetype from = 0) const

Возвращает индекс первого вхождения value в списке, начиная с позиции from. Возвращает -1, если элемент не найден.

Пример:

QList<QString> list;
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::iterator QList::insert(qsizetype i, qsizetype count, QList::parameter_type value)

Это перегруженный метод.

Вставляет count копий value на индексе i в списке.

Пример:

QList<double> list;
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::iterator QList::insert(QList::const_iterator before, qsizetype count, QList::parameter_type value)

Вставляет count копий value перед элементом, на который указывает итератор before. Возвращает итератор, указывающий на первый из вставленных элементов.

bool QList::isEmpty() const

Возвращает true если размер списка равен 0, иначе возвращает false.

См. также size() и resize().

T &QList::last()

Возвращает ссылку на последний элемент в списке. Этот метод предполагает, что список не пустой.

См. также first(), isEmpty(), и constLast().

const T &QList::last() const

Это перегруженный метод.

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

Возвращает подсписок, содержащий последние n элементов этого списка.

Примечание: Поведение не определено, когда n < 0 или n > size().

Этот метод был введён в Qt 6.0.

См. также first() и sliced().

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

Возвращает индекс последнего вхождения value в списке, просматривая элементы назад от позиции from. Если from равно -1 (по умолчанию), поиск начинается с последнего элемента. Возвращает -1, если элемент не найден.

Пример:

QList<QString> list;
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().

[since 5.2] qsizetype QList::length() const

То же, что и size() и count().

Этот метод был введён в Qt 5.2.

См. также size() и count().

QList<T> QList::mid(qsizetype pos, qsizetype length = -1) const

Возвращает подсписок, содержащий элементы из этого списка, начиная с позиции pos. Если length равно -1 (по умолчанию), включаются все элементы после pos; иначе включаются length элементов (или все оставшиеся, если их меньше, чем length).

[since 5.6] void QList::move(qsizetype from, qsizetype to)

Перемещает элемент на индексе from на индекс to.

Этот метод был введён в Qt 5.6.

void QList::pop_back()

Этот метод предоставлен для совместимости со STL. Он эквивалентен методу removeLast().

void QList::pop_front()

Этот метод предоставлен для совместимости со STL. Он эквивалентен методу removeFirst().

void QList::push_back(QList::parameter_type value)

Этот метод предоставлен для совместимости со STL. Он эквивалентен методу append(value).

[since 5.6] void QList::push_back(QList::rvalue_ref value)

Это перегруженный метод.

Этот метод был введён в Qt 5.6.

[since 5.6] QList::reverse_iterator QList::rbegin()

Возвращает обратный итератор STL, указывающий на первый элемент в списке в обратном порядке.

Предупреждение: Возвращаемый итератор становится недействительным при отделении или при изменении списка QList.

Эта функция была добавлена в Qt 5.6.

См. также begin(), crbegin() и rend().

[since 5.6] QList::const_reverse_iterator QList::rbegin() const

Это перегруженная функция.

Эта функция была добавлена в Qt 5.6.

void QList::remove(qsizetype i, qsizetype n = 1)

Удаляет n элементов из списка, начиная с индекса i.

Удаление элементов сохранит емкость списка и не уменьшит выделенную память. Чтобы освободить дополнительную емкость и освободить как можно больше памяти, вызовите squeeze().

Примечание: Когда QList не является неявным общим, эта функция делает недействительными только итераторы на позициях, равных или следующих за указанной позицией.

См. также insert(), replace() и fill().

[since 5.4] template <typename AT> qsizetype QList::removeAll(const AT &t)

Удаляет все элементы, которые сравниваются как равные t из списка. Возвращает количество удаленных элементов (если таковые есть).

Удаление элементов сохранит емкость списка и не уменьшит выделенную память. Чтобы освободить дополнительную емкость и освободить как можно больше памяти, вызовите squeeze().

Эта функция была добавлена в Qt 5.4.

См. также removeOne().

[since 5.2] void QList::removeAt(qsizetype i)

Удаляет элемент с индексом i. Эквивалентно

remove(i);

Удаление элементов сохранит емкость списка и не уменьшит выделенную память. Чтобы освободить дополнительную емкость и освободить как можно больше памяти, вызовите squeeze().

Примечание: Когда QList не является неявным общим, эта функция делает недействительными только итераторы на позициях, равных или следующих за указанной позицией.

Эта функция была добавлена в Qt 5.2.

См. также remove().

[since 5.1] void QList::removeFirst()

Удаляет первый элемент в списке. Вызов этой функции эквивалентен вызову remove(0). Список не должен быть пустым. Если список может быть пустым, вызовите isEmpty() перед вызовом этой функции.

Удаление элементов сохранит емкость списка и не уменьшит выделенную память. Чтобы освободить дополнительную емкость и освободить как можно больше памяти, вызовите squeeze().

Эта функция была добавлена в Qt 5.1.

См. также remove(), takeFirst() и isEmpty().

[since 6.1] template <typename Predicate> qsizetype QList::removeIf(Predicate pred)

Удаляет все элементы, для которых предикат pred возвращает true из списка. Возвращает количество удаленных элементов (если таковые есть).

Эта функция была добавлена в Qt 6.1.

См. также removeAll().

[since 5.1] void QList::removeLast()

Удаляет последний элемент в списке. Вызов этой функции эквивалентен вызову remove(size() - 1). Список не должен быть пустым. Если список может быть пустым, вызовите isEmpty() перед вызовом этой функции.

Удаление элементов сохранит емкость списка и не уменьшит выделенную память. Чтобы освободить дополнительную емкость и освободить как можно больше памяти, вызовите squeeze().

Эта функция была добавлена в Qt 5.1.

См. также remove(), takeLast(), removeFirst() и isEmpty().

[since 5.4] template <typename AT> bool QList::removeOne(const AT &t)

Удаляет первый элемент, который сравнивается как равный t, из списка. Возвращает значение, указывающее, был ли удален элемент.

Удаление элементов сохранит емкость списка и не уменьшит выделенную память. Чтобы освободить дополнительную емкость и освободить как можно больше памяти, вызовите squeeze().

Эта функция была добавлена в Qt 5.4.

См. также removeAll().

[since 5.6] QList::reverse_iterator QList::rend()

Возвращает обратный итератор STL, указывающий на позицию, следующую за последним элементом в списке в обратном порядке.

Предупреждение: Возвращаемый итератор становится недействительным при отделении или при изменении списка QList.

Эта функция была добавлена в Qt 5.6.

См. также end(), crend() и rbegin().

[since 5.6] QList::const_reverse_iterator QList::rend() const

Это перегруженная функция.

Эта функция была добавлена в Qt 5.6.

void QList::reserve(qsizetype size)

Попытка выделить память для как минимум size элементов.

Если заранее известно, какой будет размер списка, необходимо вызвать эту функцию для предотвращения перераспределений и фрагментации памяти. Если часто происходит изменение размера списка, это также улучшит производительность.

Если неясно, сколько памяти потребуется, лучше использовать верхнюю границу как size или высокую оценку наиболее вероятного размера, если строгая верхняя граница будет намного больше. Если size является недооценкой, список будет расти по мере необходимости после превышения выделенного размера, что может привести к выделению памяти больше, чем лучшее переоценивание, и замедлит операцию, которая его спровоцировала.

Предупреждение: reserve() резервирует память, но не изменяет размер списка. Доступ к данным за пределами текущего конца списка является неопределённым поведением. Если нужно получить доступ к памяти за пределами текущего конца списка, используйте resize().

См. также squeeze(), capacity() и resize().

void QList::resize(qsizetype size)

Устанавливает размер списка в size. Если size больше текущего размера, элементы добавляются в конец; новые элементы инициализируются с помощью значения, созданного по умолчанию. Если size меньше текущего размера, элементы удаляются с конца.

Начиная с Qt 5.6, resize() больше не уменьшает емкость. Для освобождения избыточной емкости используйте squeeze().

См. также size().

[since 5.10] void QList::shrink_to_fit()

Эта функция предоставляется для совместимости со STL. Она эквивалентна squeeze().

Эта функция была добавлена в Qt 5.10.

qsizetype QList::size() const

Возвращает количество элементов в списке.

См. также isEmpty() и resize().

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

Возвращает подсписок, содержащий n элементов этого списка, начиная с позиции pos.

Примечание: Поведение является неопределённым, когда pos < 0, n < 0 или pos + n > size().

Эта функция была добавлена в Qt 6.0.

См. также first() и last().

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

Это перегруженная функция.

Возвращает подсписок, содержащий элементы этого списка, начиная с позиции pos и до его конца.

Примечание: Поведение является неопределённым, когда pos < 0 или pos > size().

Эта функция была добавлена в Qt 6.0.

См. также first() и last().

void QList::squeeze()

Освобождает любую память, не требуемую для хранения элементов.

Единственная цель этой функции — предоставить способ тонкой настройки использования памяти в QList. Как правило, вам редко понадобится вызывать эту функцию.

См. также reserve() и capacity().

bool QList::startsWith(QList::parameter_type value) const

Возвращает true если этот список не пуст и его первый элемент равен value; в противном случае возвращает false.

См. также isEmpty() и first().

void QList::swap(QList<T> &other)

Меняет местами список other и этот список. Эта операция очень быстрая и никогда не терпит неудачу.

void QList::swapItemsAt(qsizetype i, qsizetype j)

Поменяйте элемент с индексом i на элемент с индексом j. Эта функция предполагает, что i и j не меньше 0, но меньше размера(). Чтобы избежать ошибок, проверьте, что i и j не меньше 0 и меньше размера().

[since 5.2] T QList::takeAt(qsizetype i)

Удаляет элемент с индексом i и возвращает его.

Эквивалентно

T t = at(i);
remove(i);
return t;

Примечание: Когда QList не неявное совместное использование, эта функция делает недействительными только итераторы, начиная с указанного положения.

Эта функция была введена в Qt 5.2.

См. также takeFirst() и takeLast().

[since 5.1] QList::value_type QList::takeFirst()

Удаляет первый элемент в списке и возвращает его. Эта функция предполагает, что список не пуст. Для предотвращения ошибок вызовите isEmpty() перед вызовом этой функции.

Эта функция была введена в Qt 5.1.

См. также takeLast() и removeFirst().

[since 5.1] QList::value_type QList::takeLast()

Удаляет последний элемент в списке и возвращает его. Эта функция предполагает, что список не пуст. Для предотвращения ошибок вызовите isEmpty() перед вызовом этой функции.

Если вам не нужно значение возвращаемое функцией, то removeLast() более эффективна.

Эта функция была введена в Qt 5.1.

См. также takeFirst() и removeLast().

T QList::value(qsizetype i) const

Возвращает значение с индексом i в списке.

Если индекс i выходит за пределы диапазона, функция возвращает значение по умолчанию. Если вы уверены, что i находится в пределах границ, вы можете использовать at(), которая немного быстрее.

См. также at() и operator[]().

T QList::value(qsizetype i, QList::parameter_type defaultValue) const

Это перегруженная функция.

Если индекс i выходит за пределы диапазона, функция возвращает defaultValue.

template <typename U> QTypeTraits::compare_eq_result<U> QList::operator!=(const QList<T> &other) const

Возвращает true если other не равно этому списку; в противном случае возвращает false.

Два списка считаются равными, если они содержат одинаковые значения в том же порядке.

Эта функция требует, чтобы тип значения имел реализацию operator==().

См. также operator==().

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

Возвращает список, который содержит все элементы этого списка, за которыми следуют все элементы списка other.

См. также operator+=().

[since 6.0] QList<T> QList::operator+(QList<T> &&other) const

Это перегруженная функция.

Эта функция была введена в Qt 6.0.

См. также operator+=().

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

Добавляет элементы списка other в этот список и возвращает ссылку на этот список.

См. также operator+() и append().

[since 6.0] QList<T> &QList::operator+=(QList<T> &&other)

Это перегруженная функция.

Эта функция была введена в Qt 6.0.

См. также operator+() и append().

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

Это перегруженная функция.

Добавляет value в список.

См. также append() и operator<<().

[since 5.11] QList<T> &QList::operator+=(QList::rvalue_ref value)

Это перегруженная функция.

Эта функция была введена в Qt 5.11.

См. также append() и operator<<().

[since 5.6] template <typename U> QTypeTraits::compare_lt_result<U> QList::operator<(const QList<T> &other) const

Возвращает true если этот список лексикографически меньше other; в противном случае возвращает false.

Эта функция требует, чтобы тип значения имел реализацию operator<().

Эта функция была введена в Qt 5.6.

QList<T> &QList::operator<<(QList::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.

[since 5.11] QList<T> &QList::operator<<(QList::rvalue_ref value)

Это перегруженная функция.

Эта функция была введена в Qt 5.11.

См. также append() и operator+=().

[since 5.6] template <typename U> QTypeTraits::compare_lt_result<U> QList::operator<=(const QList<T> &other) const

Возвращает true если этот список лексикографически меньше или равен other; в противном случае возвращает false.

Эта функция требует, чтобы тип значения имел реализацию operator<().

Эта функция была введена в Qt 5.6.

[since 5.14] QList<T> &QList::operator=(std::initializer_list<T> args)

Присваивает набор значений в args этому экземпляру QList.

Эта функция была введена в Qt 5.14.

template <typename U> QTypeTraits::compare_eq_result<U> QList::operator==(const QList<T> &other) const

Возвращает true если other равно этому списку; в противном случае возвращает false.

Два списка считаются равными, если они содержат одинаковые значения в том же порядке.

Эта функция требует, чтобы тип значения имел реализацию operator==().

См. также operator!=().

[since 5.6] template <typename U> QTypeTraits::compare_lt_result<U> QList::operator>(const QList<T> &other) const

Возвращает true если этот список лексикографически больше other; в противном случае возвращает false.

Эта функция требует, чтобы тип значения имел реализацию operator<().

Эта функция была введена в Qt 5.6.

[since 5.6] template <typename U> QTypeTraits::compare_lt_result<U> QList::operator>=(const QList<T> &other) const

Возвращает true если этот список лексикографически больше или равен other; в противном случае возвращает false.

Эта функция требует, чтобы тип значения имел реализацию operator<().

Эта функция была введена в Qt 5.6.

QList::reference QList::operator[](qsizetype i)

Возвращает элемент в позиции i как изменяемую ссылку.

i должно быть допустимой позицией индекса в списке (т.е., 0 <= i < размер()).

Обратите внимание, что использование не-константных операторов может привести к тому, что QList сделает глубокую копию.

См. также at() и value().

QList::const_reference QList::operator[](qsizetype i) const

Это перегруженная функция.

То же самое, что и at(i).