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