Класс 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 *), элементы не инициализируются. Для других типов элементы инициализируются со значением по умолчанию.

QVarLengthArray::QVarLengthArray()

Конструирует массив с начальным размером ноль.

[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)

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

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

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

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

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

QVarLengthArray::const_iterator QVarLengthArray::constEnd() const

Возвращает указатель 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

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

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

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

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

Возвращает 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.

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, из массива. Возвращает, был ли элемент удалён.

Эта функция была введена в 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

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