summaryrefslogtreecommitdiffstats
path: root/src/qt3support/tools
diff options
context:
space:
mode:
Diffstat (limited to 'src/qt3support/tools')
-rw-r--r--src/qt3support/tools/q3asciicache.qdoc465
-rw-r--r--src/qt3support/tools/q3asciidict.qdoc416
-rw-r--r--src/qt3support/tools/q3cache.qdoc461
-rw-r--r--src/qt3support/tools/q3dict.qdoc446
-rw-r--r--src/qt3support/tools/q3intcache.qdoc446
-rw-r--r--src/qt3support/tools/q3intdict.qdoc390
-rw-r--r--src/qt3support/tools/q3memarray.qdoc523
-rw-r--r--src/qt3support/tools/q3ptrdict.qdoc388
-rw-r--r--src/qt3support/tools/q3ptrlist.qdoc1157
-rw-r--r--src/qt3support/tools/q3ptrqueue.qdoc230
-rw-r--r--src/qt3support/tools/q3ptrstack.qdoc217
-rw-r--r--src/qt3support/tools/q3ptrvector.qdoc427
-rw-r--r--src/qt3support/tools/q3valuelist.qdoc569
-rw-r--r--src/qt3support/tools/q3valuestack.qdoc149
-rw-r--r--src/qt3support/tools/q3valuevector.qdoc274
15 files changed, 6558 insertions, 0 deletions
diff --git a/src/qt3support/tools/q3asciicache.qdoc b/src/qt3support/tools/q3asciicache.qdoc
new file mode 100644
index 0000000..b86113f
--- /dev/null
+++ b/src/qt3support/tools/q3asciicache.qdoc
@@ -0,0 +1,465 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3AsciiCache
+ \brief The Q3AsciiCache class is a template class that provides a cache based on char* keys.
+ \compat
+
+ Q3AsciiCache is implemented as a template class. Define a template
+ instance Q3AsciiCache\<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 Q3Cache template instead, which uses QString keys. A Q3Cache
+ has the same performace as a Q3AsciiCache.
+
+ 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 Q3PtrCollection::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 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. Its default implementation
+ in Q3AsciiCache is to delete the item if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+ There is a Q3AsciiCacheIterator which may be used to traverse the
+ items in the cache in arbitrary order.
+
+ \sa Q3AsciiCacheIterator, Q3Cache, Q3IntCache
+*/
+
+/*!
+ \fn Q3AsciiCache::Q3AsciiCache( const Q3AsciiCache<type> &c )
+
+ \internal
+
+ Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version.
+*/
+
+
+/*!
+ \fn Q3AsciiCache::Q3AsciiCache( 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), Q3AsciiCache 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 Q3AsciiCache::~Q3AsciiCache()
+
+ Removes all items from the cache and destroys it.
+ All iterators that access this cache will be reset.
+*/
+
+/*!
+ \fn Q3AsciiCache<type>& Q3AsciiCache::operator=( const Q3AsciiCache<type> &c )
+
+ \internal
+
+ Do not use. A Q3AsciiCache cannot be copied. Calls qFatal() in debug version.
+*/
+
+/*!
+ \fn int Q3AsciiCache::maxCost() const
+
+ Returns the maximum allowed total cost of the cache.
+
+ \sa setMaxCost() totalCost()
+*/
+
+/*!
+ \fn int Q3AsciiCache::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 Q3AsciiCache::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 Q3AsciiCache::count() const
+
+ Returns the number of items in the cache.
+
+ \sa totalCost() size()
+*/
+
+/*!
+ \fn uint Q3AsciiCache::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 Q3AsciiCache::isEmpty() const
+
+ Returns TRUE if the cache is empty; otherwise returns FALSE.
+*/
+
+/*!
+ \fn bool Q3AsciiCache::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,
+ Q3AsciiCache 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 Q3AsciiCache::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 Q3PtrCollection::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 *Q3AsciiCache::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 Q3AsciiCache::clear()
+
+ Removes all items from the cache, and deletes them if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink has been
+ enabled.
+
+ All cache iterators that operate on this cache are reset.
+
+ \sa remove() take()
+*/
+
+/*!
+ \fn type *Q3AsciiCache::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 *Q3AsciiCache::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 Q3AsciiCache::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.
+*/
+
+/*!
+ \class Q3AsciiCacheIterator
+ \brief The Q3AsciiCacheIterator class provides an iterator for Q3AsciiCache 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 Q3AsciiCache. Q3AsciiCache updates all iterators
+ that refer an item when that item is removed.
+
+ Q3AsciiCacheIterator 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 Q3AsciiCache
+*/
+
+/*!
+ \fn Q3AsciiCacheIterator::Q3AsciiCacheIterator( const Q3AsciiCache<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 Q3AsciiCacheIterator::Q3AsciiCacheIterator (const Q3AsciiCacheIterator<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 Q3AsciiCacheIterator<type>& Q3AsciiCacheIterator::operator=( const Q3AsciiCacheIterator<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 Q3AsciiCacheIterator::count() const
+
+ Returns the number of items in the cache over which this iterator
+ operates.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool Q3AsciiCacheIterator::isEmpty() const
+
+ Returns TRUE if the cache is empty, i.e. count() == 0; otherwise
+ returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn bool Q3AsciiCacheIterator::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 Q3AsciiCacheIterator::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 *Q3AsciiCacheIterator::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 *Q3AsciiCacheIterator::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 Q3AsciiCacheIterator::operator type *() const
+
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *Q3AsciiCacheIterator::current() const
+
+ Returns a pointer to the current iterator item.
+*/
+
+/*!
+ \fn const char *Q3AsciiCacheIterator::currentKey() const
+
+ Returns the key for the current iterator item.
+*/
+
+/*!
+ \fn type *Q3AsciiCacheIterator::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 *Q3AsciiCacheIterator::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 *Q3AsciiCacheIterator::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 *Q3AsciiCacheIterator::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 *Q3AsciiCacheIterator::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.
+*/
+
diff --git a/src/qt3support/tools/q3asciidict.qdoc b/src/qt3support/tools/q3asciidict.qdoc
new file mode 100644
index 0000000..1262a37
--- /dev/null
+++ b/src/qt3support/tools/q3asciidict.qdoc
@@ -0,0 +1,416 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3AsciiDict
+ \brief The Q3AsciiDict class is a template class that provides a dictionary based on char* keys.
+ \compat
+
+ Q3AsciiDict is implemented as a template class. Define a template
+ instance Q3AsciiDict\<X\> to create a dictionary that operates on
+ pointers to X (X*).
+
+ A dictionary is a collection of key-value pairs. The key is a
+ char* used for insertion, removal and lookup. The value is a
+ pointer. Dictionaries provide very fast insertion and lookup.
+
+ Q3AsciiDict cannot handle Unicode keys; use the Q3Dict template
+ instead, which uses QString keys. A Q3Dict has the same
+ performace as a Q3AsciiDict.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 0
+ In this example we use a dictionary to keep track of the line
+ edits we're using. We insert each line edit into the dictionary
+ with a unique name and then access the line edits via the
+ dictionary. See Q3PtrDict, Q3IntDict and Q3Dict.
+
+ See Q3Dict for full details, including the choice of dictionary
+ size, and how deletions are handled.
+
+ \sa Q3AsciiDictIterator, Q3Dict, Q3IntDict, Q3PtrDict
+*/
+
+
+/*!
+ \fn Q3AsciiDict::Q3AsciiDict( int size, bool caseSensitive, bool copyKeys )
+
+ Constructs a dictionary optimized for less than \a size entries.
+
+ We recommend setting \a size to a suitably large prime number (a
+ bit larger than the expected number of entries). This makes the
+ hash distribution better and will improve lookup performance.
+
+ When \a caseSensitive is TRUE (the default) Q3AsciiDict treats
+ "abc" and "Abc" as different keys; when it is FALSE "abc" and
+ "Abc" are the same. Case-insensitive comparison only considers the
+ 26 letters in US-ASCII.
+
+ If \a copyKeys is TRUE (the default), the dictionary copies keys
+ using strcpy(); if it is FALSE, the dictionary just copies the
+ pointers.
+*/
+
+/*!
+ \fn Q3AsciiDict::Q3AsciiDict( const Q3AsciiDict<type> &dict )
+
+ Constructs a copy of \a dict.
+
+ Each item in \a dict is inserted into this dictionary. Only the
+ pointers are copied (shallow copy).
+*/
+
+/*!
+ \fn Q3AsciiDict::~Q3AsciiDict()
+
+ Removes all items from the dictionary and destroys it.
+
+ The items are deleted if auto-delete is enabled.
+
+ All iterators that access this dictionary will be reset.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn Q3AsciiDict<type> &Q3AsciiDict::operator=(const Q3AsciiDict<type> &dict)
+
+ Assigns \a dict to this dictionary and returns a reference to this
+ dictionary.
+
+ This dictionary is first cleared and then each item in \a dict is
+ inserted into this dictionary. Only the pointers are copied
+ (shallow copy) unless newItem() has been reimplemented().
+*/
+
+/*!
+ \fn uint Q3AsciiDict::count() const
+
+ Returns the number of items in the dictionary.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn uint Q3AsciiDict::size() const
+
+ Returns the size of the internal hash array (as specified in the
+ constructor).
+
+ \sa count()
+*/
+
+/*!
+ \fn void Q3AsciiDict::resize( uint newsize )
+
+ Changes the size of the hashtable to \a newsize. The contents of
+ the dictionary are preserved but all iterators on the dictionary
+ become invalid.
+*/
+
+/*!
+ \fn bool Q3AsciiDict::isEmpty() const
+
+ Returns TRUE if the dictionary is empty, i.e. count() == 0;
+ otherwise it returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn void Q3AsciiDict::insert( const char *key, const type *item )
+
+ Inserts the \a key with the \a item into the dictionary.
+
+ Multiple items can have the same key, in which case only the last
+ item will be accessible using \l operator[]().
+
+ \a item may not be 0.
+
+ \sa replace()
+*/
+
+/*!
+ \fn void Q3AsciiDict::replace( const char *key, const type *item )
+
+ Replaces an item that has a key equal to \a key with \a item.
+
+ If the item does not already exist, it will be inserted.
+
+ \a item may not be 0.
+
+ Equivalent to:
+ \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 1
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be replaced.
+
+ \sa insert()
+*/
+
+/*!
+ \fn bool Q3AsciiDict::remove( const char *key )
+
+ Removes the item associated with \a key from the dictionary.
+ Returns TRUE if successful, i.e. if the key existed in the
+ dictionary; otherwise returns FALSE.
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be removed.
+
+ The removed item is deleted if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+ All dictionary iterators that refer to the removed item will be
+ set to point to the next item in the dictionary traversal order.
+
+ \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn type *Q3AsciiDict::take( const char *key )
+
+ Takes the item associated with \a key out of the dictionary
+ without deleting it (even if \link Q3PtrCollection::setAutoDelete()
+ auto-deletion\endlink is enabled).
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be taken.
+
+ Returns a pointer to the item taken out, or 0 if the key does not
+ exist in the dictionary.
+
+ All dictionary iterators that refer to the taken item will be set
+ to point to the next item in the dictionary traversal order.
+
+ \sa remove(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn void Q3AsciiDict::clear()
+
+ Removes all items from the dictionary.
+
+ The removed items are deleted if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+ All dictionary iterators that operate on dictionary are reset.
+
+ \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+ \fn type *Q3AsciiDict::find( const char *key ) const
+
+ Returns the item associated with \a key, or 0 if the key does not
+ exist in the dictionary.
+
+ This function uses an internal hashing algorithm to optimize
+ lookup.
+
+ If there are two or more items with equal keys, then the item that
+ was most recently inserted will be found.
+
+ Equivalent to the [] operator.
+
+ \sa operator[]()
+*/
+
+/*!
+ \fn type *Q3AsciiDict::operator[]( const char *key ) const
+
+ Returns the item associated with \a key, or 0 if the key does
+ not exist in the dictionary.
+
+ This function uses an internal hashing algorithm to optimize
+ lookup.
+
+ If there are two or more items with equal keys, then the item that
+ was most recently inserted will be found.
+
+ Equivalent to the find() function.
+
+ \sa find()
+*/
+
+/*!
+ \fn void Q3AsciiDict::statistics() const
+
+ Debugging-only function that prints out the dictionary
+ distribution using qDebug().
+*/
+
+/*!
+ \fn QDataStream& Q3AsciiDict::read( QDataStream &s,
+ Q3PtrCollection::Item &item )
+
+ Reads a dictionary item from the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation sets \a item to 0.
+
+ \sa write()
+*/
+
+/*!
+ \fn QDataStream& Q3AsciiDict::write(QDataStream &s, Q3PtrCollection::Item item) const
+
+ Writes a dictionary \a item to the stream \a s and returns a
+ reference to the stream.
+
+ \sa read()
+*/
+
+/*!
+ \class Q3AsciiDictIterator
+ \brief The Q3AsciiDictIterator class provides an iterator for Q3AsciiDict collections.
+ \compat
+
+ Q3AsciiDictIterator is implemented as a template class. Define a
+ template instance Q3AsciiDictIterator\<X\> to create a dictionary
+ iterator that operates on Q3AsciiDict\<X\> (dictionary of X*).
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 2
+ In the example we insert some line edits into a dictionary, then
+ iterate over the dictionary printing the strings associated with
+ those line edits.
+
+ Note that the traversal order is arbitrary; you are not guaranteed
+ any particular order.
+
+ Multiple iterators may independently traverse the same dictionary.
+ A Q3AsciiDict knows about all the iterators that are operating on
+ the dictionary. When an item is removed from the dictionary,
+ Q3AsciiDict updates all the iterators that are referring to the
+ removed item to point to the next item in the (arbitrary)
+ traversal order.
+
+ \sa Q3AsciiDict
+*/
+
+/*!
+ \fn Q3AsciiDictIterator::Q3AsciiDictIterator( const Q3AsciiDict<type> &dict )
+
+ Constructs an iterator for \a dict. The current iterator item is
+ set to point on the first item in the \a dict.
+*/
+
+/*!
+ \fn Q3AsciiDictIterator::~Q3AsciiDictIterator()
+
+ Destroys the iterator.
+*/
+
+/*!
+ \fn uint Q3AsciiDictIterator::count() const
+
+ Returns the number of items in the dictionary this iterator
+ operates over.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool Q3AsciiDictIterator::isEmpty() const
+
+ Returns TRUE if the dictionary is empty, i.e. count() == 0,
+ otherwise returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn type *Q3AsciiDictIterator::toFirst()
+
+ Sets the current iterator item to point to the first item in the
+ dictionary and returns a pointer to the item. If the dictionary is
+ empty it sets the current item to 0 and returns 0.
+*/
+
+/*!
+ \fn Q3AsciiDictIterator::operator type *() const
+
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *Q3AsciiDictIterator::current() const
+
+ Returns a pointer to the current iterator item.
+*/
+
+/*!
+ \fn const char *Q3AsciiDictIterator::currentKey() const
+
+ Returns a pointer to the key for the current iterator item.
+*/
+
+/*!
+ \fn type *Q3AsciiDictIterator::operator()()
+
+ Makes the succeeding item current and returns the original current
+ item.
+
+ If the current iterator item was the last item in the dictionary
+ or if it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3AsciiDictIterator::operator++()
+
+ Prefix ++ makes the succeeding item current and returns the new
+ current item.
+
+ If the current iterator item was the last item in the dictionary
+ or if it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3AsciiDictIterator::operator+=( uint jump )
+
+ Sets the current item to the item \a jump positions after the
+ current item, and returns a pointer to that item.
+
+ If that item is beyond the last item or if the dictionary is
+ empty, it sets the current item to 0 and returns 0.
+*/
diff --git a/src/qt3support/tools/q3cache.qdoc b/src/qt3support/tools/q3cache.qdoc
new file mode 100644
index 0000000..20b777f
--- /dev/null
+++ b/src/qt3support/tools/q3cache.qdoc
@@ -0,0 +1,461 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $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.
+*/
+
diff --git a/src/qt3support/tools/q3dict.qdoc b/src/qt3support/tools/q3dict.qdoc
new file mode 100644
index 0000000..2234c2d
--- /dev/null
+++ b/src/qt3support/tools/q3dict.qdoc
@@ -0,0 +1,446 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3Dict
+ \brief The Q3Dict class is a template class that provides a
+ dictionary based on QString keys.
+ \compat
+
+ Q3Dict is implemented as a template class. Define a template
+ instance Q3Dict\<X\> to create a dictionary that operates on
+ pointers to X (X *).
+
+ A dictionary is a collection of key-value pairs. The key is a
+ QString used for insertion, removal and lookup. The value is a
+ pointer. Dictionaries provide very fast insertion and lookup.
+
+ If you want to use non-Unicode, plain 8-bit \c char* keys, use the
+ Q3AsciiDict template. A Q3Dict has the same performance as a
+ Q3AsciiDict. If you want to have a dictionary that maps QStrings to
+ QStrings use QMap.
+
+ The size() of the dictionary is very important. In order to get
+ good performance, you should use a suitably large prime number.
+ Suitable means equal to or larger than the maximum expected number
+ of dictionary items. Size is set in the constructor but may be
+ changed with resize().
+
+ Items are inserted with insert(); 0 pointers cannot be inserted.
+ Items are removed with remove(). All the items in a dictionary can
+ be removed with clear(). The number of items in the dictionary is
+ returned by count(). If the dictionary contains no items isEmpty()
+ returns TRUE. You can change an item's value with replace(). Items
+ are looked up with operator[](), or with find() which return a
+ pointer to the value or 0 if the given key does not exist. You can
+ take an item out of the dictionary with take().
+
+ Calling setAutoDelete(TRUE) for a dictionary tells it to delete
+ items that are removed. The default behavior is not to delete
+ items when they are removed.
+
+ When an item is inserted, the key is converted (hashed) to an
+ integer index into an internal hash array. This makes lookup very
+ fast.
+
+ Items with equal keys are allowed. When inserting two items with
+ the same key, only the last inserted item will be accessible (last
+ in, first out) until it is removed.
+
+ The Q3DictIterator class can traverse the dictionary, but only in
+ an arbitrary order. Multiple iterators may independently traverse
+ the same dictionary.
+
+ When inserting an item into a dictionary, only the pointer is
+ copied, not the item itself, i.e. a shallow copy is made. It is
+ possible to make the dictionary copy all of the item's data (a
+ deep copy) when an item is inserted. insert() calls the virtual
+ function Q3PtrCollection::newItem() for the item to be inserted.
+ Inherit a dictionary and reimplement newItem() if you want deep
+ copies.
+
+ When removing a dictionary item, the virtual function
+ Q3PtrCollection::deleteItem() is called. Q3Dict's default
+ implementation is to delete the item if auto-deletion is enabled.
+
+ \sa Q3DictIterator, Q3AsciiDict, Q3IntDict, Q3PtrDict
+*/
+
+
+/*!
+ \fn Q3Dict::Q3Dict( int size, bool caseSensitive )
+
+ Constructs a dictionary optimized for less than \a size entries.
+
+ We recommend setting \a size to a suitably large prime number
+ (e.g. a prime that's slightly larger than the expected number of
+ entries). This makes the hash distribution better which will lead
+ to faster lookup.
+
+ If \a caseSensitive is TRUE (the default), keys which differ only
+ by case are considered different.
+*/
+
+/*!
+ \fn Q3Dict::Q3Dict( const Q3Dict<type> &dict )
+
+ Constructs a copy of \a dict.
+
+ Each item in \a dict is inserted into this dictionary. Only the
+ pointers are copied (shallow copy).
+*/
+
+/*!
+ \fn Q3Dict::~Q3Dict()
+
+ Removes all items from the dictionary and destroys it. If
+ setAutoDelete() is TRUE, each value is deleted. All iterators that
+ access this dictionary will be reset.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn Q3Dict<type> &Q3Dict::operator=(const Q3Dict<type> &dict)
+
+ Assigns \a dict to this dictionary and returns a reference to this
+ dictionary.
+
+ This dictionary is first cleared, then each item in \a dict is
+ inserted into this dictionary. Only the pointers are copied
+ (shallow copy), unless newItem() has been reimplemented.
+*/
+
+/*!
+ \fn uint Q3Dict::count() const
+
+ Returns the number of items in the dictionary.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn uint Q3Dict::size() const
+
+ Returns the size of the internal hash array (as specified in the
+ constructor).
+
+ \sa count()
+*/
+
+/*!
+ \fn void Q3Dict::resize( uint newsize )
+
+ Changes the size of the hash table to \a newsize. The contents of
+ the dictionary are preserved, but all iterators on the dictionary
+ become invalid.
+*/
+
+/*!
+ \fn bool Q3Dict::isEmpty() const
+
+ Returns TRUE if the dictionary is empty, i.e. count() == 0;
+ otherwise returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn void Q3Dict::insert( const QString &key, const type *item )
+
+ Inserts the key \a key with value \a item into the dictionary.
+
+ Multiple items can have the same key, in which case only the last
+ item will be accessible using \l operator[]().
+
+ \a item may not be 0.
+
+ \sa replace()
+*/
+
+/*!
+ \fn void Q3Dict::replace( const QString &key, const type *item )
+
+ Replaces the value of the key, \a key with \a item.
+
+ If the item does not already exist, it will be inserted.
+
+ \a item may not be 0.
+
+ Equivalent to:
+ \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 0
+
+ If there are two or more items with equal keys, then the last item
+ that was inserted will be replaced.
+
+ \sa insert()
+*/
+
+/*!
+ \fn bool Q3Dict::remove( const QString &key )
+
+ Removes the item with \a key from the dictionary. Returns TRUE if
+ successful, i.e. if the item is in the dictionary; otherwise
+ returns FALSE.
+
+ If there are two or more items with equal keys, then the last item
+ that was inserted will be removed.
+
+ The removed item is deleted if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+ All dictionary iterators that refer to the removed item will be
+ set to point to the next item in the dictionary's traversal order.
+
+ \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn type *Q3Dict::take( const QString &key )
+
+ Takes the item with \a key out of the dictionary without deleting
+ it (even if \link Q3PtrCollection::setAutoDelete()
+ auto-deletion\endlink is enabled).
+
+ If there are two or more items with equal keys, then the last item
+ that was inserted will be taken.
+
+ Returns a pointer to the item taken out, or 0 if the key does not
+ exist in the dictionary.
+
+ All dictionary iterators that refer to the taken item will be set
+ to point to the next item in the dictionary traversal order.
+
+ \sa remove(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn void Q3Dict::clear()
+
+ Removes all items from the dictionary.
+
+ The removed items are deleted if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+ All dictionary iterators that operate on the dictionary are reset.
+
+ \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+ \fn type *Q3Dict::find( const QString &key ) const
+
+ Returns the item with key \a key, or 0 if the key does not exist
+ in the dictionary.
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be found.
+
+ Equivalent to the [] operator.
+
+ \sa operator[]()
+*/
+
+/*!
+ \fn type *Q3Dict::operator[]( const QString &key ) const
+
+ Returns the item with key \a key, or 0 if the key does not
+ exist in the dictionary.
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be found.
+
+ Equivalent to the find() function.
+
+ \sa find()
+*/
+
+/*!
+ \fn void Q3Dict::statistics() const
+
+ Debugging-only function that prints out the dictionary
+ distribution using qDebug().
+*/
+
+/*!
+ \fn QDataStream& Q3Dict::read( QDataStream &s, Q3PtrCollection::Item &item )
+
+ Reads a dictionary item from the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation sets \a item to 0.
+
+ \sa write()
+*/
+
+/*!
+ \fn QDataStream& Q3Dict::write( QDataStream &s, Q3PtrCollection::Item item ) const
+
+ Writes a dictionary \a item to the stream \a s and returns a
+ reference to the stream.
+
+ \sa read()
+*/
+
+/*!
+ \class Q3DictIterator
+ \brief The Q3DictIterator class provides an iterator for Q3Dict collections.
+ \compat
+
+ Q3DictIterator is implemented as a template class. Define a
+ template instance Q3DictIterator\<X\> to create a dictionary
+ iterator that operates on Q3Dict\<X\> (dictionary of X*).
+
+ The traversal order is arbitrary; when we speak of the "first",
+ "last" and "next" item we are talking in terms of this arbitrary
+ order.
+
+ Multiple iterators may independently traverse the same dictionary.
+ A Q3Dict knows about all the iterators that are operating on the
+ dictionary. When an item is removed from the dictionary, Q3Dict
+ updates all iterators that are referring to the removed item to
+ point to the next item in the (arbitrary) traversal order.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3dict.qdoc 1
+ In the example we insert some pointers to line edits into a
+ dictionary, then iterate over the dictionary printing the strings
+ associated with the line edits.
+
+ \sa Q3Dict
+*/
+
+/*!
+ \fn Q3DictIterator::Q3DictIterator( const Q3Dict<type> &dict )
+
+ Constructs an iterator for \a dict. The current iterator item is
+ set to point to the first item in the dictionary, \a dict. First
+ in this context means first in the arbitrary traversal order.
+*/
+
+/*!
+ \fn Q3DictIterator::~Q3DictIterator()
+
+ Destroys the iterator.
+*/
+
+/*!
+ \fn uint Q3DictIterator::count() const
+
+ Returns the number of items in the dictionary over which the
+ iterator is operating.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool Q3DictIterator::isEmpty() const
+
+ Returns TRUE if the dictionary is empty, i.e. count() == 0;
+ otherwise returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn type *Q3DictIterator::toFirst()
+
+ Resets the iterator, making the first item the first current item.
+ First in this context means first in the arbitrary traversal
+ order. Returns a pointer to this item.
+
+ If the dictionary is empty it sets the current item to 0 and
+ returns 0.
+*/
+
+/*!
+ \fn type *Q3DictIterator::operator*()
+ \internal
+*/
+
+/*!
+ \fn Q3DictIterator::operator type*() const
+
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+
+/*!
+ \fn type *Q3DictIterator::current() const
+
+ Returns a pointer to the current iterator item's value.
+*/
+
+/*!
+ \fn QString Q3DictIterator::currentKey() const
+
+ Returns the current iterator item's key.
+*/
+
+/*!
+ \fn type *Q3DictIterator::operator()()
+
+ Makes the next item current and returns the original current item.
+
+ If the current iterator item was the last item in the dictionary
+ or if it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3DictIterator::operator++()
+
+ Prefix ++ makes the next item current and returns the new current
+ item.
+
+ If the current iterator item was the last item in the dictionary
+ or if it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3DictIterator::operator+=( uint jump )
+ \internal
+ Sets the current item to the item \a jump positions after the current item,
+ and returns a pointer to that item.
+
+ If that item is beyond the last item or if the dictionary is empty,
+ it sets the current item to 0 and returns 0.
+*/
diff --git a/src/qt3support/tools/q3intcache.qdoc b/src/qt3support/tools/q3intcache.qdoc
new file mode 100644
index 0000000..770532e
--- /dev/null
+++ b/src/qt3support/tools/q3intcache.qdoc
@@ -0,0 +1,446 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3IntCache
+ \brief The Q3IntCache class is a template class that provides a cache based on long keys.
+ \compat
+
+ Q3IntCache is implemented as a template class. Define a template
+ instance Q3IntCache\<X\> to create a cache that operates on
+ pointers to X, or X*.
+
+ A cache is a least recently used (LRU) list of cache items,
+ accessed via \c long keys. 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 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 dictionary and reimplement newItem() if you want deep
+ copies.
+
+ When removing a cache item, the item will be automatically
+ deleted if auto-deletion is enabled.
+
+ There is a Q3IntCacheIterator which may be used to traverse the
+ items in the cache in arbitrary order.
+
+ \sa Q3IntCacheIterator, Q3Cache, Q3AsciiCache
+*/
+
+/*!
+ \fn Q3IntCache::Q3IntCache( const Q3IntCache<type> &c )
+
+ \internal
+
+ Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version.
+*/
+
+/*!
+ \fn Q3IntCache::Q3IntCache( int maxCost, int size )
+
+ 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 is associated with a 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.
+*/
+
+/*!
+ \fn Q3IntCache::~Q3IntCache()
+
+ Removes all items from the cache and then destroys the int cache.
+ If auto-deletion is enabled the cache's items are deleted. All
+ iterators that access this cache will be reset.
+*/
+
+/*!
+ \fn Q3IntCache<type>& Q3IntCache::operator=( const Q3IntCache<type> &c )
+
+ \internal
+
+ Do not use. A Q3IntCache cannot be copied. Calls qFatal() in debug version.
+*/
+
+/*!
+ \fn int Q3IntCache::maxCost() const
+
+ Returns the maximum allowed total cost of the cache.
+
+ \sa setMaxCost() totalCost()
+*/
+
+/*!
+ \fn int Q3IntCache::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 Q3IntCache::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 Q3IntCache::count() const
+
+ Returns the number of items in the cache.
+
+ \sa totalCost()
+*/
+
+/*!
+ \fn uint Q3IntCache::size() const
+
+ Returns the size of the hash array used to implement the cache.
+ This should be a bit larger than count() is likely to be.
+*/
+
+/*!
+ \fn bool Q3IntCache::isEmpty() const
+
+ Returns TRUE if the cache is empty; otherwise returns FALSE.
+*/
+
+/*!
+ \fn bool Q3IntCache::insert( long k, const type *d, int c, int p )
+
+ Inserts the item \a d into the cache with key \a k and assigns it
+ a cost of \a c (default 1). Returns TRUE if it succeeds; otherwise
+ returns FALSE.
+
+ The cache's size is limited, and if the total cost is too high,
+ Q3IntCache will remove old, least-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 (for example, the cost \c,
+ exceeds maxCost()), you must delete \a d yourself. Additionally,
+ be very careful about using \a d after calling this function. 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 Q3IntCache::remove( long 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 most recently 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 * Q3IntCache::take( long 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 most recently 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 Q3IntCache::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 * Q3IntCache::find( long k, bool ref ) const
+
+ Returns the item associated with \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 most recently is returned.
+*/
+
+/*!
+ \fn type * Q3IntCache::operator[]( long k ) const
+
+ Returns the item associated with \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 most recently is returned.
+
+ This is the same as find( k, TRUE ).
+
+ \sa find()
+*/
+
+/*!
+ \fn void Q3IntCache::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.
+*/
+
+/*!
+ \class Q3IntCacheIterator
+ \brief The Q3IntCacheIterator class provides an iterator for Q3IntCache 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 Q3IntCache. Q3IntCache updates all iterators
+ that refer an item when that item is removed.
+
+ Q3IntCacheIterator provides an operator++(), and an operator+=() to
+ traverse the cache; current() and currentKey() to access the
+ current cache item and its key; atFirst() atLast(), which return
+ TRUE if the iterator points to the first/last item in the cache;
+ isEmpty(), which returns TRUE if the cache is empty; and count(),
+ which 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 Q3IntCache
+*/
+
+/*!
+ \fn Q3IntCacheIterator::Q3IntCacheIterator( const Q3IntCache<type> &cache )
+
+ Constructs an iterator for \a cache. The current iterator item is
+ set to point to the first item in the \a cache (or rather, the
+ first item is defined to be the item at which this constructor
+ sets the iterator to point).
+*/
+
+/*!
+ \fn Q3IntCacheIterator::Q3IntCacheIterator (const Q3IntCacheIterator<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 Q3IntCacheIterator<type>& Q3IntCacheIterator::operator=( const Q3IntCacheIterator<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 Q3IntCacheIterator::count() const
+
+ Returns the number of items in the cache on which this iterator
+ operates.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool Q3IntCacheIterator::isEmpty() const
+
+ Returns TRUE if the cache is empty; otherwise returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn bool Q3IntCacheIterator::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 Q3IntCacheIterator::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 *Q3IntCacheIterator::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 *Q3IntCacheIterator::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 Q3IntCacheIterator::operator type *() const
+
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *Q3IntCacheIterator::current() const
+
+ Returns a pointer to the current iterator item.
+*/
+
+/*!
+ \fn long Q3IntCacheIterator::currentKey() const
+
+ Returns the key for the current iterator item.
+*/
+
+/*!
+ \fn type *Q3IntCacheIterator::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 *Q3IntCacheIterator::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 *Q3IntCacheIterator::operator-=( uint jump )
+
+ Returns the item \a jump positions before the current item, or 0
+ if it is beyond the first item. Makes this the current item.
+*/
+
+/*!
+ \fn type *Q3IntCacheIterator::operator++()
+
+ Prefix ++ makes the iterator point to the item just after
+ current(), and makes it the new current item for the iterator. If
+ current() was the last item, operator--() returns 0.
+*/
+
+/*!
+ \fn type *Q3IntCacheIterator::operator--()
+
+ Prefix -- makes the iterator point to the item just before
+ current(), and makes it the new current item for the iterator. If
+ current() was the first item, operator--() returns 0.
+*/
diff --git a/src/qt3support/tools/q3intdict.qdoc b/src/qt3support/tools/q3intdict.qdoc
new file mode 100644
index 0000000..731050d
--- /dev/null
+++ b/src/qt3support/tools/q3intdict.qdoc
@@ -0,0 +1,390 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3IntDict
+ \brief The Q3IntDict class is a template class that provides a dictionary based on long keys.\
+ \compat
+
+ Q3IntDict is implemented as a template class. Define a template
+ instance Q3IntDict\<X\> to create a dictionary that operates on
+ pointers to X (X*).
+
+ A dictionary is a collection of key-value pairs. The key is an \c
+ long used for insertion, removal and lookup. The value is a
+ pointer. Dictionaries provide very fast insertion and lookup.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0
+
+ See Q3Dict for full details, including the choice of dictionary
+ size, and how deletions are handled.
+
+ \sa Q3IntDictIterator, Q3Dict, Q3AsciiDict, Q3PtrDict
+*/
+
+
+/*!
+ \fn Q3IntDict::Q3IntDict( int size )
+
+ Constructs a dictionary using an internal hash array of size \a
+ size.
+
+ Setting \a size to a suitably large prime number (equal to or
+ greater than the expected number of entries) makes the hash
+ distribution better which leads to faster lookup.
+*/
+
+/*!
+ \fn Q3IntDict::Q3IntDict( const Q3IntDict<type> &dict )
+
+ Constructs a copy of \a dict.
+
+ Each item in \a dict is inserted into this dictionary. Only the
+ pointers are copied (shallow copy).
+*/
+
+/*!
+ \fn Q3IntDict::~Q3IntDict()
+
+ Removes all items from the dictionary and destroys it.
+
+ All iterators that access this dictionary will be reset.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn Q3IntDict<type> &Q3IntDict::operator=(const Q3IntDict<type> &dict)
+
+ Assigns \a dict to this dictionary and returns a reference to this
+ dictionary.
+
+ This dictionary is first cleared and then each item in \a dict is
+ inserted into this dictionary. Only the pointers are copied
+ (shallow copy), unless newItem() has been reimplemented.
+*/
+
+/*!
+ \fn uint Q3IntDict::count() const
+
+ Returns the number of items in the dictionary.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn uint Q3IntDict::size() const
+
+ Returns the size of the internal hash array (as specified in the
+ constructor).
+
+ \sa count()
+*/
+
+/*!
+ \fn void Q3IntDict::resize( uint newsize )
+
+ Changes the size of the hashtable to \a newsize. The contents of
+ the dictionary are preserved, but all iterators on the dictionary
+ become invalid.
+*/
+
+/*!
+ \fn bool Q3IntDict::isEmpty() const
+
+ Returns TRUE if the dictionary is empty; otherwise returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn void Q3IntDict::insert( long key, const type *item )
+
+ Insert item \a item into the dictionary using key \a key.
+
+ Multiple items can have the same key, in which case only the last
+ item will be accessible using \l operator[]().
+
+ \a item may not be 0.
+
+ \sa replace()
+*/
+
+/*!
+ \fn void Q3IntDict::replace( long key, const type *item )
+
+ If the dictionary has key \a key, this key's item is replaced with
+ \a item. If the dictionary doesn't contain key \a key, \a item is
+ inserted into the dictionary using key \a key.
+
+ \a item may not be 0.
+
+ Equivalent to:
+ \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be replaced.
+
+ \sa insert()
+*/
+
+/*!
+ \fn bool Q3IntDict::remove( long key )
+
+ Removes the item associated with \a key from the dictionary.
+ Returns TRUE if successful, i.e. if the \a key is in the
+ dictionary; otherwise returns FALSE.
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be removed.
+
+ The removed item is deleted if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+ All dictionary iterators that refer to the removed item will be
+ set to point to the next item in the dictionary's traversal
+ order.
+
+ \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn type *Q3IntDict::take( long key )
+
+ Takes the item associated with \a key out of the dictionary
+ without deleting it (even if \link Q3PtrCollection::setAutoDelete()
+ auto-deletion\endlink is enabled).
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be taken.
+
+ Returns a pointer to the item taken out, or 0 if the key does not
+ exist in the dictionary.
+
+ All dictionary iterators that refer to the taken item will be set
+ to point to the next item in the dictionary's traversing order.
+
+ \sa remove(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn void Q3IntDict::clear()
+
+ Removes all items from the dictionary.
+
+ The removed items are deleted if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+ All dictionary iterators that access this dictionary will be reset.
+
+ \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+ \fn type *Q3IntDict::find( long key ) const
+
+ Returns the item associated with \a key, or 0 if the key does not
+ exist in the dictionary.
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be found.
+
+ Equivalent to operator[].
+
+ \sa operator[]()
+*/
+
+/*!
+ \fn type *Q3IntDict::operator[]( long key ) const
+
+ Returns the item associated with \a key, or 0 if the key does not
+ exist in the dictionary.
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be found.
+
+ Equivalent to the find() function.
+
+ \sa find()
+*/
+
+/*!
+ \fn void Q3IntDict::statistics() const
+
+ Debugging-only function that prints out the dictionary
+ distribution using qDebug().
+*/
+
+/*!
+ \fn QDataStream& Q3IntDict::read( QDataStream &s, Q3PtrCollection::Item &item )
+
+ Reads a dictionary item from the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation sets \a item to 0.
+
+ \sa write()
+*/
+
+/*!
+ \fn QDataStream& Q3IntDict::write( QDataStream &s, Q3PtrCollection::Item item ) const
+
+ Writes a dictionary \a item to the stream \a s and returns a
+ reference to the stream.
+
+ \sa read()
+*/
+
+/*!
+ \class Q3IntDictIterator
+ \brief The Q3IntDictIterator class provides an iterator for Q3IntDict collections.
+ \compat
+
+ Q3IntDictIterator is implemented as a template class. Define a
+ template instance Q3IntDictIterator\<X\> to create a dictionary
+ iterator that operates on Q3IntDict\<X\> (dictionary of X*).
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2
+
+ Note that the traversal order is arbitrary; you are not guaranteed the
+ order shown above.
+
+ Multiple iterators may independently traverse the same dictionary.
+ A Q3IntDict knows about all the iterators that are operating on the
+ dictionary. When an item is removed from the dictionary, Q3IntDict
+ updates all iterators that refer the removed item to point to the
+ next item in the traversal order.
+
+ \sa Q3IntDict
+*/
+
+/*!
+ \fn Q3IntDictIterator::Q3IntDictIterator( const Q3IntDict<type> &dict )
+
+ Constructs an iterator for \a dict. The current iterator item is
+ set to point to the 'first' item in the \a dict. The first item
+ refers to the first item in the dictionary's arbitrary internal
+ ordering.
+*/
+
+/*!
+ \fn Q3IntDictIterator::~Q3IntDictIterator()
+
+ Destroys the iterator.
+*/
+
+/*!
+ \fn uint Q3IntDictIterator::count() const
+
+ Returns the number of items in the dictionary this iterator
+ operates over.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool Q3IntDictIterator::isEmpty() const
+
+ Returns TRUE if the dictionary is empty; otherwise eturns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn type *Q3IntDictIterator::toFirst()
+
+ Sets the current iterator item to point to the first item in the
+ dictionary and returns a pointer to the item. The first item
+ refers to the first item in the dictionary's arbitrary internal
+ ordering. If the dictionary is empty it sets the current item to
+ 0 and returns 0.
+*/
+
+/*!
+ \fn Q3IntDictIterator::operator type *() const
+
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *Q3IntDictIterator::current() const
+
+ Returns a pointer to the current iterator item.
+*/
+
+/*!
+ \fn long Q3IntDictIterator::currentKey() const
+
+ Returns the key for the current iterator item.
+*/
+
+/*!
+ \fn type *Q3IntDictIterator::operator()()
+
+ Makes the succeeding item current and returns the original current
+ item.
+
+ If the current iterator item was the last item in the dictionary
+ or if it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3IntDictIterator::operator++()
+
+ Prefix ++ makes the succeeding item current and returns the new
+ current item.
+
+ If the current iterator item was the last item in the dictionary
+ or if it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3IntDictIterator::operator+=( uint jump )
+
+ Sets the current item to the item \a jump positions after the
+ current item, and returns a pointer to that item.
+
+ If that item is beyond the last item or if the dictionary is
+ empty, it sets the current item to 0 and returns 0.
+*/
diff --git a/src/qt3support/tools/q3memarray.qdoc b/src/qt3support/tools/q3memarray.qdoc
new file mode 100644
index 0000000..eb0648c
--- /dev/null
+++ b/src/qt3support/tools/q3memarray.qdoc
@@ -0,0 +1,523 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3MemArray
+ \brief The Q3MemArray class is a template class that provides arrays of simple types.
+ \compat
+
+ Q3MemArray is implemented as a template class. Define a template
+ instance Q3MemArray\<X\> to create an array that contains X items.
+
+ Q3MemArray stores the array elements directly in the array. It can
+ only deal with simple types (i.e. C++ types, structs, and classes
+ that have no constructors, destructors, or virtual functions).
+ Q3MemArray uses bitwise operations to copy and compare array
+ elements.
+
+ The Q3PtrVector collection class is also a kind of array. Like most
+ old Qt collection classes, it uses pointers to the contained items.
+
+ Q3MemArray uses explicit sharing with a
+ reference count. If more than one array shares common data and one
+ of the arrays is modified, all the arrays are modified.
+
+ The benefit of sharing is that a program does not need to duplicate
+ data when it is not required, which results in lower memory use
+ and less copying of data.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 0
+
+ Program output:
+ \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 1
+
+ Note concerning the use of Q3MemArray for manipulating structs or
+ classes: Compilers will often pad the size of structs of odd sizes
+ up to the nearest word boundary. This will then be the size
+ Q3MemArray will use for its bitwise element comparisons. Because
+ the remaining bytes will typically be uninitialized, this can
+ cause find() etc. to fail to find the element. Example:
+
+ \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 2
+
+ To work around this, make sure that you use a struct where
+ sizeof() returns the same as the sum of the sizes of the members
+ either by changing the types of the struct members or by adding
+ dummy members.
+
+ Q3MemArray data can be traversed by iterators (see begin() and
+ end()). The number of items is returned by count(). The array can
+ be resized with resize() and filled using fill().
+
+ You can make a shallow copy of the array with assign() (or
+ operator=()) and a deep copy with duplicate().
+
+ Search for values in the array with find() and contains(). For
+ sorted arrays (see sort()) you can search using bsearch().
+
+ You can set the data directly using setRawData() and
+ resetRawData(), although this requires care.
+*/
+
+/*! \fn Q3MemArray::operator QVector<type>() const
+
+ Automatically converts the Q3MemArray<type> into a QVector<type>.
+*/
+
+/*! \typedef Q3MemArray::Iterator
+ A Q3MemArray iterator.
+ \sa begin() end()
+*/
+/*! \typedef Q3MemArray::ConstIterator
+ A const Q3MemArray iterator.
+ \sa begin() end()
+*/
+/*! \typedef Q3MemArray::ValueType
+ \internal
+*/
+
+/*!
+ \fn Q3MemArray::Q3MemArray()
+
+ Constructs a null array.
+
+ \sa isNull()
+*/
+
+/*!
+ \fn Q3MemArray::Q3MemArray( int size )
+
+ Constructs an array with room for \a size elements. Makes a null
+ array if \a size == 0.
+
+ The elements are left uninitialized.
+
+ \sa resize(), isNull()
+*/
+
+/*!
+ \fn Q3MemArray::Q3MemArray( const Q3MemArray<type> &a )
+
+ Constructs a shallow copy of \a a.
+
+ \sa assign()
+*/
+
+/*!
+ \fn Q3MemArray::Q3MemArray(const QVector<type> &vector)
+
+ Constructs a copy of \a vector.
+*/
+
+/*!
+ \fn Q3MemArray::Q3MemArray(int arg1, int arg2)
+
+ Constructs an array \e{without allocating} array space. The
+ arguments \a arg1 and \a arg2 should be zero. Use at your own
+ risk.
+*/
+
+/*!
+ \fn Q3MemArray::~Q3MemArray()
+
+ Dereferences the array data and deletes it if this was the last
+ reference.
+*/
+
+/*!
+ \fn Q3MemArray<type> &Q3MemArray::operator=( const Q3MemArray<type> &a )
+
+ Assigns a shallow copy of \a a to this array and returns a
+ reference to this array.
+
+ Equivalent to assign( a ).
+*/
+
+/*!
+ \fn type *Q3MemArray::data() const
+
+ Returns a pointer to the actual array data.
+
+ The array is a null array if data() == 0 (null pointer).
+
+ \sa isNull()
+*/
+
+/*!
+ \fn uint Q3MemArray::nrefs() const
+
+ Returns the reference count for the shared array data. This
+ reference count is always greater than zero.
+*/
+
+/*!
+ \fn uint Q3MemArray::size() const
+
+ Returns the size of the array (maximum number of elements).
+
+ The array is a null array if size() == 0.
+
+ \sa isNull(), resize()
+*/
+
+/*!
+ \fn uint Q3MemArray::count() const
+
+ Returns the same as size().
+
+ \sa size()
+*/
+
+/*!
+ \fn bool Q3MemArray::isEmpty() const
+
+ Returns TRUE if the array is empty; otherwise returns FALSE.
+
+ isEmpty() is equivalent to isNull() for Q3MemArray (unlike
+ QString).
+*/
+
+/*!
+ \fn bool Q3MemArray::isNull() const
+
+ Returns TRUE if the array is null; otherwise returns FALSE.
+
+ A null array has size() == 0 and data() == 0.
+*/
+
+/*!
+ \fn bool Q3MemArray::resize( uint size, Optimization optim )
+
+ Resizes (expands or shrinks) the array to \a size elements. The
+ array becomes a null array if \a size == 0.
+
+ Returns TRUE if successful, or FALSE if the memory cannot be
+ allocated.
+
+ New elements are not initialized.
+
+ \a optim is either Q3GArray::MemOptim (the default) or
+ Q3GArray::SpeedOptim. When optimizing for speed rather than memory
+ consumption, the array uses a smart grow and shrink algorithm that
+ might allocate more memory than is actually needed for \a size
+ elements. This speeds up subsequent resize operations, for example
+ when appending many elements to an array, since the space has
+ already been allocated.
+
+ \sa size()
+*/
+
+/*!
+ \fn bool Q3MemArray::resize( uint size )
+
+ \overload
+
+ Resizes (expands or shrinks) the array to \a size elements. The
+ array becomes a null array if \a size == 0.
+
+ Returns TRUE if successful, i.e. if the memory can be allocated;
+ otherwise returns FALSE.
+
+ New elements are not initialized.
+
+ \sa size()
+*/
+
+/*!
+ \fn bool Q3MemArray::truncate( uint pos )
+
+ Truncates the array at position \a pos.
+
+ Returns TRUE if successful, i.e. if the memory can be allocated;
+ otherwise returns FALSE.
+
+ Equivalent to resize(\a pos).
+
+ \sa resize()
+*/
+
+/*!
+ \fn bool Q3MemArray::fill( const type &v, int size )
+
+ Fills the array with the value \a v. If \a size is specified as
+ different from -1, then the array will be resized before being
+ filled.
+
+ Returns TRUE if successful, i.e. if \a size is -1, or \a size is
+ != -1 and the memory can be allocated; otherwise returns FALSE.
+
+ \sa resize()
+*/
+
+/*!
+ \fn void Q3MemArray::detach()
+
+ Detaches this array from shared array data; i.e. it makes a
+ private, deep copy of the data.
+
+ Copying will be performed only if the \link nrefs() reference
+ count\endlink is greater than one.
+
+ \sa copy()
+*/
+
+/*!
+ \fn Q3MemArray<type> Q3MemArray::copy() const
+
+ Returns a deep copy of this array.
+
+ \sa detach(), duplicate()
+*/
+
+/*!
+ \fn Q3MemArray<type> &Q3MemArray::assign( const Q3MemArray<type> &a )
+
+ Shallow copy. Dereferences the current array and references the
+ data contained in \a a instead. Returns a reference to this array.
+
+ \sa operator=()
+*/
+
+/*!
+ \fn Q3MemArray<type> &Q3MemArray::assign( const type *data, uint size )
+
+ \overload
+
+ Shallow copy. Dereferences the current array and references the
+ array data \a data, which contains \a size elements. Returns a
+ reference to this array.
+
+ Do not delete \a data later; Q3MemArray will call free() on it
+ at the right time.
+*/
+
+/*!
+ \fn Q3MemArray<type> &Q3MemArray::duplicate( const Q3MemArray<type> &a )
+
+ Deep copy. Dereferences the current array and obtains a copy of
+ the data contained in \a a instead. Returns a reference to this
+ array.
+
+ \sa copy()
+*/
+
+/*!
+ \fn Q3MemArray<type> &Q3MemArray::duplicate( const type *data, uint size )
+
+ \overload
+
+ Deep copy. Dereferences the current array and obtains a copy of
+ the array data \a data instead. Returns a reference to this array.
+ The size of the array is given by \a size.
+
+ \sa copy()
+*/
+
+/*!
+ \fn Q3MemArray<type> &Q3MemArray::setRawData( const type *data, uint size )
+
+ Sets raw data and returns a reference to the array.
+
+ Dereferences the current array and sets the new array data to \a
+ data and the new array size to \a size. Do not attempt to resize
+ or re-assign the array data when raw data has been set. Call
+ resetRawData(\a data, \a size) to reset the array.
+
+ Setting raw data is useful because it sets Q3MemArray data without
+ allocating memory or copying data.
+
+ Example I (intended use):
+ \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 3
+
+ Example II (you don't want to do this):
+ \snippet doc/src/snippets/code/doc_src_q3memarray.qdoc 4
+
+ \warning If you do not call resetRawData(), Q3MemArray will attempt
+ to deallocate or reallocate the raw data, which might not be too
+ good. Be careful.
+
+ \sa resetRawData()
+*/
+
+/*!
+ \fn void Q3MemArray::resetRawData( const type *data, uint size )
+
+ Removes internal references to the raw data that was set using
+ setRawData(). This means that Q3MemArray no longer has access to
+ the \a data, so you are free to manipulate \a data as you wish.
+ You can now use the Q3MemArray without affecting the original \a
+ data, for example by calling setRawData() with a pointer to some
+ other data.
+
+ The arguments must be the \a data and length, \a size, that were
+ passed to setRawData(). This is for consistency checking.
+
+ \sa setRawData()
+*/
+
+/*!
+ \fn int Q3MemArray::find( const type &v, uint index ) const
+
+ Finds the first occurrence of \a v, starting at position \a index.
+
+ Returns the position of \a v, or -1 if \a v could not be found.
+
+ \sa contains()
+*/
+
+/*!
+ \fn int Q3MemArray::contains( const type &v ) const
+
+ Returns the number of times \a v occurs in the array.
+
+ \sa find()
+*/
+
+/*!
+ \fn void Q3MemArray::sort()
+
+ Sorts the array elements in ascending order, using bitwise
+ comparison (memcmp()).
+
+ \sa bsearch()
+*/
+
+/*!
+ \fn int Q3MemArray::bsearch( const type &v ) const
+
+ In a sorted array (as sorted by sort()), finds the first
+ occurrence of \a v by using a binary search. For a sorted
+ array this is generally much faster than find(), which does
+ a linear search.
+
+ Returns the position of \a v, or -1 if \a v could not be found.
+
+ \sa sort(), find()
+*/
+
+/*!
+ \fn type &Q3MemArray::operator[]( int index ) const
+
+ Returns a reference to the element at position \a index in the
+ array.
+
+ This can be used to both read and set an element. Equivalent to
+ at().
+
+ \sa at()
+*/
+
+/*!
+ \fn type &Q3MemArray::at( uint index ) const
+
+ Returns a reference to the element at position \a index in the array.
+
+ This can be used to both read and set an element.
+
+ \sa operator[]()
+*/
+
+/*!
+ \fn Q3MemArray::operator const type *() const
+
+ Cast operator. Returns a pointer to the array.
+
+ \sa data()
+*/
+
+/*!
+ \fn bool Q3MemArray::operator==( const Q3MemArray<type> &a ) const
+
+ Returns TRUE if this array is equal to \a a; otherwise returns
+ FALSE.
+
+ The two arrays are compared bitwise.
+
+ \sa operator!=()
+*/
+
+/*!
+ \fn bool Q3MemArray::operator!=( const Q3MemArray<type> &a ) const
+
+ Returns TRUE if this array is different from \a a; otherwise
+ returns FALSE.
+
+ The two arrays are compared bitwise.
+
+ \sa operator==()
+*/
+
+/*!
+ \fn Iterator Q3MemArray::begin()
+
+ Returns an iterator pointing at the beginning of this array. This
+ iterator can be used in the same way as the iterators of
+ Q3ValueList and QMap, for example.
+*/
+
+/*!
+ \fn Iterator Q3MemArray::end()
+
+ Returns an iterator pointing behind the last element of this
+ array. This iterator can be used in the same way as the iterators
+ of Q3ValueList and QMap, for example.
+*/
+
+/*!
+ \fn ConstIterator Q3MemArray::begin() const
+
+ \overload
+
+ Returns a const iterator pointing at the beginning of this array.
+ This iterator can be used in the same way as the iterators of
+ Q3ValueList and QMap, for example.
+*/
+
+/*!
+ \fn ConstIterator Q3MemArray::end() const
+
+ \overload
+
+ Returns a const iterator pointing behind the last element of this
+ array. This iterator can be used in the same way as the iterators
+ of Q3ValueList and QMap, for example.
+*/
diff --git a/src/qt3support/tools/q3ptrdict.qdoc b/src/qt3support/tools/q3ptrdict.qdoc
new file mode 100644
index 0000000..531b085
--- /dev/null
+++ b/src/qt3support/tools/q3ptrdict.qdoc
@@ -0,0 +1,388 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3PtrDict
+ \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys.
+ \compat
+
+ Q3PtrDict is implemented as a template class. Define a template
+ instance Q3PtrDict\<X\> to create a dictionary that operates on
+ pointers to X (X*).
+
+ A dictionary is a collection of key-value pairs. The key is a
+ void* used for insertion, removal and lookup. The value is a
+ pointer. Dictionaries provide very fast insertion and lookup.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 0
+ In this example we use a dictionary to add an extra property (a
+ char*) to the line edits we're using.
+
+ See Q3Dict for full details, including the choice of dictionary
+ size, and how deletions are handled.
+
+ \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict
+*/
+
+
+/*!
+ \fn Q3PtrDict::Q3PtrDict( int size )
+
+ Constructs a dictionary using an internal hash array with the size
+ \a size.
+
+ Setting \a size to a suitably large prime number (equal to or
+ greater than the expected number of entries) makes the hash
+ distribution better and improves lookup performance.
+*/
+
+/*!
+ \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict<type> &dict )
+
+ Constructs a copy of \a dict.
+
+ Each item in \a dict is inserted into this dictionary. Only the
+ pointers are copied (shallow copy).
+*/
+
+/*!
+ \fn Q3PtrDict::~Q3PtrDict()
+
+ Removes all items from the dictionary and destroys it.
+
+ All iterators that access this dictionary will be reset.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn Q3PtrDict<type> &Q3PtrDict::operator=(const Q3PtrDict<type> &dict)
+
+ Assigns \a dict to this dictionary and returns a reference to this
+ dictionary.
+
+ This dictionary is first cleared and then each item in \a dict is
+ inserted into the dictionary. Only the pointers are copied
+ (shallow copy), unless newItem() has been reimplemented.
+*/
+
+/*!
+ \fn uint Q3PtrDict::count() const
+
+ Returns the number of items in the dictionary.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn uint Q3PtrDict::size() const
+
+ Returns the size of the internal hash table (as specified in the
+ constructor).
+
+ \sa count()
+*/
+
+/*!
+ \fn void Q3PtrDict::resize( uint newsize )
+
+ Changes the size of the hash table to \a newsize. The contents of
+ the dictionary are preserved, but all iterators on the dictionary
+ become invalid.
+*/
+
+/*!
+ \fn bool Q3PtrDict::isEmpty() const
+
+ Returns TRUE if the dictionary is empty; otherwise returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn void Q3PtrDict::insert( void *key, const type *item )
+
+ Inserts the \a key with the \a item into the dictionary.
+
+ Multiple items can have the same key, in which case only the last
+ item will be accessible using \l operator[]().
+
+ \a item may not be 0.
+
+ \sa replace()
+*/
+
+/*!
+ \fn void Q3PtrDict::replace( void *key, const type *item )
+
+ If the dictionary has key \a key, this key's item is replaced with
+ \a item. If the dictionary doesn't contain key \a key, \a item is
+ inserted into the dictionary using key \a key.
+
+ \a item may not be 0.
+
+ Equivalent to
+ \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be replaced.
+
+ \sa insert()
+*/
+
+/*!
+ \fn bool Q3PtrDict::remove( void *key )
+
+ Removes the item associated with \a key from the dictionary.
+ Returns TRUE if successful, i.e. if \a key is in the dictionary;
+ otherwise returns FALSE.
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be removed.
+
+ The removed item is deleted if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+ All dictionary iterators that refer to the removed item will be
+ set to point to the next item in the dictionary traversal order.
+
+ \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn type *Q3PtrDict::take( void *key )
+
+ Takes the item associated with \a key out of the dictionary
+ without deleting it (even if \link Q3PtrCollection::setAutoDelete()
+ auto-deletion\endlink is enabled).
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be removed.
+
+ Returns a pointer to the item taken out, or 0 if the key does not
+ exist in the dictionary.
+
+ All dictionary iterators that refer to the taken item will be set
+ to point to the next item in the dictionary traversal order.
+
+ \sa remove(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn void Q3PtrDict::clear()
+
+ Removes all items from the dictionary.
+
+ The removed items are deleted if \link
+ Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
+
+ All dictionary iterators that access this dictionary will be
+ reset.
+
+ \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+ \fn type *Q3PtrDict::find( void *key ) const
+
+ Returns the item associated with \a key, or 0 if the key does not
+ exist in the dictionary.
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be found.
+
+ Equivalent to operator[].
+
+ \sa operator[]()
+*/
+
+/*!
+ \fn type *Q3PtrDict::operator[]( void *key ) const
+
+ Returns the item associated with \a key, or 0 if the key does not
+ exist in the dictionary.
+
+ If there are two or more items with equal keys, then the most
+ recently inserted item will be found.
+
+ Equivalent to the find() function.
+
+ \sa find()
+*/
+
+/*!
+ \fn void Q3PtrDict::statistics() const
+
+ Debugging-only function that prints out the dictionary
+ distribution using qDebug().
+*/
+
+/*!
+ \fn QDataStream& Q3PtrDict::read( QDataStream &s, Q3PtrCollection::Item &item )
+
+ Reads a dictionary item from the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation sets \a item to 0.
+
+ \sa write()
+*/
+
+/*!
+ \fn QDataStream& Q3PtrDict::write( QDataStream &s, Q3PtrCollection::Item item) const
+
+ Writes a dictionary \a item to the stream \a s and returns a
+ reference to the stream.
+
+ \sa read()
+*/
+
+/*!
+ \class Q3PtrDictIterator
+ \brief The Q3PtrDictIterator class provides an iterator for Q3PtrDict collections.
+ \compat
+
+ Q3PtrDictIterator is implemented as a template class. Define a
+ template instance Q3PtrDictIterator\<X\> to create a dictionary
+ iterator that operates on Q3PtrDict\<X\> (dictionary of X*).
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 2
+ In the example we insert some line edits into a dictionary,
+ associating a string with each. We then iterate over the
+ dictionary printing the associated strings.
+
+ Multiple iterators may independently traverse the same dictionary.
+ A Q3PtrDict knows about all the iterators that are operating on the
+ dictionary. When an item is removed from the dictionary, Q3PtrDict
+ updates all iterators that refer the removed item to point to the
+ next item in the traversing order.
+
+ \sa Q3PtrDict
+*/
+
+/*!
+ \fn Q3PtrDictIterator::Q3PtrDictIterator( const Q3PtrDict<type> &dict )
+
+ Constructs an iterator for \a dict. The current iterator item is
+ set to point on the first item in the \a dict.
+*/
+
+/*!
+ \fn Q3PtrDictIterator::~Q3PtrDictIterator()
+
+ Destroys the iterator.
+*/
+
+/*!
+ \fn uint Q3PtrDictIterator::count() const
+
+ Returns the number of items in the dictionary this iterator
+ operates on.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool Q3PtrDictIterator::isEmpty() const
+
+ Returns TRUE if the dictionary is empty; otherwise returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn type *Q3PtrDictIterator::toFirst()
+
+ Sets the current iterator item to point to the first item in the
+ dictionary and returns a pointer to the item. If the dictionary is
+ empty, it sets the current item to 0 and returns 0.
+*/
+
+/*!
+ \fn Q3PtrDictIterator::operator type *() const
+
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *Q3PtrDictIterator::current() const
+
+ Returns a pointer to the current iterator item's value.
+*/
+
+/*!
+ \fn void *Q3PtrDictIterator::currentKey() const
+
+ Returns the current iterator item's key.
+*/
+
+/*!
+ \fn type *Q3PtrDictIterator::operator()()
+
+ Makes the succeeding item current and returns the original current
+ item.
+
+ If the current iterator item was the last item in the dictionary
+ or if it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3PtrDictIterator::operator++()
+
+ Prefix ++ makes the succeeding item current and returns the new
+ current item.
+
+ If the current iterator item was the last item in the dictionary
+ or if it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3PtrDictIterator::operator+=( uint jump )
+
+ Sets the current item to the item \a jump positions after the
+ current item and returns a pointer to that item.
+
+ If that item is beyond the last item or if the dictionary is
+ empty, it sets the current item to 0 and returns 0.
+*/
diff --git a/src/qt3support/tools/q3ptrlist.qdoc b/src/qt3support/tools/q3ptrlist.qdoc
new file mode 100644
index 0000000..b2b9c3f
--- /dev/null
+++ b/src/qt3support/tools/q3ptrlist.qdoc
@@ -0,0 +1,1157 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3PtrList
+ \brief The Q3PtrList class is a template class that provides a list.
+ \compat
+
+ Q3ValueList is an STL-compatible alternative to this class.
+
+ Define a template instance Q3PtrList\<X\> to create a list that
+ operates on pointers to X (X*).
+
+ The list class is indexable and has a \link at() current
+ index\endlink and a \link current() current item\endlink. The
+ first item corresponds to index position 0. The current index is
+ -1 if the current item is 0.
+
+ Items are inserted with prepend(), insert() or append(). Items are
+ removed with remove(), removeRef(), removeFirst() and
+ removeLast(). You can search for an item using find(), findNext(),
+ findRef() or findNextRef(). The list can be sorted with sort().
+ You can count the number of occurrences of an item with contains()
+ or containsRef(). You can get a pointer to the current item with
+ current(), to an item at a particular index position in the list
+ with at() or to the first or last item with getFirst() and
+ getLast(). You can also iterate over the list with first(),
+ last(), next() and prev() (which all update current()). The list's
+ deletion property is set with setAutoDelete().
+
+ \target example
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 0
+
+ The output is
+ \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 1
+
+ Q3PtrList has several member functions for traversing the list, but
+ using a Q3PtrListIterator can be more practical. Multiple list
+ iterators may traverse the same list, independently of each other
+ and of the current list item.
+
+ In the example above we make the call setAutoDelete(true).
+ Enabling auto-deletion tells the list to delete items that are
+ removed. The default is to not delete items when they are removed
+ but this would cause a memory leak in the example because there
+ are no other references to the list items.
+
+ When inserting an item into a list only the pointer is copied, not
+ the item itself, i.e. a shallow copy. It is possible to make the
+ list copy all of the item's data (deep copy) when an item is
+ inserted. insert(), inSort() and append() call the virtual
+ function Q3PtrCollection::newItem() for the item to be inserted.
+ Inherit a list and reimplement newItem() to have deep copies.
+
+ When removing an item from a list, the virtual function
+ Q3PtrCollection::deleteItem() is called. Q3PtrList's default
+ implementation is to delete the item if auto-deletion is enabled.
+
+ The virtual function compareItems() can be reimplemented to
+ compare two list items. This function is called from all list
+ functions that need to compare list items, for instance
+ remove(const type*). If you only want to deal with pointers, there
+ are functions that compare pointers instead, for instance
+ removeRef(const type*). These functions are somewhat faster than
+ those that call compareItems().
+
+ List items are stored as \c void* in an internal Q3LNode, which
+ also holds pointers to the next and previous list items. The
+ functions currentNode(), removeNode(), and takeNode() operate
+ directly on the Q3LNode, but they should be used with care. The
+ data component of the node is available through Q3LNode::getData().
+
+ The Q3StrList class is a list of \c char*.
+ It reimplements newItem(), deleteItem() and compareItems(). (But
+ see QStringList for a list of Unicode QStrings.)
+
+ \sa Q3PtrListIterator
+*/
+
+
+/*!
+ \fn Q3PtrList::Q3PtrList()
+
+ Constructs an empty list.
+*/
+
+/*!
+ \fn Q3PtrList::Q3PtrList( const Q3PtrList<type> &list )
+
+ Constructs a copy of \a list.
+
+ Each item in \a list is \link append() appended\endlink to this
+ list. Only the pointers are copied (shallow copy).
+*/
+
+/*!
+ \fn Q3PtrList::~Q3PtrList()
+
+ Removes all items from the list and destroys the list.
+
+ All list iterators that access this list will be reset.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn Q3PtrList<type> &Q3PtrList::operator=(const Q3PtrList<type> &list)
+
+ Assigns \a list to this list and returns a reference to this list.
+
+ This list is first cleared and then each item in \a list is \link
+ append() appended\endlink to this list. Only the pointers are
+ copied (shallow copy) unless newItem() has been reimplemented.
+*/
+
+/*!
+ \fn bool Q3PtrList::operator==(const Q3PtrList<type> &list ) const
+
+ Compares this list with \a list. Returns TRUE if the lists contain
+ the same data; otherwise returns FALSE.
+*/
+
+/*!
+ \fn uint Q3PtrList::count() const
+
+ Returns the number of items in the list.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool Q3PtrList::operator!=(const Q3PtrList<type> &list ) const
+
+ Compares this list with \a list. Returns TRUE if the lists contain
+ different data; otherwise returns FALSE.
+*/
+
+
+/*!
+ \fn void Q3PtrList::sort()
+
+ Sorts the list by the result of the virtual compareItems()
+ function.
+
+ The heap sort algorithm is used for sorting. It sorts n items with
+ O(n*log n) comparisons. This is the asymptotic optimal solution of
+ the sorting problem.
+
+ If the items in your list support operator<() and operator==(),
+ you might be better off with Q3SortedList because it implements the
+ compareItems() function for you using these two operators.
+
+ \sa inSort()
+*/
+
+/*!
+ \fn bool Q3PtrList::isEmpty() const
+
+ Returns TRUE if the list is empty; otherwise returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn bool Q3PtrList::insert( uint index, const type *item )
+
+ Inserts the \a item at position \a index in the list.
+
+ Returns TRUE if successful, i.e. if \a index is in range;
+ otherwise returns FALSE. The valid range is 0 to count()
+ (inclusively). The item is appended if \a index == count().
+
+ The inserted item becomes the current list item.
+
+ \a item must not be 0.
+
+ \sa append(), current(), replace()
+*/
+
+/*!
+ \fn bool Q3PtrList::replace( uint index, const type *item )
+
+ Replaces the item at position \a index with the new \a item.
+
+ Returns TRUE if successful, i.e. \a index is in the range 0 to
+ count()-1.
+
+ \sa append(), current(), insert()
+*/
+
+/*!
+ \fn void Q3PtrList::inSort( const type *item )
+
+ Inserts the \a item at its sorted position in the list.
+
+ The sort order depends on the virtual compareItems() function. All
+ items must be inserted with inSort() to maintain the sorting
+ order.
+
+ The inserted item becomes the current list item.
+
+ \a item must not be 0.
+
+ \warning Using inSort() is slow. An alternative, especially if you
+ have lots of items, is to simply append() or insert() them and
+ then use sort(). inSort() takes up to O(n) compares. That means
+ inserting n items in your list will need O(n^2) compares whereas
+ sort() only needs O(n*log n) for the same task. So use inSort()
+ only if you already have a presorted list and want to insert just
+ a few additional items.
+
+ \sa insert(), compareItems(), current(), sort()
+*/
+
+/*!
+ \fn void Q3PtrList::append( const type *item )
+
+ Inserts the \a item at the end of the list.
+
+ The inserted item becomes the current list item. This is
+ equivalent to \c{insert( count(), item )}.
+
+ \a item must not be 0.
+
+ \sa insert(), current(), prepend()
+*/
+
+/*!
+ \fn void Q3PtrList::prepend( const type *item )
+
+ Inserts the \a item at the start of the list.
+
+ The inserted item becomes the current list item. This is
+ equivalent to \c{insert( 0, item )}.
+
+ \a item must not be 0.
+
+ \sa append(), insert(), current()
+*/
+
+/*!
+ \fn bool Q3PtrList::remove( uint index )
+
+ Removes the item at position \a index in the list.
+
+ Returns TRUE if successful, i.e. if \a index is in range;
+ otherwise returns FALSE. The valid range is \c{0..(count() - 1)}
+ inclusive.
+
+ The removed item is deleted if \link setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ The item after the removed item becomes the new current list item
+ if the removed item is not the last item in the list. If the last
+ item is removed, the new last item becomes the current item.
+
+ All list iterators that refer to the removed item will be set to
+ point to the new current item.
+
+ \sa take(), clear(), setAutoDelete(), current() removeRef()
+*/
+
+/*!
+ \fn bool Q3PtrList::remove()
+
+ \overload
+
+ Removes the current list item.
+
+ Returns TRUE if successful, i.e. if the current item isn't 0;
+ otherwise returns FALSE.
+
+ The removed item is deleted if \link setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ The item after the removed item becomes the new current list item
+ if the removed item is not the last item in the list. If the last
+ item is removed, the new last item becomes the current item. The
+ current item is set to 0 if the list becomes empty.
+
+ All list iterators that refer to the removed item will be set to
+ point to the new current item.
+
+ \sa take(), clear(), setAutoDelete(), current() removeRef()
+*/
+
+/*!
+ \fn bool Q3PtrList::remove( const type *item )
+
+ \overload
+
+ Removes the first occurrence of \a item from the list.
+
+ Returns TRUE if successful, i.e. if \a item is in the list;
+ otherwise returns FALSE.
+
+ The removed item is deleted if \link setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ The compareItems() function is called when searching for the item
+ in the list. If compareItems() is not reimplemented, it is more
+ efficient to call removeRef().
+
+ If \a item is NULL then the current item is removed from the list.
+
+ The item after the removed item becomes the new current list item
+ if the removed item is not the last item in the list. If the last
+ item is removed, the new last item becomes the current item. The
+ current item is set to 0 if the list becomes empty.
+
+ All list iterators that refer to the removed item will be set to
+ point to the new current item.
+
+ \sa removeRef(), take(), clear(), setAutoDelete(), compareItems(),
+ current()
+*/
+
+/*!
+ \fn bool Q3PtrList::removeRef( const type *item )
+
+ Removes the first occurrence of \a item from the list.
+
+ Returns TRUE if successful, i.e. if \a item is in the list;
+ otherwise returns FALSE.
+
+ The removed item is deleted if \link setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ Equivalent to:
+ \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 2
+
+ The item after the removed item becomes the new current list item
+ if the removed item is not the last item in the list. If the last
+ item is removed, the new last item becomes the current item. The
+ current item is set to 0 if the list becomes empty.
+
+ All list iterators that refer to the removed item will be set to
+ point to the new current item.
+
+ \sa remove(), clear(), setAutoDelete(), current()
+*/
+
+/*!
+ \fn void Q3PtrList::removeNode( Q3LNode *node )
+
+ Removes the \a node from the list.
+
+ This node must exist in the list, otherwise the program may crash.
+
+ The removed item is deleted if \link setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ The first item in the list will become the new current list item.
+ The current item is set to 0 if the list becomes empty.
+
+ All list iterators that refer to the removed item will be set to
+ point to the item succeeding this item or to the preceding item if
+ the removed item was the last item.
+
+ \warning Do not call this function unless you are an expert.
+
+ \sa takeNode(), currentNode() remove() removeRef()
+*/
+
+/*!
+ \fn bool Q3PtrList::removeFirst()
+
+ Removes the first item from the list. Returns TRUE if successful,
+ i.e. if the list isn't empty; otherwise returns FALSE.
+
+ The removed item is deleted if \link setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ The first item in the list becomes the new current list item. The
+ current item is set to 0 if the list becomes empty.
+
+ All list iterators that refer to the removed item will be set to
+ point to the new current item.
+
+ \sa removeLast(), setAutoDelete(), current() remove()
+*/
+
+/*!
+ \fn bool Q3PtrList::removeLast()
+
+ Removes the last item from the list. Returns TRUE if successful,
+ i.e. if the list isn't empty; otherwise returns FALSE.
+
+ The removed item is deleted if \link setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ The last item in the list becomes the new current list item. The
+ current item is set to 0 if the list becomes empty.
+
+ All list iterators that refer to the removed item will be set to
+ point to the new current item.
+
+ \sa removeFirst(), setAutoDelete(), current()
+*/
+
+/*!
+ \fn type *Q3PtrList::take( uint index )
+
+ Takes the item at position \a index out of the list without
+ deleting it (even if \link setAutoDelete() auto-deletion\endlink
+ is enabled).
+
+ Returns a pointer to the item taken out of the list, or 0 if the
+ index is out of range. The valid range is \c{0..(count() - 1)}
+ inclusive.
+
+ The item after the removed item becomes the new current list item
+ if the removed item is not the last item in the list. If the last
+ item is removed, the new last item becomes the current item. The
+ current item is set to 0 if the list becomes empty.
+
+ All list iterators that refer to the taken item will be set to
+ point to the new current item.
+
+ \sa remove(), clear(), current()
+*/
+
+/*!
+ \fn type *Q3PtrList::take()
+
+ \overload
+
+ Takes the current item out of the list without deleting it (even
+ if \link setAutoDelete() auto-deletion\endlink is enabled).
+
+ Returns a pointer to the item taken out of the list, or 0 if
+ the current item is 0.
+
+ The item after the removed item becomes the new current list item
+ if the removed item is not the last item in the list. If the last
+ item is removed, the new last item becomes the current item. The
+ current item is set to 0 if the list becomes empty.
+
+ All list iterators that refer to the taken item will be set to
+ point to the new current item.
+
+ \sa remove(), clear(), current()
+*/
+
+/*!
+ \fn type *Q3PtrList::takeNode( Q3LNode *node )
+
+ Takes the \a node out of the list without deleting its item (even
+ if \link setAutoDelete() auto-deletion\endlink is enabled).
+ Returns a pointer to the item taken out of the list.
+
+ This node must exist in the list, otherwise the program may crash.
+
+ The first item in the list becomes the new current list item.
+
+ All list iterators that refer to the taken item will be set to
+ point to the item succeeding this item or to the preceding item if
+ the taken item was the last item.
+
+ \warning Do not call this function unless you are an expert.
+
+ \sa removeNode(), currentNode()
+*/
+
+/*!
+ \fn void Q3PtrList::clear()
+
+ Removes all items from the list.
+
+ The removed items are deleted if \link setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ All list iterators that access this list will be reset.
+
+ \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+ \fn int Q3PtrList::find( const type *item )
+
+ Finds the first occurrence of \a item in the list.
+
+ If the item is found, the list sets the current item to point to
+ the found item and returns the index of this item. If the item is
+ not found, the list sets the current item to 0, the current
+ index to -1, and returns -1.
+
+ The compareItems() function is called when searching for the item
+ in the list. If compareItems() is not reimplemented, it is more
+ efficient to call findRef().
+
+ \sa findNext(), findRef(), compareItems(), current()
+*/
+
+/*!
+ \fn int Q3PtrList::findNext( const type *item )
+
+ Finds the next occurrence of \a item in the list, starting from
+ the current list item.
+
+ If the item is found, the list sets the current item to point to
+ the found item and returns the index of this item. If the item is
+ not found, the list sets the current item to 0, the current
+ index to -1, and returns -1.
+
+ The compareItems() function is called when searching for the item
+ in the list. If compareItems() is not reimplemented, it is more
+ efficient to call findNextRef().
+
+ \sa find(), findNextRef(), compareItems(), current()
+*/
+
+/*!
+ \fn int Q3PtrList::findRef( const type *item )
+
+ Finds the first occurrence of \a item in the list.
+
+ If the item is found, the list sets the current item to point to
+ the found item and returns the index of this item. If the item is
+ not found, the list sets the current item to 0, the current
+ index to -1, and returns -1.
+
+ Calling this function is much faster than find() because find()
+ compares \a item with each list item using compareItems(), whereas
+ this function only compares the pointers.
+
+ \sa findNextRef(), find(), current()
+*/
+
+/*!
+ \fn int Q3PtrList::findNextRef( const type *item )
+
+ Finds the next occurrence of \a item in the list, starting from
+ the current list item.
+
+ If the item is found, the list sets the current item to point to
+ the found item and returns the index of this item. If the item is
+ not found, the list sets the current item to 0, the current
+ index to -1, and returns -1.
+
+ Calling this function is much faster than findNext() because
+ findNext() compares \a item with each list item using
+ compareItems(), whereas this function only compares the pointers.
+
+ \sa findRef(), findNext(), current()
+*/
+
+/*!
+ \fn uint Q3PtrList::contains( const type *item ) const
+
+ Returns the number of occurrences of \a item in the list.
+
+ The compareItems() function is called when looking for the \a item
+ in the list. If compareItems() is not reimplemented, it is more
+ efficient to call containsRef().
+
+ This function does not affect the current list item.
+
+ \sa containsRef(), compareItems()
+*/
+
+/*!
+ \fn uint Q3PtrList::containsRef( const type *item ) const
+
+ Returns the number of occurrences of \a item in the list.
+
+ Calling this function is much faster than contains() because
+ contains() compares \a item with each list item using
+ compareItems(), whereas his function only compares the pointers.
+
+ This function does not affect the current list item.
+
+ \sa contains()
+*/
+
+/*!
+ \fn type *Q3PtrList::at( uint index )
+
+ Returns a pointer to the item at position \a index in the list, or
+ 0 if the index is out of range.
+
+ Sets the current list item to this item if \a index is valid. The
+ valid range is \c{0..(count() - 1)} inclusive.
+
+ This function is very efficient. It starts scanning from the first
+ item, last item, or current item, whichever is closest to \a
+ index.
+
+ \sa current()
+*/
+
+/*!
+ \fn int Q3PtrList::at() const
+
+ \overload
+
+ Returns the index of the current list item. The returned value is
+ -1 if the current item is 0.
+
+ \sa current()
+*/
+
+/*!
+ \fn type *Q3PtrList::current() const
+
+ Returns a pointer to the current list item. The current item may
+ be 0 (implies that the current index is -1).
+
+ \sa at()
+*/
+
+/*!
+ \fn Q3LNode *Q3PtrList::currentNode() const
+
+ Returns a pointer to the current list node.
+
+ The node can be kept and removed later using removeNode(). The
+ advantage is that the item can be removed directly without
+ searching the list.
+
+ \warning Do not call this function unless you are an expert.
+
+ \sa removeNode(), takeNode(), current()
+*/
+
+/*!
+ \fn type *Q3PtrList::getFirst() const
+
+ Returns a pointer to the first item in the list, or 0 if the list
+ is empty.
+
+ This function does not affect the current list item.
+
+ \sa first(), getLast()
+*/
+
+/*!
+ \fn type *Q3PtrList::getLast() const
+
+ Returns a pointer to the last item in the list, or 0 if the list
+ is empty.
+
+ This function does not affect the current list item.
+
+ \sa last(), getFirst()
+*/
+
+/*!
+ \fn type *Q3PtrList::first()
+
+ Returns a pointer to the first item in the list and makes this the
+ current list item; returns 0 if the list is empty.
+
+ \sa getFirst(), last(), next(), prev(), current()
+*/
+
+/*!
+ \fn type *Q3PtrList::last()
+
+ Returns a pointer to the last item in the list and makes this the
+ current list item; returns 0 if the list is empty.
+
+ \sa getLast(), first(), next(), prev(), current()
+*/
+
+/*!
+ \fn type *Q3PtrList::next()
+
+ Returns a pointer to the item succeeding the current item. Returns
+ 0 if the current item is 0 or equal to the last item.
+
+ Makes the succeeding item current. If the current item before this
+ function call was the last item, the current item will be set to
+ 0. If the current item was 0, this function does nothing.
+
+ \sa first(), last(), prev(), current()
+*/
+
+/*!
+ \fn type *Q3PtrList::prev()
+
+ Returns a pointer to the item preceding the current item. Returns
+ 0 if the current item is 0 or equal to the first item.
+
+ Makes the preceding item current. If the current item before this
+ function call was the first item, the current item will be set to
+ 0. If the current item was 0, this function does nothing.
+
+ \sa first(), last(), next(), current()
+*/
+
+/*!
+ \fn void Q3PtrList::toVector( Q3GVector *vec ) const
+
+ Stores all list items in the vector \a vec.
+
+ The vector must be of the same item type, otherwise the result
+ will be undefined.
+*/
+
+/*!
+ \typedef Q3PtrList::iterator
+
+ \internal
+*/
+
+/*!
+ \typedef Q3PtrList::Iterator
+
+ \internal
+*/
+
+/*!
+ \typedef Q3PtrList::ConstIterator
+
+ \internal
+*/
+
+/*!
+ \typedef Q3PtrList::const_iterator
+
+ \internal
+*/
+
+/*!
+ \fn Q3PtrList::constBegin() const
+
+ \internal
+*/
+
+/*!
+ \fn Q3PtrList::constEnd() const
+
+ \internal
+*/
+
+/*!
+ \fn Q3PtrList::erase(Iterator)
+
+ \internal
+*/
+
+
+/*****************************************************************************
+ Q3PtrListIterator documentation
+ *****************************************************************************/
+
+/*!
+ \class Q3PtrListIterator
+ \brief The Q3PtrListIterator class provides an iterator for
+ Q3PtrList collections.
+ \compat
+
+ Define a template instance Q3PtrListIterator\<X\> to create a list
+ iterator that operates on Q3PtrList\<X\> (list of X*).
+
+ The following example is similar to the
+ example in the Q3PtrList class documentation,
+ but it uses Q3PtrListIterator. The class Employee is
+ defined there.
+
+ \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 3
+
+ The output is
+ \snippet doc/src/snippets/code/doc_src_q3ptrlist.qdoc 4
+
+ Using a list iterator is a more robust way of traversing the list
+ than using the Q3PtrList member functions \link Q3PtrList::first()
+ first\endlink(), \link Q3PtrList::next() next\endlink(), \link
+ Q3PtrList::current() current\endlink(), etc., as many iterators can
+ traverse the same list independently.
+
+ An iterator has its own current list item and can get the next and
+ previous list items. It doesn't modify the list in any way.
+
+ When an item is removed from the list, all iterators that point to
+ that item are updated to point to Q3PtrList::current() instead to
+ avoid dangling references.
+
+ \sa Q3PtrList
+*/
+
+/*!
+ \fn Q3PtrListIterator::Q3PtrListIterator( const Q3PtrList<type> &list )
+
+ Constructs an iterator for \a list. The current iterator item is
+ set to point on the first item in the \a list.
+*/
+
+/*!
+ \fn Q3PtrListIterator::~Q3PtrListIterator()
+
+ Destroys the iterator.
+*/
+
+/*!
+ \fn uint Q3PtrListIterator::count() const
+
+ Returns the number of items in the list this iterator operates on.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool Q3PtrListIterator::isEmpty() const
+
+ Returns TRUE if the list is empty; otherwise returns FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn bool Q3PtrListIterator::atFirst() const
+
+ Returns TRUE if the current iterator item is the first list item;
+ otherwise returns FALSE.
+
+ \sa toFirst(), atLast()
+*/
+
+/*!
+ \fn bool Q3PtrListIterator::atLast() const
+
+ Returns TRUE if the current iterator item is the last list item;
+ otherwise returns FALSE.
+
+ \sa toLast(), atFirst()
+*/
+
+/*!
+ \fn type *Q3PtrListIterator::toFirst()
+
+ Sets the current iterator item to point to the first list item and
+ returns a pointer to the item. Sets the current item to 0 and
+ returns 0 if the list is empty.
+
+ \sa toLast(), atFirst()
+*/
+
+/*!
+ \fn type *Q3PtrListIterator::toLast()
+
+ Sets the current iterator item to point to the last list item and
+ returns a pointer to the item. Sets the current item to 0 and
+ returns 0 if the list is empty.
+
+ \sa toFirst(), atLast()
+*/
+
+/*!
+ \fn Q3PtrListIterator::operator type *() const
+
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *Q3PtrListIterator::operator*()
+
+ Asterisk operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *Q3PtrListIterator::current() const
+
+ Returns a pointer to the current iterator item. If the iterator is
+ positioned before the first item in the list or after the last
+ item in the list, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3PtrListIterator::operator()()
+
+ Makes the succeeding item current and returns the original current
+ item.
+
+ If the current iterator item was the last item in the list or if
+ it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3PtrListIterator::operator++()
+
+ Prefix ++ makes the succeeding item current and returns the new
+ current item.
+
+ If the current iterator item was the last item in the list or if
+ it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3PtrListIterator::operator+=( uint jump )
+
+ Sets the current item to the item \a jump positions after the
+ current item and returns a pointer to that item.
+
+ If that item is beyond the last item or if the list is empty, it
+ sets the current item to 0 and returns 0
+*/
+
+/*!
+ \fn type *Q3PtrListIterator::operator--()
+
+ Prefix - makes the preceding item current and returns the new
+ current item.
+
+ If the current iterator item was the first item in the list or if
+ it was 0, 0 is returned.
+*/
+
+/*!
+ \fn type *Q3PtrListIterator::operator-=( uint jump )
+
+ Returns the item \a jump positions before the current item or 0
+ if it is beyond the first item. Makes this the current item.
+*/
+
+/*!
+ \fn Q3PtrListIterator<type>& Q3PtrListIterator::operator=( const Q3PtrListIterator<type> &it )
+
+ Assignment. Makes a copy of the iterator \a it and returns a
+ reference to this iterator.
+*/
+
+/*!
+ \class Q3StrList
+ \brief The Q3StrList class provides a doubly-linked list of char*.
+ \compat
+
+ If you want a string list of \l{QString}s use QStringList.
+
+ This class is a Q3PtrList\<char\> instance (a list of char*).
+
+ Q3StrList can make deep or shallow copies of the strings that are
+ inserted.
+
+ A deep copy means that memory is allocated for the string and then
+ the string data is copied into that memory. A shallow copy is just
+ a copy of the pointer value and not of the string data itself.
+
+ The disadvantage of shallow copies is that because a pointer can
+ be deleted only once, the program must put all strings in a
+ central place and know when it is safe to delete them (i.e. when
+ the strings are no longer referenced by other parts of the
+ program). This can make the program more complex. The advantage of
+ shallow copies is that they consume far less memory than deep
+ copies. It is also much faster to copy a pointer (typically 4 or 8
+ bytes) than to copy string data.
+
+ A Q3StrList that operates on deep copies will, by default, turn on
+ auto-deletion (see setAutoDelete()). Thus, by default Q3StrList
+ will deallocate any string copies it allocates.
+
+ The virtual compareItems() function is reimplemented and does a
+ case-sensitive string comparison. The inSort() function will
+ insert strings in sorted order. In general it is fastest to insert
+ the strings as they come and sort() at the end; inSort() is useful
+ when you just have to add a few extra strings to an already sorted
+ list.
+
+ The Q3StrListIterator class is an iterator for Q3StrList.
+*/
+
+/*!
+ \fn Q3StrList::operator QList<QByteArray>() const
+
+ Automatically converts a Q3StrList into a QList<QByteArray>.
+*/
+
+/*!
+ \fn Q3StrList::Q3StrList( bool deepCopies )
+
+ Constructs an empty list of strings. Will make deep copies of all
+ inserted strings if \a deepCopies is TRUE, or use shallow copies
+ if \a deepCopies is FALSE.
+*/
+
+/*!
+ \fn Q3StrList::Q3StrList(const Q3StrList &list)
+ \fn Q3StrList::Q3StrList(const QList<QByteArray> &list)
+
+ Constructs a copy of \a list.
+*/
+
+/*!
+ \fn Q3StrList::~Q3StrList()
+
+ Destroys the list. All strings are removed.
+*/
+
+/*!
+ \fn Q3StrList& Q3StrList::operator=(const Q3StrList& list)
+ \fn Q3StrList &Q3StrList::operator=(const QList<QByteArray> &list)
+
+ Assigns \a list to this list and returns a reference to this list.
+*/
+
+/*!
+ \class Q3StrIList
+ \brief The Q3StrIList class provides a doubly-linked list of char*
+ with case-insensitive comparison.
+ \compat
+
+ This class is a Q3PtrList\<char\> instance (a list of char*).
+
+ Q3StrIList is identical to Q3StrList except that the virtual
+ compareItems() function is reimplemented to compare strings
+ case-insensitively. The inSort() function inserts strings in a
+ sorted order. In general it is fastest to insert the strings as
+ they come and sort() at the end; inSort() is useful when you just
+ have to add a few extra strings to an already sorted list.
+
+ The Q3StrListIterator class works for Q3StrIList.
+
+ \sa QStringList
+*/
+
+/*!
+ \fn Q3StrIList::Q3StrIList( bool deepCopies )
+
+ Constructs a list of strings. Will make deep copies of all
+ inserted strings if \a deepCopies is TRUE, or use shallow copies
+ if \a deepCopies is FALSE.
+*/
+
+/*!
+ \fn Q3StrIList::~Q3StrIList()
+
+ Destroys the list. All strings are removed.
+*/
+
+/*!
+ \fn int Q3PtrList::compareItems( Q3PtrCollection::Item item1,
+ Q3PtrCollection::Item item2 )
+
+ This virtual function compares two list items.
+
+ Returns:
+ \list
+ \i zero if \a item1 == \a item2
+ \i nonzero if \a item1 != \a item2
+ \endlist
+
+ This function returns \e int rather than \e bool so that
+ reimplementations can return three values and use it to sort by:
+
+ \list
+ \i 0 if \a item1 == \a item2
+ \i \> 0 (positive integer) if \a item1 \> \a item2
+ \i \< 0 (negative integer) if \a item1 \< \a item2
+ \endlist
+
+ inSort() requires that compareItems() is implemented as described
+ here.
+
+ This function should not modify the list because some const
+ functions call compareItems().
+
+ The default implementation compares the pointers.
+*/
+
+/*!
+ \fn QDataStream& Q3PtrList::read( QDataStream& s,
+ Q3PtrCollection::Item& item )
+
+ Reads a list item from the stream \a s and returns a reference to
+ the stream.
+
+ The default implementation sets \a item to 0.
+
+ \sa write()
+*/
+
+/*!
+ \fn QDataStream& Q3PtrList::write( QDataStream& s,
+ Q3PtrCollection::Item item ) const
+
+ Writes a list item, \a item to the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation does nothing.
+
+ \sa read()
+*/
+
+/*! \fn iterator Q3PtrList::begin()
+\internal
+*/
+/*! \fn const_iterator Q3PtrList::begin() const
+\internal
+*/
+/*! \fn iterator Q3PtrList::end()
+\internal
+*/
+/*! \fn const_iterator Q3PtrList::end() const
+\internal
+*/
+
+/*!
+ \class Q3StrListIterator
+ \brief The Q3StrListIterator class is an iterator for the Q3StrList
+ and Q3StrIList classes.
+ \compat
+
+ This class is a Q3PtrListIterator\<char\> instance. It can traverse
+ the strings in the Q3StrList and Q3StrIList classes.
+*/
+
+
+/*
+ \class Q3PtrListAutoDelete
+ \brief The Q3PtrListAutoDelete class is a template class that provides a list that auto-deletes its data.
+ \compat
+
+ A Q3PtrListAutoDelete is identical to a Q3PtrList with
+ setAutoDelete(TRUE).
+*/
diff --git a/src/qt3support/tools/q3ptrqueue.qdoc b/src/qt3support/tools/q3ptrqueue.qdoc
new file mode 100644
index 0000000..c60193c
--- /dev/null
+++ b/src/qt3support/tools/q3ptrqueue.qdoc
@@ -0,0 +1,230 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3PtrQueue
+ \brief The Q3PtrQueue class is a template class that provides a queue.
+ \compat
+
+ Q3ValueVector can be used as an STL-compatible alternative to this
+ class.
+
+ A template instance Q3PtrQueue\<X\> is a queue that operates on
+ pointers to X (X*).
+
+ A queue is a first in, first out structure. Items are added to the
+ tail of the queue with enqueue() and retrieved from the head with
+ dequeue(). You can peek at the head item without dequeing it using
+ head().
+
+ You can control the queue's deletion policy with setAutoDelete().
+
+ For compatibility with the Q3PtrCollection classes, current() and
+ remove() are provided; both operate on the head().
+
+ \sa Q3PtrList Q3PtrStack
+*/
+
+/*!
+ \fn Q3PtrQueue::Q3PtrQueue ()
+
+ Creates an empty queue with autoDelete() set to FALSE.
+*/
+
+/*!
+ \fn Q3PtrQueue::Q3PtrQueue( const Q3PtrQueue<type>& queue )
+
+ Creates a queue from \a queue.
+
+ Only the pointers are copied; the items are not. The autoDelete()
+ flag is set to FALSE.
+*/
+
+/*!
+ \fn Q3PtrQueue::~Q3PtrQueue()
+
+ Destroys the queue. Items in the queue are deleted if autoDelete()
+ is TRUE.
+*/
+
+/*!
+ \fn Q3PtrQueue<type>& Q3PtrQueue::operator= (const Q3PtrQueue<type>& queue)
+
+ Assigns \a queue to this queue and returns a reference to this
+ queue.
+
+ This queue is first cleared and then each item in \a queue is
+ enqueued to this queue. Only the pointers are copied.
+
+ \warning The autoDelete() flag is not modified. If it is TRUE for
+ both \a queue and this queue, deleting the two lists will cause \e
+ double-deletion of the items.
+*/
+
+/*!
+ \fn bool Q3PtrQueue::isEmpty() const
+
+ Returns TRUE if the queue is empty; otherwise returns FALSE.
+
+ \sa count() dequeue() head()
+*/
+
+/*!
+ \fn void Q3PtrQueue::enqueue (const type* d)
+
+ Adds item \a d to the tail of the queue.
+
+ \sa count() dequeue()
+*/
+
+/*!
+ \fn type* Q3PtrQueue::dequeue ()
+
+ Takes the head item from the queue and returns a pointer to it.
+ Returns 0 if the queue is empty.
+
+ \sa enqueue() count()
+*/
+
+/*!
+ \fn bool Q3PtrQueue::remove()
+
+ Removes the head item from the queue, and returns TRUE if there
+ was an item, i.e. the queue wasn't empty; otherwise returns FALSE.
+
+ The item is deleted if autoDelete() is TRUE.
+
+ \sa head() isEmpty() dequeue()
+*/
+
+/*!
+ \fn void Q3PtrQueue::clear()
+
+ Removes all items from the queue, and deletes them if autoDelete()
+ is TRUE.
+
+ \sa remove()
+*/
+
+/*!
+ \fn uint Q3PtrQueue::count() const
+
+ Returns the number of items in the queue.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn type* Q3PtrQueue::head() const
+
+ Returns a pointer to the head item in the queue. The queue is not
+ changed. Returns 0 if the queue is empty.
+
+ \sa dequeue() isEmpty()
+*/
+
+/*!
+ \fn Q3PtrQueue::operator type*() const
+
+ Returns a pointer to the head item in the queue. The queue is not
+ changed. Returns 0 if the queue is empty.
+
+ \sa dequeue() isEmpty()
+*/
+
+/*!
+ \fn type* Q3PtrQueue::current() const
+
+ Returns a pointer to the head item in the queue. The queue is not
+ changed. Returns 0 if the queue is empty.
+
+ \sa dequeue() isEmpty()
+*/
+
+/*!
+ \fn bool Q3PtrQueue::autoDelete() const
+
+ Returns the setting of the auto-delete option. The default is
+ FALSE.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn void Q3PtrQueue::setAutoDelete( bool enable )
+
+ Sets the queue to auto-delete its contents if \a enable is TRUE
+ and not to delete them if \a enable is FALSE.
+
+ If auto-deleting is turned on, all the items in a queue are
+ deleted when the queue itself is deleted. This can be quite
+ convenient if the queue has the only pointer to the items.
+
+ The default setting is FALSE, for safety. If you turn it on, be
+ careful about copying the queue: you might find yourself with two
+ queues deleting the same items.
+
+ \sa autoDelete()
+*/
+
+/*!
+ \fn QDataStream& Q3PtrQueue::read( QDataStream& s,
+ Q3PtrCollection::Item& item )
+
+ Reads a queue item, \a item, from the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation sets \a item to 0.
+
+ \sa write()
+*/
+
+/*!
+ \fn QDataStream& Q3PtrQueue::write( QDataStream& s,
+ Q3PtrCollection::Item item ) const
+
+ Writes a queue item, \a item, to the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation does nothing.
+
+ \sa read()
+*/
diff --git a/src/qt3support/tools/q3ptrstack.qdoc b/src/qt3support/tools/q3ptrstack.qdoc
new file mode 100644
index 0000000..071fcd0
--- /dev/null
+++ b/src/qt3support/tools/q3ptrstack.qdoc
@@ -0,0 +1,217 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3PtrStack
+ \brief The Q3PtrStack class is a template class that provides a stack.
+ \compat
+
+ Q3ValueStack is an STL-compatible alternative to this class.
+
+ Define a template instance Q3PtrStack\<X\> to create a stack that
+ operates on pointers to X, (X*).
+
+ A stack is a last in, first out (LIFO) structure. Items are added
+ to the top of the stack with push() and retrieved from the top
+ with pop(). Use top() to get a reference to the top element
+ without changing the stack.
+
+ You can control the stack's deletion policy with setAutoDelete().
+
+ For compatibility with the Q3PtrCollection classes current() and
+ remove() are provided; they both operate on the top().
+
+ \sa Q3PtrList Q3PtrQueue
+*/
+
+/*!
+ \fn Q3PtrStack::Q3PtrStack ()
+
+ Creates an empty stack.
+*/
+
+/*!
+ \fn Q3PtrStack::Q3PtrStack (const Q3PtrStack<type>& s)
+
+ Creates a stack by making a shallow copy of another stack \a s.
+*/
+
+/*!
+ \fn Q3PtrStack::~Q3PtrStack ()
+
+ Destroys the stack. All items will be deleted if autoDelete() is
+ true.
+*/
+
+/*!
+ \fn Q3PtrStack<type>& Q3PtrStack::operator= (const Q3PtrStack<type>& s)
+
+ Sets the contents of this stack by making a shallow copy of
+ another stack \a s. Elements currently in this stack will be
+ deleted if autoDelete() is true.
+*/
+
+/*!
+ \fn bool Q3PtrStack::isEmpty () const
+
+ Returns true if the stack contains no elements; otherwise returns
+ false.
+*/
+
+/*!
+ \fn void Q3PtrStack::push (const type* d)
+
+ Adds an element \a d to the top of the stack. Last in, first out.
+*/
+
+/*!
+ \fn type* Q3PtrStack::pop ()
+
+ Removes the top item from the stack and returns it. The stack must
+ not be empty.
+*/
+
+/*!
+ \fn bool Q3PtrStack::remove ()
+
+ Removes the top item from the stack and deletes it if autoDelete()
+ is true. Returns true if there was an item to pop; otherwise
+ returns false.
+
+ \sa clear()
+*/
+
+/*!
+ \fn void Q3PtrStack::clear()
+
+ Removes all items from the stack, deleting them if autoDelete() is
+ true.
+
+ \sa remove()
+*/
+
+/*!
+ \fn uint Q3PtrStack::count() const
+
+ Returns the number of items in the stack.
+
+ \sa isEmpty()
+*/
+
+/*!
+ \fn type* Q3PtrStack::top () const
+
+ Returns a pointer to the top item on the stack (most recently
+ pushed). The stack is not changed. Returns 0 if the stack is
+ empty.
+*/
+
+/*!
+ \fn Q3PtrStack::operator type* ()const
+
+ Returns a pointer to the top item on the stack (most recently
+ pushed). The stack is not changed. Returns 0 if the stack is
+ empty.
+*/
+
+/*!
+ \fn type* Q3PtrStack::current () const
+
+ Returns a pointer to the top item on the stack (most recently
+ pushed). The stack is not changed. Returns 0 if the stack is
+ empty.
+*/
+
+/*!
+ \fn bool Q3PtrStack::autoDelete() const
+
+ The same as Q3PtrCollection::autoDelete(). Returns true if
+ the auto-delete option is set. If the option is set, the
+ stack auto-deletes its contents.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn void Q3PtrStack::setAutoDelete(bool enable)
+
+ Defines whether this stack auto-deletes its contents. The same as
+ Q3PtrCollection::setAutoDelete(). If \a enable is true, auto-delete
+ is turned on.
+
+ If auto-deleting is turned on, all the items in the stack are
+ deleted when the stack itself is deleted. This is convenient if
+ the stack has the only pointers to the items.
+
+ The default setting is false, for safety. If you turn it on, be
+ careful about copying the stack, or you might find yourself with
+ two stacks deleting the same items.
+
+ Note that the auto-delete setting may also affect other functions in
+ subclasses. For example, a subclass that has a remove() function
+ will remove the item from its data structure, and if auto-delete is
+ enabled, will also delete the item.
+
+ \sa autoDelete()
+*/
+
+/*!
+ \fn QDataStream& Q3PtrStack::read(QDataStream& s, Q3PtrCollection::Item& item)
+
+ Reads a stack item, \a item, from the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation sets \a item to 0.
+
+ \sa write()
+*/
+
+/*!
+ \fn QDataStream& Q3PtrStack::write(QDataStream& s,
+ Q3PtrCollection::Item item) const
+
+ Writes a stack item, \a item, to the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation does nothing.
+
+ \sa read()
+*/
diff --git a/src/qt3support/tools/q3ptrvector.qdoc b/src/qt3support/tools/q3ptrvector.qdoc
new file mode 100644
index 0000000..c734064
--- /dev/null
+++ b/src/qt3support/tools/q3ptrvector.qdoc
@@ -0,0 +1,427 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3PtrVector
+ \brief The Q3PtrVector class is a template collection class that
+ provides a vector (array).
+ \compat
+
+ Q3ValueVector is an STL-compatible alternative to this class.
+
+ Q3PtrVector is implemented as a template class. Defines a template
+ instance Q3PtrVector\<X\> to create a vector that contains pointers
+ to X (X*).
+
+ A vector is the same as an array. The main difference between
+ Q3PtrVector and Q3MemArray is that Q3PtrVector stores pointers to the
+ elements, whereas Q3MemArray stores the elements themselves (i.e.
+ Q3MemArray is value-based and Q3PtrVector is pointer-based).
+
+ Items are added to the vector using insert() or fill(). Items are
+ removed with remove(). You can get a pointer to an item at a
+ particular index position using at().
+
+ Unless otherwise stated, all functions that remove items from the
+ vector will also delete the element pointed to if \link
+ setAutoDelete() auto-deletion\endlink is enabled. By default,
+ auto-deletion is disabled; see setAutoDelete(). This behavior can
+ be changed in a subclass by reimplementing the virtual function
+ deleteItem().
+
+ Functions that compare items (find() and sort() for example) will
+ do so using the virtual function compareItems(). The default
+ implementation of this function only compares the pointer values.
+ Reimplement compareItems() in a subclass to get searching and
+ sorting based on the item contents. You can perform a linear
+ search for a pointer in the vector using findRef(), or a binary
+ search (of a sorted vector) using bsearch(). You can count the
+ number of times an item appears in the vector with contains() or
+ containsRef().
+
+ \sa Q3MemArray
+*/
+
+/*!
+ \fn Q3PtrVector::Q3PtrVector()
+
+ Constructs a null vector.
+
+ \sa isNull()
+*/
+
+/*!
+ \fn Q3PtrVector::Q3PtrVector(uint size)
+
+ Constructs an vector with room for \a size items. Makes a null
+ vector if \a size == 0.
+
+ All \a size positions in the vector are initialized to 0.
+
+ \sa size(), resize(), isNull()
+*/
+
+/*!
+ \fn Q3PtrVector::Q3PtrVector(const Q3PtrVector<type> &v)
+
+ Constructs a copy of \a v. Only the pointers are copied (i.e.
+ shallow copy).
+*/
+
+/*!
+ \fn Q3PtrVector::~Q3PtrVector()
+
+ Removes all items from the vector, and destroys the vector itself.
+
+ \sa clear()
+*/
+
+/*!
+ \fn Q3PtrVector<type> &Q3PtrVector::operator=(const Q3PtrVector<type> &v)
+
+ Assigns \a v to this vector and returns a reference to this
+ vector.
+
+ This vector is first cleared and then all the items from \a v are
+ copied into the vector. Only the pointers are copied (i.e. shallow
+ copy).
+
+ \sa clear()
+*/
+
+/*!
+ \fn type **Q3PtrVector::data() const
+
+ Returns a pointer to the actual vector data, which is an array of
+ type*.
+
+ The vector is a null vector if data() == 0 (null pointer).
+
+ \sa isNull()
+*/
+
+/*!
+ \fn uint Q3PtrVector::size() const
+
+ Returns the size of the vector, i.e. the number of vector
+ positions. This is also the maximum number of items the vector can
+ hold.
+
+ The vector is a null vector if size() == 0.
+
+ \sa isNull(), resize(), count()
+*/
+
+/*!
+ \fn uint Q3PtrVector::count() const
+
+ Returns the number of items in the vector. The vector is empty if
+ count() == 0.
+
+ \sa isEmpty(), size(), isNull()
+*/
+
+/*!
+ \fn bool Q3PtrVector::isEmpty() const
+
+ Returns true if the vector is empty; otherwise returns false.
+
+ \sa count()
+*/
+
+/*!
+ \fn bool Q3PtrVector::isNull() const
+
+ Returns true if the vector is null; otherwise returns false.
+
+ A null vector has size() == 0 and data() == 0.
+
+ \sa size()
+*/
+
+/*!
+ \fn bool Q3PtrVector::resize(uint size)
+
+ Resizes (expands or shrinks) the vector to \a size elements. The
+ vector becomes a null vector if \a size == 0.
+
+ Any items at position \a size or beyond in the vector are removed.
+ New positions are initialized to 0.
+
+ Returns true if successful, i.e. if the memory was successfully
+ allocated; otherwise returns false.
+
+ \sa size(), isNull()
+*/
+
+/*!
+ \fn bool Q3PtrVector::insert(uint i, const type *d)
+
+ Sets position \a i in the vector to contain the item \a d. \a i
+ must be less than size(). Any previous element in position \a i is
+ removed.
+
+ Returns true if \a i is within range; otherwise returns false.
+
+ \sa at()
+*/
+
+/*!
+ \fn bool Q3PtrVector::remove(uint i)
+
+ Removes the item at position \a i in the vector, if there is one.
+ \a i must be less than size().
+
+ Returns true if \a i is within range; otherwise returns false.
+
+ \sa take(), at()
+*/
+
+/*!
+ \fn type* Q3PtrVector::take(uint i)
+
+ Returns the item at position \a i in the vector, and removes that
+ item from the vector. \a i must be less than size(). If there is
+ no item at position \a i, 0 is returned.
+
+ Unlike remove(), this function does \e not call deleteItem() for
+ the removed item.
+
+ \sa remove(), at()
+*/
+
+/*!
+ \fn void Q3PtrVector::clear()
+
+ Removes all items from the vector, and destroys the vector itself.
+
+ The vector becomes a null vector.
+
+ \sa isNull()
+*/
+
+/*!
+ \fn bool Q3PtrVector::fill(const type *d, int size)
+
+ Inserts item \a d in all positions in the vector. Any existing
+ items are removed. If \a d is 0, the vector becomes empty.
+
+ If \a size >= 0, the vector is first resized to \a size. By
+ default, \a size is -1.
+
+ Returns true if successful, i.e. \a size is the same as the
+ current size, or \a size is larger and the memory has successfully
+ been allocated; otherwise returns false.
+
+ \sa resize(), insert(), isEmpty()
+*/
+
+/*!
+ \fn void Q3PtrVector::sort()
+
+ Sorts the items in ascending order. Any empty positions will be
+ put last.
+
+ Compares items using the virtual function compareItems().
+
+ \sa bsearch()
+*/
+
+/*!
+ \fn int Q3PtrVector::bsearch(const type* d) const
+
+ In a sorted array, finds the first occurrence of \a d using a
+ binary search. For a sorted array, this is generally much faster
+ than find(), which performs a linear search.
+
+ Returns the position of \a d, or -1 if \a d could not be found. \a
+ d must not be 0.
+
+ Compares items using the virtual function compareItems().
+
+ \sa sort(), find()
+*/
+
+
+/*!
+ \fn int Q3PtrVector::findRef(const type *d, uint i) const
+
+ Finds the first occurrence of the item pointer \a d in the vector
+ using a linear search. The search starts at position \a i, which
+ must be less than size(). \a i is by default 0; i.e. the search
+ starts at the start of the vector.
+
+ Returns the position of \a d, or -1 if \a d could not be found.
+
+ This function does \e not use compareItems() to compare items.
+
+ Use the much faster bsearch() to search a sorted vector.
+
+ \sa find(), bsearch()
+*/
+
+/*!
+ \fn int Q3PtrVector::find(const type *d, uint i) const
+
+ Finds the first occurrence of item \a d in the vector using a
+ linear search. The search starts at position \a i, which must be
+ less than size(). \a i is by default 0; i.e. the search starts at
+ the start of the vector.
+
+ Returns the position of \a d, or -1 if \a d could not be found.
+
+ Compares items using the virtual function compareItems().
+
+ Use the much faster bsearch() to search a sorted vector.
+
+ \sa findRef(), bsearch()
+*/
+
+
+/*!
+ \fn uint Q3PtrVector::containsRef(const type *d) const
+
+ Returns the number of occurrences of the item pointer \a d in the
+ vector.
+
+ This function does \e not use compareItems() to compare items.
+
+ \sa findRef()
+*/
+
+/*!
+ \fn uint Q3PtrVector::contains(const type *d) const
+
+ Returns the number of occurrences of item \a d in the vector.
+
+ Compares items using the virtual function compareItems().
+
+ \sa containsRef()
+*/
+
+/*!
+ \fn type *Q3PtrVector::operator[](int i) const
+
+ Returns the item at position \a i, or 0 if there is no item at
+ that position. \a i must be less than size().
+
+ Equivalent to at(\a i).
+
+ \sa at()
+*/
+
+/*!
+ \fn type *Q3PtrVector::at(uint i) const
+
+ Returns the item at position \a i, or 0 if there is no item at
+ that position. \a i must be less than size().
+*/
+
+
+/*!
+ \fn void Q3PtrVector::toList(Q3GList *list) const
+
+ \internal
+
+ Copies all items in this vector to the list \a list. \a list is
+ first cleared and then all items are appended to \a list.
+
+ \sa Q3PtrList, Q3PtrStack, Q3PtrQueue
+*/
+
+/*!
+ \fn int Q3PtrVector::compareItems(Q3PtrCollection::Item d1,
+ Q3PtrCollection::Item d2)
+
+ This virtual function compares two list items.
+
+ Returns:
+ \list
+ \i zero if \a d1 == \a d2
+ \i nonzero if \a d1 != \a d2
+ \endlist
+
+ This function returns \e int rather than \e bool so that
+ reimplementations can return one of three values and use it to
+ sort by:
+ \list
+ \i 0 if \a d1 == \a d2
+ \i \> 0 (positive integer) if \a d1 \> \a d2
+ \i \< 0 (negative integer) if \a d1 \< \a d2
+ \endlist
+
+ The sort() and bsearch() functions require compareItems() to be
+ implemented as described here.
+
+ This function should not modify the vector because some const
+ functions call compareItems().
+*/
+
+/*!
+ \fn QDataStream& Q3PtrVector::read(QDataStream &s,
+ Q3PtrCollection::Item &item)
+
+ Reads a vector item, \a item, from the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation sets \a item to 0.
+
+ \sa write()
+*/
+
+/*!
+ \fn QDataStream& Q3PtrVector::write(QDataStream &s,
+ Q3PtrCollection::Item item) const
+
+ Writes a vector item, \a item, to the stream \a s and returns a
+ reference to the stream.
+
+ The default implementation does nothing.
+
+ \sa read()
+*/
+
+/*!
+ \fn bool Q3PtrVector::operator==(const Q3PtrVector<type> &v) const
+
+ Returns true if this vector and \a v are equal; otherwise returns
+ false.
+*/
diff --git a/src/qt3support/tools/q3valuelist.qdoc b/src/qt3support/tools/q3valuelist.qdoc
new file mode 100644
index 0000000..062a9da
--- /dev/null
+++ b/src/qt3support/tools/q3valuelist.qdoc
@@ -0,0 +1,569 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3ValueList
+ \brief The Q3ValueList class is a value-based template class that
+ provides lists.
+ \compat
+
+ Q3ValueList is a Qt implementation of an STL-like list container.
+ It can be used in your application if the standard \c list is not
+ available for your target platforms.
+
+ Q3ValueList\<T\> defines a template instance to create a list of
+ values that all have the class T. Note that Q3ValueList does not
+ store pointers to the members of the list; it holds a copy of
+ every member. This is why these kinds of classes are called "value
+ based"; Q3PtrList and Q3Dict are "pointer based".
+
+ Q3ValueList contains and manages a collection of objects of type T
+ and provides iterators that allow the contained objects to be
+ addressed. Q3ValueList owns the contained items. For more relaxed
+ ownership semantics, see Q3PtrCollection and friends which are
+ pointer-based containers.
+
+ Some classes cannot be used within a Q3ValueList, for example, all
+ classes derived from QObject and thus all classes that implement
+ widgets. Only values can be used in a Q3ValueList. To qualify as a
+ value the class must provide:
+ \list
+ \i a copy constructor;
+ \i an assignment operator;
+ \i a default constructor, i.e. a constructor that does not take any arguments.
+ \endlist
+
+ Note that C++ defaults to field-by-field assignment operators and
+ copy constructors if no explicit version is supplied. In many
+ cases this is sufficient.
+
+ In addition, some compilers (e.g. Sun CC) might require that the
+ class provides an equality operator (operator==()).
+
+ Q3ValueList's function naming is consistent with the other Qt
+ classes (e.g. count(), isEmpty()). Q3ValueList also provides extra
+ functions for compatibility with STL algorithms, such as size()
+ and empty(). Programmers already familiar with the STL \c list may
+ prefer to use the STL-compatible functions.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 0
+
+
+ Notice that the latest changes to Mary's salary did not affect the
+ value in the list because the list created a copy of Mary's entry.
+
+ There are several ways to find items in the list. The begin() and
+ end() functions return iterators to the beginning and end of the
+ list. The advantage of getting an iterator is that you can move
+ forward or backward from this position by
+ incrementing/decrementing the iterator. The iterator returned by
+ end() points to the item which is one \e past the last item in the
+ container. The past-the-end iterator is still associated with the
+ list it belongs to, however it is \e not dereferenceable;
+ operator*() will not return a well-defined value. If the list is
+ empty(), the iterator returned by begin() will equal the iterator
+ returned by end().
+
+ It is safe to have multiple iterators a the list at the same
+ time. If some member of the list is removed, only iterators
+ pointing to the removed member become invalid. Inserting into the
+ list does not invalidate any iterator. For convenience, the
+ function last() returns a reference to the last item in the list,
+ and first() returns a reference to the first item. If the
+ list is empty(), both last() and first() have undefined behavior
+ (your application will crash or do unpredictable things). Use
+ last() and first() with caution, for example:
+
+ \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 1
+
+ Because Q3ValueList is value-based there is no need to be careful
+ about deleting items in the list. The list holds its own copies
+ and will free them if the corresponding member or the list itself
+ is deleted. You can force the list to free all of its items with
+ clear().
+
+ Q3ValueList is shared implicitly, which means it can be copied in
+ constant time, i.e. O(1). If multiple Q3ValueList instances share
+ the same data and one needs to modify its contents, this modifying
+ instance makes a copy and modifies its private copy; therefore it
+ does not affect the other instances; this takes O(n) time. This is
+ often called "copy on write". If a Q3ValueList is being used in a
+ multi-threaded program, you must protect all access to the list.
+ See \l QMutex.
+
+ There are several ways to insert items into the list. The
+ prepend() and append() functions insert items at the beginning and
+ the end of the list respectively. The insert() function comes in
+ several flavors and can be used to add one or more items at
+ specific positions within the list.
+
+ Items can also be removed from the list in several ways. There
+ are several variants of the remove() function, which removes a
+ specific item from the list. The remove() function will find and
+ remove items according to a specific item value.
+
+ \sa Q3ValueListIterator
+*/
+
+/*! \typedef Q3ValueList::iterator
+ The list's iterator type, Q3ValueListIterator. */
+/*! \typedef Q3ValueList::const_iterator
+ The list's const iterator type, Q3ValueListConstIterator. */
+/*! \typedef Q3ValueList::value_type
+ The type of the object stored in the list, T. */
+/*! \typedef Q3ValueList::pointer
+ The pointer to T type. */
+/*! \typedef Q3ValueList::const_pointer
+ The const pointer to T type. */
+/*! \typedef Q3ValueList::reference
+ The reference to T type. */
+/*! \typedef Q3ValueList::const_reference
+ The const reference to T type. */
+/*! \typedef Q3ValueList::size_type
+ An unsigned integral type, used to represent various sizes. */
+/*! \typedef Q3ValueList::difference_type
+ \internal
+*/
+/*!
+ \fn Q3ValueList::Q3ValueList()
+
+ Constructs an empty list.
+*/
+
+/*!
+ \fn Q3ValueList::Q3ValueList( const Q3ValueList<T>& l )
+ \fn Q3ValueList::Q3ValueList( const QList<T>& l )
+ \fn Q3ValueList::Q3ValueList( const QLinkedList<T>& l )
+
+ Constructs a copy of \a l.
+*/
+
+/*!
+ \fn Q3ValueList::Q3ValueList( const std::list<T>& l )
+
+ Contructs a copy of \a l.
+
+ This constructor is provided for compatibility with STL
+ containers.
+*/
+
+/*!
+ \fn Q3ValueList::~Q3ValueList()
+
+ Destroys the list. References to the values in the list and all
+ iterators of this list become invalidated. Note that it is
+ impossible for an iterator to check whether or not it is valid:
+ Q3ValueList is highly tuned for performance, not for error
+ checking.
+*/
+
+/*!
+ \fn bool Q3ValueList::operator== ( const Q3ValueList<T>& l ) const
+
+ Compares both lists.
+
+ Returns TRUE if this list and \a l are equal; otherwise returns
+ FALSE.
+*/
+
+/*!
+ \fn bool Q3ValueList::operator== ( const std::list<T>& l ) const
+
+ \overload
+
+ Returns TRUE if this list and \a l are equal; otherwise returns
+ FALSE.
+
+ This operator is provided for compatibility with STL containers.
+*/
+
+/*!
+ \fn Q3ValueList<T>& Q3ValueList::operator= ( const Q3ValueList<T>& l )
+
+ Assigns \a l to this list and returns a reference to this list.
+
+ All iterators of the current list become invalidated by this
+ operation. The cost of such an assignment is O(1) since Q3ValueList
+ is implicitly shared.
+*/
+
+/*!
+ \fn Q3ValueList<T>& Q3ValueList::operator= ( const QList<T>& l )
+
+ Assigns \a l to this list and returns a reference to this list.
+
+ All iterators of the current list become invalidated by this
+ operation.
+*/
+
+/*!
+ \fn Q3ValueList<T>& Q3ValueList::operator= ( const std::list<T>& l )
+
+ \overload
+
+ Assigns the contents of \a l to the list.
+
+ All iterators of the current list become invalidated by this
+ operation.
+*/
+
+/*!
+ \fn bool Q3ValueList::operator!= ( const Q3ValueList<T>& l ) const
+
+ Compares both lists.
+
+ Returns TRUE if this list and \a l are unequal; otherwise returns
+ FALSE.
+*/
+
+/*!
+ \fn iterator Q3ValueList::insert( typename Q3ValueList<T>::Iterator it, const T& x )
+
+ Inserts the value \a x in front of the item pointed to by the
+ iterator, \a it.
+
+ Returns an iterator pointing at the inserted item.
+
+ \sa append(), prepend()
+*/
+
+/*!
+ \fn uint Q3ValueList::remove( const T& x )
+
+ \overload
+
+ Removes all items that have value \a x and returns the number of
+ removed items.
+*/
+
+/*!
+ \fn QDataStream& operator>>( QDataStream& s, Q3ValueList<T>& l )
+
+ \relates Q3ValueList
+
+ Reads a list, \a l, from the stream \a s. The type T stored in the
+ list must implement the streaming operator.
+*/
+
+/*!
+ \fn QDataStream& operator<<( QDataStream& s, const Q3ValueList<T>& l )
+
+ \overload
+ \relates Q3ValueList
+
+ Writes a list, \a l, to the stream \a s. The type T stored in the
+ list must implement the streaming operator.
+*/
+
+/*!
+ \fn void Q3ValueList::insert( typename Q3ValueList<T>::Iterator pos,
+ typename Q3ValueList<T>::size_type n, const T& x )
+
+ \overload
+
+ Inserts \a n copies of \a x before position \a pos.
+*/
+
+/*!
+ \fn Q3ValueList<T>& Q3ValueList::operator<< ( const T& x )
+
+ Adds the value \a x to the end of the list.
+
+ Returns a reference to the list.
+*/
+
+/*!
+ \fn const T& Q3ValueList::operator[] ( typename Q3ValueList<T>::size_type i ) const
+
+ Returns a const reference to the item with index \a i in the list.
+ It is up to you to check whether this item really exists. You can
+ do that easily with the count() function. However this operator
+ does not check whether \a i is in range and will deliver undefined
+ results if it does not exist.
+
+ \warning This function uses a linear search and can be extremely
+ slow for large lists. Q3ValueList is not optimized for random item
+ access. If you need random access use a different container, such
+ as Q3ValueVector.
+*/
+
+/*!
+ \fn T& Q3ValueList::operator[] ( typename Q3ValueList<T>::size_type i )
+
+ \overload
+
+ Returns a non-const reference to the item with index \a i.
+*/
+
+/*!
+ \fn const_iterator Q3ValueList::at( typename Q3ValueList<T>::size_type i ) const
+
+ Returns an iterator pointing to the item at position \a i in the
+ list, or an undefined value if the index is out of range.
+
+ \warning This function uses a linear search and can be extremely
+ slow for large lists. Q3ValueList is not optimized for random item
+ access. If you need random access use a different container, such
+ as Q3ValueVector.
+*/
+
+/*!
+ \fn iterator Q3ValueList::at( typename Q3ValueList<T>::size_type i )
+
+ \overload
+
+ Returns an iterator pointing to the item at position \a i in the
+ list, or an undefined value if the index is out of range.
+
+*/
+
+/*!
+ \fn iterator Q3ValueList::fromLast()
+
+ \overload
+
+ Returns an iterator to the last item in the list, or end() if
+ there is no last item.
+
+ Use the end() function instead. For example:
+
+ \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 2
+
+*/
+
+/*!
+ \fn const_iterator Q3ValueList::fromLast() const
+
+ Returns an iterator to the last item in the list, or end() if
+ there is no last item.
+
+ Use the end() function instead. For example:
+
+ \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 3
+
+*/
+
+/*!
+ \fn Q3ValueList<T> Q3ValueList::operator+( const Q3ValueList<T>& l ) const
+
+ Creates a new list and fills it with the items of this list. Then
+ the items of \a l are appended. Returns the new list.
+*/
+
+/*!
+ \fn Q3ValueList<T>& Q3ValueList::operator+= ( const Q3ValueList<T>& l )
+
+ Appends the items of \a l to this list. Returns a reference to
+ this list.
+*/
+
+/*!
+ \fn Q3ValueList<T>& Q3ValueList::operator+= ( const T& x )
+
+ \overload
+
+ Appends the value \a x to the list. Returns a reference to the
+ list.
+*/
+
+/*!
+ \fn iterator Q3ValueList::append( const T& x )
+
+ Inserts \a x at the end of the list.
+
+ \sa insert(), prepend()
+*/
+
+/*!
+ \fn iterator Q3ValueList::prepend( const T& x )
+
+ Inserts \a x at the beginning of the list.
+
+ \sa insert(), append()
+*/
+
+/*!
+ \fn iterator Q3ValueList::remove( typename Q3ValueList<T>::Iterator it )
+
+ Removes the item pointed to by \a it from the list. No iterators
+ other than \a it or other iterators pointing at the same item as
+ \a it are invalidated. Returns an iterator to the next item after
+ \a it, or end() if there is no such item.
+
+ \sa clear()
+*/
+
+/*!
+ \fn uint Q3ValueList::contains( const T& x ) const
+
+ Returns the number of occurrences of the value \a x in the list.
+*/
+
+/*!
+ \class Q3ValueListIterator
+ \brief The Q3ValueListIterator class provides an iterator for Q3ValueList.
+ \compat
+
+ An iterator is a class for accessing the items of a container
+ class: a generalization of the index in an array. A pointer
+ into a "const char *" and an index into an "int[]" are both
+ iterators, and the general idea is to provide that functionality
+ for any data structure.
+
+ The Q3ValueListIterator class is an iterator for Q3ValueList
+ instantiations. You can create the appropriate iterator type by
+ using the \c iterator typedef provided by Q3ValueList.
+
+ The only way to access the items in a Q3ValueList is to use an
+ iterator.
+
+ Example (see Q3ValueList for the complete code):
+ \snippet doc/src/snippets/code/doc_src_q3valuelist.qdoc 4
+
+ Q3ValueList is highly optimized for performance and memory usage.
+ This means that you must be careful: Q3ValueList does not know
+ about all its iterators and the iterators don't know to which list
+ they belong. This makes things very fast, but if you're not
+ careful, you can get spectacular bugs. Always make sure iterators
+ are valid before dereferencing them or using them as parameters to
+ generic algorithms in the STL.
+
+ Using an invalid iterator is undefined (your application will
+ probably crash). Many Qt functions return const value lists; to
+ iterate over these you should make a copy and iterate over the
+ copy.
+
+ For every Iterator there is a ConstIterator. When accessing a
+ Q3ValueList in a const environment or if the reference or pointer
+ to the list is itself const, then you must use the ConstIterator.
+ Its semantics are the same as the Iterator, but it only returns
+ const references.
+
+ \sa Q3ValueList, Q3ValueListConstIterator
+*/
+
+/*!
+ \fn Q3ValueListIterator::Q3ValueListIterator()
+
+ Constructs an unitialized iterator.
+*/
+
+/*!
+ \fn Q3ValueListIterator::Q3ValueListIterator(const Q3ValueListIterator &o)
+ \fn Q3ValueListIterator::Q3ValueListIterator(const typename QLinkedList<T>::iterator &o)
+
+ Constucts a copy of iterator \a o.
+*/
+
+/*!
+ \class Q3ValueListConstIterator
+ \brief The Q3ValueListConstIterator class provides a const iterator
+ for Q3ValueList.
+ \compat
+
+ In contrast to Q3ValueListIterator, this class is used to iterate
+ over a const list. It does not allow modification of the values of
+ the list since that would break const semantics.
+
+ You can create the appropriate const iterator type by using the \c
+ const_iterator typedef provided by Q3ValueList.
+
+ For more information on Q3ValueList iterators, see
+ Q3ValueListIterator.
+
+ \sa Q3ValueListIterator, Q3ValueList
+*/
+
+/*!
+ \fn Q3ValueListConstIterator::Q3ValueListConstIterator()
+
+ Constructs an unitialized iterator.
+*/
+
+/*!
+ \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const Q3ValueListConstIterator &o)
+ \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList<T>::const_iterator &o)
+ \fn Q3ValueListConstIterator::Q3ValueListConstIterator(const typename QLinkedList<T>::iterator &o)
+
+ Constructs a copy of iterator \a o.
+*/
+
+/*!
+ \typedef Q3ValueList::Iterator
+
+ This iterator is an instantiation of Q3ValueListIterator for the
+ same type as this Q3ValueList. In other words, if you instantiate
+ Q3ValueList<int>, Iterator is a Q3ValueListIterator<int>. Several
+ member function use it, such as Q3ValueList::begin(), which returns
+ an iterator pointing to the first item in the list.
+
+ Functionally, this is almost the same as ConstIterator. The only
+ difference is that you cannot use ConstIterator for non-const
+ operations, and that the compiler can often generate better code
+ if you use ConstIterator.
+
+ \sa Q3ValueListIterator ConstIterator
+*/
+
+/*!
+ \typedef Q3ValueList::ConstIterator
+
+ This iterator is an instantiation of Q3ValueListConstIterator for
+ the same type as this Q3ValueList. In other words, if you
+ instantiate Q3ValueList<int>, ConstIterator is a
+ Q3ValueListConstIterator<int>. Several member function use it, such
+ as Q3ValueList::begin(), which returns an iterator pointing to the
+ first item in the list.
+
+ Functionally, this is almost the same as Iterator. The only
+ difference is you cannot use ConstIterator for non-const
+ operations, and that the compiler can often generate better code
+ if you use ConstIterator.
+
+ \sa Q3ValueListIterator Iterator
+*/
+
+/*!
+ \fn Q3ValueList::operator QList<T>() const
+
+ Automatically converts a Q3ValueList<T> into a QList<T>.
+*/
diff --git a/src/qt3support/tools/q3valuestack.qdoc b/src/qt3support/tools/q3valuestack.qdoc
new file mode 100644
index 0000000..bc44235
--- /dev/null
+++ b/src/qt3support/tools/q3valuestack.qdoc
@@ -0,0 +1,149 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3ValueStack
+ \brief The Q3ValueStack class is a value-based template class that provides a stack.
+ \compat
+
+ Define a template instance Q3ValueStack\<X\> to create a stack of
+ values that all have the class X.
+
+ Note that Q3ValueStack does not store pointers to the members of
+ the stack; it holds a copy of every member. That is why these
+ kinds of classes are called "value based"; Q3PtrStack, Q3PtrList,
+ Q3Dict, etc., are "pointer based".
+
+ A stack is a last in, first out (LIFO) structure. Items are added
+ to the top of the stack with push() and retrieved from the top
+ with pop(). The top() function provides access to the topmost item
+ without removing it.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3valuestack.qdoc 0
+
+ Q3ValueStack is a specialized Q3ValueList provided for convenience.
+ All of Q3ValueList's functionality also applies to Q3PtrStack, for
+ example the facility to iterate over all elements using
+ Q3ValueStack<T>::Iterator. See Q3ValueListIterator for further
+ details.
+
+ Some classes cannot be used within a Q3ValueStack, for example
+ everything derived from QObject and thus all classes that
+ implement widgets. Only values can be used in a Q3ValueStack. To
+ qualify as a value, the class must provide
+ \list
+ \i a copy constructor;
+ \i an assignment operator;
+ \i a default constructor, i.e. a constructor that does not take any arguments.
+ \endlist
+
+ Note that C++ defaults to field-by-field assignment operators and
+ copy constructors if no explicit version is supplied. In many
+ cases this is sufficient.
+*/
+
+
+/*!
+ \fn Q3ValueStack::Q3ValueStack()
+
+ Constructs an empty stack.
+*/
+
+/*!
+ \fn Q3ValueStack::~Q3ValueStack()
+
+ Destroys the stack. References to the values in the stack and all
+ iterators of this stack become invalidated. Because Q3ValueStack is
+ highly tuned for performance, you won't see warnings if you use
+ invalid iterators because it is impossible for an iterator to
+ check whether or not it is valid.
+*/
+
+
+/*!
+ \fn void Q3ValueStack::push( const T& d )
+
+ Adds element, \a d, to the top of the stack. Last in, first out.
+
+ This function is equivalent to append().
+
+ \sa pop(), top()
+*/
+
+/*!
+ \fn T& Q3ValueStack::top()
+
+ Returns a reference to the top item of the stack or the item
+ referenced by end() if no such item exists. Note that you must not
+ change the value the end() iterator points to.
+
+ This function is equivalent to last().
+
+ \sa pop(), push(), Q3ValueList::fromLast()
+*/
+
+
+/*!
+ \fn const T& Q3ValueStack::top() const
+
+ \overload
+
+ Returns a reference to the top item of the stack or the item
+ referenced by end() if no such item exists.
+
+ This function is equivalent to last().
+
+ \sa pop(), push(), Q3ValueList::fromLast()
+*/
+
+/*!
+ \fn T Q3ValueStack::pop()
+
+ Removes the top item from the stack and returns it.
+
+ \sa top() push()
+*/
+
+
+
+
+
diff --git a/src/qt3support/tools/q3valuevector.qdoc b/src/qt3support/tools/q3valuevector.qdoc
new file mode 100644
index 0000000..4ab8896
--- /dev/null
+++ b/src/qt3support/tools/q3valuevector.qdoc
@@ -0,0 +1,274 @@
+/****************************************************************************
+**
+** 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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at http://qt.nokia.com/contact.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \class Q3ValueVector
+ \brief The Q3ValueVector class is a value-based template class that provides a dynamic array.
+ \compat
+
+ Q3ValueVector is a Qt implementation of an STL-like vector
+ container. It can be used in your application if the standard \c
+ vector is not available for your target platforms.
+
+ Q3ValueVector\<T\> defines a template instance to create a vector
+ of values that all have the class T. Q3ValueVector does not store
+ pointers to the members of the vector; it holds a copy of every
+ member. Q3ValueVector is said to be value based; in contrast,
+ Q3PtrList and Q3Dict are pointer based.
+
+ Q3ValueVector contains and manages a collection of objects of type
+ T and provides random access iterators that allow the contained
+ objects to be addressed. Q3ValueVector owns the contained
+ elements. For more relaxed ownership semantics, see Q3PtrCollection
+ and friends, which are pointer-based containers.
+
+ Q3ValueVector provides good performance if you append or remove
+ elements from the end of the vector. If you insert or remove
+ elements from anywhere but the end, performance is very bad. The
+ reason for this is that elements must to be copied into new
+ positions.
+
+ Some classes cannot be used within a Q3ValueVector: for example,
+ all classes derived from QObject and thus all classes that
+ implement widgets. Only values can be used in a Q3ValueVector. To
+ qualify as a value the class must provide:
+ \list
+ \i a copy constructor;
+ \i an assignment operator;
+ \i a default constructor, i.e., a constructor that does not take any arguments.
+ \endlist
+
+ Note that C++ defaults to field-by-field assignment operators and
+ copy constructors if no explicit version is supplied. In many
+ cases this is sufficient.
+
+ Q3ValueVector uses an STL-like syntax to manipulate and address the
+ objects it contains.
+
+ Example:
+ \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 0
+
+ Program output:
+ \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 1
+
+ As you can see, the most recent change to Joe's salary did not
+ affect the value in the vector because the vector created a copy
+ of Joe's entry.
+
+ Many Qt functions return const value vectors; to iterate over
+ these you should make a copy and iterate over the copy.
+
+ There are several ways to find items in the vector. The begin()
+ and end() functions return iterators to the beginning and end of
+ the vector. The advantage of getting an iterator is that you can
+ move forward or backward from this position by
+ incrementing/decrementing the iterator. The iterator returned by
+ end() points to the element which is one past the last element in
+ the container. The past-the-end iterator is still associated with
+ the vector it belongs to, however it is \e not dereferenceable;
+ operator*() will not return a well-defined value. If the vector is
+ empty(), the iterator returned by begin() will equal the iterator
+ returned by end().
+
+ The fastest way to access an element of a vector is by using
+ operator[]. This function provides random access and will return
+ a reference to the element located at the specified index. Thus,
+ you can access every element directly, in constant time, providing
+ you know the location of the element. It is undefined to access
+ an element that does not exist (your application will probably
+ crash). For example:
+
+ \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 2
+
+ Whenever inserting, removing or referencing elements in a vector,
+ always make sure you are referring to valid positions. For
+ example:
+
+ \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 3
+
+ The iterators provided by vector are random access iterators,
+ therefore you can use them with many generic algorithms, for
+ example, algorithms provided by the STL.
+
+ It is safe to have multiple iterators on the vector at the same
+ time. Since Q3ValueVector manages memory dynamically, all iterators
+ can become invalid if a memory reallocation occurs. For example,
+ if some member of the vector is removed, iterators that point to
+ the removed element and to all following elements become
+ invalidated. Inserting into the middle of the vector will
+ invalidate all iterators. For convenience, the function back()
+ returns a reference to the last element in the vector, and front()
+ returns a reference to the first element. If the vector is
+ empty(), both back() and front() have undefined behavior (your
+ application will crash or do unpredictable things). Use back() and
+ front() with caution, for example:
+
+ \snippet doc/src/snippets/code/doc_src_q3valuevector.qdoc 4
+
+ Because Q3ValueVector manages memory dynamically, it is recommended
+ that you contruct a vector with an initial size. Inserting and
+ removing elements happens fastest when:
+ \list
+ \i Inserting or removing elements happens at the end() of the
+ vector;
+ \i The vector does not need to allocate additional memory.
+ \endlist
+
+ By creating a Q3ValueVector with a sufficiently large initial size,
+ there will be less memory allocations. Do not use an initial size
+ that is too big, since it will still take time to construct all
+ the empty entries, and the extra space will be wasted if it is
+ never used.
+
+ Because Q3ValueVector is value-based there is no need to be careful
+ about deleting elements in the vector. The vector holds its own
+ copies and will free them if the corresponding member or the
+ vector itself is deleted. You can force the vector to free all of
+ its items with clear().
+
+ Q3ValueVector is shared implicitly, which means it can be copied in
+ constant time. If multiple Q3ValueVector instances share the same
+ data and one needs to modify its contents, this modifying instance
+ makes a copy and modifies its private copy; it thus does not
+ affect the other instances. This is often called "copy on write".
+ If a Q3ValueVector is being used in a multi-threaded program, you
+ must protect all access to the vector. See QMutex.
+
+ There are several ways to insert elements into the vector. The
+ push_back() function insert elements into the end of the vector,
+ and is usually fastest. The insert() function can be used to add
+ elements at specific positions within the vector.
+
+ Items can be also be removed from the vector in several ways.
+ There are several variants of the erase() function which removes a
+ specific element, or range of elements, from the vector.
+
+ Q3ValueVector stores its elements in contiguous memory. This means
+ that you can use a Q3ValueVector in any situation that requires an
+ array.
+*/
+
+/*!
+ \fn Q3ValueVector::Q3ValueVector()
+
+ Constructs an empty vector without any elements. To create a
+ vector which reserves an initial amount of space for elements, use
+ \c Q3ValueVector(size_type n).
+*/
+
+/*!
+ \fn Q3ValueVector::Q3ValueVector( const Q3ValueVector<T>& v )
+
+ Constructs a copy of \a v.
+
+ This operation costs O(1) time because Q3ValueVector is implicitly
+ shared.
+
+ The first modification to the vector does takes O(n) time, because
+ the elements must be copied.
+*/
+
+/*!
+ \fn Q3ValueVector::Q3ValueVector( const std::vector<T>& v )
+
+ This operation costs O(n) time because \a v is copied.
+*/
+
+/*!
+ \fn Q3ValueVector::Q3ValueVector( QVector<T>::size_type n, const T& val )
+
+ Constructs a vector with an initial size of \a n elements. Each
+ element is initialized with the value of \a val.
+*/
+
+/*!
+ \fn Q3ValueVector<T>& Q3ValueVector::operator=( const Q3ValueVector<T>& v )
+
+ Assigns \a v to this vector and returns a reference to this vector.
+
+ All iterators of the current vector become invalidated by this
+ operation. The cost of such an assignment is O(1) since
+ Q3ValueVector is implicitly shared.
+*/
+
+/*!
+ \fn Q3ValueVector<T>& Q3ValueVector::operator=( const std::vector<T>& v )
+
+ \overload
+
+ Assigns \a v to this vector and returns a reference to this vector.
+
+ All iterators of the current vector become invalidated by this
+ operation. The cost of this assignment is O(n) since \a v is
+ copied.
+*/
+
+/*!
+ \fn T &Q3ValueVector::at( int i , bool* ok )
+
+ Returns a reference to the element with index \a i. If \a ok is
+ non-null, and the index \a i is out of range, *\a ok is set to
+ FALSE and the returned reference is undefined. If the index \a i
+ is within the range of the vector, and \a ok is non-null, *\a ok
+ is set to TRUE and the returned reference is well defined.
+*/
+
+/*!
+ \fn const T &Q3ValueVector::at( int i , bool* ok ) const
+
+ \overload
+
+ Returns a const reference to the element with index \a i. If \a ok
+ is non-null, and the index \a i is out of range, *\a ok is set to
+ FALSE and the returned reference is undefined. If the index \a i
+ is within the range of the vector, and \a ok is non-null, *\a ok
+ is set to TRUE and the returned reference is well defined.
+*/
+
+/*!
+ \fn void Q3ValueVector::resize( int n, const T& val = T() )
+
+ Changes the size of the vector to \a n. If \a n is greater than
+ the current size(), elements are added to the end and initialized
+ with the value of \a val. If \a n is less than size(), elements
+ are removed from the end. If \a n is equal to size() nothing
+ happens.
+*/