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 - это ошибка.

			Справочное описание GLib
Начало \| Описание