PageRenderTime 27ms CodeModel.GetById 17ms app.highlight 5ms RepoModel.GetById 1ms app.codeStats 0ms

/src/wrappers/glib/library/data_types/glib_datasets.e

http://github.com/tybor/Liberty
Specman e | 180 lines | 7 code | 46 blank | 127 comment | 0 complexity | 216b4d589778012e319e97762c22110d MD5 | raw file
  1indexing
  2	copyright: "(C) 2005 Paolo Redaelli "
  3	license: "LGPL v2 or later"
  4	date: "$Date:$"
  5	revision: "$REvision:$"
  6
  7class GLIB_DATASETS
  8-- Prev 	Up 	Home 	GLib Reference Manual 	Next
  9-- Top  |  Description
 10-- Datasets
 11
 12-- Datasets %G รข€”%@ associate groups of data elements with particular memory locations.
 13	
 14-- Synopsis
 15
 16-- #include <glib.h>
 17
 18
 19-- #define     g_dataset_id_set_data           (l, k, d)
 20-- void        g_dataset_id_set_data_full      (gconstpointer dataset_location,
 21--                                              GQuark key_id,
 22--                                              gpointer data,
 23--                                              GDestroyNotify destroy_func);
 24-- void        (*GDestroyNotify)               (gpointer data);
 25-- gpointer    g_dataset_id_get_data           (gconstpointer dataset_location,
 26--                                              GQuark key_id);
 27-- #define     g_dataset_id_remove_data        (l, k)
 28-- gpointer    g_dataset_id_remove_no_notify   (gconstpointer dataset_location,
 29--                                              GQuark key_id);
 30
 31-- #define     g_dataset_set_data              (l, k, d)
 32-- #define     g_dataset_set_data_full         (l, k, d, f)
 33-- #define     g_dataset_get_data              (l, k)
 34-- #define     g_dataset_remove_data           (l, k)
 35-- #define     g_dataset_remove_no_notify      (l, k)
 36
 37-- void        g_dataset_foreach               (gconstpointer dataset_location,
 38--                                              GDataForeachFunc func,
 39--                                              gpointer user_data);
 40-- void        (*GDataForeachFunc)             (GQuark key_id,
 41--                                              gpointer data,
 42--                                              gpointer user_data);
 43-- void        g_dataset_destroy               (gconstpointer dataset_location);
 44
 45-- Description
 46
 47-- 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.
 48
 49-- 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.
 50
 51-- There is no function to create a dataset. It is automatically created as soon as you add elements to it.
 52
 53-- 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().
 54
 55-- To get data elements from a dataset use g_dataset_id_get_data() and g_dataset_get_data().
 56
 57-- To iterate over all data elements in a dataset use g_dataset_foreach() (not thread-safe).
 58
 59-- To remove data elements from a dataset use g_dataset_id_remove_data() and g_dataset_remove_data().
 60
 61-- To destroy a dataset, use g_dataset_destroy().
 62-- Details
 63-- g_dataset_id_set_data()
 64
 65-- #define     g_dataset_id_set_data(l, k, d)
 66
 67-- 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.
 68-- l : 	the location identifying the dataset.
 69-- k : 	the GQuark id to identify the data element.
 70-- d : 	the data element.
 71-- g_dataset_id_set_data_full ()
 72
 73-- void        g_dataset_id_set_data_full      (gconstpointer dataset_location,
 74--                                              GQuark key_id,
 75--                                              gpointer data,
 76--                                              GDestroyNotify destroy_func);
 77
 78-- 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.
 79-- dataset_location : 	the location identifying the dataset.
 80-- key_id : 	the GQuark id to identify the data element.
 81-- data : 	the data element.
 82-- 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.
 83-- GDestroyNotify ()
 84
 85-- void        (*GDestroyNotify)               (gpointer data);
 86
 87-- 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.
 88-- data : 	the data element.
 89-- g_dataset_id_get_data ()
 90
 91-- gpointer    g_dataset_id_get_data           (gconstpointer dataset_location,
 92--                                              GQuark key_id);
 93
 94-- Gets the data element corresponding to a GQuark.
 95-- dataset_location : 	the location identifying the dataset.
 96-- key_id : 	the GQuark id to identify the data element.
 97-- Returns : 	the data element corresponding to the GQuark, or NULL if it is not found.
 98-- g_dataset_id_remove_data()
 99
100-- #define     g_dataset_id_remove_data(l, k)
101
102-- Removes a data element from a dataset. The data element's destroy function is called if it has been set.
103-- l : 	the location identifying the dataset.
104-- k : 	the GQuark id identifying the data element.
105-- g_dataset_id_remove_no_notify ()
106
107-- gpointer    g_dataset_id_remove_no_notify   (gconstpointer dataset_location,
108--                                              GQuark key_id);
109
110-- Removes an element, without calling its destroy notification function.
111-- dataset_location : 	the location identifying the dataset.
112-- key_id : 	the GQuark ID identifying the data element.
113-- Returns : 	the data previously stored at key_id, or NULL if none.
114-- g_dataset_set_data()
115
116-- #define     g_dataset_set_data(l, k, d)
117
118-- Sets the data corresponding to the given string identifier.
119-- l : 	the location identifying the dataset.
120-- k : 	the string to identify the data element.
121-- d : 	the data element.
122-- g_dataset_set_data_full()
123
124-- #define     g_dataset_set_data_full(l, k, d, f)
125
126-- Sets the data corresponding to the given string identifier, and the function to call when the data element is destroyed.
127-- l : 	the location identifying the dataset.
128-- k : 	the string to identify the data element.
129-- d : 	the data element.
130-- 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.
131-- g_dataset_get_data()
132
133-- #define     g_dataset_get_data(l, k)
134
135-- Gets the data element corresponding to a string.
136-- l : 	the location identifying the dataset.
137-- k : 	the string identifying the data element.
138-- Returns : 	the data element corresponding to the string, or NULL if it is not found.
139-- g_dataset_remove_data()
140
141-- #define     g_dataset_remove_data(l, k)
142
143-- Removes a data element corresponding to a string. Its destroy function is called if it has been set.
144-- l : 	the location identifying the dataset.
145-- k : 	the string identifying the data element.
146-- g_dataset_remove_no_notify()
147
148-- #define     g_dataset_remove_no_notify(l, k)
149
150-- Removes an element, without calling its destroy notifier.
151-- l : 	the location identifying the dataset.
152-- k : 	the string identifying the data element.
153-- g_dataset_foreach ()
154
155-- void        g_dataset_foreach               (gconstpointer dataset_location,
156--                                              GDataForeachFunc func,
157--                                              gpointer user_data);
158
159-- Calls the given function for each data element which is associated with the given location. Note that this function is NOT thread-safe. So unless datalist can be protected from any modifications during invocation of this function, it should not be called.
160-- dataset_location : 	the location identifying the dataset.
161-- func : 	the function to call for each data element.
162-- user_data : 	user data to pass to the function.
163-- GDataForeachFunc ()
164
165-- void        (*GDataForeachFunc)             (GQuark key_id,
166--                                              gpointer data,
167--                                              gpointer user_data);
168
169-- 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().
170-- key_id : 	the GQuark id to identifying the data element.
171-- data : 	the data element.
172-- user_data : 	user data passed to g_dataset_foreach().
173-- g_dataset_destroy ()
174
175-- void        g_dataset_destroy               (gconstpointer dataset_location);
176
177-- Destroys the dataset, freeing all memory allocated, and calling any destroy functions set for data elements.
178-- dataset_location : 	the location identifying the dataset.
179end
180