| /**************************************************************************** |
| ** |
| ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). |
| ** All rights reserved. |
| ** Contact: Nokia Corporation (qt-info@nokia.com) |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** GNU Free Documentation License |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. |
| ** |
| ** Other Usage |
| ** Alternatively, this file may be used in accordance with the terms |
| ** and conditions contained in a signed written agreement between you |
| ** and Nokia. |
| ** |
| ** |
| ** |
| ** |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \class Q3PtrDict |
| \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys. |
| \compat |
| |
| Q3PtrDict is implemented as a template class. Define a template |
| instance Q3PtrDict\<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 |
| void* 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_q3ptrdict.cpp 0 |
| In this example we use a dictionary to add an extra property (a |
| char*) to the line edits we're using. |
| |
| See Q3Dict for full details, including the choice of dictionary |
| size, and how deletions are handled. |
| |
| \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict |
| */ |
| |
| |
| /*! |
| \fn Q3PtrDict::Q3PtrDict( int size ) |
| |
| Constructs a dictionary using an internal hash array with the 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 and improves lookup performance. |
| */ |
| |
| /*! |
| \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict<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 Q3PtrDict::~Q3PtrDict() |
| |
| Removes all items from the dictionary and destroys it. |
| |
| All iterators that access this dictionary will be reset. |
| |
| \sa setAutoDelete() |
| */ |
| |
| /*! |
| \fn Q3PtrDict<type> &Q3PtrDict::operator=(const Q3PtrDict<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 the dictionary. Only the pointers are copied |
| (shallow copy), unless newItem() has been reimplemented. |
| */ |
| |
| /*! |
| \fn uint Q3PtrDict::count() const |
| |
| Returns the number of items in the dictionary. |
| |
| \sa isEmpty() |
| */ |
| |
| /*! |
| \fn uint Q3PtrDict::size() const |
| |
| Returns the size of the internal hash table (as specified in the |
| constructor). |
| |
| \sa count() |
| */ |
| |
| /*! |
| \fn void Q3PtrDict::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 Q3PtrDict::isEmpty() const |
| |
| Returns TRUE if the dictionary is empty; otherwise returns FALSE. |
| |
| \sa count() |
| */ |
| |
| /*! |
| \fn void Q3PtrDict::insert( void *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 Q3PtrDict::replace( void *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_q3ptrdict.cpp 1 |
| |
| If there are two or more items with equal keys, then the most |
| recently inserted item will be replaced. |
| |
| \sa insert() |
| */ |
| |
| /*! |
| \fn bool Q3PtrDict::remove( void *key ) |
| |
| Removes the item associated with \a key from the dictionary. |
| Returns TRUE if successful, i.e. if \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 traversal order. |
| |
| \sa take(), clear(), setAutoDelete() |
| */ |
| |
| /*! |
| \fn type *Q3PtrDict::take( void *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 removed. |
| |
| 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 Q3PtrDict::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 *Q3PtrDict::find( void *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 *Q3PtrDict::operator[]( void *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 Q3PtrDict::statistics() const |
| |
| Debugging-only function that prints out the dictionary |
| distribution using qDebug(). |
| */ |
| |
| /*! |
| \fn QDataStream& Q3PtrDict::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& Q3PtrDict::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 Q3PtrDictIterator |
| \brief The Q3PtrDictIterator class provides an iterator for Q3PtrDict collections. |
| \compat |
| |
| Q3PtrDictIterator is implemented as a template class. Define a |
| template instance Q3PtrDictIterator\<X\> to create a dictionary |
| iterator that operates on Q3PtrDict\<X\> (dictionary of X*). |
| |
| Example: |
| \snippet doc/src/snippets/code/doc_src_q3ptrdict.cpp 2 |
| In the example we insert some line edits into a dictionary, |
| associating a string with each. We then iterate over the |
| dictionary printing the associated strings. |
| |
| Multiple iterators may independently traverse the same dictionary. |
| A Q3PtrDict knows about all the iterators that are operating on the |
| dictionary. When an item is removed from the dictionary, Q3PtrDict |
| updates all iterators that refer the removed item to point to the |
| next item in the traversing order. |
| |
| \sa Q3PtrDict |
| */ |
| |
| /*! |
| \fn Q3PtrDictIterator::Q3PtrDictIterator( const Q3PtrDict<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 Q3PtrDictIterator::~Q3PtrDictIterator() |
| |
| Destroys the iterator. |
| */ |
| |
| /*! |
| \fn uint Q3PtrDictIterator::count() const |
| |
| Returns the number of items in the dictionary this iterator |
| operates on. |
| |
| \sa isEmpty() |
| */ |
| |
| /*! |
| \fn bool Q3PtrDictIterator::isEmpty() const |
| |
| Returns TRUE if the dictionary is empty; otherwise returns FALSE. |
| |
| \sa count() |
| */ |
| |
| /*! |
| \fn type *Q3PtrDictIterator::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 Q3PtrDictIterator::operator type *() const |
| |
| Cast operator. Returns a pointer to the current iterator item. |
| Same as current(). |
| */ |
| |
| /*! |
| \fn type *Q3PtrDictIterator::current() const |
| |
| Returns a pointer to the current iterator item's value. |
| */ |
| |
| /*! |
| \fn void *Q3PtrDictIterator::currentKey() const |
| |
| Returns the current iterator item's key. |
| */ |
| |
| /*! |
| \fn type *Q3PtrDictIterator::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 *Q3PtrDictIterator::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 *Q3PtrDictIterator::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. |
| */ |