1 <!-- ##### SECTION Title ##### --> 2 Keyed Data Lists 3 4 <!-- ##### SECTION Short_Description ##### --> 5 lists of data elements which are accessible by a string or GQuark identifier 6 7 <!-- ##### SECTION Long_Description ##### --> 8 <para> 9 Keyed data lists provide lists of arbitrary data elements which can be accessed 10 either with a string or with a #GQuark corresponding to the 11 string. 12 </para> 13 <para> 14 The #GQuark methods are quicker, since the strings have to be converted to 15 #GQuarks anyway. 16 </para> 17 <para> 18 Data lists are used for associating arbitrary data with 19 #GObjects, using g_object_set_data() and related functions. 20 </para> 21 22 <para> 23 To create a datalist, use g_datalist_init(). 24 </para> 25 <para> 26 To add data elements to a datalist use g_datalist_id_set_data(), 27 g_datalist_id_set_data_full(), g_datalist_set_data() 28 and g_datalist_set_data_full(). 29 </para> 30 <para> 31 To get data elements from a datalist use g_datalist_id_get_data() and 32 g_datalist_get_data(). 33 </para> 34 <para> 35 To iterate over all data elements in a datalist use g_datalist_foreach() (not thread-safe). 36 </para> 37 <para> 38 To remove data elements from a datalist use g_datalist_id_remove_data() and 39 g_datalist_remove_data(). 40 </para> 41 <para> 42 To remove all data elements from a datalist, use g_datalist_clear(). 43 </para> 44 45 <!-- ##### SECTION See_Also ##### --> 46 <para> 47 48 </para> 49 50 <!-- ##### SECTION Stability_Level ##### --> 51 52 53 <!-- ##### STRUCT GData ##### --> 54 <para> 55 The #GData struct is an opaque data structure to represent a 56 <link linkend="glib-Keyed-Data-Lists">Keyed Data List</link>. 57 It should only be accessed via the following functions. 58 </para> 59 60 61 <!-- ##### FUNCTION g_datalist_init ##### --> 62 <para> 63 Resets the datalist to %NULL. 64 It does not free any memory or call any destroy functions. 65 </para> 66 67 @datalist: a pointer to a pointer to a datalist. 68 69 70 <!-- ##### MACRO g_datalist_id_set_data ##### --> 71 <para> 72 Sets the data corresponding to the given #GQuark id. 73 Any previous data with the same key is removed, and its 74 destroy function is called. 75 </para> 76 77 @dl: a datalist. 78 @q: the #GQuark to identify the data element. 79 @d: the data element, or %NULL to remove any previous element 80 corresponding to @q. 81 82 83 <!-- ##### FUNCTION g_datalist_id_set_data_full ##### --> 84 <para> 85 Sets the data corresponding to the given #GQuark id, and the function to 86 be called when the element is removed from the datalist. 87 Any previous data with the same key is removed, and its 88 destroy function is called. 89 </para> 90 91 @datalist: a datalist. 92 @key_id: the #GQuark to identify the data element. 93 @data: the data element or %NULL to remove any previous element 94 corresponding to @key_id. 95 @destroy_func: the function to call when the data element is removed. This 96 function will be called with the data element and can be used to free any 97 memory allocated for it. If @data is %NULL, then @destroy_func must 98 also be %NULL. 99 100 101 <!-- ##### FUNCTION g_datalist_id_get_data ##### --> 102 <para> 103 Retrieves the data element corresponding to @key_id. 104 </para> 105 106 @datalist: a datalist. 107 @key_id: the #GQuark identifying a data element. 108 @Returns: the data element, or %NULL if it is not found. 109 110 111 <!-- ##### MACRO g_datalist_id_remove_data ##### --> 112 <para> 113 Removes an element, using its #GQuark identifier. 114 </para> 115 116 @dl: a datalist. 117 @q: the #GQuark identifying the data element. 118 119 120 <!-- ##### FUNCTION g_datalist_id_remove_no_notify ##### --> 121 <para> 122 Removes an element, without calling its destroy notification function. 123 </para> 124 125 @datalist: a datalist. 126 @key_id: the #GQuark identifying a data element. 127 @Returns: the data previously stored at @key_id, or %NULL if none. 128 129 130 <!-- ##### MACRO g_datalist_set_data ##### --> 131 <para> 132 Sets the data element corresponding to the given string identifier. 133 </para> 134 135 @dl: a datalist. 136 @k: the string to identify the data element. 137 @d: the data element, or %NULL to remove any previous element 138 corresponding to @k. 139 140 141 <!-- ##### MACRO g_datalist_set_data_full ##### --> 142 <para> 143 Sets the data element corresponding to the given string identifier, and the 144 function to be called when the data element is removed. 145 </para> 146 147 @dl: a datalist. 148 @k: the string to identify the data element. 149 @d: the data element, or %NULL to remove any previous element corresponding to 150 @k. 151 @f: the function to call when the data element is removed. This 152 function will be called with the data element and can be used to free any 153 memory allocated for it. If @d is %NULL, then @f must also be %NULL. 154 155 156 <!-- ##### MACRO g_datalist_get_data ##### --> 157 <para> 158 Gets a data element, using its string identifer. 159 This is slower than g_datalist_id_get_data() because the string is first 160 converted to a #GQuark. 161 </para> 162 163 @dl: a datalist. 164 @k: the string identifying a data element. 165 @Returns: the data element, or %NULL if it is not found. 166 167 168 <!-- ##### MACRO g_datalist_remove_data ##### --> 169 <para> 170 Removes an element using its string identifier. 171 The data element's destroy function is called if it has been set. 172 </para> 173 174 @dl: a datalist. 175 @k: the string identifying the data element. 176 177 178 <!-- ##### MACRO g_datalist_remove_no_notify ##### --> 179 <para> 180 Removes an element, without calling its destroy notifier. 181 </para> 182 183 @dl: a datalist. 184 @k: the string identifying the data element. 185 186 187 <!-- ##### FUNCTION g_datalist_foreach ##### --> 188 <para> 189 Calls the given function for each data element of the datalist. 190 The function is called with each data element's #GQuark id and data, 191 together with the given @user_data parameter. 192 Note that this function is NOT thread-safe. So unless @datalist 193 can be protected from any modifications during invocation of this 194 function, it should not be called. 195 </para> 196 197 @datalist: a datalist. 198 @func: the function to call for each data element. 199 @user_data: user data to pass to the function. 200 201 202 <!-- ##### FUNCTION g_datalist_clear ##### --> 203 <para> 204 Frees all the data elements of the datalist. 205 The data elements' destroy functions are called if they have been set. 206 </para> 207 208 @datalist: a datalist. 209 210 211 <!-- ##### FUNCTION g_datalist_set_flags ##### --> 212 <para> 213 214 </para> 215 216 @datalist: 217 @flags: 218 219 220 <!-- ##### FUNCTION g_datalist_unset_flags ##### --> 221 <para> 222 223 </para> 224 225 @datalist: 226 @flags: 227 228 229 <!-- ##### FUNCTION g_datalist_get_flags ##### --> 230 <para> 231 232 </para> 233 234 @datalist: 235 @Returns: 236 237 238 <!-- ##### MACRO G_DATALIST_FLAGS_MASK ##### --> 239 <para> 240 241 </para> 242 243 244 245
