diff options
Diffstat (limited to 'doc/qdict.doc')
| -rw-r--r-- | doc/qdict.doc | 557 |
1 files changed, 557 insertions, 0 deletions
diff --git a/doc/qdict.doc b/doc/qdict.doc new file mode 100644 index 000000000..643fb8de6 --- /dev/null +++ b/doc/qdict.doc @@ -0,0 +1,557 @@ +/**************************************************************************** +** +** QDict and QDictIterator class documentation +** +** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be used under the terms of the GNU General +** Public License versions 2.0 or 3.0 as published by the Free +** Software Foundation and appearing in the files LICENSE.GPL2 +** and LICENSE.GPL3 included in the packaging of this file. +** Alternatively you may (at your option) use any later version +** of the GNU General Public License if such license has been +** publicly approved by Trolltech ASA (or its successors, if any) +** and the KDE Free Qt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing retquirements will be met: +** http://trolltech.com/products/qt/licenses/licensing/opensource/. +** If you are unsure which license is appropriate for your use, please +** review the following information: +** http://trolltech.com/products/qt/licenses/licensing/licensingoverview +** or contact the sales department at sales@trolltech.com. +** +** This file may be used under the terms of the Q Public License as +** defined by Trolltech ASA and appearing in the file LICENSE.QPL +** included in the packaging of this file. Licensees holding valid Qt +** Commercial licenses may use this file in accordance with the Qt +** Commercial License Agreement provided with the Software. +** +** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, +** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted +** herein. +** +**********************************************************************/ + + +/***************************************************************************** + QDict documentation + *****************************************************************************/ + +/*! + \class QDict + \brief The QDict class is a template class that provides a + dictionary based on QString keys. + + \ingroup collection + \ingroup tools + \mainclass + + \important autoDelete setAutoDelete + + QMap is an STL-compatible alternative to this class. + + QDict is implemented as a template class. Define a template + instance QDict\<X\> to create a dictionary that operates on + pointers to X (X *). + + A dictionary is a collection of key-value pairs. The key is a + QString used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + If you want to use non-Unicode, plain 8-bit \c char* keys, use the + QAsciiDict template. A QDict has the same performance as a + QAsciiDict. If you want to have a dictionary that maps QStrings to + QStrings use QMap. + + The size() of the dictionary is very important. In order to get + good performance, you should use a suitably large prime number. + Suitable means equal to or larger than the maximum expected number + of dictionary items. Size is set in the constructor but may be + changed with resize(). + + Items are inserted with insert(); 0 pointers cannot be inserted. + Items are removed with remove(). All the items in a dictionary can + be removed with clear(). The number of items in the dictionary is + returned by count(). If the dictionary contains no items isEmpty() + returns TRUE. You can change an item's value with replace(). Items + are looked up with operator[](), or with find() which return a + pointer to the value or 0 if the given key does not exist. You can + take an item out of the dictionary with take(). + + Calling setAutoDelete(TRUE) for a dictionary tells it to delete + items that are removed. The default behaviour is not to delete + items when they are removed. + + When an item is inserted, the key is converted (hashed) to an + integer index into an internal hash array. This makes lookup very + fast. + + Items with equal keys are allowed. When inserting two items with + the same key, only the last inserted item will be accessible (last + in, first out) until it is removed. + + The QDictIterator class can traverse the dictionary, but only in + an arbitrary order. Multiple iterators may independently traverse + the same dictionary. + + When inserting an item into a dictionary, only the pointer is + copied, not the item itself, i.e. a shallow copy is made. It is + possible to make the dictionary copy all of the item's data (a + deep copy) when an item is inserted. insert() calls the virtual + function QPtrCollection::newItem() for the item to be inserted. + Inherit a dictionary and reimplement newItem() if you want deep + copies. + + When removing a dictionary item, the virtual function + QPtrCollection::deleteItem() is called. QDict's default + implementation is to delete the item if auto-deletion is enabled. + + Example #1: + \code + QDict<QLineEdit> fields; // QString keys, QLineEdit* values + fields.insert( "forename", new QLineEdit( this ) ); + fields.insert( "surname", new QLineEdit( this ) ); + + fields["forename"]->setText( "Homer" ); + fields["surname"]->setText( "Simpson" ); + + QDictIterator<QLineEdit> it( fields ); // See QDictIterator + for( ; it.current(); ++it ) + cout << it.currentKey() << ": " << it.current()->text() << endl; + cout << endl; + + if ( fields["forename"] && fields["surname"] ) + cout << fields["forename"]->text() << " " + << fields["surname"]->text() << endl; // Prints "Homer Simpson" + + fields.remove( "forename" ); // Does not delete the line edit + if ( ! fields["forename"] ) + cout << "forename is not in the dictionary" << endl; + \endcode + In this example we use a dictionary to keep track of the line + edits we're using. We insert each line edit into the dictionary + with a unique name and then access the line edits via the + dictionary. + + Example #2: + \code + QStringList styleList = QStyleFactory::styles(); + styleList.sort(); + QDict<int> letterDict( 17, FALSE ); + for ( QStringList::Iterator it = styleList.begin(); it != styleList.end(); ++it ) { + QString styleName = *it; + QString styleAccel = styleName; + if ( letterDict[styleAccel.left(1)] ) { + for ( uint i = 0; i < styleAccel.length(); i++ ) { + if ( ! letterDict[styleAccel.mid( i, 1 )] ) { + styleAccel = styleAccel.insert( i, '&' ); + letterDict.insert(styleAccel.mid( i, 1 ), (const int *)1); + break; + } + } + } else { + styleAccel = "&" + styleAccel; + letterDict.insert(styleAccel.left(1), (const int *)1); + } + (void) new QAction( styleName, QIconSet(), styleAccel, parent ); + } + \endcode + In the example we are using the dictionary to provide fast random + access to the keys, and we don't care what the values are. The + example is used to generate a menu of QStyles, each with a unique + accelerator key (or no accelerator if there are no unused letters + left). + + We first obtain the list of available styles, then sort them so + that the menu items will be ordered alphabetically. Next we create + a dictionary of int pointers. The keys in the dictionary are each + one character long, representing letters that have been used for + accelerators. We iterate through our list of style names. If the + first letter of the style name is in the dictionary, i.e. has been + used, we iterate over all the characters in the style name to see + if we can find a letter that hasn't been used. If we find an + unused letter we put the accelerator ampersand (&) in front of it + and add that letter to the dictionary. If we can't find an unused + letter the style will simply have no accelerator. If the first + letter of the style name is not in the dictionary we use it for + the accelerator and add it to the dictionary. Finally we create a + QAction for each style. + + \sa QDictIterator, QAsciiDict, QIntDict, QPtrDict +*/ + + +/*! + \fn QDict::QDict( int size, bool caseSensitive ) + + Constructs a dictionary optimized for less than \a size entries. + + We recommend setting \a size to a suitably large prime number + (e.g. a prime that's slightly larger than the expected number of + entries). This makes the hash distribution better which will lead + to faster lookup. + + If \a caseSensitive is TRUE (the default), keys which differ only + by case are considered different. +*/ + +/*! + \fn QDict::QDict( const QDict<type> &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn QDict::~QDict() + + Removes all items from the dictionary and destroys it. If + setAutoDelete() is TRUE, each value is deleted. All iterators that + access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QDict<type> &QDict::operator=(const QDict<type> &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared, then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint 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 hash table to \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; + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void QDict::insert( const QString &key, const type *item ) + + Inserts the key \a key with value \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void QDict::replace( const QString &key, const type *item ) + + Replaces the value of the key, \a key with \a item. + + If the item does not already exist, it will be inserted. + + \a item may not be 0. + + Equivalent to: + \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 item + that was inserted will be replaced. + + \sa insert() +*/ + +/*! + \fn bool QDict::remove( const QString &key ) + + Removes the item with \a key from the dictionary. Returns TRUE if + successful, i.e. if the item is in the dictionary; otherwise + returns FALSE. + + If there are two or more items with equal keys, then the last item + that was inserted will be removed. + + The removed item is deleted if \link + QPtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary's traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *QDict::take( const QString &key ) + + Takes the item with \a key out of the dictionary without deleting + it (even if \link QPtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the last item + that was inserted will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void QDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + QPtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that operate on the dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *QDict::find( const QString &key ) const + + Returns the item with key \a key, or 0 if the key does not exist + in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *QDict::operator[]( const QString &key ) const + + Returns the item with key \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void QDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& QDict::read( QDataStream &s, QPtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& QDict::write( QDataStream &s, QPtrCollection::Item ) const + + Writes a dictionary item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/***************************************************************************** + 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*). + + The traversal order is arbitrary; when we speak of the "first", + "last" and "next" item we are talking in terms of this arbitrary + order. + + Multiple iterators may independently traverse the same dictionary. + A QDict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, QDict + updates all iterators that are referring to the removed item to + point to the next item in the (arbitrary) traversal order. + + Example: + \code + QDict<QLineEdit> fields; + fields.insert( "forename", new QLineEdit( this ) ); + fields.insert( "surname", new QLineEdit( this ) ); + fields.insert( "age", new QLineEdit( this ) ); + + fields["forename"]->setText( "Homer" ); + fields["surname"]->setText( "Simpson" ); + fields["age"]->setText( "45" ); + + QDictIterator<QLineEdit> it( fields ); + for( ; it.current(); ++it ) + cout << it.currentKey() << ": " << it.current()->text() << endl; + cout << endl; + + // Output (random order): + // age: 45 + // surname: Simpson + // forename: Homer + \endcode + In the example we insert some pointers to line edits into a + dictionary, then iterate over the dictionary printing the strings + associated with the line edits. + + \sa QDict +*/ + +/*! + \fn QDictIterator::QDictIterator( const QDict<type> &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point to the first item in the dictionary, \a dict. First + in this context means first in the arbitrary traversal order. +*/ + +/*! + \fn QDictIterator::~QDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint QDictIterator::count() const + + Returns the number of items in the dictionary over which the + iterator is operating. + + \sa isEmpty() +*/ + +/*! + \fn bool QDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *QDictIterator::toFirst() + + Resets the iterator, making the first item the first current item. + First in this context means first in the arbitrary traversal + order. Returns a pointer to this item. + + If the dictionary is empty it sets the current item to 0 and + returns 0. +*/ + +/*! + \fn type *QDictIterator::operator*() + \internal +*/ + +/*! + \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's value. +*/ + +/*! + \fn QString QDictIterator::currentKey() const + + Returns the current iterator item's key. +*/ + +/*! + \fn type *QDictIterator::operator()() + + Makes the next item current and returns the original current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *QDictIterator::operator++() + + Prefix ++ makes the next item current and returns the new current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *QDictIterator::operator+=( uint jump ) + \internal + Sets the current item to the item \a jump positions after the current item, + and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is empty, + it sets the current item to 0 and returns 0. +*/ |