diff options
Diffstat (limited to 'doc/qasciidict.doc')
| -rw-r--r-- | doc/qasciidict.doc | 475 |
1 files changed, 475 insertions, 0 deletions
diff --git a/doc/qasciidict.doc b/doc/qasciidict.doc new file mode 100644 index 0000000..7667684 --- /dev/null +++ b/doc/qasciidict.doc @@ -0,0 +1,475 @@ +/**************************************************************************** +** +** QAsciiDict and QAsciiDictIterator class documentation +** +** Copyright (C) 1992-2008 Trolltech ASA. All rights reserved. +** +** This file is part of the Qt GUI Toolkit. +** +** This file may be used under the terms of the GNU General +** Public License versions 2.0 or 3.0 as published by the Free +** Software Foundation and appearing in the files LICENSE.GPL2 +** and LICENSE.GPL3 included in the packaging of this file. +** Alternatively you may (at your option) use any later version +** of the GNU General Public License if such license has been +** publicly approved by Trolltech ASA (or its successors, if any) +** and the KDE Free Qt Foundation. +** +** Please review the following information to ensure GNU General +** Public Licensing requirements will be met: +** http://trolltech.com/products/qt/licenses/licensing/opensource/. +** If you are unsure which license is appropriate for your use, please +** review the following information: +** http://trolltech.com/products/qt/licenses/licensing/licensingoverview +** or contact the sales department at sales@trolltech.com. +** +** This file may be used under the terms of the Q Public License as +** defined by Trolltech ASA and appearing in the file LICENSE.QPL +** included in the packaging of this file. Licensees holding valid Qt +** Commercial licenses may use this file in accordance with the Qt +** Commercial License Agreement provided with the Software. +** +** This file is provided "AS IS" with NO WARRANTY OF ANY KIND, +** INCLUDING THE WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR +** A PARTICULAR PURPOSE. Trolltech reserves all rights not granted +** herein. +** +**********************************************************************/ + + +/***************************************************************************** + QAsciiDict documentation + *****************************************************************************/ + +/*! + \class QAsciiDict qasciidict.h + \brief The QAsciiDict class is a template class that provides a dictionary based on char* keys. + + \ingroup collection + \ingroup tools + + \important autoDelete setAutoDelete + + QAsciiDict is implemented as a template class. Define a template + instance QAsciiDict\<X\> to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is a + char* used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + QAsciiDict cannot handle Unicode keys; use the QDict template + instead, which uses \l QString keys. A QDict has the same + performace as a QAsciiDict. + + Example: + \code + QAsciiDict<QLineEdit> fields; // char* keys, QLineEdit* values + fields.insert( "forename", new QLineEdit( this ) ); + fields.insert( "surname", new QLineEdit( this ) ); + + fields["forename"]->setText( "Homer" ); + fields["surname"]->setText( "Simpson" ); + + QAsciiDictIterator<QLineEdit> it( fields ); // See QAsciiDictIterator + 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. See QPtrDict, QIntDict and QDict. + + See QDict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa QAsciiDictIterator, QDict, QIntDict, QPtrDict, + \link collection.html Collection Classes\endlink +*/ + + +/*! + \fn QAsciiDict::QAsciiDict( int size, bool caseSensitive, bool copyKeys ) + + Constructs a dictionary optimized for less than \a size entries. + + We recommend setting \a size to a suitably large prime number (a + bit larger than the expected number of entries). This makes the + hash distribution better and will improve lookup performance. + + When \a caseSensitive is TRUE (the default) QAsciiDict treats + "abc" and "Abc" as different keys; when it is FALSE "abc" and + "Abc" are the same. Case-insensitive comparison only considers the + 26 letters in US-ASCII. + + If \a copyKeys is TRUE (the default), the dictionary copies keys + using strcpy(); if it is FALSE, the dictionary just copies the + pointers. +*/ + +/*! + \fn QAsciiDict::QAsciiDict( const QAsciiDict<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 QAsciiDict::~QAsciiDict() + + Removes all items from the dictionary and destroys it. + + The items are deleted if auto-delete is enabled. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn QAsciiDict<type> &QAsciiDict::operator=(const QAsciiDict<type> &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy) unless newItem() has been reimplemented(). +*/ + +/*! + \fn uint QAsciiDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint QAsciiDict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void QAsciiDict::resize( uint newsize ) + + Changes the size of the hashtable to \a newsize. The contents of + the dictionary are preserved but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool QAsciiDict::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0; + otherwise it returns FALSE. + + \sa count() +*/ + +/*! + \fn void QAsciiDict::insert( const char *key, const type *item ) + + Inserts the \a key with the \a item into the dictionary. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void QAsciiDict::replace( const char *key, const type *item ) + + Replaces an item that has a key equal to \a key with \a item. + + If the item does not already exist, it will be inserted. + + \a item may not be 0. + + Equivalent to: + \code + QAsciiDict<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 most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool QAsciiDict::remove( const char *key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if the key existed in the + dictionary; otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + 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 traversal order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *QAsciiDict::take( const char *key ) + + Takes the item associated 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 most + recently inserted item will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary traversal order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void QAsciiDict::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 dictionary are reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *QAsciiDict::find( const char *key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + This function uses an internal hashing algorithm to optimize + lookup. + + If there are two or more items with equal keys, then the item that + was most recently inserted will be found. + + Equivalent to the [] operator. + + \sa operator[]() +*/ + +/*! + \fn type *QAsciiDict::operator[]( const char *key ) const + + Returns the item associated with \a key, or 0 if the key does + not exist in the dictionary. + + This function uses an internal hashing algorithm to optimize + lookup. + + If there are two or more items with equal keys, then the item that + was most recently inserted will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void QAsciiDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& QAsciiDict::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& QAsciiDict::write( QDataStream &s, + QPtrCollection::Item ) const + + Writes a dictionary item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/***************************************************************************** + QAsciiDictIterator documentation + *****************************************************************************/ + +/*! + \class QAsciiDictIterator qasciidict.h + \brief The QAsciiDictIterator class provides an iterator for QAsciiDict collections. + + \ingroup collection + \ingroup tools + + QAsciiDictIterator is implemented as a template class. Define a + template instance QAsciiDictIterator\<X\> to create a dictionary + iterator that operates on QAsciiDict\<X\> (dictionary of X*). + + Example: + \code + QAsciiDict<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" ); + + QAsciiDictIterator<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 line edits into a dictionary, then + iterate over the dictionary printing the strings associated with + those line edits. + + Note that the traversal order is arbitrary; you are not guaranteed + any particular order. + + Multiple iterators may independently traverse the same dictionary. + A QAsciiDict knows about all the iterators that are operating on + the dictionary. When an item is removed from the dictionary, + QAsciiDict updates all the iterators that are referring to the + removed item to point to the next item in the (arbitrary) + traversal order. + + \sa QAsciiDict +*/ + +/*! + \fn QAsciiDictIterator::QAsciiDictIterator( const QAsciiDict<type> &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point on the first item in the \a dict. +*/ + +/*! + \fn QAsciiDictIterator::~QAsciiDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint QAsciiDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates over. + + \sa isEmpty() +*/ + +/*! + \fn bool QAsciiDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty, i.e. count() == 0, + otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn type *QAsciiDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. If the dictionary is + empty it sets the current item to 0 and returns 0. +*/ + +/*! + \fn QAsciiDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *QAsciiDictIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn const char *QAsciiDictIterator::currentKey() const + + Returns a pointer to the key for the current iterator item. +*/ + +/*! + \fn type *QAsciiDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *QAsciiDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *QAsciiDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item, and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ |