GLib – 2.0: Keyed Data Lists and Datasets
Description: Reference for GLib-2.0: Keyed Data Lists and Datasets

#### Keyed Data Lists and Datasets

## Keyed Data Lists

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 `GQuark`s anyway.

Data lists are used for associating arbitrary data with `GObject`s, using `g_object_set_data()` and related functions. The data is stored inside opaque `GData` elements.

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()`, `g_datalist_set_data_full()` and `g_datalist_id_replace_data()`.

To get data elements from a datalist use `g_datalist_id_get_data()`, `g_datalist_get_data()` and `g_datalist_id_dup_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()`, `g_datalist_remove_data()` and `g_datalist_id_remove_multiple()`. To remove elements without destroying them, use `g_datalist_id_remove_no_notify()` and `g_datalist_remove_no_notify()`.

To remove all data elements from a datalist, use `g_datalist_clear()`.

A small number of boolean flags can be stored alongside a datalist, using `g_datalist_set_flags()`, `g_datalist_unset_flags()` and `g_datalist_get_flags()`.

## Datasets

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.

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.

There is no function to create a dataset. It is automatically created as soon as you add elements to it.

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()`.

To get data elements from a dataset use `g_dataset_id_get_data()` and `g_dataset_get_data()`.

To iterate over all data elements in a dataset use `g_dataset_foreach()` (not thread-safe).

To remove data elements from a dataset use `g_dataset_id_remove_data()` and `g_dataset_remove_data()`. To remove data without destroying it, use `g_dataset_id_remove_no_notify()` and `g_dataset_remove_no_notify()`.

To destroy a dataset, use `g_dataset_destroy()`.