Класс QContiguousCache

Класс 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(int capacity = 0)

Конструирует кэш с заданной capacity.

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

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

Конструирует копию other.

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

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

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==().

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

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

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

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

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

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() для чтения только для доступа к не-const QContiguousCache.

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

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

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

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