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 Q3PtrDict

    44     \brief The Q3PtrDict class is a template class that provides a dictionary based on void* keys.

    45     \compat

    46 

    47     Q3PtrDict is implemented as a template class. Define a template

    48     instance Q3PtrDict\<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 a

    52     void* 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_q3ptrdict.qdoc 0

    57     In this example we use a dictionary to add an extra property (a

    58     char*) to the line edits we're using. 

    59 

    60     See Q3Dict for full details, including the choice of dictionary

    61     size, and how deletions are handled. 

    62 

    63     \sa Q3PtrDictIterator, Q3Dict, Q3AsciiDict, Q3IntDict

    64 */

    65 

    66 

    67 /*!

    68     \fn Q3PtrDict::Q3PtrDict( int size )

    69 

    70     Constructs a dictionary using an internal hash array with the size

    71     \a size.

    72 

    73     Setting \a size to a suitably large prime number (equal to or

    74     greater than the expected number of entries) makes the hash

    75     distribution better and improves lookup performance.

    76 */

    77 

    78 /*!

    79     \fn Q3PtrDict::Q3PtrDict( const Q3PtrDict<type> &dict )

    80 

    81     Constructs a copy of \a dict.

    82 

    83     Each item in \a dict is inserted into this dictionary. Only the

    84     pointers are copied (shallow copy).

    85 */

    86 

    87 /*!

    88     \fn Q3PtrDict::~Q3PtrDict()

    89 

    90     Removes all items from the dictionary and destroys it.

    91 

    92     All iterators that access this dictionary will be reset.

    93 

    94     \sa setAutoDelete()

    95 */

    96 

    97 /*!

    98     \fn Q3PtrDict<type> &Q3PtrDict::operator=(const Q3PtrDict<type> &dict)

    99 

   100     Assigns \a dict to this dictionary and returns a reference to this

   101     dictionary.

   102 

   103     This dictionary is first cleared and then each item in \a dict is

   104     inserted into the dictionary. Only the pointers are copied

   105     (shallow copy), unless newItem() has been reimplemented.

   106 */

   107 

   108 /*!

   109     \fn uint Q3PtrDict::count() const

   110 

   111     Returns the number of items in the dictionary.

   112 

   113     \sa isEmpty()

   114 */

   115 

   116 /*!

   117     \fn uint Q3PtrDict::size() const

   118 

   119     Returns the size of the internal hash table (as specified in the

   120     constructor).

   121 

   122     \sa count()

   123 */

   124 

   125 /*!

   126     \fn void Q3PtrDict::resize( uint newsize )

   127 

   128     Changes the size of the hash table to \a newsize. The contents of

   129     the dictionary are preserved, but all iterators on the dictionary

   130     become invalid.

   131 */

   132 

   133 /*!

   134     \fn bool Q3PtrDict::isEmpty() const

   135 

   136     Returns TRUE if the dictionary is empty; otherwise returns FALSE.

   137 

   138     \sa count()

   139 */

   140 

   141 /*!

   142     \fn void Q3PtrDict::insert( void *key, const type *item )

   143 

   144     Inserts the \a key with the \a item into the dictionary.

   145 

   146     Multiple items can have the same key, in which case only the last

   147     item will be accessible using \l operator[]().

   148 

   149     \a item may not be 0.

   150 

   151     \sa replace()

   152 */

   153 

   154 /*!

   155     \fn void Q3PtrDict::replace( void *key, const type *item )

   156 

   157     If the dictionary has key \a key, this key's item is replaced with

   158     \a item. If the dictionary doesn't contain key \a key, \a item is

   159     inserted into the dictionary using key \a key. 

   160 

   161     \a item may not be 0.

   162 

   163     Equivalent to

   164     \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 1

   165 

   166     If there are two or more items with equal keys, then the most

   167     recently inserted item will be replaced.

   168 

   169     \sa insert()

   170 */

   171 

   172 /*!

   173     \fn bool Q3PtrDict::remove( void *key ) 

   174     

   175     Removes the item associated with \a key from the dictionary.

   176     Returns TRUE if successful, i.e. if \a key is in the dictionary;

   177     otherwise returns FALSE.

   178 

   179     If there are two or more items with equal keys, then the most

   180     recently inserted item will be removed.

   181 

   182     The removed item is deleted if \link

   183     Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.

   184 

   185     All dictionary iterators that refer to the removed item will be

   186     set to point to the next item in the dictionary traversal order.

   187 

   188     \sa take(), clear(), setAutoDelete()

   189 */

   190 

   191 /*!

   192     \fn type *Q3PtrDict::take( void *key )

   193 

   194     Takes the item associated with \a key out of the dictionary

   195     without deleting it (even if \link Q3PtrCollection::setAutoDelete()

   196     auto-deletion\endlink is enabled).

   197 

   198     If there are two or more items with equal keys, then the most

   199     recently inserted item will be removed.

   200 

   201     Returns a pointer to the item taken out, or 0 if the key does not

   202     exist in the dictionary.

   203 

   204     All dictionary iterators that refer to the taken item will be set

   205     to point to the next item in the dictionary traversal order.

   206 

   207     \sa remove(), clear(), setAutoDelete()

   208 */

   209 

   210 /*!

   211     \fn void Q3PtrDict::clear()

   212 

   213     Removes all items from the dictionary.

   214 

   215     The removed items are deleted if \link

   216     Q3PtrCollection::setAutoDelete() auto-deletion\endlink is enabled.

   217 

   218     All dictionary iterators that access this dictionary will be

   219     reset.

   220 

   221     \sa remove(), take(), setAutoDelete()

   222 */

   223 

   224 /*!

   225     \fn type *Q3PtrDict::find( void *key ) const

   226 

   227     Returns the item associated with \a key, or 0 if the key does not

   228     exist in the dictionary.

   229 

   230     If there are two or more items with equal keys, then the most

   231     recently inserted item will be found.

   232 

   233     Equivalent to operator[].

   234 

   235     \sa operator[]()

   236 */

   237 

   238 /*!

   239     \fn type *Q3PtrDict::operator[]( void *key ) const

   240 

   241     Returns the item associated with \a key, or 0 if the key does not

   242     exist in the dictionary.

   243 

   244     If there are two or more items with equal keys, then the most

   245     recently inserted item will be found.

   246 

   247     Equivalent to the find() function.

   248 

   249     \sa find()

   250 */

   251 

   252 /*!

   253     \fn void Q3PtrDict::statistics() const

   254 

   255     Debugging-only function that prints out the dictionary

   256     distribution using qDebug().

   257 */

   258 

   259 /*!

   260     \fn QDataStream& Q3PtrDict::read( QDataStream &s, Q3PtrCollection::Item &item )

   261 

   262     Reads a dictionary item from the stream \a s and returns a

   263     reference to the stream.

   264 

   265     The default implementation sets \a item to 0.

   266 

   267     \sa write()

   268 */

   269 

   270 /*!

   271     \fn QDataStream& Q3PtrDict::write( QDataStream &s, Q3PtrCollection::Item item) const

   272 

   273     Writes a dictionary \a item to the stream \a s and returns a

   274     reference to the stream.

   275 

   276     \sa read()

   277 */

   278 

   279 /*!

   280     \class Q3PtrDictIterator

   281     \brief The Q3PtrDictIterator class provides an iterator for Q3PtrDict collections.

   282     \compat

   283 

   284     Q3PtrDictIterator is implemented as a template class. Define a

   285     template instance Q3PtrDictIterator\<X\> to create a dictionary

   286     iterator that operates on Q3PtrDict\<X\> (dictionary of X*).

   287 

   288     Example:

   289     \snippet doc/src/snippets/code/doc_src_q3ptrdict.qdoc 2

   290     In the example we insert some line edits into a dictionary,

   291     associating a string with each. We then iterate over the

   292     dictionary printing the associated strings.

   293 

   294     Multiple iterators may independently traverse the same dictionary.

   295     A Q3PtrDict knows about all the iterators that are operating on the

   296     dictionary. When an item is removed from the dictionary, Q3PtrDict

   297     updates all iterators that refer the removed item to point to the

   298     next item in the traversing order.

   299 

   300     \sa Q3PtrDict

   301 */

   302 

   303 /*!

   304     \fn Q3PtrDictIterator::Q3PtrDictIterator( const Q3PtrDict<type> &dict )

   305 

   306     Constructs an iterator for \a dict. The current iterator item is

   307     set to point on the first item in the \a dict.

   308 */

   309 

   310 /*!

   311     \fn Q3PtrDictIterator::~Q3PtrDictIterator()

   312 

   313     Destroys the iterator.

   314 */

   315 

   316 /*!

   317     \fn uint Q3PtrDictIterator::count() const

   318 

   319     Returns the number of items in the dictionary this iterator

   320     operates on.

   321 

   322     \sa isEmpty()

   323 */

   324 

   325 /*!

   326     \fn bool Q3PtrDictIterator::isEmpty() const

   327 

   328     Returns TRUE if the dictionary is empty; otherwise returns FALSE.

   329 

   330     \sa count()

   331 */

   332 

   333 /*!

   334     \fn type *Q3PtrDictIterator::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. If the dictionary is

   338     empty, it sets the current item to 0 and returns 0.

   339 */

   340 

   341 /*!

   342     \fn Q3PtrDictIterator::operator type *() const

   343 

   344     Cast operator. Returns a pointer to the current iterator item.

   345     Same as current().

   346 */

   347 

   348 /*!

   349     \fn type *Q3PtrDictIterator::current() const

   350 

   351     Returns a pointer to the current iterator item's value.

   352 */

   353 

   354 /*!

   355     \fn void *Q3PtrDictIterator::currentKey() const

   356 

   357     Returns the current iterator item's key.

   358 */

   359 

   360 /*!

   361     \fn type *Q3PtrDictIterator::operator()()

   362 

   363     Makes the succeeding item current and returns the original current

   364     item.

   365 

   366     If the current iterator item was the last item in the dictionary

   367     or if it was 0, 0 is returned.

   368 */

   369 

   370 /*!

   371     \fn type *Q3PtrDictIterator::operator++()

   372 

   373     Prefix ++ makes the succeeding item current and returns the new

   374     current item.

   375 

   376     If the current iterator item was the last item in the dictionary

   377     or if it was 0, 0 is returned.

   378 */

   379 

   380 /*!

   381     \fn type *Q3PtrDictIterator::operator+=( uint jump )

   382 

   383     Sets the current item to the item \a jump positions after the

   384     current item and returns a pointer to that item.

   385 

   386     If that item is beyond the last item or if the dictionary is

   387     empty, it sets the current item to 0 and returns 0.

   388 */