1QDict(3qt) QDict(3qt)
2
6 QDict - Template class that provides a dictionary based on QString keys
7
9 #include <qdict.h>
10 Inherits QPtrCollection.
12 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 Important Inherited Members
32 bool autoDelete () const
33 void setAutoDelete ( bool enable )
34 Protected Members
36 virtual QDataStream & read ( QDataStream & s, QPtrCollection::Item &
37 item )
38 virtual QDataStream & write ( QDataStream & s, QPtrCollection::Item )
39 const
40
42 The QDict class is a template class that provides a dictionary based on
43 QString keys.
44 QMap is an STL-compatible alternative to this class.
46 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 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 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 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 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 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 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 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 The QDictIterator class can traverse the dictionary, but only in an
85 arbitrary order. Multiple iterators may independently traverse the same
86 dictionary.
87 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 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 Example #1:
100 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 Example #2:
121 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 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 See also QDictIterator, QAsciiDict, QIntDict, QPtrDict, Collection
162 Classes, and Non-GUI Classes.
163
166 Constructs a dictionary optimized for less than size entries.
167 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 If caseSensitive is TRUE (the default), keys which differ only by case
173 are considered different.
174
176 Constructs a copy of dict.
177 Each item in dict is inserted into this dictionary. Only the pointers
179 are copied (shallow copy).
180
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 See also setAutoDelete().
187
189 Returns the setting of the auto-delete option. The default is FALSE.
190 See also setAutoDelete().
192
194 Removes all items from the dictionary.
195 The removed items are deleted if auto-deletion is enabled.
197 All dictionary iterators that operate on the dictionary are reset.
199 See also remove(), take(), and setAutoDelete().
201 Reimplemented from QPtrCollection.
203
205 Returns the number of items in the dictionary.
206 See also isEmpty().
208 Reimplemented from QPtrCollection.
210
212 Returns the item with key key, or 0 if the key does not exist in the
213 dictionary.
214 If there are two or more items with equal keys, then the most recently
216 inserted item will be found.
217 Equivalent to the [] operator.
219 See also operator[]().
221
223 Inserts the key key with value item into the dictionary.
224 Multiple items can have the same key, in which case only the last item
226 will be accessible using operator[]().
227 item may not be 0.
229 See also replace().
231 Example: themes/themes.cpp.
233
235 Returns TRUE if the dictionary is empty, i.e. count() == 0; otherwise
236 returns FALSE.
237 See also count().
239
241 Assigns dict to this dictionary and returns a reference to this
242 dictionary.
243 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
249 Returns the item with key key, or 0 if the key does not exist in the
250 dictionary.
251 If there are two or more items with equal keys, then the most recently
253 inserted item will be found.
254 Equivalent to the find() function.
256 See also find().
258
260 [virtual protected]
261 Reads a dictionary item from the stream s and returns a reference to
262 the stream.
263 The default implementation sets item to 0.
265 See also write().
267
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 If there are two or more items with equal keys, then the last item that
274 was inserted will be removed.
275 The removed item is deleted if auto-deletion is enabled.
277 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 See also take(), clear(), and setAutoDelete().
282
284 Replaces the value of the key, key with item.
285 If the item does not already exist, it will be inserted.
287 item may not be 0.
289 Equivalent to:
291 QDict<char> dict;
293 ...
294 if ( dict.find( key ) )
295 dict.remove( key );
296 dict.insert( key, item );
297 If there are two or more items with equal keys, then the last item that
299 was inserted will be replaced.
300 See also insert().
302
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
309 Sets the collection to auto-delete its contents if enable is TRUE and
310 to never delete them if enable is FALSE.
311 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 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 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 See also autoDelete().
326 Examples:
328
330 Returns the size of the internal hash array (as specified in the
331 constructor).
332 See also count().
334
336 Debugging-only function that prints out the dictionary distribution
337 using qDebug().
338
340 Takes the item with key out of the dictionary without deleting it (even
341 if auto-deletion is enabled).
342 If there are two or more items with equal keys, then the last item that
344 was inserted will be taken.
345 Returns a pointer to the item taken out, or 0 if the key does not exist
347 in the dictionary.
348 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 See also remove(), clear(), and setAutoDelete().
353
355 [virtual protected]
356 Writes a dictionary item to the stream s and returns a reference to the
357 stream.
358 See also read().
360
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
372 Generated automatically from the source code.
373
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 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 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).
388Trolltech AS 2 February 2007 QDict(3qt)