?? glib-hash-tables.html
字號:
<html xmlns:cf="http://docbook.sourceforge.net/xmlns/chunkfast/1.0"><head><meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"><title>Hash Tables</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.0"><link rel="start" href="index.html" title="GLib Reference Manual"><link rel="up" href="glib-data-types.html" title="GLib Data Types"><link rel="prev" href="glib-Trash-Stacks.html" title="Trash Stacks"><link rel="next" href="glib-Strings.html" title="Strings"><meta name="generator" content="GTK-Doc V1.4 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"><link rel="chapter" href="glib.html" title="GLib Overview"><link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals"><link rel="chapter" href="glib-core.html" title="GLib Core Application Support"><link rel="chapter" href="glib-utilities.html" title="GLib Utilities"><link rel="chapter" href="glib-data-types.html" title="GLib Data Types"><link rel="chapter" href="tools.html" title="GLib Tools"><link rel="index" href="ix01.html" title="Index"><link rel="index" href="ix02.html" title="Index of deprecated symbols"><link rel="index" href="ix03.html" title="Index of new symbols in 2.2"><link rel="index" href="ix04.html" title="Index of new symbols in 2.4"><link rel="index" href="ix05.html" title="Index of new symbols in 2.6"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="glib-Trash-Stacks.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="glib-data-types.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GLib Reference Manual</th><td><a accesskey="n" href="glib-Strings.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="glib-Hash-Tables"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">Hash Tables</span></h2><p>Hash Tables — associations between keys and values so that given a key the valuecan be found quickly.</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">#include <glib.h> <a href="glib-Hash-Tables.html#GHashTable">GHashTable</a>;<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a>* <a href="glib-Hash-Tables.html#g-hash-table-new">g_hash_table_new</a> (<a href="glib-Hash-Tables.html#GHashFunc">GHashFunc</a> hash_func, <a href="glib-Hash-Tables.html#GEqualFunc">GEqualFunc</a> key_equal_func);<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a>* <a href="glib-Hash-Tables.html#g-hash-table-new-full">g_hash_table_new_full</a> (<a href="glib-Hash-Tables.html#GHashFunc">GHashFunc</a> hash_func, <a href="glib-Hash-Tables.html#GEqualFunc">GEqualFunc</a> key_equal_func, <a href="glib-Datasets.html#GDestroyNotify">GDestroyNotify</a> key_destroy_func, <a href="glib-Datasets.html#GDestroyNotify">GDestroyNotify</a> value_destroy_func);<a href="glib-Basic-Types.html#guint">guint</a> (<a href="glib-Hash-Tables.html#GHashFunc">*GHashFunc</a>) (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> key);<a href="glib-Basic-Types.html#gboolean">gboolean</a> (<a href="glib-Hash-Tables.html#GEqualFunc">*GEqualFunc</a>) (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> a, <a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> b);void <a href="glib-Hash-Tables.html#g-hash-table-insert">g_hash_table_insert</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Basic-Types.html#gpointer">gpointer</a> key, <a href="glib-Basic-Types.html#gpointer">gpointer</a> value);void <a href="glib-Hash-Tables.html#g-hash-table-replace">g_hash_table_replace</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Basic-Types.html#gpointer">gpointer</a> key, <a href="glib-Basic-Types.html#gpointer">gpointer</a> value);<a href="glib-Basic-Types.html#guint">guint</a> <a href="glib-Hash-Tables.html#g-hash-table-size">g_hash_table_size</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table);<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Hash-Tables.html#g-hash-table-lookup">g_hash_table_lookup</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> key);<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Hash-Tables.html#g-hash-table-lookup-extended">g_hash_table_lookup_extended</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> lookup_key, <a href="glib-Basic-Types.html#gpointer">gpointer</a> *orig_key, <a href="glib-Basic-Types.html#gpointer">gpointer</a> *value);void <a href="glib-Hash-Tables.html#g-hash-table-foreach">g_hash_table_foreach</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Hash-Tables.html#GHFunc">GHFunc</a> func, <a href="glib-Basic-Types.html#gpointer">gpointer</a> user_data);<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Hash-Tables.html#g-hash-table-find">g_hash_table_find</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Hash-Tables.html#GHRFunc">GHRFunc</a> predicate, <a href="glib-Basic-Types.html#gpointer">gpointer</a> user_data);void (<a href="glib-Hash-Tables.html#GHFunc">*GHFunc</a>) (<a href="glib-Basic-Types.html#gpointer">gpointer</a> key, <a href="glib-Basic-Types.html#gpointer">gpointer</a> value, <a href="glib-Basic-Types.html#gpointer">gpointer</a> user_data);<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Hash-Tables.html#g-hash-table-remove">g_hash_table_remove</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> key);<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Hash-Tables.html#g-hash-table-steal">g_hash_table_steal</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> key);<a href="glib-Basic-Types.html#guint">guint</a> <a href="glib-Hash-Tables.html#g-hash-table-foreach-remove">g_hash_table_foreach_remove</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Hash-Tables.html#GHRFunc">GHRFunc</a> func, <a href="glib-Basic-Types.html#gpointer">gpointer</a> user_data);<a href="glib-Basic-Types.html#guint">guint</a> <a href="glib-Hash-Tables.html#g-hash-table-foreach-steal">g_hash_table_foreach_steal</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table, <a href="glib-Hash-Tables.html#GHRFunc">GHRFunc</a> func, <a href="glib-Basic-Types.html#gpointer">gpointer</a> user_data);<a href="glib-Basic-Types.html#gboolean">gboolean</a> (<a href="glib-Hash-Tables.html#GHRFunc">*GHRFunc</a>) (<a href="glib-Basic-Types.html#gpointer">gpointer</a> key, <a href="glib-Basic-Types.html#gpointer">gpointer</a> value, <a href="glib-Basic-Types.html#gpointer">gpointer</a> user_data);#define <a href="glib-Hash-Tables.html#g-hash-table-freeze">g_hash_table_freeze</a> (hash_table)#define <a href="glib-Hash-Tables.html#g-hash-table-thaw">g_hash_table_thaw</a> (hash_table)void <a href="glib-Hash-Tables.html#g-hash-table-destroy">g_hash_table_destroy</a> (<a href="glib-Hash-Tables.html#GHashTable">GHashTable</a> *hash_table);<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Hash-Tables.html#g-direct-equal">g_direct_equal</a> (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> v, <a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> v2);<a href="glib-Basic-Types.html#guint">guint</a> <a href="glib-Hash-Tables.html#g-direct-hash">g_direct_hash</a> (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> v);<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Hash-Tables.html#g-int-equal">g_int_equal</a> (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> v, <a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> v2);<a href="glib-Basic-Types.html#guint">guint</a> <a href="glib-Hash-Tables.html#g-int-hash">g_int_hash</a> (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> v);<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Hash-Tables.html#g-str-equal">g_str_equal</a> (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> v, <a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> v2);<a href="glib-Basic-Types.html#guint">guint</a> <a href="glib-Hash-Tables.html#g-str-hash">g_str_hash</a> (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> v);</pre></div><div class="refsect1" lang="en"><a name="id3137355"></a><h2>Description</h2><p>A <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> provides associations between keys and values whichis optimized so that given a key, the associated value can be foundvery quickly.</p><p>Note that neither keys nor values are copied when inserted into the<a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>, so they must exist for the lifetime of the <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>.This means that the use of static strings is OK, but temporarystrings (i.e. those created in buffers and those returned by GTK+ widgets)should be copied with <a href="glib-String-Utility-Functions.html#g-strdup"><code class="function">g_strdup()</code></a> before being inserted.</p><p>If keys or values are dynamically allocated, you must be careful to ensurethat they are freed when they are removed from the <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>, and alsowhen they are overwritten by new insertions into the <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>.It is also not advisable to mix static strings and dynamically-allocatedstrings in a <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>, because it then becomes difficult to determinewhether the string should be freed.</p><p>To create a <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>, use <a href="glib-Hash-Tables.html#g-hash-table-new"><code class="function">g_hash_table_new()</code></a>.</p><p>To insert a key and value into a <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>, use <a href="glib-Hash-Tables.html#g-hash-table-insert"><code class="function">g_hash_table_insert()</code></a>.</p><p>To lookup a value corresponding to a given key, use <a href="glib-Hash-Tables.html#g-hash-table-lookup"><code class="function">g_hash_table_lookup()</code></a>and <a href="glib-Hash-Tables.html#g-hash-table-lookup-extended"><code class="function">g_hash_table_lookup_extended()</code></a>.</p><p>To remove a key and value, use <a href="glib-Hash-Tables.html#g-hash-table-remove"><code class="function">g_hash_table_remove()</code></a>.</p><p>To call a function for each key and value pair use <a href="glib-Hash-Tables.html#g-hash-table-foreach"><code class="function">g_hash_table_foreach()</code></a>.</p><p>To destroy a <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> use <a href="glib-Hash-Tables.html#g-hash-table-destroy"><code class="function">g_hash_table_destroy()</code></a>.</p></div><div class="refsect1" lang="en"><a name="id3137565"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id3137571"></a><h3><a name="GHashTable"></a>GHashTable</h3><a class="indexterm" name="id3137580"></a><pre class="programlisting">typedef struct _GHashTable GHashTable;</pre><p>The <span class="structname">GHashTable</span> struct is an opaque data structure to represent a<a href="glib-Hash-Tables.html" title="Hash Tables">Hash Table</a>.It should only be accessed via the following functions.</p></div><hr><div class="refsect2" lang="en"><a name="id3137610"></a><h3><a name="g-hash-table-new"></a>g_hash_table_new ()</h3><a class="indexterm" name="id3137620"></a><pre class="programlisting"><a href="glib-Hash-Tables.html#GHashTable">GHashTable</a>* g_hash_table_new (<a href="glib-Hash-Tables.html#GHashFunc">GHashFunc</a> hash_func, <a href="glib-Hash-Tables.html#GEqualFunc">GEqualFunc</a> key_equal_func);</pre><p>Creates a new <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>.</p><p></p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><em class="parameter"><code>hash_func</code></em> :</span></td><td> a function to create a hash value from a key. Hash values are used to determine where keys are stored within the <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> data structure. The <a href="glib-Hash-Tables.html#g-direct-hash"><code class="function">g_direct_hash()</code></a>, <a href="glib-Hash-Tables.html#g-int-hash"><code class="function">g_int_hash()</code></a> and <a href="glib-Hash-Tables.html#g-str-hash"><code class="function">g_str_hash()</code></a> functions are provided for some common types of keys. If hash_func is <code class="literal">NULL</code>, <a href="glib-Hash-Tables.html#g-direct-hash"><code class="function">g_direct_hash()</code></a> is used.</td></tr><tr><td><span class="term"><em class="parameter"><code>key_equal_func</code></em> :</span></td><td> a function to check two keys for equality. This is used when looking up keys in the <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>. The <a href="glib-Hash-Tables.html#g-direct-equal"><code class="function">g_direct_equal()</code></a>, <a href="glib-Hash-Tables.html#g-int-equal"><code class="function">g_int_equal()</code></a> and <a href="glib-Hash-Tables.html#g-str-equal"><code class="function">g_str_equal()</code></a> functions are provided for the most common types of keys. If <em class="parameter"><code>key_equal_func</code></em> is <code class="literal">NULL</code>, keys are compared directly in a similar fashion to <a href="glib-Hash-Tables.html#g-direct-equal"><code class="function">g_direct_equal()</code></a>, but without the overhead of a function call.</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> a new <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>.</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3137842"></a><h3><a name="g-hash-table-new-full"></a>g_hash_table_new_full ()</h3><a class="indexterm" name="id3137853"></a><pre class="programlisting"><a href="glib-Hash-Tables.html#GHashTable">GHashTable</a>* g_hash_table_new_full (<a href="glib-Hash-Tables.html#GHashFunc">GHashFunc</a> hash_func, <a href="glib-Hash-Tables.html#GEqualFunc">GEqualFunc</a> key_equal_func, <a href="glib-Datasets.html#GDestroyNotify">GDestroyNotify</a> key_destroy_func, <a href="glib-Datasets.html#GDestroyNotify">GDestroyNotify</a> value_destroy_func);</pre><p>Creates a new <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> like <a href="glib-Hash-Tables.html#g-hash-table-new"><code class="function">g_hash_table_new()</code></a> and allows to specifyfunctions to free the memory allocated for the key and value that get called when removing the entry from the <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>.</p><p></p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><em class="parameter"><code>hash_func</code></em> :</span></td><td> a function to create a hash value from a key.</td></tr><tr><td><span class="term"><em class="parameter"><code>key_equal_func</code></em> :</span></td><td> a function to check two keys for equality.</td></tr><tr><td><span class="term"><em class="parameter"><code>key_destroy_func</code></em> :</span></td><td> a function to free the memory allocated for the key used when removing the entry from the <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> or <code class="literal">NULL</code> if you don't want to supply such a function.</td></tr><tr><td><span class="term"><em class="parameter"><code>value_destroy_func</code></em> :</span></td><td> a function to free the memory allocated for the value used when removing the entry from the <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> or <code class="literal">NULL</code> if you don't want to supply such a function.</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> a new <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a>.</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3138049"></a><h3><a name="GHashFunc"></a>GHashFunc ()</h3><a class="indexterm" name="id3138059"></a><pre class="programlisting"><a href="glib-Basic-Types.html#guint">guint</a> (*GHashFunc) (<a href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> key);</pre><p>Specifies the type of the hash function which is passed to<a href="glib-Hash-Tables.html#g-hash-table-new"><code class="function">g_hash_table_new()</code></a> when a <a href="glib-Hash-Tables.html#GHashTable"><span class="type">GHashTable</span></a> is created.</p><p>The function is passed a key and should return a <a href="glib-Basic-Types.html#guint"><span class="type">guint</span></a> hash value.The functions <a href="glib-Hash-Tables.html#g-direct-hash"><code class="function">g_direct_hash()</code></a>, <a href="glib-Hash-Tables.html#g-int-hash"><code class="function">g_int_hash()</code></a> and <a href="glib-Hash-Tables.html#g-str-hash"><code class="function">g_str_hash()</code></a> providehash functions which can be used when the key is a <a href="glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a>, <a href="glib-Basic-Types.html#gint"><span class="type">gint</span></a>, and <a href="glib-Basic-Types.html#gchar"><span class="type">gchar</span></a>* respectively.</p><p>FIXME: Need more here.The hash values should be evenly distributed over a fairly large range?The modulus is taken with the hash table size (a prime number)to find the 'bucket' to place each key into.The function should also be very fast, since it is called for each keylookup.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><em class="parameter"><code>key</code></em> :</span></td><td>a key.</td></tr><tr>?? 快捷鍵說明
復制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號
Ctrl + =
減小字號
Ctrl + -