QVector Class

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

Header: #include <QVector>
qmake: QT += core

Note: All functions in this class are reentrant.

Public Types

typedef ConstIterator
typedef Iterator
typedef const_iterator
typedef const_pointer
typedef const_reference
typedef const_reverse_iterator
typedef difference_type
typedef iterator
typedef pointer
typedef reference
typedef reverse_iterator
typedef size_type
typedef value_type

Public Functions

QVector()
QVector(int size)
QVector(int size, const T &t)
QVector(const QVector<T> &v)
QVector(QVector<T> &&other)
QVector(std::initializer_list<T> args)
~QVector()
void append(const T &t)
void append(T &&t)
void append(const QVector<T> &l)
const T &at(int i) const
QVector::reference back()
QVector::const_reference back() const
QVector::iterator begin()
QVector::const_iterator begin() const
int capacity() const
QVector::const_iterator cbegin() const
QVector::const_iterator cend() const
void clear()
QVector::const_iterator constBegin() const
const T *constData() const
QVector::const_iterator constEnd() const
const T &constFirst() const
const T &constLast() const
bool contains(const T &t) const
int count(const T &t) const
int count() const
QVector::const_reverse_iterator crbegin() const
QVector::const_reverse_iterator crend() const
T *data()
const T *data() const
void detach()
bool empty() const
QVector::iterator end()
QVector::const_iterator end() const
bool endsWith(const T &t) const
QVector::iterator erase(QVector::iterator begin, QVector::iterator end)
QVector::iterator erase(QVector::iterator pos)
QVector<T> &fill(const T &t, int size = -1)
T &first()
const T &first() const
T &front()
QVector::const_reference front() const
int indexOf(const T &t, int from = 0) const
void insert(int i, T &&t)
void insert(int i, const T &t)
void insert(int i, int n, const T &t)
QVector::iterator insert(QVector::iterator before, int n, const T &x)
QVector::iterator insert(QVector::iterator before, const T &x)
QVector::iterator insert(QVector::iterator before, T &&x)
bool isDetached() const
bool isEmpty() const
bool isSharedWith(const QVector<T> &other) const
T &last()
const T &last() const
int lastIndexOf(const T &t, int from = -1) const
int length() const
QVector<T> mid(int pos, int len = -1) const
void move(int from, int to)
void pop_back()
void pop_front()
void prepend(T &&t)
void prepend(const T &t)
void push_back(const T &t)
void push_back(T &&t)
void push_front(T &&t)
void push_front(const T &t)
QVector::reverse_iterator rbegin()
QVector::const_reverse_iterator rbegin() const
void remove(int i)
void remove(int i, int n)
int removeAll(const T &t)
void removeAt(int i)
void removeFirst()
void removeLast()
bool removeOne(const T &t)
QVector::reverse_iterator rend()
QVector::const_reverse_iterator rend() const
void replace(int i, const T &t)
void reserve(int size)
void resize(int size)
void setSharable(bool sharable)
void shrink_to_fit()
int size() const
void squeeze()
bool startsWith(const T &t) const
void swap(QVector<T> &other)
T takeAt(int i)
T takeFirst()
T takeLast()
QList<T> toList() const
std::vector<T> toStdVector() const
T value(int i) const
T value(int i, const T &defaultValue) const
bool operator!=(const QVector<T> &v) const
QVector<T> operator+(const QVector<T> &l) const
QVector<T> &operator+=(const QVector<T> &l)
QVector<T> &operator+=(const T &t)
QVector<T> &operator+=(T &&t)
QVector<T> &operator<<(const T &t)
QVector<T> &operator<<(const QVector<T> &l)
QVector<T> &operator<<(T &&t)
QVector<T> &operator=(const QVector<T> &v)
QVector<T> &operator=(QVector<T> &&other)
bool operator==(const QVector<T> &v) const
T &operator[](int i)
const T &operator[](int i) const

Static Public Members

QVector<T> fromList(const QList<T> &list)
QVector<T> fromStdVector(const std::vector<T> &vector)

Detailed Description

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.

See also QVectorIterator, QMutableVectorIterator, QList, and QLinkedList.

Member Type Documentation

typedef QVector::ConstIterator

Qt-style synonym for QVector::const_iterator.

typedef QVector::Iterator

Qt-style synonym for QVector::iterator.

typedef QVector::const_iterator

The QVector::const_iterator typedef provides an STL-style const iterator for QVector and QStack.

QVector provides both STL-style iterators and Java-style iterators. The STL-style const iterator is simply a typedef for "const T *" (pointer to const T).

Warning: Iterators on implicitly shared containers do not work exactly like STL-iterators. You should avoid copying a container while iterators are active on that container. For more information, read Implicit sharing iterator problem.

See also QVector::constBegin(), QVector::constEnd(), QVector::iterator, and QVectorIterator.

typedef QVector::const_pointer

Typedef for const T *. Provided for STL compatibility.

typedef QVector::const_reference

Typedef for T &. Provided for STL compatibility.

typedef QVector::const_reverse_iterator

The QVector::const_reverse_iterator typedef provides an STL-style const reverse iterator for QVector.

It is simply a typedef for std::reverse_iterator<const T*>.

Warning: Iterators on implicitly shared containers do not work exactly like STL-iterators. You should avoid copying a container while iterators are active on that container. For more information, read Implicit sharing iterator problem.

This typedef was introduced in Qt 5.6.

See also QVector::rbegin(), QVector::rend(), QVector::reverse_iterator, and QVector::const_iterator.

typedef QVector::difference_type

Typedef for ptrdiff_t. Provided for STL compatibility.

typedef QVector::iterator

The QVector::iterator typedef provides an STL-style non-const iterator for QVector and QStack.

QVector provides both STL-style iterators and Java-style iterators. The STL-style non-const iterator is simply a typedef for "T *" (pointer to T).

Warning: Iterators on implicitly shared containers do not work exactly like STL-iterators. You should avoid copying a container while iterators are active on that container. For more information, read Implicit sharing iterator problem.

See also QVector::begin(), QVector::end(), QVector::const_iterator, and QMutableVectorIterator.

typedef QVector::pointer

Typedef for T *. Provided for STL compatibility.

typedef QVector::reference

Typedef for T &. Provided for STL compatibility.

typedef QVector::reverse_iterator

The QVector::reverse_iterator typedef provides an STL-style non-const reverse iterator for QVector.

It is simply a typedef for std::reverse_iterator<T*>.

Warning: Iterators on implicitly shared containers do not work exactly like STL-iterators. You should avoid copying a container while iterators are active on that container. For more information, read Implicit sharing iterator problem.

This typedef was introduced in Qt 5.6.

See also QVector::rbegin(), QVector::rend(), QVector::const_reverse_iterator, and QVector::iterator.

typedef QVector::size_type

Typedef for int. Provided for STL compatibility.

typedef QVector::value_type

Typedef for T. Provided for STL compatibility.

Member Function Documentation

QVector::QVector()

Default constructs an instance of QVector.

QVector::QVector(int size)

Default constructs an instance of QVector.

QVector::QVector(int size, const T &t)

Default constructs an instance of QVector.

QVector::QVector(const QVector<T> &v)

Default constructs an instance of QVector.

QVector::QVector(QVector<T> &&other)

Default constructs an instance of QVector.

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

Default constructs an instance of QVector.

QVector::~QVector()

Destroys the instance of QVector.

void QVector::append(const T &t)

void QVector::append(T &&t)

void QVector::append(const QVector<T> &l)

const T &QVector::at(int i) const

QVector::reference QVector::back()

QVector::const_reference QVector::back() const

QVector::iterator QVector::begin()

QVector::const_iterator QVector::begin() const

int QVector::capacity() const

QVector::const_iterator QVector::cbegin() const

QVector::const_iterator QVector::cend() const

void QVector::clear()

QVector::const_iterator QVector::constBegin() const

const T *QVector::constData() const

QVector::const_iterator QVector::constEnd() const

const T &QVector::constFirst() const

const T &QVector::constLast() const

bool QVector::contains(const T &t) const

int QVector::count(const T &t) const

int QVector::count() const

QVector::const_reverse_iterator QVector::crbegin() const

QVector::const_reverse_iterator QVector::crend() const

T *QVector::data()

const T *QVector::data() const

void QVector::detach()

bool QVector::empty() const

QVector::iterator QVector::end()

QVector::const_iterator QVector::end() const

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

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

QVector::iterator QVector::erase(QVector::iterator pos)

QVector<T> &QVector::fill(const T &t, int size = -1)

T &QVector::first()

const T &QVector::first() const

[static] QVector<T> QVector::fromList(const QList<T> &list)

[static] QVector<T> QVector::fromStdVector(const std::vector<T> &vector)

T &QVector::front()

QVector::const_reference QVector::front() const

int QVector::indexOf(const T &t, int from = 0) const

void QVector::insert(int i, T &&t)

void QVector::insert(int i, const T &t)

void QVector::insert(int i, int n, const T &t)

QVector::iterator QVector::insert(QVector::iterator before, int n, const T &x)

QVector::iterator QVector::insert(QVector::iterator before, const T &x)

QVector::iterator QVector::insert(QVector::iterator before, T &&x)

bool QVector::isDetached() const

bool QVector::isEmpty() const

bool QVector::isSharedWith(const QVector<T> &other) const

T &QVector::last()

const T &QVector::last() const

int QVector::lastIndexOf(const T &t, int from = -1) const

int QVector::length() const

QVector<T> QVector::mid(int pos, int len = -1) const

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

void QVector::pop_back()

void QVector::pop_front()

void QVector::prepend(T &&t)

void QVector::prepend(const T &t)

void QVector::push_back(const T &t)

void QVector::push_back(T &&t)

void QVector::push_front(T &&t)

void QVector::push_front(const T &t)

QVector::reverse_iterator QVector::rbegin()

QVector::const_reverse_iterator QVector::rbegin() const

void QVector::remove(int i)

void QVector::remove(int i, int n)

int QVector::removeAll(const T &t)

void QVector::removeAt(int i)

void QVector::removeFirst()

void QVector::removeLast()

bool QVector::removeOne(const T &t)

QVector::reverse_iterator QVector::rend()

QVector::const_reverse_iterator QVector::rend() const

void QVector::replace(int i, const T &t)

void QVector::reserve(int size)

void QVector::resize(int size)

void QVector::setSharable(bool sharable)

void QVector::shrink_to_fit()

int QVector::size() const

void QVector::squeeze()

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

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

T QVector::takeAt(int i)

T QVector::takeFirst()

T QVector::takeLast()

QList<T> QVector::toList() const

std::vector<T> QVector::toStdVector() const

T QVector::value(int i) const

T QVector::value(int i, const T &defaultValue) const

bool QVector::operator!=(const QVector<T> &v) const

QVector<T> QVector::operator+(const QVector<T> &l) const

QVector<T> &QVector::operator+=(const QVector<T> &l)

QVector<T> &QVector::operator+=(const T &t)

QVector<T> &QVector::operator+=(T &&t)

QVector<T> &QVector::operator<<(const T &t)

QVector<T> &QVector::operator<<(const QVector<T> &l)

QVector<T> &QVector::operator<<(T &&t)

QVector<T> &QVector::operator=(const QVector<T> &v)

Copy-assignment operator.

QVector<T> &QVector::operator=(QVector<T> &&other)

Move-assignment operator.

bool QVector::operator==(const QVector<T> &v) const

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

const T &QVector::operator[](int i) const