<!-- ##### 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 returnedfrom an external library. Since you cannot modify the structure, you useits location in memory as the key into a dataset, where you can associateany 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 witha location. The second form uses #GQuark identifiers, which are createdwith 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 stringin the hash table of #GQuark identifiers.</para><para>There is no function to create a dataset. It is automatically created assoon 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() andg_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() andg_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 functionis 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 thefunction to call when the data element is destroyed.Any previous data with the same key is removed, and itsdestroy 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. Thisfunction will be called with the data element and can be used to free anymemory allocated for it.<!-- ##### USER_FUNCTION GDestroyNotify ##### --><para>Specifies the type of function which is called when a data element isdestroyed. It is passed the pointer to the data element and should freeany 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 isnot 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 functionto 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. Thisfunction will be called with the data element and can be used to free anymemory 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 notfound.<!-- ##### 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 thegiven location.Note that this function is NOT thread-safe. So unless @datalistcan be protected from any modifications during invocation of thisfunction, 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 anydestroy functions set for data elements.</para>@dataset_location: the location identifying the dataset.