You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
477 lines
15 KiB
477 lines
15 KiB
/****************************************************************************
|
|
**
|
|
** QAsciiCache and QAsciiCacheIterator class documentation
|
|
**
|
|
** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved.
|
|
**
|
|
** This file is part of the Qt GUI Toolkit.
|
|
**
|
|
** This file may be used under the terms of the GNU General
|
|
** Public License versions 2.0 or 3.0 as published by the Free
|
|
** Software Foundation and appearing in the files LICENSE.GPL2
|
|
** and LICENSE.GPL3 included in the packaging of this file.
|
|
** Alternatively you may (at your option) use any later version
|
|
** of the GNU General Public License if such license has been
|
|
** publicly approved by Trolltech ASA (or its successors, if any)
|
|
** and the KDE Free Qt Foundation.
|
|
**
|
|
** Please review the following information to ensure GNU General
|
|
** Public Licensing requirements will be met:
|
|
** http://trolltech.com/products/qt/licenses/licensing/opensource/.
|
|
** If you are unsure which license is appropriate for your use, please
|
|
** review the following information:
|
|
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
|
|
** or contact the sales department at sales@trolltech.com.
|
|
**
|
|
** This file may be used under the terms of the Q Public License as
|
|
** defined by Trolltech ASA and appearing in the file LICENSE.QPL
|
|
** included in the packaging of this file. Licensees holding valid Qt
|
|
** Commercial licenses may use this file in accordance with the Qt
|
|
** Commercial License Agreement provided with the Software.
|
|
**
|
|
** This file is provided "AS IS" with NO WARRANTY OF ANY KIND,
|
|
** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR
|
|
** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted
|
|
** herein.
|
|
**
|
|
**********************************************************************/
|
|
|
|
|
|
/*****************************************************************************
|
|
QAsciiCache documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class QAsciiCache qasciicache.h
|
|
|
|
\brief The QAsciiCache class is a template class that provides a cache based on char* keys.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
|
|
QAsciiCache is implemented as a template class. Define a template
|
|
instance QAsciiCache\<X\> to create a cache that operates on
|
|
pointers to X (X*).
|
|
|
|
A cache is a least recently used (LRU) list of cache items. The
|
|
cache items are accessed via \c char* keys. For Unicode keys use
|
|
the QCache template instead, which uses \c QString keys. A QCache
|
|
has the same performace as a QAsciiCache.
|
|
|
|
Each cache item has a cost. The sum of item costs, totalCost(),
|
|
will not exceed 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.
|
|
|
|
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 \link QPtrCollection::setAutoDelete()
|
|
setAutoDelete(TRUE)\endlink tells the cache to delete items that
|
|
are removed. The default is to not delete items when then 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 QPtrCollection::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
|
|
QPtrCollection::deleteItem() is called. Its default implementation
|
|
in QAsciiCache is to delete the item if \link
|
|
QPtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
|
|
|
|
There is a QAsciiCacheIterator which may be used to traverse the
|
|
items in the cache in arbitrary order.
|
|
|
|
\sa QAsciiCacheIterator, QCache, QIntCache
|
|
*/
|
|
|
|
/*!
|
|
\fn QAsciiCache::QAsciiCache( const QAsciiCache<type> &c )
|
|
|
|
\internal
|
|
|
|
Do not use. A QAsciiCache cannot be copied. Calls qFatal() in debug version.
|
|
*/
|
|
|
|
|
|
/*!
|
|
\fn QAsciiCache::QAsciiCache( int maxCost, int size, bool caseSensitive, bool copyKeys )
|
|
|
|
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 prime 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 only affects the 26 letters in
|
|
US-ASCII. If \a copyKeys is TRUE (the default), QAsciiCache makes
|
|
a copy of the cache keys, otherwise it copies just the const char
|
|
* pointer - slightly faster if you can guarantee that the keys
|
|
will never change, but very risky.
|
|
*/
|
|
|
|
/*!
|
|
\fn QAsciiCache::~QAsciiCache()
|
|
|
|
Removes all items from the cache and destroys it.
|
|
All iterators that access this cache will be reset.
|
|
*/
|
|
|
|
/*!
|
|
\fn QAsciiCache<type>& QAsciiCache::operator=( const QAsciiCache<type> &c )
|
|
|
|
\internal
|
|
|
|
Do not use. A QAsciiCache cannot be copied. Calls qFatal() in debug version.
|
|
*/
|
|
|
|
/*!
|
|
\fn int QAsciiCache::maxCost() const
|
|
|
|
Returns the maximum allowed total cost of the cache.
|
|
|
|
\sa setMaxCost() totalCost()
|
|
*/
|
|
|
|
/*!
|
|
\fn int QAsciiCache::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 QAsciiCache::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 removed
|
|
immediately.
|
|
|
|
\sa maxCost() totalCost()
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QAsciiCache::count() const
|
|
|
|
Returns the number of items in the cache.
|
|
|
|
\sa totalCost() size()
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QAsciiCache::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 QAsciiCache::isEmpty() const
|
|
|
|
Returns TRUE if the cache is empty; otherwise returns FALSE.
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QAsciiCache::insert( const char *k, const type *d, int c, int p )
|
|
|
|
Inserts the item \a d into the cache using key \a k, and with an
|
|
associated cost of \a c. Returns TRUE if the item is successfully
|
|
inserted. Returns FALSE if the item is not inserted, for example,
|
|
if the cost of the item exceeds maxCost().
|
|
|
|
The cache's size is limited, and if the total cost is too high,
|
|
QAsciiCache will remove old, least recently used items until there
|
|
is room for this new item.
|
|
|
|
Items with duplicate keys can be inserted.
|
|
|
|
The parameter \a p is internal and should be left at the default
|
|
value (0).
|
|
|
|
\warning If this function returns FALSE, 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 QAsciiCache::remove( const char *k )
|
|
|
|
Removes the item with key \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 \link QPtrCollection::setAutoDelete()
|
|
setAutoDelete(TRUE)\endlink.
|
|
|
|
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 *QAsciiCache::take( const char *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 QAsciiCache::clear()
|
|
|
|
Removes all items from the cache, and deletes them if \link
|
|
QPtrCollection::setAutoDelete() auto-deletion\endlink has been
|
|
enabled.
|
|
|
|
All cache iterators that operate on this cache are reset.
|
|
|
|
\sa remove() take()
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QAsciiCache::find( const char *k, bool ref ) const
|
|
|
|
Returns the item 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 *QAsciiCache::operator[]( const char *k ) const
|
|
|
|
Returns the item 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 QAsciiCache::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.
|
|
*/
|
|
|
|
/*****************************************************************************
|
|
QAsciiCacheIterator documentation
|
|
*****************************************************************************/
|
|
|
|
/*!
|
|
\class QAsciiCacheIterator qasciicache.h
|
|
\brief The QAsciiCacheIterator class provides an iterator for QAsciiCache collections.
|
|
|
|
\ingroup collection
|
|
\ingroup tools
|
|
|
|
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 QAsciiCache. QAsciiCache updates all iterators
|
|
that refer an item when that item is removed.
|
|
|
|
QAsciiCacheIterator provides an operator++() and an operator+=()
|
|
to traverse the cache; current() and currentKey() to access the
|
|
current cache item and its key. It also provides atFirst() and
|
|
atLast(), which 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 QAsciiCache
|
|
*/
|
|
|
|
/*!
|
|
\fn QAsciiCacheIterator::QAsciiCacheIterator( const QAsciiCache<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 QAsciiCacheIterator::QAsciiCacheIterator (const QAsciiCacheIterator<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 QAsciiCacheIterator<type>& QAsciiCacheIterator::operator=( const QAsciiCacheIterator<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 QAsciiCacheIterator::count() const
|
|
|
|
Returns the number of items in the cache over which this iterator
|
|
operates.
|
|
|
|
\sa isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QAsciiCacheIterator::isEmpty() const
|
|
|
|
Returns TRUE if the cache is empty, i.e. count() == 0; otherwise
|
|
returns FALSE.
|
|
|
|
\sa count()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QAsciiCacheIterator::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 QAsciiCacheIterator::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 *QAsciiCacheIterator::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 *QAsciiCacheIterator::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 toLast() isEmpty()
|
|
*/
|
|
|
|
/*!
|
|
\fn QAsciiCacheIterator::operator type *() const
|
|
|
|
Cast operator. Returns a pointer to the current iterator item.
|
|
Same as current().
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QAsciiCacheIterator::current() const
|
|
|
|
Returns a pointer to the current iterator item.
|
|
*/
|
|
|
|
/*!
|
|
\fn const char *QAsciiCacheIterator::currentKey() const
|
|
|
|
Returns the key for the current iterator item.
|
|
*/
|
|
|
|
/*!
|
|
\fn type *QAsciiCacheIterator::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 *QAsciiCacheIterator::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 *QAsciiCacheIterator::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 *QAsciiCacheIterator::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 *QAsciiCacheIterator::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.
|
|
*/
|
|
|