Add Qt3 development HEAD version

1 files changed, 476 insertions, 0 deletions

diff --git a/doc/qasciicache.doc b/doc/qasciicache.doc
new file mode 100644
index 0000000..be6cada
--- /dev/null
+++ b/doc/qasciicache.doc
@@ -0,0 +1,476 @@
+/****************************************************************************
+**
+** 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.
+*/
+