Класс QVarLengthArray

Класс QVarLengthArray предоставляет массив переменной длины низкого уровня. Подробнее...

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

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

Типы

Общедоступные функции

Связанные нечленные функции

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

Язык C++ не поддерживает массивы переменной длины в стеке. Например, следующий код не будет компилироваться:

int myfunc(int n)
{
    int table[n + 1];  // WRONG
    ...
    return table[n];
}

Альтернативой является выделение массива в куче (с new):

int myfunc(int n)
{
    int *table = new int[n + 1];
    ...
    int ret = table[n];
    delete[] table;
    return ret;
}

Однако, если myfunc() вызывается очень часто из внутреннего цикла приложения, выделение в куче может стать основной причиной замедления.

QVarLengthArray — это попытка обойти этот пробел в языке C++. Он выделяет определённое количество элементов в стеке, и если вы изменяете размер массива на больший, он автоматически использует кучу. Выделение в стеке имеет преимущество, заключающееся в том, что оно намного быстрее, чем выделение в куче.

Пример:

int myfunc(int n)
{
    QVarLengthArray<int, 1024> array(n + 1);
    ...
    return array[n];
}

В приведённом выше примере QVarLengthArray предварительно выделит 1024 элемента в стеке и будет использовать их, если n + 1 больше, чем 1024. Если вы опустите второй шаблонный аргумент, будет использоваться значение по умолчанию QVarLengthArray — 256.

Тип значения QVarLengthArray должен быть типом, допускающим присваивание. Это охватывает большинство типов данных, которые обычно используются, но компилятор не позволит вам, например, хранить QWidget в качестве значения; вместо этого храните указатель на QWidget.

QVarLengthArray, как и QList, обеспечивает структуру данных изменяемого массива. Основные отличия между этими двумя классами:

• API QVarLengthArray намного более низкого уровня и ему не хватает некоторых функций QList.
• QVarLengthArray не инициализирует память, если значение — это базовый тип. (QList всегда делает это.)
• QList использует неявное совместное использование в качестве оптимизации памяти. QVarLengthArray не предоставляет эту функцию; однако, он обычно обеспечивает немного лучшую производительность благодаря снижению накладных расходов, особенно в плотных циклах.

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

См. также QList.

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

QVarLengthArray::const_iterator

Тип-синоним для const T *. Предоставлено для совместимости со STL.

QVarLengthArray::const_pointer

Тип-синоним для const T *. Предоставлено для совместимости со STL.

QVarLengthArray::const_reference

Тип-синоним для const T &. Предоставлено для совместимости со STL.

[since 5.6] QVarLengthArray::const_reverse_iterator

Тип-синоним для std::reverse_iterator<const T*>. Предоставлено для совместимости со STL.

Этот тип-синоним был введён в Qt 5.6.

QVarLengthArray::difference_type

Тип-синоним для ptrdiff_t. Предоставлено для совместимости со STL.

QVarLengthArray::iterator

Тип-синоним для T *. Предоставлено для совместимости со STL.

QVarLengthArray::pointer

Тип-синоним для T *. Предоставлено для совместимости со STL.

QVarLengthArray::reference

Тип-синоним для T &. Предоставлено для совместимости со STL.

[since 5.6] QVarLengthArray::reverse_iterator

Тип-синоним для std::reverse_iterator<T*>. Предоставлено для совместимости со STL.

Этот тип-синоним был введён в Qt 5.6.

QVarLengthArray::size_type

Тип-синоним для int. Предоставлено для совместимости со STL.

QVarLengthArray::value_type

Тип-синоним для T. Предоставлено для совместимости со STL.

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

Это перегруженный метод.

Вставляет value перед элементом, на который указывает итератор before. Возвращает итератор, указывающий на вставленный элемент.

Вставляет value в массив по индексу i. Если i равно 0, значение добавляется в начало вектора. Если i равно size(), значение добавляется в конец вектора.

Для больших массивов эта операция может быть медленной (время выполнения — линейное), так как требует перемещения всех элементов с индексами i и выше на одну позицию дальше в памяти. Если вам нужен класс контейнера с быстрой функцией insert(), используйте std::list вместо него.

См. также remove().

Вставляет value в начало массива.

Это то же самое, что vector.insert(0, value).

Для больших массивов эта операция может быть медленной (время выполнения — линейное), так как требует перемещения всех элементов вектора на одну позицию дальше в памяти. Если вам нужен класс контейнера с быстрой функцией prepend(), используйте std::list вместо него.

См. также append() и insert().

[since 5.14] template <typename InputIterator> QVarLengthArray::QVarLengthArray(InputIterator first, InputIterator last)

Создает массив со содержимым в диапазоне итераторов [first, last).

Тип значения InputIterator должен быть приводим к типу T.

Эта функция была добавлена в Qt 5.14.

[since 5.5] QVarLengthArray::QVarLengthArray(std::initializer_list<T> args)

Создаёт массив из std::initializer_list, заданной args.

Этот конструктор активен только если компилятор поддерживает C++11 initializer lists.

Эта функция была добавлена в Qt 5.5.

[since 6.0] QVarLengthArray::QVarLengthArray(QVarLengthArray<T, Prealloc> &&other = Prealloc)

Перемещающий конструктор этого массива переменной длины из other. После перемещения other становится пустым.

Эта функция была добавлена в Qt 6.0.

QVarLengthArray::QVarLengthArray(const QVarLengthArray<T, Prealloc> &other = Prealloc)

Создаёт копию other.

QVarLengthArray::QVarLengthArray(qsizetype size)

Создаёт массив с начальным размером size элементов.

Если тип значения является примитивным типом (например, char, int, float) или типом указателя (например, QWidget *), элементы не инициализируются. Для других типов элементы инициализируются с помощью значения по умолчанию.

[since 6.0] QVarLengthArray<T, Prealloc> &QVarLengthArray::operator=(QVarLengthArray<T, Prealloc> &&other = Prealloc)

Перемещающее присваивание other этому массиву и возвращает ссылку на этот массив. После перемещения other становится пустым.

Эта функция была добавлена в Qt 6.0.

QVarLengthArray<T, Prealloc> &QVarLengthArray::operator=(const QVarLengthArray<T, Prealloc> &other = Prealloc)

Присваивает other этому массиву и возвращает ссылку на этот массив.

QVarLengthArray::~QVarLengthArray()

Уничтожает массив.

void QVarLengthArray::append(const T &t)

Добавляет элемент t в массив, увеличивая массив при необходимости.

См. также removeLast().

[since 5.9] void QVarLengthArray::append(T &&t)

Этот метод перегружает append.

Примечание: В отличие от перегрузки append для lvalue, передача ссылки на объект, который уже является элементом *this приводит к неопределённому поведению:

vla.append(std::move(vla[0])); // BUG: passing an object that is already in the container

Эта функция была добавлена в Qt 5.9.

void QVarLengthArray::append(const T *buf, qsizetype size)

Добавляет size элементов, ссылающихся на buf в этот массив.

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

Возвращает ссылку на элемент по индексу i.

i должен быть корректным индексом в массиве (т.е., 0 <= i < size()).

См. также value() и operator[]().

[since 5.0] T &QVarLengthArray::back()

То же, что и last(). Предоставлено для совместимости со STL.

Эта функция была добавлена в Qt 5.0.

[since 5.0] const T &QVarLengthArray::back() const

Это перегруженный метод.

Эта функция была добавлена в Qt 5.0.

QVarLengthArray::iterator QVarLengthArray::begin()

Возвращает итератор STL, указывающий на первый элемент массива.

См. также constBegin() и end().

QVarLengthArray::const_iterator QVarLengthArray::begin() const

Это перегруженный метод.

qsizetype QVarLengthArray::capacity() const

Возвращает максимальное количество элементов, которое может храниться в массиве без принудительного перераспределения.

Единственная цель этой функции — предоставить способ точной настройки использования памяти QVarLengthArray. Как правило, вам редко понадобится вызывать эту функцию. Если вы хотите узнать, сколько элементов содержится в массиве, вызовите size().

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

[since 5.0] QVarLengthArray::const_iterator QVarLengthArray::cbegin() const

Возвращает постоянный итератор STL, указывающий на первый элемент массива.

Эта функция была добавлена в Qt 5.0.

См. также begin() и cend().

[since 5.0] QVarLengthArray::const_iterator QVarLengthArray::cend() const

Возвращает постоянный итератор STL, указывающий на воображаемый элемент после последнего элемента в массиве.

Эта функция была добавлена в Qt 5.0.

См. также cbegin() и end().

void QVarLengthArray::clear()

Удаляет все элементы из массива.

То же, что и resize(0).

QVarLengthArray::const_iterator QVarLengthArray::constBegin() const

Возвращает постоянный итератор STL, указывающий на первый элемент массива.

См. также begin() и constEnd().

const T *QVarLengthArray::constData() const

Возвращает постоянный указатель на данные, хранящиеся в массиве. Указатель может использоваться для доступа к элементам массива. Указатель остаётся допустимым до тех пор, пока массив не перераспределяется.

Эта функция полезна в основном для передачи массива функции, которая принимает обычный массив C++.

См. также data() и operator[]().

QVarLengthArray::const_iterator QVarLengthArray::constEnd() const

Возвращает константный итератор STL-стиля, указывающий на воображаемый элемент после последнего элемента в массиве.

См. также constBegin() и end().

[since 5.3] template <typename AT> bool QVarLengthArray::contains(const AT &value) const

Возвращает true, если массив содержит вхождение value; в противном случае возвращает false.

Эта функция требует, чтобы тип значения имел реализацию operator==().

Эта функция была добавлена в Qt 5.3.

См. также indexOf() и lastIndexOf().

qsizetype QVarLengthArray::count() const

То же, что и size().

См. также isEmpty() и resize().

[since 5.6] QVarLengthArray::const_reverse_iterator QVarLengthArray::crbegin() const

Возвращает константный итератор STL-стиля обратного поиска, указывающий на первый элемент в массиве переменной длины в обратном порядке.

Эта функция была добавлена в Qt 5.6.

См. также begin(), rbegin() и rend().

[since 5.6] QVarLengthArray::const_reverse_iterator QVarLengthArray::crend() const

Возвращает константный итератор STL-стиля обратного поиска, указывающий на элемент, следующий за последним элементом в массиве переменной длины, в обратном порядке.

Эта функция была добавлена в Qt 5.6.

См. также end(), rend() и rbegin().

T *QVarLengthArray::data()

Возвращает указатель на данные, хранящиеся в массиве. Указатель можно использовать для доступа к элементам и их изменения в массиве.

Пример:

QVarLengthArray<int> array(10);
int *data = array.data();
for (int i = 0; i < 10; ++i)
    data[i] = 2 * i;

Указатель остается действительным до тех пор, пока массив не перераспределяется.

Эта функция в основном полезна для передачи массива функции, принимающей обычный массив C++.

См. также constData() и operator[]().

const T *QVarLengthArray::data() const

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

[since 5.0] bool QVarLengthArray::empty() const

Возвращает true, если размер массива равен 0; в противном случае возвращает false.

То же, что и isEmpty(). Предоставлено для совместимости со STL.

Эта функция была добавлена в Qt 5.0.

QVarLengthArray::iterator QVarLengthArray::end()

Возвращает итератор STL-стиля, указывающий на воображаемый элемент после последнего элемента в массиве.

См. также begin() и constEnd().

QVarLengthArray::const_iterator QVarLengthArray::end() const

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

QVarLengthArray::iterator QVarLengthArray::erase(QVarLengthArray::const_iterator pos)

Удаляет элемент, на который указывает итератор pos, из вектора и возвращает итератор на следующий элемент в векторе (который может быть end()).

См. также insert() и remove().

QVarLengthArray::iterator QVarLengthArray::erase(QVarLengthArray::const_iterator begin, QVarLengthArray::const_iterator end)

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

Удаляет все элементы от begin до (но не включая) end. Возвращает итератор на тот же элемент, на который end ссылался до вызова.

T &QVarLengthArray::first()

Возвращает ссылку на первый элемент в массиве. Массив не должен быть пустым. Если массив может быть пустым, проверьте isEmpty() перед вызовом этой функции.

См. также last() и isEmpty().

const T &QVarLengthArray::first() const

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

[since 5.0] T &QVarLengthArray::front()

То же, что и first(). Предоставлено для совместимости со STL.

Эта функция была добавлена в Qt 5.0.

[since 5.0] const T &QVarLengthArray::front() const

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

Эта функция была добавлена в Qt 5.0.

[since 5.3] template <typename AT> qsizetype QVarLengthArray::indexOf(const AT &value, qsizetype from = 0) const

Возвращает индекс первого вхождения value в массиве, выполняя поиск вперед с индекса from. Возвращает -1, если элемент не найден.

Эта функция требует, чтобы тип значения имел реализацию operator==().

Эта функция была добавлена в Qt 5.3.

См. также lastIndexOf() и contains().

void QVarLengthArray::insert(qsizetype i, qsizetype count, const T &value)

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

Вставляет count копий value в позицию с индексом i в векторе.

QVarLengthArray::iterator QVarLengthArray::insert(QVarLengthArray::const_iterator before, qsizetype count, const T &value)

Вставляет count копий value перед элементом, на который указывает итератор before. Возвращает итератор, указывающий на первый из вставленных элементов.

bool QVarLengthArray::isEmpty() const

Возвращает true, если размер массива равен 0; в противном случае возвращает false.

См. также size() и resize().

T &QVarLengthArray::last()

Возвращает ссылку на последний элемент в массиве. Массив не должен быть пустым. Если массив может быть пустым, проверьте isEmpty() перед вызовом этой функции.

См. также first() и isEmpty().

const T &QVarLengthArray::last() const

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

[since 5.3] template <typename AT> qsizetype QVarLengthArray::lastIndexOf(const AT &value, qsizetype from = -1) const

Возвращает индекс последнего вхождения значения value в массиве, выполняя поиск назад с индекса from. Если from равно -1 (по умолчанию), поиск начинается с последнего элемента. Возвращает -1, если элемент не найден.

Эта функция требует, чтобы тип значения имел реализацию operator==().

Эта функция была добавлена в Qt 5.3.

См. также indexOf() и contains().

[since 5.0] qsizetype QVarLengthArray::length() const

То же, что и size().

Эта функция была добавлена в Qt 5.0.

См. также isEmpty() и resize().

[since 5.0] void QVarLengthArray::pop_back()

То же, что и removeLast(). Предоставлено для совместимости со STL.

Эта функция была добавлена в Qt 5.0.

[since 5.0] void QVarLengthArray::push_back(const T &t)

Добавляет элемент t в массив, расширяя массив при необходимости. Предоставлено для совместимости со STL.

Эта функция была добавлена в Qt 5.0.

[since 5.9] void QVarLengthArray::push_back(T &&t)

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

Примечание: В отличие от перегрузки push_back() для lvalue, передача ссылки на объект, который уже является элементом *this приводит к неопределенному поведению:

vla.push_back(std::move(vla[0])); // BUG: passing an object that is already in the container

Эта функция была добавлена в Qt 5.9.

[since 5.6] QVarLengthArray::reverse_iterator QVarLengthArray::rbegin()

Возвращает обратный итератор STL, указывающий на первый элемент в массиве переменной длины в обратном порядке.

Эта функция была добавлена в Qt 5.6.

См. также begin(), crbegin() и rend().

[since 5.6] QVarLengthArray::const_reverse_iterator QVarLengthArray::rbegin() const

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

Эта функция была добавлена в Qt 5.6.

void QVarLengthArray::remove(qsizetype i)

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

Удаляет элемент по индексу i.

См. также insert() и replace().

void QVarLengthArray::remove(qsizetype i, qsizetype count)

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

Удаляет count элементов из середины массива, начиная с позиции i.

См. также insert() и replace().

[since 6.1] template <typename AT> qsizetype QVarLengthArray::removeAll(const AT &t)

Удаляет все элементы, которые равны t, из массива. Возвращает количество удаленных элементов (если таковые имеются).

Эта функция была добавлена в Qt 6.1.

См. также removeOne().

[since 6.1] template <typename Predicate> qsizetype QVarLengthArray::removeIf(Predicate pred)

Удаляет все элементы, для которых предикат pred возвращает true, из массива. Возвращает количество удаленных элементов (если таковые имеются).

Эта функция была добавлена в Qt 6.1.

См. также removeAll().

void QVarLengthArray::removeLast()

Уменьшает размер массива на единицу. Выделенная память не меняется.

См. также append().

[since 6.1] template <typename AT> bool QVarLengthArray::removeOne(const AT &t)

Удаляет первый элемент, равный t, из массива. Возвращает true, если элемент был удален, в противном случае false.

Эта функция была добавлена в Qt 6.1.

См. также removeAll().

[since 5.6] QVarLengthArray::reverse_iterator QVarLengthArray::rend()

Возвращает обратный итератор STL, указывающий на позицию после последнего элемента в массиве переменной длины в обратном порядке.

Эта функция была добавлена в Qt 5.6.

См. также end(), crend() и rbegin().

[since 5.6] QVarLengthArray::const_reverse_iterator QVarLengthArray::rend() const

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

Эта функция была добавлена в Qt 5.6.

void QVarLengthArray::replace(qsizetype i, const T &value)

Заменяет элемент по индексу i значением value.

i должен быть допустимым индексом в массиве (т.е., 0 <= i < size()).

См. также operator[]() и remove().

void QVarLengthArray::reserve(qsizetype size)

Попытка выделить память для как минимум size элементов. Если заранее известно, какой максимальный размер может быть у массива, можно вызвать эту функцию. Частое использование resize() может улучшить производительность. Если size является заниженной оценкой, худшим результатом будет незначительное замедление работы QVarLengthArray.

Единственная цель этой функции — дать возможность точной настройки использования памяти QVarLengthArray. Как правило, вам редко понадобится вызывать эту функцию. Если нужно изменить размер массива, используйте resize().

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

void QVarLengthArray::resize(qsizetype size)

Устанавливает размер массива в size. Если size больше текущего размера, элементы добавляются в конец. Если size меньше текущего размера, элементы удаляются с конца.

Если тип значения является примитивным типом (например, char, int, float) или типом указателя (например, QWidget *), новые элементы не инициализируются. Для других типов элементы инициализируются с помощью значения по умолчанию.

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

[since 5.10] void QVarLengthArray::shrink_to_fit()

То же, что и squeeze(). Предоставлено для совместимости со STL.

Эта функция была добавлена в Qt 5.10.

qsizetype QVarLengthArray::size() const

Возвращает количество элементов в массиве.

См. также isEmpty() и resize().

[since 5.1] void QVarLengthArray::squeeze()

Освобождает любую память, не необходимую для хранения элементов. Если контейнер может поместить свое хранилище в стековой памяти, он освободит кучевую память и скопирует элементы обратно в стек.

Единственная цель этой функции — дать возможность точной настройки использования памяти QVarLengthArray. Как правило, вам редко понадобится вызывать эту функцию.

Эта функция была добавлена в Qt 5.1.

См. также reserve(), capacity() и resize().

T QVarLengthArray::value(qsizetype i) const

Возвращает значение по индексу i.

Если индекс i выходит за пределы массива, функция возвращает значение по умолчанию. Если вы уверены, что i находится в пределах массива, можно использовать at(), что немного быстрее.

См. также at() и operator[]().

T QVarLengthArray::value(qsizetype i, const T &defaultValue) const

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

Если индекс i выходит за пределы массива, функция возвращает defaultValue.

QVarLengthArray<T, Prealloc> &QVarLengthArray::operator+=(const T &value)

Добавляет value в конец массива и возвращает ссылку на этот массив.

См. также append() и operator<<().

[since 5.11] QVarLengthArray<T, Prealloc> &QVarLengthArray::operator+=(T &&value)

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

Эта функция была добавлена в Qt 5.11.

См. также append() и operator<<().

QVarLengthArray<T, Prealloc> &QVarLengthArray::operator<<(const T &value)

Добавляет value в конец массива и возвращает ссылку на этот массив.

См. также append() и operator+=().

[since 5.11] QVarLengthArray<T, Prealloc> &QVarLengthArray::operator<<(T &&value)

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

Эта функция была добавлена в Qt 5.11.

См. также append() и operator+=().

[since 5.5] QVarLengthArray<T, Prealloc> &QVarLengthArray::operator=(std::initializer_list<T> list)

Присваивает значения из list этому массиву и возвращает ссылку на этот массив.

Этот конструктор доступен только если компилятор поддерживает C++11 списки инициализации.

Эта функция была добавлена в Qt 5.5.

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

Возвращает ссылку на элемент по индексу i.

i должен быть допустимым индексом в массиве (т.е., 0 <= i < size()).

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

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

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