summaryrefslogtreecommitdiffstats
path: root/doc/html/qdict.html
diff options
context:
space:
mode:
Diffstat (limited to 'doc/html/qdict.html')
-rw-r--r--doc/html/qdict.html399
1 files changed, 399 insertions, 0 deletions
diff --git a/doc/html/qdict.html b/doc/html/qdict.html
new file mode 100644
index 0000000..04c3047
--- /dev/null
+++ b/doc/html/qdict.html
@@ -0,0 +1,399 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/doc/qdict.doc:41 -->
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<title>QDict Class</title>
+<style type="text/css"><!--
+fn { margin-left: 1cm; text-indent: -1cm; }
+a:link { color: #004faf; text-decoration: none }
+a:visited { color: #672967; text-decoration: none }
+body { background: #ffffff; color: black; }
+--></style>
+</head>
+<body>
+
+<table border="0" cellpadding="0" cellspacing="0" width="100%">
+<tr bgcolor="#E5E5E5">
+<td valign=center>
+ <a href="index.html">
+<font color="#004faf">Home</font></a>
+ | <a href="classes.html">
+<font color="#004faf">All&nbsp;Classes</font></a>
+ | <a href="mainclasses.html">
+<font color="#004faf">Main&nbsp;Classes</font></a>
+ | <a href="annotated.html">
+<font color="#004faf">Annotated</font></a>
+ | <a href="groups.html">
+<font color="#004faf">Grouped&nbsp;Classes</font></a>
+ | <a href="functions.html">
+<font color="#004faf">Functions</font></a>
+</td>
+<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QDict Class Reference</h1>
+
+<p>The QDict class is a template class that provides a
+dictionary based on QString keys.
+<a href="#details">More...</a>
+<p><tt>#include &lt;<a href="qdict-h.html">qdict.h</a>&gt;</tt>
+<p>Inherits <a href="qptrcollection.html">QPtrCollection</a>.
+<p><a href="qdict-members.html">List of all member functions.</a>
+<h2>Public Members</h2>
+<ul>
+<li class=fn><a href="#QDict"><b>QDict</b></a> ( int&nbsp;size = 17, bool&nbsp;caseSensitive = TRUE )</li>
+<li class=fn><a href="#QDict-2"><b>QDict</b></a> ( const&nbsp;QDict&lt;type&gt;&nbsp;&amp;&nbsp;dict )</li>
+<li class=fn><a href="#~QDict"><b>~QDict</b></a> ()</li>
+<li class=fn>QDict&lt;type&gt; &amp; <a href="#operator-eq"><b>operator=</b></a> ( const&nbsp;QDict&lt;type&gt;&nbsp;&amp;&nbsp;dict )</li>
+<li class=fn>virtual uint <a href="#count"><b>count</b></a> () const</li>
+<li class=fn>uint <a href="#size"><b>size</b></a> () const</li>
+<li class=fn>bool <a href="#isEmpty"><b>isEmpty</b></a> () const</li>
+<li class=fn>void <a href="#insert"><b>insert</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;key, const&nbsp;type&nbsp;*&nbsp;item )</li>
+<li class=fn>void <a href="#replace"><b>replace</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;key, const&nbsp;type&nbsp;*&nbsp;item )</li>
+<li class=fn>bool <a href="#remove"><b>remove</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;key )</li>
+<li class=fn>type * <a href="#take"><b>take</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;key )</li>
+<li class=fn>type * <a href="#find"><b>find</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;key ) const</li>
+<li class=fn>type * <a href="#operator[]"><b>operator[]</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;key ) const</li>
+<li class=fn>virtual void <a href="#clear"><b>clear</b></a> ()</li>
+<li class=fn>void <a href="#resize"><b>resize</b></a> ( uint&nbsp;newsize )</li>
+<li class=fn>void <a href="#statistics"><b>statistics</b></a> () const</li>
+</ul>
+<h2>Important Inherited Members</h2>
+<ul>
+<li class=fn>bool <a href="#autoDelete"><b>autoDelete</b></a> () const</li>
+<li class=fn>void <a href="#setAutoDelete"><b>setAutoDelete</b></a> ( bool&nbsp;enable )</li>
+</ul>
+<h2>Protected Members</h2>
+<ul>
+<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>
+<li class=fn>virtual QDataStream &amp; <a href="#write"><b>write</b></a> ( QDataStream&nbsp;&amp;&nbsp;s, QPtrCollection::Item ) const</li>
+</ul>
+<hr><a name="details"></a><h2>Detailed Description</h2>
+
+
+The QDict class is a template class that provides a
+dictionary based on <a href="qstring.html">QString</a> keys.
+<p>
+
+
+<p>
+<p> <a href="qmap.html">QMap</a> is an STL-compatible alternative to this class.
+<p> QDict is implemented as a template class. Define a template
+instance QDict&lt;X&gt; to create a dictionary that operates on
+pointers to X (X *).
+<p> A dictionary is a collection of key-value pairs. The key is a
+QString used for insertion, removal and lookup. The value is a
+pointer. Dictionaries provide very fast insertion and lookup.
+<p> If you want to use non-Unicode, plain 8-bit <tt>char*</tt> keys, use the
+<a href="qasciidict.html">QAsciiDict</a> template. A QDict has the same performance as a
+QAsciiDict. If you want to have a dictionary that maps QStrings to
+QStrings use QMap.
+<p> The <a href="#size">size</a>() of the dictionary is very important. In order to get
+good performance, you should use a suitably large <a href="primes.html#prime">prime</a> number.
+Suitable means equal to or larger than the maximum expected number
+of dictionary items. Size is set in the constructor but may be
+changed with <a href="#resize">resize</a>().
+<p> Items are inserted with <a href="#insert">insert</a>(); 0 pointers cannot be inserted.
+Items are removed with <a href="#remove">remove</a>(). All the items in a dictionary can
+be removed with <a href="#clear">clear</a>(). The number of items in the dictionary is
+returned by <a href="#count">count</a>(). If the dictionary contains no items <a href="#isEmpty">isEmpty</a>()
+returns TRUE. You can change an item's value with <a href="#replace">replace</a>(). Items
+are looked up with <a href="#operator[]">operator[]</a>(), or with <a href="#find">find</a>() which return a
+pointer to the value or 0 if the given key does not exist. You can
+take an item out of the dictionary with <a href="#take">take</a>().
+<p> Calling <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>(TRUE) for a dictionary tells it to delete
+items that are removed. The default behaviour is not to delete
+items when they are removed.
+<p> When an item is inserted, the key is converted (hashed) to an
+integer index into an internal hash array. This makes lookup very
+fast.
+<p> Items with equal keys are allowed. When inserting two items with
+the same key, only the last inserted item will be accessible (last
+in, first out) until it is removed.
+<p> The <a href="qdictiterator.html">QDictIterator</a> class can traverse the dictionary, but only in
+an arbitrary order. Multiple iterators may independently traverse
+the same dictionary.
+<p> When inserting an item into a dictionary, only the pointer is
+copied, not the item itself, i.e. a <a href="shclass.html#shallow-copy">shallow copy</a> is made. It is
+possible to make the dictionary copy all of the item's data (a
+<a href="shclass.html#deep-copy">deep copy</a>) when an item is inserted. <a href="#insert">insert</a>() calls the virtual
+function <a href="qptrcollection.html#newItem">QPtrCollection::newItem</a>() for the item to be inserted.
+Inherit a dictionary and reimplement <a href="qptrcollection.html#newItem">newItem</a>() if you want deep
+copies.
+<p> When removing a dictionary item, the virtual function
+<a href="qptrcollection.html#deleteItem">QPtrCollection::deleteItem</a>() is called. QDict's default
+implementation is to delete the item if auto-deletion is enabled.
+<p> Example #1:
+<pre>
+ QDict&lt;QLineEdit&gt; fields; // QString keys, QLineEdit* values
+ fields.<a href="#insert">insert</a>( "forename", new <a href="qlineedit.html">QLineEdit</a>( this ) );
+ fields.<a href="#insert">insert</a>( "surname", new <a href="qlineedit.html">QLineEdit</a>( this ) );
+
+ fields["forename"]-&gt;setText( "Homer" );
+ fields["surname"]-&gt;setText( "Simpson" );
+
+ <a href="qdictiterator.html">QDictIterator</a>&lt;QLineEdit&gt; it( fields ); // See QDictIterator
+ for( ; it.<a href="qdictiterator.html#current">current</a>(); ++it )
+ cout &lt;&lt; it.<a href="qdictiterator.html#currentKey">currentKey</a>() &lt;&lt; ": " &lt;&lt; it.<a href="qdictiterator.html#current">current</a>()-&gt;text() &lt;&lt; endl;
+ cout &lt;&lt; endl;
+
+ if ( fields["forename"] &amp;&amp; fields["surname"] )
+ cout &lt;&lt; fields["forename"]-&gt;text() &lt;&lt; " "
+ &lt;&lt; fields["surname"]-&gt;text() &lt;&lt; endl; // Prints "Homer Simpson"
+
+ fields.<a href="#remove">remove</a>( "forename" ); // Does not delete the line edit
+ if ( ! fields["forename"] )
+ cout &lt;&lt; "forename is not in the dictionary" &lt;&lt; endl;
+ </pre>
+
+In this example we use a dictionary to keep track of the line
+edits we're using. We insert each line edit into the dictionary
+with a unique name and then access the line edits via the
+dictionary.
+<p> Example #2:
+<pre>
+ <a href="qstringlist.html">QStringList</a> styleList = QStyleFactory::styles();
+ styleList.<a href="qstringlist.html#sort">sort</a>();
+ QDict&lt;int&gt; letterDict( 17, FALSE );
+ for ( QStringList::Iterator it = styleList.<a href="qvaluelist.html#begin">begin</a>(); it != styleList.<a href="qvaluelist.html#end">end</a>(); ++it ) {
+ <a href="qstring.html">QString</a> styleName = *it;
+ <a href="qstring.html">QString</a> styleAccel = styleName;
+ if ( letterDict[styleAccel.<a href="qstring.html#left">left</a>(1)] ) {
+ for ( uint i = 0; i &lt; styleAccel.<a href="qstring.html#length">length</a>(); i++ ) {
+ if ( ! letterDict[styleAccel.<a href="qstring.html#mid">mid</a>( i, 1 )] ) {
+ styleAccel = styleAccel.<a href="qstring.html#insert">insert</a>( i, '&amp;' );
+ letterDict.<a href="#insert">insert</a>(styleAccel.<a href="qstring.html#mid">mid</a>( i, 1 ), (const int *)1);
+ break;
+ }
+ }
+ } else {
+ styleAccel = "&amp;" + styleAccel;
+ letterDict.<a href="#insert">insert</a>(styleAccel.<a href="qstring.html#left">left</a>(1), (const int *)1);
+ }
+ (void) new <a href="qaction.html">QAction</a>( styleName, QIconSet(), styleAccel, parent );
+ }
+ </pre>
+
+In the example we are using the dictionary to provide fast random
+access to the keys, and we don't care what the values are. The
+example is used to generate a menu of QStyles, each with a unique
+accelerator key (or no accelerator if there are no unused letters
+left).
+<p> We first obtain the list of available styles, then sort them so
+that the menu items will be ordered alphabetically. Next we create
+a dictionary of int pointers. The keys in the dictionary are each
+one character long, representing letters that have been used for
+accelerators. We iterate through our list of style names. If the
+first letter of the style name is in the dictionary, i.e. has been
+used, we iterate over all the characters in the style name to see
+if we can find a letter that hasn't been used. If we find an
+unused letter we put the accelerator ampersand (&) in front of it
+and add that letter to the dictionary. If we can't find an unused
+letter the style will simply have no accelerator. If the first
+letter of the style name is not in the dictionary we use it for
+the accelerator and add it to the dictionary. Finally we create a
+<a href="qaction.html">QAction</a> for each style.
+<p> <p>See also <a href="qdictiterator.html">QDictIterator</a>, <a href="qasciidict.html">QAsciiDict</a>, <a href="qintdict.html">QIntDict</a>, <a href="qptrdict.html">QPtrDict</a>, <a href="collection.html">Collection Classes</a>, and <a href="tools.html">Non-GUI Classes</a>.
+
+<hr><h2>Member Function Documentation</h2>
+<h3 class=fn><a name="QDict"></a>QDict::QDict ( int&nbsp;size = 17, bool&nbsp;caseSensitive = TRUE )
+</h3>
+
+<p> Constructs a dictionary optimized for less than <em>size</em> entries.
+<p> We recommend setting <em>size</em> to a suitably large <a href="primes.html#prime">prime</a> number
+(e.g. a prime that's slightly larger than the expected number of
+entries). This makes the hash distribution better which will lead
+to faster lookup.
+<p> If <em>caseSensitive</em> is TRUE (the default), keys which differ only
+by case are considered different.
+
+<h3 class=fn><a name="QDict-2"></a>QDict::QDict ( const&nbsp;<a href="qdict.html">QDict</a>&lt;type&gt;&nbsp;&amp;&nbsp;dict )
+</h3>
+
+<p> Constructs a copy of <em>dict</em>.
+<p> Each item in <em>dict</em> is inserted into this dictionary. Only the
+pointers are copied (shallow copy).
+
+<h3 class=fn><a name="~QDict"></a>QDict::~QDict ()
+</h3>
+
+<p> Removes all items from the dictionary and destroys it. If
+<a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>() is TRUE, each value is deleted. All iterators that
+access this dictionary will be reset.
+<p> <p>See also <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
+
+<h3 class=fn>bool <a name="autoDelete"></a>QPtrCollection::autoDelete () const
+</h3>
+
+<p> Returns the setting of the auto-delete option. The default is FALSE.
+<p> <p>See also <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
+
+<h3 class=fn>void <a name="clear"></a>QDict::clear ()<tt> [virtual]</tt>
+</h3>
+
+<p> Removes all items from the dictionary.
+<p> The removed items are deleted if <a href="qptrcollection.html#setAutoDelete">auto-deletion</a> is enabled.
+<p> All dictionary iterators that operate on the dictionary are reset.
+<p> <p>See also <a href="#remove">remove</a>(), <a href="#take">take</a>(), and <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
+
+<p>Reimplemented from <a href="qptrcollection.html#clear">QPtrCollection</a>.
+<h3 class=fn>uint <a name="count"></a>QDict::count () const<tt> [virtual]</tt>
+</h3>
+
+<p> Returns the number of items in the dictionary.
+<p> <p>See also <a href="#isEmpty">isEmpty</a>().
+
+<p>Reimplemented from <a href="qptrcollection.html#count">QPtrCollection</a>.
+<h3 class=fn>type * <a name="find"></a>QDict::find ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;key ) const
+</h3>
+
+<p> Returns the item with key <em>key</em>, or 0 if the key does not exist
+in the dictionary.
+<p> If there are two or more items with equal keys, then the most
+recently inserted item will be found.
+<p> Equivalent to the [] operator.
+<p> <p>See also <a href="#operator[]">operator[]</a>().
+
+<h3 class=fn>void <a name="insert"></a>QDict::insert ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;key, const&nbsp;type&nbsp;*&nbsp;item )
+</h3>
+
+<p> Inserts the key <em>key</em> with value <em>item</em> into the dictionary.
+<p> Multiple items can have the same key, in which case only the last
+item will be accessible using <a href="#operator[]">operator[]</a>().
+<p> <em>item</em> may not be 0.
+<p> <p>See also <a href="#replace">replace</a>().
+
+<p>Example: <a href="themes-example.html#x326">themes/themes.cpp</a>.
+<h3 class=fn>bool <a name="isEmpty"></a>QDict::isEmpty () const
+</h3>
+
+<p> Returns TRUE if the dictionary is empty, i.e. <a href="#count">count</a>() == 0;
+otherwise returns FALSE.
+<p> <p>See also <a href="#count">count</a>().
+
+<h3 class=fn><a href="qdict.html">QDict</a>&lt;type&gt;&nbsp;&amp; <a name="operator-eq"></a>QDict::operator= ( const&nbsp;<a href="qdict.html">QDict</a>&lt;type&gt;&nbsp;&amp;&nbsp;dict )
+</h3>
+
+<p> Assigns <em>dict</em> to this dictionary and returns a reference to this
+dictionary.
+<p> This dictionary is first cleared, then each item in <em>dict</em> is
+inserted into this dictionary. Only the pointers are copied
+(shallow copy), unless <a href="qptrcollection.html#newItem">newItem</a>() has been reimplemented.
+
+<h3 class=fn>type * <a name="operator[]"></a>QDict::operator[] ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;key ) const
+</h3>
+
+<p> Returns the item with key <em>key</em>, or 0 if the key does not
+exist in the dictionary.
+<p> If there are two or more items with equal keys, then the most
+recently inserted item will be found.
+<p> Equivalent to the <a href="#find">find</a>() function.
+<p> <p>See also <a href="#find">find</a>().
+
+<h3 class=fn><a href="qdatastream.html">QDataStream</a>&nbsp;&amp; <a name="read"></a>QDict::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>
+</h3>
+
+<p> Reads a dictionary item from the stream <em>s</em> and returns a
+reference to the stream.
+<p> The default implementation sets <em>item</em> to 0.
+<p> <p>See also <a href="#write">write</a>().
+
+<h3 class=fn>bool <a name="remove"></a>QDict::remove ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;key )
+</h3>
+
+<p> Removes the item with <em>key</em> from the dictionary. Returns TRUE if
+successful, i.e. if the item is in the dictionary; otherwise
+returns FALSE.
+<p> If there are two or more items with equal keys, then the last item
+that was inserted will be removed.
+<p> The removed item is deleted if <a href="qptrcollection.html#setAutoDelete">auto-deletion</a> is enabled.
+<p> All dictionary iterators that refer to the removed item will be
+set to point to the next item in the dictionary's traversal order.
+<p> <p>See also <a href="#take">take</a>(), <a href="#clear">clear</a>(), and <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
+
+<h3 class=fn>void <a name="replace"></a>QDict::replace ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;key, const&nbsp;type&nbsp;*&nbsp;item )
+</h3>
+
+<p> Replaces the value of the key, <em>key</em> with <em>item</em>.
+<p> If the item does not already exist, it will be inserted.
+<p> <em>item</em> may not be 0.
+<p> Equivalent to:
+<pre>
+ QDict&lt;char&gt; dict;
+ ...
+ if ( dict.<a href="#find">find</a>( key ) )
+ dict.<a href="#remove">remove</a>( key );
+ dict.<a href="#insert">insert</a>( key, item );
+ </pre>
+
+<p> If there are two or more items with equal keys, then the last item
+that was inserted will be replaced.
+<p> <p>See also <a href="#insert">insert</a>().
+
+<h3 class=fn>void <a name="resize"></a>QDict::resize ( uint&nbsp;newsize )
+</h3>
+
+<p> Changes the size of the hash table to <em>newsize</em>. The contents of
+the dictionary are preserved, but all iterators on the dictionary
+become invalid.
+
+<h3 class=fn>void <a name="setAutoDelete"></a>QPtrCollection::setAutoDelete ( bool&nbsp;enable )
+</h3>
+
+<p> Sets the collection to auto-delete its contents if <em>enable</em> is
+TRUE and to never delete them if <em>enable</em> is FALSE.
+<p> If auto-deleting is turned on, all the items in a collection are
+deleted when the collection itself is deleted. This is convenient
+if the collection has the only pointer to the items.
+<p> The default setting is FALSE, for safety. If you turn it on, be
+careful about copying the collection - you might find yourself
+with two collections deleting the same items.
+<p> Note that the auto-delete setting may also affect other functions
+in subclasses. For example, a subclass that has a <a href="#remove">remove</a>()
+function will remove the item from its data structure, and if
+auto-delete is enabled, will also delete the item.
+<p> <p>See also <a href="qptrcollection.html#autoDelete">autoDelete</a>().
+
+<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>.
+<h3 class=fn>uint <a name="size"></a>QDict::size () const
+</h3>
+
+<p> Returns the size of the internal hash array (as specified in the
+constructor).
+<p> <p>See also <a href="#count">count</a>().
+
+<h3 class=fn>void <a name="statistics"></a>QDict::statistics () const
+</h3>
+
+<p> Debugging-only function that prints out the dictionary
+distribution using <a href="qapplication.html#qDebug">qDebug</a>().
+
+<h3 class=fn>type * <a name="take"></a>QDict::take ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;key )
+</h3>
+
+<p> Takes the item with <em>key</em> out of the dictionary without deleting
+it (even if <a href="qptrcollection.html#setAutoDelete">auto-deletion</a> is enabled).
+<p> If there are two or more items with equal keys, then the last item
+that was inserted will be taken.
+<p> Returns a pointer to the item taken out, or 0 if the key does not
+exist in the dictionary.
+<p> All dictionary iterators that refer to the taken item will be set
+to point to the next item in the dictionary traversal order.
+<p> <p>See also <a href="#remove">remove</a>(), <a href="#clear">clear</a>(), and <a href="qptrcollection.html#setAutoDelete">setAutoDelete</a>().
+
+<h3 class=fn><a href="qdatastream.html">QDataStream</a>&nbsp;&amp; <a name="write"></a>QDict::write ( <a href="qdatastream.html">QDataStream</a>&nbsp;&amp;&nbsp;s, <a href="qptrcollection.html#Item">QPtrCollection::Item</a> ) const<tt> [virtual protected]</tt>
+</h3>
+
+<p> Writes a dictionary item to the stream <em>s</em> and returns a
+reference to the stream.
+<p> <p>See also <a href="#read">read</a>().
+
+<!-- eof -->
+<hr><p>
+This file is part of the <a href="index.html">Qt toolkit</a>.
+Copyright &copy; 1995-2007
+<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
+<table width=100% cellspacing=0 border=0><tr>
+<td>Copyright &copy; 2007
+<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
+<td align=right><div align=right>Qt 3.3.8</div>
+</table></div></address></body>
+</html>