hash_tables.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

Inserts a new key and value into a <link linkend="GHashTable">GHashTable</link>.
</para>
<para>
If the key already exists in the <link linkend="GHashTable">GHashTable</link> its current value is replaced
with the new value. If you supplied a <parameter>value_destroy_func</parameter> when creating the 
<link linkend="GHashTable">GHashTable</link>, the old value is freed using that function. If you supplied
a <parameter>key_destroy_func</parameter> when creating the <link linkend="GHashTable">GHashTable</link>, the passed key is freed 
using that function.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hash_table</parameter>&nbsp;:</entry>
<entry> a <link linkend="GHashTable">GHashTable</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> a key to insert.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> the value to associate with the key.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-hash-table-replace">g_hash_table_replace ()</title>
<programlisting>void        g_hash_table_replace            (<link linkend="GHashTable">GHashTable</link> *hash_table,
                                             <link linkend="gpointer">gpointer</link> key,
                                             <link linkend="gpointer">gpointer</link> value);</programlisting>
<para>
Inserts a new key and value into a <link linkend="GHashTable">GHashTable</link> similar to 
<link linkend="g-hash-table-insert">g_hash_table_insert</link>(). The difference is that if the key already exists 
in the <link linkend="GHashTable">GHashTable</link>, it gets replaced by the new key. If you supplied a 
<parameter>value_destroy_func</parameter> when creating the <link linkend="GHashTable">GHashTable</link>, the old value is freed 
using that function. If you supplied a <parameter>key_destroy_func</parameter> when creating the 
<link linkend="GHashTable">GHashTable</link>, the old key is freed using that function.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hash_table</parameter>&nbsp;:</entry>
<entry> a <link linkend="GHashTable">GHashTable</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> a key to insert.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> the value to associate with the key.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-hash-table-size">g_hash_table_size ()</title>
<programlisting><link linkend="guint">guint</link>       g_hash_table_size               (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
<para>
Returns the number of elements contained in the <link linkend="GHashTable">GHashTable</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hash_table</parameter>&nbsp;:</entry>
<entry> a <link linkend="GHashTable">GHashTable</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the number of key/value pairs in the <link linkend="GHashTable">GHashTable</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-hash-table-lookup">g_hash_table_lookup ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_hash_table_lookup             (<link linkend="GHashTable">GHashTable</link> *hash_table,
                                             <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
<para>
Looks up a key in a <link linkend="GHashTable">GHashTable</link>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hash_table</parameter>&nbsp;:</entry>
<entry> a <link linkend="GHashTable">GHashTable</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to look up.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the associated value, or <literal>NULL</literal> if the key is not found.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-hash-table-lookup-extended">g_hash_table_lookup_extended ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_hash_table_lookup_extended    (<link linkend="GHashTable">GHashTable</link> *hash_table,
                                             <link linkend="gconstpointer">gconstpointer</link> lookup_key,
                                             <link linkend="gpointer">gpointer</link> *orig_key,
                                             <link linkend="gpointer">gpointer</link> *value);</programlisting>
<para>
Looks up a key in the <link linkend="GHashTable">GHashTable</link>, returning the original key and the
associated value and a <link linkend="gboolean">gboolean</link> which is <literal>TRUE</literal> if the key was found. This 
is useful if you need to free the memory allocated for the original key, 
for example before calling <link linkend="g-hash-table-remove">g_hash_table_remove</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hash_table</parameter>&nbsp;:</entry>
<entry> a <link linkend="GHashTable">GHashTable</link>.
</entry></row>
<row><entry align="right"><parameter>lookup_key</parameter>&nbsp;:</entry>
<entry> the key to look up.
</entry></row>
<row><entry align="right"><parameter>orig_key</parameter>&nbsp;:</entry>
<entry> returns the original key.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry> returns the value associated with the key.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the key was found in the <link linkend="GHashTable">GHashTable</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-hash-table-foreach">g_hash_table_foreach ()</title>
<programlisting>void        g_hash_table_foreach            (<link linkend="GHashTable">GHashTable</link> *hash_table,
                                             <link linkend="GHFunc">GHFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Calls the given function for each of the key/value pairs in the
<link linkend="GHashTable">GHashTable</link>.  The function is passed the key and value of each
pair, and the given <parameter>user_data</parameter> parameter.  The hash table may not
be modified while iterating over it (you can't add/remove
items). To remove all items matching a predicate, use
<link linkend="g-hash-table-remove">g_hash_table_remove</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hash_table</parameter>&nbsp;:</entry>
<entry> a <link linkend="GHashTable">GHashTable</link>.
</entry></row>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry> the function to call for each key/value pair.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> user data to pass to the function.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GHFunc">GHFunc ()</title>
<programlisting>void        (*GHFunc)                       (<link linkend="gpointer">gpointer</link> key,
                                             <link linkend="gpointer">gpointer</link> value,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Specifies the type of the function passed to <link linkend="g-hash-table-foreach">g_hash_table_foreach</link>().
It is called with each key/value pair, together with the <parameter>user_data</parameter> parameter
which is passed to <link linkend="g-hash-table-foreach">g_hash_table_foreach</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry>a key.
</entry></row>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>the value corresponding to the key.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry>user data passed to <link linkend="g-hash-table-foreach">g_hash_table_foreach</link>().


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-hash-table-remove">g_hash_table_remove ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_hash_table_remove             (<link linkend="GHashTable">GHashTable</link> *hash_table,
                                             <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
<para>
Removes a key and its associated value from a <link linkend="GHashTable">GHashTable</link>.
</para>
<para>
If the <link linkend="GHashTable">GHashTable</link> was created using <link linkend="g-hash-table-new-full">g_hash_table_new_full</link>(), the
key and value are freed using the supplied destroy functions, otherwise
you have to make sure that any dynamically allocated values are freed 
yourself.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hash_table</parameter>&nbsp;:</entry>
<entry> a <link linkend="GHashTable">GHashTable</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to remove.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the key was found and removed from the <link linkend="GHashTable">GHashTable</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-hash-table-steal">g_hash_table_steal ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_hash_table_steal              (<link linkend="GHashTable">GHashTable</link> *hash_table,
                                             <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
<para>
Removes a key and its associated value from a <link linkend="GHashTable">GHashTable</link> without
calling the key and value destroy functions.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hash_table</parameter>&nbsp;:</entry>
<entry> a <link linkend="GHashTable">GHashTable</link>.
</entry></row>
<row><entry align="right"><parameter>key</parameter>&nbsp;:</entry>
<entry> the key to remove.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the key was found and removed from the <link linkend="GHashTable">GHashTable</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-hash-table-foreach-remove">g_hash_table_foreach_remove ()</title>
<programlisting><link linkend="guint">guint</link>       g_hash_table_foreach_remove     (<link linkend="GHashTable">GHashTable</link> *hash_table,
                                             <link linkend="GHRFunc">GHRFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Calls the given function for each key/value pair in the <link linkend="GHashTable">GHashTable</link>.
If the function returns <literal>TRUE</literal>, then the key/value pair is removed from the
<link linkend="GHashTable">GHashTable</link>. If you supplied key or value destroy functions when creating
the <link linkend="GHashTable">GHashTable</link>, they are used to free the memory allocated for the removed
keys and values.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>hash_table</parameter>&nbsp;:</entry>
<entry> a <link linkend="GHashTable">GHashTable</link>.
</entry></row>
<row><entry align="right"><parameter>func</parameter>&nbsp;:</entry>
<entry> the function to call for each key/value pair.
</entry></row>
<row><entry align="right"><parameter>user_data</parameter>&nbsp;:</entry>
<entry> user data to pass to the function.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the number of key/value pairs removed.
</entry></row>
</tbody></tgroup></informaltable></refsect2>