mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-04-14 19:48:05 +02:00
213 lines
6.2 KiB
Plaintext
213 lines
6.2 KiB
Plaintext
<!-- ##### 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() (not thread-safe).
|
|
</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.
|
|
Note that this function is NOT thread-safe. So unless @datalist
|
|
can be protected from any modifications during invocation of this
|
|
function, it should not be called.
|
|
</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.
|
|
|
|
|