Struct qt_core::QVectorOf

#[repr(C)]
pub struct QVectorOf { /* fields omitted */ }

The QVector class is a template class that provides a dynamic array.

C++ class: QVector<void>.

C++ documentation:

The QVector class is a template class that provides a dynamic array.

QVector<T> is one of Qt's generic container classes. It stores its items in adjacent memory locations and provides fast index-based access.

QList<T>, QLinkedList<T>, QVector<T>, and QVarLengthArray<T> provide similar APIs and functionality. They are often interchangeable, but there are performance consequences. Here is an overview of use cases:

• QVector should be your default first choice. QVector<T> will usually give better performance than QList<T>, because QVector<T> always stores its items sequentially in memory, where QList<T> will allocate its items on the heap unless sizeof(T) <= sizeof(void*) and T has been declared to be either a Q_MOVABLE_TYPE or a Q_PRIMITIVE_TYPE using Q_DECLARE_TYPEINFO. See the Pros and Cons of Using QList for an explanation.
• However, QList is used throughout the Qt APIs for passing parameters and for returning values. Use QList to interface with those APIs.
• If you need a real linked list, which guarantees constant time insertions mid-list and uses iterators to items rather than indexes, use QLinkedList.

Note: QVector and QVarLengthArray both guarantee C-compatible array layout. QList does not. This might be important if your application must interface with a C API.

Note: Iterators into a QLinkedList and references into heap-allocating QLists remain valid as long as the referenced items remain in the container. This is not true for iterators and references into a QVector and non-heap-allocating QLists.

Here's an example of a QVector that stores integers and a QVector that stores QString values:

QVector<int> integerVector;
QVector<QString> stringVector;

QVector stores its items in a vector (array). Typically, vectors are created with an initial size. For example, the following code constructs a QVector with 200 elements:

QVector<QString> vector(200);

The elements are automatically initialized with a default-constructed value. If you want to initialize the vector with a different value, pass that value as the second argument to the constructor:

QVector<QString> vector(200, "Pass");

You can also call fill() at any time to fill the vector with a value.

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

if (vector[0] == "Liz")
      vector[0] = "Elizabeth";

For read-only access, an alternative syntax is to use at():

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

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

Another way to access the data stored in a QVector is to call data(). The function returns a pointer to the first item in the vector. You can use the pointer to directly access and modify the elements stored in the vector. The pointer is also useful if you need to pass a QVector to a function that accepts a plain C++ array.

If you want to find all occurrences of a particular value in a vector, use indexOf() or lastIndexOf(). The former searches forward starting from a given index position, the latter searches backward. Both return the index of the matching item if they found one; otherwise, they return -1. For example:

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

If you simply want to check whether a vector contains a particular value, use contains(). If you want to find out how many times a particular value occurs in the vector, use count().

QVector provides these basic functions to add, move, and remove items: insert(), replace(), remove(), prepend(), append(). With the exception of append() and replace(), these functions can be slow (linear time) for large vectors, because they require moving many items in the vector by one position in memory. If you want a container class that provides fast insertion/removal in the middle, use QList or QLinkedList instead.

Unlike plain C++ arrays, QVectors can be resized at any time by calling resize(). If the new size is larger than the old size, QVector might need to reallocate the whole vector. QVector tries to reduce the number of reallocations by preallocating up to twice as much memory as the actual data needs.

If you know in advance approximately how many items the QVector will contain, you can call reserve(), asking QVector to preallocate a certain amount of memory. You can also call capacity() to find out how much memory QVector actually allocated.

Note that using non-const operators and functions can cause QVector to do a deep copy of the data. This is due to implicit sharing.

QVector's value type must be an assignable data type. This covers most data types that are commonly used, but the compiler won't let you, for example, store a QWidget as a value; instead, store a QWidget *. A few functions have additional requirements; for example, indexOf() and lastIndexOf() expect the value type to support operator==(). These requirements are documented on a per-function basis.

Like the other container classes, QVector provides Java-style iterators (QVectorIterator and QMutableVectorIterator) and STL-style iterators (QVector::const_iterator and QVector::iterator). In practice, these are rarely used, because you can use indexes into the QVector.

In addition to QVector, Qt also provides QVarLengthArray, a very low-level class with little functionality that is optimized for speed.

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

More Information on Using Qt Containers

For a detailed discussion comparing Qt containers with each other and with STL containers, see Understand the Qt Containers.