diff options
Diffstat (limited to 'doc/src/q3intdict.qdoc')
| -rw-r--r-- | doc/src/q3intdict.qdoc | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/doc/src/q3intdict.qdoc b/doc/src/q3intdict.qdoc new file mode 100644 index 0000000..8f0aabf --- /dev/null +++ b/doc/src/q3intdict.qdoc @@ -0,0 +1,390 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 2.1 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 2.1 requirements +** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. +** +** In addition, as a special exception, Nokia gives you certain +** additional rights. These rights are described in the Nokia Qt LGPL +** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this +** package. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 3.0 as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL included in the +** packaging of this file. Please review the following information to +** ensure the GNU General Public License version 3.0 requirements will be +** met: http://www.gnu.org/copyleft/gpl.html. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Q3IntDict + \brief The Q3IntDict class is a template class that provides a dictionary based on long keys.\ + \compat + + Q3IntDict is implemented as a template class. Define a template + instance Q3IntDict\<X\> to create a dictionary that operates on + pointers to X (X*). + + A dictionary is a collection of key-value pairs. The key is an \c + long used for insertion, removal and lookup. The value is a + pointer. Dictionaries provide very fast insertion and lookup. + + Example: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0 + + See Q3Dict for full details, including the choice of dictionary + size, and how deletions are handled. + + \sa Q3IntDictIterator, Q3Dict, Q3AsciiDict, Q3PtrDict +*/ + + +/*! + \fn Q3IntDict::Q3IntDict( int size ) + + Constructs a dictionary using an internal hash array of size \a + size. + + Setting \a size to a suitably large prime number (equal to or + greater than the expected number of entries) makes the hash + distribution better which leads to faster lookup. +*/ + +/*! + \fn Q3IntDict::Q3IntDict( const Q3IntDict<type> &dict ) + + Constructs a copy of \a dict. + + Each item in \a dict is inserted into this dictionary. Only the + pointers are copied (shallow copy). +*/ + +/*! + \fn Q3IntDict::~Q3IntDict() + + Removes all items from the dictionary and destroys it. + + All iterators that access this dictionary will be reset. + + \sa setAutoDelete() +*/ + +/*! + \fn Q3IntDict<type> &Q3IntDict::operator=(const Q3IntDict<type> &dict) + + Assigns \a dict to this dictionary and returns a reference to this + dictionary. + + This dictionary is first cleared and then each item in \a dict is + inserted into this dictionary. Only the pointers are copied + (shallow copy), unless newItem() has been reimplemented. +*/ + +/*! + \fn uint Q3IntDict::count() const + + Returns the number of items in the dictionary. + + \sa isEmpty() +*/ + +/*! + \fn uint Q3IntDict::size() const + + Returns the size of the internal hash array (as specified in the + constructor). + + \sa count() +*/ + +/*! + \fn void Q3IntDict::resize( uint newsize ) + + Changes the size of the hashtable to \a newsize. The contents of + the dictionary are preserved, but all iterators on the dictionary + become invalid. +*/ + +/*! + \fn bool Q3IntDict::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise returns FALSE. + + \sa count() +*/ + +/*! + \fn void Q3IntDict::insert( long key, const type *item ) + + Insert item \a item into the dictionary using key \a key. + + Multiple items can have the same key, in which case only the last + item will be accessible using \l operator[](). + + \a item may not be 0. + + \sa replace() +*/ + +/*! + \fn void Q3IntDict::replace( long key, const type *item ) + + If the dictionary has key \a key, this key's item is replaced with + \a item. If the dictionary doesn't contain key \a key, \a item is + inserted into the dictionary using key \a key. + + \a item may not be 0. + + Equivalent to: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1 + + If there are two or more items with equal keys, then the most + recently inserted item will be replaced. + + \sa insert() +*/ + +/*! + \fn bool Q3IntDict::remove( long key ) + + Removes the item associated with \a key from the dictionary. + Returns TRUE if successful, i.e. if the \a key is in the + dictionary; otherwise returns FALSE. + + If there are two or more items with equal keys, then the most + recently inserted item will be removed. + + The removed item is deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that refer to the removed item will be + set to point to the next item in the dictionary's traversal + order. + + \sa take(), clear(), setAutoDelete() +*/ + +/*! + \fn type *Q3IntDict::take( long key ) + + Takes the item associated with \a key out of the dictionary + without deleting it (even if \link Q3PtrCollection::setAutoDelete() + auto-deletion\endlink is enabled). + + If there are two or more items with equal keys, then the most + recently inserted item will be taken. + + Returns a pointer to the item taken out, or 0 if the key does not + exist in the dictionary. + + All dictionary iterators that refer to the taken item will be set + to point to the next item in the dictionary's traversing order. + + \sa remove(), clear(), setAutoDelete() +*/ + +/*! + \fn void Q3IntDict::clear() + + Removes all items from the dictionary. + + The removed items are deleted if \link + Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled. + + All dictionary iterators that access this dictionary will be reset. + + \sa remove(), take(), setAutoDelete() +*/ + +/*! + \fn type *Q3IntDict::find( long key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to operator[]. + + \sa operator[]() +*/ + +/*! + \fn type *Q3IntDict::operator[]( long key ) const + + Returns the item associated with \a key, or 0 if the key does not + exist in the dictionary. + + If there are two or more items with equal keys, then the most + recently inserted item will be found. + + Equivalent to the find() function. + + \sa find() +*/ + +/*! + \fn void Q3IntDict::statistics() const + + Debugging-only function that prints out the dictionary + distribution using qDebug(). +*/ + +/*! + \fn QDataStream& Q3IntDict::read( QDataStream &s, Q3PtrCollection::Item &item ) + + Reads a dictionary item from the stream \a s and returns a + reference to the stream. + + The default implementation sets \a item to 0. + + \sa write() +*/ + +/*! + \fn QDataStream& Q3IntDict::write( QDataStream &s, Q3PtrCollection::Item item ) const + + Writes a dictionary \a item to the stream \a s and returns a + reference to the stream. + + \sa read() +*/ + +/*! + \class Q3IntDictIterator + \brief The Q3IntDictIterator class provides an iterator for Q3IntDict collections. + \compat + + Q3IntDictIterator is implemented as a template class. Define a + template instance Q3IntDictIterator\<X\> to create a dictionary + iterator that operates on Q3IntDict\<X\> (dictionary of X*). + + Example: + \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2 + + Note that the traversal order is arbitrary; you are not guaranteed the + order shown above. + + Multiple iterators may independently traverse the same dictionary. + A Q3IntDict knows about all the iterators that are operating on the + dictionary. When an item is removed from the dictionary, Q3IntDict + updates all iterators that refer the removed item to point to the + next item in the traversal order. + + \sa Q3IntDict +*/ + +/*! + \fn Q3IntDictIterator::Q3IntDictIterator( const Q3IntDict<type> &dict ) + + Constructs an iterator for \a dict. The current iterator item is + set to point to the 'first' item in the \a dict. The first item + refers to the first item in the dictionary's arbitrary internal + ordering. +*/ + +/*! + \fn Q3IntDictIterator::~Q3IntDictIterator() + + Destroys the iterator. +*/ + +/*! + \fn uint Q3IntDictIterator::count() const + + Returns the number of items in the dictionary this iterator + operates over. + + \sa isEmpty() +*/ + +/*! + \fn bool Q3IntDictIterator::isEmpty() const + + Returns TRUE if the dictionary is empty; otherwise eturns FALSE. + + \sa count() +*/ + +/*! + \fn type *Q3IntDictIterator::toFirst() + + Sets the current iterator item to point to the first item in the + dictionary and returns a pointer to the item. The first item + refers to the first item in the dictionary's arbitrary internal + ordering. If the dictionary is empty it sets the current item to + 0 and returns 0. +*/ + +/*! + \fn Q3IntDictIterator::operator type *() const + + Cast operator. Returns a pointer to the current iterator item. + Same as current(). +*/ + +/*! + \fn type *Q3IntDictIterator::current() const + + Returns a pointer to the current iterator item. +*/ + +/*! + \fn long Q3IntDictIterator::currentKey() const + + Returns the key for the current iterator item. +*/ + +/*! + \fn type *Q3IntDictIterator::operator()() + + Makes the succeeding item current and returns the original current + item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntDictIterator::operator++() + + Prefix ++ makes the succeeding item current and returns the new + current item. + + If the current iterator item was the last item in the dictionary + or if it was 0, 0 is returned. +*/ + +/*! + \fn type *Q3IntDictIterator::operator+=( uint jump ) + + Sets the current item to the item \a jump positions after the + current item, and returns a pointer to that item. + + If that item is beyond the last item or if the dictionary is + empty, it sets the current item to 0 and returns 0. +*/ |