Mac-4.7.4/src/qt3support/tools/q3cache.qdoc - platform/external/qt - Git at Google

 /****************************************************************************
 **
 ** 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.
 */
	/****************************************************************************
	**
	** 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.
	*/