Keyed Data Lists

Keyed Data Lists — Списки элементов данных которые являются доступными при помощи строки или GQuark идентификатора.

Краткое описание

#include <glib.h> GData; void g_datalist_init (GData **datalist); #define g_datalist_id_set_data (dl, q, d) void g_datalist_id_set_data_full (GData **datalist, GQuark key_id, gpointer data, GDestroyNotify destroy_func); gpointer g_datalist_id_get_data (GData **datalist, GQuark key_id); #define g_datalist_id_remove_data (dl, q) gpointer g_datalist_id_remove_no_notify (GData **datalist, GQuark key_id); #define g_datalist_set_data (dl, k, d) #define g_datalist_set_data_full (dl, k, d, f) #define g_datalist_get_data (dl, k) #define g_datalist_remove_data (dl, k) #define g_datalist_remove_no_notify (dl, k) void g_datalist_foreach (GData **datalist, GDataForeachFunc func, gpointer user_data); void g_datalist_clear (GData **datalist); void g_datalist_set_flags (GData **datalist, guint flags); void g_datalist_unset_flags (GData **datalist, guint flags); guint g_datalist_get_flags (GData **datalist); #define G_DATALIST_FLAGS_MASK

Описание

Списки ключевых данных обеспечивают списки произвольных элементов данных к которым можно обратиться либо с помощью строки, либо с помощью GQuark соответствующим строке.

GQuark метод быстрее, так как строки всё равно конвертируются в GQuarks.

Списки данных используются для связи произвольных данных с GObjects, используя g_object_set_data() и родственные функции.

Для создания списка данных, используйте g_datalist_init().

Для добавления элементов данных в список данных используйте g_datalist_id_set_data(), g_datalist_id_set_data_full(), g_datalist_set_data() и g_datalist_set_data_full().

Для получения элементов данных из списка данных используйте g_datalist_id_get_data() и g_datalist_get_data().

Для итерации через все элементы в списке данных используйте g_datalist_foreach() (not thread-safe).

Для удаления элементов данных из списка данных используйте g_datalist_id_remove_data() и g_datalist_remove_data().

Для удаления всех элементов из списка данных, используйте g_datalist_clear().

Детали

GData

typedef struct _GData GData;

Структура GData - это непрозрачная структура данных представляющая Keyed Data List. доступ к ней должен осуществляться только с помощью следующих функций.

g_datalist_init ()

void g_datalist_init (GData **datalist);

Сбрасывает список данных в NULL. Она не освобождает память и не вызывает функции уничтожения.

datalist : указатель на указатель в списке данных.

g_datalist_id_set_data()

#define g_datalist_id_set_data(dl, q, d)

Устанавливает данные соответствующие указанному GQuark идентификатору. Любые предыдущие данные с тем же ключом - удаляются, и это вызывает функцию уничтожения.

dl : список данных.
q : GQuark для идентификации элемента данных.
d : элемент данных, или NULL для удаления любых предыдущих элементов соответствующих q.

g_datalist_id_set_data_full ()

void g_datalist_id_set_data_full (GData **datalist, GQuark key_id, gpointer data, GDestroyNotify destroy_func);

Устанавливает данные соответствующие указанному GQuark идентификатору, и вызывает функцию когда элемент удаляется из списка данных. Любые предыдущие данные с тем же ключом удаляются и вызывается функция уничтожения.

datalist : список данных.
key_id : GQuark для идентификации элемента данных.
data : элемент данных или NULL для удаления любых предыдущих элементов соответствующих key_id.
destroy_func : функция вызываемая когда удаляется элемент данных. Эта функция вызывается с элементом данных и может использоваться для освобождения любой распределённой памяти для него. Если data это NULL, то destroy_func должен также быть NULL.

g_datalist_id_get_data ()

gpointer g_datalist_id_get_data (GData **datalist, GQuark key_id);

Находит элемент данных соответствующий key_id.

datalist : список данных.
key_id : GQuark идентификатор элемента данных.
Возвращает : элемент данных, или NULL если он не найден.

g_datalist_id_remove_data()

#define g_datalist_id_remove_data(dl, q)

Удаляет элемент, используя его GQuark идентификатор.

dl : список данных.
q : GQuark идентификатор элемента данных.

g_datalist_id_remove_no_notify ()

gpointer g_datalist_id_remove_no_notify (GData **datalist, GQuark key_id);

Удаляет элемент, без вызова функции уничтожения.

datalist : список данных.
key_id : GQuark идентификатор элемента данных.
Возвращает : предыдущие данные key_id, или NULL ели нет.

g_datalist_set_data()

#define g_datalist_set_data(dl, k, d)

Устанавливает элемент данных соответствующий указанному строковому идентификатору.

dl : список данных.
k : строка для идентификации элемента данных.
d : элемент данных, или NULL для удаления любых предыдущих элементов соответствующих k.

g_datalist_set_data_full()

#define g_datalist_set_data_full(dl, k, d, f)

Устанавливает элемент данных соответствующий указанной строке идентификатору, и функцию вызываемую при удалении элемента данных.

dl : список данных.
k : строка для идентификации элемента данных.
d : элемент данных, или NULL для удаления любых предыдущих элементов соответствующих k.
f : Функция вызываемая при удалении элемента данных. Эта функция вызывается с элементом данных и может использоваться для освобождения любой распределённой для него памяти. Если d это NULL, то f должен также быть NULL.

g_datalist_get_data()

#define g_datalist_get_data(dl, k)

Выдаёт элемент данных, используя его строку идентификатор. Это медленнее чем g_datalist_id_get_data() потомучто строка сначала конвертируется в GQuark.

dl : список данных.
k : строка идентификатор элемента данных.
Возвращает : элемент данных, или NULL если он не найден.

g_datalist_remove_data()

#define g_datalist_remove_data(dl, k)

Удаляет элемент используя его строковый идентификатор. Элемент данных уничтожается функцией если она была установлена.

dl : список данных.
k : строка идентификатор элемента данных.

g_datalist_remove_no_notify()

#define g_datalist_remove_no_notify(dl, k)

Удаляет элемент, без вызова уничтожающей функции.

dl : список данных.
k : строка идентификатор элемента данных.

g_datalist_foreach ()

void g_datalist_foreach (GData **datalist, GDataForeachFunc func, gpointer user_data);

Вызывает указанную функцию для каждого элемента данных в списке данных. Функция вызывается на каждым элементом данных с GQuark идентификатором и данными, вместе с параметром user_data. Помните что эта функция потоко-небезопасна. Поэтому если datalist не может быть защищён от любых изменений в течении выполнения этой функции, она не должна вызываться.

datalist : список данных.
func : функция вызываемая для каждого элемента данных.
user_data : пользовательские данные помещаемые в функцию.

g_datalist_clear ()

void g_datalist_clear (GData **datalist);

Освобождает все элементы данных в списке данных. Элементы данных уничтожаются функциями вызываемыми если она была установлена.

datalist : список данных.

g_datalist_set_flags ()

void g_datalist_set_flags (GData **datalist, guint flags);

Включает значение флажка для списка данных. Эта функция используется для хранения небольшого числа логических флажков в объекте со списком данных без использования любого дополнительного пространства. Она в основном бесполезна, кроме ситуаций когда пространство сильно уплотнено. (Она в основном типе GObject, например.)

datalist : указатель на расположение которое содержит список
flags : флажки для включения. Значения флажков ограничены G_DATALIST_FLAGS_MASK (в настоящее время 3; представляя два возможных логических флажка). Значение для flags которое не соответствует маске - ошибика.

Начиная с версии 2.8

g_datalist_unset_flags ()

void g_datalist_unset_flags (GData **datalist, guint flags);

Выключает значения флажка для списка данных. Смотрите g_datalist_unset_flags()

datalist : указатель на расположение которое содержит список
flags : флажки для выключения. Значения флажков ограничены G_DATALIST_FLAGS_MASK (в настоящее время 3: представляя два возможных логических флажка). Значение для flags которое не соответствует маске - ошибка.

Начиная с версии 2.8

g_datalist_get_flags ()

guint g_datalist_get_flags (GData **datalist);

Определяет значения флажков упакованных вместе со списком данных. Смотрите g_datalist_set_flags().

datalist : указатель на расположение которое содержит список
Возвращает : флажки списка данных

Начиная с версии 2.8

G_DATALIST_FLAGS_MASK

#define G_DATALIST_FLAGS_MASK 0x3

Битовая маска которая ограничивает возможные флажки помещаемые в g_datalist_set_flags(). Помещаемые значения флажков где флажки & ~G_DATALIST_FLAGS_MASK != 0 - это ошибка.