1<!-- ##### SECTION Title ##### --> 2Datasets 3 4<!-- ##### SECTION Short_Description ##### --> 5associate groups of data elements with particular memory locations 6 7<!-- ##### SECTION Long_Description ##### --> 8<para> 9Datasets associate groups of data elements with particular memory locations. 10These are useful if you need to associate data with a structure returned 11from an external library. Since you cannot modify the structure, you use 12its location in memory as the key into a dataset, where you can associate 13any number of data elements with it. 14</para> 15<para> 16There are two forms of most of the dataset functions. 17The first form uses strings to identify the data elements associated with 18a location. The second form uses #GQuark identifiers, which are created 19with a call to g_quark_from_string() or g_quark_from_static_string(). 20The second form is quicker, since it does not require looking up the string 21in the hash table of #GQuark identifiers. 22</para> 23<para> 24There is no function to create a dataset. It is automatically created as 25soon as you add elements to it. 26</para> 27<para> 28To add data elements to a dataset use g_dataset_id_set_data(), 29g_dataset_id_set_data_full(), g_dataset_set_data() 30and g_dataset_set_data_full(). 31</para> 32<para> 33To get data elements from a dataset use g_dataset_id_get_data() and 34g_dataset_get_data(). 35</para> 36<para> 37To iterate over all data elements in a dataset use g_dataset_foreach() (not thread-safe). 38</para> 39<para> 40To remove data elements from a dataset use g_dataset_id_remove_data() and 41g_dataset_remove_data(). 42</para> 43<para> 44To destroy a dataset, use g_dataset_destroy(). 45</para> 46 47<!-- ##### SECTION See_Also ##### --> 48<para> 49 50</para> 51 52<!-- ##### SECTION Stability_Level ##### --> 53 54 55<!-- ##### MACRO g_dataset_id_set_data ##### --> 56<para> 57Sets the data element associated with the given #GQuark id. 58Any previous data with the same key is removed, and its destroy function 59is called. 60</para> 61 62@l: the location identifying the dataset. 63@k: the #GQuark id to identify the data element. 64@d: the data element. 65 66 67<!-- ##### FUNCTION g_dataset_id_set_data_full ##### --> 68<para> 69Sets the data element associated with the given #GQuark id, and also the 70function to call when the data element is destroyed. 71Any previous data with the same key is removed, and its 72destroy function is called. 73</para> 74 75@dataset_location: the location identifying the dataset. 76@key_id: the #GQuark id to identify the data element. 77@data: the data element. 78@destroy_func: the function to call when the data element is removed. This 79function will be called with the data element and can be used to free any 80memory allocated for it. 81 82 83<!-- ##### USER_FUNCTION GDestroyNotify ##### --> 84<para> 85Specifies the type of function which is called when a data element is 86destroyed. It is passed the pointer to the data element and should free 87any memory and resources allocated for it. 88</para> 89 90@data: the data element. 91 92 93<!-- ##### FUNCTION g_dataset_id_get_data ##### --> 94<para> 95Gets the data element corresponding to a #GQuark. 96</para> 97 98@dataset_location: the location identifying the dataset. 99@key_id: the #GQuark id to identify the data element. 100@Returns: the data element corresponding to the #GQuark, or %NULL if it is 101not found. 102 103 104<!-- ##### MACRO g_dataset_id_remove_data ##### --> 105<para> 106Removes a data element from a dataset. 107The data element's destroy function is called if it has been set. 108</para> 109 110@l: the location identifying the dataset. 111@k: the #GQuark id identifying the data element. 112 113 114<!-- ##### FUNCTION g_dataset_id_remove_no_notify ##### --> 115<para> 116Removes an element, without calling its destroy notification function. 117</para> 118 119@dataset_location: the location identifying the dataset. 120@key_id: the #GQuark ID identifying the data element. 121@Returns: the data previously stored at @key_id, or %NULL if none. 122 123 124<!-- ##### MACRO g_dataset_set_data ##### --> 125<para> 126Sets the data corresponding to the given string identifier. 127</para> 128 129@l: the location identifying the dataset. 130@k: the string to identify the data element. 131@d: the data element. 132 133 134<!-- ##### MACRO g_dataset_set_data_full ##### --> 135<para> 136Sets the data corresponding to the given string identifier, and the function 137to call when the data element is destroyed. 138</para> 139 140@l: the location identifying the dataset. 141@k: the string to identify the data element. 142@d: the data element. 143@f: the function to call when the data element is removed. This 144function will be called with the data element and can be used to free any 145memory allocated for it. 146 147 148<!-- ##### MACRO g_dataset_get_data ##### --> 149<para> 150Gets the data element corresponding to a string. 151</para> 152 153@l: the location identifying the dataset. 154@k: the string identifying the data element. 155@Returns: the data element corresponding to the string, or %NULL if it is not 156found. 157 158 159<!-- ##### MACRO g_dataset_remove_data ##### --> 160<para> 161Removes a data element corresponding to a string. 162Its destroy function is called if it has been set. 163</para> 164 165@l: the location identifying the dataset. 166@k: the string identifying the data element. 167 168 169<!-- ##### MACRO g_dataset_remove_no_notify ##### --> 170<para> 171Removes an element, without calling its destroy notifier. 172</para> 173 174@l: the location identifying the dataset. 175@k: the string identifying the data element. 176 177 178<!-- ##### FUNCTION g_dataset_foreach ##### --> 179<para> 180Calls the given function for each data element which is associated with the 181given location. 182Note that this function is NOT thread-safe. So unless @datalist 183can be protected from any modifications during invocation of this 184function, it should not be called. 185</para> 186 187@dataset_location: the location identifying the dataset. 188@func: the function to call for each data element. 189@user_data: user data to pass to the function. 190 191 192<!-- ##### USER_FUNCTION GDataForeachFunc ##### --> 193<para> 194Specifies the type of function passed to g_dataset_foreach(). 195It is called with each #GQuark id and associated data element, 196together with the @user_data parameter supplied to g_dataset_foreach(). 197</para> 198 199@key_id: the #GQuark id to identifying the data element. 200@data: the data element. 201@user_data: user data passed to g_dataset_foreach(). 202 203 204<!-- ##### FUNCTION g_dataset_destroy ##### --> 205<para> 206Destroys the dataset, freeing all memory allocated, and calling any 207destroy functions set for data elements. 208</para> 209 210@dataset_location: the location identifying the dataset. 211 212 213