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