1QDict(3qt)                                                          QDict(3qt)
2
3
4

NAME

6       QDict - Template class that provides a dictionary based on QString keys
7

SYNOPSIS

9       #include <qdict.h>
10
11       Inherits QPtrCollection.
12
13   Public Members
14       QDict ( int size = 17, bool caseSensitive = TRUE )
15       QDict ( const QDict<type> & dict )
16       ~QDict ()
17       QDict<type> & operator= ( const QDict<type> & dict )
18       virtual uint count () const
19       uint size () const
20       bool isEmpty () const
21       void insert ( const QString & key, const type * item )
22       void replace ( const QString & key, const type * item )
23       bool remove ( const QString & key )
24       type * take ( const QString & key )
25       type * find ( const QString & key ) const
26       type * operator[] ( const QString & key ) const
27       virtual void clear ()
28       void resize ( uint newsize )
29       void statistics () const
30
31   Important Inherited Members
32       bool autoDelete () const
33       void setAutoDelete ( bool enable )
34
35   Protected Members
36       virtual QDataStream & read ( QDataStream & s, QPtrCollection::Item &
37           item )
38       virtual QDataStream & write ( QDataStream & s, QPtrCollection::Item )
39           const
40

DESCRIPTION

42       The QDict class is a template class that provides a dictionary based on
43       QString keys.
44
45       QMap is an STL-compatible alternative to this class.
46
47       QDict is implemented as a template class. Define a template instance
48       QDict<X> to create a dictionary that operates on pointers to X (X *).
49
50       A dictionary is a collection of key-value pairs. The key is a QString
51       used for insertion, removal and lookup. The value is a pointer.
52       Dictionaries provide very fast insertion and lookup.
53
54       If you want to use non-Unicode, plain 8-bit char* keys, use the
55       QAsciiDict template. A QDict has the same performance as a QAsciiDict.
56       If you want to have a dictionary that maps QStrings to QStrings use
57       QMap.
58
59       The size() of the dictionary is very important. In order to get good
60       performance, you should use a suitably large prime number. Suitable
61       means equal to or larger than the maximum expected number of dictionary
62       items. Size is set in the constructor but may be changed with resize().
63
64       Items are inserted with insert(); 0 pointers cannot be inserted. Items
65       are removed with remove(). All the items in a dictionary can be removed
66       with clear(). The number of items in the dictionary is returned by
67       count(). If the dictionary contains no items isEmpty() returns TRUE.
68       You can change an item's value with replace(). Items are looked up with
69       operator[](), or with find() which return a pointer to the value or 0
70       if the given key does not exist. You can take an item out of the
71       dictionary with take().
72
73       Calling setAutoDelete(TRUE) for a dictionary tells it to delete items
74       that are removed. The default behaviour is not to delete items when
75       they are removed.
76
77       When an item is inserted, the key is converted (hashed) to an integer
78       index into an internal hash array. This makes lookup very fast.
79
80       Items with equal keys are allowed. When inserting two items with the
81       same key, only the last inserted item will be accessible (last in,
82       first out) until it is removed.
83
84       The QDictIterator class can traverse the dictionary, but only in an
85       arbitrary order. Multiple iterators may independently traverse the same
86       dictionary.
87
88       When inserting an item into a dictionary, only the pointer is copied,
89       not the item itself, i.e. a shallow copy is made. It is possible to
90       make the dictionary copy all of the item's data (a deep copy) when an
91       item is inserted. insert() calls the virtual function
92       QPtrCollection::newItem() for the item to be inserted. Inherit a
93       dictionary and reimplement newItem() if you want deep copies.
94
95       When removing a dictionary item, the virtual function
96       QPtrCollection::deleteItem() is called. QDict's default implementation
97       is to delete the item if auto-deletion is enabled.
98
99       Example #1:
100
101           QDict<QLineEdit> fields; // QString keys, QLineEdit* values
102           fields.insert( "forename", new QLineEdit( this ) );
103           fields.insert( "surname", new QLineEdit( this ) );
104           fields["forename"]->setText( "Homer" );
105           fields["surname"]->setText( "Simpson" );
106           QDictIterator<QLineEdit> it( fields ); // See QDictIterator
107           for( ; it.current(); ++it )
108               cout << it.currentKey() << ": " << it.current()->text() << endl;
109           cout << endl;
110           if ( fields["forename"] && fields["surname"] )
111               cout << fields["forename"]->text() << " "
112                   << fields["surname"]->text() << endl;  // Prints "Homer Simpson"
113           fields.remove( "forename" ); // Does not delete the line edit
114           if ( ! fields["forename"] )
115               cout << "forename is not in the dictionary" << endl;
116       In this example we use a dictionary to keep track of the line edits
117       we're using. We insert each line edit into the dictionary with a unique
118       name and then access the line edits via the dictionary.
119
120       Example #2:
121
122           QStringList styleList = QStyleFactory::styles();
123           styleList.sort();
124           QDict<int> letterDict( 17, FALSE );
125           for ( QStringList::Iterator it = styleList.begin(); it != styleList.end(); ++it ) {
126               QString styleName = *it;
127               QString styleAccel = styleName;
128               if ( letterDict[styleAccel.left(1)] ) {
129                   for ( uint i = 0; i < styleAccel.length(); i++ ) {
130                       if ( ! letterDict[styleAccel.mid( i, 1 )] ) {
131                           styleAccel = styleAccel.insert( i, '&' );
132                           letterDict.insert(styleAccel.mid( i, 1 ), (const int *)1);
133                           break;
134                       }
135                   }
136               } else {
137                   styleAccel = "&" + styleAccel;
138                   letterDict.insert(styleAccel.left(1), (const int *)1);
139               }
140               (void) new QAction( styleName, QIconSet(), styleAccel, parent );
141           }
142       In the example we are using the dictionary to provide fast random
143       access to the keys, and we don't care what the values are. The example
144       is used to generate a menu of QStyles, each with a unique accelerator
145       key (or no accelerator if there are no unused letters left).
146
147       We first obtain the list of available styles, then sort them so that
148       the menu items will be ordered alphabetically. Next we create a
149       dictionary of int pointers. The keys in the dictionary are each one
150       character long, representing letters that have been used for
151       accelerators. We iterate through our list of style names. If the first
152       letter of the style name is in the dictionary, i.e. has been used, we
153       iterate over all the characters in the style name to see if we can find
154       a letter that hasn't been used. If we find an unused letter we put the
155       accelerator ampersand (&) in front of it and add that letter to the
156       dictionary. If we can't find an unused letter the style will simply
157       have no accelerator. If the first letter of the style name is not in
158       the dictionary we use it for the accelerator and add it to the
159       dictionary. Finally we create a QAction for each style.
160
161       See also QDictIterator, QAsciiDict, QIntDict, QPtrDict, Collection
162       Classes, and Non-GUI Classes.
163

MEMBER FUNCTION DOCUMENTATION

QDict::QDict ( int size = 17, bool caseSensitive = TRUE )

166       Constructs a dictionary optimized for less than size entries.
167
168       We recommend setting size to a suitably large prime number (e.g. a
169       prime that's slightly larger than the expected number of entries). This
170       makes the hash distribution better which will lead to faster lookup.
171
172       If caseSensitive is TRUE (the default), keys which differ only by case
173       are considered different.
174

QDict::QDict ( const QDict<type> & dict )

176       Constructs a copy of dict.
177
178       Each item in dict is inserted into this dictionary. Only the pointers
179       are copied (shallow copy).
180

QDict::~QDict ()

182       Removes all items from the dictionary and destroys it. If
183       setAutoDelete() is TRUE, each value is deleted. All iterators that
184       access this dictionary will be reset.
185
186       See also setAutoDelete().
187

bool QPtrCollection::autoDelete () const

189       Returns the setting of the auto-delete option. The default is FALSE.
190
191       See also setAutoDelete().
192

void QDict::clear () [virtual]

194       Removes all items from the dictionary.
195
196       The removed items are deleted if auto-deletion is enabled.
197
198       All dictionary iterators that operate on the dictionary are reset.
199
200       See also remove(), take(), and setAutoDelete().
201
202       Reimplemented from QPtrCollection.
203

uint QDict::count () const [virtual]

205       Returns the number of items in the dictionary.
206
207       See also isEmpty().
208
209       Reimplemented from QPtrCollection.
210

type * QDict::find ( const QString & key ) const

212       Returns the item with key key, or 0 if the key does not exist in the
213       dictionary.
214
215       If there are two or more items with equal keys, then the most recently
216       inserted item will be found.
217
218       Equivalent to the [] operator.
219
220       See also operator[]().
221

void QDict::insert ( const QString & key, const type * item )

223       Inserts the key key with value item into the dictionary.
224
225       Multiple items can have the same key, in which case only the last item
226       will be accessible using operator[]().
227
228       item may not be 0.
229
230       See also replace().
231
232       Example: themes/themes.cpp.
233

bool QDict::isEmpty () const

235       Returns TRUE if the dictionary is empty, i.e. count() == 0; otherwise
236       returns FALSE.
237
238       See also count().
239

QDict<type> & QDict::operator= ( const QDict<type> & dict )

241       Assigns dict to this dictionary and returns a reference to this
242       dictionary.
243
244       This dictionary is first cleared, then each item in dict is inserted
245       into this dictionary. Only the pointers are copied (shallow copy),
246       unless newItem() has been reimplemented.
247

type * QDict::operator[] ( const QString & key ) const

249       Returns the item with key key, or 0 if the key does not exist in the
250       dictionary.
251
252       If there are two or more items with equal keys, then the most recently
253       inserted item will be found.
254
255       Equivalent to the find() function.
256
257       See also find().
258

QDataStream & QDict::read ( QDataStream & s, QPtrCollection::Item & item )

260       [virtual protected]
261       Reads a dictionary item from the stream s and returns a reference to
262       the stream.
263
264       The default implementation sets item to 0.
265
266       See also write().
267

bool QDict::remove ( const QString & key )

269       Removes the item with key from the dictionary. Returns TRUE if
270       successful, i.e. if the item is in the dictionary; otherwise returns
271       FALSE.
272
273       If there are two or more items with equal keys, then the last item that
274       was inserted will be removed.
275
276       The removed item is deleted if auto-deletion is enabled.
277
278       All dictionary iterators that refer to the removed item will be set to
279       point to the next item in the dictionary's traversal order.
280
281       See also take(), clear(), and setAutoDelete().
282

void QDict::replace ( const QString & key, const type * item )

284       Replaces the value of the key, key with item.
285
286       If the item does not already exist, it will be inserted.
287
288       item may not be 0.
289
290       Equivalent to:
291
292               QDict<char> dict;
293                   ...
294               if ( dict.find( key ) )
295                   dict.remove( key );
296               dict.insert( key, item );
297
298       If there are two or more items with equal keys, then the last item that
299       was inserted will be replaced.
300
301       See also insert().
302

void QDict::resize ( uint newsize )

304       Changes the size of the hash table to newsize. The contents of the
305       dictionary are preserved, but all iterators on the dictionary become
306       invalid.
307

void QPtrCollection::setAutoDelete ( bool enable )

309       Sets the collection to auto-delete its contents if enable is TRUE and
310       to never delete them if enable is FALSE.
311
312       If auto-deleting is turned on, all the items in a collection are
313       deleted when the collection itself is deleted. This is convenient if
314       the collection has the only pointer to the items.
315
316       The default setting is FALSE, for safety. If you turn it on, be careful
317       about copying the collection - you might find yourself with two
318       collections deleting the same items.
319
320       Note that the auto-delete setting may also affect other functions in
321       subclasses. For example, a subclass that has a remove() function will
322       remove the item from its data structure, and if auto-delete is enabled,
323       will also delete the item.
324
325       See also autoDelete().
326
327       Examples:
328

uint QDict::size () const

330       Returns the size of the internal hash array (as specified in the
331       constructor).
332
333       See also count().
334

void QDict::statistics () const

336       Debugging-only function that prints out the dictionary distribution
337       using qDebug().
338

type * QDict::take ( const QString & key )

340       Takes the item with key out of the dictionary without deleting it (even
341       if auto-deletion is enabled).
342
343       If there are two or more items with equal keys, then the last item that
344       was inserted will be taken.
345
346       Returns a pointer to the item taken out, or 0 if the key does not exist
347       in the dictionary.
348
349       All dictionary iterators that refer to the taken item will be set to
350       point to the next item in the dictionary traversal order.
351
352       See also remove(), clear(), and setAutoDelete().
353

QDataStream & QDict::write ( QDataStream & s, QPtrCollection::Item ) const

355       [virtual protected]
356       Writes a dictionary item to the stream s and returns a reference to the
357       stream.
358
359       See also read().
360
361

SEE ALSO

363       http://doc.trolltech.com/qdict.html
364       http://www.trolltech.com/faq/tech.html
365
367       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
368       license file included in the distribution for a complete license
369       statement.
370

AUTHOR

372       Generated automatically from the source code.
373

BUGS

375       If you find a bug in Qt, please report it as described in
376       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
377       help you. Thank you.
378
379       The definitive Qt documentation is provided in HTML format; it is
380       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
381       web browser. This man page is provided as a convenience for those users
382       who prefer man pages, although this format is not officially supported
383       by Trolltech.
384
385       If you find errors in this manual page, please report them to qt-
386       bugs@trolltech.com.  Please include the name of the manual page
387       (qdict.3qt) and the Qt version (3.3.8).
388
389
390
391Trolltech AS                    2 February 2007                     QDict(3qt)
Impressum