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

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

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

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)

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

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

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

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

void QContiguousCache::removeFirst()

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

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

void QContiguousCache::removeLast()

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

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

void QContiguousCache::setCapacity(qsizetype size)

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

Если заданное значение size меньше текущего количества элементов в кэше, то останутся только последние 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().

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[](qsizetype i)

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

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

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

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

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

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