📄 glib-datasets.html
字号:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head><meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"><title>Datasets</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"><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-Keyed-Data-Lists.html" title="Keyed Data Lists"><link rel="next" href="glib-Relations-and-Tuples.html" title="Relations and Tuples"><meta name="generator" content="GTK-Doc V1.9 (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"><link rel="index" href="ix06.html" title="Index of new symbols in 2.8"><link rel="index" href="ix07.html" title="Index of new symbols in 2.10"><link rel="index" href="ix08.html" title="Index of new symbols in 2.12"><link rel="index" href="ix09.html" title="Index of new symbols in 2.14"><link rel="index" href="ix10.html" title="Index of new symbols in 2.16"></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="2"><tr valign="middle"><td><a accesskey="p" href="glib-Keyed-Data-Lists.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-Relations-and-Tuples.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr><tr><td colspan="5" class="shortcuts"><nobr><a href="#id3357803" class="shortcut">Top</a>  |  <a href="#id3358114" class="shortcut">Description</a></nobr></td></tr></table><div class="refentry" lang="en"><a name="glib-Datasets"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><a name="id3357803"></a><span class="refentrytitle">Datasets</span></h2><p>Datasets — associate groups of data elements with particular memory locations</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">#include <glib.h>#define <a class="link" href="glib-Datasets.html#g-dataset-id-set-data">g_dataset_id_set_data</a> (l, k, d)void <a class="link" href="glib-Datasets.html#g-dataset-id-set-data-full">g_dataset_id_set_data_full</a> (<a class="link" href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> dataset_location, <a class="link" href="glib-Quarks.html#GQuark">GQuark</a> key_id, <a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> data, <a class="link" href="glib-Datasets.html#GDestroyNotify">GDestroyNotify</a> destroy_func);void (<a class="link" href="glib-Datasets.html#GDestroyNotify">*GDestroyNotify</a>) (<a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> data);<a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> <a class="link" href="glib-Datasets.html#g-dataset-id-get-data">g_dataset_id_get_data</a> (<a class="link" href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> dataset_location, <a class="link" href="glib-Quarks.html#GQuark">GQuark</a> key_id);#define <a class="link" href="glib-Datasets.html#g-dataset-id-remove-data">g_dataset_id_remove_data</a> (l, k)<a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> <a class="link" href="glib-Datasets.html#g-dataset-id-remove-no-notify">g_dataset_id_remove_no_notify</a> (<a class="link" href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> dataset_location, <a class="link" href="glib-Quarks.html#GQuark">GQuark</a> key_id);#define <a class="link" href="glib-Datasets.html#g-dataset-set-data">g_dataset_set_data</a> (l, k, d)#define <a class="link" href="glib-Datasets.html#g-dataset-set-data-full">g_dataset_set_data_full</a> (l, k, d, f)#define <a class="link" href="glib-Datasets.html#g-dataset-get-data">g_dataset_get_data</a> (l, k)#define <a class="link" href="glib-Datasets.html#g-dataset-remove-data">g_dataset_remove_data</a> (l, k)#define <a class="link" href="glib-Datasets.html#g-dataset-remove-no-notify">g_dataset_remove_no_notify</a> (l, k)void <a class="link" href="glib-Datasets.html#g-dataset-foreach">g_dataset_foreach</a> (<a class="link" href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> dataset_location, <a class="link" href="glib-Datasets.html#GDataForeachFunc">GDataForeachFunc</a> func, <a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> user_data);void (<a class="link" href="glib-Datasets.html#GDataForeachFunc">*GDataForeachFunc</a>) (<a class="link" href="glib-Quarks.html#GQuark">GQuark</a> key_id, <a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> data, <a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> user_data);void <a class="link" href="glib-Datasets.html#g-dataset-destroy">g_dataset_destroy</a> (<a class="link" href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> dataset_location);</pre></div><div class="refsect1" lang="en"><a name="id3358114"></a><h2>Description</h2><p>Datasets associate groups of data elements with particular memory locations.These are useful if you need to associate data with a structure returnedfrom an external library. Since you cannot modify the structure, you useits location in memory as the key into a dataset, where you can associateany number of data elements with it.</p><p>There are two forms of most of the dataset functions.The first form uses strings to identify the data elements associated witha location. The second form uses <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> identifiers, which are createdwith a call to <a class="link" href="glib-Quarks.html#g-quark-from-string"><code class="function">g_quark_from_string()</code></a> or <a class="link" href="glib-Quarks.html#g-quark-from-static-string"><code class="function">g_quark_from_static_string()</code></a>.The second form is quicker, since it does not require looking up the stringin the hash table of <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> identifiers.</p><p>There is no function to create a dataset. It is automatically created assoon as you add elements to it.</p><p>To add data elements to a dataset use <a class="link" href="glib-Datasets.html#g-dataset-id-set-data"><code class="function">g_dataset_id_set_data()</code></a>,<a class="link" href="glib-Datasets.html#g-dataset-id-set-data-full"><code class="function">g_dataset_id_set_data_full()</code></a>, <a class="link" href="glib-Datasets.html#g-dataset-set-data"><code class="function">g_dataset_set_data()</code></a>and <a class="link" href="glib-Datasets.html#g-dataset-set-data-full"><code class="function">g_dataset_set_data_full()</code></a>.</p><p>To get data elements from a dataset use <a class="link" href="glib-Datasets.html#g-dataset-id-get-data"><code class="function">g_dataset_id_get_data()</code></a> and<a class="link" href="glib-Datasets.html#g-dataset-get-data"><code class="function">g_dataset_get_data()</code></a>.</p><p>To iterate over all data elements in a dataset use <a class="link" href="glib-Datasets.html#g-dataset-foreach"><code class="function">g_dataset_foreach()</code></a> (not thread-safe).</p><p>To remove data elements from a dataset use <a class="link" href="glib-Datasets.html#g-dataset-id-remove-data"><code class="function">g_dataset_id_remove_data()</code></a> and<a class="link" href="glib-Datasets.html#g-dataset-remove-data"><code class="function">g_dataset_remove_data()</code></a>.</p><p>To destroy a dataset, use <a class="link" href="glib-Datasets.html#g-dataset-destroy"><code class="function">g_dataset_destroy()</code></a>.</p></div><div class="refsect1" lang="en"><a name="id3358319"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id3358330"></a><h3><a name="g-dataset-id-set-data"></a>g_dataset_id_set_data()</h3><a class="indexterm" name="id3358342"></a><pre class="programlisting">#define g_dataset_id_set_data(l, k, d)</pre><p>Sets the data element associated with the given <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> id.Any previous data with the same key is removed, and its destroy functionis called.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><em class="parameter"><code>l</code></em> :</span></p></td><td>the location identifying the dataset.</td></tr><tr><td><p><span class="term"><em class="parameter"><code>k</code></em> :</span></p></td><td>the <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> id to identify the data element.</td></tr><tr><td><p><span class="term"><em class="parameter"><code>d</code></em> :</span></p></td><td>the data element.</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3358422"></a><h3><a name="g-dataset-id-set-data-full"></a>g_dataset_id_set_data_full ()</h3><a class="indexterm" name="id3358436"></a><pre class="programlisting">void g_dataset_id_set_data_full (<a class="link" href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> dataset_location, <a class="link" href="glib-Quarks.html#GQuark">GQuark</a> key_id, <a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> data, <a class="link" href="glib-Datasets.html#GDestroyNotify">GDestroyNotify</a> destroy_func);</pre><p>Sets the data element associated with the given <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> id, and also thefunction to call when the data element is destroyed.Any previous data with the same key is removed, and itsdestroy function is called.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><em class="parameter"><code>dataset_location</code></em> :</span></p></td><td>the location identifying the dataset.</td></tr><tr><td><p><span class="term"><em class="parameter"><code>key_id</code></em> :</span></p></td><td>the <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> id to identify the data element.</td></tr><tr><td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td><td>the data element.</td></tr><tr><td><p><span class="term"><em class="parameter"><code>destroy_func</code></em> :</span></p></td><td>the function to call when the data element is removed. Thisfunction will be called with the data element and can be used to free anymemory allocated for it.</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3358571"></a><h3><a name="GDestroyNotify"></a>GDestroyNotify ()</h3><a class="indexterm" name="id3358584"></a><pre class="programlisting">void (*GDestroyNotify) (<a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> data);</pre><p>Specifies the type of function which is called when a data element isdestroyed. It is passed the pointer to the data element and should freeany memory and resources allocated for it.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td><td>the data element.</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3358634"></a><h3><a name="g-dataset-id-get-data"></a>g_dataset_id_get_data ()</h3><a class="indexterm" name="id3358647"></a><pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> g_dataset_id_get_data (<a class="link" href="glib-Basic-Types.html#gconstpointer">gconstpointer</a> dataset_location, <a class="link" href="glib-Quarks.html#GQuark">GQuark</a> key_id);</pre><p>Gets the data element corresponding to a <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a>.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><em class="parameter"><code>dataset_location</code></em> :</span></p></td><td>the location identifying the dataset.</td></tr><tr><td><p><span class="term"><em class="parameter"><code>key_id</code></em> :</span></p></td><td>the <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> id to identify the data element.</td></tr><tr><td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td><td>the data element corresponding to the <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a>, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> if it isnot found.</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3358763"></a><h3><a name="g-dataset-id-remove-data"></a>g_dataset_id_remove_data()</h3><a class="indexterm" name="id3358776"></a><pre class="programlisting">#define g_dataset_id_remove_data(l, k)</pre><p>Removes a data element from a dataset.The data element's destroy function is called if it has been set.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><em class="parameter"><code>l</code></em> :</span></p></td><td>the location identifying the dataset.</td></tr><tr><td><p><span class="term"><em class="parameter"><code>k</code></em> :</span></p></td><td>the <a class="link" href="glib-Quarks.html#GQuark"><span class="type">GQuark</span></a> id identifying the data element.</td></tr></tbody></table></div></div><hr>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -