Top | ![]() |
![]() |
![]() |
![]() |
Keyed Data ListsKeyed Data Lists — lists of data elements which are accessible by a string or GQuark identifier |
void | g_datalist_init () |
#define | g_datalist_id_set_data() |
void | g_datalist_id_set_data_full () |
gpointer | g_datalist_id_get_data () |
#define | g_datalist_id_remove_data() |
gpointer | g_datalist_id_remove_no_notify () |
#define | g_datalist_set_data() |
#define | g_datalist_set_data_full() |
gpointer | g_datalist_get_data () |
#define | g_datalist_remove_data() |
#define | g_datalist_remove_no_notify() |
void | g_datalist_foreach () |
void | g_datalist_clear () |
void | g_datalist_set_flags () |
void | g_datalist_unset_flags () |
guint | g_datalist_get_flags () |
Keyed data lists provide lists of arbitrary data elements which can be accessed either with a string or with a GQuark corresponding to the string.
The GQuark methods are quicker, since the strings have to be converted to GQuarks anyway.
Data lists are used for associating arbitrary data with GObjects,
using g_object_set_data()
and related functions.
To create a datalist, use g_datalist_init()
.
To add data elements to a datalist use g_datalist_id_set_data()
,
g_datalist_id_set_data_full()
, g_datalist_set_data()
and
g_datalist_set_data_full()
.
To get data elements from a datalist use g_datalist_id_get_data()
and g_datalist_get_data()
.
To iterate over all data elements in a datalist use
g_datalist_foreach()
(not thread-safe).
To remove data elements from a datalist use
g_datalist_id_remove_data()
and g_datalist_remove_data()
.
To remove all data elements from a datalist, use g_datalist_clear()
.
void
g_datalist_init (GData **datalist
);
Resets the datalist to NULL
. It does not free any memory or call
any destroy functions.
#define g_datalist_id_set_data(dl, q, d)
Sets the data corresponding to the given GQuark id. Any previous data with the same key is removed, and its destroy function is called.
void g_datalist_id_set_data_full (GData **datalist
,GQuark key_id
,gpointer data
,GDestroyNotify destroy_func
);
Sets the data corresponding to the given GQuark id, and the function to be called when the element is removed from the datalist. Any previous data with the same key is removed, and its destroy function is called.
datalist |
a datalist. |
|
key_id |
the GQuark to identify the data element. |
|
data |
the data element or |
[allow-none] |
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. If |
gpointer g_datalist_id_get_data (GData **datalist
,GQuark key_id
);
Retrieves the data element corresponding to key_id
.
#define g_datalist_id_remove_data(dl, q)
Removes an element, using its GQuark identifier.
gpointer g_datalist_id_remove_no_notify (GData **datalist
,GQuark key_id
);
Removes an element, without calling its destroy notification function.
#define g_datalist_set_data(dl, k, d)
Sets the data element corresponding to the given string identifier.
dl |
a datalist. |
|
k |
the string to identify the data element. |
|
d |
the data element, or |
[allow-none] |
#define g_datalist_set_data_full(dl, k, d, f)
Sets the data element corresponding to the given string identifier, and the function to be called when the data element is removed.
dl |
a datalist. |
|
k |
the string to identify the data element. |
|
d |
the data element, or |
[allow-none] |
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. If |
gpointer g_datalist_get_data (GData **datalist
,const gchar *key
);
Gets a data element, using its string identifier. This is slower than
g_datalist_id_get_data()
because it compares strings.
#define g_datalist_remove_data(dl, k)
Removes an element using its string identifier. The data element's destroy function is called if it has been set.
#define g_datalist_remove_no_notify(dl, k)
Removes an element, without calling its destroy notifier.
void g_datalist_foreach (GData **datalist
,GDataForeachFunc func
,gpointer user_data
);
Calls the given function for each data element of the datalist. The
function is called with each data element's GQuark id and data,
together with the given user_data
parameter. 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.
void
g_datalist_clear (GData **datalist
);
Frees all the data elements of the datalist. The data elements' destroy functions are called if they have been set.
void g_datalist_set_flags (GData **datalist
,guint flags
);
Turns on flag values for a data list. This function is used to keep a small number of boolean flags in an object with a data list without using any additional space. It is not generally useful except in circumstances where space is very tight. (It is used in the base GObject type, for example.)
datalist |
pointer to the location that holds a list |
|
flags |
the flags to turn on. The values of the flags are
restricted by |
Since 2.8
void g_datalist_unset_flags (GData **datalist
,guint flags
);
Turns off flag values for a data list. See g_datalist_unset_flags()
datalist |
pointer to the location that holds a list |
|
flags |
the flags to turn off. The values of the flags are
restricted by |
Since 2.8
guint
g_datalist_get_flags (GData **datalist
);
Gets flags values packed in together with the datalist.
See g_datalist_set_flags()
.
Since 2.8
typedef struct _GData GData;
The GData struct is an opaque data structure to represent a Keyed Data List. It should only be accessed via the following functions.
#define G_DATALIST_FLAGS_MASK 0x3
A bitmask that restricts the possible flags passed to
g_datalist_set_flags()
. Passing a flags value where
flags & ~G_DATALIST_FLAGS_MASK != 0 is an error.