QList Class

template <typename T> class QList

The QList class is a template class that provides a dynamic array. More…

List of all members, including inherited members

Public Types

Public Functions

Static Public Members

Detailed Description

QList<T> stores its items contiguously and gives fast index-based access, fast appends and fast iteration. It is the container to reach for first.

QList<QString> names = {"Ada", "Grace"};
names << "Linus";
names.removeAll("Grace");
for (const QString &n : names)
    use(n);

See also QQueue, QStack and QVarLengthArray.

Differences from Qt

Member Type Documentation

typedef QList::const_iterator

The const iterator type, a random access iterator over const T.

typedef QList::const_pointer

Alias for const T *. Provided for STL compatibility.

typedef QList::const_reference

Alias for const T &. Provided for STL compatibility.

typedef QList::const_reverse_iterator

The const reverse iterator type.

typedef QList::ConstIterator

Qt-style synonym for QList::const_iterator.

typedef QList::Container

The container that stores the items: std::vector<T>, except for a list of bool, which has a container of its own, as std::vector<bool> is not an array of bool.

typedef QList::difference_type

Alias for qsizetype. Provided for STL compatibility.

typedef QList::iterator

The non-const iterator type, a random access iterator over T.

typedef QList::Iterator

Qt-style synonym for QList::iterator.

typedef QList::pointer

Alias for T *. Provided for STL compatibility.

typedef QList::reference

Alias for T &. Provided for STL compatibility.

typedef QList::reverse_iterator

The non-const reverse iterator type.

typedef QList::size_type

Alias for qsizetype. Provided for STL compatibility.

typedef QList::value_type

The type of the items stored in the list, T. Provided for STL compatibility.

Member Function Documentation

QList::QList()

Constructs an empty list.

[explicit] QList::QList(qsizetype size)

Constructs a list with size default-constructed items.

QList::QList(qsizetype size, const T &value)

This is an overloaded function.

Constructs a list with size copies of value.

QList::QList(qsizetype size, Qt::Initialization)

This is an overloaded function.

Constructs a list with size items whose values the caller is about to assign. Pass Qt::Uninitialized as the second argument.

This function was introduced in 6.8.

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

Constructs a list from the items in the initializer list args.

template <typename String = QString, typename = std::enable_if_t<std::is_same_v<T, QString> && std::is_convertible_v<const String &, QString>>>[explicit] QList::QList(const String &str)

This is an overloaded function.

Constructs a list with the single string str, which is a QString or converts to one. This constructor exists for a list of strings only, as QStringList(str).

template <typename It, typename = typename std::iterator_traits<It>::iterator_category>QList::QList(It first, It last)

Constructs a list with a copy of the items in the range [first, last).

void QList::append(const T &t)

Inserts t at the end of the list.

See also prepend(), insert() and push_back().

void QList::append(T &&t)

This is an overloaded function.

Moves t to the end of the list.

void QList::append(const QList &l)

This is an overloaded function.

Appends the items of the list l to this list.

QList & QList::assign(qsizetype n, const T &t)

Replaces the contents of the list with n copies of t and returns a reference to the list.

This function was introduced in 6.6.

See also fill().

template <typename It, typename = typename std::iterator_traits<It>::iterator_category>QList & QList::assign(It first, It last)

This is an overloaded function.

Replaces the contents of the list with a copy of the items in the range [first, last) and returns a reference to the list.

This function was introduced in 6.6.

QList & QList::assign(std::initializer_list<T> l)

This is an overloaded function.

Replaces the contents of the list with the items in l and returns a reference to the list.

This function was introduced in 6.6.

const T & QList::at(qsizetype i) const

Returns the item at index position i. i must be a valid index.

See also value(), front() and back().

T & QList::back()

Same as last(). This function is provided for STL compatibility.

const T & QList::back() const

This is an overloaded function.

Same as last() const.

iterator QList::begin()

Returns an iterator pointing to the first item in the list.

const_iterator QList::begin() const

This is an overloaded function.

Returns a const iterator pointing to the first item in the list.

qsizetype QList::capacity() const

Returns the maximum number of items the list can hold without reallocating.

See also reserve() and squeeze().

const_iterator QList::cbegin() const

Returns a const iterator pointing to the first item in the list.

const_iterator QList::cend() const

Returns a const iterator pointing just after the last item in the list.

void QList::chop(qsizetype n)

Removes n items from the end of the list. n must not be greater than size().

See also chopped() and resize().

QList QList::chopped(qsizetype n) const

Returns a sublist containing this list without its last n items.

See also chop() and first().

void QList::clear()

Removes all the items from the list.

See also resize() and removeAll().

const_iterator QList::constBegin() const

Same as cbegin().

const T * QList::constData() const

Returns a const pointer to the data stored in the list.

See also data().

const_iterator QList::constEnd() const

Same as cend().

const T & QList::constFirst() const

Returns a const reference to the first item in the list. The list must not be empty.

See also constLast() and first().

const T & QList::constLast() const

Returns a const reference to the last item in the list. The list must not be empty.

See also constFirst() and last().

template <typename AT = T>bool QList::contains(const AT &t) const

Returns true if the list contains an item equal to t; otherwise returns false.

See also indexOf() and count().

qsizetype QList::count() const

Same as size().

template <typename AT = T>qsizetype QList::count(const AT &t) const

This is an overloaded function.

Returns the number of items in the list equal to t.

See also contains() and indexOf().

const_reverse_iterator QList::crbegin() const

Returns a const reverse iterator pointing to the last item in the list.

const_reverse_iterator QList::crend() const

Returns a const reverse iterator pointing just before the first item in the list.

T * QList::data()

Returns a pointer to the data stored in the list. The pointer can be used to access and modify the items, and stays valid until the list is resized or destroyed.

See also constData().

const T * QList::data() const

This is an overloaded function.

Returns a const pointer to the data stored in the list.

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

Constructs a new item from args and inserts it at index position i. Returns an iterator to the new item. i must be between 0 and size().

See also emplaceBack() and insert().

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

This is an overloaded function.

Constructs a new item from args and inserts it before the item pointed to by before. Returns an iterator to the new item.

template <typename... Args>T & QList::emplace_back(Args &&...args)

Same as emplaceBack(args). This function is provided for STL compatibility.

template <typename... Args>T & QList::emplace_front(Args &&...args)

Same as emplaceFront(args). This function is provided for STL compatibility.

template <typename... Args>T & QList::emplaceBack(Args &&...args)

Constructs a new item at the end of the list from args and returns a reference to it.

See also append().

template <typename... Args>T & QList::emplaceFront(Args &&...args)

Constructs a new item at the beginning of the list from args and returns a reference to it.

See also emplaceBack() and prepend().

bool QList::empty() const

Same as isEmpty(). This function is provided for STL compatibility.

iterator QList::end()

Returns an iterator pointing just after the last item in the list.

const_iterator QList::end() const

This is an overloaded function.

Returns a const iterator pointing just after the last item in the list.

bool QList::endsWith(const T &t) const

Returns true if the list is not empty and its last item is equal to t; otherwise returns false.

See also startsWith().

iterator QList::erase(const_iterator pos)

Removes the item pointed to by the iterator pos and returns an iterator to the item that followed it.

See also removeAt().

iterator QList::erase(const_iterator first, const_iterator last)

This is an overloaded function.

Removes the items in the range [first, last) and returns an iterator to the item that followed the range.

void QList::fill(const T &v, qsizetype n = -1)

Assigns v to every item in the list. If n is not negative, the list is first resized to n items.

See also resize().

T & QList::first()

Returns a reference to the first item in the list. The list must not be empty.

See also last(), front() and isEmpty().

const T & QList::first() const

This is an overloaded function.

Returns a const reference to the first item in the list.

QList QList::first(qsizetype n) const

This is an overloaded function.

Returns a sublist containing the first n items of this list.

[static] QList QList::fromList(const QList &list)

Returns a copy of list. Provided for compatibility with code that converts between QList and QVector.

[static] QList QList::fromVector(const QList &vector)

Returns a copy of vector. Provided for compatibility with code that converts between QList and QVector.

T & QList::front()

Same as first(). This function is provided for STL compatibility.

const T & QList::front() const

This is an overloaded function.

Same as first() const.

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

Returns the index position of the first item equal to t, searching forward from index position from. A negative from counts from the end. Returns -1 if no item matches.

See also lastIndexOf() and contains().

iterator QList::insert(qsizetype i, const T &t)

Inserts t at index position i and returns an iterator to the inserted item. i must be between 0 and size().

See also append(), prepend() and remove().

iterator QList::insert(qsizetype i, qsizetype n, const T &t)

This is an overloaded function.

Inserts n copies of t at index position i and returns an iterator to the first inserted item.

iterator QList::insert(const_iterator before, const T &t)

This is an overloaded function.

Inserts t before the item pointed to by the iterator before and returns an iterator to the inserted item.

iterator QList::insert(qsizetype i, T &&t)

This is an overloaded function.

Moves t to index position i and returns an iterator to the inserted item.

iterator QList::insert(const_iterator before, T &&t)

This is an overloaded function.

Moves t before the item pointed to by the iterator before and returns an iterator to the inserted item.

iterator QList::insert(const_iterator before, qsizetype n, const T &t)

This is an overloaded function.

Inserts n copies of t before the item pointed to by the iterator before and returns an iterator to the first inserted item.

bool QList::isEmpty() const

Returns true if the list has size 0; otherwise returns false.

See also size() and clear().

T & QList::last()

Returns a reference to the last item in the list. The list must not be empty.

See also first(), back() and isEmpty().

const T & QList::last() const

This is an overloaded function.

Returns a const reference to the last item in the list.

QList QList::last(qsizetype n) const

This is an overloaded function.

Returns a sublist containing the last n items of this list. If n is not less than size(), the whole list is returned.

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

Returns the index position of the last item equal to t, searching backward from index position from. A negative from counts from the end, so the default of -1 starts at the last item. Returns -1 if no item matches.

See also indexOf() and contains().

qsizetype QList::length() const

Same as size().

qsizetype QList::max_size() const

Returns the largest number of items the list can theoretically hold. This function is provided for STL compatibility.

[static, constexpr] qsizetype QList::maxSize()

Returns the largest number of items a list can theoretically hold.

This function was introduced in 6.8.

See also max_size().

QList QList::mid(qsizetype pos, qsizetype len = -1) const

Returns a sublist containing up to len items starting at index position pos. If len is negative or reaches past the end, all items from pos to the end are returned. A negative pos is treated as 0; if pos is beyond the end, an empty list is returned.

See also first(), last() and sliced().

void QList::move(qsizetype from, qsizetype to)

Moves the item at index position from to index position to. Both must be valid indexes.

See also swapItemsAt().

QList & QList::operator+=(const QList &l)

Appends the items of the list l to this list and returns a reference to this list.

QList & QList::operator+=(const T &t)

This is an overloaded function.

Appends t to this list and returns a reference to this list.

QList & QList::operator+=(T &&t)

This is an overloaded function.

Moves t to the end of this list and returns a reference to this list.

QList & QList::operator<<(const T &t)

Appends t to this list and returns a reference to this list, so that calls can be chained.

QList & QList::operator<<(const QList &l)

This is an overloaded function.

Appends the items of the list l to this list and returns a reference to this list.

QList & QList::operator<<(T &&t)

This is an overloaded function.

Moves t to the end of this list and returns a reference to this list.

T & QList::operator[](qsizetype i)

Returns a reference to the item at index position i, which can be assigned to. i must be a valid index.

See also at() and value().

const T & QList::operator[](qsizetype i) const

This is an overloaded function.

Same as at(i).

void QList::pop_back()

Same as removeLast(). This function is provided for STL compatibility.

void QList::pop_front()

Same as removeFirst(). This function is provided for STL compatibility.

void QList::prepend(const T &t)

Inserts t at the beginning of the list.

See also append() and insert().

void QList::prepend(T &&t)

This is an overloaded function.

Moves t to the beginning of the list.

void QList::push_back(const T &t)

Same as append(t). This function is provided for STL compatibility.

void QList::push_back(T &&t)

This is an overloaded function.

Same as append(t) for an rvalue.

void QList::push_front(const T &t)

Same as prepend(t). This function is provided for STL compatibility.

void QList::push_front(T &&t)

This is an overloaded function.

Same as prepend(t). This function is provided for STL compatibility.

reverse_iterator QList::rbegin()

Returns a reverse iterator pointing to the last item in the list.

const_reverse_iterator QList::rbegin() const

This is an overloaded function.

Returns a const reverse iterator pointing to the last item in the list.

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

Removes n items starting at index position i. The range must be valid.

See also removeAt(), insert() and takeAt().

template <typename AT = T>qsizetype QList::removeAll(const AT &t)

Removes all items equal to t and returns the number of items removed.

See also removeOne() and removeIf().

void QList::removeAt(qsizetype i)

Removes the item at index position i. i must be a valid index.

See also remove(), takeAt() and removeOne().

void QList::removeFirst()

Removes the first item in the list. The list must not be empty.

See also removeLast() and takeFirst().

template <typename Pred>qsizetype QList::removeIf(Pred p)

Removes all items for which the predicate p returns true and returns the number of items removed.

See also removeAll().

void QList::removeLast()

Removes the last item in the list. The list must not be empty.

See also removeFirst() and takeLast().

template <typename AT = T>bool QList::removeOne(const AT &t)

Removes the first item equal to t and returns true; returns false if there is no such item.

See also removeAll() and removeAt().

reverse_iterator QList::rend()

Returns a reverse iterator pointing just before the first item in the list.

const_reverse_iterator QList::rend() const

This is an overloaded function.

Returns a const reverse iterator pointing just before the first item in the list.

void QList::replace(qsizetype i, const T &t)

Replaces the item at index position i with t. i must be a valid index.

See also remove().

void QList::reserve(qsizetype n)

Attempts to allocate memory for at least n items, so that later appends do not reallocate.

See also capacity() and squeeze().

void QList::resize(qsizetype n)

Sets the size of the list to n. If n is larger than the current size, the new items are default-constructed; if it is smaller, items are removed from the end.

See also size() and chop().

void QList::resize(qsizetype n, const T &v)

This is an overloaded function.

Sets the size of the list to n. New items are copies of v.

void QList::resizeForOverwrite(qsizetype size)

Sets the size of the list to size, for a caller that is about to assign every new item.

This function was introduced in 6.8.

See also resize().

void QList::reverse()

Reverses the order of the items in the list in place.

void QList::shrink_to_fit()

Same as squeeze(). This function is provided for STL compatibility.

qsizetype QList::size() const

Returns the number of items in the list.

See also isEmpty() and resize().

QList QList::sliced(qsizetype pos, qsizetype n) const

Returns a sublist containing n items starting at index position pos. Same as mid(pos, n).

See also mid(), first() and last().

QList QList::sliced(qsizetype pos) const

This is an overloaded function.

Returns a sublist containing all items from index position pos to the end.

void QList::squeeze()

Releases any memory not required to store the items.

See also reserve() and capacity().

bool QList::startsWith(const T &t) const

Returns true if the list is not empty and its first item is equal to t; otherwise returns false.

See also endsWith().

void QList::swap(QList &o)

Swaps this list with o. This operation is very fast and never fails.

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

Exchanges the items at index positions i and j. Both must be valid indexes.

See also move().

T QList::takeAt(qsizetype i)

Removes the item at index position i and returns it. i must be a valid index.

See also removeAt(), takeFirst() and takeLast().

T QList::takeFirst()

Removes the first item in the list and returns it. The list must not be empty.

See also takeLast() and removeFirst().

T QList::takeLast()

Removes the last item in the list and returns it. The list must not be empty.

See also takeFirst() and removeLast().

QList QList::toList() const

Returns a copy of this list. Provided for compatibility with code that converts between QList and QVector.

std::conditional_t<std::is_same_v<T, bool>, std::vector<bool>, const std::vector<T> &> QList::toStdVector() const

Returns the items as a std::vector<T>: a const reference to the vector that the list keeps them in, or, for a list of bool, a new std::vector<bool> with a copy of them.

QList QList::toVector() const

Returns a copy of this list. Provided for compatibility with code that converts between QList and QVector.

T QList::value(qsizetype i) const

Returns the item at index position i, or a default-constructed value if i is out of range.

See also at().

T QList::value(qsizetype i, const T &def) const

This is an overloaded function.

Returns the item at index position i, or def if i is out of range.