Revision control
++ // Copyright (C) 2016 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
++
++ /*!
++ \example tools/contiguouscache
++ \title Contiguous Cache Example
++ \examplecategory {Data Processing & I/O}
++ \ingroup corelib_examples
++
++ \brief The Contiguous Cache example shows how to use QContiguousCache to manage memory usage for
++ very large models. In some environments memory is limited and, even when it
++ isn't, users still dislike an application using excessive memory.
++ Using QContiguousCache to manage a list, rather than loading
++ the entire list into memory, allows the application to limit the amount
++ of memory it uses, regardless of the size of the data set it accesses.
++
++ The simplest way to use QContiguousCache is to cache as items are requested. When
++ a view requests an item at row N it is also likely to ask for items at rows near
++ to N.
++
++ \snippet tools/contiguouscache/randomlistmodel.cpp 0
++
++ After getting the row, the class determines if the row is in the bounds
++ of the contiguous cache's current range. It would have been equally valid to
++ simply have the following code instead.
++
++ \code
++ while (row > m_rows.lastIndex())
++ m_rows.append(fetchWord(m_rows.lastIndex()+1);
++ while (row < m_rows.firstIndex())
++ m_rows.prepend(fetchWord(m_rows.firstIndex()-1);
++ \endcode
++
++ However a list will often jump rows if the scroll bar is used directly, resulting in
++ the code above causing every row between the old and new rows to be fetched.
++
++ Using QContiguousCache::lastIndex() and QContiguousCache::firstIndex() allows
++ the example to determine what part of the list the cache is currently caching.
++ These values don't represent the indexes into the cache's own memory, but rather
++ a virtual infinite array that the cache represents.
++
++ By using QContiguousCache::append() and QContiguousCache::prepend() the code ensures
++ that items that may be still on the screen are not lost when the requested row
++ has not moved far from the current cache range. QContiguousCache::insert() can
++ potentially remove more than one item from the cache as QContiguousCache does not
++ allow for gaps. If your cache needs to quickly jump back and forth between
++ rows with significant gaps between them consider using QCache instead.
++
++ And that's it. A perfectly reasonable cache, using minimal memory for a very large
++ list. In this case the accessor for getting the words into the cache
++ generates random information rather than fixed information. This allows you
++ to see how the cache range is kept for a local number of rows when running the
++ example.
++
++ \snippet tools/contiguouscache/randomlistmodel.cpp 1
++
++ It is also worth considering pre-fetching items into the cache outside of the
++ application's paint routine. This can be done either with a separate thread
++ or using a QTimer to incrementally expand the range of the cache prior to
++ rows being requested out of the current cache range.
++ */