Contents

• Public Types
• Public Functions
• Static Public Members
• Related Non-Members
• Detailed Description

Detailed Description

TheQList class is a template class that provides lists.

QList<T> is one of Qt's genericcontainer classes. It stores a list of values and provides fast index-based access as well as fast insertions and removals.

QList<T>,QLinkedList<T>, andQVector<T> provide similar functionality. Here's an overview:

• For most purposes,QList is the right class to use. Its index-based API is more convenient thanQLinkedList's iterator-based API, and it is usually faster thanQVector because of the way it stores its items in memory. It also expands to less code in your executable.
• If you need a real linked list, with guarantees ofconstant time insertions in the middle of the list and iterators to items rather than indexes, useQLinkedList.
• If you want the items to occupy adjacent memory positions, useQVector.

Internally,QList<T> is represented as an array of pointers to items of type T. If T is itself a pointer type or a basic type that is no larger than a pointer, or if T is one of Qt'sshared classes, thenQList<T> stores the items directly in the pointer array. For lists under a thousand items, this array representation allows for very fast insertions in the middle, and it allows index-based access. Furthermore, operations likeprepend() andappend() are very fast, becauseQList preallocates memory at both ends of its internal array. (SeeAlgorithmic Complexity for details.) Note, however, that for unshared list items that are larger than a pointer, each append or insert of a new item requires allocating the new item on the heap, and this per item allocation might makeQVector a better choice in cases that do lots of appending or inserting, sinceQVector allocates memory for its items in a single heap allocation.

Note that the internal array only ever gets bigger over the life of the list. It never shrinks. The internal array is deallocated by the destructor, byclear(), and by the assignment operator, when one list is assigned to another.

Here's an example of aQList that stores integers and aQList that storesQDate values:

QList<int> integerList;QList<QDate> dateList;

Qt includes aQStringList class that inheritsQList<QString> and adds a convenience functionQStringList::join(). (QString::split() creates QStringLists from strings.)

QList stores a list of items. The default constructor creates an empty list. To insert items into the list, you can use operator<<():

QList<QString> list;list<<"one"<<"two"<<"three";// list: ["one", "two", "three"]

QList provides these basic functions to add, move, and remove items:insert(),replace(),removeAt(),move(), andswap(). In addition, it provides the following convenience functions:append(),prepend(),removeFirst(), andremoveLast().

QList uses 0-based indexes, just like C++ arrays. To access the item at a particular index position, you can use operator[](). On non-const lists, operator[]() returns a reference to the item and can be used on the left side of an assignment:

if (list[0]=="Bob")    list[0]="Robert";

BecauseQList is implemented as an array of pointers, this operation is very fast (constant time). For read-only access, an alternative syntax is to useat():

for (int i=0; i< list.size();++i) {if (list.at(i)=="Jane")        cout<<"Found Jane at position "<< i<< endl;}

at() can be faster than operator[](), because it never causes adeep copy to occur.

A common requirement is to remove an item from a list and do something with it. For this,QList providestakeAt(),takeFirst(), andtakeLast(). Here's a loop that removes the items from a list one at a time and callsdelete on them:

QList<QWidget*> list;...while (!list.isEmpty())delete list.takeFirst();

Inserting and removing items at either ends of the list is very fast (constant time in most cases), becauseQList preallocates extra space on both sides of its internal buffer to allow for fast growth at both ends of the list.

If you want to find all occurrences of a particular value in a list, useindexOf() orlastIndexOf(). The former searches forward starting from a given index position, the latter searches backward. Both return the index of a matching item if they find it; otherwise, they return -1. For example:

int i= list.indexOf("Jane");if (i!=-1)    cout<<"First occurrence of Jane is at position "<< i<< endl;

If you simply want to check whether a list contains a particular value, usecontains(). If you want to find out how many times a particular value occurs in the list, usecount(). If you want to replace all occurrences of a particular value with another, usereplace().

QList's value type must be anassignable data type. This covers most data types that are commonly used, but the compiler won't let you, for example, store aQWidget as a value; instead, store aQWidget *. A few functions have additional requirements; for example,indexOf() andlastIndexOf() expect the value type to supportoperator==(). These requirements are documented on a per-function basis.

Like the other container classes,QList providesJava-style iterators (QListIterator andQMutableListIterator) andSTL-style iterators (QList::const_iterator andQList::iterator). In practice, these are rarely used, because you can use indexes into theQList.QList is implemented in such a way that direct index-based access is just as fast as using iterators.

QList doesnot support inserting, prepending, appending or replacing with references to its own values. Doing so will cause your application to abort with an error message.

To makeQList as efficient as possible, its member functions don't validate their input before using it. Except forisEmpty(), member functions always assume the list isnot empty. Member functions that take index values as parameters always assume their index value parameters are in the valid range. This meansQList member functions can fail. If you define QT_NO_DEBUG when you compile, failures will not be detected. If youdon't define QT_NO_DEBUG, failures will be detected usingQ_ASSERT() orQ_ASSERT_X() with an appropriate message.

To avoid failures when your list can be empty, callisEmpty() before calling other member functions. If you must pass an index value that might not be in the valid range, check that it is less than the value returned bysize() butnot less than 0.

Member Type Documentation

typedef QList::ConstIterator

Qt-style synonym forQList::const_iterator.

typedef QList::Iterator

Qt-style synonym forQList::iterator.

typedef QList::const_pointer

Typedef for const T *. Provided for STL compatibility.

typedef QList::const_reference

Typedef for const T &. Provided for STL compatibility.

typedef QList::difference_type

Typedef for ptrdiff_t. Provided for STL compatibility.

typedef QList::pointer

Typedef for T *. Provided for STL compatibility.

typedef QList::reference

Typedef for T &. Provided for STL compatibility.

typedef QList::size_type

Typedef for int. Provided for STL compatibility.

typedef QList::value_type

Typedef for T. Provided for STL compatibility.

Member Function Documentation

QList::QList()

Constructs an empty list.

QList::QList(constQList<T> & other)

Constructs a copy ofother.

This operation takesconstant time, becauseQList isimplicitly shared. This makes returning aQList from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and that takeslinear time.

See alsooperator=().

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

Construct a list from the std::initializer_list specified byargs.

This constructor is only enabled if the compiler supports C++0x

This function was introduced in Qt 4.8.

QList::~QList()

Destroys the list. References to the values in the list and all iterators of this list become invalid.

void QList::append(constT & value)

Insertsvalue at the end of the list.

Example:

QList<QString> list;list.append("one");list.append("two");list.append("three");// list: ["one", "two", "three"]

This is the same as list.insert(size(),value).

This operation is typically very fast (constant time), becauseQList preallocates extra space on both sides of its internal buffer to allow for fast growth at both ends of the list.

See alsooperator<<(),prepend(), andinsert().

void QList::append(constQList<T> & value)

This is an overloaded function.

Appends the items of thevalue list to this list.

This function was introduced in Qt 4.5.

See alsooperator<<() andoperator+=().

constT & QList::at(int i) const

Returns the item at index positioni in the list.i must be a valid index position in the list (i.e., 0 <=i <size()).

This function is very fast (constant time).

See alsovalue() andoperator[]().

T & QList::back()

This function is provided for STL compatibility. It is equivalent tolast(). The list must not be empty. If the list can be empty, callisEmpty() before calling this function.

constT & QList::back() const

This is an overloaded function.

iterator QList::begin()

Returns an STL-style iterator pointing to the first item in the list.

See alsoconstBegin() andend().

const_iterator QList::begin() const

This is an overloaded function.

void QList::clear()

Removes all items from the list.

See alsoremoveAll().

const_iterator QList::constBegin() const

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

See alsobegin() andconstEnd().

const_iterator QList::constEnd() const

Returns a const STL-style iterator pointing to the imaginary item after the last item in the list.

See alsoconstBegin() andend().

bool QList::contains(constT & value) const

Returns true if the list contains an occurrence ofvalue; otherwise returns false.

This function requires the value type to have an implementation ofoperator==().

See alsoindexOf() andcount().

int QList::count(constT & value) const

Returns the number of occurrences ofvalue in the list.

This function requires the value type to have an implementation ofoperator==().

See alsocontains() andindexOf().

int QList::count() const

Returns the number of items in the list. This is effectively the same assize().

bool QList::empty() const

This function is provided for STL compatibility. It is equivalent toisEmpty() and returns true if the list is empty.

iterator QList::end()

Returns an STL-style iterator pointing to the imaginary item after the last item in the list.

See alsobegin() andconstEnd().

const_iterator QList::end() const

This is an overloaded function.

bool QList::endsWith(constT & value) const

Returns true if this list is not empty and its last item is equal tovalue; otherwise returns false.

This function was introduced in Qt 4.5.

See alsoisEmpty() andcontains().

iterator QList::erase(iterator pos)

Removes the item associated with the iteratorpos from the list, and returns an iterator to the next item in the list (which may beend()).

See alsoinsert() andremoveAt().

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

This is an overloaded function.

Removes all the items frombegin up to (but not including)end. Returns an iterator to the same item thatend referred to before the call.

T & QList::first()

Returns a reference to the first item in the list. The list must not be empty. If the list can be empty, callisEmpty() before calling this function.

See alsolast() andisEmpty().

constT & QList::first() const

This is an overloaded function.

[static]QList<T> QList::fromSet(constQSet<T> & set)

Returns aQList object with the data contained inset. The order of the elements in theQList is undefined.

Example:

QSet<int> set;set<<20<<30<<40<<...<<70;QList<int> list=QList<int>::fromSet(set);qSort(list);

See alsofromVector(),toSet(),QSet::toList(), andqSort().

[static]QList<T> QList::fromStdList(conststd::list<T> & list)

Returns aQList object with the data contained inlist. The order of the elements in theQList is the same as inlist.

Example:

std::list<double> stdlist;list.push_back(1.2);list.push_back(0.5);list.push_back(3.14);QList<double> list=QList<double>::fromStdList(stdlist);

See alsotoStdList() andQVector::fromStdVector().

[static]QList<T> QList::fromVector(constQVector<T> & vector)

Returns aQList object with the data contained invector.

Example:

QVector<double> vect;vect<<20.0<<30.0<<40.0<<50.0;QList<double> list=QVector<T>::fromVector(vect);// list: [20.0, 30.0, 40.0, 50.0]

See alsofromSet(),toVector(), andQVector::toList().

T & QList::front()

This function is provided for STL compatibility. It is equivalent tofirst(). The list must not be empty. If the list can be empty, callisEmpty() before calling this function.

constT & QList::front() const

This is an overloaded function.

int QList::indexOf(constT & value,int from = 0) const

Returns the index position of the first occurrence ofvalue in the list, searching forward from index positionfrom. Returns -1 if no item matched.

Example:

QList<QString> list;list<<"A"<<"B"<<"C"<<"B"<<"A";list.indexOf("B");// returns 1list.indexOf("B",1);// returns 1list.indexOf("B",2);// returns 3list.indexOf("X");// returns -1

This function requires the value type to have an implementation ofoperator==().

Note thatQList uses 0-based indexes, just like C++ arrays. Negative indexes are not supported with the exception of the value mentioned above.

See alsolastIndexOf() andcontains().

void QList::insert(int i, constT & value)

Insertsvalue at index positioni in the list. Ifi is 0, the value is prepended to the list. Ifi issize(), the value is appended to the list.

Example:

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

See alsoappend(),prepend(),replace(), andremoveAt().

iterator QList::insert(iterator before, constT & value)

This is an overloaded function.

Insertsvalue in front of the item pointed to by the iteratorbefore. Returns an iterator pointing at the inserted item. Note that the iterator passed to the function will be invalid after the call; the returned iterator should be used instead.

bool QList::isEmpty() const

Returns true if the list contains no items; otherwise returns false.

See alsosize().

T & QList::last()

Returns a reference to the last item in the list. The list must not be empty. If the list can be empty, callisEmpty() before calling this function.

See alsofirst() andisEmpty().

constT & QList::last() const

This is an overloaded function.

int QList::lastIndexOf(constT & value,int from = -1) const

Returns the index position of the last occurrence ofvalue in the list, searching backward from index positionfrom. Iffrom is -1 (the default), the search starts at the last item. Returns -1 if no item matched.

Example:

QList<QString> list;list<<"A"<<"B"<<"C"<<"B"<<"A";list.lastIndexOf("B");// returns 3list.lastIndexOf("B",3);// returns 3list.lastIndexOf("B",2);// returns 1list.lastIndexOf("X");// returns -1

This function requires the value type to have an implementation ofoperator==().

Note thatQList uses 0-based indexes, just like C++ arrays. Negative indexes are not supported with the exception of the value mentioned above.

See alsoindexOf().

int QList::length() const

This function is identical tocount().

This function was introduced in Qt 4.5.

See alsocount().

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

Returns a list whose elements are copied from this list, starting at positionpos. Iflength is -1 (the default), all elements frompos are copied; otherwiselength elements (or all remaining elements if there are less thanlength elements) are copied.

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

Moves the item at index positionfrom to index positionto.

Example:

QList<QString> list;list<<"A"<<"B"<<"C"<<"D"<<"E"<<"F";list.move(1,4);// list: ["A", "C", "D", "E", "B", "F"]

This is the same as insert(to,takeAt(from)).This function assumes that bothfrom andto are at least 0 but less thansize(). To avoid failure, test that bothfrom andto are at least 0 and less thansize().

See alsoswap(),insert(), andtakeAt().

void QList::pop_back()

This function is provided for STL compatibility. It is equivalent toremoveLast(). The list must not be empty. If the list can be empty, callisEmpty() before calling this function.

void QList::pop_front()

This function is provided for STL compatibility. It is equivalent toremoveFirst(). The list must not be empty. If the list can be empty, callisEmpty() before calling this function.

void QList::prepend(constT & value)

Insertsvalue at the beginning of the list.

Example:

QList<QString> list;list.prepend("one");list.prepend("two");list.prepend("three");// list: ["three", "two", "one"]

This is the same as list.insert(0,value).

This operation is usually very fast (constant time), becauseQList preallocates extra space on both sides of its internal buffer to allow for fast growth at both ends of the list.

See alsoappend() andinsert().

void QList::push_back(constT & value)

This function is provided for STL compatibility. It is equivalent toappend(value).

void QList::push_front(constT & value)

This function is provided for STL compatibility. It is equivalent toprepend(value).

int QList::removeAll(constT & value)

Removes all occurrences ofvalue in the list and returns the number of entries removed.

Example:

QList<QString> list;list<<"sun"<<"cloud"<<"sun"<<"rain";list.removeAll("sun");// list: ["cloud", "rain"]

This function requires the value type to have an implementation ofoperator==().

See alsoremoveOne(),removeAt(),takeAt(), andreplace().

void QList::removeAt(int i)

Removes the item at index positioni.i must be a valid index position in the list (i.e., 0 <=i <size()).

See alsotakeAt(),removeFirst(),removeLast(), andremoveOne().

void QList::removeFirst()

Removes the first item in the list. Calling this function is equivalent to callingremoveAt(0). The list must not be empty. If the list can be empty, callisEmpty() before calling this function.

See alsoremoveAt() andtakeFirst().

void QList::removeLast()

Removes the last item in the list. Calling this function is equivalent to callingremoveAt(size() - 1). The list must not be empty. If the list can be empty, callisEmpty() before calling this function.

See alsoremoveAt() andtakeLast().

bool QList::removeOne(constT & value)

Removes the first occurrence ofvalue in the list and returns true on success; otherwise returns false.

Example:

QList<QString> list;list<<"sun"<<"cloud"<<"sun"<<"rain";list.removeOne("sun");// list: ["cloud", ,"sun", "rain"]

This function requires the value type to have an implementation ofoperator==().

This function was introduced in Qt 4.4.

See alsoremoveAll(),removeAt(),takeAt(), andreplace().

void QList::replace(int i, constT & value)

Replaces the item at index positioni withvalue.i must be a valid index position in the list (i.e., 0 <=i <size()).

See alsooperator[]() andremoveAt().

void QList::reserve(int alloc)

Reserve space foralloc elements.

Ifalloc is smaller than the current size of the list, nothing will happen.

Use this function to avoid repetetive reallocation ofQList's internal data if you can predict how many elements will be appended. Note that the reservation applies only to the internal pointer array.

This function was introduced in Qt 4.7.

int QList::size() const

Returns the number of items in the list.

See alsoisEmpty() andcount().

bool QList::startsWith(constT & value) const

Returns true if this list is not empty and its first item is equal tovalue; otherwise returns false.

This function was introduced in Qt 4.5.

See alsoisEmpty() andcontains().

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

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

This function was introduced in Qt 4.8.

void QList::swap(int i,int j)

Exchange the item at index positioni with the item at index positionj. This function assumes that bothi andj are at least 0 but less thansize(). To avoid failure, test that bothi andj are at least 0 and less thansize().

Example:

QList<QString> list;list<<"A"<<"B"<<"C"<<"D"<<"E"<<"F";list.swap(1,4);// list: ["A", "E", "C", "D", "B", "F"]

See alsomove().

T QList::takeAt(int i)

Removes the item at index positioni and returns it.i must be a valid index position in the list (i.e., 0 <=i <size()).

If you don't use the return value,removeAt() is more efficient.

See alsoremoveAt(),takeFirst(), andtakeLast().

T QList::takeFirst()

Removes the first item in the list and returns it. This is the same astakeAt(0). This function assumes the list is not empty. To avoid failure, callisEmpty() before calling this function.

This operation takesconstant time.

If you don't use the return value,removeFirst() is more efficient.

See alsotakeLast(),takeAt(), andremoveFirst().

T QList::takeLast()

Removes the last item in the list and returns it. This is the same astakeAt(size() - 1). This function assumes the list is not empty. To avoid failure, callisEmpty() before calling this function.

This operation takesconstant time.

If you don't use the return value,removeLast() is more efficient.

See alsotakeFirst(),takeAt(), andremoveLast().

QSet<T> QList::toSet() const

Returns aQSet object with the data contained in thisQList. SinceQSet doesn't allow duplicates, the resultingQSet might be smaller than the original list was.

Example:

QStringList list;list<<"Julia"<<"Mike"<<"Mike"<<"Julia"<<"Julia";QSet<QString> set= list.toSet();set.contains("Julia");// returns trueset.contains("Mike");// returns trueset.size();// returns 2

See alsotoVector(),fromSet(), andQSet::fromList().

std::list<T> QList::toStdList() const

Returns a std::list object with the data contained in thisQList. Example:

QList<double> list;list<<1.2<<0.5<<3.14;std::list<double> stdlist= list.toStdList();

See alsofromStdList() andQVector::toStdVector().

QVector<T> QList::toVector() const

Returns aQVector object with the data contained in thisQList.

Example:

QStringList list;list<<"Sven"<<"Kim"<<"Ola";QVector<QString> vect= list.toVector();// vect: ["Sven", "Kim", "Ola"]

See alsotoSet(),fromVector(), andQVector::fromList().

T QList::value(int i) const

Returns the value at index positioni in the list.

If the indexi is out of bounds, the function returns a default-constructed value. If you are certain that the index is going to be within bounds, you can useat() instead, which is slightly faster.

See alsoat() andoperator[]().

T QList::value(int i, constT & defaultValue) const

This is an overloaded function.

If the indexi is out of bounds, the function returnsdefaultValue.

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

Returns true ifother is not equal to this list; otherwise returns false.

Two lists are considered equal if they contain the same values in the same order.

This function requires the value type to have an implementation ofoperator==().

See alsooperator==().

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

Returns a list that contains all the items in this list followed by all the items in theother list.

See alsooperator+=().

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

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

See alsooperator+() andappend().

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

This is an overloaded function.

Appendsvalue to the list.

See alsoappend() andoperator<<().

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

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

See alsooperator+=() andappend().

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

This is an overloaded function.

Appendsvalue to the list.

QList<T> & QList::operator=(constQList<T> & other)

Assignsother to this list and returns a reference to this list.

QList & QList::operator=(QList && other)

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

Returns true ifother is equal to this list; otherwise returns false.

Two lists are considered equal if they contain the same values in the same order.

This function requires the value type to have an implementation ofoperator==().

See alsooperator!=().

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

Returns the item at index positioni as a modifiable reference.i must be a valid index position in the list (i.e., 0 <=i <size()).

This function is very fast (constant time).

See alsoat() andvalue().

constT & QList::operator[](int i) const

This is an overloaded function.

Same asat().

Related Non-Members

QDataStream &operator<<(QDataStream & out, constQList<T> & list)

Writes the listlist to streamout.

This function requires the value type to implementoperator<<().

See alsoFormat of the QDataStream operators.

QDataStream &operator>>(QDataStream & in,QList<T> & list)

Reads a list from streamin intolist.

This function requires the value type to implementoperator>>().

See alsoFormat of the QDataStream operators.