diff options
Diffstat (limited to 'qtools')
| -rw-r--r-- | qtools/Doxyfile | 19 | ||||
| -rw-r--r-- | qtools/qarray.doc | 486 | ||||
| -rw-r--r-- | qtools/qdict.doc | 492 | ||||
| -rw-r--r-- | qtools/qintdict.doc | 475 | ||||
| -rw-r--r-- | qtools/qlist.doc | 1048 | ||||
| -rw-r--r-- | qtools/qptrdict.doc | 486 | ||||
| -rw-r--r-- | qtools/qsortedlist.doc | 94 | ||||
| -rw-r--r-- | qtools/qstack.doc | 135 | ||||
| -rw-r--r-- | qtools/qstrlist.doc | 5 | ||||
| -rw-r--r-- | qtools/qtl.doc | 249 | ||||
| -rw-r--r-- | qtools/qvaluelist.doc | 772 | ||||
| -rw-r--r-- | qtools/qvector.doc | 344 |
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 +*/ + |