/**************************************************************************** | |
** | |
** 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. | |
*/ |