diff options
Diffstat (limited to 'doc/src/q3cache.qdoc')
| -rw-r--r-- | doc/src/q3cache.qdoc | 461 |
1 files changed, 0 insertions, 461 deletions
diff --git a/doc/src/q3cache.qdoc b/doc/src/q3cache.qdoc deleted file mode 100644 index 38ed7e5..0000000 --- a/doc/src/q3cache.qdoc +++ /dev/null @@ -1,461 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). -** Contact: Nokia Corporation (qt-info@nokia.com) -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:LGPL$ -** No Commercial Usage -** This file contains pre-release code and may not be distributed. -** You may use this file in accordance with the terms and conditions -** contained in the Technology Preview License Agreement accompanying -** this package. -** -** GNU Lesser General Public License Usage -** Alternatively, this file may be used under the terms of the GNU Lesser -** General Public License version 2.1 as published by the Free Software -** Foundation and appearing in the file LICENSE.LGPL included in the -** packaging of this file. Please review the following information to -** ensure the GNU Lesser General Public License version 2.1 requirements -** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. -** -** In addition, as a special exception, Nokia gives you certain -** additional rights. These rights are described in the Nokia Qt LGPL -** Exception version 1.1, included in the file LGPL_EXCEPTION.txt in this -** package. -** -** If you have questions regarding the use of this file, please contact -** Nokia at qt-info@nokia.com. -** -** -** -** -** -** -** -** -** $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. -*/ - |