ZelphirKaltstahl
/
guile-examples


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>&lt;GHashTable&gt;: </title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.2">
<link rel="home" href="index.html" title="">
<link rel="up" href="ch01.html" title="GLib">
<link rel="prev" href="re19.html" title="&lt;%GLibFormatSizeFlags&gt;">
<link rel="next" href="re21.html" title="&lt;%GLibHookFlagMask&gt;">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="re19.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="re21.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="id-1.1.21"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>&lt;GHashTable&gt;</h2>
<p>&lt;GHashTable&gt;</p>
</div>
<div class="refsect1">
<a name="id-1.1.21.2"></a><h2>Description</h2>
<p>The <span class="type">GHashTable</span> struct is an opaque data structure to represent a
[Hash Table][glib-Hash-Tables]. It should only be accessed via the
following functions.</p>
</div>
<div class="refsect1">
<a name="id-1.1.21.3"></a><h2>Functions</h2>
<div class="refsect2">
<a name="id-1.1.21.3.2"></a><h3>hash-table:add?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table:add? hash-table key))
</pre></div>
<p>This is a convenience function for using a <span class="type">GHashTable</span> as a set.  It
is equivalent to calling <code class="function">g_hash_table_replace()</code> with <em class="parameter"><code>key</code></em> as both the
key and the value.
</p>
<p>In particular, this means that if <em class="parameter"><code>key</code></em> already exists in the hash table, then
the old copy of <em class="parameter"><code>key</code></em> in the hash table is freed and <em class="parameter"><code>key</code></em> replaces it in the
table.
</p>
<p>When a hash table only ever contains keys that have themselves as the
corresponding value it is able to be stored more efficiently.  See
the discussion in the section description.
</p>
<p>Starting from GLib 2.40, this function returns a boolean value to
indicate whether the newly added value was already in the hash table
or not.</p>
<div class="refsect3">
<a name="id-1.1.21.3.2.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>a key to insert</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.3"></a><h3>hash-table:contains?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table:contains? hash-table key))
</pre></div>
<p>Checks if <em class="parameter"><code>key</code></em> is in <em class="parameter"><code>hash_table</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.21.3.3.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>a key to check</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.4"></a><h3>hash-table:destroy</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (hash-table:destroy hash-table))
</pre></div>
<p>Destroys all keys and values in the <span class="type">GHashTable</span> and decrements its
reference count by 1. If keys and/or values are dynamically allocated,
you should either free them first or create the <span class="type">GHashTable</span> with destroy
notifiers using <code class="function">g_hash_table_new_full()</code>. In the latter case the destroy
functions you supplied will be called on all keys and values during the
destruction phase.</p>
<div class="refsect3">
<a name="id-1.1.21.3.4.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.5"></a><h3>hash-table:insert?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table:insert? hash-table key value))
</pre></div>
<p>Inserts a new key and value into a <span class="type">GHashTable</span>.
</p>
<p>If the key already exists in the <span class="type">GHashTable</span> its current
value is replaced with the new value. If you supplied a
<em class="parameter"><code>value_destroy_func</code></em> when creating the <span class="type">GHashTable</span>, the old
value is freed using that function. If you supplied a
<em class="parameter"><code>key_destroy_func</code></em> when creating the <span class="type">GHashTable</span>, the passed
key is freed using that function.
</p>
<p>Starting from GLib 2.40, this function returns a boolean value to
indicate whether the newly added value was already in the hash table
or not.</p>
<div class="refsect3">
<a name="id-1.1.21.3.5.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>a key to insert</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>the value to associate with the key</p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.6"></a><h3>hash-table:lookup</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table:lookup hash-table key))
</pre></div>
<p>Looks up a key in a <span class="type">GHashTable</span>. Note that this function cannot
distinguish between a key that is not present and one which is present
and has the value <code class="constant">NULL</code>. If you need this distinction, use
<code class="function">g_hash_table_lookup_extended()</code>.</p>
<div class="refsect3">
<a name="id-1.1.21.3.6.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to look up</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.7"></a><h3>hash-table:lookup-extended</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return orig-key value)
  (hash-table:lookup-extended hash-table lookup-key))
</pre></div>
<p>Looks up a key in the <span class="type">GHashTable</span>, returning the original key and the
associated value and a <span class="type">gboolean</span> which is <code class="constant">TRUE</code> if the key was found. This
is useful if you need to free the memory allocated for the original key,
for example before calling <code class="function">g_hash_table_remove()</code>.
</p>
<p>You can actually pass <code class="constant">NULL</code> for <em class="parameter"><code>lookup_key</code></em> to test
whether the <code class="constant">NULL</code> key exists, provided the hash and equal functions
of <em class="parameter"><code>hash_table</code></em> are <code class="constant">NULL</code>-safe.</p>
<div class="refsect3">
<a name="id-1.1.21.3.7.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lookup_key</p></td>
<td class="parameter_description">
<p>the key to look up</p>
<p>Passed as <code class="code">lookup-key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>orig_key</p></td>
<td class="parameter_description">
<p>return location for the original key</p>
<p>Passed as <code class="code">orig-key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>return location for the value associated
with the key</p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.8"></a><h3>hash-table:remove?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table:remove? hash-table key))
</pre></div>
<p>Removes a key and its associated value from a <span class="type">GHashTable</span>.
</p>
<p>If the <span class="type">GHashTable</span> was created using <code class="function">g_hash_table_new_full()</code>, 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.</p>
<div class="refsect3">
<a name="id-1.1.21.3.8.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to remove</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.9"></a><h3>hash-table:remove-all</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (hash-table:remove-all hash-table))
</pre></div>
<p>Removes all keys and their associated values from a <span class="type">GHashTable</span>.
</p>
<p>If the <span class="type">GHashTable</span> was created using <code class="function">g_hash_table_new_full()</code>,
the keys and values are freed using the supplied destroy functions,
otherwise you have to make sure that any dynamically allocated
values are freed yourself.</p>
<div class="refsect3">
<a name="id-1.1.21.3.9.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.10"></a><h3>hash-table:replace?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table:replace? hash-table key value))
</pre></div>
<p>Inserts a new key and value into a <span class="type">GHashTable</span> similar to
<code class="function">g_hash_table_insert()</code>. The difference is that if the key
already exists in the <span class="type">GHashTable</span>, it gets replaced by the
new key. If you supplied a <em class="parameter"><code>value_destroy_func</code></em> when creating
the <span class="type">GHashTable</span>, the old value is freed using that function.
If you supplied a <em class="parameter"><code>key_destroy_func</code></em> when creating the
<span class="type">GHashTable</span>, the old key is freed using that function.
</p>
<p>Starting from GLib 2.40, this function returns a boolean value to
indicate whether the newly added value was already in the hash table
or not.</p>
<div class="refsect3">
<a name="id-1.1.21.3.10.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>a key to insert</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>value</p></td>
<td class="parameter_description">
<p>the value to associate with the key</p>
<p>Passed as <code class="code">value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.11"></a><h3>hash-table:size</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table:size hash-table))
</pre></div>
<p>Returns the number of elements contained in the <span class="type">GHashTable</span>.</p>
<div class="refsect3">
<a name="id-1.1.21.3.11.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.12"></a><h3>hash-table:steal?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (hash-table:steal? hash-table key))
</pre></div>
<p>Removes a key and its associated value from a <span class="type">GHashTable</span> without
calling the key and value destroy functions.</p>
<div class="refsect3">
<a name="id-1.1.21.3.12.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>key</p></td>
<td class="parameter_description">
<p>the key to remove</p>
<p>Passed as <code class="code">key</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.13"></a><h3>hash-table:steal-all</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (hash-table:steal-all hash-table))
</pre></div>
<p>Removes all keys and their associated values from a <span class="type">GHashTable</span>
without calling the key and value destroy functions.</p>
<div class="refsect3">
<a name="id-1.1.21.3.13.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.14"></a><h3>hash-table:steal-extended</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return stolen-key stolen-value)
  (hash-table:steal-extended hash-table lookup-key))
</pre></div>
<p>Looks up a key in the <span class="type">GHashTable</span>, stealing the original key and the
associated value and returning <code class="constant">TRUE</code> if the key was found. If the key was
not found, <code class="constant">FALSE</code> is returned.
</p>
<p>If found, the stolen key and value are removed from the hash table without
calling the key and value destroy functions, and ownership is transferred to
the caller of this method; as with <code class="function">g_hash_table_steal()</code>.
</p>
<p>You can pass <code class="constant">NULL</code> for <em class="parameter"><code>lookup_key</code></em>, provided the hash and equal functions
of <em class="parameter"><code>hash_table</code></em> are <code class="constant">NULL</code>-safe.</p>
<div class="refsect3">
<a name="id-1.1.21.3.14.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>lookup_key</p></td>
<td class="parameter_description">
<p>the key to look up</p>
<p>Passed as <code class="code">lookup-key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>stolen_key</p></td>
<td class="parameter_description">
<p>return location for the
   original key</p>
<p>Passed as <code class="code">stolen-key</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>stolen_value</p></td>
<td class="parameter_description">
<p>return location
   for the value associated with the key</p>
<p>Passed as <code class="code">stolen-value</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.21.3.15"></a><h3>hash-table:unref</h3>
<div class="informalexample"><pre class="programlisting">(define-values () (hash-table:unref hash-table))
</pre></div>
<p>Atomically decrements the reference count of <em class="parameter"><code>hash_table</code></em> by one.
If the reference count drops to 0, all keys and values will be
destroyed, and all memory allocated by the hash table is released.
This function is MT-safe and may be called from any thread.</p>
<div class="refsect3">
<a name="id-1.1.21.3.15.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>hash_table</p></td>
<td class="parameter_description">
<p>a valid <span class="type">GHashTable</span></p>
<p>Passed as <code class="code">hash-table</code></p>
</td>
</tr></table></div>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>