Класс QList

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

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

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

Типы public

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

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

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

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

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 использует нумерацию с индексом 0, как и 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 (например, insert() или remove()). Когда требуется стабильность и функциональность в стиле итератора, следует использовать индексы вместо итераторов, так как они не связаны с внутренним состоянием QList и, следовательно, не становятся недействительными.

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

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

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

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

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

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

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

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

[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. Обратите внимание, что все итераторы по умолчанию аннулируются. Исключение из этого правила явно документировано.

Этот typedef был введен в 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 предоставляет итератор обратного прохода для QList в стиле STL, не являющийся константным.

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

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

Этот тип данных был введён в 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 вместо этого. В противном случае предпочтительнее QList.

См. также 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 может выделять дополнительную память в начале данных списка и увеличиваться в этом направлении без перераспределения или перемещения данных при каждой операции. Однако если вам нужен класс контейнера с гарантированным постоянным временем для добавления в начало, используйте 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.

Эта функция была введена в 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 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 является заниженной оценкой, худшее, что произойдёт, — QList будет работать немного медленнее. Если size является завышенной оценкой, вы можете использовать больше памяти, чем предполагала бы обычная стратегия роста QList, или меньше.

Предупреждение: reserve() выделяет память, но не изменяет размер списка. Обращение к данным за пределами списка — неопределённое поведение.

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

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 и меньше size(). Чтобы избежать сбоев, проверьте, что и i, и j не меньше 0 и меньше size().

[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 < size()).

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

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

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

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

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