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

См. пример Кэша непрерывного доступа.

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

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

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

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

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

QContiguousCache::QContiguousCache(int capacity = 0)

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

См. также 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().

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

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

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

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

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