docs/reference/glib/tmpl/datasets.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Datasets
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 associate groups of data elements with particular memory locations
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Datasets associate groups of data elements with particular memory locations.
  10 These are useful if you need to associate data with a structure returned
  11 from an external library. Since you cannot modify the structure, you use
  12 its location in memory as the key into a dataset, where you can associate
  13 any number of data elements with it.
  14 </para>
  15 <para>
  16 There are two forms of most of the dataset functions.
  17 The first form uses strings to identify the data elements associated with
  18 a location. The second form uses #GQuark identifiers, which are created
  19 with a call to g_quark_from_string() or g_quark_from_static_string().
  20 The second form is quicker, since it does not require looking up the string
  21 in the hash table of #GQuark identifiers.
  22 </para>
  23 <para>
  24 There is no function to create a dataset. It is automatically created as
  25 soon as you add elements to it.
  26 </para>
  27 <para>
  28 To add data elements to a dataset use g_dataset_id_set_data(),
  29 g_dataset_id_set_data_full(), g_dataset_set_data()
  30 and g_dataset_set_data_full().
  31 </para>
  32 <para>
  33 To get data elements from a dataset use g_dataset_id_get_data() and
  34 g_dataset_get_data().
  35 </para>
  36 <para>
  37 To iterate over all data elements in a dataset use g_dataset_foreach() (not thread-safe).
  38 </para>
  39 <para>
  40 To remove data elements from a dataset use g_dataset_id_remove_data() and
  41 g_dataset_remove_data().
  42 </para>
  43 <para>
  44 To 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>
  57 Sets the data element associated with the given #GQuark id.
  58 Any previous data with the same key is removed, and its destroy function
  59 is 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>
  69 Sets the data element associated with the given #GQuark id, and also the
  70 function to call when the data element is destroyed.
  71 Any previous data with the same key is removed, and its
  72 destroy 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
  79 function will be called with the data element and can be used to free any
  80 memory allocated for it.
  81
  82
  83 <!-- ##### USER_FUNCTION GDestroyNotify ##### -->
  84 <para>
  85 Specifies the type of function which is called when a data element is
  86 destroyed. It is passed the pointer to the data element and should free
  87 any 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>
  95 Gets 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
 101 not found.
 102
 103
 104 <!-- ##### MACRO g_dataset_id_remove_data ##### -->
 105 <para>
 106 Removes a data element from a dataset.
 107 The 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>
 116 Removes 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>
 126 Sets 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>
 136 Sets the data corresponding to the given string identifier, and the function
 137 to 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
 144 function will be called with the data element and can be used to free any
 145 memory allocated for it.
 146
 147
 148 <!-- ##### MACRO g_dataset_get_data ##### -->
 149 <para>
 150 Gets 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
 156 found.
 157
 158
 159 <!-- ##### MACRO g_dataset_remove_data ##### -->
 160 <para>
 161 Removes a data element corresponding to a string.
 162 Its 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>
 171 Removes 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>
 180 Calls the given function for each data element which is associated with the
 181 given location.
 182 Note that this function is NOT thread-safe. So unless @datalist
 183 can be protected from any modifications during invocation of this
 184 function, 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>
 194 Specifies the type of function passed to g_dataset_foreach().
 195 It is called with each #GQuark id and associated data element,
 196 together 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>
 206 Destroys the dataset, freeing all memory allocated, and calling any
 207 destroy functions set for data elements.
 208 </para>
 209
 210 @dataset_location: the location identifying the dataset.
 211
 212