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 Q3AsciiDict

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

    45     \compat

    46 

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

    48     instance Q3AsciiDict\<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     char* used for insertion, removal and lookup. The value is a

    53     pointer. Dictionaries provide very fast insertion and lookup.

    54 

    55     Q3AsciiDict cannot handle Unicode keys; use the Q3Dict template

    56     instead, which uses QString keys. A Q3Dict has the same

    57     performace as a Q3AsciiDict.

    58 

    59     Example:

    60     \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 0

    61     In this example we use a dictionary to keep track of the line

    62     edits we're using. We insert each line edit into the dictionary

    63     with a unique name and then access the line edits via the

    64     dictionary. See Q3PtrDict, Q3IntDict and Q3Dict.

    65 

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

    67     size, and how deletions are handled. 

    68 

    69     \sa Q3AsciiDictIterator, Q3Dict, Q3IntDict, Q3PtrDict

    70 */

    71 

    72 

    73 /*!

    74     \fn Q3AsciiDict::Q3AsciiDict( int size, bool caseSensitive, bool copyKeys )

    75 

    76     Constructs a dictionary optimized for less than \a size entries.

    77 

    78     We recommend setting \a size to a suitably large prime number (a

    79     bit larger than the expected number of entries). This makes the

    80     hash distribution better and will improve lookup performance.

    81 

    82     When \a caseSensitive is TRUE (the default) Q3AsciiDict treats

    83     "abc" and "Abc" as different keys; when it is FALSE "abc" and

    84     "Abc" are the same. Case-insensitive comparison only considers the

    85     26 letters in US-ASCII.

    86 

    87     If \a copyKeys is TRUE (the default), the dictionary copies keys

    88     using strcpy(); if it is FALSE, the dictionary just copies the

    89     pointers.

    90 */

    91 

    92 /*!

    93     \fn Q3AsciiDict::Q3AsciiDict( const Q3AsciiDict<type> &dict )

    94 

    95     Constructs a copy of \a dict.

    96 

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

    98     pointers are copied (shallow copy).

    99 */

   100 

   101 /*!

   102     \fn Q3AsciiDict::~Q3AsciiDict()

   103 

   104     Removes all items from the dictionary and destroys it.

   105 

   106     The items are deleted if auto-delete is enabled.

   107 

   108     All iterators that access this dictionary will be reset.

   109 

   110     \sa setAutoDelete()

   111 */

   112 

   113 /*!

   114     \fn Q3AsciiDict<type> &Q3AsciiDict::operator=(const Q3AsciiDict<type> &dict)

   115 

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

   117     dictionary.

   118 

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

   120     inserted into this dictionary. Only the pointers are copied

   121     (shallow copy) unless newItem() has been reimplemented().

   122 */

   123 

   124 /*!

   125     \fn uint Q3AsciiDict::count() const

   126 

   127     Returns the number of items in the dictionary.

   128 

   129     \sa isEmpty()

   130 */

   131 

   132 /*!

   133     \fn uint Q3AsciiDict::size() const

   134 

   135     Returns the size of the internal hash array (as specified in the

   136     constructor).

   137 

   138     \sa count()

   139 */

   140 

   141 /*!

   142     \fn void Q3AsciiDict::resize( uint newsize )

   143 

   144     Changes the size of the hashtable to \a newsize. The contents of

   145     the dictionary are preserved but all iterators on the dictionary

   146     become invalid.

   147 */

   148 

   149 /*!

   150     \fn bool Q3AsciiDict::isEmpty() const

   151 

   152     Returns TRUE if the dictionary is empty, i.e. count() == 0;

   153     otherwise it returns FALSE.

   154 

   155     \sa count()

   156 */

   157 

   158 /*!

   159     \fn void Q3AsciiDict::insert( const char *key, const type *item )

   160 

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

   162 

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

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

   165 

   166     \a item may not be 0.

   167 

   168     \sa replace()

   169 */

   170 

   171 /*!

   172     \fn void Q3AsciiDict::replace( const char *key, const type *item )

   173 

   174     Replaces an item that has a key equal to \a key with \a item.

   175 

   176     If the item does not already exist, it will be inserted.

   177 

   178     \a item may not be 0.

   179 

   180     Equivalent to:

   181     \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 1

   182 

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

   184     recently inserted item will be replaced.

   185 

   186     \sa insert()

   187 */

   188 

   189 /*!

   190     \fn bool Q3AsciiDict::remove( const char *key )

   191 

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

   193     Returns TRUE if successful, i.e. if the key existed in the

   194     dictionary; otherwise returns FALSE.

   195 

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

   197     recently inserted item will be removed.

   198 

   199     The removed item is deleted if \link

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

   201 

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

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

   204 

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

   206 */

   207 

   208 /*!

   209     \fn type *Q3AsciiDict::take( const char *key )

   210 

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

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

   213     auto-deletion\endlink is enabled).

   214 

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

   216     recently inserted item will be taken.

   217 

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

   219     exist in the dictionary.

   220 

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

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

   223 

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

   225 */

   226 

   227 /*!

   228     \fn void Q3AsciiDict::clear()

   229 

   230     Removes all items from the dictionary.

   231 

   232     The removed items are deleted if \link

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

   234 

   235     All dictionary iterators that operate on dictionary are reset.

   236 

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

   238 */

   239 

   240 /*!

   241     \fn type *Q3AsciiDict::find( const char *key ) const

   242 

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

   244     exist in the dictionary.

   245 

   246     This function uses an internal hashing algorithm to optimize

   247     lookup.

   248 

   249     If there are two or more items with equal keys, then the item that

   250     was most recently inserted will be found.

   251 

   252     Equivalent to the [] operator.

   253 

   254     \sa operator[]()

   255 */

   256 

   257 /*!

   258     \fn type *Q3AsciiDict::operator[]( const char *key ) const

   259 

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

   261     not exist in the dictionary.

   262 

   263     This function uses an internal hashing algorithm to optimize

   264     lookup.

   265 

   266     If there are two or more items with equal keys, then the item that

   267     was most recently inserted will be found.

   268 

   269     Equivalent to the find() function.

   270 

   271     \sa find()

   272 */

   273 

   274 /*!

   275     \fn void Q3AsciiDict::statistics() const

   276 

   277     Debugging-only function that prints out the dictionary

   278     distribution using qDebug().

   279 */

   280 

   281 /*!

   282     \fn QDataStream& Q3AsciiDict::read( QDataStream &s,

   283 					Q3PtrCollection::Item &item )

   284 

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

   286     reference to the stream.

   287 

   288     The default implementation sets \a item to 0.

   289 

   290     \sa write()

   291 */

   292 

   293 /*!

   294     \fn QDataStream& Q3AsciiDict::write(QDataStream &s, Q3PtrCollection::Item item) const

   295 

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

   297     reference to the stream.

   298 

   299     \sa read()

   300 */

   301 

   302 /*!

   303     \class Q3AsciiDictIterator

   304     \brief The Q3AsciiDictIterator class provides an iterator for Q3AsciiDict collections.

   305     \compat

   306 

   307     Q3AsciiDictIterator is implemented as a template class. Define a

   308     template instance Q3AsciiDictIterator\<X\> to create a dictionary

   309     iterator that operates on Q3AsciiDict\<X\> (dictionary of X*).

   310 

   311     Example:

   312     \snippet doc/src/snippets/code/doc_src_q3asciidict.qdoc 2

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

   314     iterate over the dictionary printing the strings associated with

   315     those line edits.

   316 

   317     Note that the traversal order is arbitrary; you are not guaranteed

   318     any particular order.

   319 

   320     Multiple iterators may independently traverse the same dictionary.

   321     A Q3AsciiDict knows about all the iterators that are operating on

   322     the dictionary. When an item is removed from the dictionary,

   323     Q3AsciiDict updates all the iterators that are referring to the

   324     removed item to point to the next item in the (arbitrary)

   325     traversal order.

   326 

   327     \sa Q3AsciiDict

   328 */

   329 

   330 /*!

   331     \fn Q3AsciiDictIterator::Q3AsciiDictIterator( const Q3AsciiDict<type> &dict )

   332 

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

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

   335 */

   336 

   337 /*!

   338     \fn Q3AsciiDictIterator::~Q3AsciiDictIterator()

   339 

   340     Destroys the iterator.

   341 */

   342 

   343 /*!

   344     \fn uint Q3AsciiDictIterator::count() const

   345 

   346     Returns the number of items in the dictionary this iterator

   347     operates over.

   348 

   349     \sa isEmpty()

   350 */

   351 

   352 /*!

   353     \fn bool Q3AsciiDictIterator::isEmpty() const

   354 

   355     Returns TRUE if the dictionary is empty, i.e. count() == 0,

   356     otherwise returns FALSE.

   357     

   358     \sa count()

   359 */

   360 

   361 /*!

   362     \fn type *Q3AsciiDictIterator::toFirst()

   363 

   364     Sets the current iterator item to point to the first item in the

   365     dictionary and returns a pointer to the item. If the dictionary is

   366     empty it sets the current item to 0 and returns 0.

   367 */

   368 

   369 /*!

   370     \fn Q3AsciiDictIterator::operator type *() const

   371 

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

   373     Same as current().

   374 */

   375 

   376 /*!

   377     \fn type *Q3AsciiDictIterator::current() const

   378 

   379     Returns a pointer to the current iterator item.

   380 */

   381 

   382 /*!

   383     \fn const char *Q3AsciiDictIterator::currentKey() const

   384 

   385     Returns a pointer to the key for the current iterator item.

   386 */

   387 

   388 /*!

   389     \fn type *Q3AsciiDictIterator::operator()()

   390 

   391     Makes the succeeding item current and returns the original current

   392     item.

   393 

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

   395     or if it was 0, 0 is returned.

   396 */

   397 

   398 /*!

   399     \fn type *Q3AsciiDictIterator::operator++()

   400 

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

   402     current item.

   403 

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

   405     or if it was 0, 0 is returned.

   406 */

   407 

   408 /*!

   409     \fn type *Q3AsciiDictIterator::operator+=( uint jump )

   410 

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

   412     current item, and returns a pointer to that item.

   413 

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

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

   416 */