Класс QContiguousCache

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

Этот класс был представлен в Qt 4.6.

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

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

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

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

Класс 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() использовать не нужно.

См. пример Contiguous Cache.

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

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

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

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

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

QContiguousCache::QContiguousCache(int capacity = 0)

Создаёт кэш с заданной capacity.

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

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)

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

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

bool QContiguousCache::areIndexesValid() const

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

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

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

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

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

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

int QContiguousCache::available() const

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

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

int QContiguousCache::capacity() const

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

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

void QContiguousCache::clear()

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

bool QContiguousCache::containsIndex(int i) const

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

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

int QContiguousCache::count() const

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

T &QContiguousCache::first()

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

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

const T &QContiguousCache::first() const

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

int QContiguousCache::firstIndex() const

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

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

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

Вставляет 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

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

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

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

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

void QContiguousCache::removeFirst()

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

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

void QContiguousCache::removeLast()

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

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

void QContiguousCache::setCapacity(int size)

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

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

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

int QContiguousCache::size() const

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

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

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

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

Данная функция была добавлена в Qt 4.8.

T QContiguousCache::takeFirst()

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

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

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

T QContiguousCache::takeLast()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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