1QAsciiDict(3qt)                                                QAsciiDict(3qt)
2
3
4

NAME

6       QAsciiDict - Template class that provides a dictionary based on char*
7       keys
8

SYNOPSIS

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

DESCRIPTION

44       The QAsciiDict class is a template class that provides a dictionary
45       based on char* keys.
46
47       QAsciiDict is implemented as a template class. Define a template
48       instance QAsciiDict<X> to create a dictionary that operates on pointers
49       to X (X*).
50
51       A dictionary is a collection of key-value pairs. The key is a char*
52       used for insertion, removal and lookup. The value is a pointer.
53       Dictionaries provide very fast insertion and lookup.
54
55       QAsciiDict cannot handle Unicode keys; use the QDict template instead,
56       which uses QString keys. A QDict has the same performace as a
57       QAsciiDict.
58
59       Example:
60
61           QAsciiDict<QLineEdit> fields; // char* keys, QLineEdit* values
62           fields.insert( "forename", new QLineEdit( this ) );
63           fields.insert( "surname", new QLineEdit( this ) );
64           fields["forename"]->setText( "Homer" );
65           fields["surname"]->setText( "Simpson" );
66           QAsciiDictIterator<QLineEdit> it( fields ); // See QAsciiDictIterator
67           for( ; it.current(); ++it )
68               cout << it.currentKey() << ": " << it.current()->text() << endl;
69           cout << endl;
70           if ( fields["forename"] && fields["surname"] )
71               cout << fields["forename"]->text() << " "
72                   << fields["surname"]->text() << endl;  // Prints "Homer Simpson"
73           fields.remove( "forename" ); // Does not delete the line edit
74           if ( ! fields["forename"] )
75               cout << "forename is not in the dictionary" << endl;
76       In this example we use a dictionary to keep track of the line edits
77       we're using. We insert each line edit into the dictionary with a unique
78       name and then access the line edits via the dictionary. See QPtrDict,
79       QIntDict and QDict.
80
81       See QDict for full details, including the choice of dictionary size,
82       and how deletions are handled.
83
84       See also QAsciiDictIterator, QDict, QIntDict, QPtrDict, Collection
85       Classes, Collection Classes, and Non-GUI Classes.
86

MEMBER FUNCTION DOCUMENTATION

QAsciiDict::QAsciiDict ( int size = 17, bool caseSensitive = TRUE, bool

89       copyKeys = TRUE )
90       Constructs a dictionary optimized for less than size entries.
91
92       We recommend setting size to a suitably large prime number (a bit
93       larger than the expected number of entries). This makes the hash
94       distribution better and will improve lookup performance.
95
96       When caseSensitive is TRUE (the default) QAsciiDict treats" abc" and
97       "Abc" as different keys; when it is FALSE "abc" and" Abc" are the same.
98       Case-insensitive comparison only considers the 26 letters in US-ASCII.
99
100       If copyKeys is TRUE (the default), the dictionary copies keys using
101       strcpy(); if it is FALSE, the dictionary just copies the pointers.
102

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

104       Constructs a copy of dict.
105
106       Each item in dict is inserted into this dictionary. Only the pointers
107       are copied (shallow copy).
108

QAsciiDict::~QAsciiDict ()

110       Removes all items from the dictionary and destroys it.
111
112       The items are deleted if auto-delete is enabled.
113
114       All iterators that access this dictionary will be reset.
115
116       See also setAutoDelete().
117

bool QPtrCollection::autoDelete () const

119       Returns the setting of the auto-delete option. The default is FALSE.
120
121       See also setAutoDelete().
122

void QAsciiDict::clear () [virtual]

124       Removes all items from the dictionary.
125
126       The removed items are deleted if auto-deletion is enabled.
127
128       All dictionary iterators that operate on dictionary are reset.
129
130       See also remove(), take(), and setAutoDelete().
131
132       Reimplemented from QPtrCollection.
133

uint QAsciiDict::count () const [virtual]

135       Returns the number of items in the dictionary.
136
137       See also isEmpty().
138
139       Reimplemented from QPtrCollection.
140

type * QAsciiDict::find ( const char * key ) const

142       Returns the item associated with key, or 0 if the key does not exist in
143       the dictionary.
144
145       This function uses an internal hashing algorithm to optimize lookup.
146
147       If there are two or more items with equal keys, then the item that was
148       most recently inserted will be found.
149
150       Equivalent to the [] operator.
151
152       See also operator[]().
153

void QAsciiDict::insert ( const char * key, const type * item )

155       Inserts the key with the item into the dictionary.
156
157       Multiple items can have the same key, in which case only the last item
158       will be accessible using operator[]().
159
160       item may not be 0.
161
162       See also replace().
163

bool QAsciiDict::isEmpty () const

165       Returns TRUE if the dictionary is empty, i.e. count() == 0; otherwise
166       it returns FALSE.
167
168       See also count().
169

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

171       Assigns dict to this dictionary and returns a reference to this
172       dictionary.
173
174       This dictionary is first cleared and then each item in dict is inserted
175       into this dictionary. Only the pointers are copied (shallow copy)
176       unless newItem() has been reimplemented().
177

type * QAsciiDict::operator[] ( const char * key ) const

179       Returns the item associated with key, or 0 if the key does not exist in
180       the dictionary.
181
182       This function uses an internal hashing algorithm to optimize lookup.
183
184       If there are two or more items with equal keys, then the item that was
185       most recently inserted will be found.
186
187       Equivalent to the find() function.
188
189       See also find().
190

QDataStream & QAsciiDict::read ( QDataStream & s, QPtrCollection::Item & item

192       ) [virtual protected]
193       Reads a dictionary item from the stream s and returns a reference to
194       the stream.
195
196       The default implementation sets item to 0.
197
198       See also write().
199

bool QAsciiDict::remove ( const char * key )

201       Removes the item associated with key from the dictionary. Returns TRUE
202       if successful, i.e. if the key existed in the dictionary; otherwise
203       returns FALSE.
204
205       If there are two or more items with equal keys, then the most recently
206       inserted item will be removed.
207
208       The removed item is deleted if auto-deletion is enabled.
209
210       All dictionary iterators that refer to the removed item will be set to
211       point to the next item in the dictionary traversal order.
212
213       See also take(), clear(), and setAutoDelete().
214

void QAsciiDict::replace ( const char * key, const type * item )

216       Replaces an item that has a key equal to key with item.
217
218       If the item does not already exist, it will be inserted.
219
220       item may not be 0.
221
222       Equivalent to:
223
224               QAsciiDict<char> dict;
225                   ...
226               if ( dict.find(key) )
227                   dict.remove( key );
228               dict.insert( key, item );
229
230       If there are two or more items with equal keys, then the most recently
231       inserted item will be replaced.
232
233       See also insert().
234

void QAsciiDict::resize ( uint newsize )

236       Changes the size of the hashtable to newsize. The contents of the
237       dictionary are preserved but all iterators on the dictionary become
238       invalid.
239

void QPtrCollection::setAutoDelete ( bool enable )

241       Sets the collection to auto-delete its contents if enable is TRUE and
242       to never delete them if enable is FALSE.
243
244       If auto-deleting is turned on, all the items in a collection are
245       deleted when the collection itself is deleted. This is convenient if
246       the collection has the only pointer to the items.
247
248       The default setting is FALSE, for safety. If you turn it on, be careful
249       about copying the collection - you might find yourself with two
250       collections deleting the same items.
251
252       Note that the auto-delete setting may also affect other functions in
253       subclasses. For example, a subclass that has a remove() function will
254       remove the item from its data structure, and if auto-delete is enabled,
255       will also delete the item.
256
257       See also autoDelete().
258
259       Examples:
260

uint QAsciiDict::size () const

262       Returns the size of the internal hash array (as specified in the
263       constructor).
264
265       See also count().
266

void QAsciiDict::statistics () const

268       Debugging-only function that prints out the dictionary distribution
269       using qDebug().
270

type * QAsciiDict::take ( const char * key )

272       Takes the item associated with key out of the dictionary without
273       deleting it (even if auto-deletion is enabled).
274
275       If there are two or more items with equal keys, then the most recently
276       inserted item will be taken.
277
278       Returns a pointer to the item taken out, or 0 if the key does not exist
279       in the dictionary.
280
281       All dictionary iterators that refer to the taken item will be set to
282       point to the next item in the dictionary traversal order.
283
284       See also remove(), clear(), and setAutoDelete().
285

QDataStream & QAsciiDict::write ( QDataStream & s, QPtrCollection::Item )

287       const [virtual protected]
288       Writes a dictionary item to the stream s and returns a reference to the
289       stream.
290
291       See also read().
292
293

SEE ALSO

295       http://doc.trolltech.com/qasciidict.html
296       http://www.trolltech.com/faq/tech.html
297
299       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
300       license file included in the distribution for a complete license
301       statement.
302

AUTHOR

304       Generated automatically from the source code.
305

BUGS

307       If you find a bug in Qt, please report it as described in
308       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
309       help you. Thank you.
310
311       The definitive Qt documentation is provided in HTML format; it is
312       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
313       web browser. This man page is provided as a convenience for those users
314       who prefer man pages, although this format is not officially supported
315       by Trolltech.
316
317       If you find errors in this manual page, please report them to qt-
318       bugs@trolltech.com.  Please include the name of the manual page
319       (qasciidict.3qt) and the Qt version (3.3.8).
320
321
322
323Trolltech AS                    2 February 2007                QAsciiDict(3qt)
Impressum