/**************************************************************************** | |
** | |
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). | |
** All rights reserved. | |
** Contact: Nokia Corporation (qt-info@nokia.com) | |
** | |
** This file is part of the documentation of the Qt Toolkit. | |
** | |
** $QT_BEGIN_LICENSE:FDL$ | |
** GNU Free Documentation License | |
** Alternatively, this file may be used under the terms of the GNU Free | |
** Documentation License version 1.3 as published by the Free Software | |
** Foundation and appearing in the file included in the packaging of | |
** this file. | |
** | |
** Other Usage | |
** Alternatively, this file may be used in accordance with the terms | |
** and conditions contained in a signed written agreement between you | |
** and Nokia. | |
** | |
** | |
** | |
** | |
** $QT_END_LICENSE$ | |
** | |
****************************************************************************/ | |
/*! | |
\class Q3Cache | |
\brief The Q3Cache class is a template class that provides a cache based on QString keys. | |
\compat | |
A cache is a least recently used (LRU) list of cache items. Each | |
cache item has a key and a certain cost. The sum of item costs, | |
totalCost(), never exceeds the maximum cache cost, maxCost(). If | |
inserting a new item would cause the total cost to exceed the | |
maximum cost, the least recently used items in the cache are | |
removed. | |
Q3Cache is a template class. Q3Cache\<X\> defines a cache that | |
operates on pointers to X, or X*. | |
Apart from insert(), by far the most important function is find() | |
(which also exists as operator[]()). This function looks up an | |
item, returns it, and by default marks it as being the most | |
recently used item. | |
There are also methods to remove() or take() an object from the | |
cache. Calling setAutoDelete(TRUE) for a cache tells it to delete | |
items that are removed. The default is to not delete items when | |
they are removed (i.e., remove() and take() are equivalent). | |
When inserting an item into the cache, only the pointer is copied, | |
not the item itself. This is called a shallow copy. It is possible | |
to make the cache copy all of the item's data (known as a deep | |
copy) when an item is inserted. insert() calls the virtual | |
function Q3PtrCollection::newItem() for the item to be inserted. | |
Inherit a cache and reimplement newItem() if you want deep copies. | |
When removing a cache item, the virtual function | |
Q3PtrCollection::deleteItem() is called. The default | |
implementation deletes the item if auto-deletion is enabled, and | |
does nothing otherwise. | |
There is a Q3CacheIterator that can be used to traverse the items | |
in the cache in arbitrary order. | |
In Q3Cache, the cache items are accessed via QString keys, which | |
are Unicode strings. If you want to use non-Unicode, plain 8-bit | |
\c char* keys, use the Q3AsciiCache template. A Q3Cache has the | |
same performance as a Q3AsciiCache. | |
\sa Q3CacheIterator, Q3AsciiCache, Q3IntCache | |
*/ | |
/*! | |
\fn Q3Cache::Q3Cache( const Q3Cache<type> &c ) | |
\internal | |
Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. | |
*/ | |
/*! | |
\fn Q3Cache::Q3Cache( int maxCost, int size, bool caseSensitive ) | |
Constructs a cache whose contents will never have a total cost | |
greater than \a maxCost and which is expected to contain less than | |
\a size items. | |
\a size is actually the size of an internal hash array; it's | |
usually best to make it a prime number and at least 50% bigger | |
than the largest expected number of items in the cache. | |
Each inserted item has an associated cost. When inserting a new | |
item, if the total cost of all items in the cache will exceed \a | |
maxCost, the cache will start throwing out the older (least | |
recently used) items until there is enough room for the new item | |
to be inserted. | |
If \a caseSensitive is TRUE (the default), the cache keys are case | |
sensitive; if it is FALSE, they are case-insensitive. | |
Case-insensitive comparison considers all Unicode letters. | |
*/ | |
/*! | |
\fn Q3Cache::~Q3Cache() | |
Removes all items from the cache and destroys it. All iterators | |
that access this cache will be reset. | |
*/ | |
/*! | |
\fn Q3Cache<type>& Q3Cache::operator=( const Q3Cache<type> &c ) | |
\internal | |
Do not use. A Q3Cache cannot be copied. Calls qFatal() in debug version. | |
*/ | |
/*! | |
\fn int Q3Cache::maxCost() const | |
Returns the maximum allowed total cost of the cache. | |
\sa setMaxCost() totalCost() | |
*/ | |
/*! | |
\fn int Q3Cache::totalCost() const | |
Returns the total cost of the items in the cache. This is an | |
integer in the range 0 to maxCost(). | |
\sa setMaxCost() | |
*/ | |
/*! | |
\fn void Q3Cache::setMaxCost( int m ) | |
Sets the maximum allowed total cost of the cache to \a m. If the | |
current total cost is greater than \a m, some items are deleted | |
immediately. | |
\sa maxCost() totalCost() | |
*/ | |
/*! | |
\fn uint Q3Cache::count() const | |
Returns the number of items in the cache. | |
\sa totalCost() | |
*/ | |
/*! | |
\fn uint Q3Cache::size() const | |
Returns the size of the hash array used to implement the cache. | |
This should be a bit bigger than count() is likely to be. | |
*/ | |
/*! | |
\fn bool Q3Cache::isEmpty() const | |
Returns TRUE if the cache is empty; otherwise returns FALSE. | |
*/ | |
/*! | |
\fn bool Q3Cache::insert( const QString &k, const type *d, int c, int p ) | |
Inserts the item \a d into the cache with key \a k and associated | |
cost, \a c. Returns TRUE if it is successfully inserted; otherwise | |
returns FALSE. | |
The cache's size is limited, and if the total cost is too high, | |
Q3Cache will remove old, least recently used items until there is | |
room for this new item. | |
The parameter \a p is internal and should be left at the default | |
value (0). | |
\warning If this function returns FALSE (which could happen, e.g. | |
if the cost of this item alone exceeds maxCost()) you must delete | |
\a d yourself. Additionally, be very careful about using \a d | |
after calling this function because any other insertions into the | |
cache, from anywhere in the application or within Qt itself, could | |
cause the object to be discarded from the cache and the pointer to | |
become invalid. | |
*/ | |
/*! | |
\fn bool Q3Cache::remove( const QString &k ) | |
Removes the item associated with \a k, and returns TRUE if the | |
item was present in the cache; otherwise returns FALSE. | |
The item is deleted if auto-deletion has been enabled, i.e., if | |
you have called setAutoDelete(TRUE). | |
If there are two or more items with equal keys, the one that was | |
inserted last is removed. | |
All iterators that refer to the removed item are set to point to | |
the next item in the cache's traversal order. | |
\sa take(), clear() | |
*/ | |
/*! | |
\fn type *Q3Cache::take( const QString &k ) | |
Takes the item associated with \a k out of the cache without | |
deleting it, and returns a pointer to the item taken out, or 0 | |
if the key does not exist in the cache. | |
If there are two or more items with equal keys, the one that was | |
inserted last is taken. | |
All iterators that refer to the taken item are set to point to the | |
next item in the cache's traversal order. | |
\sa remove(), clear() | |
*/ | |
/*! | |
\fn void Q3Cache::clear() | |
Removes all items from the cache and deletes them if auto-deletion | |
has been enabled. | |
All cache iterators that operate this on cache are reset. | |
\sa remove() take() | |
*/ | |
/*! | |
\fn type *Q3Cache::find( const QString &k, bool ref ) const | |
Returns the item associated with key \a k, or 0 if the key does | |
not exist in the cache. If \a ref is TRUE (the default), the item | |
is moved to the front of the least recently used list. | |
If there are two or more items with equal keys, the one that was | |
inserted last is returned. | |
*/ | |
/*! | |
\fn type *Q3Cache::operator[]( const QString &k ) const | |
Returns the item associated with key \a k, or 0 if \a k does not | |
exist in the cache, and moves the item to the front of the least | |
recently used list. | |
If there are two or more items with equal keys, the one that was | |
inserted last is returned. | |
This is the same as find( k, TRUE ). | |
\sa find() | |
*/ | |
/*! | |
\fn void Q3Cache::statistics() const | |
A debug-only utility function. Prints out cache usage, hit/miss, | |
and distribution information using qDebug(). This function does | |
nothing in the release library. | |
*/ | |
/***************************************************************************** | |
Q3CacheIterator documentation | |
*****************************************************************************/ | |
/*! | |
\class Q3CacheIterator qcache.h | |
\brief The Q3CacheIterator class provides an iterator for Q3Cache collections. | |
\compat | |
Note that the traversal order is arbitrary; you are not guaranteed | |
any particular order. If new objects are inserted into the cache | |
while the iterator is active, the iterator may or may not see | |
them. | |
Multiple iterators are completely independent, even when they | |
operate on the same Q3Cache. Q3Cache updates all iterators that | |
refer an item when that item is removed. | |
Q3CacheIterator provides an operator++(), and an operator+=() to | |
traverse the cache. The current() and currentKey() functions are | |
used to access the current cache item and its key. The atFirst() | |
and atLast() return TRUE if the iterator points to the first or | |
last item in the cache respectively. The isEmpty() function | |
returns TRUE if the cache is empty, and count() returns the number | |
of items in the cache. | |
Note that atFirst() and atLast() refer to the iterator's arbitrary | |
ordering, not to the cache's internal least recently used list. | |
\sa Q3Cache | |
*/ | |
/*! | |
\fn Q3CacheIterator::Q3CacheIterator( const Q3Cache<type> &cache ) | |
Constructs an iterator for \a cache. The current iterator item is | |
set to point to the first item in the \a cache. | |
*/ | |
/*! | |
\fn Q3CacheIterator::Q3CacheIterator (const Q3CacheIterator<type> & ci) | |
Constructs an iterator for the same cache as \a ci. The new | |
iterator starts at the same item as ci.current(), but moves | |
independently from there on. | |
*/ | |
/*! | |
\fn Q3CacheIterator<type>& Q3CacheIterator::operator=( const Q3CacheIterator<type> &ci ) | |
Makes this an iterator for the same cache as \a ci. The new | |
iterator starts at the same item as ci.current(), but moves | |
independently thereafter. | |
*/ | |
/*! | |
\fn uint Q3CacheIterator::count() const | |
Returns the number of items in the cache on which this iterator | |
operates. | |
\sa isEmpty() | |
*/ | |
/*! | |
\fn bool Q3CacheIterator::isEmpty() const | |
Returns TRUE if the cache is empty, i.e. count() == 0; otherwise | |
it returns FALSE. | |
\sa count() | |
*/ | |
/*! | |
\fn bool Q3CacheIterator::atFirst() const | |
Returns TRUE if the iterator points to the first item in the | |
cache; otherwise returns FALSE. Note that this refers to the | |
iterator's arbitrary ordering, not to the cache's internal least | |
recently used list. | |
\sa toFirst(), atLast() | |
*/ | |
/*! | |
\fn bool Q3CacheIterator::atLast() const | |
Returns TRUE if the iterator points to the last item in the cache; | |
otherwise returns FALSE. Note that this refers to the iterator's | |
arbitrary ordering, not to the cache's internal least recently | |
used list. | |
\sa toLast(), atFirst() | |
*/ | |
/*! | |
\fn type *Q3CacheIterator::toFirst() | |
Sets the iterator to point to the first item in the cache and | |
returns a pointer to the item. | |
Sets the iterator to 0 and returns 0 if the cache is empty. | |
\sa toLast() isEmpty() | |
*/ | |
/*! | |
\fn type *Q3CacheIterator::toLast() | |
Sets the iterator to point to the last item in the cache and | |
returns a pointer to the item. | |
Sets the iterator to 0 and returns 0 if the cache is empty. | |
\sa toFirst() isEmpty() | |
*/ | |
/*! | |
\fn Q3CacheIterator::operator type *() const | |
Cast operator. Returns a pointer to the current iterator item. | |
Same as current(). | |
*/ | |
/*! | |
\fn type *Q3CacheIterator::current() const | |
Returns a pointer to the current iterator item. | |
*/ | |
/*! | |
\fn QString Q3CacheIterator::currentKey() const | |
Returns the key for the current iterator item. | |
*/ | |
/*! | |
\fn type *Q3CacheIterator::operator()() | |
Makes the succeeding item current and returns the original current | |
item. | |
If the current iterator item was the last item in the cache or if | |
it was 0, 0 is returned. | |
*/ | |
/*! | |
\fn type *Q3CacheIterator::operator+=( uint jump ) | |
Returns the item \a jump positions after the current item, or 0 if | |
it is beyond the last item. Makes this the current item. | |
*/ | |
/*! | |
\fn type *Q3CacheIterator::operator-=( uint jump ) | |
Returns the item \a jump positions before the current item, or 0 | |
if it is before the first item. Makes this the current item. | |
*/ | |
/*! | |
\fn type *Q3CacheIterator::operator++() | |
Prefix++ makes the iterator point to the item just after current() | |
and makes that the new current item for the iterator. If current() | |
was the last item, operator++() returns 0. | |
*/ | |
/*! | |
\fn type *Q3CacheIterator::operator--() | |
Prefix-- makes the iterator point to the item just before | |
current() and makes that the new current item for the iterator. If | |
current() was the first item, operator--() returns 0. | |
*/ | |