doc/src/q3intdict.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  15 **
  16 ** GNU Lesser General Public License Usage
  17 ** Alternatively, this file may be used under the terms of the GNU Lesser
  18 ** General Public License version 2.1 as published by the Free Software
  19 ** Foundation and appearing in the file LICENSE.LGPL included in the
  20 ** packaging of this file.  Please review the following information to
  21 ** ensure the GNU Lesser General Public License version 2.1 requirements
  22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  23 **
  24 ** In addition, as a special exception, Nokia gives you certain additional
  25 ** rights.  These rights are described in the Nokia Qt LGPL Exception
  26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \class Q3IntDict
  44     \brief The Q3IntDict class is a template class that provides a dictionary based on long keys.\
  45     \compat
  46
  47     Q3IntDict is implemented as a template class. Define a template
  48     instance Q3IntDict\<X\> to create a dictionary that operates on
  49     pointers to X (X*).
  50
  51     A dictionary is a collection of key-value pairs. The key is an \c
  52     long used for insertion, removal and lookup. The value is a
  53     pointer. Dictionaries provide very fast insertion and lookup.
  54
  55     Example:
  56     \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 0
  57
  58     See Q3Dict for full details, including the choice of dictionary
  59     size, and how deletions are handled.
  60
  61     \sa Q3IntDictIterator, Q3Dict, Q3AsciiDict, Q3PtrDict
  62 */
  63
  64
  65 /*!
  66     \fn Q3IntDict::Q3IntDict( int size )
  67
  68     Constructs a dictionary using an internal hash array of size \a
  69     size.
  70
  71     Setting \a size to a suitably large prime number (equal to or
  72     greater than the expected number of entries) makes the hash
  73     distribution better which leads to faster lookup.
  74 */
  75
  76 /*!
  77     \fn Q3IntDict::Q3IntDict( const Q3IntDict<type> &dict )
  78
  79     Constructs a copy of \a dict.
  80
  81     Each item in \a dict is inserted into this dictionary. Only the
  82     pointers are copied (shallow copy).
  83 */
  84
  85 /*!
  86     \fn Q3IntDict::~Q3IntDict()
  87
  88     Removes all items from the dictionary and destroys it.
  89
  90     All iterators that access this dictionary will be reset.
  91
  92     \sa setAutoDelete()
  93 */
  94
  95 /*!
  96     \fn Q3IntDict<type> &Q3IntDict::operator=(const Q3IntDict<type> &dict)
  97
  98     Assigns \a dict to this dictionary and returns a reference to this
  99     dictionary.
 100
 101     This dictionary is first cleared and then each item in \a dict is
 102     inserted into this dictionary. Only the pointers are copied
 103     (shallow copy), unless newItem() has been reimplemented.
 104 */
 105
 106 /*!
 107     \fn uint Q3IntDict::count() const
 108
 109     Returns the number of items in the dictionary.
 110
 111     \sa isEmpty()
 112 */
 113
 114 /*!
 115     \fn uint Q3IntDict::size() const
 116
 117     Returns the size of the internal hash array (as specified in the
 118     constructor).
 119
 120     \sa count()
 121 */
 122
 123 /*!
 124     \fn void Q3IntDict::resize( uint newsize )
 125
 126     Changes the size of the hashtable to \a newsize. The contents of
 127     the dictionary are preserved, but all iterators on the dictionary
 128     become invalid.
 129 */
 130
 131 /*!
 132     \fn bool Q3IntDict::isEmpty() const
 133
 134     Returns TRUE if the dictionary is empty; otherwise returns FALSE.
 135
 136     \sa count()
 137 */
 138
 139 /*!
 140     \fn void Q3IntDict::insert( long key, const type *item )
 141
 142     Insert item \a item into the dictionary using key \a key.
 143
 144     Multiple items can have the same key, in which case only the last
 145     item will be accessible using \l operator[]().
 146
 147     \a item may not be 0.
 148
 149     \sa replace()
 150 */
 151
 152 /*!
 153     \fn void Q3IntDict::replace( long key, const type *item )
 154
 155     If the dictionary has key \a key, this key's item is replaced with
 156     \a item. If the dictionary doesn't contain key \a key, \a item is
 157     inserted into the dictionary using key \a key.
 158
 159     \a item may not be 0.
 160
 161     Equivalent to:
 162     \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 1
 163
 164     If there are two or more items with equal keys, then the most
 165     recently inserted item will be replaced.
 166
 167     \sa insert()
 168 */
 169
 170 /*!
 171     \fn bool Q3IntDict::remove( long key )
 172
 173     Removes the item associated with \a key from the dictionary.
 174     Returns TRUE if successful, i.e. if the \a key is in the
 175     dictionary; otherwise returns FALSE.
 176
 177     If there are two or more items with equal keys, then the most
 178     recently inserted item will be removed.
 179
 180     The removed item is deleted if \link
 181     Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
 182
 183     All dictionary iterators that refer to the removed item will be
 184     set to point to the next item in the dictionary's traversal
 185     order.
 186
 187     \sa take(), clear(), setAutoDelete()
 188 */
 189
 190 /*!
 191     \fn type *Q3IntDict::take( long key )
 192
 193     Takes the item associated with \a key out of the dictionary
 194     without deleting it (even if \link Q3PtrCollection::setAutoDelete()
 195     auto-deletion\endlink is enabled).
 196
 197     If there are two or more items with equal keys, then the most
 198     recently inserted item will be taken.
 199
 200     Returns a pointer to the item taken out, or 0 if the key does not
 201     exist in the dictionary.
 202
 203     All dictionary iterators that refer to the taken item will be set
 204     to point to the next item in the dictionary's traversing order.
 205
 206     \sa remove(), clear(), setAutoDelete()
 207 */
 208
 209 /*!
 210     \fn void Q3IntDict::clear()
 211
 212     Removes all items from the dictionary.
 213
 214     The removed items are deleted if \link
 215     Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.
 216
 217     All dictionary iterators that access this dictionary will be reset.
 218
 219     \sa remove(), take(), setAutoDelete()
 220 */
 221
 222 /*!
 223     \fn type *Q3IntDict::find( long key ) const
 224
 225     Returns the item associated with \a key, or 0 if the key does not
 226     exist in the dictionary.
 227
 228     If there are two or more items with equal keys, then the most
 229     recently inserted item will be found.
 230
 231     Equivalent to operator[].
 232
 233     \sa operator[]()
 234 */
 235
 236 /*!
 237     \fn type *Q3IntDict::operator[]( long key ) const
 238
 239     Returns the item associated with \a key, or 0 if the key does not
 240     exist in the dictionary.
 241
 242     If there are two or more items with equal keys, then the most
 243     recently inserted item will be found.
 244
 245     Equivalent to the find() function.
 246
 247     \sa find()
 248 */
 249
 250 /*!
 251     \fn void Q3IntDict::statistics() const
 252
 253     Debugging-only function that prints out the dictionary
 254     distribution using qDebug().
 255 */
 256
 257 /*!
 258     \fn QDataStream& Q3IntDict::read( QDataStream &s, Q3PtrCollection::Item &item )
 259
 260     Reads a dictionary item from the stream \a s and returns a
 261     reference to the stream.
 262
 263     The default implementation sets \a item to 0.
 264
 265     \sa write()
 266 */
 267
 268 /*!
 269     \fn QDataStream& Q3IntDict::write( QDataStream &s, Q3PtrCollection::Item item ) const
 270
 271     Writes a dictionary \a item to the stream \a s and returns a
 272     reference to the stream.
 273
 274     \sa read()
 275 */
 276
 277 /*!
 278     \class Q3IntDictIterator
 279     \brief The Q3IntDictIterator class provides an iterator for Q3IntDict collections.
 280     \compat
 281
 282     Q3IntDictIterator is implemented as a template class. Define a
 283     template instance Q3IntDictIterator\<X\> to create a dictionary
 284     iterator that operates on Q3IntDict\<X\> (dictionary of X*).
 285
 286     Example:
 287     \snippet doc/src/snippets/code/doc_src_q3intdict.qdoc 2
 288
 289     Note that the traversal order is arbitrary; you are not guaranteed the
 290     order shown above.
 291
 292     Multiple iterators may independently traverse the same dictionary.
 293     A Q3IntDict knows about all the iterators that are operating on the
 294     dictionary. When an item is removed from the dictionary, Q3IntDict
 295     updates all iterators that refer the removed item to point to the
 296     next item in the traversal order.
 297
 298     \sa Q3IntDict
 299 */
 300
 301 /*!
 302     \fn Q3IntDictIterator::Q3IntDictIterator( const Q3IntDict<type> &dict )
 303
 304     Constructs an iterator for \a dict. The current iterator item is
 305     set to point to the 'first' item in the \a dict. The first item
 306     refers to the first item in the dictionary's arbitrary internal
 307     ordering.
 308 */
 309
 310 /*!
 311     \fn Q3IntDictIterator::~Q3IntDictIterator()
 312
 313     Destroys the iterator.
 314 */
 315
 316 /*!
 317     \fn uint Q3IntDictIterator::count() const
 318
 319     Returns the number of items in the dictionary this iterator
 320     operates over.
 321
 322     \sa isEmpty()
 323 */
 324
 325 /*!
 326     \fn bool Q3IntDictIterator::isEmpty() const
 327
 328     Returns TRUE if the dictionary is empty; otherwise eturns FALSE.
 329
 330     \sa count()
 331 */
 332
 333 /*!
 334     \fn type *Q3IntDictIterator::toFirst()
 335
 336     Sets the current iterator item to point to the first item in the
 337     dictionary and returns a pointer to the item. The first item
 338     refers to the first item in the dictionary's arbitrary internal
 339     ordering. If the dictionary is  empty it sets the current item to
 340     0 and returns 0.
 341 */
 342
 343 /*!
 344     \fn Q3IntDictIterator::operator type *() const
 345
 346     Cast operator. Returns a pointer to the current iterator item.
 347     Same as current().
 348 */
 349
 350 /*!
 351     \fn type *Q3IntDictIterator::current() const
 352
 353     Returns a pointer to the current iterator item.
 354 */
 355
 356 /*!
 357     \fn long Q3IntDictIterator::currentKey() const
 358
 359     Returns the key for the current iterator item.
 360 */
 361
 362 /*!
 363     \fn type *Q3IntDictIterator::operator()()
 364
 365     Makes the succeeding item current and returns the original current
 366     item.
 367
 368     If the current iterator item was the last item in the dictionary
 369     or if it was 0, 0 is returned.
 370 */
 371
 372 /*!
 373   \fn type *Q3IntDictIterator::operator++()
 374
 375     Prefix ++ makes the succeeding item current and returns the new
 376     current item.
 377
 378     If the current iterator item was the last item in the dictionary
 379     or if it was 0, 0 is returned.
 380 */
 381
 382 /*!
 383     \fn type *Q3IntDictIterator::operator+=( uint jump )
 384
 385     Sets the current item to the item \a jump positions after the
 386     current item, and returns a pointer to that item.
 387
 388     If that item is beyond the last item or if the dictionary is
 389     empty, it sets the current item to 0 and returns 0.
 390 */