| <!-- ##### 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> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### 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. |
| |
| |