datasets.sgml

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

<refentry id="glib-Datasets">
<refmeta>
<refentrytitle>Datasets</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Datasets</refname><refpurpose>associate groups of data elements with particular memory locations.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


#define     <link linkend="g-dataset-id-set-data">g_dataset_id_set_data</link>           (l, k, d)
void        <link linkend="g-dataset-id-set-data-full">g_dataset_id_set_data_full</link>      (<link linkend="gconstpointer">gconstpointer</link> dataset_location,
                                             <link linkend="GQuark">GQuark</link> key_id,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_func);
void        (<link linkend="GDestroyNotify">*GDestroyNotify</link>)               (<link linkend="gpointer">gpointer</link> data);
<link linkend="gpointer">gpointer</link>    <link linkend="g-dataset-id-get-data">g_dataset_id_get_data</link>           (<link linkend="gconstpointer">gconstpointer</link> dataset_location,
                                             <link linkend="GQuark">GQuark</link> key_id);
#define     <link linkend="g-dataset-id-remove-data">g_dataset_id_remove_data</link>        (l, k)
<link linkend="gpointer">gpointer</link>    <link linkend="g-dataset-id-remove-no-notify">g_dataset_id_remove_no_notify</link>   (<link linkend="gconstpointer">gconstpointer</link> dataset_location,
                                             <link linkend="GQuark">GQuark</link> key_id);

#define     <link linkend="g-dataset-set-data">g_dataset_set_data</link>              (l, k, d)
#define     <link linkend="g-dataset-set-data-full">g_dataset_set_data_full</link>         (l, k, d, f)
#define     <link linkend="g-dataset-get-data">g_dataset_get_data</link>              (l, k)
#define     <link linkend="g-dataset-remove-data">g_dataset_remove_data</link>           (l, k)
#define     <link linkend="g-dataset-remove-no-notify">g_dataset_remove_no_notify</link>      (l, k)

void        <link linkend="g-dataset-foreach">g_dataset_foreach</link>               (<link linkend="gconstpointer">gconstpointer</link> dataset_location,
                                             <link linkend="GDataForeachFunc">GDataForeachFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> user_data);
void        (<link linkend="GDataForeachFunc">*GDataForeachFunc</link>)             (<link linkend="GQuark">GQuark</link> key_id,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="gpointer">gpointer</link> user_data);
void        <link linkend="g-dataset-destroy">g_dataset_destroy</link>               (<link linkend="gconstpointer">gconstpointer</link> dataset_location);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
Datasets associate groups of data elements with particular memory locations.
These are useful if you need to associate data with a structure returned
from an external library. Since you cannot modify the structure, you use
its location in memory as the key into a dataset, where you can associate
any number of data elements with it.
</para>
<para>
There are two forms of most of the dataset functions.
The first form uses strings to identify the data elements associated with
a location. The second form uses <link linkend="GQuark">GQuark</link> identifiers, which are created
with a call to <link linkend="g-quark-from-string">g_quark_from_string</link>() or <link linkend="g-quark-from-static-string">g_quark_from_static_string</link>().
The second form is quicker, since it does not require looking up the string
in the hash table of <link linkend="GQuark">GQuark</link> identifiers.
</para>
<para>
There is no function to create a dataset. It is automatically created as
soon as you add elements to it.
</para>
<para>
To add data elements to a dataset use <link linkend="g-dataset-id-set-data">g_dataset_id_set_data</link>(),
<link linkend="g-dataset-id-set-data-full">g_dataset_id_set_data_full</link>(), <link linkend="g-dataset-set-data">g_dataset_set_data</link>()
and <link linkend="g-dataset-set-data-full">g_dataset_set_data_full</link>().
</para>
<para>
To get data elements from a dataset use <link linkend="g-dataset-id-get-data">g_dataset_id_get_data</link>() and
<link linkend="g-dataset-get-data">g_dataset_get_data</link>().
</para>
<para>
To iterate over all data elements in a dataset use <link linkend="g-dataset-foreach">g_dataset_foreach</link>().
</para>
<para>
To remove data elements from a dataset use <link linkend="g-dataset-id-remove-data">g_dataset_id_remove_data</link>() and
<link linkend="g-dataset-remove-data">g_dataset_remove_data</link>().
</para>
<para>
To destroy a dataset, use <link linkend="g-dataset-destroy">g_dataset_destroy</link>().
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="g-dataset-id-set-data">g_dataset_id_set_data()</title>
<programlisting>#define     g_dataset_id_set_data(l, k, d)</programlisting>
<para>
Sets the data element associated with the given <link linkend="GQuark">GQuark</link> id.
Any previous data with the same key is removed, and its destroy function
is called.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>l</parameter>&nbsp;:</entry>
<entry>the location identifying the dataset.
</entry></row>
<row><entry align="right"><parameter>k</parameter>&nbsp;:</entry>
<entry>the <link linkend="GQuark">GQuark</link> id to identify the data element.
</entry></row>
<row><entry align="right"><parameter>d</parameter>&nbsp;:</entry>
<entry>the data element.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-dataset-id-set-data-full">g_dataset_id_set_data_full ()</title>
<programlisting>void        g_dataset_id_set_data_full      (<link linkend="gconstpointer">gconstpointer</link> dataset_location,
                                             <link linkend="GQuark">GQuark</link> key_id,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_func);</programlisting>
<para>
Sets the data element associated with the given <link linkend="GQuark">GQuark</link> id, and also the
function to call when the data element is destroyed.
Any previous data with the same key is removed, and its
destroy function is called.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dataset_location</parameter>&nbsp;:</entry>
<entry>the location identifying the dataset.
</entry></row>
<row><entry align="right"><parameter>key_id</parameter>&nbsp;:</entry>
<entry>the <link linkend="GQuark">GQuark</link> id to identify the data element.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data element.
</entry></row>
<row><entry align="right"><parameter>destroy_func</parameter>&nbsp;:</entry>
<entry>the function to call when the data element is removed. This
function will be called with the data element and can be used to free any
memory allocated for it.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GDestroyNotify">GDestroyNotify ()</title>
<programlisting>void        (*GDestroyNotify)               (<link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Specifies the type of function which is called when a data element is
destroyed. It is passed the pointer to the data element and should free
any memory and resources allocated for it.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry>the data element.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-dataset-id-get-data">g_dataset_id_get_data ()</title>
<programlisting><link linkend="gpointer">gpointer</link>    g_dataset_id_get_data           (<link linkend="gconstpointer">gconstpointer</link> dataset_location,
                                             <link linkend="GQuark">GQuark</link> key_id);</programlisting>
<para>
Gets the data element corresponding to a <link linkend="GQuark">GQuark</link>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dataset_location</parameter>&nbsp;:</entry>
<entry>the location identifying the dataset.
</entry></row>
<row><entry align="right"><parameter>key_id</parameter>&nbsp;:</entry>
<entry>the <link linkend="GQuark">GQuark</link> id to identify the data element.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the data element corresponding to the <link linkend="GQuark">GQuark</link>, or <literal>NULL</literal> if it is
not found.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-dataset-id-remove-data">g_dataset_id_remove_data()</title>
<programlisting>#define     g_dataset_id_remove_data(l, k)</programlisting>
<para>
Removes a data element from a dataset.
The data element's destroy function is called if it has been set.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>l</parameter>&nbsp;:</entry>
<entry>the location identifying the dataset.
</entry></row>
<row><entry align="right"><parameter>k</parameter>&nbsp;:</entry>
<entry>the <link linkend="GQuark">GQuark</link> id identifying the data element.


</entry></row>