glib/docs/reference/glib/tmpl/datalist.sgml

<!-- ##### SECTION Title ##### -->
Keyed Data Lists

<!-- ##### SECTION Short_Description ##### -->
lists of data elements which are accessible by a string or #GQuark identifier.

<!-- ##### SECTION Long_Description ##### -->
<para>
Keyed data lists provide lists of arbitrary data elements which can be accessed
either with a string or with a #GQuark corresponding to the
string.
</para>
<para>
The #GQuark methods are quicker, since the strings have to be converted to
#GQuarks anyway.
</para>
<para>
Data lists are used for associating arbitrary data with
#GObjects, using g_object_set_data() and related functions.
</para>

<para>
To create a datalist, use g_datalist_init().
</para>
<para>
To add data elements to a datalist use g_datalist_id_set_data(),
g_datalist_id_set_data_full(), g_datalist_set_data()
and g_datalist_set_data_full().
</para>
<para>
To get data elements from a datalist use g_datalist_id_get_data() and
g_datalist_get_data().
</para>
<para>
To iterate over all data elements in a datalist use g_datalist_foreach().
</para>
<para>
To remove data elements from a datalist use g_datalist_id_remove_data() and
g_datalist_remove_data().
</para>
<para>
To remove all data elements from a datalist, use g_datalist_clear().
</para>

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

</para>

<!-- ##### STRUCT GData ##### -->
<para>
The #GData struct is an opaque data structure to represent a
<link linkend="glib-Keyed-Data-Lists">Keyed Data List</link>.
It should only be accessed via the following functions.
</para>


<!-- ##### FUNCTION g_datalist_init ##### -->
<para>
Resets the datalist to %NULL.
It does not free any memory or call any destroy functions.
</para>

@datalist: a pointer to a pointer to a datalist.


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

@dl: a datalist.
@q: the #GQuark to identify the data element.
@d: the data element, or %NULL to remove any previous element
corresponding to @q.


<!-- ##### FUNCTION g_datalist_id_set_data_full ##### -->
<para>
Sets the data corresponding to the given #GQuark id, and the function to
be called when the element is removed from the datalist.
Any previous data with the same key is removed, and its
destroy function is called.
</para>

@datalist: a datalist.
@key_id: the #GQuark to identify the data element.
@data: the data element or %NULL to remove any previous element
corresponding to @key_id.
@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. If @data is %NULL, then @destroy_func must
also be %NULL.


<!-- ##### FUNCTION g_datalist_id_get_data ##### -->
<para>
Retrieves the data element corresponding to @key_id. 
</para>

@datalist: a datalist.
@key_id: the #GQuark identifying a data element.
@Returns: the data element, or %NULL if it is not found.


<!-- ##### MACRO g_datalist_id_remove_data ##### -->
<para>
Removes an element, using its #GQuark identifier.
</para>

@dl: a datalist.
@q: the #GQuark identifying the data element.


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

@datalist: a datalist.
@key_id: the #GQuark identifying a data element.
@Returns: the data previously stored at @key_id, or %NULL if none.


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

@dl: a datalist.
@k: the string to identify the data element.
@d: the data element, or %NULL to remove any previous element
corresponding to @k.


<!-- ##### MACRO g_datalist_set_data_full ##### -->
<para>
Sets the data element corresponding to the given string identifier, and the
function to be called when the data element is removed.
</para>

@dl: a datalist.
@k: the string to identify the data element.
@d: the data element, or %NULL to remove any previous element corresponding to
@k.
@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. If @d is %NULL, then @f must also be %NULL.


<!-- ##### MACRO g_datalist_get_data ##### -->
<para>
Gets a data element, using its string identifer.
This is slower than g_datalist_id_get_data() because the string is first
converted to a #GQuark.
</para>

@dl: a datalist.
@k: the string identifying a data element.
@Returns: the data element, or %NULL if it is not found.


<!-- ##### MACRO g_datalist_remove_data ##### -->
<para>
Removes an element using its string identifier.
The data element's destroy function is called if it has been set.
</para>

@dl: a datalist.
@k: the string identifying the data element.


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

@dl: a datalist.
@k: the string identifying the data element.


<!-- ##### FUNCTION g_datalist_foreach ##### -->
<para>
Calls the given function for each data element of the datalist.
The function is called with each data element's #GQuark id and data,
together with the given @user_data parameter.
</para>

@datalist: a datalist.
@func: the function to call for each data element.
@user_data: user data to pass to the function.


<!-- ##### FUNCTION g_datalist_clear ##### -->
<para>
Frees all the data elements of the datalist.
The data elements' destroy functions are called if they have been set.
</para>

@datalist: a datalist.