← Back to branch summary

~ubuntu-branches/debian/jessie/glib2.0/jessie

« back to all changes in this revision

Viewing changes to docs/reference/glib/xml/hash_tables.xml

  • Committer: Bazaar Package Importer
  • Author(s): Gustavo Noronha Silva
  • Date: 2009-02-15 13:00:43 UTC
  • mto: (1.4.3 upstream)
  • mto: This revision was merged to the branch mainline in revision 70.
  • Revision ID: james.westby@ubuntu.com-20090215130043-6snh45flhit8oalb
Tags: upstream-2.18.4
Import upstream version 2.18.4

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/glib/xml/hash_tables.xml
1
1
<refentry id="glib-Hash-Tables">
2
2
<refmeta>
3
 
<refentrytitle role="top_of_page">Hash Tables</refentrytitle>
 
3
<refentrytitle role="top_of_page" id="glib-Hash-Tables.top_of_page">Hash Tables</refentrytitle>
4
4
<manvolnum>3</manvolnum>
5
5
<refmiscinfo>GLIB Library</refmiscinfo>
6
6
</refmeta>
9
9
<refname>Hash Tables</refname>
10
10
<refpurpose>associations between keys and values so that given a key the value
11
11
can be found quickly</refpurpose>
12
 
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
13
12
</refnamediv>
14
13
 
15
 
<refsynopsisdiv role="synopsis">
 
14
<refsynopsisdiv id="glib-Hash-Tables.synopsis" role="synopsis">
16
15
<title role="synopsis.title">Synopsis</title>
17
16
 
18
17
<synopsis>
19
18
 
20
19
#include &lt;glib.h&gt;
21
20
 
22
 
 
23
21
                    <link linkend="GHashTable">GHashTable</link>;
24
22
<link linkend="GHashTable">GHashTable</link>*         <link linkend="g-hash-table-new">g_hash_table_new</link>                    (<link linkend="GHashFunc">GHashFunc</link> hash_func,
25
23
                                                         <link linkend="GEqualFunc">GEqualFunc</link> key_equal_func);
64
62
                                                         <link linkend="gpointer">gpointer</link> user_data);
65
63
<link linkend="void">void</link>                <link linkend="g-hash-table-remove-all">g_hash_table_remove_all</link>             (<link linkend="GHashTable">GHashTable</link> *hash_table);
66
64
<link linkend="void">void</link>                <link linkend="g-hash-table-steal-all">g_hash_table_steal_all</link>              (<link linkend="GHashTable">GHashTable</link> *hash_table);
67
 
<link linkend="GList">GList</link>*              <link linkend="g-hash-table-get-keys">g_hash_table_get_keys</link>               (<link linkend="GHashTable">GHashTable</link> *hash_table);
68
 
<link linkend="GList">GList</link>*              <link linkend="g-hash-table-get-values">g_hash_table_get_values</link>             (<link linkend="GHashTable">GHashTable</link> *hash_table);
 
65
<link linkend="GList">GList</link> *             <link linkend="g-hash-table-get-keys">g_hash_table_get_keys</link>               (<link linkend="GHashTable">GHashTable</link> *hash_table);
 
66
<link linkend="GList">GList</link> *             <link linkend="g-hash-table-get-values">g_hash_table_get_values</link>             (<link linkend="GHashTable">GHashTable</link> *hash_table);
69
67
<link linkend="gboolean">gboolean</link>            (<link linkend="GHRFunc">*GHRFunc</link>)                          (<link linkend="gpointer">gpointer</link> key,
70
68
                                                         <link linkend="gpointer">gpointer</link> value,
71
69
                                                         <link linkend="gpointer">gpointer</link> user_data);
104
102
 
105
103
 
106
104
 
107
 
<refsect1 role="desc">
 
105
<refsect1 id="glib-Hash-Tables.description" role="desc">
108
106
<title role="desc.title">Description</title>
109
107
<para>
110
108
A <link linkend="GHashTable"><type>GHashTable</type></link> provides associations between keys and values which
149
147
</para>
150
148
</refsect1>
151
149
 
152
 
<refsect1 role="details">
 
150
<refsect1 id="glib-Hash-Tables.details" role="details">
153
151
<title role="details.title">Details</title>
154
 
<refsect2>
155
 
<title><anchor id="GHashTable" role="struct"/>GHashTable</title>
156
 
<indexterm><primary>GHashTable</primary></indexterm><programlisting>typedef struct _GHashTable GHashTable;</programlisting>
 
152
<refsect2 id="GHashTable" role="struct">
 
153
<title>GHashTable</title>
 
154
<indexterm zone="GHashTable"><primary sortas="GHashTable">GHashTable</primary></indexterm><programlisting>typedef struct _GHashTable GHashTable;</programlisting>
157
155
<para>
158
156
The <structname>GHashTable</structname> struct is an opaque data structure to represent a
159
157
<link linkend="glib-Hash-Tables">Hash Table</link>.
160
158
It should only be accessed via the following functions.
161
159
</para></refsect2>
162
 
<refsect2>
163
 
<title><anchor id="g-hash-table-new" role="function"/>g_hash_table_new ()</title>
164
 
<indexterm><primary>g_hash_table_new</primary></indexterm><programlisting><link linkend="GHashTable">GHashTable</link>*         g_hash_table_new                    (<link linkend="GHashFunc">GHashFunc</link> hash_func,
 
160
<refsect2 id="g-hash-table-new" role="function">
 
161
<title>g_hash_table_new ()</title>
 
162
<indexterm zone="g-hash-table-new"><primary sortas="g_hash_table_new">g_hash_table_new</primary></indexterm><programlisting><link linkend="GHashTable">GHashTable</link>*         g_hash_table_new                    (<link linkend="GHashFunc">GHashFunc</link> hash_func,
165
163
                                                         <link linkend="GEqualFunc">GEqualFunc</link> key_equal_func);</programlisting>
166
164
<para>
167
165
Creates a new <link linkend="GHashTable"><type>GHashTable</type></link> with a reference count of 1.</para>
168
166
<para>
169
 
 
170
167
</para><variablelist role="params">
171
 
<varlistentry><term><parameter>hash_func</parameter>&nbsp;:</term>
 
168
<varlistentry><term><parameter>hash_func</parameter>&#160;:</term>
172
169
<listitem><simpara> a function to create a hash value from a key.
173
170
  Hash values are used to determine where keys are stored within the
174
171
  <link linkend="GHashTable"><type>GHashTable</type></link> data structure. The <link linkend="g-direct-hash"><function>g_direct_hash()</function></link>, <link linkend="g-int-hash"><function>g_int_hash()</function></link> and
175
172
  <link linkend="g-str-hash"><function>g_str_hash()</function></link> functions are provided for some common types of keys.
176
 
  If hash_func is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, <link linkend="g-direct-hash"><function>g_direct_hash()</function></link> is used.
 
173
  If hash_func is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, <link linkend="g-direct-hash"><function>g_direct_hash()</function></link> is used.
177
174
</simpara></listitem></varlistentry>
178
 
<varlistentry><term><parameter>key_equal_func</parameter>&nbsp;:</term>
 
175
<varlistentry><term><parameter>key_equal_func</parameter>&#160;:</term>
179
176
<listitem><simpara> a function to check two keys for equality.  This is
180
177
  used when looking up keys in the <link linkend="GHashTable"><type>GHashTable</type></link>.  The <link linkend="g-direct-equal"><function>g_direct_equal()</function></link>,
181
178
  <link linkend="g-int-equal"><function>g_int_equal()</function></link> and <link linkend="g-str-equal"><function>g_str_equal()</function></link> functions are provided for the most
182
 
  common types of keys. If <parameter>key_equal_func</parameter> is <link linkend="NULL:CAPS"><literal>NULL</literal></link>, keys are compared
 
179
  common types of keys. If <parameter>key_equal_func</parameter> is <link linkend="NULL--CAPS"><literal>NULL</literal></link>, keys are compared
183
180
  directly in a similar fashion to <link linkend="g-direct-equal"><function>g_direct_equal()</function></link>, but without the
184
181
  overhead of a function call.
185
182
</simpara></listitem></varlistentry>
186
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="GHashTable"><type>GHashTable</type></link>.
 
183
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GHashTable"><type>GHashTable</type></link>.
187
184
</simpara></listitem></varlistentry>
188
185
</variablelist></refsect2>
189
 
<refsect2>
190
 
<title><anchor id="g-hash-table-new-full" role="function"/>g_hash_table_new_full ()</title>
191
 
<indexterm><primary>g_hash_table_new_full</primary></indexterm><programlisting><link linkend="GHashTable">GHashTable</link>*         g_hash_table_new_full               (<link linkend="GHashFunc">GHashFunc</link> hash_func,
 
186
<refsect2 id="g-hash-table-new-full" role="function">
 
187
<title>g_hash_table_new_full ()</title>
 
188
<indexterm zone="g-hash-table-new-full"><primary sortas="g_hash_table_new_full">g_hash_table_new_full</primary></indexterm><programlisting><link linkend="GHashTable">GHashTable</link>*         g_hash_table_new_full               (<link linkend="GHashFunc">GHashFunc</link> hash_func,
192
189
                                                         <link linkend="GEqualFunc">GEqualFunc</link> key_equal_func,
193
190
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> key_destroy_func,
194
191
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> value_destroy_func);</programlisting>
197
194
of 1 and allows to specify functions to free the memory allocated for the
198
195
key and value that get called when removing the entry from the <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
199
196
<para>
200
 
 
201
197
</para><variablelist role="params">
202
 
<varlistentry><term><parameter>hash_func</parameter>&nbsp;:</term>
 
198
<varlistentry><term><parameter>hash_func</parameter>&#160;:</term>
203
199
<listitem><simpara> a function to create a hash value from a key.
204
200
</simpara></listitem></varlistentry>
205
 
<varlistentry><term><parameter>key_equal_func</parameter>&nbsp;:</term>
 
201
<varlistentry><term><parameter>key_equal_func</parameter>&#160;:</term>
206
202
<listitem><simpara> a function to check two keys for equality.
207
203
</simpara></listitem></varlistentry>
208
 
<varlistentry><term><parameter>key_destroy_func</parameter>&nbsp;:</term>
 
204
<varlistentry><term><parameter>key_destroy_func</parameter>&#160;:</term>
209
205
<listitem><simpara> a function to free the memory allocated for the key
210
 
  used when removing the entry from the <link linkend="GHashTable"><type>GHashTable</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if you
 
206
  used when removing the entry from the <link linkend="GHashTable"><type>GHashTable</type></link> or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if you
211
207
  don't want to supply such a function.
212
208
</simpara></listitem></varlistentry>
213
 
<varlistentry><term><parameter>value_destroy_func</parameter>&nbsp;:</term>
 
209
<varlistentry><term><parameter>value_destroy_func</parameter>&#160;:</term>
214
210
<listitem><simpara> a function to free the memory allocated for the
215
 
  value used when removing the entry from the <link linkend="GHashTable"><type>GHashTable</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if
 
211
  value used when removing the entry from the <link linkend="GHashTable"><type>GHashTable</type></link> or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if
216
212
  you don't want to supply such a function.
217
213
</simpara></listitem></varlistentry>
218
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a new <link linkend="GHashTable"><type>GHashTable</type></link>.
 
214
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a new <link linkend="GHashTable"><type>GHashTable</type></link>.
219
215
</simpara></listitem></varlistentry>
220
216
</variablelist></refsect2>
221
 
<refsect2>
222
 
<title><anchor id="GHashFunc" role="function"/>GHashFunc ()</title>
223
 
<indexterm><primary>GHashFunc</primary></indexterm><programlisting><link linkend="guint">guint</link>               (*GHashFunc)                        (<link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
 
217
<refsect2 id="GHashFunc" role="function">
 
218
<title>GHashFunc ()</title>
 
219
<indexterm zone="GHashFunc"><primary sortas="GHashFunc">GHashFunc</primary></indexterm><programlisting><link linkend="guint">guint</link>               (*GHashFunc)                        (<link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
224
220
<para>
225
221
Specifies the type of the hash function which is passed to
226
222
<link linkend="g-hash-table-new"><function>g_hash_table_new()</function></link> when a <link linkend="GHashTable"><type>GHashTable</type></link> is created.
228
224
<para>
229
225
The function is passed a key and should return a <link linkend="guint"><type>guint</type></link> hash value.
230
226
The functions <link linkend="g-direct-hash"><function>g_direct_hash()</function></link>, <link linkend="g-int-hash"><function>g_int_hash()</function></link> and <link linkend="g-str-hash"><function>g_str_hash()</function></link> provide
231
 
hash functions which can be used when the key is a <link linkend="gpointer"><type>gpointer</type></link>, <link linkend="gint"><type>gint</type></link>, and 
 
227
hash functions which can be used when the key is a <link linkend="gpointer"><type>gpointer</type></link>, <link linkend="gint"><type>gint</type></link>, and
232
228
<link linkend="gchar"><type>gchar</type></link>* respectively.
233
229
</para>
234
230
<para>
239
235
The function should also be very fast, since it is called for each key
240
236
lookup.
241
237
</para><variablelist role="params">
242
 
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
238
<varlistentry><term><parameter>key</parameter>&#160;:</term>
243
239
<listitem><simpara>a key.
244
240
</simpara></listitem></varlistentry>
245
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>the hash value corresponding to the key.
246
 
 
247
 
 
 
241
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the hash value corresponding to the key.
248
242
</simpara></listitem></varlistentry>
249
243
</variablelist></refsect2>
250
 
<refsect2>
251
 
<title><anchor id="GEqualFunc" role="function"/>GEqualFunc ()</title>
252
 
<indexterm><primary>GEqualFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GEqualFunc)                       (<link linkend="gconstpointer">gconstpointer</link> a,
 
244
<refsect2 id="GEqualFunc" role="function">
 
245
<title>GEqualFunc ()</title>
 
246
<indexterm zone="GEqualFunc"><primary sortas="GEqualFunc">GEqualFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GEqualFunc)                       (<link linkend="gconstpointer">gconstpointer</link> a,
253
247
                                                         <link linkend="gconstpointer">gconstpointer</link> b);</programlisting>
254
248
<para>
255
249
Specifies the type of a function used to test two values for
256
 
equality. The function should return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if both values are equal and
257
 
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
 
250
equality. The function should return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if both values are equal and
 
251
<link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
258
252
</para><variablelist role="params">
259
 
<varlistentry><term><parameter>a</parameter>&nbsp;:</term>
 
253
<varlistentry><term><parameter>a</parameter>&#160;:</term>
260
254
<listitem><simpara>a value.
261
255
</simpara></listitem></varlistentry>
262
 
<varlistentry><term><parameter>b</parameter>&nbsp;:</term>
 
256
<varlistentry><term><parameter>b</parameter>&#160;:</term>
263
257
<listitem><simpara>a value to compare with.
264
258
</simpara></listitem></varlistentry>
265
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>a</parameter> = <parameter>b</parameter>; <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.
266
 
 
267
 
 
 
259
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if <parameter>a</parameter> = <parameter>b</parameter>; <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
268
260
</simpara></listitem></varlistentry>
269
261
</variablelist></refsect2>
270
 
<refsect2>
271
 
<title><anchor id="g-hash-table-insert" role="function"/>g_hash_table_insert ()</title>
272
 
<indexterm><primary>g_hash_table_insert</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_insert                 (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
262
<refsect2 id="g-hash-table-insert" role="function">
 
263
<title>g_hash_table_insert ()</title>
 
264
<indexterm zone="g-hash-table-insert"><primary sortas="g_hash_table_insert">g_hash_table_insert</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_insert                 (<link linkend="GHashTable">GHashTable</link> *hash_table,
273
265
                                                         <link linkend="gpointer">gpointer</link> key,
274
266
                                                         <link linkend="gpointer">gpointer</link> value);</programlisting>
275
267
<para>
282
274
a <parameter>key_destroy_func</parameter> when creating the <link linkend="GHashTable"><type>GHashTable</type></link>, the passed key is freed
283
275
using that function.</para>
284
276
<para>
285
 
 
286
277
</para><variablelist role="params">
287
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
278
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
288
279
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
289
280
</simpara></listitem></varlistentry>
290
 
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
281
<varlistentry><term><parameter>key</parameter>&#160;:</term>
291
282
<listitem><simpara> a key to insert.
292
283
</simpara></listitem></varlistentry>
293
 
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
284
<varlistentry><term><parameter>value</parameter>&#160;:</term>
294
285
<listitem><simpara> the value to associate with the key.
295
286
</simpara></listitem></varlistentry>
296
287
</variablelist></refsect2>
297
 
<refsect2>
298
 
<title><anchor id="g-hash-table-replace" role="function"/>g_hash_table_replace ()</title>
299
 
<indexterm><primary>g_hash_table_replace</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_replace                (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
288
<refsect2 id="g-hash-table-replace" role="function">
 
289
<title>g_hash_table_replace ()</title>
 
290
<indexterm zone="g-hash-table-replace"><primary sortas="g_hash_table_replace">g_hash_table_replace</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_replace                (<link linkend="GHashTable">GHashTable</link> *hash_table,
300
291
                                                         <link linkend="gpointer">gpointer</link> key,
301
292
                                                         <link linkend="gpointer">gpointer</link> value);</programlisting>
302
293
<para>
307
298
using that function. If you supplied a <parameter>key_destroy_func</parameter> when creating the
308
299
<link linkend="GHashTable"><type>GHashTable</type></link>, the old key is freed using that function.</para>
309
300
<para>
310
 
 
311
301
</para><variablelist role="params">
312
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
302
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
313
303
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
314
304
</simpara></listitem></varlistentry>
315
 
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
305
<varlistentry><term><parameter>key</parameter>&#160;:</term>
316
306
<listitem><simpara> a key to insert.
317
307
</simpara></listitem></varlistentry>
318
 
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
308
<varlistentry><term><parameter>value</parameter>&#160;:</term>
319
309
<listitem><simpara> the value to associate with the key.
320
310
</simpara></listitem></varlistentry>
321
311
</variablelist></refsect2>
322
 
<refsect2>
323
 
<title><anchor id="g-hash-table-size" role="function"/>g_hash_table_size ()</title>
324
 
<indexterm><primary>g_hash_table_size</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_hash_table_size                   (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
 
312
<refsect2 id="g-hash-table-size" role="function">
 
313
<title>g_hash_table_size ()</title>
 
314
<indexterm zone="g-hash-table-size"><primary sortas="g_hash_table_size">g_hash_table_size</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_hash_table_size                   (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
325
315
<para>
326
316
Returns the number of elements contained in the <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
327
317
<para>
328
 
 
329
318
</para><variablelist role="params">
330
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
319
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
331
320
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
332
321
</simpara></listitem></varlistentry>
333
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the number of key/value pairs in the <link linkend="GHashTable"><type>GHashTable</type></link>.
 
322
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of key/value pairs in the <link linkend="GHashTable"><type>GHashTable</type></link>.
334
323
</simpara></listitem></varlistentry>
335
324
</variablelist></refsect2>
336
 
<refsect2>
337
 
<title><anchor id="g-hash-table-lookup" role="function"/>g_hash_table_lookup ()</title>
338
 
<indexterm><primary>g_hash_table_lookup</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_hash_table_lookup                 (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
325
<refsect2 id="g-hash-table-lookup" role="function">
 
326
<title>g_hash_table_lookup ()</title>
 
327
<indexterm zone="g-hash-table-lookup"><primary sortas="g_hash_table_lookup">g_hash_table_lookup</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_hash_table_lookup                 (<link linkend="GHashTable">GHashTable</link> *hash_table,
339
328
                                                         <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
340
329
<para>
341
330
Looks up a key in a <link linkend="GHashTable"><type>GHashTable</type></link>. Note that this function cannot
342
331
distinguish between a key that is not present and one which is present
343
 
and has the value <link linkend="NULL:CAPS"><literal>NULL</literal></link>. If you need this distinction, use
 
332
and has the value <link linkend="NULL--CAPS"><literal>NULL</literal></link>. If you need this distinction, use
344
333
<link linkend="g-hash-table-lookup-extended"><function>g_hash_table_lookup_extended()</function></link>.</para>
345
334
<para>
346
 
 
347
335
</para><variablelist role="params">
348
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
336
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
349
337
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
350
338
</simpara></listitem></varlistentry>
351
 
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
339
<varlistentry><term><parameter>key</parameter>&#160;:</term>
352
340
<listitem><simpara> the key to look up.
353
341
</simpara></listitem></varlistentry>
354
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the associated value, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the key is not found.
 
342
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the associated value, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if the key is not found.
355
343
</simpara></listitem></varlistentry>
356
344
</variablelist></refsect2>
357
 
<refsect2>
358
 
<title><anchor id="g-hash-table-lookup-extended" role="function"/>g_hash_table_lookup_extended ()</title>
359
 
<indexterm><primary>g_hash_table_lookup_extended</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_hash_table_lookup_extended        (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
345
<refsect2 id="g-hash-table-lookup-extended" role="function">
 
346
<title>g_hash_table_lookup_extended ()</title>
 
347
<indexterm zone="g-hash-table-lookup-extended"><primary sortas="g_hash_table_lookup_extended">g_hash_table_lookup_extended</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_hash_table_lookup_extended        (<link linkend="GHashTable">GHashTable</link> *hash_table,
360
348
                                                         <link linkend="gconstpointer">gconstpointer</link> lookup_key,
361
349
                                                         <link linkend="gpointer">gpointer</link> *orig_key,
362
350
                                                         <link linkend="gpointer">gpointer</link> *value);</programlisting>
363
351
<para>
364
352
Looks up a key in the <link linkend="GHashTable"><type>GHashTable</type></link>, returning the original key and the
365
 
associated value and a <link linkend="gboolean"><type>gboolean</type></link> which is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the key was found. This
 
353
associated value and a <link linkend="gboolean"><type>gboolean</type></link> which is <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key was found. This
366
354
is useful if you need to free the memory allocated for the original key,
367
355
for example before calling <link linkend="g-hash-table-remove"><function>g_hash_table_remove()</function></link>.</para>
368
356
<para>
369
 
 
370
357
</para><variablelist role="params">
371
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
358
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
372
359
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
373
360
</simpara></listitem></varlistentry>
374
 
<varlistentry><term><parameter>lookup_key</parameter>&nbsp;:</term>
 
361
<varlistentry><term><parameter>lookup_key</parameter>&#160;:</term>
375
362
<listitem><simpara> the key to look up.
376
363
</simpara></listitem></varlistentry>
377
 
<varlistentry><term><parameter>orig_key</parameter>&nbsp;:</term>
 
364
<varlistentry><term><parameter>orig_key</parameter>&#160;:</term>
378
365
<listitem><simpara> returns the original key.
379
366
</simpara></listitem></varlistentry>
380
 
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
367
<varlistentry><term><parameter>value</parameter>&#160;:</term>
381
368
<listitem><simpara> returns the value associated with the key.
382
369
</simpara></listitem></varlistentry>
383
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the key was found in the <link linkend="GHashTable"><type>GHashTable</type></link>.
 
370
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key was found in the <link linkend="GHashTable"><type>GHashTable</type></link>.
384
371
</simpara></listitem></varlistentry>
385
372
</variablelist></refsect2>
386
 
<refsect2>
387
 
<title><anchor id="g-hash-table-foreach" role="function"/>g_hash_table_foreach ()</title>
388
 
<indexterm><primary>g_hash_table_foreach</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_foreach                (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
373
<refsect2 id="g-hash-table-foreach" role="function">
 
374
<title>g_hash_table_foreach ()</title>
 
375
<indexterm zone="g-hash-table-foreach"><primary sortas="g_hash_table_foreach">g_hash_table_foreach</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_foreach                (<link linkend="GHashTable">GHashTable</link> *hash_table,
389
376
                                                         <link linkend="GHFunc">GHFunc</link> func,
390
377
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
391
378
<para>
400
387
See <link linkend="g-hash-table-find"><function>g_hash_table_find()</function></link> for performance caveats for linear
401
388
order searches in contrast to <link linkend="g-hash-table-lookup"><function>g_hash_table_lookup()</function></link>.</para>
402
389
<para>
403
 
 
404
390
</para><variablelist role="params">
405
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
391
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
406
392
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
407
393
</simpara></listitem></varlistentry>
408
 
<varlistentry><term><parameter>func</parameter>&nbsp;:</term>
 
394
<varlistentry><term><parameter>func</parameter>&#160;:</term>
409
395
<listitem><simpara> the function to call for each key/value pair.
410
396
</simpara></listitem></varlistentry>
411
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
397
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
412
398
<listitem><simpara> user data to pass to the function.
413
399
</simpara></listitem></varlistentry>
414
400
</variablelist></refsect2>
415
 
<refsect2>
416
 
<title><anchor id="g-hash-table-find" role="function" condition="since:2.4"/>g_hash_table_find ()</title>
417
 
<indexterm role="2.4"><primary>g_hash_table_find</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_hash_table_find                   (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
401
<refsect2 id="g-hash-table-find" role="function" condition="since:2.4">
 
402
<title>g_hash_table_find ()</title>
 
403
<indexterm zone="g-hash-table-find" role="2.4"><primary sortas="g_hash_table_find">g_hash_table_find</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_hash_table_find                   (<link linkend="GHashTable">GHashTable</link> *hash_table,
418
404
                                                         <link linkend="GHRFunc">GHRFunc</link> predicate,
419
405
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
420
406
<para>
421
407
Calls the given function for key/value pairs in the <link linkend="GHashTable"><type>GHashTable</type></link> until
422
 
<parameter>predicate</parameter> returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>.  The function is passed the key and value of
 
408
<parameter>predicate</parameter> returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>.  The function is passed the key and value of
423
409
each pair, and the given <parameter>user_data</parameter> parameter. The hash table may not
424
410
be modified while iterating over it (you can't add/remove items).
425
411
</para>
433
419
operation issued for all n values in a hash table ends up needing O(n*n)
434
420
operations).</para>
435
421
<para>
436
 
 
437
422
</para><variablelist role="params">
438
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
423
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
439
424
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
440
425
</simpara></listitem></varlistentry>
441
 
<varlistentry><term><parameter>predicate</parameter>&nbsp;:</term>
 
426
<varlistentry><term><parameter>predicate</parameter>&#160;:</term>
442
427
<listitem><simpara>  function to test the key/value pairs for a certain property.
443
428
</simpara></listitem></varlistentry>
444
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
429
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
445
430
<listitem><simpara>  user data to pass to the function.
446
431
</simpara></listitem></varlistentry>
447
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The value of the first key/value pair is returned, for which
448
 
func evaluates to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>. If no pair with the requested property is found,
449
 
<link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned.
 
432
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> The value of the first key/value pair is returned, for which
 
433
func evaluates to <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>. If no pair with the requested property is found,
 
434
<link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.
450
435
 
451
436
</simpara></listitem></varlistentry>
452
 
</variablelist><para role="since">Since  2.4
453
 
</para></refsect2>
454
 
<refsect2>
455
 
<title><anchor id="GHFunc" role="function"/>GHFunc ()</title>
456
 
<indexterm><primary>GHFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GHFunc)                           (<link linkend="gpointer">gpointer</link> key,
 
437
</variablelist><para role="since">Since 2.4</para></refsect2>
 
438
<refsect2 id="GHFunc" role="function">
 
439
<title>GHFunc ()</title>
 
440
<indexterm zone="GHFunc"><primary sortas="GHFunc">GHFunc</primary></indexterm><programlisting><link linkend="void">void</link>                (*GHFunc)                           (<link linkend="gpointer">gpointer</link> key,
457
441
                                                         <link linkend="gpointer">gpointer</link> value,
458
442
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
459
443
<para>
461
445
It is called with each key/value pair, together with the <parameter>user_data</parameter> parameter
462
446
which is passed to <link linkend="g-hash-table-foreach"><function>g_hash_table_foreach()</function></link>.
463
447
</para><variablelist role="params">
464
 
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
448
<varlistentry><term><parameter>key</parameter>&#160;:</term>
465
449
<listitem><simpara>a key.
466
450
</simpara></listitem></varlistentry>
467
 
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
451
<varlistentry><term><parameter>value</parameter>&#160;:</term>
468
452
<listitem><simpara>the value corresponding to the key.
469
453
</simpara></listitem></varlistentry>
470
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
454
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
471
455
<listitem><simpara>user data passed to <link linkend="g-hash-table-foreach"><function>g_hash_table_foreach()</function></link>.
472
 
 
473
 
 
474
456
</simpara></listitem></varlistentry>
475
457
</variablelist></refsect2>
476
 
<refsect2>
477
 
<title><anchor id="g-hash-table-remove" role="function"/>g_hash_table_remove ()</title>
478
 
<indexterm><primary>g_hash_table_remove</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_hash_table_remove                 (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
458
<refsect2 id="g-hash-table-remove" role="function">
 
459
<title>g_hash_table_remove ()</title>
 
460
<indexterm zone="g-hash-table-remove"><primary sortas="g_hash_table_remove">g_hash_table_remove</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_hash_table_remove                 (<link linkend="GHashTable">GHashTable</link> *hash_table,
479
461
                                                         <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
480
462
<para>
481
463
Removes a key and its associated value from a <link linkend="GHashTable"><type>GHashTable</type></link>.
486
468
you have to make sure that any dynamically allocated values are freed
487
469
yourself.</para>
488
470
<para>
489
 
 
490
471
</para><variablelist role="params">
491
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
472
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
492
473
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
493
474
</simpara></listitem></varlistentry>
494
 
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
475
<varlistentry><term><parameter>key</parameter>&#160;:</term>
495
476
<listitem><simpara> the key to remove.
496
477
</simpara></listitem></varlistentry>
497
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the key was found and removed from the <link linkend="GHashTable"><type>GHashTable</type></link>.
 
478
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key was found and removed from the <link linkend="GHashTable"><type>GHashTable</type></link>.
498
479
</simpara></listitem></varlistentry>
499
480
</variablelist></refsect2>
500
 
<refsect2>
501
 
<title><anchor id="g-hash-table-steal" role="function"/>g_hash_table_steal ()</title>
502
 
<indexterm><primary>g_hash_table_steal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_hash_table_steal                  (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
481
<refsect2 id="g-hash-table-steal" role="function">
 
482
<title>g_hash_table_steal ()</title>
 
483
<indexterm zone="g-hash-table-steal"><primary sortas="g_hash_table_steal">g_hash_table_steal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_hash_table_steal                  (<link linkend="GHashTable">GHashTable</link> *hash_table,
503
484
                                                         <link linkend="gconstpointer">gconstpointer</link> key);</programlisting>
504
485
<para>
505
486
Removes a key and its associated value from a <link linkend="GHashTable"><type>GHashTable</type></link> without
506
487
calling the key and value destroy functions.</para>
507
488
<para>
508
 
 
509
489
</para><variablelist role="params">
510
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
490
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
511
491
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
512
492
</simpara></listitem></varlistentry>
513
 
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
493
<varlistentry><term><parameter>key</parameter>&#160;:</term>
514
494
<listitem><simpara> the key to remove.
515
495
</simpara></listitem></varlistentry>
516
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the key was found and removed from the <link linkend="GHashTable"><type>GHashTable</type></link>.
 
496
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key was found and removed from the <link linkend="GHashTable"><type>GHashTable</type></link>.
517
497
</simpara></listitem></varlistentry>
518
498
</variablelist></refsect2>
519
 
<refsect2>
520
 
<title><anchor id="g-hash-table-foreach-remove" role="function"/>g_hash_table_foreach_remove ()</title>
521
 
<indexterm><primary>g_hash_table_foreach_remove</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_hash_table_foreach_remove         (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
499
<refsect2 id="g-hash-table-foreach-remove" role="function">
 
500
<title>g_hash_table_foreach_remove ()</title>
 
501
<indexterm zone="g-hash-table-foreach-remove"><primary sortas="g_hash_table_foreach_remove">g_hash_table_foreach_remove</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_hash_table_foreach_remove         (<link linkend="GHashTable">GHashTable</link> *hash_table,
522
502
                                                         <link linkend="GHRFunc">GHRFunc</link> func,
523
503
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
524
504
<para>
525
505
Calls the given function for each key/value pair in the <link linkend="GHashTable"><type>GHashTable</type></link>.
526
 
If the function returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, then the key/value pair is removed from the
 
506
If the function returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, then the key/value pair is removed from the
527
507
<link linkend="GHashTable"><type>GHashTable</type></link>. If you supplied key or value destroy functions when creating
528
508
the <link linkend="GHashTable"><type>GHashTable</type></link>, they are used to free the memory allocated for the removed
529
509
keys and values.
530
510
</para>
531
511
<para>
532
 
See <link linkend="GHashTableIterator"><type>GHashTableIterator</type></link> for an alternative way to loop over the 
 
512
See <link linkend="GHashTableIter"><type>GHashTableIter</type></link> for an alternative way to loop over the 
533
513
key/value pairs in the hash table.</para>
534
514
<para>
535
 
 
536
515
</para><variablelist role="params">
537
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
516
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
538
517
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
539
518
</simpara></listitem></varlistentry>
540
 
<varlistentry><term><parameter>func</parameter>&nbsp;:</term>
 
519
<varlistentry><term><parameter>func</parameter>&#160;:</term>
541
520
<listitem><simpara> the function to call for each key/value pair.
542
521
</simpara></listitem></varlistentry>
543
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
522
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
544
523
<listitem><simpara> user data to pass to the function.
545
524
</simpara></listitem></varlistentry>
546
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the number of key/value pairs removed.
 
525
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of key/value pairs removed.
547
526
</simpara></listitem></varlistentry>
548
527
</variablelist></refsect2>
549
 
<refsect2>
550
 
<title><anchor id="g-hash-table-foreach-steal" role="function"/>g_hash_table_foreach_steal ()</title>
551
 
<indexterm><primary>g_hash_table_foreach_steal</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_hash_table_foreach_steal          (<link linkend="GHashTable">GHashTable</link> *hash_table,
 
528
<refsect2 id="g-hash-table-foreach-steal" role="function">
 
529
<title>g_hash_table_foreach_steal ()</title>
 
530
<indexterm zone="g-hash-table-foreach-steal"><primary sortas="g_hash_table_foreach_steal">g_hash_table_foreach_steal</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_hash_table_foreach_steal          (<link linkend="GHashTable">GHashTable</link> *hash_table,
552
531
                                                         <link linkend="GHRFunc">GHRFunc</link> func,
553
532
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
554
533
<para>
555
534
Calls the given function for each key/value pair in the <link linkend="GHashTable"><type>GHashTable</type></link>.
556
 
If the function returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, then the key/value pair is removed from the
 
535
If the function returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, then the key/value pair is removed from the
557
536
<link linkend="GHashTable"><type>GHashTable</type></link>, but no key or value destroy functions are called.
558
537
</para>
559
538
<para>
560
 
See <link linkend="GHashTableIterator"><type>GHashTableIterator</type></link> for an alternative way to loop over the 
 
539
See <link linkend="GHashTableIter"><type>GHashTableIter</type></link> for an alternative way to loop over the 
561
540
key/value pairs in the hash table.</para>
562
541
<para>
563
 
 
564
542
</para><variablelist role="params">
565
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
543
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
566
544
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
567
545
</simpara></listitem></varlistentry>
568
 
<varlistentry><term><parameter>func</parameter>&nbsp;:</term>
 
546
<varlistentry><term><parameter>func</parameter>&#160;:</term>
569
547
<listitem><simpara> the function to call for each key/value pair.
570
548
</simpara></listitem></varlistentry>
571
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
549
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
572
550
<listitem><simpara> user data to pass to the function.
573
551
</simpara></listitem></varlistentry>
574
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the number of key/value pairs removed.
 
552
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the number of key/value pairs removed.
575
553
</simpara></listitem></varlistentry>
576
554
</variablelist></refsect2>
577
 
<refsect2>
578
 
<title><anchor id="g-hash-table-remove-all" role="function" condition="since:2.12"/>g_hash_table_remove_all ()</title>
579
 
<indexterm role="2.12"><primary>g_hash_table_remove_all</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_remove_all             (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
 
555
<refsect2 id="g-hash-table-remove-all" role="function" condition="since:2.12">
 
556
<title>g_hash_table_remove_all ()</title>
 
557
<indexterm zone="g-hash-table-remove-all" role="2.12"><primary sortas="g_hash_table_remove_all">g_hash_table_remove_all</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_remove_all             (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
580
558
<para>
581
559
Removes all keys and their associated values from a <link linkend="GHashTable"><type>GHashTable</type></link>.
582
560
</para>
586
564
have to make sure that any dynamically allocated values are freed
587
565
yourself.</para>
588
566
<para>
589
 
 
590
567
</para><variablelist role="params">
591
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
568
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
592
569
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>
593
570
</simpara></listitem></varlistentry>
594
 
</variablelist><para role="since">Since  2.12
595
 
</para></refsect2>
596
 
<refsect2>
597
 
<title><anchor id="g-hash-table-steal-all" role="function" condition="since:2.12"/>g_hash_table_steal_all ()</title>
598
 
<indexterm role="2.12"><primary>g_hash_table_steal_all</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_steal_all              (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
 
571
</variablelist><para role="since">Since 2.12</para></refsect2>
 
572
<refsect2 id="g-hash-table-steal-all" role="function" condition="since:2.12">
 
573
<title>g_hash_table_steal_all ()</title>
 
574
<indexterm zone="g-hash-table-steal-all" role="2.12"><primary sortas="g_hash_table_steal_all">g_hash_table_steal_all</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_steal_all              (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
599
575
<para>
600
576
Removes all keys and their associated values from a <link linkend="GHashTable"><type>GHashTable</type></link>
601
577
without calling the key and value destroy functions.</para>
602
578
<para>
603
 
 
604
579
</para><variablelist role="params">
605
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
580
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
606
581
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
607
582
</simpara></listitem></varlistentry>
608
 
</variablelist><para role="since">Since  2.12
609
 
</para></refsect2>
610
 
<refsect2>
611
 
<title><anchor id="g-hash-table-get-keys" role="function" condition="since:2.14"/>g_hash_table_get_keys ()</title>
612
 
<indexterm role="2.14"><primary>g_hash_table_get_keys</primary></indexterm><programlisting><link linkend="GList">GList</link>*              g_hash_table_get_keys               (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
 
583
</variablelist><para role="since">Since 2.12</para></refsect2>
 
584
<refsect2 id="g-hash-table-get-keys" role="function" condition="since:2.14">
 
585
<title>g_hash_table_get_keys ()</title>
 
586
<indexterm zone="g-hash-table-get-keys" role="2.14"><primary sortas="g_hash_table_get_keys">g_hash_table_get_keys</primary></indexterm><programlisting><link linkend="GList">GList</link> *             g_hash_table_get_keys               (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
613
587
<para>
614
588
Retrieves every key inside <parameter>hash_table</parameter>. The returned data is valid
615
589
until <parameter>hash_table</parameter> is modified.</para>
616
590
<para>
617
 
 
618
591
</para><variablelist role="params">
619
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
592
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
620
593
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>
621
594
</simpara></listitem></varlistentry>
622
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a <link linkend="GList"><type>GList</type></link> containing all the keys inside the hash
 
595
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GList"><type>GList</type></link> containing all the keys inside the hash
623
596
  table. The content of the list is owned by the hash table and
624
597
  should not be modified or freed. Use <link linkend="g-list-free"><function>g_list_free()</function></link> when done
625
598
  using the list.
626
599
 
627
600
</simpara></listitem></varlistentry>
628
 
</variablelist><para role="since">Since  2.14
629
 
</para></refsect2>
630
 
<refsect2>
631
 
<title><anchor id="g-hash-table-get-values" role="function" condition="since:2.14"/>g_hash_table_get_values ()</title>
632
 
<indexterm role="2.14"><primary>g_hash_table_get_values</primary></indexterm><programlisting><link linkend="GList">GList</link>*              g_hash_table_get_values             (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
 
601
</variablelist><para role="since">Since 2.14</para></refsect2>
 
602
<refsect2 id="g-hash-table-get-values" role="function" condition="since:2.14">
 
603
<title>g_hash_table_get_values ()</title>
 
604
<indexterm zone="g-hash-table-get-values" role="2.14"><primary sortas="g_hash_table_get_values">g_hash_table_get_values</primary></indexterm><programlisting><link linkend="GList">GList</link> *             g_hash_table_get_values             (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
633
605
<para>
634
606
Retrieves every value inside <parameter>hash_table</parameter>. The returned data is
635
607
valid until <parameter>hash_table</parameter> is modified.</para>
636
608
<para>
637
 
 
638
609
</para><variablelist role="params">
639
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
610
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
640
611
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>
641
612
</simpara></listitem></varlistentry>
642
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a <link linkend="GList"><type>GList</type></link> containing all the values inside the hash
 
613
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="GList"><type>GList</type></link> containing all the values inside the hash
643
614
  table. The content of the list is owned by the hash table and
644
615
  should not be modified or freed. Use <link linkend="g-list-free"><function>g_list_free()</function></link> when done
645
616
  using the list.
646
617
 
647
618
</simpara></listitem></varlistentry>
648
 
</variablelist><para role="since">Since  2.14
649
 
</para></refsect2>
650
 
<refsect2>
651
 
<title><anchor id="GHRFunc" role="function"/>GHRFunc ()</title>
652
 
<indexterm><primary>GHRFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GHRFunc)                          (<link linkend="gpointer">gpointer</link> key,
 
619
</variablelist><para role="since">Since 2.14</para></refsect2>
 
620
<refsect2 id="GHRFunc" role="function">
 
621
<title>GHRFunc ()</title>
 
622
<indexterm zone="GHRFunc"><primary sortas="GHRFunc">GHRFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            (*GHRFunc)                          (<link linkend="gpointer">gpointer</link> key,
653
623
                                                         <link linkend="gpointer">gpointer</link> value,
654
624
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
655
625
<para>
656
626
Specifies the type of the function passed to <link linkend="g-hash-table-foreach-remove"><function>g_hash_table_foreach_remove()</function></link>.
657
627
It is called with each key/value pair, together with the <parameter>user_data</parameter> parameter
658
628
passed to <link linkend="g-hash-table-foreach-remove"><function>g_hash_table_foreach_remove()</function></link>.
659
 
It should return <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the key/value pair should be removed from the
 
629
It should return <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the key/value pair should be removed from the
660
630
<link linkend="GHashTable"><type>GHashTable</type></link>.
661
631
</para><variablelist role="params">
662
 
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
 
632
<varlistentry><term><parameter>key</parameter>&#160;:</term>
663
633
<listitem><simpara>a key.
664
634
</simpara></listitem></varlistentry>
665
 
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
 
635
<varlistentry><term><parameter>value</parameter>&#160;:</term>
666
636
<listitem><simpara>the value associated with the key.
667
637
</simpara></listitem></varlistentry>
668
 
<varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 
638
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
669
639
<listitem><simpara>user data passed to <link linkend="g-hash-table-remove"><function>g_hash_table_remove()</function></link>.
670
640
</simpara></listitem></varlistentry>
671
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the key/value pair should be removed from the <link linkend="GHashTable"><type>GHashTable</type></link>.
672
 
 
673
 
 
 
641
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE if the key/value pair should be removed from the <link linkend="GHashTable"><type>GHashTable</type></link>.
674
642
</simpara></listitem></varlistentry>
675
643
</variablelist></refsect2>
676
 
<refsect2>
677
 
<title><anchor id="g-hash-table-freeze" role="macro" condition="deprecated:"/>g_hash_table_freeze()</title>
678
 
<indexterm role="deprecated"><primary>g_hash_table_freeze</primary></indexterm><programlisting>#define             g_hash_table_freeze(hash_table)</programlisting>
 
644
<refsect2 id="g-hash-table-freeze" role="macro" condition="deprecated:">
 
645
<title>g_hash_table_freeze()</title>
 
646
<indexterm zone="g-hash-table-freeze" role="deprecated"><primary sortas="g_hash_table_freeze">g_hash_table_freeze</primary></indexterm><programlisting>#define             g_hash_table_freeze(hash_table)</programlisting>
679
647
<warning><para><literal>g_hash_table_freeze</literal> is deprecated and should not be used in newly-written code.</para></warning>
680
648
<para>
681
649
This function is deprecated and will be removed in the next major
682
650
 release of GLib. It does nothing.
683
651
</para><variablelist role="params">
684
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
652
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
685
653
<listitem><simpara>a <link linkend="GHashTable"><type>GHashTable</type></link>
686
 
 
687
 
 
688
654
</simpara></listitem></varlistentry>
689
655
</variablelist></refsect2>
690
 
<refsect2>
691
 
<title><anchor id="g-hash-table-thaw" role="macro" condition="deprecated:"/>g_hash_table_thaw()</title>
692
 
<indexterm role="deprecated"><primary>g_hash_table_thaw</primary></indexterm><programlisting>#define             g_hash_table_thaw(hash_table)</programlisting>
 
656
<refsect2 id="g-hash-table-thaw" role="macro" condition="deprecated:">
 
657
<title>g_hash_table_thaw()</title>
 
658
<indexterm zone="g-hash-table-thaw" role="deprecated"><primary sortas="g_hash_table_thaw">g_hash_table_thaw</primary></indexterm><programlisting>#define             g_hash_table_thaw(hash_table)</programlisting>
693
659
<warning><para><literal>g_hash_table_thaw</literal> is deprecated and should not be used in newly-written code.</para></warning>
694
660
<para>
695
661
This function is deprecated and will be removed in the next major
696
662
 release of GLib. It does nothing.
697
663
</para><variablelist role="params">
698
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
664
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
699
665
<listitem><simpara>a <link linkend="GHashTable"><type>GHashTable</type></link>
700
 
 
701
 
 
702
666
</simpara></listitem></varlistentry>
703
667
</variablelist></refsect2>
704
 
<refsect2>
705
 
<title><anchor id="g-hash-table-destroy" role="function"/>g_hash_table_destroy ()</title>
706
 
<indexterm><primary>g_hash_table_destroy</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_destroy                (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
 
668
<refsect2 id="g-hash-table-destroy" role="function">
 
669
<title>g_hash_table_destroy ()</title>
 
670
<indexterm zone="g-hash-table-destroy"><primary sortas="g_hash_table_destroy">g_hash_table_destroy</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_destroy                (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
707
671
<para>
708
672
Destroys all keys and values in the <link linkend="GHashTable"><type>GHashTable</type></link> and decrements its
709
673
reference count by 1. If keys and/or values are dynamically allocated,
712
676
functions you supplied will be called on all keys and values during the
713
677
destruction phase.</para>
714
678
<para>
715
 
 
716
679
</para><variablelist role="params">
717
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
680
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
718
681
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
719
682
</simpara></listitem></varlistentry>
720
683
</variablelist></refsect2>
721
 
<refsect2>
722
 
<title><anchor id="g-hash-table-ref" role="function" condition="since:2.10"/>g_hash_table_ref ()</title>
723
 
<indexterm role="2.10"><primary>g_hash_table_ref</primary></indexterm><programlisting><link linkend="GHashTable">GHashTable</link>*         g_hash_table_ref                    (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
 
684
<refsect2 id="g-hash-table-ref" role="function" condition="since:2.10">
 
685
<title>g_hash_table_ref ()</title>
 
686
<indexterm zone="g-hash-table-ref" role="2.10"><primary sortas="g_hash_table_ref">g_hash_table_ref</primary></indexterm><programlisting><link linkend="GHashTable">GHashTable</link>*         g_hash_table_ref                    (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
724
687
<para>
725
688
Atomically increments the reference count of <parameter>hash_table</parameter> by one.
726
689
This function is MT-safe and may be called from any thread.</para>
727
690
<para>
728
 
 
729
691
</para><variablelist role="params">
730
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
692
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
731
693
<listitem><simpara> a valid <link linkend="GHashTable"><type>GHashTable</type></link>.
732
694
</simpara></listitem></varlistentry>
733
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the passed in <link linkend="GHashTable"><type>GHashTable</type></link>.
 
695
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the passed in <link linkend="GHashTable"><type>GHashTable</type></link>.
734
696
 
735
697
</simpara></listitem></varlistentry>
736
 
</variablelist><para role="since">Since  2.10
737
 
</para></refsect2>
738
 
<refsect2>
739
 
<title><anchor id="g-hash-table-unref" role="function" condition="since:2.10"/>g_hash_table_unref ()</title>
740
 
<indexterm role="2.10"><primary>g_hash_table_unref</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_unref                  (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
 
698
</variablelist><para role="since">Since 2.10</para></refsect2>
 
699
<refsect2 id="g-hash-table-unref" role="function" condition="since:2.10">
 
700
<title>g_hash_table_unref ()</title>
 
701
<indexterm zone="g-hash-table-unref" role="2.10"><primary sortas="g_hash_table_unref">g_hash_table_unref</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_unref                  (<link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
741
702
<para>
742
703
Atomically decrements the reference count of <parameter>hash_table</parameter> by one.
743
704
If the reference count drops to 0, all keys and values will be
744
705
destroyed, and all memory allocated by the hash table is released.
745
706
This function is MT-safe and may be called from any thread.</para>
746
707
<para>
747
 
 
748
708
</para><variablelist role="params">
749
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
709
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
750
710
<listitem><simpara> a valid <link linkend="GHashTable"><type>GHashTable</type></link>.
751
711
</simpara></listitem></varlistentry>
752
 
</variablelist><para role="since">Since  2.10
753
 
</para></refsect2>
754
 
<refsect2>
755
 
<title><anchor id="GHashTableIter" role="struct"/>GHashTableIter</title>
756
 
<indexterm><primary>GHashTableIter</primary></indexterm><programlisting>typedef struct {
 
712
</variablelist><para role="since">Since 2.10</para></refsect2>
 
713
<refsect2 id="GHashTableIter" role="struct">
 
714
<title>GHashTableIter</title>
 
715
<indexterm zone="GHashTableIter"><primary sortas="GHashTableIter">GHashTableIter</primary></indexterm><programlisting>typedef struct {
757
716
} GHashTableIter;
758
717
</programlisting>
759
718
<para>
760
 
 
 
719
A GHashTableIter structure represents an iterator that can be
 
720
used to iterate over the elements of a <link linkend="GHashTable"><type>GHashTable</type></link>. GHashTableIter
 
721
structures are typically allocated on the stack and then initialized
 
722
with <link linkend="g-hash-table-iter-init"><function>g_hash_table_iter_init()</function></link>.
761
723
</para></refsect2>
762
 
<refsect2>
763
 
<title><anchor id="g-hash-table-iter-init" role="function" condition="since:2.16"/>g_hash_table_iter_init ()</title>
764
 
<indexterm role="2.16"><primary>g_hash_table_iter_init</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_iter_init              (<link linkend="GHashTableIter">GHashTableIter</link> *iter,
 
724
<refsect2 id="g-hash-table-iter-init" role="function" condition="since:2.16">
 
725
<title>g_hash_table_iter_init ()</title>
 
726
<indexterm zone="g-hash-table-iter-init" role="2.16"><primary sortas="g_hash_table_iter_init">g_hash_table_iter_init</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_iter_init              (<link linkend="GHashTableIter">GHashTableIter</link> *iter,
765
727
                                                         <link linkend="GHashTable">GHashTable</link> *hash_table);</programlisting>
766
728
<para>
767
729
Initializes a key/value pair iterator and associates it with
778
740
  }
779
741
</programlisting></informalexample></para>
780
742
<para>
781
 
 
782
743
</para><variablelist role="params">
783
 
<varlistentry><term><parameter>iter</parameter>&nbsp;:</term>
 
744
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
784
745
<listitem><simpara> an uninitialized <link linkend="GHashTableIter"><type>GHashTableIter</type></link>.
785
746
</simpara></listitem></varlistentry>
786
 
<varlistentry><term><parameter>hash_table</parameter>&nbsp;:</term>
 
747
<varlistentry><term><parameter>hash_table</parameter>&#160;:</term>
787
748
<listitem><simpara> a <link linkend="GHashTable"><type>GHashTable</type></link>.
788
749
</simpara></listitem></varlistentry>
789
 
</variablelist><para role="since">Since  2.16
790
 
</para></refsect2>
791
 
<refsect2>
792
 
<title><anchor id="g-hash-table-iter-next" role="function" condition="since:2.16"/>g_hash_table_iter_next ()</title>
793
 
<indexterm role="2.16"><primary>g_hash_table_iter_next</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_hash_table_iter_next              (<link linkend="GHashTableIter">GHashTableIter</link> *iter,
 
750
</variablelist><para role="since">Since 2.16</para></refsect2>
 
751
<refsect2 id="g-hash-table-iter-next" role="function" condition="since:2.16">
 
752
<title>g_hash_table_iter_next ()</title>
 
753
<indexterm zone="g-hash-table-iter-next" role="2.16"><primary sortas="g_hash_table_iter_next">g_hash_table_iter_next</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_hash_table_iter_next              (<link linkend="GHashTableIter">GHashTableIter</link> *iter,
794
754
                                                         <link linkend="gpointer">gpointer</link> *key,
795
755
                                                         <link linkend="gpointer">gpointer</link> *value);</programlisting>
796
756
<para>
797
757
Advances <parameter>iter</parameter> and retrieves the key and/or value that are now
798
 
pointed to as a result of this advancement. If <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> is returned,
 
758
pointed to as a result of this advancement. If <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> is returned,
799
759
<parameter>key</parameter> and <parameter>value</parameter> are not set, and the iterator becomes invalid.</para>
800
760
<para>
801
 
 
802
761
</para><variablelist role="params">
803
 
<varlistentry><term><parameter>iter</parameter>&nbsp;:</term>
 
762
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
804
763
<listitem><simpara> an initialized <link linkend="GHashTableIter"><type>GHashTableIter</type></link>.
805
764
</simpara></listitem></varlistentry>
806
 
<varlistentry><term><parameter>key</parameter>&nbsp;:</term>
807
 
<listitem><simpara> a location to store the key, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
808
 
</simpara></listitem></varlistentry>
809
 
<varlistentry><term><parameter>value</parameter>&nbsp;:</term>
810
 
<listitem><simpara> a location to store the value, or <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
811
 
</simpara></listitem></varlistentry>
812
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if the end of the <link linkend="GHashTable"><type>GHashTable</type></link> has been reached.
 
765
<varlistentry><term><parameter>key</parameter>&#160;:</term>
 
766
<listitem><simpara> a location to store the key, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 
767
</simpara></listitem></varlistentry>
 
768
<varlistentry><term><parameter>value</parameter>&#160;:</term>
 
769
<listitem><simpara> a location to store the value, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
 
770
</simpara></listitem></varlistentry>
 
771
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> if the end of the <link linkend="GHashTable"><type>GHashTable</type></link> has been reached.
813
772
 
814
773
</simpara></listitem></varlistentry>
815
 
</variablelist><para role="since">Since  2.16
816
 
</para></refsect2>
817
 
<refsect2>
818
 
<title><anchor id="g-hash-table-iter-get-hash-table" role="function" condition="since:2.16"/>g_hash_table_iter_get_hash_table ()</title>
819
 
<indexterm role="2.16"><primary>g_hash_table_iter_get_hash_table</primary></indexterm><programlisting><link linkend="GHashTable">GHashTable</link>*         g_hash_table_iter_get_hash_table    (<link linkend="GHashTableIter">GHashTableIter</link> *iter);</programlisting>
 
774
</variablelist><para role="since">Since 2.16</para></refsect2>
 
775
<refsect2 id="g-hash-table-iter-get-hash-table" role="function" condition="since:2.16">
 
776
<title>g_hash_table_iter_get_hash_table ()</title>
 
777
<indexterm zone="g-hash-table-iter-get-hash-table" role="2.16"><primary sortas="g_hash_table_iter_get_hash_table">g_hash_table_iter_get_hash_table</primary></indexterm><programlisting><link linkend="GHashTable">GHashTable</link>*         g_hash_table_iter_get_hash_table    (<link linkend="GHashTableIter">GHashTableIter</link> *iter);</programlisting>
820
778
<para>
821
779
Returns the <link linkend="GHashTable"><type>GHashTable</type></link> associated with <parameter>iter</parameter>.</para>
822
780
<para>
823
 
 
824
781
</para><variablelist role="params">
825
 
<varlistentry><term><parameter>iter</parameter>&nbsp;:</term>
 
782
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
826
783
<listitem><simpara> an initialized <link linkend="GHashTableIter"><type>GHashTableIter</type></link>.
827
784
</simpara></listitem></varlistentry>
828
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> the <link linkend="GHashTable"><type>GHashTable</type></link> associated with <parameter>iter</parameter>.
 
785
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GHashTable"><type>GHashTable</type></link> associated with <parameter>iter</parameter>.
829
786
 
830
787
</simpara></listitem></varlistentry>
831
 
</variablelist><para role="since">Since  2.16
832
 
</para></refsect2>
833
 
<refsect2>
834
 
<title><anchor id="g-hash-table-iter-remove" role="function" condition="since:2.16"/>g_hash_table_iter_remove ()</title>
835
 
<indexterm role="2.16"><primary>g_hash_table_iter_remove</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_iter_remove            (<link linkend="GHashTableIter">GHashTableIter</link> *iter);</programlisting>
 
788
</variablelist><para role="since">Since 2.16</para></refsect2>
 
789
<refsect2 id="g-hash-table-iter-remove" role="function" condition="since:2.16">
 
790
<title>g_hash_table_iter_remove ()</title>
 
791
<indexterm zone="g-hash-table-iter-remove" role="2.16"><primary sortas="g_hash_table_iter_remove">g_hash_table_iter_remove</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_iter_remove            (<link linkend="GHashTableIter">GHashTableIter</link> *iter);</programlisting>
836
792
<para>
837
793
Removes the key/value pair currently pointed to by the iterator
838
794
from its associated <link linkend="GHashTable"><type>GHashTable</type></link>. Can only be called after
839
 
<link linkend="g-hash-table-iter-next"><function>g_hash_table_iter_next()</function></link> returned <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, and cannot be called more
 
795
<link linkend="g-hash-table-iter-next"><function>g_hash_table_iter_next()</function></link> returned <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, and cannot be called more
840
796
than once for the same key/value pair.
841
797
</para>
842
798
<para>
845
801
you have to make sure that any dynamically allocated values are freed 
846
802
yourself.</para>
847
803
<para>
848
 
 
849
804
</para><variablelist role="params">
850
 
<varlistentry><term><parameter>iter</parameter>&nbsp;:</term>
 
805
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
851
806
<listitem><simpara> an initialized <link linkend="GHashTableIter"><type>GHashTableIter</type></link>.
852
807
</simpara></listitem></varlistentry>
853
 
</variablelist><para role="since">Since  2.16
854
 
</para></refsect2>
855
 
<refsect2>
856
 
<title><anchor id="g-hash-table-iter-steal" role="function" condition="since:2.16"/>g_hash_table_iter_steal ()</title>
857
 
<indexterm role="2.16"><primary>g_hash_table_iter_steal</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_iter_steal             (<link linkend="GHashTableIter">GHashTableIter</link> *iter);</programlisting>
 
808
</variablelist><para role="since">Since 2.16</para></refsect2>
 
809
<refsect2 id="g-hash-table-iter-steal" role="function" condition="since:2.16">
 
810
<title>g_hash_table_iter_steal ()</title>
 
811
<indexterm zone="g-hash-table-iter-steal" role="2.16"><primary sortas="g_hash_table_iter_steal">g_hash_table_iter_steal</primary></indexterm><programlisting><link linkend="void">void</link>                g_hash_table_iter_steal             (<link linkend="GHashTableIter">GHashTableIter</link> *iter);</programlisting>
858
812
<para>
859
813
Removes the key/value pair currently pointed to by the iterator
860
814
from its associated <link linkend="GHashTable"><type>GHashTable</type></link>, without calling the key and value
861
815
destroy functions. Can only be called after
862
 
<link linkend="g-hash-table-iter-next"><function>g_hash_table_iter_next()</function></link> returned <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, and cannot be called more
 
816
<link linkend="g-hash-table-iter-next"><function>g_hash_table_iter_next()</function></link> returned <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, and cannot be called more
863
817
than once for the same key/value pair.</para>
864
818
<para>
865
 
 
866
819
</para><variablelist role="params">
867
 
<varlistentry><term><parameter>iter</parameter>&nbsp;:</term>
 
820
<varlistentry><term><parameter>iter</parameter>&#160;:</term>
868
821
<listitem><simpara> an initialized <link linkend="GHashTableIter"><type>GHashTableIter</type></link>.
869
822
</simpara></listitem></varlistentry>
870
 
</variablelist><para role="since">Since  2.16
871
 
</para></refsect2>
872
 
<refsect2>
873
 
<title><anchor id="g-direct-equal" role="function"/>g_direct_equal ()</title>
874
 
<indexterm><primary>g_direct_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_direct_equal                      (<link linkend="gconstpointer">gconstpointer</link> v1,
 
823
</variablelist><para role="since">Since 2.16</para></refsect2>
 
824
<refsect2 id="g-direct-equal" role="function">
 
825
<title>g_direct_equal ()</title>
 
826
<indexterm zone="g-direct-equal"><primary sortas="g_direct_equal">g_direct_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_direct_equal                      (<link linkend="gconstpointer">gconstpointer</link> v1,
875
827
                                                         <link linkend="gconstpointer">gconstpointer</link> v2);</programlisting>
876
828
<para>
877
 
Compares two <link linkend="gpointer"><type>gpointer</type></link> arguments and returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if they are equal.
 
829
Compares two <link linkend="gpointer"><type>gpointer</type></link> arguments and returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if they are equal.
878
830
It can be passed to <link linkend="g-hash-table-new"><function>g_hash_table_new()</function></link> as the <parameter>key_equal_func</parameter>
879
831
parameter, when using pointers as keys in a <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
880
832
<para>
881
 
 
882
833
</para><variablelist role="params">
883
 
<varlistentry><term><parameter>v1</parameter>&nbsp;:</term>
 
834
<varlistentry><term><parameter>v1</parameter>&#160;:</term>
884
835
<listitem><simpara> a key.
885
836
</simpara></listitem></varlistentry>
886
 
<varlistentry><term><parameter>v2</parameter>&nbsp;:</term>
 
837
<varlistentry><term><parameter>v2</parameter>&#160;:</term>
887
838
<listitem><simpara> a key to compare with <parameter>v1</parameter>.
888
839
</simpara></listitem></varlistentry>
889
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the two keys match.
 
840
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the two keys match.
890
841
</simpara></listitem></varlistentry>
891
842
</variablelist></refsect2>
892
 
<refsect2>
893
 
<title><anchor id="g-direct-hash" role="function"/>g_direct_hash ()</title>
894
 
<indexterm><primary>g_direct_hash</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_direct_hash                       (<link linkend="gconstpointer">gconstpointer</link> v);</programlisting>
 
843
<refsect2 id="g-direct-hash" role="function">
 
844
<title>g_direct_hash ()</title>
 
845
<indexterm zone="g-direct-hash"><primary sortas="g_direct_hash">g_direct_hash</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_direct_hash                       (<link linkend="gconstpointer">gconstpointer</link> v);</programlisting>
895
846
<para>
896
847
Converts a gpointer to a hash value.
897
848
It can be passed to <link linkend="g-hash-table-new"><function>g_hash_table_new()</function></link> as the <parameter>hash_func</parameter> parameter, 
898
849
when using pointers as keys in a <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
899
850
<para>
900
 
 
901
851
</para><variablelist role="params">
902
 
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
 
852
<varlistentry><term><parameter>v</parameter>&#160;:</term>
903
853
<listitem><simpara> a <link linkend="gpointer"><type>gpointer</type></link> key
904
854
</simpara></listitem></varlistentry>
905
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a hash value corresponding to the key.
 
855
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a hash value corresponding to the key.
906
856
</simpara></listitem></varlistentry>
907
857
</variablelist></refsect2>
908
 
<refsect2>
909
 
<title><anchor id="g-int-equal" role="function"/>g_int_equal ()</title>
910
 
<indexterm><primary>g_int_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_int_equal                         (<link linkend="gconstpointer">gconstpointer</link> v1,
 
858
<refsect2 id="g-int-equal" role="function">
 
859
<title>g_int_equal ()</title>
 
860
<indexterm zone="g-int-equal"><primary sortas="g_int_equal">g_int_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_int_equal                         (<link linkend="gconstpointer">gconstpointer</link> v1,
911
861
                                                         <link linkend="gconstpointer">gconstpointer</link> v2);</programlisting>
912
862
<para>
913
863
Compares the two <link linkend="gint"><type>gint</type></link> values being pointed to and returns 
914
 
<link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if they are equal.
 
864
<link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if they are equal.
915
865
It can be passed to <link linkend="g-hash-table-new"><function>g_hash_table_new()</function></link> as the <parameter>key_equal_func</parameter>
916
866
parameter, when using pointers to integers as keys in a <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
917
867
<para>
918
 
 
919
868
</para><variablelist role="params">
920
 
<varlistentry><term><parameter>v1</parameter>&nbsp;:</term>
 
869
<varlistentry><term><parameter>v1</parameter>&#160;:</term>
921
870
<listitem><simpara> a pointer to a <link linkend="gint"><type>gint</type></link> key.
922
871
</simpara></listitem></varlistentry>
923
 
<varlistentry><term><parameter>v2</parameter>&nbsp;:</term>
 
872
<varlistentry><term><parameter>v2</parameter>&#160;:</term>
924
873
<listitem><simpara> a pointer to a <link linkend="gint"><type>gint</type></link> key to compare with <parameter>v1</parameter>.
925
874
</simpara></listitem></varlistentry>
926
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the two keys match.
 
875
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the two keys match.
927
876
</simpara></listitem></varlistentry>
928
877
</variablelist></refsect2>
929
 
<refsect2>
930
 
<title><anchor id="g-int-hash" role="function"/>g_int_hash ()</title>
931
 
<indexterm><primary>g_int_hash</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_int_hash                          (<link linkend="gconstpointer">gconstpointer</link> v);</programlisting>
 
878
<refsect2 id="g-int-hash" role="function">
 
879
<title>g_int_hash ()</title>
 
880
<indexterm zone="g-int-hash"><primary sortas="g_int_hash">g_int_hash</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_int_hash                          (<link linkend="gconstpointer">gconstpointer</link> v);</programlisting>
932
881
<para>
933
882
Converts a pointer to a <link linkend="gint"><type>gint</type></link> to a hash value.
934
883
It can be passed to <link linkend="g-hash-table-new"><function>g_hash_table_new()</function></link> as the <parameter>hash_func</parameter> parameter, 
935
884
when using pointers to integers values as keys in a <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
936
885
<para>
937
 
 
938
886
</para><variablelist role="params">
939
 
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
 
887
<varlistentry><term><parameter>v</parameter>&#160;:</term>
940
888
<listitem><simpara> a pointer to a <link linkend="gint"><type>gint</type></link> key
941
889
</simpara></listitem></varlistentry>
942
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a hash value corresponding to the key.
 
890
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a hash value corresponding to the key.
943
891
</simpara></listitem></varlistentry>
944
892
</variablelist></refsect2>
945
 
<refsect2>
946
 
<title><anchor id="g-str-equal" role="function"/>g_str_equal ()</title>
947
 
<indexterm><primary>g_str_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_str_equal                         (<link linkend="gconstpointer">gconstpointer</link> v1,
 
893
<refsect2 id="g-str-equal" role="function">
 
894
<title>g_str_equal ()</title>
 
895
<indexterm zone="g-str-equal"><primary sortas="g_str_equal">g_str_equal</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            g_str_equal                         (<link linkend="gconstpointer">gconstpointer</link> v1,
948
896
                                                         <link linkend="gconstpointer">gconstpointer</link> v2);</programlisting>
949
897
<para>
950
 
Compares two strings for byte-by-byte equality and returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> 
 
898
Compares two strings for byte-by-byte equality and returns <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> 
951
899
if they are equal. It can be passed to <link linkend="g-hash-table-new"><function>g_hash_table_new()</function></link> as the 
952
900
<parameter>key_equal_func</parameter> parameter, when using strings as keys in a <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
953
901
<para>
954
902
</para><variablelist role="params">
955
 
<varlistentry><term><parameter>v1</parameter>&nbsp;:</term>
 
903
<varlistentry><term><parameter>v1</parameter>&#160;:</term>
956
904
<listitem><simpara> a key
957
905
</simpara></listitem></varlistentry>
958
 
<varlistentry><term><parameter>v2</parameter>&nbsp;:</term>
 
906
<varlistentry><term><parameter>v2</parameter>&#160;:</term>
959
907
<listitem><simpara> a key to compare with <parameter>v1</parameter>
960
908
</simpara></listitem></varlistentry>
961
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the two keys match
 
909
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the two keys match
962
910
</simpara></listitem></varlistentry>
963
911
</variablelist></refsect2>
964
 
<refsect2>
965
 
<title><anchor id="g-str-hash" role="function"/>g_str_hash ()</title>
966
 
<indexterm><primary>g_str_hash</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_str_hash                          (<link linkend="gconstpointer">gconstpointer</link> v);</programlisting>
 
912
<refsect2 id="g-str-hash" role="function">
 
913
<title>g_str_hash ()</title>
 
914
<indexterm zone="g-str-hash"><primary sortas="g_str_hash">g_str_hash</primary></indexterm><programlisting><link linkend="guint">guint</link>               g_str_hash                          (<link linkend="gconstpointer">gconstpointer</link> v);</programlisting>
967
915
<para>
968
916
Converts a string to a hash value.
969
917
It can be passed to <link linkend="g-hash-table-new"><function>g_hash_table_new()</function></link> as the <parameter>hash_func</parameter> 
970
918
parameter, when using strings as keys in a <link linkend="GHashTable"><type>GHashTable</type></link>.</para>
971
919
<para>
972
920
</para><variablelist role="params">
973
 
<varlistentry><term><parameter>v</parameter>&nbsp;:</term>
 
921
<varlistentry><term><parameter>v</parameter>&#160;:</term>
974
922
<listitem><simpara> a string key
975
923
</simpara></listitem></varlistentry>
976
 
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> a hash value corresponding to the key
 
924
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a hash value corresponding to the key
977
925
</simpara></listitem></varlistentry>
978
926
</variablelist></refsect2>
979
927
 
982
930
 
983
931
 
984
932
 
985
 
 
986
 
<refsect1><refsect2 /><refsect2 /></refsect1>
987
933
</refentry>