source: trunk/doc/html/qasciidict.html@ 208

Last change on this file since 208 was 190, checked in by rudi, 14 years ago

reference documentation added

File size: 16.5 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/qasciidict.doc:41 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QAsciiDict Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QAsciiDict Class Reference</h1>
33
34<p>The QAsciiDict class is a template class that provides a dictionary based on char* keys.
35<a href="#details">More...</a>
36<p><tt>#include &lt;<a href="qasciidict-h.html">qasciidict.h</a>&gt;</tt>
37<p>Inherits <a href="qptrcollection.html">QPtrCollection</a>.
38<p><a href="qasciidict-members.html">List of all member functions.</a>
39<h2>Public Members</h2>
40<ul>
41<li class=fn><a href="#QAsciiDict"><b>QAsciiDict</b></a> ( int&nbsp;size = 17, bool&nbsp;caseSensitive = TRUE, bool&nbsp;copyKeys = TRUE )</li>
42<li class=fn><a href="#QAsciiDict-2"><b>QAsciiDict</b></a> ( const&nbsp;QAsciiDict&lt;type&gt;&nbsp;&amp;&nbsp;dict )</li>
43<li class=fn><a href="#~QAsciiDict"><b>~QAsciiDict</b></a> ()</li>
44<li class=fn>QAsciiDict&lt;type&gt; &amp; <a href="#operator-eq"><b>operator=</b></a> ( const&nbsp;QAsciiDict&lt;type&gt;&nbsp;&amp;&nbsp;dict )</li>
45<li class=fn>virtual uint <a href="#count"><b>count</b></a> () const</li>
46<li class=fn>uint <a href="#size"><b>size</b></a> () const</li>
47<li class=fn>bool <a href="#isEmpty"><b>isEmpty</b></a> () const</li>
48<li class=fn>void <a href="#insert"><b>insert</b></a> ( const&nbsp;char&nbsp;*&nbsp;key, const&nbsp;type&nbsp;*&nbsp;item )</li>
49<li class=fn>void <a href="#replace"><b>replace</b></a> ( const&nbsp;char&nbsp;*&nbsp;key, const&nbsp;type&nbsp;*&nbsp;item )</li>
50<li class=fn>bool <a href="#remove"><b>remove</b></a> ( const&nbsp;char&nbsp;*&nbsp;key )</li>
51<li class=fn>type * <a href="#take"><b>take</b></a> ( const&nbsp;char&nbsp;*&nbsp;key )</li>
52<li class=fn>type * <a href="#find"><b>find</b></a> ( const&nbsp;char&nbsp;*&nbsp;key ) const</li>
53<li class=fn>type * <a href="#operator[]"><b>operator[]</b></a> ( const&nbsp;char&nbsp;*&nbsp;key ) const</li>
54<li class=fn>virtual void <a href="#clear"><b>clear</b></a> ()</li>
55<li class=fn>void <a href="#resize"><b>resize</b></a> ( uint&nbsp;newsize )</li>
56<li class=fn>void <a href="#statistics"><b>statistics</b></a> () const</li>
57</ul>
58<h2>Important Inherited Members</h2>
59<ul>
60<li class=fn>bool <a href="#autoDelete"><b>autoDelete</b></a> () const</li>
61<li class=fn>void <a href="#setAutoDelete"><b>setAutoDelete</b></a> ( bool&nbsp;enable )</li>
62</ul>
63<h2>Protected Members</h2>
64<ul>
65<li class=fn>virtual QDataStream &amp; <a href="#read"><b>read</b></a> ( QDataStream&nbsp;&amp;&nbsp;s, QPtrCollection::Item&nbsp;&amp;&nbsp;item )</li>
66<li class=fn>virtual QDataStream &amp; <a href="#write"><b>write</b></a> ( QDataStream&nbsp;&amp;&nbsp;s, QPtrCollection::Item ) const</li>
67</ul>
68<hr><a name="details"></a><h2>Detailed Description</h2>
69
70
71The QAsciiDict class is a template class that provides a dictionary based on char* keys.
72<p>
73
74<p>
75<p> QAsciiDict is implemented as a template class. Define a template
76instance QAsciiDict&lt;X&gt; to create a dictionary that operates on
77pointers to X (X*).
78<p> A dictionary is a collection of key-value pairs. The key is a
79char* used for insertion, removal and lookup. The value is a
80pointer. Dictionaries provide very fast insertion and lookup.
81<p> QAsciiDict cannot handle Unicode keys; use the <a href="qdict.html">QDict</a> template
82instead, which uses <a href="qstring.html">QString</a> keys. A QDict has the same
83performace as a QAsciiDict.
84<p> Example:
85<pre>
86 QAsciiDict&lt;QLineEdit&gt; fields; // char* keys, QLineEdit* values
87 fields.<a href="#insert">insert</a>( "forename", new <a href="qlineedit.html">QLineEdit</a>( this ) );
88 fields.<a href="#insert">insert</a>( "surname", new <a href="qlineedit.html">QLineEdit</a>( this ) );
89
90 fields["forename"]-&gt;setText( "Homer" );
91 fields["surname"]-&gt;setText( "Simpson" );
92
93 <a href="qasciidictiterator.html">QAsciiDictIterator</a>&lt;QLineEdit&gt; it( fields ); // See QAsciiDictIterator
94 for( ; it.<a href="qasciidictiterator.html#current">current</a>(); ++it )
95 cout &lt;&lt; it.<a href="qasciidictiterator.html#currentKey">currentKey</a>() &lt;&lt; ": " &lt;&lt; it.<a href="qasciidictiterator.html#current">current</a>()-&gt;text() &lt;&lt; endl;
96 cout &lt;&lt; endl;
97
98 if ( fields["forename"] &amp;&amp; fields["surname"] )
99 cout &lt;&lt; fields["forename"]-&gt;text() &lt;&lt; " "
100 &lt;&lt; fields["surname"]-&gt;text() &lt;&lt; endl; // Prints "Homer Simpson"
101
102 fields.<a href="#remove">remove</a>( "forename" ); // Does not delete the line edit
103 if ( ! fields["forename"] )
104 cout &lt;&lt; "forename is not in the dictionary" &lt;&lt; endl;
105 </pre>
106
107In this example we use a dictionary to keep track of the line
108edits we're using. We insert each line edit into the dictionary
109with a unique name and then access the line edits via the
110dictionary. See <a href="qptrdict.html">QPtrDict</a>, <a href="qintdict.html">QIntDict</a> and <a href="qdict.html">QDict</a>.
111<p> See QDict for full details, including the choice of dictionary
112size, and how deletions are handled.
113<p> <p>See also <a href="qasciidictiterator.html">QAsciiDictIterator</a>, <a href="qdict.html">QDict</a>, <a href="qintdict.html">QIntDict</a>, <a href="qptrdict.html">QPtrDict</a>, <a href="collection.html">Collection Classes</a>, <a href="collection.html">Collection Classes</a>, and <a href="tools.html">Non-GUI Classes</a>.
114
115<hr><h2>Member Function Documentation</h2>
116<h3 class=fn><a name="QAsciiDict"></a>QAsciiDict::QAsciiDict ( int&nbsp;size = 17, bool&nbsp;caseSensitive = TRUE, bool&nbsp;copyKeys = TRUE )
117</h3>
118
119<p> Constructs a dictionary optimized for less than <em>size</em> entries.
120<p> We recommend setting <em>size</em> to a suitably large <a href="primes.html#prime">prime</a> number (a
121bit larger than the expected number of entries). This makes the
122hash distribution better and will improve lookup performance.
123<p> When <em>caseSensitive</em> is TRUE (the default) QAsciiDict treats
124"abc" and "Abc" as different keys; when it is FALSE "abc" and
125"Abc" are the same. Case-insensitive comparison only considers the
12626 letters in US-ASCII.
127<p> If <em>copyKeys</em> is TRUE (the default), the dictionary copies keys
128using strcpy(); if it is FALSE, the dictionary just copies the
129pointers.
130
131<h3 class=fn><a name="QAsciiDict-2"></a>QAsciiDict::QAsciiDict ( const&nbsp;<a href="qasciidict.html">QAsciiDict</a>&lt;type&gt;&nbsp;&amp;&nbsp;dict )
132</h3>
133
134<p> Constructs a copy of <em>dict</em>.
135<p> Each item in <em>dict</em> is inserted into this dictionary. Only the
136pointers are copied (shallow copy).
137
138<h3 class=fn><a name="~QAsciiDict"></a>QAsciiDict::~QAsciiDict ()
139</h3>
140
141<p> Removes all items from the dictionary and destroys it.
142<p> The items are deleted if auto-delete is enabled.
143<p> All iterators that access this dictionary will be reset.
144<p> <p>See also <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
145
146<h3 class=fn>bool <a name="autoDelete"></a>QPtrCollection::autoDelete () const
147</h3>
148
149<p> Returns the setting of the auto-delete option. The default is FALSE.
150<p> <p>See also <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
151
152<h3 class=fn>void <a name="clear"></a>QAsciiDict::clear ()<tt> [virtual]</tt>
153</h3>
154
155<p> Removes all items from the dictionary.
156<p> The removed items are deleted if <a href="qptrcollection.html#setAutoDelete">auto-deletion</a> is enabled.
157<p> All dictionary iterators that operate on dictionary are reset.
158<p> <p>See also <a href="#remove">remove</a>(), <a href="#take">take</a>(), and <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
159
160<p>Reimplemented from <a href="qptrcollection.html#clear">QPtrCollection</a>.
161<h3 class=fn>uint <a name="count"></a>QAsciiDict::count () const<tt> [virtual]</tt>
162</h3>
163
164<p> Returns the number of items in the dictionary.
165<p> <p>See also <a href="#isEmpty">isEmpty</a>().
166
167<p>Reimplemented from <a href="qptrcollection.html#count">QPtrCollection</a>.
168<h3 class=fn>type * <a name="find"></a>QAsciiDict::find ( const&nbsp;char&nbsp;*&nbsp;key ) const
169</h3>
170
171<p> Returns the item associated with <em>key</em>, or 0 if the key does not
172exist in the dictionary.
173<p> This function uses an internal hashing algorithm to optimize
174lookup.
175<p> If there are two or more items with equal keys, then the item that
176was most recently inserted will be found.
177<p> Equivalent to the [] operator.
178<p> <p>See also <a href="#operator[]">operator[]</a>().
179
180<h3 class=fn>void <a name="insert"></a>QAsciiDict::insert ( const&nbsp;char&nbsp;*&nbsp;key, const&nbsp;type&nbsp;*&nbsp;item )
181</h3>
182
183<p> Inserts the <em>key</em> with the <em>item</em> into the dictionary.
184<p> Multiple items can have the same key, in which case only the last
185item will be accessible using <a href="#operator[]">operator[]</a>().
186<p> <em>item</em> may not be 0.
187<p> <p>See also <a href="#replace">replace</a>().
188
189<h3 class=fn>bool <a name="isEmpty"></a>QAsciiDict::isEmpty () const
190</h3>
191
192<p> Returns TRUE if the dictionary is empty, i.e. <a href="#count">count</a>() == 0;
193otherwise it returns FALSE.
194<p> <p>See also <a href="#count">count</a>().
195
196<h3 class=fn><a href="qasciidict.html">QAsciiDict</a>&lt;type&gt;&nbsp;&amp; <a name="operator-eq"></a>QAsciiDict::operator= ( const&nbsp;<a href="qasciidict.html">QAsciiDict</a>&lt;type&gt;&nbsp;&amp;&nbsp;dict )
197</h3>
198
199<p> Assigns <em>dict</em> to this dictionary and returns a reference to this
200dictionary.
201<p> This dictionary is first cleared and then each item in <em>dict</em> is
202inserted into this dictionary. Only the pointers are copied
203(shallow copy) unless <a href="qptrcollection.html#newItem">newItem</a>() has been reimplemented().
204
205<h3 class=fn>type * <a name="operator[]"></a>QAsciiDict::operator[] ( const&nbsp;char&nbsp;*&nbsp;key ) const
206</h3>
207
208<p> Returns the item associated with <em>key</em>, or 0 if the key does
209not exist in the dictionary.
210<p> This function uses an internal hashing algorithm to optimize
211lookup.
212<p> If there are two or more items with equal keys, then the item that
213was most recently inserted will be found.
214<p> Equivalent to the <a href="#find">find</a>() function.
215<p> <p>See also <a href="#find">find</a>().
216
217<h3 class=fn><a href="qdatastream.html">QDataStream</a>&nbsp;&amp; <a name="read"></a>QAsciiDict::read ( <a href="qdatastream.html">QDataStream</a>&nbsp;&amp;&nbsp;s, <a href="qptrcollection.html#Item">QPtrCollection::Item</a>&nbsp;&amp;&nbsp;item )<tt> [virtual protected]</tt>
218</h3>
219
220<p> Reads a dictionary item from the stream <em>s</em> and returns a
221reference to the stream.
222<p> The default implementation sets <em>item</em> to 0.
223<p> <p>See also <a href="#write">write</a>().
224
225<h3 class=fn>bool <a name="remove"></a>QAsciiDict::remove ( const&nbsp;char&nbsp;*&nbsp;key )
226</h3>
227
228<p> Removes the item associated with <em>key</em> from the dictionary.
229Returns TRUE if successful, i.e. if the key existed in the
230dictionary; otherwise returns FALSE.
231<p> If there are two or more items with equal keys, then the most
232recently inserted item will be removed.
233<p> The removed item is deleted if <a href="qptrcollection.html#setAutoDelete">auto-deletion</a> is enabled.
234<p> All dictionary iterators that refer to the removed item will be
235set to point to the next item in the dictionary traversal order.
236<p> <p>See also <a href="#take">take</a>(), <a href="#clear">clear</a>(), and <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
237
238<h3 class=fn>void <a name="replace"></a>QAsciiDict::replace ( const&nbsp;char&nbsp;*&nbsp;key, const&nbsp;type&nbsp;*&nbsp;item )
239</h3>
240
241<p> Replaces an item that has a key equal to <em>key</em> with <em>item</em>.
242<p> If the item does not already exist, it will be inserted.
243<p> <em>item</em> may not be 0.
244<p> Equivalent to:
245<pre>
246 QAsciiDict&lt;char&gt; dict;
247 ...
248 if ( dict.<a href="#find">find</a>(key) )
249 dict.<a href="#remove">remove</a>( key );
250 dict.<a href="#insert">insert</a>( key, item );
251 </pre>
252
253<p> If there are two or more items with equal keys, then the most
254recently inserted item will be replaced.
255<p> <p>See also <a href="#insert">insert</a>().
256
257<h3 class=fn>void <a name="resize"></a>QAsciiDict::resize ( uint&nbsp;newsize )
258</h3>
259
260<p> Changes the size of the hashtable to <em>newsize</em>. The contents of
261the dictionary are preserved but all iterators on the dictionary
262become invalid.
263
264<h3 class=fn>void <a name="setAutoDelete"></a>QPtrCollection::setAutoDelete ( bool&nbsp;enable )
265</h3>
266
267<p> Sets the collection to auto-delete its contents if <em>enable</em> is
268TRUE and to never delete them if <em>enable</em> is FALSE.
269<p> If auto-deleting is turned on, all the items in a collection are
270deleted when the collection itself is deleted. This is convenient
271if the collection has the only pointer to the items.
272<p> The default setting is FALSE, for safety. If you turn it on, be
273careful about copying the collection - you might find yourself
274with two collections deleting the same items.
275<p> Note that the auto-delete setting may also affect other functions
276in subclasses. For example, a subclass that has a <a href="#remove">remove</a>()
277function will remove the item from its data structure, and if
278auto-delete is enabled, will also delete the item.
279<p> <p>See also <a href="qptrcollection.html#autoDelete">autoDelete</a>().
280
281<p>Examples: <a href="grapher-nsplugin-example.html#x2769">grapher/grapher.cpp</a>, <a href="scribble-example.html#x924">scribble/scribble.cpp</a>, and <a href="bigtable-example.html#x1291">table/bigtable/main.cpp</a>.
282<h3 class=fn>uint <a name="size"></a>QAsciiDict::size () const
283</h3>
284
285<p> Returns the size of the internal hash array (as specified in the
286constructor).
287<p> <p>See also <a href="#count">count</a>().
288
289<h3 class=fn>void <a name="statistics"></a>QAsciiDict::statistics () const
290</h3>
291
292<p> Debugging-only function that prints out the dictionary
293distribution using <a href="qapplication.html#qDebug">qDebug</a>().
294
295<h3 class=fn>type * <a name="take"></a>QAsciiDict::take ( const&nbsp;char&nbsp;*&nbsp;key )
296</h3>
297
298<p> Takes the item associated with <em>key</em> out of the dictionary
299without deleting it (even if <a href="qptrcollection.html#setAutoDelete">auto-deletion</a> is enabled).
300<p> If there are two or more items with equal keys, then the most
301recently inserted item will be taken.
302<p> Returns a pointer to the item taken out, or 0 if the key does not
303exist in the dictionary.
304<p> All dictionary iterators that refer to the taken item will be set
305to point to the next item in the dictionary traversal order.
306<p> <p>See also <a href="#remove">remove</a>(), <a href="#clear">clear</a>(), and <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
307
308<h3 class=fn><a href="qdatastream.html">QDataStream</a>&nbsp;&amp; <a name="write"></a>QAsciiDict::write ( <a href="qdatastream.html">QDataStream</a>&nbsp;&amp;&nbsp;s, <a href="qptrcollection.html#Item">QPtrCollection::Item</a> ) const<tt> [virtual protected]</tt>
309</h3>
310
311<p> Writes a dictionary item to the stream <em>s</em> and returns a
312reference to the stream.
313<p> <p>See also <a href="#read">read</a>().
314
315<!-- eof -->
316<hr><p>
317This file is part of the <a href="index.html">Qt toolkit</a>.
318Copyright &copy; 1995-2007
319<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
320<table width=100% cellspacing=0 border=0><tr>
321<td>Copyright &copy; 2007
322<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
323<td align=right><div align=right>Qt 3.3.8</div>
324</table></div></address></body>
325</html>
Note: See TracBrowser for help on using the repository browser.