docs/reference/glib/tmpl/datasets.sgml

<!-- ##### SECTION Title ##### -->
Datasets

<!-- ##### SECTION Short_Description ##### -->
associate groups of data elements with particular memory locations.

<!-- ##### SECTION Long_Description ##### -->
<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 #GQuark identifiers, which are created
with a call to g_quark_from_string() or g_quark_from_static_string().
The second form is quicker, since it does not require looking up the string
in the hash table of #GQuark 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 g_dataset_id_set_data(),
g_dataset_id_set_data_full(), g_dataset_set_data()
and g_dataset_set_data_full().
</para>
<para>
To get data elements from a dataset use g_dataset_id_get_data() and
g_dataset_get_data().
</para>
<para>
To iterate over all data elements in a dataset use g_dataset_foreach().
</para>
<para>
To remove data elements from a dataset use g_dataset_id_remove_data() and
g_dataset_remove_data().
</para>
<para>
To destroy a dataset, use g_dataset_destroy().
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### MACRO g_dataset_id_set_data ##### -->
<para>
Sets the data element associated with the given #GQuark id.
Any previous data with the same key is removed, and its destroy function
is called.
</para>

@l: the location identifying the dataset.
@k: the #GQuark id to identify the data element.
@d: the data element.


<!-- ##### FUNCTION g_dataset_id_set_data_full ##### -->
<para>
Sets the data element associated with the given #GQuark 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>

@dataset_location: the location identifying the dataset.
@key_id: the #GQuark id to identify the data element.
@data: the data element.
@destroy_func: 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.


<!-- ##### USER_FUNCTION GDestroyNotify ##### -->
<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>

@data: the data element.


<!-- ##### FUNCTION g_dataset_id_get_data ##### -->
<para>
Gets the data element corresponding to a #GQuark.
</para>

@dataset_location: the location identifying the dataset.
@key_id: the #GQuark id to identify the data element.
@Returns: the data element corresponding to the #GQuark, or %NULL if it is
not found.


<!-- ##### MACRO g_dataset_id_remove_data ##### -->
<para>
Removes a data element from a dataset.
The data element's destroy function is called if it has been set.
</para>

@l: the location identifying the dataset.
@k: the #GQuark id identifying the data element.


<!-- ##### FUNCTION g_dataset_id_remove_no_notify ##### -->
<para>
Removes an element, without calling its destroy notification function.
</para>

@dataset_location: the location identifying the dataset.
@key_id: the #GQuark ID identifying the data element.
@Returns: the data previously stored at @key_id, or %NULL if none.


<!-- ##### MACRO g_dataset_set_data ##### -->
<para>
Sets the data corresponding to the given string identifier.
</para>

@l: the location identifying the dataset.
@k: the string to identify the data element.
@d: the data element.


<!-- ##### MACRO g_dataset_set_data_full ##### -->
<para>
Sets the data corresponding to the given string identifier, and the function
to call when the data element is destroyed.
</para>

@l: the location identifying the dataset.
@k: the string to identify the data element.
@d: the data element.
@f: 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.


<!-- ##### MACRO g_dataset_get_data ##### -->
<para>
Gets the data element corresponding to a string.
</para>

@l: the location identifying the dataset.
@k: the string identifying the data element.
@Returns: the data element corresponding to the string, or %NULL if it is not
found.


<!-- ##### MACRO g_dataset_remove_data ##### -->
<para>
Removes a data element corresponding to a string.
Its destroy function is called if it has been set.
</para>

@l: the location identifying the dataset.
@k: the string identifying the data element.


<!-- ##### MACRO g_dataset_remove_no_notify ##### -->
<para>
Removes an element, without calling its destroy notifier.
</para>

@l: the location identifying the dataset.
@k: the string identifying the data element.


<!-- ##### FUNCTION g_dataset_foreach ##### -->
<para>
Calls the given function for each data element which is associated with the
given location.
</para>

@dataset_location: the location identifying the dataset.
@func: the function to call for each data element.
@user_data: user data to pass to the function.


<!-- ##### USER_FUNCTION GDataForeachFunc ##### -->
<para>
Specifies the type of function passed to g_dataset_foreach().
It is called with each #GQuark id and associated data element,
together with the @user_data parameter supplied to g_dataset_foreach().
</para>

@key_id: the #GQuark id to identifying the data element.
@data: the data element.
@user_data: user data passed to g_dataset_foreach().


<!-- ##### FUNCTION g_dataset_destroy ##### -->
<para>
Destroys the dataset, freeing all memory allocated, and calling any
destroy functions set for data elements.
</para>

@dataset_location: the location identifying the dataset.