summaryrefslogtreecommitdiffstats
path: root/qtools
diff options
context:
space:
mode:
authordimitri <dimitri@afe2bf4a-e733-0410-8a33-86f594647bc7>2001-10-21 18:02:53 (GMT)
committerdimitri <dimitri@afe2bf4a-e733-0410-8a33-86f594647bc7>2001-10-21 18:02:53 (GMT)
commitaa58eb72e74a736d7f05328466858ac179918649 (patch)
treef5aef68ee03709376658e93142ca5df6850e649d /qtools
parent4f13c95eed55e8b0d989f2eeeb0ab72bd70f2b38 (diff)
downloadDoxygen-aa58eb72e74a736d7f05328466858ac179918649.zip
Doxygen-aa58eb72e74a736d7f05328466858ac179918649.tar.gz
Doxygen-aa58eb72e74a736d7f05328466858ac179918649.tar.bz2
Release-1.2.11-20011021
Diffstat (limited to 'qtools')
-rw-r--r--qtools/Doxyfile19
-rw-r--r--qtools/qarray.doc486
-rw-r--r--qtools/qdict.doc492
-rw-r--r--qtools/qintdict.doc475
-rw-r--r--qtools/qlist.doc1048
-rw-r--r--qtools/qptrdict.doc486
-rw-r--r--qtools/qsortedlist.doc94
-rw-r--r--qtools/qstack.doc135
-rw-r--r--qtools/qstrlist.doc5
-rw-r--r--qtools/qtl.doc249
-rw-r--r--qtools/qvaluelist.doc772
-rw-r--r--qtools/qvector.doc344
12 files changed, 4590 insertions, 15 deletions
diff --git a/qtools/Doxyfile b/qtools/Doxyfile
index 8a54cc9..838a299 100644
--- a/qtools/Doxyfile
+++ b/qtools/Doxyfile
@@ -51,21 +51,10 @@ WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
-INPUT = . \
- $(QTDIR)/src/doc/qarray.doc \
- $(QTDIR)/src/doc/qdict.doc \
- $(QTDIR)/src/doc/qintdict.doc \
- $(QTDIR)/src/doc/qlist.doc \
- $(QTDIR)/src/doc/qptrdict.doc \
- $(QTDIR)/src/doc/qsortedlist.doc \
- $(QTDIR)/src/doc/qstack.doc \
- $(QTDIR)/src/doc/qstrlist.doc \
- $(QTDIR)/src/doc/qvector.doc \
- $(QTDIR)/src/doc/qvaluelist.doc \
- $(QTDIR)/src/doc/qtl.doc
+INPUT = .
FILE_PATTERNS = *.h \
*.cpp \
- q*.doc
+ *.doc
RECURSIVE = NO
EXCLUDE_PATTERNS =
EXAMPLE_PATH =
@@ -77,8 +66,8 @@ FILTER_SOURCE_FILES = NO
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
ALPHABETICAL_INDEX = YES
-COLS_IN_ALPHA_INDEX = 5
-IGNORE_PREFIX =
+COLS_IN_ALPHA_INDEX = 4
+IGNORE_PREFIX = Q
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
diff --git a/qtools/qarray.doc b/qtools/qarray.doc
new file mode 100644
index 0000000..d5a606e
--- /dev/null
+++ b/qtools/qarray.doc
@@ -0,0 +1,486 @@
+/****************************************************************************
+** $Id$
+**
+** QArray class documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+ QArray documentation
+ *****************************************************************************/
+
+/*!
+ \class QArray qarray.h
+ \brief The QArray class is a template class that provides arrays of simple types.
+
+ \ingroup tools
+
+ QArray is implemented as a template class. Define a template
+ instance QArray\<X\> to create an array that contains X items.
+
+ QArray 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. QArray uses
+ bitwise operations to copy and compare array elements.
+
+ The QVector collection class is also a kind of array. Like most
+ \link collection.html collection classes\endlink, it has pointers to the
+ contained items.
+
+ QArray uses explicit \link shclass.html sharing\endlink with a reference
+ count. If more than one array share common data, and one array is
+ modified, all arrays will be modified.
+
+ The benefit of sharing is that a program does not need to duplicate
+ data when it is not required, which results in less memory usage and
+ less copying of data.
+
+ Example:
+ \code
+ #include <qarray.h>
+ #include <stdio.h>
+
+ QArray<int> fib( int num ) // returns fibonacci array
+ {
+ ASSERT( num > 2 );
+ QArray<int> f( num ); // array of ints
+
+ f[0] = f[1] = 1; // initialize first two numbers
+ for ( int i=2; i<num; i++ )
+ f[i] = f[i-1] + f[i-2];
+
+ return f;
+ }
+
+ void main()
+ {
+ QArray<int> a = fib( 6 ); // get 6 first fibonaccis
+ int i;
+
+ for ( i=0; i<a.size(); i++ ) // print them
+ prinf( "%d: %d\n", i, a[i] );
+
+ printf( "1 is found %d time(s)\n", a.contains(1) );
+ printf( "5 is found at index %d\n", a.find(5) );
+ }
+ \endcode
+
+ Program output:
+ \code
+ 0: 1
+ 1: 1
+ 2: 2
+ 3: 3
+ 4: 5
+ 5: 8
+ 1 is found 2 times
+ 5 is found at index 4
+ \endcode
+
+ Note about using QArray 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 QArray will use
+ for its bitwise element comparisons. Since the remaining bytes will
+ typically be uninitialized, this can cause find() etc. to fail to
+ find the element. Example:
+
+ \code
+ struct MyStruct
+ {
+ short i; // 2 bytes
+ char c; // 1 byte
+ }; // sizeof(MyStruct) may be padded to 4 bytes
+
+ QArray<MyStruct> a(1);
+ a[0].i = 5;
+ a[0].c = 't';
+
+ MyStruct x;
+ x.i = '5';
+ x.c = 't';
+ int i = a.find( x ); // May return -1 if the pad bytes differ
+ \endcode
+
+ To workaround 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.
+
+ \sa \link shclass.html Shared Classes\endlink
+*/
+
+
+/*!
+ \fn QArray::QArray()
+ Constructs a null array.
+ \sa isNull()
+*/
+
+/*!
+ \fn QArray::QArray( int size )
+ Constructs an array with room for \e size elements.
+ Makes a null array if \e size == 0.
+
+ Note that the elements are not initialized.
+
+ \sa resize(), isNull()
+*/
+
+/*!
+ \fn QArray::QArray( const QArray<type> &a )
+ Constructs a shallow copy of \e a.
+ \sa assign()
+*/
+
+/*!
+ \fn QArray::QArray( int, int )
+ Constructs an array <em>without allocating</em> array space.
+ The arguments should be (0, 0). Use at own risk.
+*/
+
+/*!
+ \fn QArray::~QArray()
+ Dereferences the array data and deletes it if this was the last
+ reference.
+*/
+
+/*!
+ \fn QArray<type> &QArray::operator=( const QArray<type> &a )
+ Assigns a shallow copy of \e a to this array and returns a reference
+ to this array.
+
+ Equivalent to assign( a ).
+*/
+
+/*!
+ \fn type *QArray::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 QArray::nrefs() const
+ Returns the reference count for the shared array data. This reference count
+ is always greater than zero.
+*/
+
+/*!
+ \fn uint QArray::size() const
+ Returns the size of the array (max number of elements).
+
+ The array is a null array if size() == 0.
+
+ \sa isNull(), resize()
+*/
+
+/*!
+ \fn uint QArray::count() const
+ Returns the same as size().
+
+ \sa size()
+*/
+
+/*!
+ \fn bool QArray::isEmpty() const
+ Returns TRUE if the array is empty, i.e. size() == 0, otherwise FALSE.
+
+ isEmpty() is equivalent with isNull() for QArray. Note that this is not
+ the case for QCString::isEmpty().
+*/
+
+/*!
+ \fn bool QArray::isNull() const
+ Returns TRUE if the array is null, otherwise FALSE.
+
+ A null array has size() == 0 and data() == 0.
+*/
+
+/*!
+ \fn bool QArray::resize( uint size )
+ Resizes (expands or shrinks) the array to \e size elements. The array
+ becomes a null array if \e size == 0.
+
+ Returns TRUE if successful, or FALSE if the memory cannot be allocated.
+
+ New elements will not be initialized.
+
+ \sa size()
+*/
+
+/*!
+ \fn bool QArray::truncate( uint pos )
+ Truncates the array at position \e pos.
+
+ Returns TRUE if successful, or FALSE if the memory cannot be allocated.
+
+ Equivalent to resize(\e pos).
+
+ \sa resize()
+*/
+
+/*!
+ \fn bool QArray::fill( const type &v, int size )
+ Fills the array with the value \e v. If \e size is specified as different
+ from -1, then the array will be resized before filled.
+
+ Returns TRUE if successful, or FALSE if the memory cannot be allocated
+ (only when \e size != -1).
+
+ \sa resize()
+*/
+
+/*!
+ \fn void QArray::detach()
+ Detaches this array from shared array data, i.e. makes a private, deep
+ copy of the data.
+
+ Copying will only be performed if the
+ \link nrefs() reference count\endlink is greater than one.
+
+ \sa copy()
+*/
+
+/*!
+ \fn QArray<type> QArray::copy() const
+ Returns a deep copy of this array.
+ \sa detach(), duplicate()
+*/
+
+/*!
+ \fn QArray<type> &QArray::assign( const QArray<type> &a )
+ Shallow copy. Dereferences the current array and references the data
+ contained in \e a instead. Returns a reference to this array.
+ \sa operator=()
+*/
+
+/*!
+ \fn QArray<type> &QArray::assign( const type *data, uint size )
+ Shallow copy. Dereferences the current array and references the
+ array data \e data, which contains \e size elements.
+ Returns a reference to this array.
+
+ Do not delete \e data later, QArray takes care of that.
+*/
+
+/*!
+ \fn QArray<type> &QArray::duplicate( const QArray<type> &a )
+ Deep copy. Dereferences the current array and obtains a copy of the data
+ contained in \e a instead. Returns a reference to this array.
+ \sa copy()
+*/
+
+/*!
+ \fn QArray<type> &QArray::duplicate( const type *data, uint size )
+ Deep copy. Dereferences the current array and obtains a copy of the
+ array data \e data instead. Returns a reference to this array.
+ \sa copy()
+*/
+
+/*!
+ \fn QArray<type> &QArray::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 \e data and
+ the new array size to \e size. Do not attempt to resize or re-assign the
+ array data when raw data has been set.
+ Call resetRawData(d,len) to reset the array.
+
+ Setting raw data is useful because it sets QArray data without allocating
+ memory or copying data.
+
+ Example I (intended use):
+ \code
+ static char bindata[] = { 231, 1, 44, ... };
+ QByteArray a;
+ a.setRawData( bindata, sizeof(bindata) ); // a points to bindata
+ QDataStream s( a, IO_ReadOnly ); // open on a's data
+ s >> <something>; // read raw bindata
+ a.resetRawData( bindata, sizeof(bindata) ); // finished
+ \endcode
+
+ Example II (you don't want to do this):
+ \code
+ static char bindata[] = { 231, 1, 44, ... };
+ QByteArray a, b;
+ a.setRawData( bindata, sizeof(bindata) ); // a points to bindata
+ a.resize( 8 ); // will crash
+ b = a; // will crash
+ a[2] = 123; // might crash
+ // forget to resetRawData - will crash
+ \endcode
+
+ \warning If you do not call resetRawData(), QArray will attempt to
+ deallocate or reallocate the raw data, which might not be too good.
+ Be careful.
+
+ \sa resetRawData()
+*/
+
+/*!
+ \fn void QArray::resetRawData( const type *data, uint size )
+ Resets raw data that was set using setRawData().
+
+ The arguments must be the data and length that were passed to
+ setRawData(). This is for consistency checking.
+
+ \sa setRawData()
+*/
+
+/*!
+ \fn int QArray::find( const type &v, uint index ) const
+ Finds the first occurrence of \e v, starting at position \e index.
+
+ Returns the position of \e v, or -1 if \e v could not be found.
+
+ \sa contains()
+*/
+
+/*!
+ \fn int QArray::contains( const type &v ) const
+ Returns the number of times \e v occurs in the array.
+ \sa find()
+*/
+
+/*!
+ \fn void QArray::sort()
+ Sorts the array elements in ascending order, using bitwise
+ comparison (memcmp()).
+
+ \sa bsearch()
+*/
+
+/*!
+ \fn int QArray::bsearch( const type &v ) const
+ In a sorted array, finds the first occurrence of \e v using binary
+ search. For a sorted array, this is generally much faster than
+ find(), which does a linear search.
+
+ Returns the position of \e v, or -1 if \e v could not be found.
+
+ \sa sort(), find()
+*/
+
+/*!
+ \fn type &QArray::operator[]( int index ) const
+ Returns a reference to the element at position \e index in the array.
+
+ This can be used to both read and set an element. Equivalent to at().
+
+ \sa at()
+*/
+
+/*!
+ \fn type &QArray::at( uint index ) const
+ Returns a reference to the element at position \e index in the array.
+
+ This can be used to both read and set an element.
+
+ \sa operator[]()
+*/
+
+/*!
+ \fn QArray::operator const type *() const
+ Cast operator. Returns a pointer to the array.
+ \sa data()
+*/
+
+/*!
+ \fn bool QArray::operator==( const QArray<type> &a ) const
+ Returns TRUE if this array is equal to \e a, otherwise FALSE.
+
+ The two arrays are bitwise compared.
+
+ \sa operator!=()
+*/
+
+/*!
+ \fn bool QArray::operator!=( const QArray<type> &a ) const
+ Returns TRUE if this array is different from \e a, otherwise FALSE.
+
+ The two arrays are bitwise compared.
+
+ \sa operator==()
+*/
+
+/*!
+ \fn Iterator QArray::begin()
+ Returns an iterator pointing at the beginning of this array.
+ This iterator can be used as the iterators of QValueList and QMap
+ for example. In fact it does not only behave like a usual pointer:
+ It is a pointer.
+*/
+
+/*!
+ \fn Iterator QArray::end()
+ Returns an iterator pointing behind the last element of this array.
+ This iterator can be used as the iterators of QValueList and QMap
+ for example. In fact it does not only behave like a usual pointer:
+ It is a pointer.
+*/
+
+/*!
+ \fn ConstIterator QArray::begin() const
+ Returns a const iterator pointing at the beginning of this array.
+ This iterator can be used as the iterators of QValueList and QMap
+ for example. In fact it does not only behave like a usual pointer:
+ It is a pointer.
+*/
+
+/*!
+ \fn ConstIterator QArray::end() const
+ Returns a const iterator pointing behind the last element of this array.
+ This iterator can be used as the iterators of QValueList and QMap
+ for example. In fact it does not only behave like a usual pointer:
+ It is a pointer.
+*/
+
+
+/*****************************************************************************
+ QByteArray documentation
+ *****************************************************************************/
+
+/*!
+ \class QByteArray qcstring.h
+ \brief The QByteArray class provides an array of bytes.
+
+ \inherit QArray
+
+ \ingroup tools
+
+ The QByteArray class provides an explicitly shared array of
+ bytes. It is useful for manipulating memory areas with custom
+ data. QByteArray is implemented as QArray<char>. See the QArray
+ documentation for further information.
+*/
diff --git a/qtools/qdict.doc b/qtools/qdict.doc
new file mode 100644
index 0000000..4472a3c
--- /dev/null
+++ b/qtools/qdict.doc
@@ -0,0 +1,492 @@
+/****************************************************************************
+** $Id$
+**
+** QDict and QDictIterator class documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+ QDict documentation
+ *****************************************************************************/
+
+/*!
+ \class QDict qdict.h
+ \brief The QDict class is a template class that provides a dictionary based on \c QString keys.
+
+ \ingroup collection
+ \ingroup tools
+
+ QDict is implemented as a template class. Define a template instance
+ QDict\<X\> to create a dictionary that operates on pointers to X, or X*.
+
+ A dictionary is a collection that associates an item with a key.
+ The key is used for inserting and looking up an item. QDict has
+ \l QString keys, which are Unicode strings. If you want to use
+ non-Unicode, plain 8-bit \c char* keys, use the QAsciiDict template.
+ A QDict has the same performace as a QAsciiDict.
+
+ The dictionary has very fast insertion and lookup.
+
+ Example:
+ \code
+ #include <qdict.h>
+ #include <stdio.h>
+
+ void main()
+ {
+ // Creates a dictionary that maps QString ==> char* (case insensitive)
+ QDict<char> dict( 17, FALSE );
+
+ dict.insert( "France", "Paris" );
+ dict.insert( "Russia", "Moscow" );
+ dict.insert( "Norway", "Oslo" );
+
+ printf( "%s\n", dict["Norway"] );
+ printf( "%s\n", dict["FRANCE"] );
+ printf( "%s\n", dict["russia"] );
+
+ if ( !dict["Italy"] )
+ printf( "Italy not defined\n" );
+ }
+ \endcode
+
+ Program output:
+ \code
+ Oslo
+ Paris
+ Moscow
+ Italy not defined
+ \endcode
+
+ The dictionary in our example maps \c QString keys to \c char* items.
+ Note that the mapping is case insensitive (specified in the
+ \link QDict::QDict() constructor\endlink).
+ QDict implements the \link operator[] [] operator\endlink to lookup an item.
+
+ QDict is implemented by QGDict as a hash array with a fixed number of
+ entries. Each array entry points to a singly linked list of buckets, in
+ which the dictionary items are stored.
+
+ When an item is inserted with a key, the key is converted (hashed) to
+ an integer index into the hash array. The item is inserted before the
+ first bucket in the list of buckets.
+
+ Looking up an item is normally very fast. The key is again hashed to an
+ array index. Then QDict scans the list of buckets and returns the item
+ found or null if the item was not found. You cannot insert null pointers
+ into a dictionary.
+
+ The size of the hash array is very important. In order to get good
+ performance, you should use a suitably large \link primes.html prime
+ number\endlink. Suitable means equal to or larger than the maximum
+ expected number of dictionary items.
+
+ Items with equal keys are allowed. When inserting two items with the
+ same key, only the last inserted item will be visible (last in, first out)
+ until it is removed.
+
+ Example:
+ \code
+ #include <qdict.h>
+ #include <stdio.h>
+
+ void main()
+ {
+ // Creates a dictionary that maps QString ==> char* (case sensitive)
+ QDict<char> dict;
+
+ dict.insert( "Germany", "Berlin" );
+ dict.insert( "Germany", "Bonn" );
+
+ printf( "%s\n", dict["Germany"] );
+ dict.remove( "Germany" ); // Oct 3rd 1990
+ printf( "%s\n", dict["Germany"] );
+ }
+ \endcode
+
+ Program output:
+ \code
+ Bonn
+ Berlin
+ \endcode
+
+ The QDictIterator class can traverse the dictionary contents, but only
+ in an arbitrary order. Multiple iterators may independently traverse the
+ same dictionary.
+
+ Calling setAutoDelete(TRUE) for a dictionary tells it to delete items
+ that are removed . The default is to not delete items when they are
+ removed.
+
+ When inserting an item into a dictionary, only the pointer is copied, not
+ the item itself. This is called a shallow copy. It is possible to make the
+ dictionary copy all of the item's data (known as a deep copy) when an
+ item is inserted. insert() calls the virtual function
+ QCollection::newItem() for the item to be inserted.
+ Inherit a dictionary and reimplement it if you want deep copies.
+
+ When removing a dictionary item, the virtual function
+ QCollection::deleteItem() is called. QDict's default implementation
+ is to delete the item if auto-deletion is enabled.
+
+ \sa QDictIterator, QAsciiDict, QIntDict, QPtrDict,
+ \link collection.html Collection Classes\endlink
+*/
+
+
+/*!
+ \fn QDict::QDict( int size, bool caseSensitive )
+ Constructs a dictionary with the following properties:
+ \arg \e size is the size of the internal hash array.
+ \arg \e caseSensitive specifies whether to use case sensitive lookup or not.
+
+ Setting \e size to a suitably large \link primes.html prime
+ number\endlink (equal to or greater than the expected number of entries)
+ makes the hash distribution better and hence the loopup faster.
+
+ Setting \e caseSensitive to TRUE will treat "abc" and "Abc" as different
+ keys. Setting it to FALSE will make the dictionary ignore case.
+ Case insensitive comparison includes the whole Unicode alphabeth.
+*/
+
+/*!
+ \fn QDict::QDict( const QDict<type> &dict )
+ Constructs a copy of \e dict.
+
+ Each item in \e dict are inserted into this dictionary.
+ Only the pointers are copied (shallow copy).
+*/
+
+/*!
+ \fn QDict::~QDict()
+ Removes all items from the dictionary and destroys it.
+ All iterators that access this dictionary will be reset.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn QDict<type> &QDict::operator=(const QDict<type> &dict)
+ Assigns \e dict to this dictionary and returns a reference to this
+ dictionary.
+
+ This dictionary is first cleared, then each item in \e dict is inserted
+ into this dictionary.
+ Only the pointers are copied (shallow copy), unless newItem() has been
+ reimplemented().
+*/
+
+/*!
+ \fn uint QDict::count() const
+ Returns the number of items in the dictionary.
+ \sa isEmpty()
+*/
+
+/*!
+ \fn uint QDict::size() const
+ Returns the size of the internal hash array (as specified in the
+ constructor).
+ \sa count()
+*/
+
+/*!
+ \fn void QDict::resize( uint newsize )
+ Changes the size of the hashtable the \a newsize.
+ The contents of the dictionary are preserved,
+ but all iterators on the dictionary become invalid.
+*/
+
+/*!
+ \fn bool QDict::isEmpty() const
+ Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE
+ otherwise.
+ \sa count()
+*/
+
+/*!
+ \fn void QDict::insert( const QString &key, const type *item )
+
+ Inserts the \e key with the \e item into the dictionary.
+
+ The key does not have to be a unique dictionary key. If multiple items
+ are inserted with the same key, only the last item will be visible.
+
+ Null items are not allowed.
+
+ \sa replace()
+*/
+
+/*!
+ \fn void QDict::replace( const QString &key, const type *item )
+
+ Replaces an item which has a key equal to \e key with \e item.
+
+ If the item does not already exist, it will be inserted.
+
+ Null items are not allowed.
+
+ Equivalent to:
+ \code
+ QDict<char> dict;
+ ...
+ if ( dict.find(key) )
+ dict.remove( key );
+ dict.insert( key, item );
+ \endcode
+
+ If there are two or more items with equal keys, then the last inserted
+ of these will be replaced.
+
+ \sa insert()
+*/
+
+/*!
+ \fn bool QDict::remove( const QString &key )
+
+ Removes the item associated with \e key from the dictionary.
+ Returns TRUE if successful, or FALSE if the key does not exist in the
+ dictionary.
+
+ If there are two or more items with equal keys, then the last inserted
+ of these will be removed.
+
+ The removed item is deleted if \link QCollection::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 traversing order.
+
+ \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn type *QDict::take( const QString &key )
+
+ Takes the item associated with \e key out of the dictionary without
+ deleting it (even if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled).
+
+ If there are two or more items with equal keys, then the last inserted
+ of these will be taken.
+
+ Returns a pointer to the item taken out, or null 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 QDict::clear()
+
+ Removes all items from the dictionary.
+
+ The removed items are deleted if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ All dictionary iterators that operate on dictionary are reset.
+
+ \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+ \fn type *QDict::find( const QString &key ) const
+
+ Returns the item associated with \e key, or null 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 last inserted
+ of these will be found.
+
+ Equivalent to the [] operator.
+
+ \sa operator[]()
+*/
+
+/*!
+ \fn type *QDict::operator[]( const QString &key ) const
+
+ Returns the item associated with \e key, or null 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 last inserted
+ of these will be found.
+
+ Equivalent to the find() function.
+
+ \sa find()
+*/
+
+/*!
+ \fn void QDict::statistics() const
+ Debugging-only function that prints out the dictionary distribution
+ using qDebug().
+*/
+
+
+/*****************************************************************************
+ QDictIterator documentation
+ *****************************************************************************/
+
+/*!
+ \class QDictIterator qdict.h
+ \brief The QDictIterator class provides an iterator for QDict collections.
+
+ \ingroup collection
+ \ingroup tools
+
+ QDictIterator is implemented as a template class.
+ Define a template instance QDictIterator\<X\> to create a
+ dictionary iterator that operates on QDict\<X\> (dictionary of X*).
+
+ Example:
+ \code
+ #include <qdict.h>
+ #include <stdio.h>
+
+ void main()
+ {
+ // Creates a dictionary that maps QString ==> char* (case insensitive)
+ QDict<char> dict( 17, FALSE );
+
+ dict.insert( "France", "Paris" );
+ dict.insert( "Russia", "Moscow" );
+ dict.insert( "Norway", "Oslo" );
+
+ QDictIterator<char> it( dict ); // iterator for dict
+
+ while ( it.current() ) {
+ printf( "%s -> %s\n", it.currentKey().latin1(), it.current() );
+ ++it;
+ }
+ }
+ \endcode
+
+ Program output:
+ \code
+ Russia -> Moscow
+ Norway -> Oslo
+ France -> Paris
+ \endcode
+
+ Note that the traversal order is arbitrary, you are not guaranteed the
+ order above.
+
+ Multiple iterators may independently traverse the same dictionary.
+ A QDict knows about all iterators that are operating on the dictionary.
+ When an item is removed from the dictionary, QDict update all iterators
+ that are referring the removed item to point to the next item in the
+ traversing order.
+
+ \sa QDict, \link collection.html Collection Classes\endlink
+*/
+
+/*!
+ \fn QDictIterator::QDictIterator( const QDict<type> &dict )
+ Constructs an iterator for \e dict. The current iterator item is
+ set to point on the first item in the \e dict.
+*/
+
+/*!
+ \fn QDictIterator::~QDictIterator()
+ Destroys the iterator.
+*/
+
+/*!
+ \fn uint QDictIterator::count() const
+ Returns the number of items in the dictionary this iterator operates on.
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool QDictIterator::isEmpty() const
+ Returns TRUE if the dictionary is empty, i.e. count() == 0, otherwise FALSE.
+ \sa count()
+*/
+
+/*!
+ \fn type *QDictIterator::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 null and
+ returns null.
+*/
+
+/*!
+ \fn QDictIterator::operator type *() const
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *QDictIterator::current() const
+ Returns a pointer to the current iterator item.
+*/
+
+/*!
+ \fn QString QDictIterator::currentKey() const
+ Returns a pointer to the key for the current iterator item.
+*/
+
+/*!
+ \fn type *QDictIterator::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 null, null is returned.
+*/
+
+/*!
+ \fn type *QDictIterator::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 null, null is returned.
+*/
+
+/*!
+ \fn type *QDictIterator::operator+=( uint jump )
+ Sets the current item to the item \e 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 null and returns null.
+*/
+
+
diff --git a/qtools/qintdict.doc b/qtools/qintdict.doc
new file mode 100644
index 0000000..0a77398
--- /dev/null
+++ b/qtools/qintdict.doc
@@ -0,0 +1,475 @@
+/****************************************************************************
+** $Id$
+**
+** QIntDict and QIntDictIterator class documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+ QIntDict documentation
+ *****************************************************************************/
+
+/*!
+ \class QIntDict qintdict.h
+ \brief The QIntDict class is a template class that provides a dictionary based on \c long keys.
+
+ \ingroup collection
+ \ingroup tools
+
+ QIntDict is implemented as a template class. Define a
+ template instance QIntDict\<X\> to create a dictionary that operates on
+ pointers to X, or X*.
+
+ A dictionary is a collection that associates an item with a key.
+ The key is used for inserting and looking up an item. QIntDict has
+ \c long keys.
+
+ The dictionary has very fast insertion and lookup.
+
+ Example:
+ \code
+ #include <qintdict.h>
+ #include <stdio.h>
+
+ void main()
+ {
+ QIntDict<char> dict; // maps long ==> char*
+
+ dict.insert( 33, "France" );
+ dict.insert( 7, "Russia" );
+ dict.insert( 49, "Norway" );
+
+ printf( "%s\n", dict[49] );
+ printf( "%s\n", dict[33] );
+ printf( "%s\n", dict[7] );
+
+ if ( !dict[39] )
+ printf( "39 not defined\n" );
+ }
+ \endcode
+
+ Program output:
+ \code
+ Norway
+ France
+ Russia
+ 39 not defined
+ \endcode
+
+ The dictionary in our example maps \c long keys to \c char* items.
+ QIntDict implements the \link operator[] [] operator\endlink to lookup
+ an item.
+
+ QIntDict is implemented by QGDict as a hash array with a fixed number of
+ entries. Each array entry points to a singly linked list of buckets, in
+ which the dictionary items are stored.
+
+ When an item is inserted with a key, the key is converted (hashed) to
+ an integer index into the hash array using the \c mod operation. The
+ item is inserted before the first bucket in the list of buckets.
+
+ Looking up an item is normally very fast. The key is again hashed to an
+ array index. Then QIntDict scans the list of buckets and returns the item
+ found or null if the item was not found. You cannot insert null pointers
+ into a dictionary.
+
+ The size of the hash array is very important. In order to get good
+ performance, you should use a suitably large \link primes.html prime
+ number\endlink. Suitable means equal to or larger than the maximum
+ expected number of dictionary items.
+
+ Items with equal keys are allowed. When inserting two items with the
+ same key, only the last inserted item will be visible (last in, first out)
+ until it is removed.
+
+ Example:
+ \code
+ #include <qintdict.h>
+ #include <stdio.h>
+
+ void main()
+ {
+ QIntDict<char> dict; // maps long ==> char*
+
+ dict.insert( 7, "Russia" );
+ dict.insert( 7, "USSR" );
+
+ printf( "%s\n", dict[7] );
+ dict.remove( 7 ); // Gorbie was here
+ printf( "%s\n", dict[7] );
+ }
+ \endcode
+
+ Program output:
+ \code
+ USSR
+ Russia
+ \endcode
+
+ The QIntDictIterator class can traverse the dictionary contents, but only
+ in an arbitrary order. Multiple iterators may independently traverse the
+ same dictionary.
+
+ Calling setAutoDelete(TRUE) for a dictionary tells it to delete items
+ that are removed . The default is to not delete items when they are
+ removed.
+
+ When inserting an item into a dictionary, only the pointer is copied, not
+ the item itself. This is called a shallow copy. It is possible to make the
+ dictionary copy all of the item's data (known as a deep copy) when an
+ item is inserted. insert() calls the virtual function
+ QCollection::newItem() for the item to be inserted.
+ Inherit a dictionary and reimplement it if you want deep copies.
+
+ When removing a dictionary item, the virtual function
+ QCollection::deleteItem() is called. QIntDict's default implementation
+ is to delete the item if auto-deletion is enabled.
+
+ \sa QIntDictIterator, QDict, QAsciiDict, QPtrDict,
+ \link collection.html Collection Classes\endlink
+*/
+
+
+/*!
+ \fn QIntDict::QIntDict( int size )
+ Constructs a dictionary using an internal hash array with the size
+ \e size.
+
+ Setting \e size to a suitably large \link primes.html prime number\endlink
+ (equal to or greater than the expected number of entries) makes the hash
+ distribution better and hence the loopup faster.
+*/
+
+/*!
+ \fn QIntDict::QIntDict( const QIntDict<type> &dict )
+ Constructs a copy of \e dict.
+
+ Each item in \e dict are inserted into this dictionary.
+ Only the pointers are copied (shallow copy).
+*/
+
+/*!
+ \fn QIntDict::~QIntDict()
+ Removes all items from the dictionary and destroys it.
+
+ All iterators that access this dictionary will be reset.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn QIntDict<type> &QIntDict::operator=(const QIntDict<type> &dict)
+ Assigns \e dict to this dictionary and returns a reference to this
+ dictionary.
+
+ This dictionary is first cleared, then each item in \e dict is inserted
+ into this dictionary.
+ Only the pointers are copied (shallow copy), unless newItem() has been
+ reimplemented.
+*/
+
+/*!
+ \fn uint QIntDict::count() const
+ Returns the number of items in the dictionary.
+ \sa isEmpty()
+*/
+
+/*!
+ \fn uint QIntDict::size() const
+ Returns the size of the internal hash array (as specified in the
+ constructor).
+ \sa count()
+*/
+
+/*!
+ \fn void QIntDict::resize( uint newsize )
+ Changes the size of the hashtable the \a newsize.
+ The contents of the dictionary are preserved,
+ but all iterators on the dictionary become invalid.
+*/
+
+/*!
+ \fn bool QIntDict::isEmpty() const
+ Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE
+ otherwise.
+ \sa count()
+*/
+
+/*!
+ \fn void QIntDict::insert( long key, const type *item )
+ Inserts the \e key with the \e item into the dictionary.
+
+ The key does not have to be a unique dictionary key. If multiple items
+ are inserted with the same key, only the last item will be visible.
+
+ Null items are not allowed.
+
+ \sa replace()
+*/
+
+/*!
+ \fn void QIntDict::replace( long key, const type *item )
+ Replaces an item which has a key equal to \e key with \e item.
+
+ If the item does not already exist, it will be inserted.
+
+ Null items are not allowed.
+
+ Equivalent to:
+ \code
+ QIntDict<char> dict;
+ ...
+ if ( dict.find(key) )
+ dict.remove( key );
+ dict.insert( key, item );
+ \endcode
+
+ If there are two or more items with equal keys, then the last inserted
+ of these will be replaced.
+
+ \sa insert()
+*/
+
+/*!
+ \fn bool QIntDict::remove( long key )
+ Removes the item associated with \e key from the dictionary.
+ Returns TRUE if successful, or FALSE if the key does not exist in the
+ dictionary.
+
+ If there are two or more items with equal keys, then the last inserted
+ of these will be removed.
+
+ The removed item is deleted if \link QCollection::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 traversing order.
+
+ \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn type *QIntDict::take( long key )
+ Takes the item associated with \e key out of the dictionary without
+ deleting it (even if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled).
+
+ If there are two or more items with equal keys, then the last inserted
+ of these will be taken.
+
+ Returns a pointer to the item taken out, or null 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 traversing order.
+
+ \sa remove(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn void QIntDict::clear()
+ Removes all items from the dictionary.
+
+ The removed items are deleted if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ All dictionary iterators that access this dictionary will be reset.
+
+ \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+ \fn type *QIntDict::find( long key ) const
+ Returns the item associated with \e key, or null 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 last inserted
+ of these will be found.
+
+ Equivalent to the [] operator.
+
+ \sa operator[]()
+*/
+
+/*!
+ \fn type *QIntDict::operator[]( long key ) const
+ Returns the item associated with \e key, or null 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 last inserted
+ of these will be found.
+
+ Equivalent to the find() function.
+
+ \sa find()
+*/
+
+/*!
+ \fn void QIntDict::statistics() const
+ Debugging-only function that prints out the dictionary distribution
+ using qDebug().
+*/
+
+
+/*****************************************************************************
+ QIntDictIterator documentation
+ *****************************************************************************/
+
+/*!
+ \class QIntDictIterator qintdict.h
+ \brief The QIntDictIterator class provides an iterator for QIntDict collections.
+
+ \ingroup collection
+ \ingroup tools
+
+ QIntDictIterator is implemented as a template class.
+ Define a template instance QIntDictIterator\<X\> to create a
+ dictionary iterator that operates on QIntDict\<X\> (dictionary of X*).
+
+ Example:
+ \code
+ #include <qintdict.h>
+ #include <stdio.h>
+
+ void main()
+ {
+ QIntDict<char> dict; // maps long ==> char*
+
+ dict.insert( 33, "France" );
+ dict.insert( 7, "Russia" );
+ dict.insert( 49, "Norway" );
+
+ QIntDictIterator<char> it( dict ); // iterator for dict
+
+ while ( it.current() ) {
+ printf( "%d -> %s\n", it.currentKey(), it.current() );
+ ++it;
+ }
+ }
+ \endcode
+
+ Program output:
+ \code
+ 7 -> Russia
+ 49 -> Norway
+ 33 -> France
+ \endcode
+
+ Note that the traversal order is arbitrary, you are not guaranteed the
+ order above.
+
+ Multiple iterators may independently traverse the same dictionary.
+ A QIntDict knows about all iterators that are operating on the dictionary.
+ When an item is removed from the dictionary, QIntDict update all
+ iterators that are referring the removed item to point to the next item
+ in the traversing order.
+
+ \sa QIntDict, \link collection.html Collection Classes\endlink
+*/
+
+/*!
+ \fn QIntDictIterator::QIntDictIterator( const QIntDict<type> &dict )
+ Constructs an iterator for \e dict. The current iterator item is
+ set to point on the first item in the \e dict.
+*/
+
+/*!
+ \fn QIntDictIterator::~QIntDictIterator()
+ Destroys the iterator.
+*/
+
+/*!
+ \fn uint QIntDictIterator::count() const
+ Returns the number of items in the dictionary this iterator operates on.
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool QIntDictIterator::isEmpty() const
+ Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE
+ otherwise.
+ \sa count()
+*/
+
+/*!
+ \fn type *QIntDictIterator::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 null and
+ returns null.
+*/
+
+/*!
+ \fn QIntDictIterator::operator type *() const
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *QIntDictIterator::current() const
+ Returns a pointer to the current iterator item.
+*/
+
+/*!
+ \fn long QIntDictIterator::currentKey() const
+ Returns the key for the current iterator item.
+*/
+
+/*!
+ \fn type *QIntDictIterator::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 null, null is returned.
+*/
+
+/*!
+ \fn type *QIntDictIterator::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 null, null is returned.
+*/
+
+/*!
+ \fn type *QIntDictIterator::operator+=( uint jump )
+ Sets the current item to the item \e 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 null and returns null.
+*/
diff --git a/qtools/qlist.doc b/qtools/qlist.doc
new file mode 100644
index 0000000..85dbf5b
--- /dev/null
+++ b/qtools/qlist.doc
@@ -0,0 +1,1048 @@
+/****************************************************************************
+** $Id$
+**
+** QList and QListIterator class documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+ QList documentation
+ *****************************************************************************/
+
+/*!
+ \class QList qlist.h
+ \brief The QList class is a template class that provides doubly linked lists.
+
+ \ingroup collection
+ \ingroup tools
+
+ In Qt 2.0 QList is only implemented as a template class. Define a
+ template instance QList\<X\> to create a list that operates on pointers
+ to X, or X*.
+
+ Example:
+ \code
+ #include <qlist.h>
+ #include <qstring.h>
+ #include <stdio.h>
+
+ class Employee
+ {
+ public:
+ Employee( const QString& name, int salary ) { n=name; s=salary; }
+ QString name() const { return n; }
+ int salary() const { return s; }
+ private:
+ QString n;
+ int s;
+ };
+
+ void main()
+ {
+ QList<Employee> list; // list of pointers to Employee
+ list.setAutoDelete( TRUE ); // delete items when they are removed
+
+ list.append( new Employee("Bill", 50000) );
+ list.append( new Employee("Steve",80000) );
+ list.append( new Employee("Ron", 60000) );
+
+ Employee *emp;
+ for ( emp=list.first(); emp != 0; emp=list.next() )
+ printf( "%s earns %d\n", emp->name().latin1(), emp->salary() );
+ }
+ \endcode
+
+ Program output:
+ \code
+ Bill earns 50000
+ Steve earns 80000
+ Ron earns 60000
+ \endcode
+
+ 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 0. The current index is -1 if the current item is null.
+
+ QList has several member functions for traversing the list, but using
+ a QListIterator can be more practical. Multiple list iterators may
+ traverse the same list, independent of each other and independent 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
+ from the list. The default is to not delete items when they are
+ removed, but that would cause a memory leak in our example since we have
+ no other references to the list items.
+
+ List items are stored as \c void* in an internal QLNode, which also
+ holds pointers to the next and previous list items. The functions
+ currentNode(), removeNode() and takeNode() operate directly on the
+ QLNode, but they should be used with care.
+
+ When inserting an item into a list, only the pointer is copied, not the
+ item itself. This is called a shallow copy. It is possible to make the
+ list copy all of the item's data (known as a deep copy) when an item is
+ inserted. insert(), inSort() and append() call the virtual function
+ QCollection::newItem() for the item to be inserted.
+ Inherit a list and reimplement it if you want deep copies.
+
+ When removing an item from a list, the virtual function
+ QCollection::deleteItem() is called. QList's default implementation
+ is to delete the item if auto-deletion is enabled.
+
+ The virtual function QGList::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().
+
+ The QStrList class in qstrlist.h is a list of \c char*. QStrList is
+ a good example of a list that reimplements newItem(), deleteItem() and
+ compareItems()
+
+ \sa QListIterator, \link collection.html Collection Classes\endlink
+*/
+
+
+/*!
+ \fn QList::QList()
+ Constructs an empty list.
+*/
+
+/*!
+ \fn QList::QList( const QList<type> &list )
+ Constructs a copy of \e list.
+
+ Each item in \e list is \link append() appended\endlink to this list.
+ Only the pointers are copied (shallow copy).
+*/
+
+/*!
+ \fn QList::~QList()
+ Removes all items from the list and destroys the list.
+
+ All list iterators that access this list will be reset.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn QList<type> &QList::operator=(const QList<type> &list)
+ Assigns \e list to this list and returns a reference to this list.
+
+ This list is first cleared, then each item in \e list is
+ \link append() appended\endlink to this list. Only the pointers are copied
+ (shallow copy), unless newItem() has been reimplemented().
+*/
+
+/*!
+ \fn bool QList::operator==(const QList<type> &list ) const
+
+ Compares this list with \a list. Retruns TRUE if the lists
+ contain the same data, else FALSE.
+*/
+
+/*!
+ \fn uint QList::count() const
+ Returns the number of items in the list.
+ \sa isEmpty()
+*/
+
+/*!
+ \fn void QList::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) compares. This is the asymptotic optimal solution of the
+ sorting problem.
+
+ If the items in your list support operator< and operator== then you
+ might be better off with QSortedList since it implements the
+ compareItems() function for you using these two operators.
+
+ \sa inSort()
+*/
+
+/*!
+ \fn bool QList::isEmpty() const
+ Returns TRUE if the list is empty, i.e. count() == 0. Returns FALSE
+ otherwise.
+ \sa count()
+*/
+
+/*!
+ \fn bool QList::insert( uint index, const type *item )
+ Inserts the \e item at the position \e index in the list.
+
+ Returns TRUE if successful, or FALSE if \e index is out of range.
+ The valid range is <code>0 .. count()</code> inclusive.
+ The item is appended if \e index == count().
+
+ The inserted item becomes the current list item.
+
+ The \e item must not be a null pointer.
+
+ \sa append(), current()
+*/
+
+/*!
+ \fn void QList::inSort( const type *item )
+ Inserts the \e item at its sorted position in the list.
+
+ The sort order depends on the virtual QGList::compareItems() function.
+ All items must be inserted with inSort() to maintain the sorting order.
+
+ The inserted item becomes the current list item.
+
+ The \e item must not be a null pointer.
+
+ Please note that inSort is slow. If you want to insert lots of items
+ in a list and sort after inserting then you should use sort().
+ inSort() takes up to O(n) compares. That means inserting n items in
+ your list will need O(n^2) compares while sort() only needs O(n*logn)
+ for the same task. So you inSort() only if you already have a pre-sorted
+ list and want to insert only few additional items.
+
+ \sa insert(), QGList::compareItems(), current(), sort()
+*/
+
+/*!
+ \fn void QList::append( const type *item )
+ Inserts the \e item at the end of the list.
+
+ The inserted item becomes the current list item.
+ This is equivalent to \c insert(count(),item).
+
+
+ The \e item must not be a null pointer.
+
+ \sa insert(), current(), prepend()
+*/
+
+/*!
+ \fn void QList::prepend( const type *item )
+
+ Inserts the \e item at the start of the list.
+
+ The inserted item becomes the current list item.
+ This is equivalent to \c insert(0,item).
+
+ The \e item must not be a null pointer.
+
+ \sa append(), insert(), current()
+*/
+
+/*!
+ \fn bool QList::remove( uint index )
+ Removes the item at position \e index in the list.
+
+ Returns TRUE if successful, or FALSE if \e index is out of range.
+ The valid range is <code>0 .. (count() - 1)</code> inclusive.
+
+ The removed item is deleted if \link QCollection::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 in Qt 2.x.
+ In 3.0, the current item will be set to null. The current item is
+ set to null 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 QList::remove()
+ Removes the current list item.
+
+ Returns TRUE if successful, or FALSE if the current item is null.
+
+ The removed item is deleted if \link QCollection::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 in Qt 2.x.
+ In 3.0, the current item will be set to null. The current item is
+ set to null 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 QList::remove( const type *item )
+ Removes the first occurrence of \e item from the list.
+
+ Returns TRUE if successful, or FALSE if the item could not be found in the
+ list.
+
+ The removed item is deleted if \link QCollection::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().
+
+ 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 in Qt 2.x.
+ In 3.0, the current item will be set to null. The current item is
+ set to null 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 QList::removeRef( const type *item )
+ Removes the first occurrence of \e item from the list.
+
+ Returns TRUE if successful, or FALSE if the item cannot be found in the
+ list.
+
+ The removed item is deleted if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ The list is scanned until the pointer \e item is found. It is removed
+ if it is found.
+
+ Equivalent to:
+ \code
+ if ( list.findRef(item) != -1 )
+ list.remove();
+ \endcode
+
+ 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 in Qt 2.x.
+ In 3.0, the current item will be set to null. The current item is
+ set to null 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 QList::removeNode( QLNode *node )
+ Removes the \e node from the list.
+
+ This node must exist in the list, otherwise the program may crash.
+
+ The removed item is deleted if \link QCollection::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 null 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 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 QList::removeFirst()
+ Removes the first item from the list.
+ Returns TRUE if successful, or FALSE if the list is empty.
+
+ The removed item is deleted if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ The first item in the list becomes the new current list item.
+ The current item is set to null 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 QList::removeLast()
+ Removes the last item from the list.
+ Returns TRUE if successful, or FALSE if the list is empty.
+
+ The removed item is deleted if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ The last item in the list becomes the new current list item.
+ The current item is set to null 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 *QList::take( uint index )
+ Takes the item at position \e index out of the list without
+ deleting it (even if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled).
+
+ Returns a pointer to the item taken out of the list, or null if
+ the index is out of range.
+ The valid range is <code>0 .. (count() - 1)</code> inclusive.
+
+ The item after the taken item becomes the new current list item if
+ the taken item is not the last item in the list. If the last item
+ is taken, the new last item becomes the current item in Qt 2.x. In
+ 3.0, the current item will be set to null. The current item is set
+ to null 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 *QList::take()
+ Takes the current item out of the list without deleting it (even if
+ \link QCollection::setAutoDelete() auto-deletion\endlink is enabled).
+ Returns a pointer to the item taken out of the list, or null if
+ the current item is null.
+
+ The item after the taken item becomes the new current list item if
+ the taken item is not the last item in the list. If the last item
+ is taken, the new last item becomes the current item in Qt 2.x. In
+ 3.0, the current item will be set to null. The current item is set
+ to null 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 *QList::takeNode( QLNode *node )
+ Takes the \e node out of the list without deleting its item (even if
+ \link QCollection::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 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 QList::clear()
+ Removes all items from the list.
+
+ The removed items are deleted if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ All list iterators that access this list will be reset.
+
+ \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+ \fn int QList::find( const type *item )
+ Finds the first occurrence of \e 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 null,
+ 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 QList::findNext( const type *item )
+ Finds the next occurrence of \e 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 null,
+ 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 QList::findRef( const type *item )
+ Finds the first occurrence of \e 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 null,
+ the current index to -1 and returns -1.
+
+ Calling this function is must faster than find(), because find()
+ compares \e item with each list item using compareItems().
+ This function only compares the pointers.
+
+ \sa findNextRef(), find(), current()
+*/
+
+/*!
+ \fn int QList::findNextRef( const type *item )
+ Finds the next occurrence of \e 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 null,
+ the current index to -1 and returns -1.
+
+ Calling this function is must faster than findNext(), because findNext()
+ compares \e item with each list item using compareItems().
+ This function only compares the pointers.
+
+ \sa findRef(), findNext(), current()
+*/
+
+/*!
+ \fn uint QList::contains( const type *item ) const
+ Counts and returns the number of occurrences of \e item in the list.
+
+ The compareItems() function is called when looking for the \e item
+ in the list. If compareItems() is not reimplemented, it is more
+ efficient to call containsRef().
+
+ Does not affect the current list item.
+
+ \sa containsRef(), compareItems()
+*/
+
+/*!
+ \fn uint QList::containsRef( const type *item ) const
+ Counts and returns the number of occurrences of \e item in the list.
+
+ Calling this function is must faster than contains(), because contains()
+ compares \e item with each list item using compareItems().
+ This function only compares the pointers.
+
+ Does not affect the current list item.
+
+ \sa contains()
+*/
+
+/*!
+ \fn type *QList::at( uint index )
+ Returns a pointer to the item at position \e index in the list, or
+ null if the index is out of range.
+
+ Sets the current list item to this item if \e index is valid.
+ The valid range is <code>0 .. (count() - 1)</code> inclusive.
+
+ This function is very efficient. It starts scanning from the first
+ item, last item or current item, whichever is closest to \e index.
+
+ \sa current()
+*/
+
+/*!
+ \fn int QList::at() const
+ Returns the index of the current list item. The returned value is -1
+ if the current item is null.
+ \sa current()
+*/
+
+/*!
+ \fn type *QList::current() const
+ Returns a pointer to the current list item. The current item may be
+ null (implies that the current index is -1).
+ \sa at()
+*/
+
+/*!
+ \fn QLNode *QList::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 *QList::getFirst() const
+ Returns a pointer to the first item in the list, or null if the
+ list is empty.
+
+ Does not affect the current list item.
+
+ \sa first(), getLast()
+*/
+
+/*!
+ \fn type *QList::getLast() const
+ Returns a pointer to the last item in the list, or null if the
+ list is empty.
+
+ Does not affect the current list item.
+
+ \sa last(), getFirst()
+*/
+
+/*!
+ \fn type *QList::first()
+ Returns a pointer to the first item in the list and makes this the
+ current list item, or null if the list is empty.
+ \sa getFirst(), last(), next(), prev(), current()
+*/
+
+/*!
+ \fn type *QList::last()
+ Returns a pointer to the last item in the list and makes this the
+ current list item, or null if the list is empty.
+ \sa getLast(), first(), next(), prev(), current()
+*/
+
+/*!
+ \fn type *QList::next()
+ Returns a pointer to the item succeeding the current item.
+ Returns null if the current item is null 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 null.
+ If the current item was null, this function does nothing.
+
+ \sa first(), last(), prev(), current()
+*/
+
+/*!
+ \fn type *QList::prev()
+ Returns a pointer to the item preceding the current item.
+ Returns null if the current item is null 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 null.
+ If the current item was null, this function does nothing.
+
+ \sa first(), last(), next(), current()
+*/
+
+/*!
+ \fn void QList::toVector( QGVector *vec ) const
+ Stores all list items in the vector \e vec.
+
+ The vector must be have the same item type, otherwise the result
+ will be undefined.
+*/
+
+
+/*****************************************************************************
+ QListIterator documentation
+ *****************************************************************************/
+
+/*!
+ \class QListIterator qlist.h
+ \brief The QListIterator class provides an iterator for QList collections.
+
+ \ingroup collection
+ \ingroup tools
+
+ Define a template instance QListIterator\<X\> to create a list iterator
+ that operates on QList\<X\> (list of X*).
+
+ Example:
+ \code
+ #include <qlist.h>
+ #include <qstring.h>
+ #include <stdio.h>
+
+ class Employee
+ {
+ public:
+ Employee( const char *name, int salary ) { n=name; s=salary; }
+ const char *name() const { return n; }
+ int salary() const { return s; }
+ private:
+ QString n;
+ int s;
+ };
+
+ void main()
+ {
+ QList<Employee> list; // list of pointers to Employee
+ list.setAutoDelete( TRUE ); // delete items when they are removed
+
+ list.append( new Employee("Bill", 50000) );
+ list.append( new Employee("Steve",80000) );
+ list.append( new Employee("Ron", 60000) );
+
+ QListIterator<Employee> it(list); // iterator for employee list
+ for ( ; it.current(); ++it ) {
+ Employee *emp = it.current();
+ printf( "%s earns %d\n", emp->name().latin1(), emp->salary() );
+ }
+ }
+ \endcode
+
+ Program output:
+ \code
+ Bill earns 50000
+ Steve earns 80000
+ Ron earns 60000
+ \endcode
+
+ Although QList has member functions to traverse the doubly linked list
+ structure, using a list iterator is a much more robust way of traversing
+ the list, because multiple list iterators can operate on the same list,
+ independent of each other and independent of the QList's current item.
+ An iterator has its own current list item and can get the next and
+ previous list items. It can only traverse the list, never modify it.
+
+ A QList knows about all list iterators that are operating on the list.
+ When an item is removed from the list, the list update all iterators
+ that are pointing the removed item to point to the new current list item.
+
+ Example:
+ \code
+ #include <qlist.h>
+ #include <qstring.h>
+ #include <stdio.h>
+
+ class Employee
+ {
+ ... // same as above
+ };
+
+ void main()
+ {
+ QList<Employee> list; // list of pointers to Employee
+ list.setAutoDelete( TRUE ); // delete items when they are removed
+
+ list.append( new Employee("Bill", 50000) );
+ list.append( new Employee("Steve",80000) );
+ list.append( new Employee("Ron", 60000) );
+
+ QListIterator<Employee> it(list);
+
+ list.at( 1 ); // current list item: "Steve"
+ it.toLast(); // it: "Ron"
+ --it; // it: "Steve"
+
+ // Now, both the list and the iterator are referring the same item
+
+ list.remove();
+ printf( "%s\n", it.current()->name().latin1() );
+ }
+ \endcode
+
+ Program output:
+ \code
+ Ron
+ \endcode
+
+ \sa QList, \link collection.html collection classes\endlink
+*/
+
+/*!
+ \fn QListIterator::QListIterator( const QList<type> &list )
+ Constructs an iterator for \e list. The current iterator item is
+ set to point on the first item in the \e list.
+*/
+
+/*!
+ \fn QListIterator::~QListIterator()
+ Destroys the iterator.
+*/
+
+/*!
+ \fn uint QListIterator::count() const
+ Returns the number of items in the list this iterator operates on.
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool QListIterator::isEmpty() const
+ Returns TRUE if the list is empty, i.e. count() == 0, otherwise FALSE.
+ \sa count()
+*/
+
+/*!
+ \fn bool QListIterator::atFirst() const
+ Returns TRUE if the current iterator item is the first list item, otherwise
+ FALSE.
+ \sa toFirst(), atLast()
+*/
+
+/*!
+ \fn bool QListIterator::atLast() const
+ Returns TRUE if the current iterator item is the last list item, otherwise
+ FALSE.
+ \sa toLast(), atFirst()
+*/
+
+/*!
+ \fn type *QListIterator::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 null and returns null
+ if the list is empty.
+ \sa toLast(), atFirst()
+*/
+
+/*!
+ \fn type *QListIterator::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 null and returns null
+ if the list is empty.
+ \sa toFirst(), atLast()
+*/
+
+/*!
+ \fn QListIterator::operator type *() const
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *QListIterator::operator*()
+ Asterix operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *QListIterator::current() const
+ Returns a pointer to the current iterator item.
+*/
+
+/*!
+ \fn type *QListIterator::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
+ null, null is returned.
+*/
+
+/*!
+ \fn char *QStrListIterator::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
+ null, null is returned.
+*/
+
+/*!
+ \fn type *QListIterator::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
+ null, null is returned.
+*/
+
+/*!
+ \fn type *QListIterator::operator+=( uint jump )
+ Sets the current item to the item \e 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 null and returns null
+*/
+
+/*!
+ \fn type *QListIterator::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
+ null, null is returned.
+*/
+
+/*!
+ \fn type *QListIterator::operator-=( uint jump )
+ Returns the item \e jump positions before the current item, or null if
+ it is beyond the first item. Makes this the current item.
+*/
+
+/*!
+ \fn QListIterator<type>& QListIterator::operator=( const QListIterator<type> &it )
+ Assignment. Makes a copy of the iterator \a it and returns a reference
+ to this iterator.
+*/
+
+
+/*****************************************************************************
+ QStrList documentation
+ *****************************************************************************/
+
+typedef QList<char> QStrList
+
+/*!
+ \class QStrList qstrlist.h
+ \brief The QStrList class provides a doubly linked list of \c char*.
+
+ \inherit QList
+
+ \ingroup collection
+ \ingroup tools
+
+ This class is a QList\<char\> instance (a list of char*).
+
+ QStrList can make deep or shallow copies of the strings that are inserted.
+
+ A deep copy means to allocate space for the string and then copy the string
+ data into it. A shallow copy is just a copy of the pointer value and not
+ the string data.
+
+ The disadvantage with shallow copies is that since a pointer can only
+ be deleted 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 shallow copies
+ 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 QStrList that operates on deep copies will by default turn on
+ auto-deletion (see setAutoDelete()). Thus, by default, QStrList 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 a sorted order.
+
+ The QStrListIterator class is an iterator for QStrList.
+*/
+
+/*!
+ \fn QStrList::QStrList( bool deepCopies )
+ Constructs an empty list of strings. Will make deep copies of all inserted
+ strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies
+ is FALSE.
+*/
+
+/*!
+ \fn QStrList::QStrList( const QStrList &list )
+ Constructs a copy of \e list.
+
+ If \e list has deep copies, this list will also get deep copies.
+ Only the pointers are copied (shallow copy) if the other list does not
+ use deep copies.
+*/
+
+/*!
+ \fn QStrList::~QStrList()
+ Destroys the list. All strings are removed.
+*/
+
+/*!
+ \fn QStrList& QStrList::operator=( const QStrList& list )
+ Assigns \e list to this list and returns a reference to this list.
+
+ If \e list has deep copies, this list will also get deep copies.
+ Only the pointers are copied (shallow copy) if the other list does not
+ use deep copies.
+*/
+
+
+/*****************************************************************************
+ QStrIList documentation
+ *****************************************************************************/
+
+/*!
+ \class QStrIList qstrlist.h
+ \brief The QStrIList class provides a doubly linked list of \c char* with
+case insensitive compare.
+
+ \ingroup collection
+ \ingroup tools
+
+ This class is a QList\<char\> instance (a list of char*).
+
+ QStrIList is similar to QStrList except that it is case insensitive.
+ The virtual compareItems() function is reimplemented and does a
+ case insensitive string comparison.
+ The inSort() function will insert strings in a sorted order.
+
+ The QStrListIterator class is an iterator for QStrList.
+*/
+
+/*!
+ \fn QStrIList::QStrIList( bool deepCopies )
+ Constructs a list of strings. Will make deep copies of all inserted
+ strings if \e deepCopies is TRUE, or uses shallow copies if \e deepCopies
+ is FALSE.
+*/
+
+/*!
+ \fn QStrIList::~QStrIList()
+ Destroys the list. All strings are removed.
+*/
+
+
+/*****************************************************************************
+ QStrListIterator documentation
+ *****************************************************************************/
+
+/*!
+ \class QStrListIterator qstrlist.h
+ \brief The QStrListIterator class is an iterator for the QStrList and QStrIList classes.
+
+ \inherit QListIterator
+
+ \ingroup tools
+
+ This class is a QListIterator\<char\> instance.
+ It can traverse the strings in the QStrList and QStrIList classes.
+*/
diff --git a/qtools/qptrdict.doc b/qtools/qptrdict.doc
new file mode 100644
index 0000000..5a652d0
--- /dev/null
+++ b/qtools/qptrdict.doc
@@ -0,0 +1,486 @@
+/****************************************************************************
+** $Id$
+**
+** QPtrDict and QPtrDictIterator class documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+ QPtrDict documentation
+ *****************************************************************************/
+
+/*!
+ \class QPtrDict qptrdict.h
+ \brief The QPtrDict class is a template class that provides a dictionary based on \c void* keys.
+
+ \ingroup collection
+ \ingroup tools
+
+ QPtrDict is implemented as a template class. Define a
+ template instance QPtrDict\<X\> to create a dictionary that operates on
+ pointers to X, or X*.
+
+ A dictionary is a collection that associates an item with a key.
+ The key is used for inserting and looking up an item. QPtrDict has
+ \c void* keys.
+
+ The dictionary has very fast insertion and lookup.
+
+ Example:
+ \code
+ #include <qptrdict.h>
+ #include <stdio.h>
+
+ void main()
+ {
+ int *a = new int[12];
+ int *b = new int[10];
+ int *c = new int[18];
+ int *d = new int[13];
+
+ QPtrDict<char> dict; // maps void* -> char*
+
+ dict.insert( a, "a is int[12]" ); // describe pointers
+ dict.insert( b, "b is int[10]" );
+ dict.insert( c, "c is int[18]" );
+
+ printf( "%s\n", dict[a] ); // print descriptions
+ printf( "%s\n", dict[b] );
+ printf( "%s\n", dict[c] );
+
+ if ( !dict[d] )
+ printf( "d not in dictionary\n" );
+ }
+ \endcode
+
+ Program output:
+ \code
+ a is int[12]
+ b is int[10]
+ c is int[18]
+ d not in dictionary
+ \endcode
+
+ The dictionary in our example maps \c int* keys to \c char* items.
+ QPtrDict implements the \link operator[] [] operator\endlink to lookup
+ an item.
+
+ QPtrDict is implemented by QGDict as a hash array with a fixed number of
+ entries. Each array entry points to a singly linked list of buckets, in
+ which the dictionary items are stored.
+
+ When an item is inserted with a key, the key is converted (hashed) to
+ an integer index into the hash array using the \c mod operation. The
+ item is inserted before the first bucket in the list of buckets.
+
+ Looking up an item is normally very fast. The key is again hashed to an
+ array index. Then QPtrDict scans the list of buckets and returns the item
+ found or null if the item was not found. You cannot insert null pointers
+ into a dictionary.
+
+ The size of the hash array is very important. In order to get good
+ performance, you should use a suitably large \link primes.html prime
+ number\endlink. Suitable means equal to or larger than the maximum
+ expected number of dictionary items.
+
+ Items with equal keys are allowed. When inserting two items with the
+ same key, only the last inserted item will be visible (last in, first out)
+ until it is removed.
+
+ Example:
+ \code
+ #include <qptrdict.h>
+ #include <stdio.h>
+
+ void main()
+ {
+ QPtrDict<char> dict; // maps char* ==> char*
+
+ double *ptr = new double[28];
+ dict.insert( ptr, "first" );
+ dict.insert( ptr, "second" );
+
+ printf( "%s\n", dict[ptr] );
+ dict.remove( ptr );
+ printf( "%s\n", dict[ptr] );
+ }
+ \endcode
+
+ Program output:
+ \code
+ second
+ first
+ \endcode
+
+ The QPtrDictIterator class can traverse the dictionary contents, but only
+ in an arbitrary order. Multiple iterators may independently traverse the
+ same dictionary.
+
+ Calling setAutoDelete(TRUE) for a dictionary tells it to delete items
+ that are removed . The default is to not delete items when they are
+ removed.
+
+ When inserting an item into a dictionary, only the pointer is copied, not
+ the item itself. This is called a shallow copy. It is possible to make the
+ dictionary copy all of the item's data (known as a deep copy) when an
+ item is inserted. insert() calls the virtual function
+ QCollection::newItem() for the item to be inserted.
+ Inherit a dictionary and reimplement it if you want deep copies.
+
+ When removing a dictionary item, the virtual function
+ QCollection::deleteItem() is called. QPtrDict's default implementation
+ is to delete the item if auto-deletion is enabled.
+
+ \sa QPtrDictIterator, QDict, QAsciiDict, QIntDict,
+ \link collection.html Collection Classes\endlink
+*/
+
+
+/*!
+ \fn QPtrDict::QPtrDict( int size )
+ Constructs a dictionary using an internal hash array with the size
+ \e size.
+
+ Setting \e size to a suitably large \link primes.html prime number\endlink
+ (equal to or greater than the expected number of entries) makes the hash
+ distribution better and hence the loopup faster.
+*/
+
+/*!
+ \fn QPtrDict::QPtrDict( const QPtrDict<type> &dict )
+ Constructs a copy of \e dict.
+
+ Each item in \e dict are inserted into this dictionary.
+ Only the pointers are copied (shallow copy).
+*/
+
+/*!
+ \fn QPtrDict::~QPtrDict()
+ Removes all items from the dictionary and destroys it.
+
+ All iterators that access this dictionary will be reset.
+
+ \sa setAutoDelete()
+*/
+
+/*!
+ \fn QPtrDict<type> &QPtrDict::operator=(const QPtrDict<type> &dict)
+ Assigns \e dict to this dictionary and returns a reference to this
+ dictionary.
+
+ This dictionary is first cleared, then each item in \e dict is inserted
+ into this dictionary.
+ Only the pointers are copied (shallow copy), unless newItem() has been
+ reimplemented().
+*/
+
+/*!
+ \fn uint QPtrDict::count() const
+ Returns the number of items in the dictionary.
+ \sa isEmpty()
+*/
+
+/*!
+ \fn uint QPtrDict::size() const
+ Returns the size of the internal hash array (as specified in the
+ constructor).
+ \sa count()
+*/
+
+/*!
+ \fn void QPtrDict::resize( uint newsize )
+ Changes the size of the hashtable the \a newsize.
+ The contents of the dictionary are preserved,
+ but all iterators on the dictionary become invalid.
+*/
+
+/*!
+ \fn bool QPtrDict::isEmpty() const
+ Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE
+ otherwise.
+ \sa count()
+*/
+
+/*!
+ \fn void QPtrDict::insert( void *key, const type *item )
+ Inserts the \e key with the \e item into the dictionary.
+
+ The key does not have to be a unique dictionary key. If multiple items
+ are inserted with the same key, only the last item will be visible.
+
+ Null items are not allowed.
+
+ \sa replace()
+*/
+
+/*!
+ \fn void QPtrDict::replace( void *key, const type *item )
+ Replaces an item which has a key equal to \e key with \e item.
+
+ If the item does not already exist, it will be inserted.
+
+ Null items are not allowed.
+
+ Equivalent to:
+ \code
+ QPtrDict<char> dict;
+ ...
+ if ( dict.find(key) )
+ dict.remove( key );
+ dict.insert( key, item );
+ \endcode
+
+ If there are two or more items with equal keys, then the last inserted
+ of these will be replaced.
+
+ \sa insert()
+*/
+
+/*!
+ \fn bool QPtrDict::remove( void *key )
+ Removes the item associated with \e key from the dictionary.
+ Returns TRUE if successful, or FALSE if the key does not exist in the
+ dictionary.
+
+ If there are two or more items with equal keys, then the last inserted
+ of these will be removed.
+
+ The removed item is deleted if \link QCollection::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 traversing order.
+
+ \sa take(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn type *QPtrDict::take( void *key )
+ Takes the item associated with \e key out of the dictionary without
+ deleting it (even if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled).
+
+ If there are two or more items with equal keys, then the last inserted
+ of these will be taken.
+
+ Returns a pointer to the item taken out, or null 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 traversing order.
+
+ \sa remove(), clear(), setAutoDelete()
+*/
+
+/*!
+ \fn void QPtrDict::clear()
+ Removes all items from the dictionary.
+
+ The removed items are deleted if \link QCollection::setAutoDelete()
+ auto-deletion\endlink is enabled.
+
+ All dictionary iterators that access this dictionary will be reset.
+
+ \sa remove(), take(), setAutoDelete()
+*/
+
+/*!
+ \fn type *QPtrDict::find( void *key ) const
+ Returns the item associated with \e key, or null 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 last inserted
+ of these will be found.
+
+ Equivalent to the [] operator.
+
+ \sa operator[]()
+*/
+
+/*!
+ \fn type *QPtrDict::operator[]( void *key ) const
+ Returns the item associated with \e key, or null 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 last inserted
+ of these will be found.
+
+ Equivalent to the find() function.
+
+ \sa find()
+*/
+
+/*!
+ \fn void QPtrDict::statistics() const
+ Debugging-only function that prints out the dictionary distribution
+ using qDebug().
+*/
+
+
+/*****************************************************************************
+ QPtrDictIterator documentation
+ *****************************************************************************/
+
+/*!
+ \class QPtrDictIterator qptrdict.h
+ \brief The QPtrDictIterator class provides an iterator for QPtrDict collections.
+
+ \ingroup collection
+ \ingroup tools
+
+ QPtrDictIterator is implemented as a template class.
+ Define a template instance QPtrDictIterator\<X\> to create a
+ dictionary iterator that operates on QPtrDict\<X\> (dictionary of X*).
+
+ Example:
+ \code
+ #include <qptrdict.h>
+ #include <stdio.h>
+
+ void main()
+ {
+ int *a = new int[12];
+ int *b = new int[10];
+ int *c = new int[18];
+ int *d = new int[13];
+
+ QPtrDict<char> dict; // maps void* -> char*
+
+ dict.insert( a, "a is int[12]" ); // describe pointers
+ dict.insert( b, "b is int[10]" );
+ dict.insert( c, "c is int[18]" );
+
+ QPtrDictIterator<char> it( dict ); // iterator for dict
+
+ while ( it.current() ) {
+ printf( "%x -> %s\n", it.currentKey(), it.current() );
+ ++it;
+ }
+ }
+ \endcode
+
+ Program output:
+ \code
+ 804a788 -> a is int[12]
+ 804a7f0 -> c is int[18]
+ 804a7c0 -> b is int[10]
+ \endcode
+
+ Note that the traversal order is arbitrary, you are not guaranteed the
+ order above.
+
+ Multiple iterators may independently traverse the same dictionary.
+ A QPtrDict knows about all iterators that are operating on the dictionary.
+ When an item is removed from the dictionary, QPtrDict update all
+ iterators that are referring the removed item to point to the next item
+ in the traversing order.
+
+ \sa QPtrDict, \link collection.html Collection Classes\endlink
+*/
+
+/*!
+ \fn QPtrDictIterator::QPtrDictIterator( const QPtrDict<type> &dict )
+ Constructs an iterator for \e dict. The current iterator item is
+ set to point on the first item in the \e dict.
+*/
+
+/*!
+ \fn QPtrDictIterator::~QPtrDictIterator()
+ Destroys the iterator.
+*/
+
+/*!
+ \fn uint QPtrDictIterator::count() const
+ Returns the number of items in the dictionary this iterator operates on.
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool QPtrDictIterator::isEmpty() const
+ Returns TRUE if the dictionary is empty, i.e. count() == 0. Returns FALSE
+ otherwise.
+ \sa count()
+*/
+
+/*!
+ \fn type *QPtrDictIterator::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 null and
+ returns null.
+*/
+
+/*!
+ \fn QPtrDictIterator::operator type *() const
+ Cast operator. Returns a pointer to the current iterator item.
+ Same as current().
+*/
+
+/*!
+ \fn type *QPtrDictIterator::current() const
+ Returns a pointer to the current iterator item.
+*/
+
+/*!
+ \fn void *QPtrDictIterator::currentKey() const
+ Returns the key for the current iterator item.
+*/
+
+/*!
+ \fn type *QPtrDictIterator::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 null, null is returned.
+*/
+
+/*!
+ \fn type *QPtrDictIterator::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 null, null is returned.
+*/
+
+/*!
+ \fn type *QPtrDictIterator::operator+=( uint jump )
+ Sets the current item to the item \e 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 null and returns null.
+*/
diff --git a/qtools/qsortedlist.doc b/qtools/qsortedlist.doc
new file mode 100644
index 0000000..12d3f02
--- /dev/null
+++ b/qtools/qsortedlist.doc
@@ -0,0 +1,94 @@
+/****************************************************************************
+** $Id$
+**
+** QSortedList documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+ QSortedList documentation
+ *****************************************************************************/
+
+/*!
+ \class QSortedList qsortedlist.h
+ \brief The QSortedList class provides a list sorted by operator< and operator==
+
+ \ingroup collection
+ \ingroup tools
+
+ If you want to sort a QList you have to reimplement the
+ QGList::compareItems() method. If the elements of your list support
+ operator<() and operator==() then you can use QSortedList instead.
+ Its compareItems() calls operator<() and operator==() and returns an
+ appropriate result.
+
+ Otherwise, this is as QList.
+
+ \sa QList, \link collection.html Collection Classes\endlink
+*/
+
+
+/*!
+ \fn QSortedList::QSortedList()
+ Constructs an empty list.
+*/
+
+/*!
+ \fn QSortedList::QSortedList( const QSortedList<type> &list )
+ Constructs a copy of \e list.
+
+ Each item in \e list is copied to this new list.
+*/
+
+/*!
+ \fn QSortedList::~QSortedList()
+ Removes all items from the list and destroys the list.
+
+ All list iterators that access this list will be reset.
+*/
+
+/*!
+ \fn QSortedList<type>& QSortedList::operator=(const QSortedList<type>& list)
+ Assigns \e list to this list and returns a reference to this list.
+
+ This list is first cleared, then each item in \e list is
+ appended to this list. Only the pointers are copied
+ (shallow copy), unless newItem() has been reimplemented().
+*/
+
+/*!
+ \fn int QSortedList::compareItems( QCollection::Item s1, QCollection::Item s2 )
+
+ \reimp
+
+ This reimplementation uses operator< and operator== to compare.
+*/
diff --git a/qtools/qstack.doc b/qtools/qstack.doc
new file mode 100644
index 0000000..b51e7c0
--- /dev/null
+++ b/qtools/qstack.doc
@@ -0,0 +1,135 @@
+/****************************************************************************
+** $Id$
+**
+** QStack class documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+ QStack documentation
+ *****************************************************************************/
+
+/*!
+ \class QStack qstack.h
+ \brief The QStack class is a template class that provides a stack.
+
+ \ingroup collection
+ \ingroup tools
+
+ QStack is implemented as a template class. Define a template
+ instance QStack\<X\> to create a stack that operates on pointers to
+ X, or 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().
+
+ \sa \link collection.html Collection Classes\endlink
+*/
+
+/*! \fn QStack::QStack ()
+ Creates and empty stack.
+*/
+
+/*! \fn QStack::QStack (const QStack<type>& s)
+ Creates a stack by making a shallow copy of another stack.
+*/
+
+/*! \fn QStack::~QStack ()
+ Destroys the stack. All items will be deleted if autoDelete() is TRUE.
+*/
+
+/*! \fn QStack<type>& QStack::operator= (const QStack<type>& s)
+ Sets the contents of this stack by making a shallow copy of another stack.
+ Elements currently in this stack will be deleted if autoDelete() is TRUE.
+*/
+
+/*! \fn bool QStack::isEmpty () const
+ Returns TRUE is the stack contains no elements to be \link pop() popped\endlink.
+*/
+
+/*! \fn void QStack::push (const type* d)
+ Adds an element to the top of the stack. Last in, first out.
+*/
+
+/*! \fn type* QStack::pop ()
+ Removes the top item from the stack and returns it.
+*/
+
+/*! \fn bool QStack::remove ()
+ Removes the top item from the stack and deletes it if
+ autoDelete() is TRUE. Returns TRUE if there was an item to pop.
+
+ \sa clear()
+*/
+
+/*! \fn void QStack::clear()
+ Removes all items from the stack, deleting them if
+ autoDelete() is TRUE.
+
+ \sa remove()
+*/
+
+/*! \fn uint QStack::count() const
+ Returns the number of items in the stack.
+
+ \sa isEmpty()
+*/
+
+/*! \fn type* QStack::top () const
+ Returns a reference to the top item on the stack (most recently pushed).
+ The stack is not changed.
+*/
+
+/*! \fn QStack::operator type* ()const
+ Returns a reference to the top item on the stack (most recently pushed).
+ The stack is not changed.
+*/
+
+/*! \fn type* QStack::current () const
+ Returns a reference to the top item on the stack (most recently pushed).
+ The stack is not changed.
+*/
+
+/*! \fn bool QStack::autoDelete() const
+
+ The same as QCollection::autoDelete().
+
+ \sa setAutoDelete()
+*/
+
+/*! \fn void QStack::setAutoDelete( bool enable )
+
+ The same as QCollection::setAutoDelete().
+
+ \sa autoDelete()
+*/
diff --git a/qtools/qstrlist.doc b/qtools/qstrlist.doc
new file mode 100644
index 0000000..81e4e46
--- /dev/null
+++ b/qtools/qstrlist.doc
@@ -0,0 +1,5 @@
+/****************************************************************************
+** $Id$
+*****************************************************************************/
+
+//typedef QListIterator<char> QStrListIterator;
diff --git a/qtools/qtl.doc b/qtools/qtl.doc
new file mode 100644
index 0000000..e4ce0d0
--- /dev/null
+++ b/qtools/qtl.doc
@@ -0,0 +1,249 @@
+/****************************************************************************
+** $Id$
+**
+** Qt template library classes documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+/*!
+\page qtl.html
+
+\title Qt Template library
+
+Thq Qt Template Library is a set of templates within Qt dealing with
+containers of objects. It provides a list of objects, a stack of
+objects, a map (or dictionary) from one type to another, and
+associated iterators and algorithms.
+
+Qt also contains similar classes that deal with pointers to objects;
+\l QValueList vs. \l QList, etc. Compared to the pointer-based
+templates, the QTL offers easy copying of the container, real support
+for classes that e.g. require constructors, expand to much more object
+code, can often be a bit faster, require that the objects stored can
+be copied, and finally, have a worse record of compiler problems.
+
+Compared to the STL, the QTL contains only the most important features
+of the STL, has more regular function naming, has no platform
+differences, is often a little slower and often expands to less object
+code.
+
+
+If you can not make copies of the objects you want to store you are
+better off with QCollection and friends. They were designed to handle
+exactly that kind of pointer semantics. This applies for example to
+all classes derived from \l QObject. A QObject does not have a copy
+constructor, so using it as value is impossible. You may choose be
+store pointers to QObjects in a QValueList, but using QList directly
+seems to be the better choice for this kind of application
+domain. QList, like all other QCollection based containers, provides
+far more sanity checking than a speed-optimized value
+based container.
+
+If you have objects that implement value semantics, use the Qt
+template library. Value semantics require at least
+<ul>
+<li>a copy constructor,
+<li>an assignment operator and
+<li> a default constructor, i.e. a constructor that does not take
+any arguments.
+</ul>
+Note that a fast copy constructor is absolutely crucial for a good
+overall performance of the container, since many copy operations are
+going to happen.
+
+Examples for value based classes are QRect, QPoint, QSize and all
+simple C++ types like int, bool or double.
+
+The Qt template library is designed for speed. Especially iterators
+are extremely fast. On the drawback side, less error checking is done
+than in the QCollection based containers. A template library container
+for example does not track associated iterators. This makes certain
+validity checks, like on removing items, impossible to perform
+automatically.
+
+<h2> Iterators </h2>
+
+The Qt template library deals with value objects, not with pointers.
+For that reason, there is no other way of iterating over containers
+than using iterators. This is no disadvantage as the size of an
+iterator matches the size of a normal pointer - 32 or 64 bits
+depending on your CPU architecture.
+
+To iterate over a container, use a loop like this:
+
+\code
+ typedef QValueList<int> List;
+ List l;
+ for( List::Iterator it = l.begin(); it != l.end(); ++it )
+ printf("Number is %i\n",*it);
+\endcode
+
+begin() returns the iterator pointing at the first element, while
+end() returns an iterator that points \e after the last
+element. end() marks an invalid position, it can never be
+dereferenced. It's the break condition in any iteration, may it be
+from begin() or fromLast(). For maximum speed, use increment or
+decrement iterators with the prefix operator (++it, --it) instead of the the
+postfix one (it++, it--), since the former is slightly faster.
+
+The same concept applies to the other container classes:
+
+\code
+ typedef QMap<QString,QString> Map;
+ Map map;
+ for( Map::Iterator it = map.begin(); it != map.end(); ++it )
+ printf("Key=%s Data=%s\n", it.key().ascii(), it.data().ascii() );
+
+ typedef QArray<int> Array;
+ Array array;
+ for( Array::Iterator it = array.begin(); it != array.end(); ++it )
+ printf("Data=%i\n", *it );
+\endcode
+
+There are two kind of iterators, the volatile iterator shown in the
+examples above and a version that returns a const reference to its
+current object, the ConstIterator. Const iterators are required
+whenever the container itself is const, such as a member variable
+inside a const function. Assigning a ConstIterator to a normal
+Iterator is not allowed as it would violate const semantics.
+
+<h2> Algorithms </h2>
+
+The template library defines a number of algorithms that operate on
+its containers: qHeapSort(), qBubbleSort(), qSwap() and
+qCopy(). These algorithms are implemented as template functions.
+
+qHeapSort() and qBubbleSort() provide the well known sorting
+algorithms. You can use them like this:
+
+\code
+ typedef QValueList<int> List;
+ List l;
+ l << 42 << 100 << 1234 << 12 << 8;
+ qHeapSort( l );
+
+ List l2;
+ l2 << 42 << 100 << 1234 << 12 << 8;
+ List::Iterator b = l2.find( 100 );
+ List::Iterator e = l2.find( 8 );
+ qHeapSort( b, e );
+
+ double arr[] = { 3.2, 5.6, 8.9 };
+ qHeapSort( arr, arr + 3 );
+\endcode
+
+The first example sorts the entire list. The second one sorts all
+elements enclosed in the two iterators, namely 100, 1234 and 12. The
+third example shows that iterators act like pointers and can be
+treated as such.
+
+Naturally, the sorting templates won't work with const iterators.
+
+Another utility is qSwap(). It exchanges the values of two variables:
+
+\code
+ QString second( "Einstein" );
+ QString name( "Albert" );
+ qSwap( second, name );
+\endcode
+
+Another template function is qCopy(). It copies a container or a slice
+of it to an OutputIterator, in this case a QTextOStreamIterator:
+
+\code
+ typedef QValueList<int> List;
+ List l;
+ l << 100 << 200 << 300;
+ QTextOStream str( stdout );
+ qCopy( l, QTextOStreamIterator( str ) );
+\endcode
+
+In addition, you can use any Qt template library iterator as the
+OutputIterator. Just make sure that the right hand of the iterator has
+as many elements present as you want to insert. The following example
+illustrates this:
+
+\code
+ QStringList l1, l2;
+ l1 << "Weis" << "Ettrich" << "Arnt" << "Sue";
+ l2 << "Torben" << "Matthias";
+ qCopy( l2, l1.begin();
+\endcode
+
+At the end of this code fragment, the List l1 contains "Torben",
+"Matthias", "Arnt" and "Sue", with the prior contents being
+overwritten. Another flavor of qCopy() takes three arguments to make
+it possible to copy a slice of a container:
+
+\code
+ typedef QValueList<int> List;
+ List l;
+ l << 42 << 100 << 1234 << 12 << 8;
+ List::Iterator b = l.find( 100 );
+ List::Iterator e = l.find( 8 );
+ QTextOStream str( stdout );
+ qCopy( b, e, QTextOStreamIterator( str ) );
+\endcode
+
+If you write new algorithms, consider writing them as template
+functions in order to make them usable with as many containers
+possible. In the above example, you could just as easily print out a
+standard C++ array with qCopy():
+
+\code
+ int arr[] = { 100, 200, 300 };
+ QTextOStream str( stdout );
+ qCopy( arr, arr + 3, QTextOStreamIterator( str ) );
+\endcode
+
+
+<h2> Streaming </h2>
+
+All mentioned containers can be serialized with the respective
+streaming operators. Here is an example.
+
+\code
+ QDataStream str(...);
+ QValueList<QRect> l;
+ // ... fill the list here
+ str << l;
+\endcode
+
+The container can be read in again with:
+
+\code
+ QValueList<QRect> l;
+ str >> l;
+\endcode
+
+The same applies to QStringList, QValueStack and QMap.
+
+*/
diff --git a/qtools/qvaluelist.doc b/qtools/qvaluelist.doc
new file mode 100644
index 0000000..6aa95d8
--- /dev/null
+++ b/qtools/qvaluelist.doc
@@ -0,0 +1,772 @@
+/****************************************************************************
+** $Id$
+**
+** QValueList and QValueListIterator class documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+ QValueList documentation
+ *****************************************************************************/
+
+/*!
+ \class QValueList qvaluelist.h
+ \brief The QValueList class is a value based template class that provides doubly linked lists.
+
+ \ingroup qtl
+ \ingroup tools
+ \ingroup shared
+
+ Define a template instance QValueList\<X\> to create a list of values which all
+ have the class X. Please notice that QValueList does not store pointers to the
+ members of the list. It holds a copy of every member. That is the reason why this
+ kind of classes are called "value based" while QList and QDict are "reference based".
+
+ Some classes can not be used within a QValueList, for example everything
+ derived from QObject and thus all classes that implement widgets.
+ Only values can be used in a QValueList. To qualify as a value, the class
+ must provide
+ <ul>
+ <li>a copy constructor,
+ <li>an assignment operator and
+ <li> a default constructor, i.e. a constructor that does not take any arguments.
+ </ul>
+
+ 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.
+
+ Example:
+ \code
+ #include <qvaluelist.h>
+ #include <qstring.h>
+ #include <stdio.h>
+
+ class Employee
+ {
+ public:
+ Employee(): s(0) {}
+ Employee( const QString& name, int salary )
+ : n(name), s(salary)
+ {}
+
+ QString name() const { return n; }
+ int salary() const { return s; }
+ void setSalary( int salary ) { s = salary; }
+ private:
+ QString n;
+ int s;
+ };
+
+ void main()
+ {
+ typedef QValueList<Employee> EmployeeList;
+ EmployeeList list; // list of Employee
+
+ list.append( Employee("Bill", 50000) );
+ list.append( Employee("Steve",80000) );
+ list.append( Employee("Ron", 60000) );
+
+ Employee joe( "Joe", 50000 );
+ list.append( joe );
+ joe.setSalary( 4000 );
+
+ EmployeeList::Iterator it;
+ for( it = list.begin(); it != list.end(); ++it )
+ printf( "%s earns %d\n", (*it).name().latin1(), (*it).salary().latin1() );
+ }
+ \endcode
+
+ Program output:
+ \code
+ Bill earns 50000
+ Steve earns 80000
+ Ron earns 60000
+ Joe earns 50000
+ \endcode
+
+ As you can see, the latest changes to Joes salary did not affect the value
+ in the list because the list created a copy of Joes entry.
+
+ There are three ways of finding items in the list. The first one is by using
+ the at() function. It returns an iterator. The advantages of
+ getting an iterator is that you can now move forward or backward from this
+ position by incrementing/decrementing the iterator. To get the amount of
+ items in the list call count(). Valid indices are 0..count().
+
+ The second way of accessing a list is with operator[]. That means you can address
+ it like an array. The return value is a reference to the value stored in the list.
+ There exist two versions of this operator. The first one is const and returns a
+ const reference to the value. The second on is non const and returns a non const
+ reference to the value. It is up to your compiler to choose the correct one.
+
+ The third method is to use the functions begin() and end().
+ With a simple for loop as shown in the example you can iterate over the complete list.
+ It is save to have multiple iterators at the same time. If some member of the list is
+ removed then only iterators pointing to the removed member become invalid. Inserting in
+ the list does not invalidate any iterator. For convenience the function last() returns
+ an iterator for the last and first() for the first element in the list.
+
+ In addition you can search items in the list with the find() function. It exists in a const
+ and a non const version. It starts searching from the beginning of the list, but another
+ flavor of the find() function allows you to specify where searching should start.
+ If you just want to know wether a certain item is at least once in the list, then you
+ can use the contains() function.
+
+ Since QValueList is value based there is no need to care about deleting elements 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 item with clear().
+
+ QValueList is implicitly shared. That means you can just make copies of the list
+ in time O(1). If multiple QValueList instances share the same data and one
+ is doing a modification of the lists data then this modifying instance makes a copy
+ and modifies its private copy. So it does not affect the other instances.
+ From a developers point of view you can think that a QValueList and a copy of this
+ list have nothing to do with each other. Developers may only notice that copying is
+ very fast. People known to a CPUs MMU architecture will know this pattern as "copy on write".
+
+ There exist three functions to insert items in the list. append()
+ inserts an item at the end, prepend() inserts at the beginning
+ and insert() inserts in front of the position given by an iterator.
+
+ Items can be removed from the list in two ways. The first is to pass an iterator to
+ the remove(). The other possibility is to pass a value to remove() which will
+ delete all members which match this value.
+
+ Lists can be sorted with the algorithms provided by the <a
+ href="qtl.html">Qt Template Library</a>, for example with
+ qHeapSort():
+
+ Example:
+ \code
+ QValueList l;
+ l.append( 5 );
+ l.append( 8 );
+ l.append( 3 );
+ l.append( 4 );
+ qHeapSort( l );
+ \endcode
+
+ \sa QValueListIterator
+*/
+
+
+/*!
+ \fn QValueList::QValueList()
+ Constructs an empty list.
+*/
+
+/*!
+ \fn QValueList::QValueList( const QValueList<T>& l )
+ Constructs a copy of \e l.
+
+ This operation costs O(1) time since QValueList is implicit shared.
+ The first instance applying modifications to a shared list will create
+ a copy which takes in turn O(n) time. However returning a QValueList from
+ a function is very fast.
+*/
+
+/*!
+ \fn QValueList::~QValueList()
+ Destroys the list. References to the values in the list and all iterators
+ of this list become invalidated. Since QValueList is highly tuned for performance
+ you wont see warnings if you use invalid iterators,
+ because it is impossible for
+ an iterator to check wether it is valid or not.
+*/
+
+/*!
+ \fn QValueList<T>& QValueList::operator= ( const QValueList<T>& l )
+ Assigns \e 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 QValueList is implicitly shared.
+*/
+
+/*!
+ \fn QValueList<T> QValueList::operator+ ( const QValueList<T>& l ) const
+ Creates a new list and fills it with the elements of this list. Then the
+ elements of \e l are appended.
+
+ Returns the new list.
+*/
+
+/*!
+ \fn QValueList<T>& QValueList::operator+= ( const QValueList<T>& l )
+ Adds \e list to this list.
+
+ Returns a reference to this list.
+*/
+
+/*!
+ \fn bool QValueList::operator== ( const QValueList<T>& l ) const
+ Compares both lists.
+
+ Returns TRUE if both list are equal.
+*/
+
+/*!
+ \fn bool QValueList::operator!= ( const QValueList<T>& l ) const
+ Compares both lists.
+
+ Returns TRUE if both list are unequal.
+*/
+
+/*!
+ \fn QValueList<T>& QValueList::operator+= ( const T& x )
+ Adds the value \e x to the end of the list.
+
+ Returns a reference to the list.
+*/
+
+/*!
+ \fn QValueList<T>& QValueList::operator<< ( const T& x )
+ Adds the value \e x to the end of the list.
+
+ Returns a reference to the list.
+*/
+
+/*!
+ \fn const T& QValueList::operator[] ( uint i ) const
+ Returns a const reference to the item with index \e i in the list.
+ It is up to you to check wether this item really exists. You can do that easily
+ with the count() function. However this operator does not check wether \e i
+ is in range and will deliver undefined results if it does not exist.
+*/
+
+/*!
+ \fn T& QValueList::operator[] ( uint i )
+ Returns a reference to the item with index \e i in the list.
+ It is up to you to check wether this item really exists. You can do that easily
+ with the count() function. However this operator does not check wether \e i
+ is in range and will deliver undefined results if it does not exist.
+ In contrast to the const operator[] you may manipulate the value returned by this
+ operator.
+*/
+
+/*!
+ \fn uint QValueList::count() const
+ Returns the number of items in the list.
+ \sa isEmpty()
+*/
+
+/*!
+ \fn bool QValueList::isEmpty() const
+ Returns TRUE if the list is empty, i.e. count() == 0. Returns FALSE
+ otherwise.
+ \sa count()
+*/
+
+/*!
+ \fn Iterator QValueList::insert( Iterator it, const T& x )
+ Inserts the value \e x in front of the iterator \e it.
+
+ Returns an iterator pointing at the inserted item.
+
+ \sa append(), prepend()
+*/
+
+/*!
+ \fn Iterator QValueList::append( const T& x )
+ Inserts the value \e x at the end of the list.
+
+ Returns an iterator pointing at the inserted item.
+
+ \sa insert(), prepend()
+*/
+
+/*!
+ \fn Iterator QValueList::prepend( const T& x )
+ Inserts the value \e x at the beginning of the list.
+
+ Returns an iterator pointing at the inserted item.
+
+ \sa insert(), append()
+*/
+
+/*!
+ \fn Iterator QValueList::remove( Iterator it )
+ Removes the item at position \e it in the list.
+
+ Returns an iterator pointing to the item following the
+ removed on or end() if the last item was deleted.
+
+ \sa clear()
+*/
+
+/*!
+ \fn void QValueList::remove( const T& x )
+ Removes all items which have the value \e x.
+
+ \sa clear()
+*/
+
+/*!
+ \fn void QValueList::clear()
+ Removes all items from the list.
+
+ \sa remove()
+*/
+
+/*!
+ \fn Iterator QValueList::find( const T& x )
+ Finds the first occurrence of \e x in the list.
+
+ Returns end() if no item did match.
+*/
+
+/*!
+ \fn ConstIterator QValueList::find( const T& x ) const
+ Finds the first occurrence of \e x in the list.
+
+ Returns end() if no item did match.
+*/
+
+/*!
+ \fn Iterator QValueList::find( Iterator it, const T& x )
+ Finds the first occurrence of \e x in the list starting at
+ the position given by \e it.
+
+ Returns end() if no item did match.
+*/
+
+/*!
+ \fn ConstIterator QValueList::find( ConstIterator it, const T& x ) const
+ Finds the first occurrence of \e x in the list starting at
+ the position given by \e it.
+
+ Returns end() if no item did match.
+*/
+
+/*!
+ \fn uint QValueList::contains( const T& x ) const
+ Counts and returns the number of occurrences of the value \e x in the list.
+*/
+
+/*!
+ \fn int QValueList::findIndex( const T& x ) const
+ Returns the first index of the value \e x in the list or -1 if no such value
+ can be found in the list.
+*/
+
+/*!
+ \fn Iterator QValueList::at( uint i )
+ Returns an iterator pointing to the item at position \e i in the list, or
+ end() if the index is out of range.
+*/
+
+/*!
+ \fn ConstIterator QValueList::at( uint i ) const
+ Returns an iterator pointing to the item at position \e i in the list, or
+ end() if the index is out of range.
+*/
+
+/*!
+ \fn T& QValueList::first()
+ Returns a reference to the first item in the list or the item
+ referenced by end()
+ if no such items exists. Please note that you may not change
+ the value the end() Iterator is pointing to.
+
+ \sa begin(), last()
+*/
+
+/*!
+ \fn const T& QValueList::first() const
+ Returns a reference to the first item in the list or the item
+ referenced by end() if
+ no such items exists.
+
+ \sa begin(), last()
+*/
+
+/*!
+ \fn Iterator QValueList::fromLast()
+ Returns an iterator pointing to the last element in the list or
+ end() if no such item exists.
+
+ \sa last()
+*/
+
+/*!
+ \fn ConstIterator QValueList::fromLast() const
+ Returns an iterator pointing to the last element in the list or
+ end() if no such item exists.
+
+ \sa last()
+*/
+
+/*!
+ \fn T& QValueList::last()
+ Returns a reference to the last item in the list or the item
+ referenced by end() if no
+ such item exists. Please note that you may not change
+ the value the end() Iterator is pointing to.
+
+ \sa end(), first(), fromLast()
+*/
+
+/*!
+ \fn const T& QValueList::last() const
+ Returns a reference to the last item in the list or the item
+ referenced by end() if no such item exists.
+
+ \sa end(), first(), fromLast()
+*/
+
+/*!
+ \fn Iterator QValueList::begin()
+ Returns an iterator pointing to the first element in the list. This
+ iterator equals end() if the list is empty;
+ \sa first(), end()
+*/
+
+/*!
+ \fn ConstIterator QValueList::begin() const
+ Returns an iterator pointing to the first element in the list. This
+ iterator equals end() if the list is empty;
+ \sa first(), end()
+*/
+
+/*!
+ \fn Iterator QValueList::end()
+ Returns an iterator pointing behind the last element in the list. This
+ iterator equals begin() if the list is empty.
+
+ \sa last(), begin()
+*/
+
+/*!
+ \fn ConstIterator QValueList::end() const
+ Returns an iterator pointing behind the last element in the list. This
+ iterator equals begin() if the list is empty.
+
+ \sa last(), begin()
+*/
+
+/*!
+ \fn void QValueList::detach()
+ If the list does not share its data with another QValueList instance, then nothing
+ happens, otherwise the function creates a new copy of this data and detaches
+ from the shared one. This function is called whenever the list is modified.
+ The implicit sharing mechanism is implemented this way.
+*/
+
+/*!
+ \fn QDataStream& operator>>( QDataStream& s, QValueList<T>& l )
+ \relates QValueList
+ Reads a list from the stream. The type \e T stored in the list must implement
+ the streaming operator, too.
+*/
+
+/*!
+ \fn QDataStream& operator<<( QDataStream& s, const QValueList<T>& l )
+ \relates QValueList
+ Writes a list to the stream. The type \e T stored in the list must implement
+ the streaming operator, too.
+*/
+
+/*****************************************************************************
+ QValueListIterator documentation
+ *****************************************************************************/
+
+/*!
+ \class QValueListIterator qvaluelist.h
+ \brief The QValueListIterator class provides an iterator for QValueList.
+
+ \ingroup qtl
+ \ingroup tools
+
+ You can not create an iterator by yourself. Instead you have to
+ ask a list to give you one. An iterator has only the size of a pointer.
+ On 32 bit machines that means 4 bytes otherwise 8 bytes. That makes them
+ very fast. In fact they resemble the semantics of pointers as good as possible
+ and they are almost as fast as usual pointers.
+
+ Example:
+ \code
+ #include <qvaluelist.h>
+ #include <qstring.h>
+ #include <stdio.h>
+
+ class Employee
+ {
+ public:
+ Employee(): s(0) {}
+ Employee( const QString& name, int salary )
+ : n(name), s(salary)
+ {}
+
+ QString name() const { return n; }
+ int salary() const { return s; }
+ void setSalary( int salary ) { s = salary; }
+ private:
+ QString n;
+ int s;
+ };
+
+ void main()
+ {
+ typedef QValueList<Employee> EmployeeList;
+ EmployeeList list; // list of Employee
+
+ list.append( Employee("Bill", 50000) );
+ list.append( Employee("Steve",80000) );
+ list.append( Employee("Ron", 60000) );
+
+ Employee joe( "Joe", 50000 );
+ list.append( joe );
+ joe.setSalary( 4000 );
+
+ EmployeeList::Iterator it;
+ for( it = list.begin(); it != list.end(); ++it )
+ printf( "%s earns %d\n", (*it).name().latin1(), (*it).salary() );
+ }
+ \endcode
+
+ Program output:
+ \code
+ Bill earns 50000
+ Steve earns 80000
+ Ron earns 60000
+ Joe earns 50000
+ \endcode
+
+ In contrast to QList there are no built in functions in QValueList to
+ traverse the list. The only way to do this is to use iterators.
+ QValueList is highly optimized for performance and memory usage.
+ On the other hand that means that you have to be a bit more careful
+ by what you are doing. QValueList does not know about all its iterators
+ and the iterators dont even know to which list they belong. That makes
+ things fast and slim but a bit dangerous because it is up to you to make
+ sure that iterators you are using are still valid. QListIterator will be able
+ to give warnings while QValueListIterator may end up in an undefined state.
+
+ For every Iterator there is a ConstIterator. When accessing a QValueList
+ in a const environment or if the reference or pointer to the list is itself
+ const, then you have to use the ConstIterator. Its semantics are the same,
+ but it returns only const references to the item it points to.
+
+ \sa QValueList, QValueListConstIterator
+*/
+
+/*!
+ \fn QValueListIterator::QValueListIterator()
+ Creates un uninitialized iterator.
+*/
+
+/*!
+ \fn QValueListIterator::QValueListIterator( NodePtr p )
+ Internal function.
+*/
+
+/*!
+ \fn QValueListIterator::QValueListIterator( const QValueListIterator<T>& it )
+ Constructs a copy of the iterator \e it.
+*/
+
+/*!
+ \fn QValueListIterator::~QValueListIterator()
+ Destroys the iterator.
+*/
+
+/* Unfortunately not with MSVC
+ \fn T *QValueListIterator::operator->()
+ Pointer operator. Returns a pointer to the current iterator item.
+ The great advantage of this operator is that you can treat the
+ iterator like a pointer.
+
+ Example:
+ \code
+ QValueList<int>::Iterator it = list.begin();
+ for( ; it != end(); ++it )
+ it->show();
+ \endcode
+*/
+
+/*!
+ \fn T& QValueListIterator::operator*()
+ Asterix operator. Returns a reference to the current iterator item.
+*/
+
+/*!
+ \fn const T& QValueListIterator::operator*() const
+ Asterix operator. Returns a reference to the current iterator item.
+*/
+
+/*!
+ \fn QValueListIterator<T>& QValueListIterator::operator++()
+ Prefix ++ makes the succeeding item current and returns
+ an iterator pointing to the new current item.
+ The iterator can not check wether it reached the end of the list. Incrementing
+ the iterator as returned by end() causes undefined results.
+*/
+
+/*!
+ \fn QValueListIterator<T> QValueListIterator::operator++(int)
+ Postfix ++ makes the succeeding item current and returns
+ an iterator pointing to the new current item.
+ The iterator can not check wether it reached the end of the list. Incrementing
+ the iterator as returned by end() causes undefined results.
+*/
+
+/*!
+ \fn QValueListIterator<T>& QValueListIterator::operator--()
+ Prefix -- makes the previous item current and returns
+ an iterator pointing to the new current item.
+ The iterator can not check wether it reached the beginning of the list. Decrementing
+ the iterator as returned by begin() causes undefined results.
+*/
+
+/*!
+ \fn QValueListIterator<T> QValueListIterator::operator--(int)
+ Postfix -- makes the previous item current and returns
+ an iterator pointing to the new current item.
+ The iterator can not check wether it reached the beginning of the list. Decrementing
+ the iterator as returned by begin() causes undefined results.
+*/
+
+/*!
+ \fn bool QValueListIterator::operator==( const QValueListIterator<T>& it ) const
+ Compares both iterators and returns TRUE if they point to the same item.
+*/
+
+/*!
+ \fn bool QValueListIterator::operator!=( const QValueListIterator<T>& it ) const
+ Compares both iterators and returns TRUE if they point to different items.
+*/
+
+/*****************************************************************************
+ QValueListConstIterator documentation
+ *****************************************************************************/
+
+/*!
+ \class QValueListConstIterator qvaluelist.h
+ \brief The QValueListConstIterator class provides an iterator for QValueList.
+
+ \ingroup qtl
+ \ingroup tools
+
+ In contrast to QValueListIterator this class is used to iterate over a const
+ list. It does not allow to modify the values of the list since this would
+ break the const semantics.
+
+ For more informations on QValueList iterators see QValueListIterator.
+
+ \sa QValueListIterator, QValueList
+*/
+
+/*!
+ \fn QValueListConstIterator::QValueListConstIterator()
+ Creates un uninitialized iterator.
+*/
+
+/*!
+ \fn QValueListConstIterator::QValueListConstIterator( NodePtr p )
+ Internal function.
+*/
+
+/*!
+ \fn QValueListConstIterator::QValueListConstIterator( const QValueListConstIterator<T>& it )
+ Constructs a copy of the iterator \e it.
+*/
+
+/*!
+ \fn QValueListConstIterator::QValueListConstIterator( const QValueListIterator<T>& it )
+ Constructs a copy of the iterator \e it.
+*/
+
+/*!
+ \fn QValueListConstIterator::~QValueListConstIterator()
+ Destroys the iterator.
+*/
+
+/* Unfortunately not with MSVC
+ \fn const T *QValueListConstIterator::operator->()
+ Pointer operator. Returns a pointer to the current iterator item.
+ The great advantage of this operator is that you can treat the
+ iterator like a pointer.
+
+ Example:
+ \code
+ QValueList<int>::Iterator it = list.begin();
+ for( ; it != end(); ++it )
+ it->show();
+ \endcode
+*/
+
+/*!
+ \fn const T& QValueListConstIterator::operator*() const
+ Asterix operator. Returns a reference to the current iterator item.
+*/
+
+/*!
+ \fn QValueListConstIterator<T>& QValueListConstIterator::operator++()
+ Prefix ++ makes the succeeding item current and returns
+ an iterator pointing to the new current item.
+ The iterator can not check wether it reached the end of the list. Incrementing
+ the iterator as returned by end() causes undefined results.
+*/
+
+/*!
+ \fn QValueListConstIterator<T> QValueListConstIterator::operator++(int)
+ Postfix ++ makes the succeeding item current and returns
+ an iterator pointing to the new current item.
+ The iterator can not check wether it reached the end of the list. Incrementing
+ the iterator as returned by end() causes undefined results.
+*/
+
+/*!
+ \fn QValueListConstIterator<T>& QValueListConstIterator::operator--()
+ Prefix -- makes the previous item current and returns
+ an iterator pointing to the new current item.
+ The iterator can not check wether it reached the beginning of the list. Decrementing
+ the iterator as returned by begin() causes undefined results.
+*/
+
+/*!
+ \fn QValueListConstIterator<T> QValueListConstIterator::operator--(int)
+ Postfix -- makes the previous item current and returns
+ an iterator pointing to the new current item.
+ The iterator can not check wether it reached the beginning of the list. Decrementing
+ the iterator as returned by begin() causes undefined results.
+*/
+
+/*!
+ \fn bool QValueListConstIterator::operator==( const QValueListConstIterator<T>& it ) const
+ Compares both iterators and returns TRUE if they point to the same item.
+*/
+
+/*!
+ \fn bool QValueListConstIterator::operator!=( const QValueListConstIterator<T>& it ) const
+ Compares both iterators and returns TRUE if they point to different items.
+*/
diff --git a/qtools/qvector.doc b/qtools/qvector.doc
new file mode 100644
index 0000000..24309e3
--- /dev/null
+++ b/qtools/qvector.doc
@@ -0,0 +1,344 @@
+/****************************************************************************
+** $Id$
+**
+** QVector class documentation
+**
+** Copyright (C) 1992-2000 Trolltech AS. All rights reserved.
+**
+** This file is part of the Qt GUI Toolkit.
+**
+** This file may be distributed under the terms of the Q Public License
+** as defined by Trolltech AS of Norway and appearing in the file
+** LICENSE.QPL included in the packaging of this file.
+**
+** This file may be distributed and/or modified under the terms of the
+** GNU General Public License version 2 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.
+**
+** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
+** licenses may use this file in accordance with the Qt Commercial License
+** Agreement provided with the Software.
+**
+** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
+** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+**
+** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
+** information about Qt Commercial License Agreements.
+** See http://www.trolltech.com/qpl/ for QPL licensing information.
+** See http://www.trolltech.com/gpl/ for GPL licensing information.
+**
+** Contact info@trolltech.com if any conditions of this licensing are
+** not clear to you.
+**
+**********************************************************************/
+
+
+/*****************************************************************************
+ QVector documentation
+ *****************************************************************************/
+
+// BEING REVISED: ettrich
+/*!
+ \class QVector qvector.h
+
+ \brief The QVector class is a template collection class that
+ provides a vector (array).
+
+ \ingroup tools
+
+ QVector is implemented as a template class. Define a template
+ instance QVector\<X\> to create a vector that contains pointers to
+ X, or X*.
+
+ A vector is the same as an array. The main difference between
+ QVector and QArray is that QVector stores pointers to the elements,
+ while QArray stores the elements themselves (i.e. QArray is
+ value-based).
+
+ Unless where otherwise stated, all functions that remove items from
+ the vector will also delete the element pointed to if auto-deletion
+ is enabled - see setAutoDelete(). By default, auto-deletion is
+ disabled. This behaviour can be changed in a subclass by
+ reimplementing the virtual method deleteItem().
+
+ Functions that compares items, e.g. find() and sort(), will do so
+ using the virtual function compareItems(). The default
+ implementation of this function will only compare the absolute
+ pointer values. Reimplement compareItems() in a subclass to get
+ searching and sorting based on the item contents.
+
+ \sa \link collection.html Collection Classes\endlink, QArray
+*/
+
+/*!
+ \fn QVector::QVector()
+
+ Constructs a null vector.
+
+ \sa isNull()
+*/
+
+/*!
+ \fn QVector::QVector( 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 QVector::QVector( const QVector<type> &v )
+
+ Constructs a copy of \a v. Only the pointers are copied (i.e. shallow copy).
+*/
+
+/*!
+ \fn QVector::~QVector()
+
+ Removes all items from the vector, and destroys the vector itself.
+
+ \sa clear()
+*/
+
+/*!
+ \fn QVector<type> &QVector::operator=( const QVector<type> &v )
+
+ Assigns \a v to this vector and returns a reference to this vector.
+
+ This vector is first cleared, then all the items from \a v is copied
+ into this vector. Only the pointers are copied (i.e. shallow copy).
+
+ \sa clear()
+*/
+
+/*!
+ \fn type **QVector::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 QVector::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 QVector::count() const
+
+ Returns the number of items in the vector. The vector is empty if
+ count() == 0.
+
+ \sa isEmpty(), size()
+*/
+
+/*!
+ \fn bool QVector::isEmpty() const
+
+ Returns TRUE if the vector is empty, i.e. count() == 0, otherwise FALSE.
+
+ \sa count()
+*/
+
+/*!
+ \fn bool QVector::isNull() const
+
+ Returns TRUE if the vector is null, otherwise FALSE.
+
+ A null vector has size() == 0 and data() == 0.
+
+ \sa size()
+*/
+
+/*!
+ \fn bool QVector::resize( uint size )
+ Resizes (expands or shrinks) the vector to \a size elements. The array
+ becomes a null array if \a size == 0.
+
+ Any items in position \a size or beyond in the vector are removed.
+ New positions are initialized 0.
+
+ Returns TRUE if successful, or FALSE if the memory cannot be allocated.
+
+ \sa size(), isNull()
+*/
+
+/*!
+ \fn bool QVector::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.
+
+ \sa at()
+*/
+
+/*!
+ \fn bool QVector::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 unless \a i is out of range.
+
+ \sa take(), at()
+*/
+
+/*!
+ \fn type* QVector::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.
+
+ In contrast to remove(), this function does \e not call deleteItem()
+ for the removed item.
+
+ \sa remove(), at()
+*/
+
+/*!
+ \fn void QVector::clear()
+
+ Removes all items from the vector, and destroys the vector
+ itself.
+
+ The vector becomes a null vector.
+
+ \sa isNull()
+*/
+
+/*!
+ \fn bool QVector::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, or FALSE if the memory cannot be allocated
+ (only if a resize has been requested).
+
+ \sa resize(), insert(), isEmpty()
+*/
+
+/*!
+ \fn void QVector::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 QVector::bsearch( const type* d ) const
+
+ In a sorted array, finds the first occurrence of \a d using binary
+ search. For a sorted array, this is generally much faster than
+ find(), which does a linear search.
+
+ Returns the position of \a d, or -1 if \a d could not be found. \a d
+ may not be 0.
+
+ Compares items using the virtual function compareItems().
+
+ \sa sort(), find()
+*/
+
+
+/*!
+ \fn int QVector::findRef( const type *d, uint i ) const
+
+ Finds the first occurrence of the item pointer \a d in the vector,
+ using 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.
+
+ \sa find(), bsearch()
+*/
+
+/*!
+ \fn int QVector::find( const type *d, uint i ) const
+
+ Finds the first occurrence of item \a d in the vector, using 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 \e v, or -1 if \e v could not be found.
+
+ Compares items using the virtual function compareItems().
+
+ \sa findRef(), bsearch()
+*/
+
+
+/*!
+ \fn uint QVector::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 QVector::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 *QVector::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 *QVector::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 QVector::toList( QGList *list ) const
+
+ Copies all items in this vector to the list \a list. First, \a list
+ is cleared, then all items are appended to \a list.
+
+ \sa QList, QStack, QQueue
+*/
+