Класс QContiguousCache

Класс QContiguousCache — это шаблонный класс, предоставляющий непрерывный кэш. Подробнее...

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

Примечание: Все функции в этом классе являются реентерабельными.

Открытые функции

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

Класс QContiguousCache предоставляет эффективный способ кеширования элементов для отображения в представлении пользовательского интерфейса. В отличие от QCache, он добавляет ограничение, что элементы в кэше расположены непрерывно. Это имеет преимущество соответствия тому, как представления пользовательского интерфейса чаще всего запрашивают данные, как набор строк, локализованных вокруг текущей прокрученной позиции. Это ограничение позволяет кэшу потреблять меньше памяти и процессорного времени, чем QCache.

QContiguousCache работает с фиксированной емкостью, заданной с помощью setCapacity() или переданной в качестве параметра конструктору. Эта емкость — верхняя граница использования памяти самим кэшем, не включая память, выделенную самими элементами. Обратите внимание, что кэш с емкостью ноль (по умолчанию) означает, что элементы не будут храниться: операции insert(), append() и prepend() фактически будут операциями-не действиями. Поэтому важно задать емкость разумному значению перед добавлением элементов в кэш.

Самый простой способ использования непрерывного кэша — использовать append() и prepend().

MyRecord record(int row) const
{
    Q_ASSERT(row >= 0 && row < count());

    while (row > cache.lastIndex())
        cache.append(slowFetchRecord(cache.lastIndex()+1));
    while (row < cache.firstIndex())
        cache.prepend(slowFetchRecord(cache.firstIndex()-1));

    return cache.at(row);
}

Если кэш заполнен, то элемент в противоположном конце кэша от того, где добавлен новый элемент, будет удалён.

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

Диапазон допустимых индексов для класса QContiguousCache составляет от 0 до INT_MAX. Вызов prepend() таким образом, что первый индекс станет меньше 0, или append() таким образом, что последний индекс станет больше INT_MAX, может привести к тому, что индексы кэша станут недопустимыми. Когда индексы кэша недопустимы, важно вызвать normalizeIndexes() перед вызовом любого из containsIndex(), firstIndex(), lastIndex(), at() или operator[](). Вызов этих функций при недопустимых индексах кэша приведёт к неопределённому поведению. Индексы можно проверить с помощью areIndexesValid()

В большинстве случаев индексы не будут превышать 0 до INT_MAX, и normalizeIndexes() использовать не нужно.

См. пример Кэша непрерывного хранения.

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

QContiguousCache::QContiguousCache(const QContiguousCache<T> &other)

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

Эта операция занимает постоянное время, потому что QContiguousCache является неявным общим. Это делает возврат QContiguousCache из функции очень быстрым. Если изменён общий экземпляр, он будет скопирован (copy-on-write), и это занимает линейное время.

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

QContiguousCache::QContiguousCache(qsizetype capacity = 0)

Создаёт кэш с заданной емкостью.

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

[since 5.2] QContiguousCache<T> &QContiguousCache::operator=(QContiguousCache<T> &&other)

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

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

QContiguousCache<T> &QContiguousCache::operator=(const QContiguousCache<T> &other)

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

QContiguousCache::~QContiguousCache()

Удаляет кэш.

void QContiguousCache::append(const T &value)

Вставляет значение в конец кэша. Если кэш уже заполнен, элемент в начале кэша будет удалён.

См. также prepend(), insert(), и isFull().

bool QContiguousCache::areIndexesValid() const

Возвращает, являются ли индексы элементов, хранящихся в кэше, валидными. Индексы могут стать невалидными, если элементы добавляются после позиции индекса INT_MAX или перед позицией индекса 0. Это ожидается только при очень длительном использовании кэша в стиле кольцевого буфера. Индексы можно сделать валидными снова, вызвав normalizeIndexes().

См. также normalizeIndexes(), append(), и prepend().

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

Возвращает элемент по индексу i в кэше. i должен быть валидным индексом в кэше (т. е., firstIndex() <= i <= lastIndex()).

Индексы в кэше относятся к количеству позиций, на которые элемент удалён от первого добавленного элемента в кэш. То есть, кэш с емкостью 100, в который было добавлено 150 элементов, будет иметь допустимый диапазон индексов от 50 до 149. Это позволяет вставлять и извлекать элементы в кэш, основываясь на теоретическом бесконечном списке

См. также firstIndex(), lastIndex(), insert(), и operator[]().

qsizetype QContiguousCache::available() const

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

См. также size(), capacity(), и isFull().

qsizetype QContiguousCache::capacity() const

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

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

void QContiguousCache::clear()

Удаляет все элементы из кэша. Емкость не изменяется.

bool QContiguousCache::containsIndex(qsizetype i) const

Возвращает true если диапазон индексов кэша включает указанный индекс i.

См. также firstIndex() и lastIndex().

qsizetype QContiguousCache::count() const

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

T &QContiguousCache::first()

Возвращает ссылку на первый элемент в кэше. Эта функция предполагает, что кэш не пуст.

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

const T &QContiguousCache::first() const

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

qsizetype QContiguousCache::firstIndex() const

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

См. также capacity(), size(), и lastIndex().

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

Вставляет значение в позицию индекса i. Если кэш уже содержит элемент в i, то это значение заменяется. Если i на единицу больше lastIndex() или на единицу меньше firstIndex(), это эквивалентно append() или prepend().

Если заданный индекс i не входит в текущий диапазон кэша и не примыкает к границам диапазона индексов кэша, кэш сначала очищается перед вставкой элемента. В этот момент размер кэша будет 1. Стоит приложить усилия, чтобы вставлять элементы в порядке, начинающемся рядом с текущим диапазоном индексов кэша.

Диапазон допустимых индексов для класса QContiguousCache составляет от 0 до INT_MAX. Вставка вне этого диапазона имеет неопределённое поведение.

См. также prepend(), append(), isFull(), firstIndex(), и lastIndex().

bool QContiguousCache::isEmpty() const

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

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

bool QContiguousCache::isFull() const

Возвращает true если количество элементов, хранящихся в кэше, равно емкости кэша.

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

T &QContiguousCache::last()

Возвращает ссылку на последний элемент в кэше. Эта функция предполагает, что кэш не пуст.

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

const T &QContiguousCache::last() const

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

qsizetype QContiguousCache::lastIndex() const

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

См. также capacity(), size(), и firstIndex().

void QContiguousCache::normalizeIndexes()

Перемещает первый и последний индексы кэша таким образом, чтобы они указывали на валидные индексы. Функция не изменяет содержимое кэша или порядок элементов в кэше.

Она предоставляется для исправления переполнений индексов при использовании кэша как кольцевого буфера.

QContiguousCache<int> cache(10);
cache.insert(INT_MAX, 1); // cache contains one value and has valid indexes, INT_MAX to INT_MAX
cache.append(2); // cache contains two values but does not have valid indexes.
cache.normalizeIndexes(); // cache has two values, 1 and 2.  New first index will be in the range of 0 to capacity().

См. также areIndexesValid(), append(), и prepend().

void QContiguousCache::prepend(const T &value)

Вставляет значение в начало кэша. Если кэш уже заполнен, элемент в конце кэша будет удалён.

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

void QContiguousCache::removeFirst()

Удаляет первый элемент из кэша. Эта функция предполагает, что кэш не пуст.

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

void QContiguousCache::removeLast()

Удаляет последний элемент из кэша. Эта функция предполагает, что кэш не пуст.

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

void QContiguousCache::setCapacity(qsizetype size)

Устанавливает емкость кэша на заданный размер. Кэш может содержать количество элементов, равное его емкости. При вставке, добавлении или предварительной вставке элементов в кэш, если кэш уже заполнен, то элемент, наиболее удаленный от добавляемого элемента, будет удален.

Если заданный размер меньше текущего количества элементов в кэше, то останутся только последние размер элементов из кэша.

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

qsizetype QContiguousCache::size() const

Возвращает количество элементов, содержащихся в кэше.

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

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

Меняет местами кэш other с этим кэшем. Эта операция очень быстрая и никогда не завершается ошибкой.

T QContiguousCache::takeFirst()

Удаляет первый элемент в кэше и возвращает его. Эта функция предполагает, что кэш не пуст.

Если вам не нужно значение возвращаемое функцией, removeFirst() более эффективна.

См. также takeLast() и removeFirst().

T QContiguousCache::takeLast()

Удаляет последний элемент в кэше и возвращает его. Эта функция предполагает, что кэш не пуст.

Если вам не нужно значение возвращаемое функцией, removeLast() более эффективна.

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

template <typename U> QTypeTraits::compare_eq_result<U> QContiguousCache::operator!=(const QContiguousCache<T> &other) const

Возвращает true если other не равно этому кэшу; в противном случае возвращает false.

Два кэша считаются равными, если они содержат одинаковые значения в одинаковых индексах. Эта функция требует, чтобы тип значения реализовывал operator==().

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

template <typename U> QTypeTraits::compare_eq_result<U> QContiguousCache::operator==(const QContiguousCache<T> &other) const

Возвращает true если other равно этому кэшу; в противном случае возвращает false.

Два кэша считаются равными, если они содержат одинаковые значения в одинаковых индексах. Эта функция требует, чтобы тип значения реализовывал operator==().

См. также operator!=().

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

Возвращает элемент с индексом i как ссылку на изменяемый объект. Если кэш не содержит элемента с данным индексом i, то сначала вставится пустой элемент в эту позицию.

В большинстве случаев лучше использовать либо at(), либо insert().

Примечание: Этот неконстантный перегруз оператора [] требует от QContiguousCache создавать глубокую копию. Используйте at() для чтения неизменяемого QContiguousCache.

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

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

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

То же самое, что и at(i).