Справочное описание GLib |
---|
Версия GLib 2.13.0
Замечания по поводу перевода присылать sergeyvp@gmail.com
Table of Contents
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
ArraysArrays — Массивы произвольных элементов, которые автоматически увеличиваются при добавлении элементов. |
#include <glib.h> GArray; GArray* g_array_new (gboolean zero_terminated, gboolean clear_, guint element_size); GArray* g_array_sized_new (gboolean zero_terminated, gboolean clear_, guint element_size, guint reserved_size); #define g_array_append_val (a,v) GArray* g_array_append_vals (GArray *array, gconstpointer data, guint len); #define g_array_prepend_val (a,v) GArray* g_array_prepend_vals (GArray *array, gconstpointer data, guint len); #define g_array_insert_val (a,i,v) GArray* g_array_insert_vals (GArray *array, guint index_, gconstpointer data, guint len); GArray* g_array_remove_index (GArray *array, guint index_); GArray* g_array_remove_index_fast (GArray *array, guint index_); GArray* g_array_remove_range (GArray *array, guint index_, guint length); void g_array_sort (GArray *array, GCompareFunc compare_func); void g_array_sort_with_data (GArray *array, GCompareDataFunc compare_func, gpointer user_data); #define g_array_index (a,t,i) GArray* g_array_set_size (GArray *array, guint length); gchar* g_array_free (GArray *array, gboolean free_segment);
Массивы подобные стандартным массивам C, за исключением того, что автоматически увеличиваются при добавлении элементов.
Массив элементов может быть любого размера (однако все элементы в пределах одного массива равны) и массив может автоматически очищаться до '0' и завершаться нулём.
Для создания нового массива используйте g_array_new()
.
Для добавления элементов в массив, используйте g_array_append_val()
, g_array_append_vals()
,
g_array_prepend_val()
и g_array_prepend_vals()
.
Для доступа к элементам массива, используйте g_array_index()
.
Для установки размера массива, используйте g_array_set_size()
.
Для освобождения массива, используйте g_array_free()
.
Пример 5. Using a GArray to store gint values
GArray *garray; gint i; /* Мы создаём новый массив для хранения значений gint. Мы не хотим его завершать нулём или очищать до 0. */ garray = g_array_new (FALSE, FALSE, sizeof (gint)); for (i = 0; i < 10000; i++) g_array_append_val (garray, i); for (i = 0; i < 10000; i++) if (g_array_index (garray, gint, i) != i) g_print ("ERROR: got %d instead of %d\n", g_array_index (garray, gint, i), i); g_array_free (garray, TRUE);
GArray* g_array_new (gboolean zero_terminated, gboolean clear_, guint element_size);
Создаёт новый GArray.
GArray* g_array_sized_new (gboolean zero_terminated, gboolean clear_, guint element_size, guint reserved_size);
Создаёт новый GArray с предварительно распределёнными элементами
reserved_size
. Это помогает избежать частых перераспределений,
если вы добавляете много элементов в массив. Однако помните, что размер массива остаётся 0.
zero_terminated : |
TRUE если массив должен иметь в конце дополнительный элемент
с полностью чистыми битами.
|
clear_ : |
TRUE если все биты в массиве должны быть очищены
до 0 при распределении.
|
element_size : |
размер каждого элемента в массиве. |
reserved_size : |
количество предварительно распределённых элементов. |
Возвращает : | новый GArray. |
#define g_array_append_val(a,v)
Добавляет значение в конец массива. Массив будет увеличивать размер автоматически, если необходимо.
g_array_append_val()
это макрос который использует ссылку на значение параметра v
.
Это значит что вы не можете использовать его с литеральными значениями, такими как "27".
Вы должны использовать переменные.
GArray* g_array_append_vals (GArray *array, gconstpointer data, guint len);
Добавляет len
элементов в конец массива.
#define g_array_prepend_val(a,v)
Добавляет значение в начало массива. Массив будет автоматически увеличиваться, если необходимо.
Эта операция медленнее чем g_array_append_val()
так как существующие элементы в массиве будут перемещаться освобождая пространство для нового элемента.
g_array_prepend_val()
это макрос который использует
ссылку на значение параметра v
. Это значит вы не можете использовать его с литеральными значениями,
такими как "27". Вы должны использовать переменные.
GArray* g_array_prepend_vals (GArray *array, gconstpointer data, guint len);
Добавляет len
элементов в начало массива.
Эта операция медленнее чем g_array_append_vals()
,
так как существующие элементы в массиве будут перемещаться освобождая пространство для новых элементов.
#define g_array_insert_val(a,i,v)
Вставляет элемент в массив в указанную позицию.
g_array_insert_val()
это макрос который использует
ссылку на значение параметра v
. Это значит что вы не можете использовать его с литеральными значениями
такими как "27". Вы должны использовать переменные.
GArray* g_array_insert_vals (GArray *array, guint index_, gconstpointer data, guint len);
Вставляет len
элементов в GArray
в указанную позицию.
GArray* g_array_remove_index (GArray *array, guint index_);
Удаляет элемент из указанной позиции в GArray. Следующие элементы перемещаются на одну позицию вниз.
GArray* g_array_remove_index_fast (GArray *array, guint index_);
Удаляет элемент из указанной позиции в GArray.
Оставшиеся элементы в массиве используются для заполнения пространства, поэтому эта функция не сохраняет порядок
GArray. Но она быстрее чем
g_array_remove_index()
.
array : |
GArray .
|
index_ : |
позиция удаляемого элемента. |
Возвращает : | GArray. |
GArray* g_array_remove_range (GArray *array, guint index_, guint length);
Удаляет полученное количество элементов начиная с указанной позиции GArray. Следующие элементы перемещаются заполняя пустоту.
array : |
GArray .
|
index_ : |
позиция первого удаляемого элемента. |
length : |
количество удаляемых элементов. |
Возвращает : | GArray. |
Начиная с версии 2.4
void g_array_sort (GArray *array, GCompareFunc compare_func);
Сортирует GArray используя
compare_func
которая должна быть в стиле функции сравнения qsort()
(возвращает значение меньше нуля если первый arg меньше чем второй arg,
ноль если они равны, больше нуля если первый arg больше чем второй arg).
Если два сравниваемых элемента массива равны, их порядок сортировки в массиве неопределён.
array : |
GArray. |
compare_func : |
функция сравнения. |
void g_array_sort_with_data (GArray *array, GCompareDataFunc compare_func, gpointer user_data);
Похожа на g_array_sort()
,
но функция сравнения получает дополнительный аргумент пользовательских данных.
array : |
GArray. |
compare_func : |
функция сравнения. |
user_data : |
данные помещаемые в compare_func .
|
#define g_array_index(a,t,i)
Возвращает элемент GArray в указанной позиции. Возвращаемое значение приводится к указанному типу.
Пример 6. Getting указатель на element in a GArray
EDayViewEvent *event; /* Возвращает указатель на третий элемент в массиве структур EDayViewEvent. */ event = &g_array_index (events, EDayViewEvent, 3);
GArray* g_array_set_size (GArray *array, guint length);
Устанавливает размер массива, расширяя его если необходимо.
Если массив создаётся с clear_
установленным в
TRUE
, новые элементы устанавливаются в 0.
gchar* g_array_free (GArray *array, gboolean free_segment);
Освобождает память распределённую для GArray.
Если free_segment
это TRUE
она также освобождает блок памяти содержащей элементы.
Поместите FALSE
если вы хотите освободить оболочку GArray, но тем ни менее сохранить для использования основной массив.
Если массив элементов содержит динамически распределённую память, она должна освобождаться первой.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GAsyncQueue; GAsyncQueue* g_async_queue_new (void); GAsyncQueue* g_async_queue_ref (GAsyncQueue *queue); void g_async_queue_unref (GAsyncQueue *queue); void g_async_queue_push (GAsyncQueue *queue, gpointer data); void g_async_queue_push_sorted (GAsyncQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data); gpointer g_async_queue_pop (GAsyncQueue *queue); gpointer g_async_queue_try_pop (GAsyncQueue *queue); gpointer g_async_queue_timed_pop (GAsyncQueue *queue, GTimeVal *end_time); gint g_async_queue_length (GAsyncQueue *queue); void g_async_queue_sort (GAsyncQueue *queue, GCompareDataFunc func, gpointer user_data); void g_async_queue_lock (GAsyncQueue *queue); void g_async_queue_unlock (GAsyncQueue *queue); void g_async_queue_ref_unlocked (GAsyncQueue *queue); void g_async_queue_unref_and_unlock (GAsyncQueue *queue); void g_async_queue_push_unlocked (GAsyncQueue *queue, gpointer data); void g_async_queue_push_sorted_unlocked (GAsyncQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data); gpointer g_async_queue_pop_unlocked (GAsyncQueue *queue); gpointer g_async_queue_try_pop_unlocked (GAsyncQueue *queue); gpointer g_async_queue_timed_pop_unlocked (GAsyncQueue *queue, GTimeVal *end_time); gint g_async_queue_length_unlocked (GAsyncQueue *queue); void g_async_queue_sort_unlocked (GAsyncQueue *queue, GCompareDataFunc func, gpointer user_data);
Часто вам нужна взаимосвязь между разными потоками. В общем более безопасно делать это не с помощью общей памяти, а явно передавать сообщения. Эти сообщения имеют смысл только если они асинхронны для много-поточных приложений, однако, синхронные операции могут также выполняться в тех же потоках.
Асинхронные структуры данных являются исключением из большинства других структур данных GLib, поскольку они могут использоваться одновременно в множестве потоков без явной блокировки и они имеют свой собственный встроенный подсчет ссылок. Так как асинхронные структуры данных будут всегда использоваться как минимум двумя параллельными потоками.
Для использования асинхронной структуры сначала нужно её создать с помощью
g_async_queue_new()
. Вновь созданная структура имеет количество ссылок равное 1.
Каждый раз, когда другой поток создаёт новую ссылку на (то есть указатель на)
структуру, количество её ссылок увеличивается (используется g_async_queue_ref()
).
Также, перед удаление этой ссылки, количество ссылок уменьшается (используется
g_async_queue_unref()
). После этого структура не может больше существовать,
поэтому вы не должны обращаться к ней.
Поток который хочет отправить сообщение в эту структуру просто вызывает
g_async_queue_push()
для помещения сообщения в очередь.
Поток который ожидает сообщение из асинхронной структуры просто вызывает
g_async_queue_pop()
для этой очереди. Если нет доступных сообщений в
указанной очереди, поток засыпает пока не появится сообщение. Сообщение
удаляется из очереди и возвращается. Функции g_async_queue_try_pop()
и
g_async_queue_timed_pop()
могут использоваться только для проверки присутствия
сообщений или ожидания определенное время сообщений соответственно.
Почти для каждой функции существует два варианта, первый блокирует
очередь, а второй не делает этого. Таким образом вы можете удерживать
блокировку очереди (блокировать с помощью href="glib-Asynchronous-Queues.html#g-async-queue-lock">g_async_queue_lock()
и
освобождать с помощью g_async_queue_unlock()
) через множественные
инструкции доступа к очереди. Это может быть необходимо для гарантирования
целостности очереди, но должно использоваться только когда это действительно
необходимо, так как может усложнить вам жизнь при неблагоразумном использовании.
Обычно вы должны использовать только варианты функции блокировки
(то есть без суффикса _unlocked)
typedef struct _GAsyncQueue GAsyncQueue;
Структура GAsyncQueue - это закрытая структура данных, которые представляют асинхронную очередь.
Доступ к этим данным должен осуществляться только с помощью функций g_async_queue_*
.
GAsyncQueue* g_async_queue_new (void);
Создаёт новую асинхронную структуру с начальным количеством ссылок равным 1.
Возвращает : | новая GAsyncQueue. |
GAsyncQueue* g_async_queue_ref (GAsyncQueue *queue);
Увеличивает количество ссылок асинхронной queue
на 1.
Вы не должны удерживать блокировку для вызова этой функции.
queue : |
GAsyncQueue. |
Возвращает : | queue которую помещали (Начиная с версии 2.6)
|
void g_async_queue_unref (GAsyncQueue *queue);
Уменьшает количество ссылок асинхронной queue
на 1. Если количество ссылок дошло до 0,
queue
уничтожается и память распределённая для неё освобождается.
Таким образом вам нельзя использовать queue
впоследствии. Вам не нужно удерживать блокировку
для вызова этой функции.
queue : |
GAsyncQueue. |
void g_async_queue_push (GAsyncQueue *queue, gpointer data);
Помещает data
в queue
. data
должен быть не NULL
.
queue : |
GAsyncQueue. |
data : |
data помещаемые в queue .
|
void g_async_queue_push_sorted (GAsyncQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data);
Вставляет data
в queue
используя func
для определения новой позиции.
Перед использованием функции для вставки нового элемента, queue
должна быть отсортирована.
Эта функция блокирует queue
перед сортировкой и разблокирует после завершения работы.
Для примера func
смотрите g_async_queue_sort()
.
queue : |
GAsyncQueue |
data : |
data помещаемые в queue
|
func : |
GCompareDataFunc используемая для сортировки queue . Помещая в эту функцию два элемента
queue , функция возвращает 0 если они эквивалентны, отрицательное если первый элемент
должен быть выше в queue или положительное значение, если первый элемент должен быть ниже в
queue чем второй элемент.
|
user_data : |
пользовательские данные помещаемые в func .
|
Начиная с версии 2.10
gpointer g_async_queue_pop (GAsyncQueue *queue);
Выталкивает данные из queue
. Эта функция блокируется пока данные доступны.
queue : |
GAsyncQueue. |
Возвращает : | данные из очереди. |
gpointer g_async_queue_try_pop (GAsyncQueue *queue);
Пытается вытолкнуть данные из очереди queue
. Если данные не доступны, возвращает NULL
.
queue : |
GAsyncQueue. |
Возвращает : | данные из очереди или NULL , если нет немедленно доступных данных.
|
gpointer g_async_queue_timed_pop (GAsyncQueue *queue, GTimeVal *end_time);
Выталкивает данные из очереди queue
. Если данные получены перед end_time
, возвращает NULL
.
Для простоты расчёта параметра end_time
можно использовать комбинацию g_get_current_time()
и g_time_val_add()
.
queue : |
GAsyncQueue. |
end_time : |
GTimeVal, определяющая время завершения. |
Возвращает : | данные из очереди или NULL , если данные получены раньше end_time .
|
gint g_async_queue_length (GAsyncQueue *queue);
Возвращает длину очереди, отрицательное значение означает ожидание
потоков, положительное значение означает доступность ввода в
queue
. Фактически эта функция возвращает количество элементов данных
в очереди минус количество ожидающих потоков. Таким образом возвращаемое
значение 0 может означать 'n' входов в очередь и 'n' потоков ожидания.
Это может произойти или из-за блокировки очереди или из-за планирования.
queue : |
GAsyncQueue. |
Возвращает : | длина queue .
|
void g_async_queue_sort (GAsyncQueue *queue, GCompareDataFunc func, gpointer user_data);
Сортирует queue
используя func
.
Эта функция блокирует queue
перед сортировкой и разблокирует после завершения.
Если вам нужно отсортировать список по приоритету, чтобы убедиться что низший приоритет будет сверху очереди, вы должны использовать:
gint32 id1; gint32 id2; id1 = GPOINTER_TO_INT (element1); id2 = GPOINTER_TO_INT (element2); return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
queue : |
GAsyncQueue |
func : |
GCompareDataFunc используемая для сортировки queue . Помещая в эту функцию два элемента
queue , функция возвращает 0 если они эквивалентны, отрицательное если первый элемент
должен быть выше в queue или положительное значение, если первый элемент должен быть ниже в
queue чем второй элемент.
|
user_data : |
пользовательские данные помещаемые в func
|
Начиная с версии 2.10
void g_async_queue_lock (GAsyncQueue *queue);
Блокирует queue
's. После этого вы можете вызвать только g_async_queue_*
вариант функции для этой _unlocked()
queue
. Иначе она зависнет (deadlock).
queue : |
GAsyncQueue. |
void g_async_queue_unlock (GAsyncQueue *queue);
Снимает блокировку queue's.
queue : |
GAsyncQueue. |
void g_async_queue_ref_unlocked (GAsyncQueue *queue);
g_async_queue_ref_unlocked
устарела и не должна использоваться во вновь создаваемом коде.
Увеличивает количество ссылок асинхронной queue
на 1.
Устарела
: Начиная с версии 2.8, подсчёт ссылок сделан атомарным, поэтому
g_async_queue_ref()
может использоваться независимо от блокировки queue
's.
queue : |
GAsyncQueue. |
void g_async_queue_unref_and_unlock (GAsyncQueue *queue);
g_async_queue_unref_and_unlock
устарела и не должна использоваться во вновь создаваемом коде.
Уменьшает количество ссылок асинхронной queue
на 1 и отменяет блокировку.
Эта функция должна вызываться во время удержания блокировки queue
's.
Если количество ссылок достигло 0, queue
будет уничтожена и память
распределённая для неё будет освобождена.
Устарела
: Начиная с версии 2.8, подсчёт ссылок выполняется атомарно, поэтому
g_async_queue_unref()
может использоваться независимо от блокировки queue
's.
queue : |
GAsyncQueue. |
void g_async_queue_push_unlocked (GAsyncQueue *queue, gpointer data);
Помещает data
в queue
. data
должен быть не NULL
. Эта функция должна вызываться в течении
блокировки queue
's.
queue : |
GAsyncQueue. |
data : |
данные для помещения в queue .
|
void g_async_queue_push_sorted_unlocked (GAsyncQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data);
Вставляет data
в queue
используя func
для определения новой позиции.
Перед использованием этой функции для вставки нового элемента queue
должна быть отсортирована.
Эта функция вызывается в течении блокировки queue
's.
В качестве примера func
смотрите g_async_queue_sort()
.
queue : |
GAsyncQueue |
data : |
данные для помещения в queue
|
func : |
GCompareDataFunc используемая для сортировки queue . Помещая в эту функцию два элемента
queue , функция возвращает 0 если они эквивалентны, отрицательное если первый элемент
должен быть выше в queue или положительное значение, если первый элемент должен быть ниже в
queue чем второй элемент.
|
user_data : |
пользовательские данные помещаемые в func .
|
Начиная с версии 2.10
gpointer g_async_queue_pop_unlocked (GAsyncQueue *queue);
Выталкивает данные из queue
. Функция блокируется пока данные доступны.
Должна вызываться во время блокировки queue
's.
queue : |
GAsyncQueue. |
Возвращает : | данные из очереди. |
gpointer g_async_queue_try_pop_unlocked (GAsyncQueue *queue);
Пытается вытолкнуть данные из queue
. Если данные не доступны, возвращается NULL
.
Функция должна вызываться во время блокировки queue
's.
queue : |
GAsyncQueue. |
Возвращает : | данные из очереди или NULL , если нет немедленно доступных данных.
|
gpointer g_async_queue_timed_pop_unlocked (GAsyncQueue *queue, GTimeVal *end_time);
Выталкивает данные из queue
. Если данные получены раньше end_time
,
возвращает NULL
. Эта функция должна вызываться во время блокировки queue
's.
Для простоты расчета end_time
можно использовать комбинацию g_get_current_time()
и g_time_val_add()
.
queue : |
GAsyncQueue. |
end_time : |
GTimeVal, определяющая время завершения. |
Возвращает : | данные из очереди или NULL , если нет данных полученных раньше end_time .
|
gint g_async_queue_length_unlocked (GAsyncQueue *queue);
Возвращает длину очереди, отрицательное значение означает ожидание потоков, положительное значение означает доступность ввода в queue. Фактически эта функция возвращает количество элементов данных в очереди минус количество ожидающих потоков. Таким образом возвращаемое значение 0 может означать 'n' входов в очередь и 'n' потоков ожидания. Это может произойти или из-за блокировки очереди или из-за планирования. Функция должна вызываться во время блокировки очереди.
queue : |
GAsyncQueue. |
Возвращает : | длина очереди queue .
|
void g_async_queue_sort_unlocked (GAsyncQueue *queue, GCompareDataFunc func, gpointer user_data);
Сортирует queue
используя func
.
Эта функция вызывается во время блокировки queue
's.
queue : |
GAsyncQueue |
func : |
GCompareDataFunc используемая для сортировки queue . Помещая в эту функцию два элемента
queue , функция возвращает 0 если они эквивалентны, отрицательное если первый элемент
должен быть выше в queue или положительное значение, если первый элемент должен быть ниже в
queue чем второй элемент.
|
user_data : |
пользовательские данные для func
|
Начиная с версии 2.10
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> gint g_atomic_int_get (volatile gint *atomic); void g_atomic_int_set (volatile gint *atomic, gint newval); void g_atomic_int_add (volatile gint *atomic, gint val); gint g_atomic_int_exchange_and_add (volatile gint *atomic, gint val); gboolean g_atomic_int_compare_and_exchange (volatile gint *atomic, gint oldval, gint newval); gpointer g_atomic_pointer_get (volatile gpointer *atomic); void g_atomic_pointer_set (volatile gpointer *atomic, gpointer newval); gboolean g_atomic_pointer_compare_and_exchange (volatile gpointer *atomic, gpointer oldval, gpointer newval); void g_atomic_int_inc (gint *atomic); gboolean g_atomic_int_dec_and_test (gint *atomic);
Следующие функции могут использоваться для атомарного доступа к целочисленным и указателям. Иначе они реализуются как действующие ассемблерные функции на большинстве платформ и используют медленный переход в аварийный режим (fall-backs). Их использование может иногда уберечь вас от использования расточительной работы GMutex для защиты целочисленных и указателей.
Самое важное использование - это подсчёт ссылок. Используя
g_atomic_int_inc()
и g_atomic_int_dec_and_test()
выполняется очень быстрая операция подсчёта ссылок.
Вы не должны непосредственно читать целочисленные или указатели с одновременным многопоточным
доступом, а использовать вместо этого функции атомарного доступа.
Таким образом, всегда используйте g_atomic_int_get()
и g_atomic_pointer_get()
для чтения извне.
Они обеспечивают необходимый механизм синхронизации как границы памяти для одновременного
обращения к распределённой памяти.
Если вы используете эти функции для чего то кроме простого подсчета ссылок,
вы должны знать реальную реализацию этого. Существует буквально тысячи способов навредить себе.
Поэтому если вы сомневаетесь, используйте GMutex.
Если вы не знаете что такое границы памяти не используйте ничего кроме g_atomic_int_inc()
и
g_atomic_int_dec_and_test()
.
Не безопасно устанавливать целочисленное или указатель простым назначением,
когда к ним параллельно обращаются другие нити (threads) со следующими функциями.
Используйте
g_atomic_int_compare_and_exchange()
или
g_atomic_pointer_compare_and_exchange()
соответственно.
gint g_atomic_int_get (volatile gint *atomic);
Читает значение целочисленного на которое указывает atomic
.
Также действует как граница памяти.
atomic : |
указатель на целочисленное |
Возвращает : | значение *atomic
|
Начиная с версии 2.4
void g_atomic_int_set (volatile gint *atomic, gint newval);
Устанавливает значение целочисленного указанного atomic
.
Также действует как граница памяти.
atomic : |
указатель на целочисленное |
newval : |
новое значение |
Начиная с версии 2.10
void g_atomic_int_add (volatile gint *atomic, gint val);
Атомарно добавляет val
к целочисленному указанному atomic
.
Также действует как граница памяти.
atomic : |
указатель на целочисленное. |
val : |
значение добавляемое к *atomic .
|
Начиная с версии 2.4
gint g_atomic_int_exchange_and_add (volatile gint *atomic, gint val);
Атомарно добавляет val
к целочисленному указанному atomic
. Возвращает значение *atomic
непосредственно перед добавлением.
Также действует как граница памяти.
atomic : |
указатель на целочисленное. |
val : |
значение добавляемое к *atomic .
|
Возвращает : | значение *atomic перед добавлением.
|
Начиная с версии 2.4
gboolean g_atomic_int_compare_and_exchange (volatile gint *atomic, gint oldval, gint newval);
Сравнивает oldval
с целочисленным указанным atomic
и если они равны, атомарно обменивает *atomic
с newval
.
Также действует как граница памяти.
atomic : |
указатель на целочисленное. |
oldval : |
принятое старое значение *atomic .
|
newval : |
новое значение *atomic .
|
Возвращает : |
TRUE , если *atomic был равен oldval . Иначе FALSE .
|
Начиная с версии 2.4
gpointer g_atomic_pointer_get (volatile gpointer *atomic);
Читает значение указателя на который указывает atomic
.
Также действует как граница памяти.
atomic : |
указатель на gpointer. |
Возвращает : | значение добавляемое к *atomic .
|
Начиная с версии 2.4
void g_atomic_pointer_set (volatile gpointer *atomic, gpointer newval);
Устанавливает значение указателя на который указывает
atomic
.
Также действует как граница памяти.
atomic : |
указатель на gpointer |
newval : |
новое значение |
Начиная с версии 2.10
gboolean g_atomic_pointer_compare_and_exchange (volatile gpointer *atomic, gpointer oldval, gpointer newval);
Сравнивает oldval
с указателем на который указывает atomic
и если они равны, атомарно обменивает *atomic
с newval
.
Также действует как граница памяти.
atomic : |
указатель на gpointer. |
oldval : |
принятое старое значение *atomic .
|
newval : |
новое значение *atomic .
|
Возвращает : |
TRUE , если *atomic был равен oldval . Иначе FALSE .
|
Начиная с версии 2.4
void g_atomic_int_inc (gint *atomic);
Атомарно увеличивает указатель на который указывает atomic
на 1.
atomic : |
указатель на целочисленное. |
Начиная с версии 2.4
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Automatic String CompletionAutomatic String Completion — Поддержка для автоматического завершения используя группу целевых строк. |
#include <glib.h> GCompletion; GCompletion* g_completion_new (GCompletionFunc func); gchar* (*GCompletionFunc) (gpointer ); void g_completion_add_items (GCompletion *cmp, GList *items); void g_completion_remove_items (GCompletion *cmp, GList *items); void g_completion_clear_items (GCompletion *cmp); GList* g_completion_complete (GCompletion *cmp, const gchar *prefix, gchar **new_prefix); GList* g_completion_complete_utf8 (GCompletion *cmp, const gchar *prefix, gchar **new_prefix); void g_completion_set_compare (GCompletion *cmp, GCompletionStrncmpFunc strncmp_func); gint (*GCompletionStrncmpFunc) (const gchar *s1, const gchar *s2, gsize n); void g_completion_free (GCompletion *cmp);
GCompletion обеспечивает поддержку автоматического завершения строки используя любую группу целевых строк. Это обычно используется для завершения имён файлов как в обычных оболочках UNIX.
GCompletion создаётся используя
g_completion_new()
.
Целевые элементы добавляются и удаляются с помощью
g_completion_add_items()
,
g_completion_remove_items()
и
g_completion_clear_items()
.
Попытка завершения запрашивается с помощью
g_completion_complete()
или
g_completion_complete_utf8()
.
GCompletion освобождается с помощью g_completion_free()
когда больше не нужна.
Завершающими элементами могут быть просто строки (например имена файлов),
или указателями на произвольные структуры данных. Если используются структуры данных вы должны обеспечить
GCompletionFunc в
g_completion_new()
,
которая находит элементы строк в структуре данных.
Вы можете изменять способ сравнения строк устанавливая разные
GCompletionStrncmpFunc в g_completion_set_compare()
.
typedef struct { GList* items; GCompletionFunc func; gchar* prefix; GList* cache; GCompletionStrncmpFunc strncmp_func; } GCompletion;
Структура данных используемая для автоматического завершения.
GList *items ; |
список целевых элементов (строки или структуры данных). |
GCompletionFunc func ; |
функция вызываемая для получения строки связанной с целевым элементом.
Может быть NULL если целевые элементы являются строками.
|
gchar *prefix ; |
последний префикс помещаемый в
g_completion_complete() или
g_completion_complete_utf8() .
|
GList *cache ; |
список элементов который начинается с prefix .
|
GCompletionStrncmpFunc strncmp_func ; |
функция используемая для сравнения строк.
Используйте
g_completion_set_compare() для изменения этой функции.
|
GCompletion* g_completion_new (GCompletionFunc func);
Создаёт новую GCompletion.
func : |
функция вызываемая для возврата строки представляющей элемент в
GCompletion, или
NULL если строки будут использоваться как элементы
GCompletion.
|
Возвращает : | новая структура GCompletion. |
gchar* (*GCompletionFunc) (gpointer );
Определяет тип функции помещаемой в g_completion_new()
.
Она должна возвращать строку соответствующую полученному целевому элементу.
Используется когда вы используете структуры данных как элементы
GCompletion.
Param1 : |
завершающий элемент. |
Возвращает : | строка соответствующая элементу. |
void g_completion_add_items (GCompletion *cmp, GList *items);
Добавляет элементы в GCompletion.
cmp : |
GCompletion. |
items : |
список добавляемых элементов. |
void g_completion_remove_items (GCompletion *cmp, GList *items);
Удаляет элементы из GCompletion.
cmp : |
GCompletion. |
items : |
элементы для удаления. |
void g_completion_clear_items (GCompletion *cmp);
Удаляет все элементы для удаления GCompletion.
cmp : |
GCompletion. |
GList* g_completion_complete (GCompletion *cmp, const gchar *prefix, gchar **new_prefix);
Пытается завершить строку prefix
используя целевые элементы
GCompletion.
cmp : |
GCompletion. |
prefix : |
строковый префикс, обычно печатается пользователем, который сравнивается с каждым элементом структуры. |
new_prefix : |
если не-NULL ,
возвращает самый длинный префикс который является основой для всех элементов соответствующих
prefix , или NULL
если нет элементов соответствующих prefix .
Эта строка должна освобождаться когда больше не нужна.
|
Возвращает : | список элементов строки которых начинаются с prefix .
Не должно изменяться.
|
GList* g_completion_complete_utf8 (GCompletion *cmp, const gchar *prefix, gchar **new_prefix);
Пытается завершить строку prefix
используя целевые элементы
GCompletion.
В отличие от g_completion_complete()
,
эта функция возвращает самый длинный prefix который является допустимой строкой UTF-8, опуская возможные общие части символа.
Вы должны использовать эту функцию вместо g_completion_complete()
если ваши элементы являются строками UTF-8.
cmp : |
the GCompletion |
prefix : |
строка префикс, обычно используется пользователем, которая сравнивается с каждым элементом |
new_prefix : |
если не-NULL ,
возвращает самый длинный префикс который является основой для всех элементов соответствующих
prefix , или
NULL если нет элементов соответствующих prefix .
Эта строка должна освобождаться когда больше не нужна.
|
Возвращает : | список элементов строки которых начинаются с prefix .
Не должен меняться.
|
Начиная с версии 2.4
void g_completion_set_compare (GCompletion *cmp, GCompletionStrncmpFunc strncmp_func);
Устанавливает функцию используемую для сравнения строк. По умолчанию строки сравниваются функцией strncmp()
.
cmp : |
GCompletion. |
strncmp_func : |
функция сравнения строк. |
gint (*GCompletionStrncmpFunc) (const gchar *s1, const gchar *s2, gsize n);
Определяет тип функции помещаемой в g_completion_set_compare()
.
Используется когда вы используете строки как элементы GCompletion.
s1 : |
строка для сравнения с s2 .
|
s2 : |
строка для сравнения с s1 .
|
n : |
максимальное количество байт для сравнения. |
Возвращает : | целочисленное меньше, равное, или больше нуля если первые найденные
n байт s1 , соответственно меньше, равны,
или больше чем первые n байт s2 .
|
void g_completion_free (GCompletion *cmp);
Освобождает всю память используемую для GCompletion.
cmp : |
GCompletion. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Balanced Binary TreesBalanced Binary Trees — Отсортированная коллекция пар ключ/значение оптимизированная для поиска и пересечения в определённом порядке. |
#include <glib.h> GTree; GTree* g_tree_new (GCompareFunc key_compare_func); GTree* g_tree_new_with_data (GCompareDataFunc key_compare_func, gpointer key_compare_data); GTree* g_tree_new_full (GCompareDataFunc key_compare_func, gpointer key_compare_data, GDestroyNotify key_destroy_func, GDestroyNotify value_destroy_func); void g_tree_insert (GTree *tree, gpointer key, gpointer value); void g_tree_replace (GTree *tree, gpointer key, gpointer value); gint g_tree_nnodes (GTree *tree); gint g_tree_height (GTree *tree); gpointer g_tree_lookup (GTree *tree, gconstpointer key); gboolean g_tree_lookup_extended (GTree *tree, gconstpointer lookup_key, gpointer *orig_key, gpointer *value); void g_tree_foreach (GTree *tree, GTraverseFunc func, gpointer user_data); void g_tree_traverse (GTree *tree, GTraverseFunc traverse_func, GTraverseType traverse_type, gpointer user_data); gboolean (*GTraverseFunc) (gpointer key, gpointer value, gpointer data); enum GTraverseType; gpointer g_tree_search (GTree *tree, GCompareFunc search_func, gconstpointer user_data); gboolean g_tree_remove (GTree *tree, gconstpointer key); gboolean g_tree_steal (GTree *tree, gconstpointer key); void g_tree_destroy (GTree *tree);
Структура GTree и связанные с ней функции обеспечивают отсортированную коллекцию пар ключ/значение оптимизированную для поиска и пересечения в определённом порядке.
Для создания новой GTree используйте
g_tree_new()
.
Для вставки пары ключ/значение в GTree используйте
g_tree_insert()
.
Для поиска значения соответствующего полученному ключу, используйте
g_tree_lookup()
и
g_tree_lookup_extended()
.
Для определения количества ветвей в GTree,
используйте g_tree_nnodes()
.
Для определения высоты GTree,
используйте g_tree_height()
.
Для пересечения GTree,
вызывая функцию для каждой ветви посещаемой при пересечении, используйте
g_tree_foreach()
.
Для удаления пар ключ/значение используйте
g_tree_remove()
.
Для уничтожения GTree, используйте
g_tree_destroy()
.
typedef struct _GTree GTree;
Структура GTree это непрозрачная структура данных представляющая Balanced Binary Tree. Доступ к ней разрешён только функциям перечисленным ниже.
GTree* g_tree_new (GCompareFunc key_compare_func);
Создаёт новую GTree.
key_compare_func : |
функция используемая для упорядочивания ветвей в GTree.
Она должна возвращать значения подобно стандартной функции strcmp() -
0 если два аргумента равны, отрицательное значение если первый аргумент располагается перед вторым,
или положительное значение если первый аргумент располагается после второго.
|
Возвращает : | новая GTree. |
GTree* g_tree_new_with_data (GCompareDataFunc key_compare_func, gpointer key_compare_data);
Создаёт новую GTree
при помощи функции сравнения которая принимает пользовательские данные.
Смотрите g_tree_new()
для подробностей.
key_compare_func : |
функция сравнения в стиле qsort() .
|
key_compare_data : |
данные помещаемые в функцию сравнения. |
Возвращает : | новая GTree. |
GTree* g_tree_new_full (GCompareDataFunc key_compare_func, gpointer key_compare_data, GDestroyNotify key_destroy_func, GDestroyNotify value_destroy_func);
Создаёт новую GTree подобно
g_tree_new()
и позволяет
указать функцию освобождающую память распределяемую для ключей и значений которые получены при удалении элементов из
GTree.
key_compare_func : |
функция сравнения в стиле qsort() .
|
key_compare_data : |
данные помещаемые в функцию сравнения. |
key_destroy_func : |
функция освобождающая память распределённую для ключей используемых при удалении элементов из
GTree или
NULL
если вы не хотите указывать такую функцию.
|
value_destroy_func : |
функция освобождающая память распределённую для значений используемых при удалении элементов из
GTree или
NULL
если вы не хотите использовать такую функцию.
|
Возвращает : | новая GTree. |
void g_tree_insert (GTree *tree, gpointer key, gpointer value);
Вставляет пару ключ/значение в GTree.
Если полученный ключ уже существует в GTree
соответствующее ему значение устанавливается в новое значение. Если вы указали value_destroy_func при создании
GTree, старое значение освободится с помощью этой функции.
Если вы указали key_destroy_func
при создании
GTree, помещаемый ключ освобождается с помощью этой функции.
Дерево автоматически сбалансировано, так как новые пары ключ/значение добавляются таким образом, чтобы расстояние от корня до листьев было минимальным на сколько это возможно.
tree : |
GTree. |
key : |
вставляемый ключ. |
value : |
значение соответствующее ключу. |
void g_tree_replace (GTree *tree, gpointer key, gpointer value);
Вставляет новый ключ и значение в GTree подобно
g_tree_insert()
.
Отличие в том, что если ключ уже существует в GTree,
он переписывается новым ключом. Если вы указали value_destroy_func
при создании
GTree, старое значение освобождается с помощью этой функции.
Если вы указали key_destroy_func
при создании
GTree, старый ключ освобождается при помощи этой функции.
Дерево автоматически сбалансировано, так как новые пары ключ/значение добавляются таким образом, чтобы расстояние между корнем и листьями было минимально возможным.
tree : |
GTree. |
key : |
ключ для вставки. |
value : |
значение соответствующее ключу. |
gint g_tree_height (GTree *tree);
Определяет высоту GTree.
Если GTree не содержит ветвей, высота равна 0. Если GTree содержит только корневую ветвь, высота равна 1. Если корневая ветвь имеет дочернюю, высота равна 2, и т.д..
gpointer g_tree_lookup (GTree *tree, gconstpointer key);
Определяет значение соответствующее полученному ключу. Так как GTree автоматически балансируется при добавлении пар ключ/значение, ключ находится очень быстро.
gboolean g_tree_lookup_extended (GTree *tree, gconstpointer lookup_key, gpointer *orig_key, gpointer *value);
Находит ключ в GTree, возвращает оригинальный ключ,
связанное с ним значение и gboolean которое
TRUE
если ключ был найден.
Это полезно если вам необходимо освободить память связанную с оригинальным ключом,
например перед вызовом g_tree_remove()
.
void g_tree_foreach (GTree *tree, GTraverseFunc func, gpointer user_data);
Вызывает указанную функцию для каждой пары ключ/значение в
GTree.
В функцию помещаются ключ и значение для каждой пары, а также полученный параметр
data
. Дерево пересекается в порядке сортировки.
Дерево не может быть изменено в процессе итерации через него (вы не можете добавлять/удалять элементы). Для удаления всех элементов соответствующих предикате, вам необходимо добавить каждый элемент в список в вашу GTraverseFunc, так как вы проходите по дереву, затем проходите через список и удаляете каждый элемент.
void g_tree_traverse (GTree *tree, GTraverseFunc traverse_func, GTraverseType traverse_type, gpointer user_data);
g_tree_traverse
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде.
Порядок сбалансированного дерева несколько произволен. Если вы просто хотите посетить все ветви в сортировочном порядке,
используйте g_tree_foreach()
.
Если вы действительно нуждаетесь в посещении ветвей в другом порядке, рассмотрите использование
N-ary Tree.
Вызывает полученную функцию для каждой ветви в GTree.
tree : |
GTree. |
traverse_func : |
функция вызываемая для каждой посещаемой ветви. Если эта функция возвращает
TRUE ,
пересечение прекращается.
|
traverse_type : |
порядок в котором посещаются ветви, один из
G_IN_ORDER ,
G_PRE_ORDER и
G_POST_ORDER .
|
user_data : |
пользовательские данные помещаемые в функцию. |
gboolean (*GTraverseFunc) (gpointer key, gpointer value, gpointer data);
Определяет тип функции помещаемой в g_tree_traverse()
.
Она помещает пару ключ/значение для каждой ветви, вместе с параметром user_data
помещаемым
в g_tree_traverse()
.
Если функция вернула TRUE
, пересечение прекращается.
key : |
ключ GTree ветви. |
value : |
значение соответствующее ключу. |
data : |
пользовательские данные помещаемые в g_tree_traverse() .
|
Возвращает : |
TRUE для остановки пересечения.
|
typedef enum { G_IN_ORDER, G_PRE_ORDER, G_POST_ORDER, G_LEVEL_ORDER } GTraverseType;
Определяет тип функции пересечения g_tree_traverse()
,
g_node_traverse()
и g_node_find()
.
G_IN_ORDER |
сначала посещает левую дочернюю ветвь, затем саму ветвь, затем правую дочернюю ветвь. Используйте это если вам нужен вывод сортированный согласно функции сравнения. |
G_PRE_ORDER |
посещает ветвь, затем дочерние. |
G_POST_ORDER |
посещает дочерние ветви, затем саму ветвь. |
G_LEVEL_ORDER |
не реализовано для Balanced Binary Trees. Для N-ary Trees, первой посещается корневая ветвь, затем её дочерние ветви, затем их дочерние, и так далее. Помните что это менее эффективно чем другие порядки. |
gpointer g_tree_search (GTree *tree, GCompareFunc search_func, gconstpointer user_data);
Находит GTree используя
search_func
.
search_func
вызывается с указателем на ключ пары ключ/значение в дереве,
переданном в user_data
. Если search_func
возвращает 0
для пары ключ/значение, то g_tree_search_func()
вернёт значение этой пары.
Если search_func
возвращает -1, то поиск продолжается среди пар ключ/значение,
которые имеют меньший ключ; если search_func
возвращает 1,
поиск продолжается среди пар ключ/значение которые имеют больший ключ.
gboolean g_tree_remove (GTree *tree, gconstpointer key);
Удаляет пару ключ/значение из GTree.
Если GTree создана с использованием
g_tree_new_full()
, ключ и значение
освобождаются используя указанную функцию уничтожения, иначе вы должны убедиться что освободили все динамически распределённые
значения самостоятельно.
Если ключ не существует в GTree, функция ничего не делает.
gboolean g_tree_steal (GTree *tree, gconstpointer key);
Удаляет ключ со связанным с ним значением из GTree без вызова функции уничтожения ключа и значения.
Если ключ не существует в GTree, функция ничего не делает.
void g_tree_destroy (GTree *tree);
Уничтожает GTree.
Если ключ и/или значение распределены динамически, вы должны либо освобождать их первыми либо создать
GTree используя
g_tree_new_full()
.
В последнем случае функция уничтожения указанная вами будет вызвана для всех ключей и значений перед уничтожением
GTree.
tree : |
GTree. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> gsize g_base64_encode_step (const guchar *in, gsize len, gboolean break_lines, gchar *out, gint *state, gint *save); gsize g_base64_encode_close (gboolean break_lines, gchar *out, gint *state, gint *save); gchar* g_base64_encode (const guchar *data, gsize len); gsize g_base64_decode_step (const gchar *in, gsize len, guchar *out, gint *state, guint *save); guchar* g_base64_decode (const gchar *text, gsize *out_len);
Base64 это кодировка которая позволяет кодировать последовательность произвольных байт в последовательность печатных ASCII символов. Для определения Base64, смотрите RFC 1421 или RFC 2045. Base64 в основном используется как кодировка передачи MIME для email.
GLib поддерживает возрастающую кодировку используя g_base64_encode_step()
и
g_base64_encode_close()
. Возрастающее декодирование может быть выполнено с помощью
g_base64_decode_step()
. Для кодировки или декодирования данных в одном направлении, используйте
g_base64_encode()
или g_base64_decode()
.
Поддержка кодировки Base64 была добавлена в GLib 2.12.
gsize g_base64_encode_step (const guchar *in, gsize len, gboolean break_lines, gchar *out, gint *state, gint *save);
Возрастающее кодирование двоичных данных в строковое представление Base-64. Вызывая эту функцию многократно вы можете конвертировать данные в части избегая необходимости иметь полностью закодированные данные в памяти.
Когда все данные конвертированы вы должны вызвать
g_base64_encode_close()
для сброса на диск сохранённого состояния.
Буфер вывода должен быть достаточно большим чтобы вместить все данные которые будут в него записаны.
Из=за способа кодирования base64 вам потребуется по крайней мере:
len
* 4 / 3 + 6 байт.
Если вы включили прерывание строк (line-breaking) вам потребуется как минимум:
len
* 4 / 3 + len
* 4 / (3 * 72) + 7 байт.
break_lines
обычно используются когда данные закодированные в base64-кодировку помещаются в письма (emails).
Это распределяет строки в 72 столбца, вместо помещения всего текста в одну строку,
что позволяет избежать проблем с длинными строками в почтовой системе.
in : |
двоичные данные для кодирования. |
len : |
длина in .
|
break_lines : |
прерываются ли длинные строки |
out : |
указатель на буфер назначения |
state : |
Сохраняемое состояние между этапами, начиная с 0 |
save : |
Сохраняемое состояние между этапами, начиная с 0 |
Возвращает : | Количество записанных байт вывода |
Начиная с версии 2.12
gsize g_base64_encode_close (gboolean break_lines, gchar *out, gint *state, gint *save);
Сбрасывает на диск состояние из последовательных вызовов g_base64_encode_step()
.
break_lines : |
прерываются ли длинные строки |
out : |
указатель на буфер назначения |
state : |
Сохраняемое состояние из g_base64_encode_step()
|
save : |
Сохраняемое состояние из g_base64_encode_step()
|
Возвращает : | Количество записанных байт |
Начиная с версии 2.12
gchar* g_base64_encode (const guchar *data, gsize len);
Кодирует последовательность двоичных данных в текстовое представление Base-64.
data : |
двоичные данные для кодирования. |
len : |
длина data .
|
Возвращает : | вновь распределённая, zero-завершённая строка в кодировке Base-64
представляющая данные data .
|
Начиная с версии 2.12
gsize g_base64_decode_step (const gchar *in, gsize len, guchar *out, gint *state, guint *save);
Возрастающее кодирование последовательности двоичных данных в текстовое представление Base-64. Вызывая эту функцию многократно вы можете конвертировать данные частями избегая необходимость иметь полностью закодированные данные в памяти.
Буфер вывода должен быть достаточно большим чтобы вместить все записываемые в него данные.
Так как base64 кодирует 3 байта в 4 символа вам необходимо по крайней мере:
len
* 3 / 4 bytes.
in : |
двоичный ввод данных |
len : |
максимальная длина данных in для декодирования
|
out : |
буфер вывода |
state : |
Сохраняемое состояние между этапами, начиная с 0 |
save : |
Сохраняемое состояние между этапами, начиная с 0 |
Возвращает : | Количество записанных байт вывода |
Начиная с версии 2.12
guchar* g_base64_decode (const gchar *text, gsize *out_len);
Декодирует последовательность текстовой кодировки Base-64 в двоичные данные
text : |
zero-завершённая строка с текстом в кодировке base64 для декодирования. |
out_len : |
здесь записывается длина декодированных данных. |
Возвращает : | вновь распределённый буфер который содержит двоичные данные представленные text
|
Начиная с версии 2.12
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Основные типыBasic Types — Стандартные типы GLib, определяемые для простоты использования и переносимости. |
#include <glib.h> typedef gboolean; typedef gpointer; typedef gconstpointer; typedef gchar; typedef guchar; typedef gint; typedef guint; typedef gshort; typedef gushort; typedef glong; typedef gulong; typedef gint8; typedef guint8; typedef gint16; typedef guint16; typedef gint32; typedef guint32; #define G_HAVE_GINT64 typedef gint64; typedef guint64; #define G_GINT64_CONSTANT (val) #define G_GUINT64_CONSTANT (val) typedef gfloat; typedef gdouble; typedef gsize; typedef gssize;
GLib определяет большое число основных используемых типов, которые можно разделить на 4 группы:
Новые типы которые не являются частью стандарта C - gboolean, gsize, gssize.
Целочисленные типы которые гарантируют одинаковый размер на разных платформах - gint8, guint8, gint16, guint16, gint32, guint32, gint64, guint64.
Типы которые проще использовать чем их стандартные аналоги C - gpointer, gconstpointer, guchar, guint, gushort, gulong.
Типы которые соответствуют существующим стандартным типам C, но являются более полными - gchar, gint, gshort, glong, gfloat, gdouble.
typedef gint gboolean;
Стандартный логический тип.
Переменные этого типа содержат логическое значение TRUE
или FALSE
.
typedef void* gpointer;
Указывает отсутствие типа. gpointer лучше выглядит и удобней в использовании чем void*.
typedef const void *gconstpointer;
Указывает отсутствие типа константных данных. Указанные данные не должны изменяться.
Это обычно используется в прототипах функций для указания что данные не меняются функцией.
typedef int gint;
Соответствует стандартному типу int. Значение этого типа может быть в диапазоне от G_MININT до G_MAXINT.
typedef unsigned int guint;
Соответствует стандартному типу unsigned int. Значение этого типа может быть в диапазоне от 0 до G_MAXUINT.
typedef short gshort;
Соответствует стандартному типу short. Значение этого типа может быть в диапазоне от G_MINSHORT до G_MAXSHORT.
typedef unsigned short gushort;
Соответствует стандартному типу unsigned short. Значение этого типа может быть в диапазоне от 0 до G_MAXUSHORT.
typedef long glong;
Соответствует стандартному типу long. Значение этого типа может быть в диапазоне от G_MINLONG до G_MAXLONG.
typedef unsigned long gulong;
Соответствует стандартному типу unsigned long. Значение этого типа может быть в диапазоне от 0 до G_MAXULONG.
typedef signed char gint8;
Целочисленное со знаком гарантировано равно 8 битам на всех платформах. Значение этого типа может быть в диапазоне от -128 до 127.
typedef unsigned char guint8;
Целочисленное без знака гарантировано равно 8 битам на всех платформах. Значение этого типа может быть в диапазоне от 0 до 255.
typedef signed short gint16;
Целочисленное со знаком гарантировано равно 16 битам на всех платформах. Значение этого типа может быть в диапазоне от -32,768 до 32,767.
typedef unsigned short guint16;
Целочисленное без знака гарантировано равно 16 битам на всех платформах. Значение этого типа может быть в диапазоне от 0 до 65,535.
typedef signed int gint32;
Целочисленное со знаком гарантировано равно 32 битам на всех платформах. Значение этого типа может быть в диапазоне от -2,147,483,648 до 2,147,483,647.
typedef unsigned int guint32;
Целочисленное без знака гарантировано равно 32 битам на всех платформах. Значение этого типа может быть в диапазоне от 0 до 4,294,967,295.
#define G_HAVE_GINT64 1 /* устаревшее, всегда верно */
G_HAVE_GINT64
устарела и не должна использоваться во вновь создаваемом коде. GLib нуждается в поддержке 64-bit целых начиная с версии 2.0, поэтому
G_HAVE_GINT64
всегда определено.
Этот макрос определяется если 64-битные целочисленные со знаком и без поддерживаются этой платформой.
G_GNUC_EXTENSION typedef signed long long gint64;
Целочисленное со знаком гарантировано равно 64 битам на всех платформах. Значение этого типа может быть в диапазоне от -9,223,372,036,854,775,808 до 9,223,372,036,854,775,807.
G_GNUC_EXTENSION typedef unsigned long long guint64;
Целочисленное без знака гарантировано равно 64 битам на всех платформах. Значение этого типа может быть в диапазоне от 0 до 18,446,744,073,709,551,615.
#define G_GINT64_CONSTANT(val) (G_GNUC_EXTENSION (val##LL))
Этот макрос используется для вставки буквальных 64-bit целочисленных в исходный код.
val : |
буквальное целочисленное значение, например 0x1d636b02300a7aa7U. |
#define G_GUINT64_CONSTANT(val) (G_GNUC_EXTENSION (val##ULL))
Этот макрос используется для вставки буквальных 64-bit целочисленных без знака в исходный код.
val : |
буквальное значение целочисленного, например 0x1d636b02300a7aa7U. |
Начиная с версии 2.10
typedef float gfloat;
Соответствует стандартному типу float. Значение этого типа может быть в диапазоне от -G_MAXFLOAT to G_MAXFLOAT.
typedef double gdouble;
Соответствует стандартному типу double. Значение этого типа может быть в диапазоне от -G_MAXDOUBLE to G_MAXDOUBLE.
typedef unsigned int gsize;
Целочисленное 32-bit без знака, предназначенное представлять размер данных структур.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GBookmarkFile; #define G_BOOKMARK_FILE_ERROR enum GBookmarkFileError; GBookmarkFile* g_bookmark_file_new (void); void g_bookmark_file_free (GBookmarkFile *bookmark); gboolean g_bookmark_file_load_from_file (GBookmarkFile *bookmark, const gchar *filename, GError **error); gboolean g_bookmark_file_load_from_data (GBookmarkFile *bookmark, const gchar *data, gsize length, GError **error); gboolean g_bookmark_file_load_from_data_dirs (GBookmarkFile *bookmark, const gchar *file, gchar **full_path, GError **error); gchar* g_bookmark_file_to_data (GBookmarkFile *bookmark, gsize *length, GError **error); gboolean g_bookmark_file_to_file (GBookmarkFile *bookmark, const gchar *filename, GError **error); gboolean g_bookmark_file_has_item (GBookmarkFile *bookmark, const gchar *uri); gboolean g_bookmark_file_has_group (GBookmarkFile *bookmark, const gchar *uri, const gchar *group, GError **error); gboolean g_bookmark_file_has_application (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, GError **error); gint g_bookmark_file_get_size (GBookmarkFile *bookmark); gchar** g_bookmark_file_get_uris (GBookmarkFile *bookmark, gsize *length); gchar* g_bookmark_file_get_title (GBookmarkFile *bookmark, const gchar *uri, GError **error); gchar* g_bookmark_file_get_description (GBookmarkFile *bookmark, const gchar *uri, GError **error); gchar* g_bookmark_file_get_mime_type (GBookmarkFile *bookmark, const gchar *uri, GError **error); gboolean g_bookmark_file_get_is_private (GBookmarkFile *bookmark, const gchar *uri, GError **error); gboolean g_bookmark_file_get_icon (GBookmarkFile *bookmark, const gchar *uri, gchar **href, gchar **mime_type, GError **error); time_t g_bookmark_file_get_added (GBookmarkFile *bookmark, const gchar *uri, GError **error); time_t g_bookmark_file_get_modified (GBookmarkFile *bookmark, const gchar *uri, GError **error); time_t g_bookmark_file_get_visited (GBookmarkFile *bookmark, const gchar *uri, GError **error); gchar** g_bookmark_file_get_groups (GBookmarkFile *bookmark, const gchar *uri, gsize *length, GError **error); gchar** g_bookmark_file_get_applications (GBookmarkFile *bookmark, const gchar *uri, gsize *length, GError **error); gboolean g_bookmark_file_get_app_info (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, gchar **exec, guint *count, time_t *stamp, GError **error); void g_bookmark_file_set_title (GBookmarkFile *bookmark, const gchar *uri, const gchar *title); void g_bookmark_file_set_description (GBookmarkFile *bookmark, const gchar *uri, const gchar *description); void g_bookmark_file_set_mime_type (GBookmarkFile *bookmark, const gchar *uri, const gchar *mime_type); void g_bookmark_file_set_is_private (GBookmarkFile *bookmark, const gchar *uri, gboolean is_private); void g_bookmark_file_set_icon (GBookmarkFile *bookmark, const gchar *uri, const gchar *href, const gchar *mime_type); void g_bookmark_file_set_added (GBookmarkFile *bookmark, const gchar *uri, time_t added); void g_bookmark_file_set_groups (GBookmarkFile *bookmark, const gchar *uri, const gchar **groups, gsize length); void g_bookmark_file_set_modified (GBookmarkFile *bookmark, const gchar *uri, time_t modified); void g_bookmark_file_set_visited (GBookmarkFile *bookmark, const gchar *uri, time_t visited); gboolean g_bookmark_file_set_app_info (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, const gchar *exec, gint count, time_t stamp, GError **error); void g_bookmark_file_add_group (GBookmarkFile *bookmark, const gchar *uri, const gchar *group); void g_bookmark_file_add_application (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, const gchar *exec); gboolean g_bookmark_file_remove_group (GBookmarkFile *bookmark, const gchar *uri, const gchar *group, GError **error); gboolean g_bookmark_file_remove_application (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, GError **error); gboolean g_bookmark_file_remove_item (GBookmarkFile *bookmark, const gchar *uri, GError **error); gboolean g_bookmark_file_move_item (GBookmarkFile *bookmark, const gchar *old_uri, const gchar *new_uri, GError **error);
GBookmarkFile позволяет вам анализировать, редактировать или создавать файлы содержащие закладки на URI, вместе с некоторыми meta-данными о ресурсе на который указывает URI, например его MIME тип, приложение которое зарегистрировало закладку и значок который должен использоваться для отображения закладки. Данные хранятся согласно Desktop Bookmark Specification.
Синтаксис файлов закладок детально описан в Desktop Bookmark Specification,
здесь приведено краткое описание: файлы закладок используют подкласс спецификации
XML Bookmark Exchange Language, состоят из XML в
правильной кодировке UTF-8, под корневым элементом xbel
;
каждая закладка сохраняется в элементе bookmark
, используя её URI:
относительные пути не могут использоваться в файле закладок. Закладка может иметь заголовок и описание
определённые пользователем, используемые вместо URI.
Под элементом metadata
, с его набором атрибутов owner
в http://freedesktop.org
, хранятся meta-данные о ресурсе указанном URI.
Мета-данные состоят из MIME типа ресурса; приложения которое зарегистрировало закладку;
группы к которой принадлежит закладка; флага видимости, используемом для установки закладки как "private"
для приложений и групп которые имеют регистрацию; URI и MIME тип значка, для изображения закладки внутри GUI.
<?xml version="1.0"?> <!DOCTYPE xbel PUBLIC "+//IDN python.org//DTD XML Bookmark Exchange Language 1.0//EN//XML" "http://www.python.org/topics/xml/dtds/xbel-1.0.dtd"> <xbel version="1.0" xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info" xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks"> <bookmark href="file:///home/ebassi/bookmark-spec/bookmark-spec.xml"> <title>Desktop Bookmarks Spec</title> <info> <metadata owner="http://freedesktop.org"> <mime:mime-type>text/xml</mime:mime-type> <bookmark:applications> <bookmark:application name="GEdit" count="2" exec="gedit <link linkend="u"><literal>u</literal></link>" timestamp="1115726763"/> <bookmark:application name="GViM" count="7" exec="gvim <link linkend="f"><literal>f</literal></link>" timestamp="1115726812"/> </bookmark:applications> <bookmark:groups> <bookmark:group>Editors</bookmark:group> </bookmark:groups> </metadata> </info> </bookmark> </xbel>
Файл закладок может содержать больше одной закладки; к каждой закладке обращаются через её URI.
Важное замечание для файлов закладок в том, что когда вы добавляете закладку вы должны также добавить приложение которое зарегистрировало её,
используя
g_bookmark_file_add_application()
или g_bookmark_file_set_app_info()
.
Если закладка не имеет приложений, то она будет сброшена при записи на диск, используя
g_bookmark_file_to_data()
или
g_bookmark_file_to_file()
.
Анализатор GBookmarkFile добавлен в версии GLib 2.12.
typedef struct _GBookmarkFile GBookmarkFile;
Структура GBookmarkFile содержит только закрытые данные к которым нет прямого доступа.
#define G_BOOKMARK_FILE_ERROR (g_bookmark_file_error_quark ())
Домен ошибки для анализатора файла закладок. Ошибки в этом домене из перечисления GBookmarkFileError. Смотрите GError для информации о доменах ошибки.
typedef enum { G_BOOKMARK_FILE_ERROR_INVALID_URI, G_BOOKMARK_FILE_ERROR_INVALID_VALUE, G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED, G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND, G_BOOKMARK_FILE_ERROR_READ, G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING, G_BOOKMARK_FILE_ERROR_WRITE, G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND } GBookmarkFileError;
Коды ошибок возвращаемые анализатором файла закладок.
GBookmarkFile* g_bookmark_file_new (void);
Создаёт новый пустой объект GBookmarkFile.
Используйте g_bookmark_file_load_from_file()
, g_bookmark_file_load_from_data()
или g_bookmark_file_load_from_data_dirs()
для чтения существующего файла закладок.
Возвращает : | пустой GBookmarkFile |
Начиная с версии 2.12
void g_bookmark_file_free (GBookmarkFile *bookmark);
Освобождает GBookmarkFile.
bookmark : |
GBookmarkFile |
Начиная с версии 2.12
gboolean g_bookmark_file_load_from_file (GBookmarkFile *bookmark, const gchar *filename, GError **error);
Загружает desktop bookmark file в пустую структуру GBookmarkFile.
Если файл не загружен, то устанавливается error
в GFileError
или GBookmarkFileError.
bookmark : |
пустая структура GBookmarkFile |
filename : |
путь к имени файла для загрузки, в кодировке имён файлов GLib |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если desktop bookmark file не загружен
|
Начиная с версии 2.12
gboolean g_bookmark_file_load_from_data (GBookmarkFile *bookmark, const gchar *data, gsize length, GError **error);
Загружает файл закладок из памяти в пустую структуру GBookmarkFile.
Если объект не создан, то устанавливается error
в
GBookmarkFileError.
bookmark : |
пустая структура GBookmarkFile |
data : |
desktop закладки загруженные в память |
length : |
размер data в байтах
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если desktop закладка не загружена.
|
Начиная с версии 2.12
gboolean g_bookmark_file_load_from_data_dirs (GBookmarkFile *bookmark, const gchar *file, gchar **full_path, GError **error);
Эта функция находит desktop bookmark file с именем file
в пути который возвращает
g_get_user_data_dir()
и
g_get_system_data_dirs()
,
загружает в файл bookmark
и возвращает полный путь файла в
full_path
. Если файл не загружен, то error
устанавливается либо в
GFileError, либо в
GBookmarkFileError.
bookmark : |
GBookmarkFile |
file : |
относительный путь имени файла для открытия и анализа |
full_path : |
расположение для возвращаемой строки содержащей полный путь файла,
или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если файл загружен,
иначе FALSE
|
Начиная с версии 2.12
gchar* g_bookmark_file_to_data (GBookmarkFile *bookmark, gsize *length, GError **error);
Эта функция выводит bookmark
как строку.
bookmark : |
GBookmarkFile |
length : |
расположение для длины возвращаемой строки, или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённая строка содержащая GBookmarkFile |
Начиная с версии 2.12
gboolean g_bookmark_file_to_file (GBookmarkFile *bookmark, const gchar *filename, GError **error);
Эта функция выводит bookmark
в файл. Пишущий процесс будет гарантировано атомарным
при внутреннем использовании g_file_set_contents()
.
bookmark : |
GBookmarkFile |
filename : |
путь к файлу для записи |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если файл полностью записан.
|
Начиная с версии 2.12
gboolean g_bookmark_file_has_item (GBookmarkFile *bookmark, const gchar *uri);
Находит имеет ли desktop закладка элемент URI установленный в uri
.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
Возвращает : | TRUE если uri
находится внутри bookmark , иначе
FALSE
|
Начиная с версии 2.12
gboolean g_bookmark_file_has_group (GBookmarkFile *bookmark, const gchar *uri, const gchar *group, GError **error);
Проверяет относится ли group
к списку групп к которым принадлежит закладка для
uri
.
В случае когда URI не найден, возвращает FALSE
и устанавливает error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
group : |
имя группы для поиска |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если group
найдена.
|
Начиная с версии 2.12
gboolean g_bookmark_file_has_application (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, GError **error);
Проверяет имеет ли закладка для uri
внутри bookmark
регистрацию приложения name
.
В случае когда URI не найден, возвращает FALSE
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
name : |
имя приложения |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если приложение
name найдено
|
Начиная с версии 2.12
gint g_bookmark_file_get_size (GBookmarkFile *bookmark);
Определяет количество закладок в bookmark
.
bookmark : |
GBookmarkFile |
Возвращает : | количество закладок |
Начиная с версии 2.12
gchar** g_bookmark_file_get_uris (GBookmarkFile *bookmark, gsize *length);
Возвращает все URIs закладок в файле bookmark
.
Массив возвращаемых URIs будет NULL
-завершённый,
поэтому length
может опционально быть
NULL
.
bookmark : |
GBookmarkFile |
length : |
расположение для количества возвращаемых URIs, или NULL
|
Возвращает : | вновь распределённый NULL -завершённый массив строк.
Используйте g_strfreev() для его освобождения.
|
Начиная с версии 2.12
gchar* g_bookmark_file_get_title (GBookmarkFile *bookmark, const gchar *uri, GError **error);
Возвращает заголовок закладки для uri
.
Если uri
это NULL
,
возвращает заголовок bookmark
.
В случае когда URI не найден, возвращает NULL
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
uri : |
правильный URI или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённая строка или NULL
если определённый URI не найден.
|
Начиная с версии 2.12
gchar* g_bookmark_file_get_description (GBookmarkFile *bookmark, const gchar *uri, GError **error);
Находит описание закладки для uri
.
В случае когда URI не найден, возвращает NULL
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённая строка или NULL
если определённый URI не найден.
|
Начиная с версии 2.12
gchar* g_bookmark_file_get_mime_type (GBookmarkFile *bookmark, const gchar *uri, GError **error);
Находит MIME тип источника на который указывает uri
.
В случае когда URI не найден, возвращает NULL
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
В случае когда MIME тип не найден, возвращает NULL
и устанавливает error
в G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённая строка или NULL
если определённый URI не найден.
|
Начиная с версии 2.12
gboolean g_bookmark_file_get_is_private (GBookmarkFile *bookmark, const gchar *uri, GError **error);
Определяет установлен ли приватный флаг закладки для uri
.
В случае когда URI не найден, возвращает FALSE
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
В случае когда приватный флаг не найден, возвращает FALSE
и
устанавливает error
в G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если приватный флаг установлен,
иначе FALSE .
|
Начиная с версии 2.12
gboolean g_bookmark_file_get_icon (GBookmarkFile *bookmark, const gchar *uri, gchar **href, gchar **mime_type, GError **error);
Определяет значок закладки для uri
.
В случае когда URI не найден, возвращает FALSE
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
href : |
расположение для возвращаемого местонахождения значка или NULL
|
mime_type : |
расположение для возвращаемого MIME типа значка или NULL
|
error : |
расположение для возвращаемого GError
или NULL
|
Возвращает : | TRUE если значок закладки для URI найден.
Вы должны освободить возвращаемые строки.
|
Начиная с версии 2.12
time_t g_bookmark_file_get_added (GBookmarkFile *bookmark, const gchar *uri, GError **error);
Определяет время добавления закладки для uri
в bookmark
В случае когда URI не найден, возвращает -1 и устанавливает error
в
G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | время добавления закладки (timestamp) |
Начиная с версии 2.12
time_t g_bookmark_file_get_modified (GBookmarkFile *bookmark, const gchar *uri, GError **error);
Определяет время последней модификации закладки для uri
.
В случае когда URI не найден, возвращает -1 и устанавливает error
в
G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | Время последней модификации закладки (timestamp) |
Начиная с версии 2.12
time_t g_bookmark_file_get_visited (GBookmarkFile *bookmark, const gchar *uri, GError **error);
Определяет время последнего посещения закладки для uri
was last visited.
В случае когда URI не найден, возвращает -1 и устанавливает error
в
G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | Время последнего посещения (timestamp). |
Начиная с версии 2.12
gchar** g_bookmark_file_get_groups (GBookmarkFile *bookmark, const gchar *uri, gsize *length, GError **error);
Находит имена групп к которым принадлежит закладка для uri
.
В случае когда URI не найден, возвращает NULL
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
Возвращаемый массив является NULL
-завершённым,
поэтому length
может опционально быть NULL
.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
length : |
расположение длины возвращаемой строки, или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённый NULL -завершённый массив имён групп.
Используйте g_strfreev() для его освобождения.
|
Начиная с версии 2.12
gchar** g_bookmark_file_get_applications (GBookmarkFile *bookmark, const gchar *uri, gsize *length, GError **error);
Находит имена приложений которые зарегистрированы закладкой для uri
.
В случае когда URI не найден, возвращает NULL
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
length : |
расположение длины возвращаемого списка, или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённый NULL -завершённый массив строк.
Используйте g_strfreev() для его освобождения.
|
Начиная с версии 2.12
gboolean g_bookmark_file_get_app_info (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, gchar **exec, guint *count, time_t *stamp, GError **error);
Получает регистрационную информацию app_name
закладки для
uri
.
Смотрите g_bookmark_file_set_app_info()
для получения информации о возвращаемых данных.
Строка возвращаемая в app_exec
должна быть освобождена.
В случае когда URI не найден, возвращает FALSE
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
В случае когда нет приложения с именем app_name
зарегистрированного закладкой для
uri
, возвращает FALSE
и устанавливает ошибку в
G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
name : |
имя приложения |
exec : |
расположение для командной строки приложения, или NULL
|
count : |
расположение для возвращаемого количества регистраций,
или NULL
|
stamp : |
расположение для возвращаемого времени последней регистрации,
или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE при успешном выполнении.
|
Начиная с версии 2.12
void g_bookmark_file_set_title (GBookmarkFile *bookmark, const gchar *uri, const gchar *title);
Устанавливает title
как заголовок закладки для uri
внутри
файла закладок bookmark
.
Если uri
это NULL
,
устанавливает заголовок bookmark
.
Если закладка для uri
не найдена, то она создаётся.
bookmark : |
GBookmarkFile |
uri : |
правильный URI или NULL
|
title : |
строка в кодировке UTF-8 |
Начиная с версии 2.12
void g_bookmark_file_set_description (GBookmarkFile *bookmark, const gchar *uri, const gchar *description);
Устанавливает description
как описание закладки для uri
.
Если uri
это NULL
,
устанавливает описание bookmark
.
Если закладка для uri
не найдена, то она создаётся.
bookmark : |
GBookmarkFile |
uri : |
правильный URI или NULL
|
description : |
строка |
Начиная с версии 2.12
void g_bookmark_file_set_mime_type (GBookmarkFile *bookmark, const gchar *uri, const gchar *mime_type);
Устанавливает mime_type
как MIME тип закладки для uri
.
Если закладка для uri
не найдена, то она создаётся.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
mime_type : |
MIME тип |
Начиная с версии 2.12
void g_bookmark_file_set_is_private (GBookmarkFile *bookmark, const gchar *uri, gboolean is_private);
Устанавливает приватный флаг закладки для uri
.
Если закладка для uri
не найдена, то она создаётся.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
is_private : |
TRUE если закладка должна быть помечена как закрытая
|
Начиная с версии 2.12
void g_bookmark_file_set_icon (GBookmarkFile *bookmark, const gchar *uri, const gchar *href, const gchar *mime_type);
Устанавливает значок закладки для uri
. Если href
это
NULL
, сбрасывает установленный в текущий момент значок.
Если нет найденной закладки для uri
, она создаётся.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
href : |
URI значка для закладки, или NULL
|
mime_type : |
MIME тип значка для закладки |
Начиная с версии 2.12
void g_bookmark_file_set_added (GBookmarkFile *bookmark, const gchar *uri, time_t added);
Устанавливает время добавления закладки для uri
в bookmark
.
Если нет найденной закладки для uri
, то она создаётся.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
added : |
временная отметка или -1 для использования текущего времени |
Начиная с версии 2.12
void g_bookmark_file_set_groups (GBookmarkFile *bookmark, const gchar *uri, const gchar **groups, gsize length);
Устанавливает список имён групп для элементов с uri
.
Каждое предварительно установленное имя группы списка удаляется.
Если uri
не найден, то элементы для него создаются.
bookmark : |
GBookmarkFile |
uri : |
URI элемент |
groups : |
массив имён групп, или NULL для удаления всех групп
|
length : |
количество имен групп в groups
|
Начиная с версии 2.12
void g_bookmark_file_set_modified (GBookmarkFile *bookmark, const gchar *uri, time_t modified);
Устанавливает время последнего изменения закладки для uri
.
Если закладка для uri
не найдена, то она создаётся.
Время изменения закладки должно устанавливаться только когда meta-данные были фактически изменены.
Все функции GBookmarkFile которые изменяют закладку
также изменяют время модификации, за исключением
g_bookmark_file_set_visited()
.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
modified : |
временная отметка или -1 для использования текущего времени |
Начиная с версии 2.12
void g_bookmark_file_set_visited (GBookmarkFile *bookmark, const gchar *uri, time_t visited);
Устанавливает время последнего посещения закладки для uri
.
Если закладка для uri
не найдена, то она создаётся.
Время посещения должно устанавливаться только если закладка была задействована,
любое использование командной строки найденное с помощью g_bookmark_file_get_app_info()
или приложение по умолчанию для закладки MIME типа найденное с использованием
g_bookmark_file_get_mime_type()
.
Изменение времени "посещения" не влияет на время "модификации".
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
visited : |
временная метка или -1 для использования текущего времени |
Начиная с версии 2.12
gboolean g_bookmark_file_set_app_info (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, const gchar *exec, gint count, time_t stamp, GError **error);
Устанавливает meta-данные приложения name
в список приложений которые были зарегистрированы закладкой
для uri
внутри bookmark
.
Вы должны редко использовать эту функцию; вместо неё используйте g_bookmark_file_add_application()
и g_bookmark_file_remove_application()
.
name
может быть любой строкой в кодировке UTF-8 используемой для идентификации приложения.
exec
может иметь один из двух модификаторов:
"f
", который будет расшифрован как локальное имя файла полученное из URI закладки;
"u
", который будет расшифрован как закладка URI.
Расшифровка выполняется автоматически когда находится сохранённая командная строка используя функцию
g_bookmark_file_get_app_info()
.
count
это количество регистраций приложения закладкой;
если < 0, текущее количество регистраций будет увеличено на одну,
если 0, приложение с именем name
будет удалено из списка зарегистрированных приложений.
stamp
Unix время последней регистрации; если -1, используется текущее время.
Если вы попытаетесь удалить приложение установив количество его регистраций в ноль, а закладка для
uri
не найдена, то вернётся FALSE
и установится error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND;
точно так же, в случае когда нет приложения с именем name
зарегистрированного закладкой для uri
, то возвращается FALSE
и
устанавливается ошибка в G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.
Иначе, если закладка для uri
не найдена, то она создаётся.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
name : |
имя приложения |
exec : |
командная строка приложения |
count : |
количество выполненных регистраций для приложения |
stamp : |
время последней регистрации для приложения |
error : |
расположение для возвращаемой GError
или NULL
|
Возвращает : | TRUE если meta-данные приложения
полностью изменены.
|
Начиная с версии 2.12
void g_bookmark_file_add_group (GBookmarkFile *bookmark, const gchar *uri, const gchar *group);
Добавляет group
в список групп к которым принадлежит закладка для uri
.
Если закладка для uri
не найдена, то она создаётся.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
group : |
имя добавляемой группы |
Начиная с версии 2.12
void g_bookmark_file_add_application (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, const gchar *exec);
Добавляет приложение с именем name
и exec
в список
приложений, которые зарегистрированы закладкой для uri
, в
bookmark
.
Все закладки внутри GBookmarkFile должны иметь по меньшей мере одно зарегистрированное приложение. Каждое приложение должно иметь имя, командная строка полезна для запуска закладки, количество регистраций закладкой приложения и время последней регистрации приложения этой закладкой.
Если name
это NULL
,
имя приложения будет тем что возвращает функция g_get_application()
;
если exec
это NULL
,
командная строка будет состоять из имени программы которое возвращает g_get_prgname()
и модификатора "u
", который будет расшифрован как URI закладки.
Эта функция автоматически обновляет количество регистраций и timestamping в случае когда приложение с именем
name
уже зарегистрировано закладкой для uri
внутри bookmark
.
Если закладка для uri
не найдена, то она создаётся.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
name : |
имя приложения зарегистрированное закладкой, или
NULL
|
exec : |
командная строка используемая для активации закладки, или NULL
|
Начиная с версии 2.12
gboolean g_bookmark_file_remove_group (GBookmarkFile *bookmark, const gchar *uri, const gchar *group, GError **error);
Удаляет group
из списка групп к которым принадлежит закладка для
uri
.
В случае когда URI не найден, возвращает FALSE
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
В случае когда группа не определена, возвращает FALSE
и
устанавливает error
в G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
group : |
имя группы для удаления |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если group
была полностью удалена.
|
Начиная с версии 2.12
gboolean g_bookmark_file_remove_application (GBookmarkFile *bookmark, const gchar *uri, const gchar *name, GError **error);
Удаляет регистрацию приложения с именем name
из списка приложений которые зарегистрированы
закладкой для uri
внутри bookmark
.
В случае когда URI не найден, возвращает FALSE
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
В случае когда приложение с именем app_name
не зарегистрировано закладкой для
uri
, возвращает FALSE
и устанавливает ошибку в
G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
name : |
имя приложения |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если приложение полностью удалено.
|
Начиная с версии 2.12
gboolean g_bookmark_file_remove_item (GBookmarkFile *bookmark, const gchar *uri, GError **error);
Удаляет закладку для uri
из файла закладок bookmark
.
bookmark : |
GBookmarkFile |
uri : |
правильный URI |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если закладка была полностью удалена.
|
Начиная с версии 2.12
gboolean g_bookmark_file_move_item (GBookmarkFile *bookmark, const gchar *old_uri, const gchar *new_uri, GError **error);
Изменяет URI закладки из параметра old_uri
на new_uri
.
Любые существующие закладки для new_uri
будут переписаны.
Если new_uri
это NULL
,
тогда закладка удаляется.
В случае когда URI не найден, возвращает FALSE
и устанавливает
error
в G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
bookmark : |
GBookmarkFile |
old_uri : |
правильный URI |
new_uri : |
правильный URI, или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если URI полностью изменён
|
Начиная с версии 2.12
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Byte ArraysByte Arrays — Массив байт, который автоматически увеличивается при добавлении элементов. |
#include <glib.h> GByteArray; GByteArray* g_byte_array_new (void); GByteArray* g_byte_array_sized_new (guint reserved_size); GByteArray* g_byte_array_append (GByteArray *array, const guint8 *data, guint len); GByteArray* g_byte_array_prepend (GByteArray *array, const guint8 *data, guint len); GByteArray* g_byte_array_remove_index (GByteArray *array, guint index_); GByteArray* g_byte_array_remove_index_fast (GByteArray *array, guint index_); GByteArray* g_byte_array_remove_range (GByteArray *array, guint index_, guint length); void g_byte_array_sort (GByteArray *array, GCompareFunc compare_func); void g_byte_array_sort_with_data (GByteArray *array, GCompareDataFunc compare_func, gpointer user_data); GByteArray* g_byte_array_set_size (GByteArray *array, guint length); guint8* g_byte_array_free (GByteArray *array, gboolean free_segment);
GByteArray основан на GArray, для обеспечения массива байт который автоматически увеличивается при добавлении элементов.
Для создания нового GByteArray используйте
g_byte_array_new()
.
Для добавления элементов в GByteArray,
используйте g_byte_array_append()
и
g_byte_array_prepend()
.
Для установки размера GByteArray,
используйте g_byte_array_set_size()
.
Для освобождения GByteArray,
используйте g_byte_array_free()
.
Пример 8. Using a GByteArray
GByteArray *gbarray; gint i; gbarray = g_byte_array_new (); for (i = 0; i < 10000; i++) g_byte_array_append (gbarray, (guint8*) "abcd", 4); for (i = 0; i < 10000; i++) { g_assert (gbarray->data[4*i] == 'a'); g_assert (gbarray->data[4*i+1] == 'b'); g_assert (gbarray->data[4*i+2] == 'c'); g_assert (gbarray->data[4*i+3] == 'd'); } g_byte_array_free (gbarray, TRUE);
typedef struct { guint8 *data; guint len; } GByteArray;
Структура GByteArray позволяет доступ к общедоступным полям GByteArray.
guint8 *data ; |
указатель на элемент данных. Данные могут перемещаться когда добавляются элементы в GByteArray. |
guint len ; |
количество элементов в GByteArray. |
GByteArray* g_byte_array_new (void);
Создаёт новый GByteArray.
Возвращает : | новый GByteArray. |
GByteArray* g_byte_array_sized_new (guint reserved_size);
Создаёт новый GByteArray с
reserved_size
предварительно распределённых байт.
Это позволяет избегать частых перераспределений, если вы добавляете много байт в массив.
Однако помните что размер массива остаётся 0.
reserved_size : |
количество предварительно распределённых байт. |
Возвращает : | новый GByteArray. |
GByteArray* g_byte_array_append (GByteArray *array, const guint8 *data, guint len);
Добавляет полученные байты в конец GByteArray. Массив автоматически увеличивает размер, если необходимо.
array : |
GByteArray. |
data : |
байты данных для добавления. |
len : |
количество добавляемых байт. |
Возвращает : | GByteArray. |
GByteArray* g_byte_array_prepend (GByteArray *array, const guint8 *data, guint len);
Добавляет полученные данные в начало GByteArray. Массив будет увеличиваться автоматически, если необходимо.
array : |
GByteArray. |
data : |
байты данных для добавления. |
len : |
количество добавляемых байт. |
Возвращает : | GByteArray. |
GByteArray* g_byte_array_remove_index (GByteArray *array, guint index_);
Удаляет байт с полученным номером из GByteArray. Следующие байты перемещаются вниз на одну позицию.
array : |
GByteArray. |
index_ : |
номер байта для удаления. |
Возвращает : | GByteArray. |
GByteArray* g_byte_array_remove_index_fast (GByteArray *array, guint index_);
Удаляет байт в полученной позиции GByteArray.
Оставшиеся элементы в массиве используются для заполнения пространства, поэтому эта функция не сохраняет порядок
GByteArray. Но она быстрее чем
g_byte_array_remove_index()
.
array : |
GByteArray. |
index_ : |
номер байта для удаления. |
Возвращает : | GByteArray. |
GByteArray* g_byte_array_remove_range (GByteArray *array, guint index_, guint length);
Удаляет полученное количество байт на начиная с указанной позиции GByteArray. Следующие элементы перемещаются закрывая пустоту.
array : |
GByteArray .
|
index_ : |
номер первого байта для удаления. |
length : |
количество байт для удаления. |
Возвращает : | GByteArray. |
Начиная с версии 2.4
void g_byte_array_sort (GByteArray *array, GCompareFunc compare_func);
Сортирует массив байт, используя compare_func
которая должна быть в стиле функции сравнения
qsort()
(возвращать отрицательное значение если первый arg меньше чем второй arg, ноль если они равны,
положительное значение если первый arg больше чем второй arg).
Если два сравниваемых массива элементов равны, их порядок в сортируемом массиве не определён.
array : |
GByteArray. |
compare_func : |
функция сравнения. |
void g_byte_array_sort_with_data (GByteArray *array, GCompareDataFunc compare_func, gpointer user_data);
Похожа на g_byte_array_sort()
,
но функция сравнения принимает дополнительный аргумент пользовательских данных.
array : |
GByteArray. |
compare_func : |
функция сравнения. |
user_data : |
данные помещаемые в compare_func .
|
GByteArray* g_byte_array_set_size (GByteArray *array, guint length);
Устанавливает размер GByteArray, расширяя если необходимо.
array : |
GByteArray. |
length : |
новый размер GByteArray. |
Возвращает : | GByteArray. |
guint8* g_byte_array_free (GByteArray *array, gboolean free_segment);
Освобождает память распределённую для GByteArray.
Если free_segment
это TRUE
, она освобождает фактические байты данных.
array : |
GByteArray. |
free_segment : |
если TRUE фактические байты данных так же освобождаются.
|
Возвращает : | элемент данных если free_segment это
FALSE ,
иначе NULL
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Макроопределения последовательности байтByte Order Macros — портируемый способ преобразования между разными последовательностями байт. |
#include <glib.h> #define G_BYTE_ORDER #define G_LITTLE_ENDIAN #define G_BIG_ENDIAN #define G_PDP_ENDIAN #define g_htonl (val) #define g_htons (val) #define g_ntohl (val) #define g_ntohs (val) #define GINT_FROM_BE (val) #define GINT_FROM_LE (val) #define GINT_TO_BE (val) #define GINT_TO_LE (val) #define GUINT_FROM_BE (val) #define GUINT_FROM_LE (val) #define GUINT_TO_BE (val) #define GUINT_TO_LE (val) #define GLONG_FROM_BE (val) #define GLONG_FROM_LE (val) #define GLONG_TO_BE (val) #define GLONG_TO_LE (val) #define GULONG_FROM_BE (val) #define GULONG_FROM_LE (val) #define GULONG_TO_BE (val) #define GULONG_TO_LE (val) #define GINT16_FROM_BE (val) #define GINT16_FROM_LE (val) #define GINT16_TO_BE (val) #define GINT16_TO_LE (val) #define GUINT16_FROM_BE (val) #define GUINT16_FROM_LE (val) #define GUINT16_TO_BE (val) #define GUINT16_TO_LE (val) #define GINT32_FROM_BE (val) #define GINT32_FROM_LE (val) #define GINT32_TO_BE (val) #define GINT32_TO_LE (val) #define GUINT32_FROM_BE (val) #define GUINT32_FROM_LE (val) #define GUINT32_TO_BE (val) #define GUINT32_TO_LE (val) #define GINT64_FROM_BE (val) #define GINT64_FROM_LE (val) #define GINT64_TO_BE (val) #define GINT64_TO_LE (val) #define GUINT64_FROM_BE (val) #define GUINT64_FROM_LE (val) #define GUINT64_TO_BE (val) #define GUINT64_TO_LE (val) #define GUINT16_SWAP_BE_PDP (val) #define GUINT16_SWAP_LE_BE (val) #define GUINT16_SWAP_LE_PDP (val) #define GUINT32_SWAP_BE_PDP (val) #define GUINT32_SWAP_LE_BE (val) #define GUINT32_SWAP_LE_PDP (val) #define GUINT64_SWAP_LE_BE (val)
Эти макросы обеспечивают переносимый способ определения машинной последовательности байт и преобразование значений между различными последовательностями байт.
Последовательность байт это порядок в котором байты сохраняются для создания больших типов данных таких как значения gint и glong. Машинная последовательность байт это порядок байт используемый на текущей машине.
Некоторые процессоры сохраняют самые важные байты (то есть байты которые содержат большую часть значения) первыми. Они известны как big-endian процессоры.
Другие процессоры (особенно семейство x86) сохраняют самые важные байты последними. Они известны как little-endian процессоры.
В завершение, для полного усложнения, некоторые процессоры сохраняют байты в довольно любопытном порядке известном как PDP-endian. Для 4-байтного слова, 3-ий самый важный байт сохраняется первым, затем 4-ый, затем 1-ый и в конце 2-ой.
Очевидно есть проблемы когда эти разные процессоры взаимодействуют между собой, например через сеть или при использовании бинарных форматов файлов. Вот тут необходимы данные макроопределения. Они обычно используются для конвертации значений в последовательность байт которая подходит для использования при взаимодействии разных процессоров. Интернет использует известный как 'network byte order' (сетевая последовательность байт) стандарт последовательности байт (который фактически является big-endian последовательностью байт).
Помните что макросы преобразования последовательности байт могут вычислять аргументы несколько раз, поэтому вы не должны использовать их с аргументами имеющими побочные эффекты.
#define G_BYTE_ORDER G_LITTLE_ENDIAN
Машинная последовательность байт. Это может быть или G_LITTLE_ENDIAN или G_BIG_ENDIAN (поддержка для G_PDP_ENDIAN может быть добавлена в будущем.)
#define G_LITTLE_ENDIAN 1234
Определяет одну из возможных последовательностей байт. Смотрите G_BYTE_ORDER.
#define G_BIG_ENDIAN 4321
Определяет один из возможных типов последовательности байт. Смотрите G_BYTE_ORDER.
#define G_PDP_ENDIAN 3412 /* неиспользуется, нуждается в определённой проверке PDP */
Определяет один из возможных типов последовательности байт (в настоящее время не используется). Смотрите G_BYTE_ORDER.
#define g_htonl(val)
Конвертирует 32-битное целочисленное значение из машинной в сетевую последовательность байт.
val : |
32-битное целочисленное значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в сетевую последовательность байт.
|
#define g_htons(val)
Конвертирует 16-битное целочисленное значение из машинной в сетевую последовательность байт.
val : |
16-битное целочисленное значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в сетевую последовательность байт.
|
#define g_ntohl(val)
Конвертирует 32-битное целочисленное значение из сетевой в машинную последовательность байт.
val : |
32-битное целочисленное значение в сетевой последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define g_ntohs(val)
Конвертирует 16-битное целочисленное значение из сетевой в машинную последовательность байт.
val : |
16-битное целочисленное значение в сетевой последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GINT_FROM_BE(val) (GINT_TO_BE (val))
Конвертирует gint значение из big-endian в машинную последовательность байт.
val : |
gint значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GINT_FROM_LE(val) (GINT_TO_LE (val))
Конвертирует gint значение из little-endian в машинную последовательность байт.
val : |
gint значение в little-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GINT_TO_BE(val) ((gint) GINT32_TO_BE (val))
Конвертирует gint значение из машинной последовательности байт в big-endian.
val : |
gint значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian последовательностью байт.
|
#define GINT_TO_LE(val) ((gint) GINT32_TO_LE (val))
Конвертирует gint значение из машинной последовательности байт в little-endian.
val : |
gint значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian последовательность байт.
|
#define GUINT_FROM_BE(val) (GUINT_TO_BE (val))
Конвертирует guint значение из big-endian в машинную последовательность байт.
val : |
guint значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GUINT_FROM_LE(val) (GUINT_TO_LE (val))
Конвертирует guint значение из little-endian в машинную последовательность байт.
val : |
guint значение в little-endian последовательностью байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GUINT_TO_BE(val) ((guint) GUINT32_TO_BE (val))
Конвертирует guint значение из машинной последовательности байт в big-endian.
val : |
guint значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian последовательность байт.
|
#define GUINT_TO_LE(val) ((guint) GUINT32_TO_LE (val))
Конвертирует guint значение из машинной последовательности байт в little-endian.
val : |
guint значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian последовательность байт.
|
#define GLONG_FROM_BE(val) (GLONG_TO_BE (val))
Конвертирует glong значение из big-endian to the host последовательность байт.
val : |
glong значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GLONG_FROM_LE(val) (GLONG_TO_LE (val))
Конвертирует glong значение из little-endian в машинную последовательность байт.
val : |
glong значение в little-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GLONG_TO_BE(val) ((glong) GINT32_TO_BE (val))
Конвертирует glong значение из машинной последовательности байт в big-endian.
val : |
glong значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian последовательность байт.
|
#define GLONG_TO_LE(val) ((glong) GINT32_TO_LE (val))
Конвертирует glong значение из машинной последовательности байт в little-endian.
val : |
glong значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian.
|
#define GULONG_FROM_BE(val) (GULONG_TO_BE (val))
Конвертирует gulong значение из big-endian в машинную последовательность байт.
val : |
gulong значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GULONG_FROM_LE(val) (GULONG_TO_LE (val))
Конвертирует gulong значение из little-endian в машинную последовательность байт.
val : |
gulong значение в little-endian последовательность байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GULONG_TO_BE(val) ((gulong) GUINT32_TO_BE (val))
Конвертирует gulong значение из машинной последовательности байт в big-endian.
val : |
gulong значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian.
|
#define GULONG_TO_LE(val) ((gulong) GUINT32_TO_LE (val))
Конвертирует gulong значение из машинной последовательности байт в little-endian.
val : |
gulong значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian.
|
#define GINT16_FROM_BE(val) (GINT16_TO_BE (val))
Конвертирует gint16 значение из big-endian в машинную последовательность байт.
val : |
gint16 значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GINT16_FROM_LE(val) (GINT16_TO_LE (val))
Конвертирует gint16 значение из little-endian в машинную последовательность байт.
val : |
gint16 значение в little-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GINT16_TO_BE(val) ((gint16) GUINT16_SWAP_LE_BE (val))
Конвертирует gint16 значение из машинной последовательности байт в big-endian.
val : |
gint16 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian.
|
#define GINT16_TO_LE(val) ((gint16) (val))
Конвертирует gint16 значение из машинной последовательности байт в little-endian.
val : |
gint16 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian.
|
#define GUINT16_FROM_BE(val) (GUINT16_TO_BE (val))
Конвертирует guint16 значение из big-endian в машинную последовательность байт.
val : |
guint16 значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GUINT16_FROM_LE(val) (GUINT16_TO_LE (val))
Конвертирует guint16 значение из little-endian в машинную последовательность байт.
val : |
guint16 значение в little-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GUINT16_TO_BE(val) (GUINT16_SWAP_LE_BE (val))
Конвертирует guint16 значение из машинной последовательности байт в big-endian.
val : |
guint16 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian.
|
#define GUINT16_TO_LE(val) ((guint16) (val))
Конвертирует guint16 значение из машинной последовательности байт в little-endian.
val : |
guint16 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian.
|
#define GINT32_FROM_BE(val) (GINT32_TO_BE (val))
Конвертирует gint32 значение из big-endian в машинную последовательность байт.
val : |
gint32 значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GINT32_FROM_LE(val) (GINT32_TO_LE (val))
Конвертирует gint32 значение из little-endian в машинную последовательность байт.
val : |
gint32 значение в little-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GINT32_TO_BE(val) ((gint32) GUINT32_SWAP_LE_BE (val))
Конвертирует gint32 значение из машинной последовательности байт в big-endian.
val : |
gint32 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian.
|
#define GINT32_TO_LE(val) ((gint32) (val))
Конвертирует gint32 значение из машинной последовательности байт в little-endian.
val : |
gint32 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian.
|
#define GUINT32_FROM_BE(val) (GUINT32_TO_BE (val))
Конвертирует guint32 значение из big-endian в машинную последовательность байт.
val : |
guint32 значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GUINT32_FROM_LE(val) (GUINT32_TO_LE (val))
Конвертирует guint32 значение из little-endian в машинную последовательность байт.
val : |
guint32 значение в little-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GUINT32_TO_BE(val) (GUINT32_SWAP_LE_BE (val))
Конвертирует guint32 значение из машинной последовательности байт в big-endian.
val : |
guint32 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian.
|
#define GUINT32_TO_LE(val) ((guint32) (val))
Конвертирует guint32 значение из машинной последовательности байт в little-endian.
val : |
guint32 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian.
|
#define GINT64_FROM_BE(val) (GINT64_TO_BE (val))
Конвертирует gint64 значение из big-endian в машинную последовательность байт.
val : |
gint64 значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GINT64_FROM_LE(val) (GINT64_TO_LE (val))
Конвертирует gint64 значение из little-endian в машинную последовательность байт.
val : |
gint64 значение в little-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GINT64_TO_BE(val) ((gint64) GUINT64_SWAP_LE_BE (val))
Конвертирует gint64 значение из машинной последовательности байт в big-endian.
val : |
gint64 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian.
|
#define GINT64_TO_LE(val) ((gint64) (val))
Конвертирует gint64 значение из машинной последовательности байт в little-endian.
val : |
gint64 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian.
|
#define GUINT64_FROM_BE(val) (GUINT64_TO_BE (val))
Конвертирует guint64 значение из big-endian в машинную последовательность байт.
val : |
guint64 значение в big-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GUINT64_FROM_LE(val) (GUINT64_TO_LE (val))
Конвертирует guint64 значение из little-endian в машинную последовательность байт.
val : |
guint64 значение в little-endian последовательности байт. |
Возвращает : |
val конвертированное в машинную последовательность байт.
|
#define GUINT64_TO_BE(val) (GUINT64_SWAP_LE_BE (val))
Конвертирует guint64 значение из машинной последовательности байт в big-endian.
val : |
guint64 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в big-endian.
|
#define GUINT64_TO_LE(val) ((guint64) (val))
Конвертирует guint64 значение из машинной последовательности байт в little-endian.
val : |
guint64 значение в машинной последовательности байт. |
Возвращает : |
val конвертированное в little-endian.
|
#define GUINT16_SWAP_BE_PDP(val) (GUINT16_SWAP_LE_BE (val))
Конвертирует guint16 значение между big-endian и pdp-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.
val : |
guint16 значение в big-endian или pdp-endian последовательности байт. |
Возвращает : |
val конвертированное в противоположную последовательность байт.
|
#define GUINT16_SWAP_LE_BE(val)
Конвертирует guint16 значение между little-endian и big-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.
val : |
guint16 значение в little-endian или big-endian последовательности байт. |
Возвращает : |
val конвертированное в противоположную последовательность байт.
|
#define GUINT16_SWAP_LE_PDP(val) ((guint16) (val))
Конвертирует guint16 значение между little-endian и pdp-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.
val : |
guint16 значение в little-endian или pdp-endian последовательности байт. |
Возвращает : |
val конвертированное в противоположную последовательность байт.
|
#define GUINT32_SWAP_BE_PDP(val)
Конвертирует guint32 значение между big-endian и pdp-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.
val : |
guint32 значение в big-endian или pdp-endian последовательности байт. |
Возвращает : |
val конвертированное в противоположную последовательность байт.
|
#define GUINT32_SWAP_LE_BE(val)
Конвертирует guint32 значение между little-endian и big-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.
val : |
guint32 значение в little-endian или big-endian последовательности байт. |
Возвращает : |
val конвертированное в противоположную последовательность байт.
|
#define GUINT32_SWAP_LE_PDP(val)
Конвертирует guint32 значение между little-endian и pdp-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.
val : |
guint32 значение в little-endian или pdp-endian последовательности байт. |
Возвращает : |
val конвертированное в противоположную последовательность байт.
|
#define GUINT64_SWAP_LE_BE(val)
Конвертирует guint64 значение между little-endian и big-endian последовательностью байт. Преобразование является симметричным, поэтому может использоваться в обоих направлениях.
val : |
guint64 значение в little-endian или big-endian последовательности байт. |
Возвращает : |
val конвертированное в противоположную последовательность байт.
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GCache; GCache* g_cache_new (GCacheNewFunc value_new_func, GCacheDestroyFunc value_destroy_func, GCacheDupFunc key_dup_func, GCacheDestroyFunc key_destroy_func, GHashFunc hash_key_func, GHashFunc hash_value_func, GEqualFunc key_equal_func); gpointer g_cache_insert (GCache *cache, gpointer key); void g_cache_remove (GCache *cache, gconstpointer value); void g_cache_destroy (GCache *cache); void g_cache_key_foreach (GCache *cache, GHFunc func, gpointer user_data); void g_cache_value_foreach (GCache *cache, GHFunc func, gpointer user_data); void (*GCacheDestroyFunc) (gpointer value); gpointer (*GCacheDupFunc) (gpointer value); gpointer (*GCacheNewFunc) (gpointer key);
GCache позволяет объединить комплекс структур данных, в порядке сохранения системных ресурсов.
GTK+ использует кеши для GtkStyles и GdkGCs. Они потребляют много ресурсов, поэтому GCache используется для отслеживания ситуации когда GtkStyle или GdkGC запрашивают уже существующие свойства. Если это выполнено, то используются существующие объекты вместо создания новых.
GCache использует ключи и значения. GCache ключ описывает свойство специального ресурса. GCache значение - это фактический ресурс.
typedef struct _GCache GCache;
Структура GCache является непрозрачной структурой данных содержащей информацию о GCache. Доступ к ней должен осуществляться только через следующие функции.
GCache* g_cache_new (GCacheNewFunc value_new_func, GCacheDestroyFunc value_destroy_func, GCacheDupFunc key_dup_func, GCacheDestroyFunc key_destroy_func, GHashFunc hash_key_func, GHashFunc hash_value_func, GEqualFunc key_equal_func);
Создаёт новую GCache.
value_new_func : |
функция для создания нового объекта данного ключа.
Она вызывается функцией g_cache_insert()
если объект с данным ключом ещё не существует.
|
value_destroy_func : |
функция для уничтожения объекта. Она вызывается с помощью
g_cache_remove()
когда объект больше не нужен (то есть количество его ссылок сброшено в 0).
|
key_dup_func : |
функция для копирования ключа. Она вызывается функцией
g_cache_insert()
если ключ ещё не существует в GCache.
|
key_destroy_func : |
функция для уничтожения ключа. Она вызывается функцией
g_cache_remove()
когда объект больше не нужен (то есть количество его ссылок сброшено в 0).
|
hash_key_func : |
функция создаёт хеш значение из ключа. |
hash_value_func : |
функция создаёт хеш значение из значения. |
key_equal_func : |
функция для сравнения двух ключей. Она должна вернуть TRUE
если два ключа равны.
|
Возвращает : | новая GCache. |
gpointer g_cache_insert (GCache *cache, gpointer key);
Определяет значение соответствующее полученному ключу, создаёт если необходимо.
Она сначала проверяет существует ли значение в GCache,
используя key_equal_func
функцию помещённую в
g_cache_new()
.
Если существует, возвращает это значение и увеличивает количество ссылок на одну.
Если значение не существует в текущий момент, оно создаётся вызовом value_new_func
.
Ключ дублируется вызовом key_dup_func
и дубликат ключа и значения вставляется в
GCache.
void g_cache_remove (GCache *cache, gconstpointer value);
Уменьшает количество ссылок на указанное значение.
Если сброшено в 0, то значение и соответствующий ключ уничтожаются,
используя value_destroy_func
и key_destroy_func
помещённые в g_cache_new()
.
cache : |
GCache. |
value : |
значение для удаления. |
void g_cache_destroy (GCache *cache);
Освобождает память распределённую для GCache.
Помните что она не уничтожает ключи и значения которые содержит GCache.
cache : |
GCache. |
void g_cache_key_foreach (GCache *cache, GHFunc func, gpointer user_data);
Вызывает указанную функцию для каждого ключа в GCache.
func
принимает три параметра, значение и ключ кеш элемента и
user_data
. Порядок значение и ключ отличается от порядка в котором
g_hash_table_foreach()
проходит пары ключ/значение
в callback-функцию!
void g_cache_value_foreach (GCache *cache, GHFunc func, gpointer user_data);
g_cache_value_foreach
устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде.
Благоразумней поместить указатели для внутренних структур данных в func
;
используя g_cache_key_foreach()
Вызывает указанную функцию для каждого значения в GCache.
void (*GCacheDestroyFunc) (gpointer value);
Определяет тип value_destroy_func
и key_destroy_func
функций
помещаемых в g_cache_new()
.
В функции помещаются указатели на GCache ключ или GCache значение и она должна освободить любую память и другие ресурсы связанные с ними.
value : |
GCache значение для уничтожения. |
gpointer (*GCacheDupFunc) (gpointer value);
Определяет тип key_dup_func
функции помещаемой в
g_cache_new()
.
В функцию помещается ключ (не значение, поскольку подразумевается образец)
и она должна вернуть копию ключа.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Character Set ConversionCharacter Set Conversion — конвертирование строк между разными наборами символов используя |
#include <glib.h> gchar* g_convert (const gchar *str, gssize len, const gchar *to_codeset, const gchar *from_codeset, gsize *bytes_read, gsize *bytes_written, GError **error); gchar* g_convert_with_fallback (const gchar *str, gssize len, const gchar *to_codeset, const gchar *from_codeset, gchar *fallback, gsize *bytes_read, gsize *bytes_written, GError **error); GIConv; gchar* g_convert_with_iconv (const gchar *str, gssize len, GIConv converter, gsize *bytes_read, gsize *bytes_written, GError **error); #define G_CONVERT_ERROR GIConv g_iconv_open (const gchar *to_codeset, const gchar *from_codeset); size_t g_iconv (GIConv converter, gchar **inbuf, gsize *inbytes_left, gchar **outbuf, gsize *outbytes_left); gint g_iconv_close (GIConv converter); gchar* g_locale_to_utf8 (const gchar *opsysstring, gssize len, gsize *bytes_read, gsize *bytes_written, GError **error); gchar* g_filename_to_utf8 (const gchar *opsysstring, gssize len, gsize *bytes_read, gsize *bytes_written, GError **error); gchar* g_filename_from_utf8 (const gchar *utf8string, gssize len, gsize *bytes_read, gsize *bytes_written, GError **error); gchar* g_filename_from_uri (const gchar *uri, gchar **hostname, GError **error); gchar* g_filename_to_uri (const gchar *filename, const gchar *hostname, GError **error); gboolean g_get_filename_charsets (G_CONST_RETURN gchar ***charsets); gchar* g_filename_display_name (const gchar *filename); gchar* g_filename_display_basename (const gchar *filename); gchar** g_uri_list_extract_uris (const gchar *uri_list); gchar* g_locale_from_utf8 (const gchar *utf8string, gssize len, gsize *bytes_read, gsize *bytes_written, GError **error); enum GConvertError; gboolean g_get_charset (G_CONST_RETURN char **charset);
Исторически, Unix не имел определённой кодировки для имен файла:
имя файла допустимо пока в нём нет разделителей пути ("/").
Однако, отображение имён файла может требовать преобразования:
из набора символа в котором оно создавалось, в набор символов
с которым оперирует приложение. Рассмотрим Испанское имя файла
"Presentación.sxi
". Если
приложение которое создавало его использует ISO-8859-1 для его кодировки,
то фактическое имя файла на диске должно выглядеть так:
Character: P r e s e n t a c i ó n . s x i Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
Однако, если приложение использует UTF-8, фактическое имя файла на диске будет выглядеть так:
Character: P r e s e n t a c i ó n . s x i Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
Glib использует UTF-8 для строк, и GUI toolkits такой как GTK+
который использует Glib делает тоже самое. Если вы получили имя файла из
файловой системы, например, из
readdir(3)
или из
,
и желаете отобразить имя файла пользователю, вы
будете должны конвертировать его в UTF-8.
Противоположный случай когда пользователь печатает имя файла и хочет его сохранить:
инструментарий (toolkit) выдаст вам что строка в кодировке UTF-8,
и вам необходимо конвертировать её в набор символов используемый файловой системой
перед тем как вы сможете создать файл с помощью g_dir_read_name()
open(2)
или fopen(3)
.
По умолчанию, Glib предполагает что имена файлов на диске находятся в кодировке UTF-8.
Это правильное предположение для файловых систем которые были созданы относительно недавно:
большинство приложений используют UTF-8 кодировку для их строк, а так же для имён файлов которые
они создают. Однако, более старые файловые системы могут по прежнему создавать имена файлов
в "старых" кодировках, таких как ISO-8859-1. В этом случае, по причинам совместимости, вы можете
инструктировать Glib использовать эту специальную кодировки для имен файлов а не UTF-8.
Вы можете выполнить это определив кодировку для имён файлов в переменной окружения
G_FILENAME_ENCODING
.
Например, если ваша инсталяция использует ISO-8859-1 для имен файлов, вы можете поместить следующее в свой
~/.profile
:
export G_FILENAME_ENCODING=ISO-8859-1
Glib обеспечивает функции
и g_filename_to_utf8()
для выполнения необходимых преобразований. Эти функции конвертируют имена файлов из кодировки определённой в
g_filename_from_utf8()
G_FILENAME_ENCODING
в кодировку UTF-8 и наоборот.
Схема 1, “Конвертация между кодировками имён файлов” иллюстрирует как эти функции используются
для конвертации между UTF-8 и кодировкой имён файлов в файловой системе.
Эта секция суммирует детали описанные выше. Вы можете использовать это как контрольный список необходимых вещей выполняемых для того чтобы удостоверится что ваше приложение выполняет перекодировку имён файлов корректно.
Если вы получаете имя файла из файловой системы с помощью функций
таких как readdir(3)
или
,
вы не должны выполнять никаких конвертаций для помещения этого имени файла
в функции такие как gtk_file_chooser_get_filename()
open(2)
,
rename(2)
, или
fopen(3)
— изначальные имена файлов которые понимает файловая система.
Если вам нужно отобразить имя файла, конвертируйте его в UTF-8 перед использованием
.
Если конвертация не удалась, отображается строка как
"g_filename_to_utf8()
Unknown file name
".
Не конвертируйте эту
строку обратно в кодировку используемую для имён файла
если вы хотите поместить её в файловую систему;
используйте оригинальное имя файла вместо этого.
Например, окно документа в текстовом процессоре
может отобразить "Unknown file name" в своём заголовке, но при этом
всё ещё позволяет пользователю сохранить файл, так как это сохранит
исходное имя внутренне. Это может произойти если пользователь
не имеет установленной переменной окружения G_FILENAME_ENCODING
даже если у него есть файлы имена которых не закодированы в UTF-8.
Если ваш пользовательский интерфейс позволяет пользователю печатать имя файла
для сохранения или переименования, конвертируйте его в кодировку используемую для имен файлов файловой системы
используя
.
Поместите конвертированное имя файла в функции такие как
g_filename_from_utf8()
fopen(3)
. Если конверсия неудалась,
у пользователя запрашивается другое имя файла. Это может произойти
если пользователь печатает Японскими символами когда
G_FILENAME_ENCODING
установлена в
ISO-8859-1
, например.
gchar* g_convert (const gchar *str, gssize len, const gchar *to_codeset, const gchar *from_codeset, gsize *bytes_read, gsize *bytes_written, GError **error);
Конвертирует строку из одного символьного набора в другой.
Помните что вы должны использовать g_iconv()
для поточных конвертаций[2].
str : |
строка для конвертации |
len : |
длина строки, или -1 если строка это nul-завершённый[1]. |
to_codeset : |
имя набора символов в который конвертируется str
|
from_codeset : |
набор символов str .
|
bytes_read : |
Размещение для хранения количества байт во входной строке которые были успешно конвертированы,
или NULL .
Даже если конвертация полностью удалась, это значение может быть меньше чем
len если были частичные символы в конце ввода.
Если произошла ошибка
G_CONVERT_ERROR_ILLEGAL_SEQUENCE, значение хранит смещение
байт после последней допустимой последовательности ввода.
|
bytes_written : |
количество байт сохраняемое в буфере вывода (не включая завершающий nul). |
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Любая из ошибок в
GConvertError может произойти.
|
Возвращает : | Если конвертация выполнена, вновь распределённую nul-завершённую строку, которая должна быть освобождена
g_free() .
Иначе устанавливается NULL
и error .
|
gchar* g_convert_with_fallback (const gchar *str, gssize len, const gchar *to_codeset, const gchar *from_codeset, gchar *fallback, gsize *bytes_read, gsize *bytes_written, GError **error);
Конвертирует строку из одного набора символов в другой, возможно включая
последовательности перехода в аварийный режим для символов не подходящих для вывода.
Помните что это не гарантирует что спецификация для последовательности аварийного режима
в fallback
будет учтена. Некоторые системы могут выполнять
приблизительную конвертацию из from_codeset
в to_codeset
в их iconv()
функциях,
в этом случае GLib будет просто возвращать эту приблизительную конвертацию.
Помните что вы должны использовать g_iconv()
для конвертации строк[2].
str : |
строка для конвертации |
len : |
длина строки, или -1 если строка это nul-terminated[1]. |
to_codeset : |
имя набора символов в который конвертируется строка str
|
from_codeset : |
набор символов str .
|
fallback : |
UTF-8 строка для использования вместо символа не представленного в целевой кодировке.
(Строка должна быть доступна для представления в целевой кодировке).
Если NULL , символы не в целевой кодировке
будут представлены как Unicode escapes \uxxxx или \Uxxxxyyyy.
|
bytes_read : |
Расположение для хранения количества байт во входной строке которые были успешно конвертированы,
или NULL .
Даже если конвертация была полностью выполнена, это значение может быть
меньше чем len если есть частичные символы завершающие ввод.
|
bytes_written : |
количество байт сохранённых в буфер вывода (не включая завершающий nul). |
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Любые ошибки в GConvertError могут произойти.
|
Возвращает : | Если конвертация была полностью выполнена, вновь распределёная nul-завершённая строка, которая может быть освобождена с помощью
g_free() .
Иначе NULL
и error будут установлены.
|
typedef struct _GIConv GIConv;
GIConv структура оболочка
дескриптора конвертации. Она содержит закрытые данные и
доступ к ней должен осуществляться с помощью функций описанных ниже.
iconv()
gchar* g_convert_with_iconv (const gchar *str, gssize len, GIConv converter, gsize *bytes_read, gsize *bytes_written, GError **error);
Конвертирует строку из одного набора символов в другой.
Помните что вы должны использовать g_iconv()
для поточных конвертаций[2].
str : |
строка для конвертации |
len : |
длина строки, или -1 если строка это nul-terminated[1]. |
converter : |
дескриптор конвертации из g_iconv_open()
|
bytes_read : |
размещение для хранения количества байт во входной строке
которые были успешно конвертированы, или NULL .
Даже если конвертация полностью выполнена, это значение может быть меньше
чем len , если были частичные символы в конце ввода.
Если произошла ошибка
G_CONVERT_ERROR_ILLEGAL_SEQUENCE, будет сохранено значение
смещения байт после последней допустимой последовательности ввода.
|
bytes_written : |
количество байт сохраняемых в буфере вывода (не включая завершающий nul). |
error : |
размещение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут произойти любые ошибки указанные в
GConvertError.
|
Возвращает : | если конвертация полностью выполнена, вновь распределённую nul-завершённую строку,
которая может быть освобождена
g_free() . Иначе
NULL и error будут установлены.
|
#define G_CONVERT_ERROR g_convert_error_quark()
Домен ошибки (Error domain) для конвертации набора символов. Ошибки в этом домене будут из перечисления GConvertError. Смотрите GError для детальной информации об ошибках.
GIConv g_iconv_open (const gchar *to_codeset, const gchar *from_codeset);
То же самое что и стандартная подпрограмма UNIX iconv_open()
,
но может быть реализована через libiconv на разновидностях UNIX где имеется недостаток в родной реализации.
GLib обеспечивает g_convert()
и g_locale_to_utf8()
которые вероятно являются более удобными чем исходные оболочки iconv.
to_codeset : |
определяет устанавливаемую кодировку |
from_codeset : |
из какой кодировки перекодируется |
Возвращает : | "дескриптор конвертора", или (GIConv)-1 если открываемый конвертер недоступен. |
size_t g_iconv (GIConv converter, gchar **inbuf, gsize *inbytes_left, gchar **outbuf, gsize *outbytes_left);
Тоже самое как стандартная подпрограмма UNIX iconv()
,
но может быть реализована через libiconv на разновидностях UNIX в которых нет родной реализации.
GLib обеспечивает g_convert()
и g_locale_to_utf8()
которые намного удобнее чем исходные оболочки iconv.
converter : |
дескриптор конвертации из g_iconv_open()
|
inbuf : |
байты для конвертации |
inbytes_left : |
входной параметр, байты остаются для конвертации в inbuf
|
outbuf : |
конвертирует вывод байт |
outbytes_left : |
параметр ввода-вывода, байты доступные для заполнения в outbuf
|
Возвращает : | подсчёт необратимый преобразований, или -1 при возникновении ошибки error |
gint g_iconv_close (GIConv converter);
Тоже самое что стандартная подпрограмма UNIX iconv_close()
,
но может быть реализована через libiconv на разновидностях UNIX где нет родной реализации.
Должна вызываться для очистки дескриптора конвертации из g_iconv_open()
когда вы выполняете конвертационные действия.
GLib обеспечивает g_convert()
и g_locale_to_utf8()
которые намного удобнее чем исходные оболочки iconv.
converter : |
дескриптор конвертации из g_iconv_open()
|
Возвращает : | -1 при ошибке, 0 при удачном выполнении |
gchar* g_locale_to_utf8 (const gchar *opsysstring, gssize len, gsize *bytes_read, gsize *bytes_written, GError **error);
Конвертирует строку которая находится в кодировке используемой для строк C runtime (обычно тоже самое что используется операционной системой) в текущей локали в строку UTF-8.
opsysstring : |
строка в кодировке текущей локали. В Windows это означает system codepage. |
len : |
длина строки, или -1 если строка это завершающий ноль (nul-terminated)[1]. |
bytes_read : |
размещение для хранения количества байт во входной строке когда конвертация полностью выполнена,
или NULL .
Даже если конвертация выполнена, этот параметр может быть меньше чем
len если есть части символов в конце ввода.
Если произошла ошибка
G_CONVERT_ERROR_ILLEGAL_SEQUENCE, будет сохранено значение
смещения байт после последней допустимой цепочки ввода.
|
bytes_written : |
количество байт сохранённых в буфере вывода (не включая завершающий nul). |
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут произойти любые ошибки в
GConvertError.
|
Возвращает : | Конвертируемая строка, или NULL при ошибке.
|
gchar* g_filename_to_utf8 (const gchar *opsysstring, gssize len, gsize *bytes_read, gsize *bytes_written, GError **error);
Конвертирует строку которая в кодировке используемой GLib для имён файлов в строку UTF-8. Помните что в Windows GLib использует UTF-8 для имён файлов.
opsysstring : |
строка в кодировке для имён файлов |
len : |
длина строки, или -1 если строка это завершающий ноль (nul-terminated)[1]. |
bytes_read : |
расположение для хранения количества байт во входной строке когда конвертация полностью выполнена,
или NULL .
Даже если конвертация удалась, это значение может быть меньше чем
len если есть части символов в конце ввода.
Если произошла ошибка
G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
будет сохранено смещение байт после последней допустимой цепочки ввода.
|
bytes_written : |
количество байт сохранённых в буфере вывода (не включая завершающий ноль). |
error : |
размещение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут произойти любые ошибки в GConvertError.
|
Возвращает : | Конвертированная строка, или NULL при ошибке.
|
gchar* g_filename_from_utf8 (const gchar *utf8string, gssize len, gsize *bytes_read, gsize *bytes_written, GError **error);
Конвертирует строку из UTF-8 в кодировку GLib используемую для имен файлов. Помните что в Windows GLib использует UTF-8 для имён файлов.
utf8string : |
строка в кодировке UTF-8. |
len : |
длина строки, или -1 если строка это завершающий ноль (nul-terminated). |
bytes_read : |
расположение для хранения количества байт во входной строке при удачном выполнении конвертации,
или NULL .
Даже если конвертация выполнена, это значение может быть меньше чем
len если есть части символов в конце ввода.
Если произошла ошибка
G_CONVERT_ERROR_ILLEGAL_SEQUENCE, сохраняется значение
смещения байт после последней допустимой цепочки ввода.
|
bytes_written : |
количество байт сохранённых в буфере вывода (не включая завершающий ноль). |
error : |
размещение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут произойти любые ошибки в
GConvertError.
|
Возвращает : | Конвертируемая строка, или NULL при ошибке.
|
gchar* g_filename_from_uri (const gchar *uri, gchar **hostname, GError **error);
Конвертирует ASCII-кодировку URI в локальное имя файла в кодировке используемой для имён файлов.
uri : |
uri описывающий имя файла (escaped, encoded in ASCII). |
hostname : |
расположение для хранения имени узла (hostname) для URI, или
NULL .
Если нет имени узла (hostname) в URI, то в этом расположении сохраняется
NULL .
|
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут происходить любые ошибки в GConvertError.
|
Возвращает : | результат в виде вновь распределённой строки содержащей имя файла,
или NULL при ошибке.
|
gchar* g_filename_to_uri (const gchar *filename, const gchar *hostname, GError **error);
Конвертирует абсолютное имя файла в управляющие символы ASCII-кодировки URI, с компонентом пути упоминаемым далее в Разделе 3.3. RFC 2396.
filename : |
абсолютное имя файла определённое в GLib кодировке имён файлов, которое является дисковыми байтами имени файла в Unix, и UTF-8 в Windows |
hostname : |
Имя узла в кодировке UTF-8, или NULL если нет.
|
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут происходить любые ошибки в GConvertError.
|
Возвращает : | вновь распределённая строка содержащая результат URI,
или NULL при ошибке.
|
gboolean g_get_filename_charsets (G_CONST_RETURN gchar ***charsets);
Определяет привилегированные наборы символов используемые для имён файлов.
Первый набор символов из charsets
это кодировка имени файла,
последующие наборы символов используются когда происходят попытки сгенерировать отображаемое представление имени файла,
смотрите g_filename_display_name()
.
В Unix, набор символов определяются с помощью переменных окружения G_FILENAME_ENCODING
и
G_BROKEN_FILENAMES
. В Windows, набор символов используемый в GLib API всегда UTF-8,
а переменные окружения не имеют никакого эффекта.
G_FILENAME_ENCODING
может быть установлен для разделённого запятыми списка
набора символов имён. Специальная лексема "locale
" применяется
для обозначения набора символов для текущей локали. Если G_FILENAME_ENCODING
не установлена, но установлена G_BROKEN_FILENAMES
, набор символов текущей
локали применяется как кодировка имени файла. Если переменные окружения не установлены совсем,
в качестве кодировки имени файла применяется UTF-8, но набор символов текущей локали также помещается
в список кодировок.
Возвращаемые charsets
принадлежат GLib и не должны освобождаться.
Помните что в Unix, независимо от локального набора символов или значения G_FILENAME_ENCODING
,
фактические имена файлов представленные в системе могут быть в любой произвольной кодировке или просто тарабарщиной (gibberish).
charsets : |
расположение возвращаемого NULL -завершённого
списка кодировок имён
|
Возвращает : | TRUE если кодировка имени файла UTF-8.
|
Начиная с версии 2.6
gchar* g_filename_display_name (const gchar *filename);
Конвертирует имя файла в допустимую UTF-8 строку. Конвертация необязательно
обратима, поэтому вы должны иметь оригинал и использовать возвращаемое значение
этой функции только непосредственно для отображения.
В отличие от g_filename_to_utf8()
, результатом гарантировано будет не-NULL
даже если имя файла фактически не находится в кодировке имени файла GLib.
Если GLib не может понять кодировку filename
, как последний способ
она заменяет неизвестные символы с помощью U+FFFD, символом замены Unicode.
Вы можете искать результат кодировки UTF-8 этого символа (который находится в восьмеричной записи "\357\277\275") для поиска вывода если
filename
был в недопустимой кодировке.
Если вы знаете полное имя пути файла вы должны использовать
g_filename_display_basename()
,
так как она позволяет перекодировку имён файлов на основе их расположения.
filename : |
имя пути предположительно в GLib кодировке имени файла |
Возвращает : | вновь распределённая строка содержащая перевод имени файла в правильной UTF-8 |
Начиная с версии 2.6
gchar* g_filename_display_basename (const gchar *filename);
Возвращает отображаемое базовое имя для специфического имени файла, гарантировано в правильной UTF-8. Отображаемое имя может быть не идентично имени файла, например могут быть проблемы конвертации в UTF-8, а некоторые файлы могут быть оттранслированы в отображении.
Если GLib не может понять кодировку filename
, как последний вариант она
заменяет неизвестные символы с помощью U+FFFD, символ замены Unicode.
Вы можете найти результат для UTF-8 кодировки этого символа (который находится в восьмеричном представлении "\357\277\275")
для поиска вывода если filename
был в недопустимой кодировке.
Вы должны поместить полное имя пути файла в функцию чтобы можно было выполнить трансляцию известных расположений.
Эта функция предпочтительней чем
g_filename_display_name()
если вам известен полный путь, так как это позволяет трансляцию.
filename : |
полное имя пути в кодировке имени файла GLib |
Возвращает : | вновь распределённая строка содержащая представление базового имени файла в допустимой UTF-8 |
Начиная с версии 2.6
gchar** g_uri_list_extract_uris (const gchar *uri_list);
Разбирает URI список соответствующий text/uri-списку mime type, определённого в RFC 2483, в индивидуальные URIs, отменяя любые коментарии. URIs являются не утверждёнными.
uri_list : |
URI список |
Возвращает : | вновь распределённый NULL -завершённый список
строк содержащих индивидуальные URIs. Массив должен быть освобождён с помощью
g_strfreev() .
|
Начиная с версии 2.6
gchar* g_locale_from_utf8 (const gchar *utf8string, gssize len, gsize *bytes_read, gsize *bytes_written, GError **error);
Конвертирует строку из UTF-8 в кодировку используемую для строк C runtime (обычно тоже самое что используется операционной системой) в текущей локали.
utf8string : |
строка в кодировке UTF-8 |
len : |
длина строки, или -1 если строка завершающий ноль[1]. |
bytes_read : |
расположение для хранения количества байт во входной строке
когда конвертация полностью выполнена, или NULL .
Даже если конвертация завершилась успешно, это значение может быть меньше
чем len если есть части символов в конце ввода.
Если произошла ошибка
G_CONVERT_ERROR_ILLEGAL_SEQUENCE, сохраняется значение
смещения байт после последней удачной цепочки ввода.
|
bytes_written : |
количество байт сохранённых в буфере вывода (не включая завершающий ноль). |
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут произойти любые ошибки в
GConvertError.
|
Возвращает : | конвертированная строка, или NULL при ошибке.
|
typedef enum { G_CONVERT_ERROR_NO_CONVERSION, G_CONVERT_ERROR_ILLEGAL_SEQUENCE, G_CONVERT_ERROR_FAILED, G_CONVERT_ERROR_PARTIAL_INPUT, G_CONVERT_ERROR_BAD_URI, G_CONVERT_ERROR_NOT_ABSOLUTE_PATH } GConvertError;
Коды ошибок возвращаемые подпрограммами конвертации наборов символов.
gboolean g_get_charset (G_CONST_RETURN char **charset);
Получает набор символов для текущей локали; вы можете использовать этот набор символов как аргумент для
g_convert()
, для конвертации из
текущей локальной кодировки в некоторую другую кодировку. (Часто
g_locale_to_utf8()
и g_locale_from_utf8()
являются хорошими shortcuts, всё же.)
Возвращаемое значение равно TRUE
если локальной кодировкой является UTF-8, в этом случае вы можете избежать вызова
g_convert()
.
Возвращаемая строка в charset
не распределяется, и не должна освобождаться.
charset : |
расположение возвращаемого имени набора символов |
Возвращает : | TRUE если возвращаемый набор символов UTF-8
|
[1]
Помните что некоторые кодировки могут позволять nul байтам находится в строках.
В этом случае, использовать -1 для параметра len
опасно.
[2]
Несмотря на то, что byes_read
может возвращать информацию о частичных символах,
функции g_convert_...
являются в основном неподходящими для потоков.
Если основной конвертер поддерживает внутреннее состояние, то это не сохраняется через последовательность вызовов g_convert()
, g_convert_with_iconv()
или
g_convert_with_fallback()
.
(Примером этому является GNU C конвертер для CP1255 который не выдаст основной символ
пока он знает что следующий символ не знак который можно совместить с основным символом.)
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> enum GOptionError; #define G_OPTION_ERROR gboolean (*GOptionArgFunc) (const gchar *option_name, const gchar *value, gpointer data, GError **error); GOptionContext; GOptionContext* g_option_context_new (const gchar *parameter_string); void g_option_context_set_summary (GOptionContext *context, const gchar *summary); const gchar* g_option_context_get_summary (GOptionContext *context); void g_option_context_set_description (GOptionContext *context, const gchar *description); const gchar* g_option_context_get_description (GOptionContext *context); const gchar* (*GTranslateFunc) (const gchar *str, gpointer data); void g_option_context_set_translate_func (GOptionContext *context, GTranslateFunc func, gpointer data, GDestroyNotify destroy_notify); void g_option_context_set_translation_domain (GOptionContext *context, const gchar *domain); void g_option_context_free (GOptionContext *context); gboolean g_option_context_parse (GOptionContext *context, gint *argc, gchar ***argv, GError **error); void g_option_context_set_help_enabled (GOptionContext *context, gboolean help_enabled); gboolean g_option_context_get_help_enabled (GOptionContext *context); void g_option_context_set_ignore_unknown_options (GOptionContext *context, gboolean ignore_unknown); gboolean g_option_context_get_ignore_unknown_options (GOptionContext *context); enum GOptionArg; enum GOptionFlags; #define G_OPTION_REMAINING GOptionEntry; void g_option_context_add_main_entries (GOptionContext *context, const GOptionEntry *entries, const gchar *translation_domain); GOptionGroup; void g_option_context_add_group (GOptionContext *context, GOptionGroup *group); void g_option_context_set_main_group (GOptionContext *context, GOptionGroup *group); GOptionGroup* g_option_context_get_main_group (GOptionContext *context); GOptionGroup* g_option_group_new (const gchar *name, const gchar *description, const gchar *help_description, gpointer user_data, GDestroyNotify destroy); void g_option_group_free (GOptionGroup *group); void g_option_group_add_entries (GOptionGroup *group, const GOptionEntry *entries); gboolean (*GOptionParseFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error); void g_option_group_set_parse_hooks (GOptionGroup *group, GOptionParseFunc pre_parse_func, GOptionParseFunc post_parse_func); void (*GOptionErrorFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error); void g_option_group_set_error_hook (GOptionGroup *group, GOptionErrorFunc error_func); void g_option_group_set_translate_func (GOptionGroup *group, GTranslateFunc func, gpointer data, GDestroyNotify destroy_notify); void g_option_group_set_translation_domain (GOptionGroup *group, const gchar *domain);
Анализатор командной строки GOption предназначен для более простой замены библиотеки popt. Он поддерживает короткие и длинные опции командной строки, как показано в следующем примере:
testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2
Пример демонстрирует множество особенностей синтаксического анализатора командной строки GOption
Опции могут быть одиночной буквой с предустановленным одиночным тире. Множество коротких опций могут быть сгруппированы за одним тире.
Длинные опцией предустанавливаются двумя последовательными тире.
Опции могут иметь дополнительный аргумент, который может быть числом, строкой или именем файла. Для длинных опций, дополнительный аргумент может быть присоединён с помощью знака равенства сразу после названия опции.
Неопциональные аргументы возвращаются как сброшенные аргументы.
Аргумент состоящий исключительно из двух тире предотвращает дальнейший анализ, любые аргументы (даже которые начинаются с тире) возвращаются как сброшенные аргументы.
Другая важная особенность GOption в автоматической генерации приятно оформленного вывода справки.
Если это явно не выключено с помощью функции
g_option_context_set_help_enabled()
, GOption распознаёт
--help
, -?
, --help-all
и --help-
groupname
опции
(где groupname
это имя GOptionGroup)
и пишет текст, подобный показанному в следующем примере, в stdout.
Usage: testtreemodel [OPTION...] - test tree model performance Help Options: -?, --help Показать опции справки --help-all Показать все опции справки --help-gtk Показать опции GTK+ Application Options: -r, --repeats=N Среднее число повторений N -m, --max-size=M Проверить до 2^M элементов --display=DISPLAY X display для использования -v, --verbose Подробности -b, --beep Сигнал при выполнении --rand Произвольные данные
Группы опций GOption находятся в GOptionGroups,
которые облегчают включение опций из многочисленных источников. Они позволяют приложениям собирать группы опций из используемых библиотек,
добавляя их к своему GOptionContext,
и анализируя все опции одним вызовом
g_option_context_parse()
.
Смотрите gtk_get_option_group()
для примера.
Если задекларированная опция является печатной строкой или именем файла, GOption позаботится о преобразовании в правильную кодировку; строки возвращаются в кодировке UTF-8, имена файлов в кодировке имён файлов GLib.
Вот полный пример настроек GOption для анализа командной строки приведенной в примере выше и выполнение вывода примера справки.
static gint repeats = 2; static gint max_size = 8; static gboolean verbose = FALSE; static gboolean beep = FALSE; static gboolean rand = FALSE; static GOptionEntry entries[] = { { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Среднее число повторений N", "N" }, { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Проверка до 2^M элементов", "M" }, { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Подробности", NULL }, { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Сигнал при выполнениии", NULL }, { "rand", 0, 0, G_OPTION_ARG_NONE, &rand, "Произовольные данные", NULL }, { NULL } }; int main (int argc, char *argv[]) { GError *error = NULL; GOptionContext *context; context = g_option_context_new ("- test tree model performance"); g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE); g_option_context_add_group (context, gtk_get_option_group (TRUE)); g_option_context_parse (context, &argc, &argv, &error); /* ... */ }
typedef enum { G_OPTION_ERROR_UNKNOWN_OPTION, G_OPTION_ERROR_BAD_VALUE, G_OPTION_ERROR_FAILED } GOptionError;
Коды ошибок возвращаемые анализатором опций.
G_OPTION_ERROR_UNKNOWN_OPTION |
Опция неизвестна анализатору.
Эта ошибка будет сообщена только если анализатор небыл проинструктирован игнорировать неизвестные опции,
смотрите g_option_context_set_ignore_unknown_options() .
|
G_OPTION_ERROR_BAD_VALUE |
Значение небыло проанализировано. |
G_OPTION_ERROR_FAILED |
Функция GOptionArgFunc завершилась неудачно. |
#define G_OPTION_ERROR (g_option_error_quark ())
Домен ошибки для анализатора опций. Ошибки в этом домене из перечисления GOptionError. Смотрите GError для информации о доменах ошибок.
gboolean (*GOptionArgFunc) (const gchar *option_name, const gchar *value, gpointer data, GError **error);
Тип функции для анализа как callback-функция для опции G_OPTION_ARG_CALLBACK
.
option_name : |
Имя анализируемой опции. Это может быть любая буква с предустановленным одиночным тире (для коротких имён) или два последовательных тире перед длинным именем. |
value : |
Значение для анализа. |
data : |
Пользовательские данные добавляемые в
GOptionGroup содержащую опции, которая была
создана с помощью g_option_group_new()
|
error : |
Расположение для возвращаемых ошибок.
Коды ошибок G_OPTION_ERROR_FAILED
предназначены для использования в GOptionArgFunc.
|
Возвращает : |
TRUE если опция была полностью проанализирована,
FALSE если произошла ошибка,
в этом случае error должна быть установлена с помощью g_set_error()
|
typedef struct _GOptionContext GOptionContext;
Структура GOptionContext определяет какие опции применяются анализатором опций командной строки. Структура содержит только закрытые поля и не должна использоваться непосредственно.
GOptionContext* g_option_context_new (const gchar *parameter_string);
Создаёт новый опциональный контекст.
parameter_string
может служить для множества целей.
Он может служить для добавления описания сброшенных аргументов, которые не проанализированы
GOptionContext,
обычно что-то вроде "FILES" или "FILE1 FILE2...". Если вы используете
G_OPTION_REMAINING для
сбора сброшенных параметров, GLib обработает это автоматически используя arg_description
соответсвующий GOptionEntry
в суммарном использовании.
Другое назначение может дать короткое описание функциональности программы,
например " - frob strings", которое отобразится в той же строке где и "использование".
Для длинных описаний функциональности программы, которые должны отображаться как параграф ниже линии описывающей использование программы,
используйте g_option_context_set_summary()
.
Помните что parameter_string
переводится
(смотрите g_option_context_set_translate_func()
).
parameter_string : |
строка которая отображается в первой линии вывода --help ,
после короткого описания использования
|
Возвращает : | вновь созданная GOptionContext,
которая должна быть освобождена с помощью
g_option_context_free()
после использования.
|
Начиная с версии 2.6
void g_option_context_set_summary (GOptionContext *context, const gchar *summary);
Добавляет строку в отображаемый вывод --help
перед списком опций. Обычно это короткое описание функциональности программы.
Помните что короткое описание переводится
(смотрите g_option_context_set_translate_func()
).
context : |
GOptionContext |
summary : |
строка для отображения в выводе --help
перед списком опций, или NULL
|
Начиная с версии 2.12
const gchar* g_option_context_get_summary (GOptionContext *context);
Возвращает короткое описание. Смотрите g_option_context_set_summary()
.
context : |
GOptionContext |
Возвращает : | короткое описание |
Начиная с версии 2.12
void g_option_context_set_description (GOptionContext *context, const gchar *description);
Добавляет строку для отображения в выводе --help
после списка опций. Этот текст часто включает адрес для сообщения об ошибках.
Помните что краткое описание переводится
(смотрите g_option_context_set_translate_func()
).
context : |
GOptionContext |
description : |
строка для отображения в выводе --help
после списка опций, или NULL
|
Начиная с версии 2.12
const gchar* g_option_context_get_description (GOptionContext *context);
Возвращает описание. Смотрите g_option_context_set_description()
.
context : |
GOptionContext |
Возвращает : | описание |
Начиная с версии 2.12
const gchar* (*GTranslateFunc) (const gchar *str, gpointer data);
Тип функции которая используется для перевода видимых пользователем строк, для вывода --help
.
str : |
непереведённая строка |
data : |
пользовательские данные определяемые при установке функции, например
g_option_group_set_translate_func()
|
Возвращает : | переведённую строку для текущей локализации. Возвращаемой строкой владеет GLib и она не должна освобождаться. |
void g_option_context_set_translate_func (GOptionContext *context, GTranslateFunc func, gpointer data, GDestroyNotify destroy_notify);
Устанавливает функцию которая используется для перевода содержимого строк видимых пользователем,
для вывода --help
.
Если func
равен NULL
,
строки не переводятся.
Помните что группы опций имеют собственные функции перевода,
эта функция затрагивает только parameter_string
(смотрите g_option_context_nex()
),
краткое описание (смотрите g_option_context_set_summary()
) и описание
(смотрите g_option_context_set_description()
).
Если вы используете gettext()
, вам нужно только установить область перевода, смотрите g_context_group_set_translation_domain()
.
context : |
GOptionContext |
func : |
GTranslateFunc, или NULL
|
data : |
пользовательские данные помещаемые в func ,
или NULL
|
destroy_notify : |
функция которая вызывается для освобождения data ,
или NULL
|
Начиная с версии 2.12
void g_option_context_set_translation_domain (GOptionContext *context, const gchar *domain);
Удобная функция использующая
gettext()
для перевода видимых пользователем строк.
context : |
GOptionContext |
domain : |
используемая область |
Начиная с версии 2.12
void g_option_context_free (GOptionContext *context);
Освобождает контекст и все добавленные в него группы.
context : |
GOptionContext |
Начиная с версии 2.6
gboolean g_option_context_parse (GOptionContext *context, gint *argc, gchar ***argv, GError **error);
Анализирует аргументы командной строки, распознавая опции которые были добавлены в context
.
Побочный эффект вызова этой функции в том, что будет вызвана g_set_prgname()
.
Если анализ полностью выполнен, любые анализируемые аргументы будут удалены из массива, а argc
и argv
соответственно обновятся. Опция '--' удаляется из argv
нет не анализируемых опций перед ней и после неё, или некоторые опции после неё начинаются с '-'.
В этом случае происходит ошибка, argc
и argv
остаются неизменёнными.
Если включена автоматическая поддержка --help
(смотрите g_option_context_set_help_enabled()
), а массив argv
содержит одну из распознаваемых опций справки,
эта функция выполнит вывод справки на stdout и вызовет exit (0)
.
context : |
GOptionContext |
argc : |
указатель на номер аргумента командной строки. |
argv : |
указатель на массив аргументов командной строки. |
error : |
расположение для возвращаемой ошибки |
Возвращает : | TRUE если анализ полностью выполнен,
FALSE если произошла ошибка
|
Начиная с версии 2.6
void g_option_context_set_help_enabled (GOptionContext *context, gboolean help_enabled);
Включает или выключает автоматическую генерацию вывода --help
.
По умолчанию, g_option_context_parse()
распознаёт --help
, -?
, --help-all
и --help-
groupname
и создаёт подходящий вывод на stdout.
context : |
GOptionContext |
help_enabled : |
TRUE для включения --help ,
FALSE для отключения
|
Начиная с версии 2.6
gboolean g_option_context_get_help_enabled (GOptionContext *context);
Определяет включена ли автоматическая генерация --help
для context
.
Смотрите g_option_context_set_help_enabled()
.
context : |
GOptionContext |
Возвращает : | TRUE если автоматическая генерация справки включена.
|
Начиная с версии 2.6
void g_option_context_set_ignore_unknown_options (GOptionContext *context, gboolean ignore_unknown);
Устанавливает игнорировать неизвестные опции или нет. Если опция игнорируется, то она сбрасывается в массив argv
после анализа.
По умолчанию, g_option_context_parse()
воспринимает неизвестные опции как ошибки.
Эти настройки не затрагивают не опциональные аргументы (то есть аргументы которые начинаются не с тире). Но помните что GOption не может надёжно определить принадлежит ли не-опция к предыдущей неизвестной опции.
context : |
GOptionContext |
ignore_unknown : |
TRUE для игнорирования неизвестных опций,
FALSE
для производства ошибки при встрече неизвестной опции
|
Начиная с версии 2.6
gboolean g_option_context_get_ignore_unknown_options (GOptionContext *context);
Определяет игнорируются неизвестные опции или нет.
Смотрите g_option_context_set_ignore_unknown_options()
.
context : |
GOptionContext |
Возвращает : | TRUE если неизвестные опции игнорируются.
|
Начиная с версии 2.6
typedef enum { G_OPTION_ARG_NONE, G_OPTION_ARG_STRING, G_OPTION_ARG_INT, G_OPTION_ARG_CALLBACK, G_OPTION_ARG_FILENAME, G_OPTION_ARG_STRING_ARRAY, G_OPTION_ARG_FILENAME_ARRAY, G_OPTION_ARG_DOUBLE, G_OPTION_ARG_INT64 } GOptionArg;
GOptionArg перечисляет значения определяющие какой тип
дополнительного параметра опции ожидается обнаружить. Если опции ожидает дополнительный параметр, он может быть определён несколькими
способами; с короткими опциями: -x arg
, с длинными опциями: --name arg
или комбинировано в одном аргументе: --name=arg
.
G_OPTION_ARG_NONE |
Нет дополнительного параметра. Это полезно для простых флагов. |
G_OPTION_ARG_STRING |
Опция принимает строковый параметр. |
G_OPTION_ARG_INT |
Опция принимает целочисленный параметр. |
G_OPTION_ARG_CALLBACK |
Опция обеспечивает callback-функцию для анализа дополнительного параметра. |
G_OPTION_ARG_FILENAME |
Опция принимает имя файла как параметр. |
G_OPTION_ARG_STRING_ARRAY |
Опция принимает строковый параметр, многократное использование опции собирается в строковый массив. |
G_OPTION_ARG_FILENAME_ARRAY |
Опция принимает имя файла как параметр, многократное использование опции собирается в строковый массив. |
G_OPTION_ARG_DOUBLE |
Опция принимает двойной параметр. Параметр может быть в формате пользовательской локализации или в "C" locale. Начиная с версии 2.12 |
G_OPTION_ARG_INT64 |
Опция принимает 64-битное целочисленное.
Как G_OPTION_ARG_INT
но для большего числа. Число может быть десятичным, шестнадцатиричным
(когда префикс 0x , например, 0xffffffff ).
Начиная с версии 2.12
|
typedef enum { G_OPTION_FLAG_HIDDEN = 1 << 0, G_OPTION_FLAG_IN_MAIN = 1 << 1, G_OPTION_FLAG_REVERSE = 1 << 2, G_OPTION_FLAG_NO_ARG = 1 << 3, G_OPTION_FLAG_FILENAME = 1 << 4, G_OPTION_FLAG_OPTIONAL_ARG = 1 << 5, G_OPTION_FLAG_NOALIAS = 1 << 6 } GOptionFlags;
Флаги которые модифицируют отдельные опции.
G_OPTION_FLAG_HIDDEN |
Опция не появляется в выводе --help .
|
G_OPTION_FLAG_IN_MAIN |
Опция появляется в основном разделе вывода --help , даже если она определена в группе.
|
G_OPTION_FLAG_REVERSE |
Для опции вида G_OPTION_ARG_NONE ,
этот флаг указывает что опция имеет обратный смысл.
|
G_OPTION_FLAG_NO_ARG |
Для опции вида G_OPTION_ARG_CALLBACK ,
этот флаг указывает что callback-функция не принимает аргументов
(как опция G_OPTION_ARG_NONE ).
Начиная с версии 2.8
|
G_OPTION_FLAG_FILENAME |
Для опции вида G_OPTION_ARG_CALLBACK ,
этот флаг указывает что аргумент должен быть помещён в callback-функцию в кодировке имён файлов GLib, а не в UTF-8.
Начиная с версии 2.8
|
G_OPTION_FLAG_OPTIONAL_ARG |
Для опции вида G_OPTION_ARG_CALLBACK ,
этот флаг указывает что аргумент является опциональным. Если нет аргумента, то данные для
GOptionParseFunc
будут установлены в значение NULL. Начиная с версии 2.8
|
G_OPTION_FLAG_NOALIAS |
Этот флаг выключает автоматическое разрешение противоречий префиксов имён длинных опций с groupname- ,
если есть конфликты. Эта опция должна использоваться только в ситуациях где псевдоним необходим для некоторого устаревшего интерфейса
командной строки. Использование этой опции небезопасно, если все все группы опций не находятся под вашим прямым контролем.
Начиная с версии 2.8.
|
#define G_OPTION_REMAINING ""
Если длинная опция в основной группе имеет это имя, она не обрабатывается как обычная опция.
Вместо этого она собирает все неопциональные аргументы которые в противном случае будут сброшены в argv
.
Опция должна быть типа
G_OPTION_ARG_STRING_ARRAY
или
G_OPTION_ARG_FILENAME_ARRAY
.
Использование G_OPTION_REMAINING,
вместо простого сканирования argv
для просмотра оставшихся параметров, имеет преимущество, так как
GOption заботится о необходимом перекодировании строк или имён файлов.
Начиная с версии 2.6
typedef struct { const gchar *long_name; gchar short_name; gint flags; GOptionArg arg; gpointer arg_data; const gchar *description; const gchar *arg_description; } GOptionEntry;
GOptionEntry определяет единственную опцию.
Для эффективности, она должна быть добавлена в
GOptionGroup с помощью
g_option_context_add_main_entries()
или g_option_group_add_entries()
.
const gchar *long_name ; |
Длинное имя опции может использоваться для определения в командной строке как --long_name .
Все опции должны иметь длинные имена. Для решения конфликтов, если множество групп опций содержат одинаковое длинное имя,
опцию также возможно определить как --groupname -long_name .
|
gchar short_name ; |
Если опция имеет короткое имя, она может быть определена в командной строке как -short_name .
short_name должен быть печатным ASCII символом не тире '-',
или нулём если опция не имеет короткого имени.
|
gint flags ; |
Флаги из GOptionFlags. |
GOptionArg arg ; |
Тип опции, как GOptionArg. |
gpointer arg_data ; |
Если тип arg это
G_OPTION_ARG_CALLBACK ,
тогда arg_data должен указывать на
GOptionArgFunc callback-функцию,
которая будет вызвана для обработки дополнительных параметров.
Иначе, arg_data это указатель на расположение для сохраняемого значения,
требуемый тип расположения зависит от типа arg :
|
const gchar *description ; |
описание для опции в выводе --help .
description переводится с помощью translate_func группы,
смотрите g_option_group_set_translation_domain() .
|
const gchar *arg_description ; |
метка-заполнитель для используемого дополнительного параметра анализируемой опции в выводе --help .
arg_description переводится используя translate_func
группы, смотрите g_option_group_set_translation_domain() .
|
void g_option_context_add_main_entries (GOptionContext *context, const GOptionEntry *entries, const gchar *translation_domain);
Удобная функция которая создаёт основную группу если она не существует,
добавляет в неё entries
и устанавливает область перевода.
context : |
GOptionContext |
entries : |
NULL -завершённый массив
GOptionEntrys
|
translation_domain : |
область перевода используемая для перевода вывода --help
опций в entries с помощью
gettext() ,
или NULL
|
Начиная с версии 2.6
typedef struct _GOptionGroup GOptionGroup;
Структура GOptionGroup определяет опции в единственной группе. Структура имеет только закрытые поля и не должна использоваться непосредственно.
Все опции в группе используют совместно одну функцию перевода. Библиотеки которые необходимы для анализа опций командной строки обеспечат функцию для получения GOptionGroup содержащую эти опции, которую приложение может добавить в свой GOptionContext.
void g_option_context_add_group (GOptionContext *context, GOptionGroup *group);
Добавляет GOptionGroup в
context
, так чтобы анализ context
распознал опции в группе. Помните что группа будет освобождена вместе с контекстом когда будет вызвана
g_option_context_free()
,
поэтому вы не должны освобождать группу самостоятельно после добавления её в контекст.
context : |
GOptionContext |
group : |
добавляемая группа |
Начиная с версии 2.6
void g_option_context_set_main_group (GOptionContext *context, GOptionGroup *group);
Устанавливает GOptionGroup как основную группу
context
.
Это имеет тот же эффект как вызов g_option_context_add_group()
,
только разница в том, что опции в основной группе обрабатываются по другому когда генерируется вывод --help
.
context : |
GOptionContext |
group : |
группа для установки в качестве основной |
Начиная с версии 2.6
GOptionGroup* g_option_context_get_main_group (GOptionContext *context);
Возвращает указатель на основную группу которая принадлежит к context
.
context : |
GOptionContext |
Возвращает : | основная группа для context , или
NULL
если context не имеет основной группы.
Помните что группа принадлежит context
и не должна изменяться или освобождаться.
|
Начиная с версии 2.6
GOptionGroup* g_option_group_new (const gchar *name, const gchar *description, const gchar *help_description, gpointer user_data, GDestroyNotify destroy);
Создаёт новую GOptionGroup.
name : |
имя для группы опции, оно используется для получения справки об опциях в этой группе с помощью
--help- name
|
description : |
описание для этой группы которое должно показываться в выводе --help .
Эта строка переводится используя область перевода или функцию перевода в группе.
|
help_description : |
описание для --help- name опции.
Эта строка переводится используя область перевода или функцию перевода в группе.
|
user_data : |
пользовательские данные которые будут помещены в обработчик перед и после анализа,
обработчик ошибок и callbacks-функции
G_OPTION_ARG_CALLBACK опций,
или NULL
|
destroy : |
функция для освобождения user_data ,
или NULL
|
Возвращает : | вновь созданная группа опций. Она должна быть добавлена в
GOptionContext
или освобождена с помощью
g_option_group_free() .
|
Начиная с версии 2.6
void g_option_group_free (GOptionGroup *group);
Освобождает GOptionGroup. Помните что вы не должны освобождать группы добавленные в GOptionContext.
group : |
GOptionGroup |
Начиная с версии 2.6
void g_option_group_add_entries (GOptionGroup *group, const GOptionEntry *entries);
Добавляет опцию определённую в entries
к group
.
group : |
GOptionGroup |
entries : |
NULL -завершённый массив
GOptionEntrys
|
Начиная с версии 2.6
gboolean (*GOptionParseFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error);
Тип функции которая может быть вызвана перед и после анализа.
context : |
Активный GOptionContext |
group : |
группа с которой связана функция |
data : |
пользовательские данные добавляемые в GOptionGroup
содержащую опцию где она была создана с помощью
g_option_group_new()
|
error : |
расположение для возвращаемой ошибки |
Возвращает : |
TRUE если функция полностью выполнена,
FALSE если произошла ошибка,
в этом случае должна быть установлена error с помощью
g_set_error()
|
void g_option_group_set_parse_hooks (GOptionGroup *group, GOptionParseFunc pre_parse_func, GOptionParseFunc post_parse_func);
Связывает две функции с group
которые будут вызваны из
g_option_context_parse()
перед анализом первой опции и после анализа последней опции соответственно.
Помните что пользовательские данные помещаемые в pre_parse_func
и
post_parse_func
могут быть определены при создании группы с помощью
g_option_group_new()
.
group : |
GOptionGroup |
pre_parse_func : |
функция вызываемая перед анализом, или NULL
|
post_parse_func : |
функция вызываемая после анализа, или NULL
|
Начиная с версии 2.6
void (*GOptionErrorFunc) (GOptionContext *context, GOptionGroup *group, gpointer data, GError **error);
Тип функции используемая как callback-функция когда происходит ошибка анализа.
context : |
Активный GOptionContext |
group : |
группа с которой связана функция |
data : |
пользовательские данные добавляемые в GOptionGroup содержащую опцию где она была создана с помощью g_option_group_new()
|
error : |
GError содержащая детали произошедшей ошибки анализа |
void g_option_group_set_error_hook (GOptionGroup *group, GOptionErrorFunc error_func);
Связывает функцию с group
которая будет вызвана из
g_option_context_parse()
когда произойдёт ошибка.
Помните что пользовательские данные помещаемые в pre_parse_func
и
post_parse_func
могут быть определены при создании группы с помощью
g_option_group_new()
.
group : |
GOptionGroup |
error_func : |
функция вызываемая при возникновении ошибки |
Начиная с версии 2.6
void g_option_group_set_translate_func (GOptionGroup *group, GTranslateFunc func, gpointer data, GDestroyNotify destroy_notify);
Устанавливает функцию которая используется для перевода строк видимых пользователем,
для вывода --help
. Разные группы могут использовать разные
GTranslateFuncs.
Если func
это NULL
,
строки не переводятся.
Если вы используете gettext()
, вам нужно только установить область перевода, смотрите g_option_group_set_translation_domain()
.
group : |
GOptionGroup |
func : |
GTranslateFunc, или
NULL
|
data : |
пользовательские данные помещаемые в func ,
или NULL
|
destroy_notify : |
функция которая вызывается для освобождения data ,
или NULL
|
Начиная с версии 2.6
void g_option_group_set_translation_domain (GOptionGroup *group, const gchar *domain);
Удобная функция использующая gettext()
для перевода видимых пользователем строк.
group : |
GOptionGroup |
domain : |
используемая область |
Начиная с версии 2.6
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> #define g_dataset_id_set_data (l, k, d) void g_dataset_id_set_data_full (gconstpointer dataset_location, GQuark key_id, gpointer data, GDestroyNotify destroy_func); void (*GDestroyNotify) (gpointer data); gpointer g_dataset_id_get_data (gconstpointer dataset_location, GQuark key_id); #define g_dataset_id_remove_data (l, k) gpointer g_dataset_id_remove_no_notify (gconstpointer dataset_location, GQuark key_id); #define g_dataset_set_data (l, k, d) #define g_dataset_set_data_full (l, k, d, f) #define g_dataset_get_data (l, k) #define g_dataset_remove_data (l, k) #define g_dataset_remove_no_notify (l, k) void g_dataset_foreach (gconstpointer dataset_location, GDataForeachFunc func, gpointer user_data); void (*GDataForeachFunc) (GQuark key_id, gpointer data, gpointer user_data); void g_dataset_destroy (gconstpointer dataset_location);
Наборы данных связывают группы элементов данных со специфическим расположением памяти. Это полезно если вам необходимо связать данные со структурами возвращаемыми из внешних библиотек. Так как вы не изменяете структуру, вы используете её расположение в памяти как ключ в наборе данных, в котором вы можете связать любое количество элементов данных.
Есть две формы большинства функций набора данных.
Первая форма использовать строки для идентификации элементов данных связанных с расположением.
Вторая форма использует идентификаторы GQuark, которые создаются
с помощью вызова g_quark_from_string()
или
g_quark_from_static_string()
.
Вторая форма быстрее, так как она не требует поиска строки в хеш таблице идентификаторов
GQuark.
Нет функции для создания набора данных. Он автоматически создаётся когда вы добавляете элемент в него.
Для добавления элемента в набор данных используйте g_dataset_id_set_data()
,
g_dataset_id_set_data_full()
, g_dataset_set_data()
and g_dataset_set_data_full()
.
Для получения элемента данных из набора данных используйте g_dataset_id_get_data()
и
g_dataset_get_data()
.
Для перемещения по всем элементам данных в наборе данных используйте g_dataset_foreach()
(not thread-safe).
Для удаления элементов данных из набора данных используйте g_dataset_id_remove_data()
и
g_dataset_remove_data()
.
Для уничтожения набора данных, используйте g_dataset_destroy()
.
#define g_dataset_id_set_data(l, k, d)
Устанавливает элемент данных связанный с указанным GQuark идентификатором. Любые предыдущие данные с тем же ключом удаляются и вызывается функция их уничтожения.
l : |
расположение идентифицирующее набор данных. |
k : |
GQuark для идентификации элемента данных. |
d : |
элемент данных. |
void g_dataset_id_set_data_full (gconstpointer dataset_location, GQuark key_id, gpointer data, GDestroyNotify destroy_func);
Устанавливает элемент данных связанный с указанным GQuark, а также функцию вызываемую для разрушения элемента данных. Любые предыдущие данные с тем же ключом удаляются и вызывается функция их уничтожения.
dataset_location : |
расположение идентифицирующее набор данных. |
key_id : |
GQuark идентифицирующий элемент данных. |
data : |
элемент данных. |
destroy_func : |
функция вызываемая при удалении элемента данных. Эта функция вызывается с элементом данных и может использоваться для освобождения любой памяти распределённой для него. |
void (*GDestroyNotify) (gpointer data);
Определяет тип функции которая вызывается когда элемент уничтожается. В неё помещается указатель на элемент данных и она должна освободить всю память и все ресурсы распределённые для этого элемента.
data : |
элемент данных. |
gpointer g_dataset_id_get_data (gconstpointer dataset_location, GQuark key_id);
Выдает элемент данных соответствующий GQuark.
#define g_dataset_id_remove_data(l, k)
Удаляет элемент данных из набора данных. Функция уничтожения элемента данных вызывается если была установлена.
l : |
расположение идентифицирующее набор данных. |
k : |
GQuark идентифицирующий элемент данных. |
gpointer g_dataset_id_remove_no_notify (gconstpointer dataset_location, GQuark key_id);
Удаляет элемент, не вызывая разрушающую функцию для него.
#define g_dataset_set_data(l, k, d)
Устанавливает данные соответствующие указанному строковому идентификатору.
l : |
расположение идентифицирующее набор данных. |
k : |
строка строка идентифицирующая элемент данных. |
d : |
элемент данных. |
#define g_dataset_set_data_full(l, k, d, f)
Устанавливает данные соответствующие указанному строковому идентификатору, и функцию уничтожающую элемент данных.
l : |
расположение идентифицирующее набор данных. |
k : |
строка строка идентифицирующая элемент данных. |
d : |
элемент данных. |
f : |
функция вызываемая когда удаляется элемент данных. Эта функция вызывается с элементом данных и может использоваться для освобождения любой памяти и ресурсов распределённых для него. |
#define g_dataset_get_data(l, k)
Выдаёт элемент данных соответствующий строке.
l : |
расположение идентифицирующее набор данных. |
k : |
строка идентифицирующая элемент данных. |
Возвращает : | элемент данных соответствующий строке, или
NULL
если он не найден.
|
#define g_dataset_remove_data(l, k)
Удаляет элемент данных соответствующий строке. Она вызывает функцию уничтожения если та установлена.
l : |
расположение идентифицирующее набор данных. |
k : |
строка identifying элемент данных. |
#define g_dataset_remove_no_notify(l, k)
Удаляет элемент, без вызова функции уничтожения.
l : |
расположение идентифицирующее набор данных. |
k : |
строка идентифицирующая элемент данных. |
void g_dataset_foreach (gconstpointer dataset_location, GDataForeachFunc func, gpointer user_data);
Вызывает указанную функцию для каждого элемента данных который связан с указанным расположением.
Помните что эта функция потоко-небезопасна. Поэтому если datalist
не может быть защищен от любых изменений в течении вызова этой функции, она не должна вызываться.
dataset_location : |
расположение идентифицирующее набор данных. |
func : |
функция вызываемая для каждого элемента данных. |
user_data : |
пользовательские данные помещаемые в функцию. |
void (*GDataForeachFunc) (GQuark key_id, gpointer data, gpointer user_data);
Определяет тип функции помещаемой в g_dataset_foreach()
.
Она вызывается с каждым GQuark id и связывает элемент днных,
вместе с параметром user_data
поставляемым в
g_dataset_foreach()
.
key_id : |
GQuark идентифицирующий элемент данных. |
data : |
элемент данных. |
user_data : |
пользовательские данные для g_dataset_foreach() .
|
void g_dataset_destroy (gconstpointer dataset_location);
Уничтожает набор данных, освобождая всю распределённую память и вызывая любую функцию уничтожения установленную для элементов данных.
dataset_location : |
расположение идентифицирующее набор данных. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Функции даты и времениDate and Time Functions — календарные вычисления и различный материал времени. |
#include <glib.h> #define G_USEC_PER_SEC GTimeVal; void g_get_current_time (GTimeVal *result); void g_usleep (gulong microseconds); void g_time_val_add (GTimeVal *time_, glong microseconds); gboolean g_time_val_from_iso8601 (const gchar *iso_date, GTimeVal *time_); gchar* g_time_val_to_iso8601 (GTimeVal *time_); GDate; typedef GTime; enum GDateDMY; typedef GDateDay; enum GDateMonth; typedef GDateYear; enum GDateWeekday; #define G_DATE_BAD_DAY #define G_DATE_BAD_JULIAN #define G_DATE_BAD_YEAR GDate* g_date_new (void); GDate* g_date_new_dmy (GDateDay day, GDateMonth month, GDateYear year); GDate* g_date_new_julian (guint32 julian_day); void g_date_clear (GDate *date, guint n_dates); void g_date_free (GDate *date); void g_date_set_day (GDate *date, GDateDay day); void g_date_set_month (GDate *date, GDateMonth month); void g_date_set_year (GDate *date, GDateYear year); void g_date_set_dmy (GDate *date, GDateDay day, GDateMonth month, GDateYear y); void g_date_set_julian (GDate *date, guint32 julian_date); void g_date_set_time (GDate *date, GTime time_); void g_date_set_time_t (GDate *date, time_t timet); void g_date_set_time_val (GDate *date, GTimeVal *timeval); void g_date_set_parse (GDate *date, const gchar *str); void g_date_add_days (GDate *date, guint n_days); void g_date_subtract_days (GDate *date, guint n_days); void g_date_add_months (GDate *date, guint n_months); void g_date_subtract_months (GDate *date, guint n_months); void g_date_add_years (GDate *date, guint n_years); void g_date_subtract_years (GDate *date, guint n_years); gint g_date_days_between (const GDate *date1, const GDate *date2); gint g_date_compare (const GDate *lhs, const GDate *rhs); void g_date_clamp (GDate *date, const GDate *min_date, const GDate *max_date); void g_date_order (GDate *date1, GDate *date2); GDateDay g_date_get_day (const GDate *date); GDateMonth g_date_get_month (const GDate *date); GDateYear g_date_get_year (const GDate *date); guint32 g_date_get_julian (const GDate *date); GDateWeekday g_date_get_weekday (const GDate *date); guint g_date_get_day_of_year (const GDate *date); guint8 g_date_get_days_in_month (GDateMonth month, GDateYear year); gboolean g_date_is_first_of_month (const GDate *date); gboolean g_date_is_last_of_month (const GDate *date); gboolean g_date_is_leap_year (GDateYear year); guint g_date_get_monday_week_of_year (const GDate *date); guint8 g_date_get_monday_weeks_in_year (GDateYear year); guint g_date_get_sunday_week_of_year (const GDate *date); guint8 g_date_get_sunday_weeks_in_year (GDateYear year); guint g_date_get_iso8601_week_of_year (const GDate *date); gsize g_date_strftime (gchar *s, gsize slen, const gchar *format, const GDate *date); void g_date_to_struct_tm (const GDate *date, struct tm *tm); gboolean g_date_valid (const GDate *date); gboolean g_date_valid_day (GDateDay day); gboolean g_date_valid_month (GDateMonth month); gboolean g_date_valid_year (GDateYear year); gboolean g_date_valid_dmy (GDateDay day, GDateMonth month, GDateYear year); gboolean g_date_valid_julian (guint32 julian_date); gboolean g_date_valid_weekday (GDateWeekday weekday);
Структура данных GDate представляет день
между 1 Января (January 1), 1 Года (Year 1), и несколькими тысячами лет в будущем (в данный момент это составляет приблизительно 65535 лет,
но g_date_set_parse()
анализирует только до
8000 года приблизительно - простой счёт в "несколько тысяч").
GDate предназначена для
представления ежедневных дат, не астрономических дат, не исторических дат, не
ISO временных интервалов (timestamps) и не подобных им. Она экстраполирует текущий Григорианский календарь
вперёд и назад во времени; не производится никаких попыток изменить календарь для соответствия временным периодам или месту расположения.
GDate не хранит информацию о времени;
она представляет day.
GDate реализация имеет несколько прекрасных особенностей; она является 64-битной структурой, поэтому хранение большого количества дат очень эффективно. Она может принимать оба вида представления даты и Юлианское и день-месяц-год, так как некоторые расчёты более просты либо с одним представлением даты либо с другим. Юлианское представление - это просто подсчёт дней с некоторой фиксированной даты в прошлом; для GDate фиксированным днём является 1 Января, 1 года нашей эры (1 AD). ("Юлианские" даты в GDate API не являются фактическими Юлианскими датами в техническом смысле; технически, Юлианские даты подсчитываются начиная с Юлианского периода, 1 Января 4713 год до нашей эры (Julian period, Jan 1, 4713 BC)).
GDate проста в использовании.
Сначала вам потребуется пустая дата ("blank" date); вы можете получить динамически распределяемую дату из
g_date_new()
, или вы можете объявить
автоматическую переменную или массив и инициализировать его в нормальное состояние вызвав
g_date_clear()
.
Очищенная дата это нормально; это безопасно для вызова
g_date_set_dmy()
и других функций мутаторов для инициализации значения очищенной даты. Однако, очищенная дата первоначально
недоступна, это значит что она представляет день которого не существует.
Она не определена для вызова любых подпрограмм расчёта даты. Если вы определяете дату от пользователя или другого
непредсказуемого источника, вы должны проверять правильность даты с помощью
g_date_valid()
.
g_date_valid()
также используется для проверки ошибок g_date_set_parse()
и других функций которые могут завершиться неудачно.
Даты могут быть очищены снова с помощью вызова g_date_clear()
.
Очень важно использовать API для доступа к GDatestruct. Зачастую правильным является только представление день-месяц-год (day-month-year) или Юлианское. Иногда не одно из этих представлений неправильно. Используйте API.
GLib не содержит функций манипулирования временем; однако, есть GTime typedef и GTimeVal структура которые представляют более точное время (в микросекундах). Вы можете запросить текущее время как GTimeVal с помощью g_get_current_time()
.
#define G_USEC_PER_SEC 1000000
Количество микросекунд в одной секунде (1 миллион). Этот макрос обеспечивает удобочитаемость кода.
typedef struct { glong tv_sec; glong tv_usec; } GTimeVal;
Представляет точное время, с секундами и микросекундами.
Похоже на возврат struct timeval вызова
the
UNIX.
gettimeofday()
void g_get_current_time (GTimeVal *result);
Аналог UNIX функции gettimeofday()
, но переносимый.
result : |
GTimeVal структура в которой хранится текущее время. |
void g_usleep (gulong microseconds);
Приостанавливает текущий поток на определённое количество микросекунд. В секунде есть 1 миллион микросекунд (представляется с помощью макроса
G_USEC_PER_SEC). g_usleep()
может иметь ограниченную точность,
зависит от аппаратуры и операционной системы; не полагайтесь на точную длину паузы.
microseconds : |
количество микросекунд для паузы. |
void g_time_val_add (GTimeVal *time_, glong microseconds);
Добавляет полученное количество микросекунд к time_
.
microseconds
может быть также отрицательным для уменьшения значения
time_
.
time_ : |
GTimeVal |
microseconds : |
количество микросекунд для добавления к time
|
gboolean g_time_val_from_iso8601 (const gchar *iso_date, GTimeVal *time_);
Конвертирует строку содержащую код даты и времени ISO 8601 в
GTimeVal и помещает её в
time_
.
iso_date : |
строка кода даты ISO 8601 |
time_ : |
GTimeVal |
Возвращает : | TRUE если конвертация прошла успешно.
|
Начиная с версии 2.12
gchar* g_time_val_to_iso8601 (GTimeVal *time_);
Конвертирует time_
в строку кода ISO 8601, относительно Coordinated Universal Time (UTC).
time_ : |
GTimeVal |
Возвращает : | вновь распределённая строка содержащая дату ISO 8601 |
Начиная с версии 2.12
typedef struct { guint julian_days : 32; /* julian days representation - we use a * bitfield hoping that 64 bit platforms * will pack this whole struct in one big * int */ guint julian : 1; /* julian is valid */ guint dmy : 1; /* dmy is valid */ /* DMY representation */ guint day : 6; guint month : 4; guint year : 16; } GDate;
Представляет день между 1 Января 1 Года и и несколькими тысячами лет будущего.
Ни к одному из членов не нужно обращаться непосредственно. Если GDate
определена из g_date_new()
,
она будет безопасна для изменений, но недоступна и поэтому не безопасна для календарных расчётов.
Если это объявить в стеке, он будет содержать мусор поэтому должен быть инициализирован с помощью
g_date_clear()
.
g_date_clear()
делает дату недопустимой
но нормальной. Недопустимая дата не представляет день, она "пустая". Дата становится допустимой после того, как вы установите её в
Юлианский день или день, месяц и год.
guint julian_days : 32; |
Юлианское представление даты |
guint julian : 1; |
этот бит устанавливается если julian_days допустим
|
guint dmy : 1; |
это устанавливается если day , month и year являются допустимыми
|
guint day : 6; |
день в преставлении даты в виде день-месяц-год, как число между 1 и 31 |
guint month : 4; |
месяц в представлении даты в виде день-месяц-год, как число между 1 и 12 |
guint year : 16; |
год в представлении даты как день-месяц-год |
typedef gint32 GTime;
Просто замена для time_t. Она устарела так как не является эквивалентом для time_t на 64-битных платформах с 64-битной time_t. Несвязана с GTimer.
Помните что GTime определяется всегда как 32bit целочисленное,
в отличие от time_t которая может быть 64bit на некоторых системах.
Поэтому, GTime переполнится в 2038 году, и вы не сможете использовать
адрес переменной GTime как аргумент для UNIX функции time()
.
Вместо этого сделайте следующее:
time_t ttime; GTime gtime; time (&ttime); gtime = (GTime)ttime;
typedef enum { G_DATE_DAY = 0, G_DATE_MONTH = 1, G_DATE_YEAR = 2 } GDateDMY;
Это перечисление не используется в API, но может быть полезно если вам необходимо маркировать номер как день, месяц, или год.
typedef guint8 GDateDay; /* day of the month */
Целочисленное представляющее день в месяце; между 1 и 31. G_DATE_BAD_DAY представляет недопустимый день в месяце.
typedef enum { G_DATE_BAD_MONTH = 0, G_DATE_JANUARY = 1, G_DATE_FEBRUARY = 2, G_DATE_MARCH = 3, G_DATE_APRIL = 4, G_DATE_MAY = 5, G_DATE_JUNE = 6, G_DATE_JULY = 7, G_DATE_AUGUST = 8, G_DATE_SEPTEMBER = 9, G_DATE_OCTOBER = 10, G_DATE_NOVEMBER = 11, G_DATE_DECEMBER = 12 } GDateMonth;
Перечисление представляющее месяц; значениями являются G_DATE_JANUARY, G_DATE_FEBRUARY, и т.д.. G_DATE_BAD_MONTH представляет недопустимое значение.
typedef guint16 GDateYear;
Целочисленное представляющее год; G_DATE_BAD_YEAR представляет недопустимое значение. Год должен быть 1 или больше; отрицательное значение недопустимо. Год представляется четырьмя цифрами.
typedef enum { G_DATE_BAD_WEEKDAY = 0, G_DATE_MONDAY = 1, G_DATE_TUESDAY = 2, G_DATE_WEDNESDAY = 3, G_DATE_THURSDAY = 4, G_DATE_FRIDAY = 5, G_DATE_SATURDAY = 6, G_DATE_SUNDAY = 7 } GDateWeekday;
Перечисление представляющее день в неделе; G_DATE_MONDAY, G_DATE_TUESDAY, и т.д.. G_DATE_BAD_WEEKDAY недопустимый день недели.
#define G_DATE_BAD_JULIAN 0U
Представляет недопустимый номер дня в Юлианском представлении.
GDate* g_date_new (void);
Распределяет GDate
и инициализирует её до нормального сотсояния. Новая дата будет очищена
(как если бы вы вызвали g_date_clear()
)
но недопустима (она не будет представлять существующий день). Возвращаемое значение освобождается с помощью
g_date_free()
.
Возвращает : | вновь распределённая GDate. |
GDate* g_date_new_dmy (GDateDay day, GDateMonth month, GDateYear year);
Аналогична g_date_new()
,
но также устанавливает значение даты. Допустим вы помещаете в тройку день-месяц-год существующий день,
тогда возвращаемая дата будет допустимой.
day : |
день месяца. |
month : |
месяц в году. |
year : |
год |
Возвращает : | вновь распределённая GDate инициализированная с помощью
дня , месяца и года .
|
GDate* g_date_new_julian (guint32 julian_day);
Аналогична g_date_new()
, но так же устанавливает
значение даты. Допустим вы поместили допустимый Юлианский номер дня (больше чем 0, меньше чем разумно большое число),
возвращаемая дата будет допустимой.
julian_day : |
день начиная с 1 Января 1 Года (January 1, Year 1). |
Возвращает : | вновь распределённая GDate инициализированная julian_day .
|
void g_date_clear (GDate *date, guint n_dates);
Инициализирует одну или больше структур GDate
до нормального, но недопустимого состояния. Очищенные даты не будут представлять существующие даты, но не будут содержать мусор.
Полезно для инициализации дат объявленных в стеке.
Допустимость может быть проверена с помощью g_date_valid()
.
date : |
указатель на одну или более дат для очистки. |
n_dates : |
количество дат для очистки. |
void g_date_free (GDate *date);
Освобождает GDate возвращаемую из g_date_new()
.
date : |
GDate. |
void g_date_set_day (GDate *date, GDateDay day);
Устанавливает день месяца для GDate. Если результат тройки день-месяц-год недопустим, дата будет недопустимой.
date : |
GDate. |
day : |
день для установки. |
void g_date_set_month (GDate *date, GDateMonth month);
Устанавливает месяц в году для GDate. Если результат тройки день-месяц-год недопустим, дата будет недопустимой.
date : |
GDate. |
month : |
месяц для установки. |
void g_date_set_year (GDate *date, GDateYear year);
Устанавливает год для GDate. Если результат тройки день-месяц-год недопустим, дата будет недопустимой.
date : |
GDate. |
year : |
год для установки. |
void g_date_set_dmy (GDate *date, GDateDay day, GDateMonth month, GDateYear y);
Устанавливает значение GDate из дня, месяца и года.
Тройка день-месяц-год должна быть допустимой; если вы не уверены в этом, вызовите
g_date_valid_dmy()
для проверки перед установкой.
date : |
GDate. |
day : |
день. |
month : |
месяц. |
y : |
год. |
void g_date_set_julian (GDate *date, guint32 julian_date);
Устанавливает значение GDate от Юлианского номера дня.
date : |
GDate. |
julian_date : |
Юлианский номер дня (день начиная с 1 Января 1 Года). |
void g_date_set_time (GDate *date, GTime time_);
g_date_set_time
устарела и не должна использоваться во вновь создаваемом коде.
Устанавливает значение даты из значения GTime.
Устаревшее
:2.10: Вместо неё используйте g_date_set_time_t()
.
void g_date_set_time_t (GDate *date, time_t timet);
Устанавливает значение даты из значения time_t.
Для установки значения даты текущего дня, вы должны написать:
g_date_set_time_t (date, time (NULL));
date : |
GDate |
timet : |
time_t значение для установки |
Начиная с версии 2.10
void g_date_set_time_val (GDate *date, GTimeVal *timeval);
Устанавливает значение даты из значения GTimeVal.
Помните что tv_usec
член игнорируется, потомучто
GDate не может использовать дополнительную точность.
Начиная с версии 2.10
void g_date_set_parse (GDate *date, const gchar *str);
Анализирует строку пользовательского ввода str
, и пытается выяснить какую дату она представляет,
принимая во внимание текущую локаль. Если строка полностью проанализирована, дата будет доступна после вызова.
Иначе, она будет недоступна. С помощью g_date_valid()
вы должны проверить выполнен ли анализ строки успешно.
Эта функция не является соответствующей для форматированных файлов и т.п.; она не очень точна и точность её поведения изменяется в зависимости от локали. Она предназначена для эвристической подпрограммы которая предполагает что пользователь подразумевает данной строкой (в этом смысле она работает вполне прилично).
date : |
GDate для заполнения. |
str : |
строка для анализа. |
void g_date_add_days (GDate *date, guint n_days);
Увеличивает дату некоторым количеством дней. Для перемещения понедельно, добавьте weeks*7 days. Дата должна быть допустимой.
date : |
GDate для увеличения. |
n_days : |
количество дней для перемещения даты вперёд. |
void g_date_subtract_days (GDate *date, guint n_days);
Перемещение даты на некоторое количество дней в прошлое. Для понедельного перемещения, просто используйте weeks*7 days. Дата должна быть допустимой.
date : |
GDate для уменьшения. |
n_days : |
количество дней для перемещения. |
void g_date_add_months (GDate *date, guint n_months);
Увеличивает дату на некоторое количество месяцев. Если день месяца больше чем 28, эта подпрограмма может изменить день месяца (потомучто месяц назначения может не иметь такого текущего дня). Дата должна быть допустимой.
date : |
GDate для увеличения. |
n_months : |
количество месяцев для перемещения вперёд. |
void g_date_subtract_months (GDate *date, guint n_months);
Перемещает дату на некоторое количество месяцев в прошлое. Если текущий день месяца не существует в месяце назначения, день месяца может быть изменён. Дата должна быть допустимой.
date : |
GDate для уменьшения. |
n_months : |
количество месяцев для перемещения. |
void g_date_add_years (GDate *date, guint n_years);
Увеличивает дату некоторым количеством лет. Если датой является 29 Февраля, а год назначения не является високосным, дата будет изменена на 28 Февраля. Дата должна быть допустимой.
date : |
GDate для увеличения. |
n_years : |
количество лет для перемещения вперёд. |
void g_date_subtract_years (GDate *date, guint n_years);
Перемещает дату на некоторое число лет в прощлое. Если текущий день не существует в году назначения (то есть это 29 Февраля и вы перемещаетесь не в високосный год) то день изменяется на 28 Февраля. Дата должна быть допустимой.
date : |
GDate для уменьшения. |
n_years : |
число лет для перемещения. |
gint g_date_days_between (const GDate *date1, const GDate *date2);
Расчитывает число дней между двумя датами.
Если date2
находится перед date1
,
возвращается негативное значение. Обе даты должны быть допустимыми.
date1 : |
первая дата. |
date2 : |
вторая дата. |
Возвращает : | количество дней между date1 и date2 .
|
gint g_date_compare (const GDate *lhs, const GDate *rhs);
-style функции для сравнения дат. Обе даты должны быть допустимыми.
qsort()
lhs : |
первая дата для сравнения. |
rhs : |
вторая дата для сравнения. |
Возвращает : | 0 если даты равны, меньше нуля если lhs меньше чем rhs ,
больше нуля если lhs больше чем rhs .
|
void g_date_clamp (GDate *date, const GDate *min_date, const GDate *max_date);
Если date
находится перед min_date
, устанавливает date
как эквивалент min_date
.
Если date
расположена после max_date
, устанавливает date
как эквивалент max_date
.
Любой параметр min_date
и max_date
может быть NULL
. Все не-NULL
даты должны быть допустимыми.
date : |
GDate для сопоставления. |
min_date : |
минимально применимое значение для date .
|
max_date : |
максимально применимое значение для date .
|
void g_date_order (GDate *date1, GDate *date2);
Проверяет меньше ли date1
или эквивалентна date2
,
и сбрасывает значение если это не так.
date1 : |
первая дата. |
date2 : |
вторая дата. |
GDateDay g_date_get_day (const GDate *date);
Возвращает день месяца. Дата должна быть допустимой.
date : |
GDate для извлечения дня месяца. |
Возвращает : | день месяца. |
GDateMonth g_date_get_month (const GDate *date);
Возвращает месяц в году. Дата должна быть допустимой.
date : |
GDate для извлечения месяца. |
Возвращает : | месяц в году как GDateMonth. |
GDateYear g_date_get_year (const GDate *date);
Возвращает год из GDate. Дата должна быть допустимой.
date : |
GDate. |
Возвращает : | год на который выпадает дата. |
guint32 g_date_get_julian (const GDate *date);
Возвращает Юлианский день или "серийный номер" из GDate. Юлианский день - это просто номер дня начиная с 1 Января 1 Года; то есть, 1 Января 1 Года является 1 Юлианским днём; 2 Января 2 Года является 2 Юлианским днём, и т.д.. Дата должна быть допустимой.
date : |
GDate для извлечения Юлианского дня. |
Возвращает : | Юлианский день. |
GDateWeekday g_date_get_weekday (const GDate *date);
Возвращает день недели для GDate. Дата должна быть допустимой.
date : |
GDate. |
Возвращает : | день недели как GDateWeekday. |
guint g_date_get_day_of_year (const GDate *date);
Возвращаемый день в году, где 1 Января является первым днём года. Дата должна быть допустимой.
date : |
GDate для извлечения дня в году. |
Возвращает : | день в году. |
guint8 g_date_get_days_in_month (GDateMonth month, GDateYear year);
Возвращает число дней в месяце, принимая во внимание високосные годы.
month : |
месяц. |
year : |
год. |
Возвращает : | количество дней в month в течении year .
|
gboolean g_date_is_first_of_month (const GDate *date);
Возвращает TRUE
если дата является первым днём месяца.
Дата должна быть допустимой.
gboolean g_date_is_last_of_month (const GDate *date);
Возвращает TRUE
если дата является последним днём месяца.
Дата должна быть допустимой.
gboolean g_date_is_leap_year (GDateYear year);
Возвращает TRUE
если год является високосным.
year : |
год для проверки. |
Возвращает : |
TRUE если год високосный.
|
guint g_date_get_monday_week_of_year (const GDate *date);
Возвращает неделю в году, где недели начинаются с понедельника. Если дата перед первым понедельником в году, возвращается 0. Дата должна быть допустимой.
date : |
GDate. |
Возвращает : | неделя в году. |
guint8 g_date_get_monday_weeks_in_year (GDateYear year);
Возвращает количество недель в году, где недели начинаются с понедельника. Будет либо 52 либо 53. Дата должна быть допустимой. (Года всегда имеют 52 периода по 7-дней, плюс 1 или 2 дополнительных дня в зависимости от того, является ли год високосным. Эта функция в основном сообщает сколько понедельников находится в году, то есть 53 понедельника будет если один из дополнительных дней окажется понедельником.)
year : |
год. |
Возвращает : | количество понедельников в году. |
guint g_date_get_sunday_week_of_year (const GDate *date);
Возвращает неделю года на которую выпадает дата, если недели начинаются с воскресенья. Дата должна быть допустимой. Может вернуть 0 если день находится перед первым воскресеньем в году.
date : |
GDate. |
Возвращает : | номер недели. |
guint8 g_date_get_sunday_weeks_in_year (GDateYear year);
Возвращает количество недель в году, где недели начинаются с воскресенья. Будет либо 52 либо 53. Дата должна быть допустимой. (Годы всегда имеют 52 периода по 7-дней, плюс 1 или 2 дополнительных дня в зависимости от того, является ли год високосным. Эта функция в основном сообщает вам сколько воскресений в году, то есть является ли 53 воскресенье дополнительным днём года.)
year : |
год для подсчёта недель. |
Возвращает : | количество недель. |
guint g_date_get_iso8601_week_of_year (const GDate *date);
Возвращает неделю года, где недели интерпретируются согласно ISO 8601.
date : |
допустимая GDate |
Возвращает : | ISO 8601 число недель в году. |
Начиная с версии 2.6
gsize g_date_strftime (gchar *s, gsize slen, const gchar *format, const GDate *date);
Генерирует печатное представление даты, локале-зависимым способом. Работает просто как платформенная C библиотечная функция
, но принимает только дата-зависимые форматы;
время-зависимые форматы выдают неопределённый результат. Дата должна быть допустимой.
В отличие от strftime()
(которая использует локальную кодировку), эта функция работает со строками в кодировке UTF-8 и сохраняет результат в кодировке UTF-8.
strftime()
Эта функция не обеспечивает никаких дополнительных спецификаторов конвертирования для платформенной реализации библиотеки C.
Например, не ждите что использование
сделает g_date_strftime()
F
обеспечив C99
работая на Windows где библиотека C скомпилирована только для C89.
strftime()
s : |
буфер назначения. |
slen : |
размер буфера. |
format : |
строка формата. |
date : |
допустимая GDate. |
Возвращает : | количество символов записанных в буфер, или 0 если буфер слишком маленький. |
void g_date_to_struct_tm (const GDate *date, struct tm *tm);
Заполняет дата-зависимый бит в struct tm
используя значение date
. Инициализирует non-date пары с чем то
нормальным но бессмысленным.
date : |
GDate для установки struct tm. |
tm : |
struct tm для заполнения. |
gboolean g_date_valid (const GDate *date);
Возвращает TRUE
если GDate представляет существующий день. Дата не должна содержать мусор;
она должна быть инициализирована с помощью g_date_clear()
если она не была распределена одним из вариантов g_date_new()
.
date : |
GDate для проверки. |
Возвращает : | является ли дата допустимой. |
gboolean g_date_valid_day (GDateDay day);
Возвращает TRUE
если день месяца допустим
(день допустим если он находится в промежутке чисел от 1 до 31 включительно).
day : |
день для проверки. |
Возвращает : |
TRUE если день допустим.
|
gboolean g_date_valid_month (GDateMonth month);
Возвращает TRUE
если значение месяца допустимо.
Только 12 значений в перечислении GDateMonth
являются допустимыми.
month : |
месяц. |
Возвращает : |
TRUE если месяц допустим.
|
gboolean g_date_valid_year (GDateYear year);
Возвращает TRUE
если год допустим.
Допустимым является год только больше 0, однако есть 16-битный предел того что может понять GDate.
year : |
год. |
Возвращает : |
TRUE если год допустим.
|
gboolean g_date_valid_dmy (GDateDay day, GDateMonth month, GDateYear year);
Возвращает TRUE
если форма триплёта день-месяц-год допустима,
существует понятный день в диапазоне дней GDate
(1 год или больше, но не больше нескольких тысяч лет в будущее).
day : |
день. |
month : |
месяц. |
year : |
год. |
Возвращает : |
TRUE если дата допустима.
|
gboolean g_date_valid_julian (guint32 julian_date);
Возвращает TRUE
ели Юлианский день допустим.
Число больше нуля в основном является допустимым Юлианским днём, однако есть 32-битный предел.
julian_date : |
Юлианский день для проверки. |
Возвращает : |
TRUE если Юлианский день допустим.
|
gboolean g_date_valid_weekday (GDateWeekday weekday);
Возвращает TRUE
если день недели допустим.
Только 7 значений в перечислении GDateWeekday
являются допустимыми.
weekday : |
день недели. |
Возвращает : |
TRUE если день недели допустим.
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GQueue; GQueue* g_queue_new (void); void g_queue_free (GQueue *queue); gboolean g_queue_is_empty (GQueue *queue); guint g_queue_get_length (GQueue *queue); void g_queue_reverse (GQueue *queue); GQueue* g_queue_copy (GQueue *queue); void g_queue_foreach (GQueue *queue, GFunc func, gpointer user_data); GList* g_queue_find (GQueue *queue, gconstpointer data); GList* g_queue_find_custom (GQueue *queue, gconstpointer data, GCompareFunc func); void g_queue_sort (GQueue *queue, GCompareDataFunc compare_func, gpointer user_data); void g_queue_push_head (GQueue *queue, gpointer data); void g_queue_push_tail (GQueue *queue, gpointer data); void g_queue_push_nth (GQueue *queue, gpointer data, gint n); gpointer g_queue_pop_head (GQueue *queue); gpointer g_queue_pop_tail (GQueue *queue); gpointer g_queue_pop_nth (GQueue *queue, guint n); gpointer g_queue_peek_head (GQueue *queue); gpointer g_queue_peek_tail (GQueue *queue); gpointer g_queue_peek_nth (GQueue *queue, guint n); gint g_queue_index (GQueue *queue, gconstpointer data); void g_queue_remove (GQueue *queue, gconstpointer data); void g_queue_remove_all (GQueue *queue, gconstpointer data); void g_queue_insert_before (GQueue *queue, GList *sibling, gpointer data); void g_queue_insert_after (GQueue *queue, GList *sibling, gpointer data); void g_queue_insert_sorted (GQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data); void g_queue_push_head_link (GQueue *queue, GList *link_); void g_queue_push_tail_link (GQueue *queue, GList *link_); void g_queue_push_nth_link (GQueue *queue, gint n, GList *link_); GList* g_queue_pop_head_link (GQueue *queue); GList* g_queue_pop_tail_link (GQueue *queue); GList* g_queue_pop_nth_link (GQueue *queue, guint n); GList* g_queue_peek_head_link (GQueue *queue); GList* g_queue_peek_tail_link (GQueue *queue); GList* g_queue_peek_nth_link (GQueue *queue, guint n); gint g_queue_link_index (GQueue *queue, GList *link_); void g_queue_unlink (GQueue *queue, GList *link_); void g_queue_delete_link (GQueue *queue, GList *link_);
Структура GQueue и связанные с ней функции обеспечивают стандартную очередь структур данных. Внутренне, GQueue использует для хранения элементов те же структуры что и GList.
Данные содержащиеся в каждом элементе могут быть либо целочисленными значениями, используя Type Conversion Macros, или просто указатели на любой тип данных.
Для создания новой GQueue,
используйте g_queue_new()
.
Для добавления элементов, используйте g_queue_push_head()
, g_queue_push_head_link()
,
g_queue_push_tail()
and g_queue_push_tail_link()
.
Для удаления элементов, используйте g_queue_pop_head()
и g_queue_pop_tail()
.
Для освобождения элементов очереди, используйте g_queue_free()
.
typedef struct { GList *head; GList *tail; guint length; } GQueue;
Содержит общедоступные поля Queue.
void g_queue_free (GQueue *queue);
Освобождает память распределённую для GQueue.
queue : |
GQueue. |
guint g_queue_get_length (GQueue *queue);
Возвращает количество элементов в queue
.
queue : |
GQueue |
Возвращает : | Количество элементов в queue .
|
Начиная с версии 2.4
void g_queue_reverse (GQueue *queue);
Переворачивает направление элементов в queue
.
queue : |
GQueue |
Начиная с версии 2.4
GQueue* g_queue_copy (GQueue *queue);
Копирует queue
. Помните что это поверхностная копия. Если очередь содержит указатели на данные,
то указатели копируются, а фактические данные нет.
queue : |
GQueue |
Возвращает : | копия queue
|
Начиная с версии 2.4
void g_queue_foreach (GQueue *queue, GFunc func, gpointer user_data);
Вызывает функцию func
для каждого элемента в очереди помещая
user_data
в функцию.
queue : |
GQueue |
func : |
функция вызываемая для каждого элемента данных |
user_data : |
пользовательские данные помещаемые в func
|
Начиная с версии 2.4
GList* g_queue_find (GQueue *queue, gconstpointer data);
Находит первую связь в queue
которая содержит data
.
queue : |
GQueue |
data : |
данные для поиска |
Возвращает : | Первая связь в queue которая содержит data .
|
Начиная с версии 2.4
GList* g_queue_find_custom (GQueue *queue, gconstpointer data, GCompareFunc func);
Находит элемент в GQueue, используя полученную функцию для поиска желаемого элемента. Она передвигается через очередь, вызывая полученную функцию которая должна вернуть 0 когда желаемый элемент найден. Функция принимает два аргумента gconstpointer, элементы данных GQueue как первый аргумент и полученные пользовательские данные как второй аргумент.
queue : |
GQueue |
data : |
пользовательские данные помещаемые в func
|
func : |
GCompareFunc вызываемая для каждого элемента. Она должна вернуть 0 когда желаемый элемент найден. |
Возвращает : | Найденный элемент, или NULL если не найден.
|
Начиная с версии 2.4
void g_queue_sort (GQueue *queue, GCompareDataFunc compare_func, gpointer user_data);
Сортирует queue
используя compare_func
.
queue : |
GQueue |
compare_func : |
GCompareDataFunc используемая для сортировки
queue . В эту функцию помещаются два элемента очереди и она должна вернуть 0 если они равны,
отрицательное значение если первый располагается перед вторым, а положительное если второй располагается перед первым.
|
user_data : |
пользовательские данные помещаемые в compare_func
|
Начиная с версии 2.4
void g_queue_push_head (GQueue *queue, gpointer data);
Добавляет новый элемент первым в очередь.
queue : |
GQueue. |
data : |
данные для нового элемента. |
void g_queue_push_tail (GQueue *queue, gpointer data);
Добавляет новый элемент в конец очереди.
queue : |
GQueue. |
data : |
данные для нового элемента. |
void g_queue_push_nth (GQueue *queue, gpointer data, gint n);
Вставляет новый элемент в queue
в указанную позицию.
queue : |
GQueue |
data : |
данные для нового элемента |
n : |
позиция расположения нового элемента. Если n отрицательное или
больше чем число элементов в queue , элемент добавляемый в конец очереди.
|
Начиная с версии 2.4
gpointer g_queue_pop_tail (GQueue *queue);
Удаляет последний элемент из очереди.
gpointer g_queue_pop_nth (GQueue *queue, guint n);
Удаляет n
элемент в queue
.
queue : |
GQueue |
n : |
позиция элемента. |
Возвращает : | данные элемента, или NULL
если n выходит за пределы queue .
|
Начиная с версии 2.4
gpointer g_queue_peek_tail (GQueue *queue);
Возвращает последний элемент в очереди.
gpointer g_queue_peek_nth (GQueue *queue, guint n);
Возвращает n
элемент в queue
.
queue : |
GQueue |
n : |
позиция элемента. |
Возвращает : | Данные для n элемента в queue ,
или NULL если n
выходит за пределы queue .
|
Начиная с версии 2.4
gint g_queue_index (GQueue *queue, gconstpointer data);
Возвращает позицию первого элемента в queue
который содержит data
.
queue : |
GQueue |
data : |
данные для поиска. |
Возвращает : | Позиция первого элемента в queue который содержит data ,
или -1 если нет элемента в queue содержащего data .
|
Начиная с версии 2.4
void g_queue_remove (GQueue *queue, gconstpointer data);
Удаляет первый элемент в queue
который содержит data
.
queue : |
GQueue |
data : |
удаляемые данные. |
Начиная с версии 2.4
void g_queue_remove_all (GQueue *queue, gconstpointer data);
Удаляет все элементы в queue
которые содержат data
.
queue : |
GQueue |
data : |
данные для удаления |
Начиная с версии 2.4
void g_queue_insert_before (GQueue *queue, GList *sibling, gpointer data);
Вставляет data
в queue
перед
sibling
.
sibling
должен быть частью queue
.
Начиная с версии 2.4
void g_queue_insert_after (GQueue *queue, GList *sibling, gpointer data);
Вставляет data
в queue
после
sibling
sibling
должен быть частью queue
Начиная с версии 2.4
void g_queue_insert_sorted (GQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data);
Вставляет data
в queue
используя
func
для определения новой позиции.
queue : |
GQueue |
data : |
вставляемые данные |
func : |
GCompareDataFunc используется для сравнения
элементов в очереди. Она вызывается с двумя элементами, queue и
user_data . Должна вернуть 0 если элементы равны, отрицательное значение если первый
элемент располагается перед вторым, а положительное значение если второй элемент располагается перед первым.
|
user_data : |
пользовательские данные помещаемые в func .
|
Начиная с версии 2.4
void g_queue_push_head_link (GQueue *queue, GList *link_);
Добавляет новый элемент первым в очередь.
void g_queue_push_tail_link (GQueue *queue, GList *link_);
Добавляет новый элемент в конец очереди.
void g_queue_push_nth_link (GQueue *queue, gint n, GList *link_);
Вставляет link
в полученную позицию queue
.
queue : |
GQueue |
n : |
позиция для вставки узла. Если отрицательное или больше чем количество элементов в
queue , узел добавляется в конец
queue .
|
link_ : |
узел добавляемый в queue
|
Начиная с версии 2.4
GList* g_queue_pop_head_link (GQueue *queue);
Удаляет первый элемент в очереди.
GList* g_queue_pop_tail_link (GQueue *queue);
Удаляет последний элемент в очереди.
GList* g_queue_pop_nth_link (GQueue *queue, guint n);
Удаляет и возвращает узел в полученной позиции.
Начиная с версии 2.4
GList* g_queue_peek_head_link (GQueue *queue);
Возвращает первый узел в queue
Начиная с версии 2.4
GList* g_queue_peek_tail_link (GQueue *queue);
Возвращает последний узел queue
.
Начиная с версии 2.4
GList* g_queue_peek_nth_link (GQueue *queue, guint n);
Возвращает узел из полученной позиции
queue : |
GQueue |
n : |
позиция узла |
Возвращает : | узел из n -ной позиции, или
NULL
если n выходит за пределы очереди
|
Начиная с версии 2.4
gint g_queue_link_index (GQueue *queue, GList *link_);
Возвращает позицию link_
в queue
.
queue : |
Gqueue |
link_ : |
элемент GList |
Возвращает : | позиция link_ , или -1 если узел не часть queue
|
Начиная с версии 2.4
void g_queue_unlink (GQueue *queue, GList *link_);
Сбрасывает link_
так чтобы он не был больше частью queue
.
Узел не освобождается.
link_
должен быть частью queue
,
Начиная с версии 2.4
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Doubly-Linked ListsDoubly-Linked Lists — Связанные списки содержащие целочисленные значения или указатели на данные, с возможностью выполнения итерации по списку в обоих направлениях. |
#include <glib.h> GList; GList* g_list_append (GList *list, gpointer data); GList* g_list_prepend (GList *list, gpointer data); GList* g_list_insert (GList *list, gpointer data, gint position); GList* g_list_insert_before (GList *list, GList *sibling, gpointer data); GList* g_list_insert_sorted (GList *list, gpointer data, GCompareFunc func); GList* g_list_remove (GList *list, gconstpointer data); GList* g_list_remove_link (GList *list, GList *llink); GList* g_list_delete_link (GList *list, GList *link_); GList* g_list_remove_all (GList *list, gconstpointer data); void g_list_free (GList *list); GList* g_list_alloc (void); void g_list_free_1 (GList *list); #define g_list_free1 guint g_list_length (GList *list); GList* g_list_copy (GList *list); GList* g_list_reverse (GList *list); GList* g_list_sort (GList *list, GCompareFunc compare_func); gint (*GCompareFunc) (gconstpointer a, gconstpointer b); GList* g_list_insert_sorted_with_data (GList *list, gpointer data, GCompareDataFunc func, gpointer user_data); GList* g_list_sort_with_data (GList *list, GCompareDataFunc compare_func, gpointer user_data); gint (*GCompareDataFunc) (gconstpointer a, gconstpointer b, gpointer user_data); GList* g_list_concat (GList *list1, GList *list2); void g_list_foreach (GList *list, GFunc func, gpointer user_data); void (*GFunc) (gpointer data, gpointer user_data); GList* g_list_first (GList *list); GList* g_list_last (GList *list); #define g_list_previous (list) #define g_list_next (list) GList* g_list_nth (GList *list, guint n); gpointer g_list_nth_data (GList *list, guint n); GList* g_list_nth_prev (GList *list, guint n); GList* g_list_find (GList *list, gconstpointer data); GList* g_list_find_custom (GList *list, gconstpointer data, GCompareFunc func); gint g_list_position (GList *list, GList *llink); gint g_list_index (GList *list, gconstpointer data); void g_list_push_allocator (gpointer allocator); void g_list_pop_allocator (void);
Структура GList и связанные с ней функции обеспечивают стандартный двусвязный список структур данных.
Каждый элемент в списке содержит часть данных, вместе с указателями которые связаны с предыдущим и следующим элементом списка. Использование этих указателей позволяет элементам перемещаться через список в обоих направлениях (в отличие от односвязных списков, которые позволяют перемещение по списку только вперёд).
Данные содержащиеся в каждом элементе могут быть либо целочисленными значениями, при использовании одного из Type Conversion Macros, либо простыми указателями на любой тип данных.
Список элементов распределяется с помощью slice allocator, что более эффективно чем индивидуальное распределение элементов.
Помите что большинство функций GList предполагают помещение указателя на первый элемент в списке. Функции которые вставляют элементы, возвращают новое начало списка, которое может быть изменено.
Нет функции для создания GList.
NULL
рассматривается как пустой список,
поэтому вы можете просто установить GList*
в значение NULL
.
Для добавления элементов используйте g_list_append()
,
g_list_prepend()
,
g_list_insert()
и
g_list_insert_sorted()
.
Для удаления элементов используйте g_list_remove()
.
Для поиска элементов в списке используйте g_list_first()
, g_list_last()
, g_list_next()
,
g_list_previous()
, g_list_nth()
, g_list_nth_data()
, g_list_find()
и
g_list_find_custom()
.
Для поиска номера элемента используйте g_list_position()
и g_list_index()
.
Для вызова функции для каждого элемента в списке используйте g_list_foreach()
.
Для освобождения полей списка используйте g_list_free()
.
typedef struct { gpointer data; GList *next; GList *prev; } GList;
Структура GList используется для каждого элемента двусвязного списка.
gpointer data ; |
содержит элементы данных, которые могут быть указателем на любой вид данных, или любым целочисленным значением используя Type Conversion Macros. |
GList *next ; |
содержит ссылку на следующий элемент в списке. |
GList *prev ; |
содержит ссылку на предыдущий элемент в списке. |
GList* g_list_append (GList *list, gpointer data);
Добавляет новый элемент в конец списка.
Возвращаемое значение является новым началом списка, которое может быть изменено, поэтому убедитесь что вы сохранили новое значение.
Помните что g_list_append()
должен пересечь все поля списка для нахождения конца, это не эффективно при добавлении множества элементов.
Основная идиома в исключении неэффективности в том, чтобы приставлять элементы а затем перевернуть список,
когда все элементы будут добавлены.
/* Помните что это инициализирует пустой список. */ GList *list = NULL, *number_list = NULL; /* Это список строк. */ list = g_list_append (list, "first"); list = g_list_append (list, "second"); /* Это список целочисленных. */ number_list = g_list_append (number_list, GINT_TO_POINTER (27)); number_list = g_list_append (number_list, GINT_TO_POINTER (14));
GList* g_list_prepend (GList *list, gpointer data);
Добавляет новый элемент в начало списка.
Возвращаемое значение является новым началом списка, которое может изменится, поэтому убедитесь что вы сохранили новое значение.
/* Помните что это инициализирует пустой список. */ GList *list = NULL; list = g_list_prepend (list, "last"); list = g_list_prepend (list, "first");
GList* g_list_insert (GList *list, gpointer data, gint position);
Вставляет новый элемент в список в полученную позицию.
GList* g_list_insert_before (GList *list, GList *sibling, gpointer data);
Вставляет новый элемент в список перед полученной позицией.
GList* g_list_insert_sorted (GList *list, gpointer data, GCompareFunc func);
Вставляет новый элемент в список, использует полученную функцию сравнения для определения позиции.
GList* g_list_remove (GList *list, gconstpointer data);
Удаляет элемент из GList. Если два элемента содержат одинаковые данные, удаляется только первый. Если нет элементов содержащих данные, GList не изменяется.
GList* g_list_remove_link (GList *list, GList *llink);
Удаляет элемент из GList, без освобождения элемента.
У удалённого элемента ссылки на предыдущий и следующий устанавливаются в
NULL
, так чтобы он стал списком с единственным элементом.
GList* g_list_delete_link (GList *list, GList *link_);
Удаляет узел link_
из list
.
list : |
GList. |
link_ : |
узел для удаления из list .
|
Возвращает : | новый первый элемент list .
|
GList* g_list_remove_all (GList *list, gconstpointer data);
Удаляет все узлы списка с данными равными data
. Возвращает новый первый элемент списка.
В отличие от g_list_remove()
,
которая удаляет только первый узел соответствующий полученным данным.
list : |
GList. |
data : |
удаляемые данные. |
Возвращает : | новый первый элемент list .
|
void g_list_free (GList *list);
Освобождает всю память используемую GList. Освобождает элементы возвращаемые распределителем слайсов.
Если первый элемент содержит динамически-распределённую память, он должен быть освобождён первым.
list : |
GList. |
GList* g_list_alloc (void);
Распределяет пространство для одного элемента GList.
Она вызывается с помощью g_list_append()
,
g_list_prepend()
,
g_list_insert()
и
g_list_insert_sorted()
и очень редко используется самостоятельно.
Возвращает : | указатель для вновь распределённого элемента GList. |
void g_list_free_1 (GList *list);
Освобождает один элемент GList.
Она в основном используется после g_list_remove_link()
.
list : |
элемент GList. |
GList* g_list_copy (GList *list);
Копирует GList.
Помните что это "пустая" копия. Если список элементов содержит указатели на данные, указатели копируются, а реальные данные нет.
list : |
GList. |
Возвращает : | копия list .
|
GList* g_list_reverse (GList *list);
Переворачивает GList. Она просто переключает предыдущие и следующие указатели в каждом элементе.
GList* g_list_sort (GList *list, GCompareFunc compare_func);
Сортирует GList используя полученную функцию для сравнения.
list : |
GList. |
compare_func : |
функция сравнения используемая для сортировки GList. Функция принимает данные из двух элементов GList и должна вернуть 0 если они равны, отрицательное значение если первый элемент помещается перед вторым, или положительное значение если первый элемент помещается после второго. |
Возвращает : | начало отсортированной GList. |
gint (*GCompareFunc) (gconstpointer a, gconstpointer b);
Определяет тип сравнивающей функции используемой для сравнения двух значений. Функция должна возвращать отрицательное целочисленное если первое значение расположено перед вторым, 0 если они равны, или положительное целочисленное если первое значение расположено после второго.
a : |
первое значение. |
b : |
значение для сравнения. |
Возвращает : | отрицательное значение если a < b ;
ноль если a = b ;
положительное значение если a > b .
|
GList* g_list_insert_sorted_with_data (GList *list, gpointer data, GCompareDataFunc func, gpointer user_data);
Вставляет новый элемент в список, используя полученную функцию сравнения для определения их положения.
list : |
указатель на GList. |
data : |
данные для нового элемента. |
func : |
функция для сравнения элементов всписке. Она должна вернуть число > 0 если первый параметр расположен после второго параметра в порядке сортировки. |
user_data : |
данные помещаемые в функцию сравнения. |
Возвращает : | новое начало GList.
Начиная с версии 2.10
|
GList* g_list_sort_with_data (GList *list, GCompareDataFunc compare_func, gpointer user_data);
Похожа на g_list_sort()
,
но функция сравнения принимает параметр пользовательских данных.
list : |
GList. |
compare_func : |
функция сравнения. |
user_data : |
пользовательские данные помещаемые в функцию сравнения. |
Возвращает : | новый первый элемент list .
|
gint (*GCompareDataFunc) (gconstpointer a, gconstpointer b, gpointer user_data);
Определяет тип функции сравнения используемой для сравнения двух значений. Функция должна возвращать отрицательное целочисленное если первое значение располагается перед вторым, 0 если они равны, или положительное целочисленное если первое значение располагается после второго.
a : |
первое значение. |
b : |
значение для сравнения. |
user_data : |
данные помещаемые в функцию сравнения. |
Возвращает : | отрицательное значение если a < b ;
ноль если a = b ;
положительное значение если a > b .
|
GList* g_list_concat (GList *list1, GList *list2);
Добавляет второй GList в конец первого GList. Помните что элементы второго GList не копируются. Они используются на прямую.
void g_list_foreach (GList *list, GFunc func, gpointer user_data);
Вызывает функцию для каждого элемента GList.
list : |
GList. |
func : |
функция вызываемая для каждого элемента данных. |
user_data : |
данные помещаемые в функцию. |
void (*GFunc) (gpointer data, gpointer user_data);
Определяет тип функции помещаемой в g_list_foreach()
и g_slist_foreach()
.
data : |
элементы данных. |
user_data : |
данные помещаемые в g_list_foreach()
или g_slist_foreach() .
|
#define g_list_previous(list)
Удобный макрос для получения предыдущего элемента в GList.
gpointer g_list_nth_data (GList *list, guint n);
Определяет данные элемента в указанной позиции.
GList* g_list_nth_prev (GList *list, guint n);
Определяет элемент n
помещаемый перед list
.
GList* g_list_find (GList *list, gconstpointer data);
Находит элемент в GList который содержит полученные данные.
GList* g_list_find_custom (GList *list, gconstpointer data, GCompareFunc func);
Ищет элемент в GList, используя предоставленную функцию для поиска желаемого элемента. Она перемещается по списку, вызывая полученную функцию которая должна вернуть 0 когда желаемый элемент найден. Функция принимает два аргумента gconstpointer, элемент данных GList как первый аргумент и полученные пользовательские данные.
gint g_list_position (GList *list, GList *llink);
Определяет позицию полученного элемента в GList (начиная с 0).
gint g_list_index (GList *list, gconstpointer data);
Определяет позицию элемента содержащего полученные данные (начиная с 0).
list : |
GList. |
data : |
искомые данные. |
Возвращает : | перечень элементов содержащих данные, или -1 если данные не найдены. |
void g_list_push_allocator (gpointer allocator);
g_list_push_allocator
устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде.
Она ничего не делает, так как GList был конвертирован в
slice allocator
Заставляет использовать распределитель для распределения элементов GList.
Использует g_list_pop_allocator()
для восстановления предыдущего распределения.
Помните что эта функция не доступна если GLib скомпилирована с опцией --disable-mem-pools
allocator : |
GAllocator используемый для распределения элементов GList. |
void g_list_pop_allocator (void);
g_list_pop_allocator
устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде.
Она ничего не делает, так как GList был конвертирован в
slice allocator
Восстанавливает предыдущий GAllocator, используемый для распределения элементов GList.
Помните что эта функция недоступна если GLib скомпилирована с опцией --disable-mem-pools
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Dynamic Loading of ModulesDynamic Loading of Modules — Переносимый способ для динамической загрузки 'plug-ins'. |
#include <gmodule.h> GModule; gboolean g_module_supported (void); gchar* g_module_build_path (const gchar *directory, const gchar *module_name); GModule* g_module_open (const gchar *file_name, GModuleFlags flags); enum GModuleFlags; gboolean g_module_symbol (GModule *module, const gchar *symbol_name, gpointer *symbol); const gchar* g_module_name (GModule *module); void g_module_make_resident (GModule *module); gboolean g_module_close (GModule *module); const gchar* g_module_error (void); const gchar* (*GModuleCheckInit) (GModule *module); void (*GModuleUnload) (GModule *module); #define G_MODULE_SUFFIX #define G_MODULE_EXPORT #define G_MODULE_IMPORT
Эти функции обеспечивают переносимый способ динамической загрузки объектных файлов
(известны как 'plug-ins').
Текущая реализация поддерживает все системы которые обеспечивают выполнение
(например Linux/Sun), а также
HP-UX через механизм dlopen()
и
Windows через DLLs.
shl_load()
Программы которые предполагается использовать с этими функциями должны быть слинкованы с библиотеками вывода (output) с помощью команды pkg-config --libs gmodule-2.0.
Для их использования вы сначала должны определить поддерживается ли динамическая загрузка на
используемой платформе с помощью вызова g_module_supported()
.
Если поддерживается, то вы можете открывать модули с помощью g_module_open()
,
искать модульные идентификаторы (например имена функций) с помощью g_module_symbol()
,
а затем закрывать модули с помощью g_module_close()
.
g_module_name()
возвращает имя файла текущего открытого модуля.
Если любая из описанных выше функций завершается неудачей, описание ошибки можно найти с помощью
g_module_error()
.
GModule реализует особенность подсчета ссылок для открытых модулей и поддержку функций обработки прерываний в модуле, которая вызывается когда модуль загружается и выгружается (смотрите GModuleCheckInit и GModuleUnload).
Если ваш модуль вводит статические данные для общих подсистем в выполняемой программе,
например через вызов g_quark_from_static_string ("my-module-stuff")
,
он должен быть уверен что никогда не выгрузится с помощью вызова g_module_make_resident()
.
Пример 12. Calling a function defined in a GModule
/* Подпись функции для 'say_hello' */ typedef void (* SayHelloFunc) (const char *message); gboolean just_say_hello (const char *filename, GError **error) { SayHelloFunc say_hello; GModule *module; module = g_module_open (filename, G_MODULE_BIND_LAZY); if (!module) { g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH, "%s", g_module_error ()); return FALSE; } if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello)) { g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN, "%s: %s", filename, g_module_error ()); if (!g_module_close (module)) g_warning ("%s: %s", filename, g_module_error ()); return FALSE; } /* вызываем нашу функцию в модуле */ say_hello ("Hello world!"); if (!g_module_close (module)) g_warning ("%s: %s", filename, g_module_error ()); return TRUE; }
typedef struct _GModule GModule;
Непрозрачная структура данных GModule представляет Dynamically-Loaded Module. Доступ к ней должен осуществляться только с помощью функций описанных ниже.
gboolean g_module_supported (void);
Проверяет поддерживается ли модуль текущей платформой.
Возвращает : |
TRUE если модуль поддерживается.
|
gchar* g_module_build_path (const gchar *directory, const gchar *module_name);
Переносимый способ создания имени файла модуля. Платформо-специфичные префикс и суффикс добавляются для имени файла, если необходимо и результат добавляется в каталог, используя правильный символьный разделитель.
Параметр directory должен определять каталог где где может быть найден модуль.
Он может быть NULL
или пустой строкой указывая что модуль находится в стандартном платформо-зависимом каталоге, хотя это не рекомендуется, так как может быть найден неправильный модуль.
Например, вызов g_module_build_path()
в системе Linux с параметром directory
равным значению /lib
и параметром module_name
равным значению "mylibrary" вернёт
/lib/libmylibrary.so
. В системе Windows, использование \Windows
как значение параметра directory
вернёт \Windows\mylibrary.dll
.
directory : |
каталог где находится модуль. Может быть NULL или пустой строкой указывая что
используется стандартный платформо-зависимый каталог, хотя это не рекомендуется.
|
module_name : |
имя модуля. |
Возвращает : | абсолютный путь модуля, включая стандартный библиотечный префикс и суффикс. Должен освобождаться когда больше не нужен. |
GModule* g_module_open (const gchar *file_name, GModuleFlags flags);
Открывает модуль. Если модуль уже открыт, то увеличивает количество ссылок.
Прежде всего g_module_open()
пытается открыть file_name
как модуль. Если это не удаётся и file_name
имеет суффикс ".la" (и есть архив libtool), она пробует открыть соответствующий модуль.
Если терпит неудачу и он не имеет надлежащего суффикса модуля для платформы
(G_MODULE_SUFFIX), этот суффикс будет приставлен и соответствующий модуль будет открыт.
Если это не удаётся и file_name
не имеет суффикса ".la",
этот суффикс подставляется и g_module_open()
пытается открыть соответствующий модуль.
Если и это не удаётся, то возвращается NULL
.
file_name : |
имя файла содержащего модуль, или NULL
для получения GModule представляющую непосредственно основную программу.
|
flags : |
флаги используемые для открытия модуля. Это может быть логическое ИЛИ любого из GModuleFlags. |
Возвращает : | GModule если выполнено удачно, или NULL если неудачно.
|
typedef enum { G_MODULE_BIND_LAZY = 1 << 0, G_MODULE_BIND_LOCAL = 1 << 1, G_MODULE_BIND_MASK = 0x03 } GModuleFlags;
Флаги помещаемые в g_module_open()
. Помните что эти флаги поддерживаются на всех платформах.
gboolean g_module_symbol (GModule *module, const gchar *symbol_name, gpointer *symbol);
Получает указатель символа из модуля.
const gchar* g_module_name (GModule *module);
Получает имя файла из GModule.
module : |
GModule. |
Возвращает : | имя файла модуля, или "main" если модуль непосредственно основная программа. |
void g_module_make_resident (GModule *module);
Гарантирует что модуль не будет выгружен.
Любые вызовы g_module_close()
для модуля будут игнорироваться в последствии.
module : |
GModule для постоянного нахождения в памяти. |
const gchar* g_module_error (void);
Получает строку описывающую последнюю ошибку модуля.
Возвращает : | строка описывающая последнюю ошибку модуля. |
const gchar* (*GModuleCheckInit) (GModule *module);
Определяет тип функции инициализации модуля.
Если модуль содержит функцию с именем g_module_check_init()
она вызывается автоматически при загрузке модуля.
В неё помещается структура GModule и она должна вернуть NULL
при успешном выполнении инициализации, или строку описывающую ошибку.
void (*GModuleUnload) (GModule *module);
Определяет тип модульной функции вызываемой при выгрузке.
Если модуль содержит функцию с именем g_module_unload()
она вызывается автоматически при выгрузке модуля.
В неё помещается структура GModule.
module : |
GModule который выгружается. |
#define G_MODULE_SUFFIX "so"
Расширение для надлежащего обще-библиотечного суффикса текущей платформы, без точки. Для большинства версий Uniх и Linux это "so", для некоторых версий HP-UX это "sl", а для Windows это "dll".
#define G_MODULE_EXPORT
Используется для декларации функций экспортируемых модулями.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GError; GError* g_error_new (GQuark domain, gint code, const gchar *format, ...); GError* g_error_new_literal (GQuark domain, gint code, const gchar *message); void g_error_free (GError *error); GError* g_error_copy (const GError *error); gboolean g_error_matches (const GError *error, GQuark domain, gint code); void g_set_error (GError **err, GQuark domain, gint code, const gchar *format, ...); void g_propagate_error (GError **dest, GError *src); void g_clear_error (GError **err);
GLib обеспечивает стандартный метод сообщения об ошибках из вызванной функции в вызываемом коде. (Это также решает проблему исключительной ситуации в других языках). Важно понять что это метод - data type (GError объект) и набора правил. Если вы используете GError неправильно, то ваш код не будет правильно взаимодействовать с другим кодом использующим GError, а пользователи вашего API вероятно запутаются.
Прежде всего: GError должен использоваться только для сообщения о восстанавливаемых ошибках в процессе выполнения.
Обычно вы должны использовать g_warning()
,
g_return_if_fail()
, g_assert()
, g_error()
, или похожее средство.
(помните что функция g_error()
должна использоваться
только для программных ошибок, она не должна использоваться для печати любой ошибки о которой сообщено через GError.)
Примером восстанавливаемых ошибок во время выполнения программы являются
"file not found" (файл не найден) или "failed to parse input" (не удаётся проанализировать ввод).
Примером программных ошибок являются "NULL passed to strcmp()
" или
"attempted to free the same pointer twice". Эти два вида ошибок существенно отличаются:
ошибки во время выполнения должны обрабатываться или о них должно быть сообщено пользователю,
програмные ошибки должны ликвидироваться исправлением в программе.
Поэтому большинство функций в GLib и GTK+ не используют GError.
Функции которые могут завершиться неудачно принимают в качестве последнего параметра место расположения возвращаемой GError. Например:
gboolean g_file_get_contents (const gchar *filename, gchar **contents, gsize *length, GError **error);
Если вы поместили не-NULL
значение в параметр error
, он должен указывать на место куда может быть помещена ошибка. Например:
gchar *contents; GError *err = NULL; g_file_get_contents ("foo.txt", &contents, NULL, &err); g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); if (err != NULL) { /* Сообщаем об ошибке пользователю, и освобождаем ошибку */ g_assert (contents == NULL); fprintf (stderr, "Unable to read file: %s\n", err->message); g_error_free (err); } else { /* Используем содержимое файла */ g_assert (contents != NULL); }
Помните что err != NULL
в этом примере
надежно проверяет не закончилась ли неудачей
g_file_get_contents()
. Дополнительно, g_file_get_contents()
возвращает логическое которое указывает была ли она завершена удачно.
Поскольку g_file_get_contents()
возвращает FALSE
при неудаче, если вы интересуетесь только статусом завершения и не нуждаетесь в
отображении сообщения об ошибке, вы можете поместить NULL
в параметр error
:
if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* игнорирование ошибок */ /* нет произошедших ошибок */ ; else /* ошибка */ ;
Объект GError содержит три поля: domain
указывает функцию сообщения об ошибках,
code
указывает произошедшую специфическую ошибку,
а message
читабельное для пользователя сообщение которое более
детально описывает ошибку насколько это возможно. Некоторые функции предназначены для связи с
ошибкой полученной из вызываемой функции:
g_error_matches()
возвращает TRUE
если ошибка соответствует данной domain и code,
g_propagate_error()
копирует ошибку в место хранения ошибки (таким образом вызываемая функция получает её),
а g_clear_error()
очищает место расположения ошибки освобождая ошибку и переустанавливая место хранения ошибки в
NULL
.
Для отображения ошибки пользователю, просто отобразите
error->message
, возможно наряду с дополнительным контекстом
известным только вызываемой функции (открываемый файл, или любой -- хотя в случае g_file_get_contents()
,
error->message
уже содержит имя файла).
При реализации функций способных сообщать об ошибках основной инструмент g_set_error()
.
Обычно, если происходит фатальная ошибка вам необходима g_set_error()
,
затем немедленное возвращение. g_set_error()
ничего не делает если расположение ошибки помещённое в неё NULL
. Например:
gint foo_open_file (GError **error) { gint fd; fd = open ("file.txt", O_RDONLY); if (fd < 0) { g_set_error (error, FOO_ERROR, /* область ошибки (error domain) */ FOO_ERROR_BLAH, /* код ошибки (error code) */ "Failed to open file: %s", /* форматированная строка сообщения об ошибке */ g_strerror (errno)); return -1; } else return fd; }
Немного сложнее если вы самостоятельно вызываете функцию которая может сообщить
GError.
Если подчинённая функция указывает на неисправимые ошибки некоторым способом отличающимся от сообщения GError, таким как возвращение TRUE
при удачном исполнении, вы можете просто сделать следующее:
gboolean my_function_that_can_fail (GError **err) { g_return_val_if_fail (err == NULL || *err == NULL, FALSE); if (!sub_function_that_can_fail (err)) { /* предполагается что ошибка была установлена с помощью подчинённой функции (sub-function) */ g_assert (err == NULL || *err != NULL); return FALSE; } /* иначе продолжаем, ошибка не происходит */ g_assert (err == NULL || *err == NULL); }
Если подчинённая функция не указывает о других ошибках кроме как сообщения GError,
вы должны создать временную GError та как помещаемая в неё может быть NULL
.
g_propagate_error()
предназначена для использования в этом случае.
gboolean my_function_that_can_fail (GError **err) { GError *tmp_error; g_return_val_if_fail (err == NULL || *err == NULL, FALSE); tmp_error = NULL; sub_function_that_can_fail (&tmp_error); if (tmp_error != NULL) { /* сохраняем tmp_error в err, если err != NULL, * иначе вызываем g_error_free() для tmp_error */ g_propagate_error (err, tmp_error); return FALSE; } /* иначе продолжаем, ошибка не происходит */ }
Error pileups являются всегда ошибкой. Например, этот код неправильный:
gboolean my_function_that_can_fail (GError **err) { GError *tmp_error; g_return_val_if_fail (err == NULL || *err == NULL, FALSE); tmp_error = NULL; sub_function_that_can_fail (&tmp_error); other_function_that_can_fail (&tmp_error); if (tmp_error != NULL) { g_propagate_error (err, tmp_error); return FALSE; } }
tmp_error
должна быть проверена немедленно после
,
и либо очищена либо распространена на верх.
Правило: после каждой ошибки, вы должны либо обработать ошибку, либо вернуть её в вызываемую функцию. Помните что sub_function_that_can_fail()
NULL
для параметра расположения ошибки эквивалентно обработке ошибки ничего не делая с ней.
Таким образом следующий код является хорошим примером, предполагается что ошибки в
являются не фатальными для sub_function_that_can_fail()
:
my_function_that_can_fail()
gboolean my_function_that_can_fail (GError **err) { GError *tmp_error; g_return_val_if_fail (err == NULL || *err == NULL, FALSE); sub_function_that_can_fail (NULL); /* игнорирование ошибок */ tmp_error = NULL; other_function_that_can_fail (&tmp_error); if (tmp_error != NULL) { g_propagate_error (err, tmp_error); return FALSE; } }
Помните что помещаемый NULL
в параметр размещения ошибки означает игнорирование
ошибок; это эквивалентно
try {
в C++. Это не значит оставить ошибки не обработанными; это значит обработать ошибки ничего не делая.
sub_function_that_can_fail()
; } catch
(...) {}
Области и коды ошибки традиционно именуются следующим образом:
Область ошибки называют согласно шаблона
<NAMESPACE>_<MODULE>_ERROR
, например
G_EXEC_ERROR
или G_THREAD_ERROR
.
Коды ошибки находятся в перечислении называемом согласно шаблона <Namespace><Module>Error
; например,
GThreadError или GSpawnError.
Элементы перечисления кодов ошибки называются согласно шаблона <NAMESPACE>_<MODULE>_ERROR_<CODE>
, например G_SPAWN_ERROR_FORK
или G_THREAD_ERROR_AGAIN
.
Если есть "generic" или "unknown" коды ошибки для неисправимых ошибок нет смысла различать их
другими специфическими кодами, они должны быть названы по шаблону <NAMESPACE>_<MODULE>_ERROR_FAILED
, например G_SPAWN_ERROR_FAILED
or G_THREAD_ERROR_FAILED
.
Сводные правила использования GError:
Не сообщайте о программных ошибках через GError.
Последним параметром функции возвращающей ошибку должно быть место размещения GError (то есть "GError ** error"). Если GError используется с переменным количеством аргументов, то GError** должна быть последним аргументом перед "...".
Вызывающий может помещать NULL
для GError** если его не интересуют подробности произошедшей ошибки.
Если NULL
помещён для GError**
аргумента, тогда ошибка не должна возвращаться к вызывающей функции, но ваша функция всё же должна
прерываться и возвращаться если произошла ошибка. Таким образом, на управление потоком не должно влиять получение или неполучение вызывающей функцией GError.
Если о GError сообщено, то ваша функция по определению имеет фатальную ошибку и не закончила то что должна была сделать. Если произошла не фатальная ошибка, то вы обрабатываете её и не должны сообщать о ней. Если она была фатальной, то вы должны сообщить о ней и прекратить выполнение немедленно.
GError* должна быть инициализирована в значение NULL
перед помещением её адреса в функцию которая может сообщать об ошибках.
"Накопление" ошибок - всегда ошибка. Таким образом, если вы назначили новую
GError для GError* которая не-NULL
, переписывая таким образом предыдущую ошибку,
она указывает вам что нужно прервать операцию вместо продолжения. Вы можете продолжать
если очистите предыдущую ошибку с помощью g_clear_error()
. g_set_error()
будет предупреждать если вы накапливаете ошибки.
В соответствие с соглашением, если вы возвращаете логическое значение, то
TRUE
означает успешное выполнение, а FALSE
означает неудачу. Если возвращено значение FALSE
,
ошибка должна быть установлена в значение
не-NULL
.
Возвращённое значение NULL
часто также означает что произошла ошибка. Вы должны разъяснить в вашей документации означает ли NULL
допустимое возвращаемое значение в случае безошибочного выполнения; если NULL
допустимое значение,
то пользователи должны проверить была ли возвращена ошибка, чтобы увидеть выполнена ли
функция успешно.
Когда реализуется функция которая может сообщать об ошибках, вы можете добавить
проверку в начале вашей функции является ли место расположения ошибки значением
NULL
или
используется ли значение NULL
в качестве указателя ошибки
(например g_return_if_fail (error == NULL || *error ==
NULL);
).
typedef struct { GQuark domain; gint code; gchar *message; } GError;
Структура GError содержит информацию о произошедшей ошибке.
GQuark domain ; |
область ошибки, например G_FILE_ERROR. |
gint code ; |
код ошибки, например G_FILE_ERROR_NOENT .
|
gchar *message ; |
удобное для чтения пользователем информационное сообщение об ошибке. |
GError* g_error_new (GQuark domain, gint code, const gchar *format, ...);
Создаёт новую GError с полученными domain
и code
,
а сообщение форматируется с помощью format
.
domain : |
область ошибки |
code : |
код ошибки |
format : |
printf() -стиль форматирования для сообщения об ошибке
|
... : |
параметры для форматирования сообщения |
Возвращает : | новая GError |
GError* g_error_new_literal (GQuark domain, gint code, const gchar *message);
Создаёт новую GError; в отличие от g_error_new()
, message
является строкой не в printf()
-стиле форматирования. Используйте эту функцию если message
содержит текст не контролируемый вами,
который мог бы включать printf()
escape-последовательность.
domain : |
область ошибки |
code : |
код ошибки |
message : |
сообщение об ошибке |
Возвращает : | новая GError |
void g_error_free (GError *error);
Освобождает GError и связанные с ней ресурсы.
error : |
GError |
gboolean g_error_matches (const GError *error, GQuark domain, gint code);
Возвращает TRUE
если
error
соответствует domain
и code
, FALSE
в любом другом случае.
error : |
GError |
domain : |
область ошибки |
code : |
код ошибки |
Возвращает : | соответствует ли error domain и code
|
void g_set_error (GError **err, GQuark domain, gint code, const gchar *format, ...);
Ничего не делает если err
имеет значение NULL
; если err
не-NULL
, то *err
должна быть NULL
. Новая GError создаётся привязанной к *err
.
void g_propagate_error (GError **dest, GError *src);
Если dest
имеет значение NULL
, освобождает src
; иначе,
перемещает src
в *dest
. *dest
должен быть NULL
.
dest : |
расположение возвращаемой ошибки |
src : |
ошибка для перемещения в расположение указанное параметром dest
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> #include <glib/gstdio.h> enum GFileError; #define G_FILE_ERROR enum GFileTest; GFileError g_file_error_from_errno (gint err_no); gboolean g_file_get_contents (const gchar *filename, gchar **contents, gsize *length, GError **error); gboolean g_file_set_contents (const gchar *filename, const gchar *contents, gssize length, GError **error); gboolean g_file_test (const gchar *filename, GFileTest test); gint g_mkstemp (gchar *tmpl); gint g_file_open_tmp (const gchar *tmpl, gchar **name_used, GError **error); gchar* g_file_read_link (const gchar *filename, GError **error); int g_mkdir_with_parents (const gchar *pathname, int mode); GDir; GDir* g_dir_open (const gchar *path, guint flags, GError **error); const gchar* g_dir_read_name (GDir *dir); void g_dir_rewind (GDir *dir); void g_dir_close (GDir *dir); GMappedFile; GMappedFile* g_mapped_file_new (const gchar *filename, gboolean writable, GError **error); void g_mapped_file_free (GMappedFile *file); gsize g_mapped_file_get_length (GMappedFile *file); gchar* g_mapped_file_get_contents (GMappedFile *file); int g_open (const gchar *filename, int flags, int mode); int g_rename (const gchar *oldfilename, const gchar *newfilename); int g_mkdir (const gchar *filename, int mode); int g_stat (const gchar *filename, struct stat *buf); int g_lstat (const gchar *filename, struct stat *buf); int g_unlink (const gchar *filename); int g_remove (const gchar *filename); int g_rmdir (const gchar *filename); FILE* g_fopen (const gchar *filename, const gchar *mode); FILE* g_freopen (const gchar *filename, const gchar *mode, FILE *stream); int g_chmod (const gchar *filename, int mode); int g_access (const gchar *filename, int mode); int g_creat (const gchar *filename, int mode); int g_chdir (const gchar *path);
Есть группа функций которые являются оболочками для основных POSIX функций имеющих дело с именами файлов
(g_open()
, g_rename()
, g_mkdir()
, g_stat()
,
g_unlink()
, g_remove()
, g_fopen()
, g_freopen()
). Указанные оболочки позволяют обрабатывать имена файлов с любыми
Unicode символами в Windows без необходимости использования ifdefs и расширенного API символов в коде приложения.
Аргумент pathname должен быть в кодировке имён файлов GLib. В
POSIX это фактическая кодировка на диске которая может соответствовать
установкам locale процесса (или переменной окружения G_FILENAME_ENCODING
), или нет.
В Windows кодировкой имён файлов GLib является UTF-8. Помните что Microsoft C library не использует UTF-8, но имеет раздельный APIs для текущей системной кодовой страницы и расширенных символов (UTF-16). Оболочки GLib вызывают расширенный символьный API, если представлен (на современных системах Windows), иначе конвертируют в/из системной кодовой страницы.
Другая группа функций позволяет открывать и читать каталоги в кодировке имён файлов GLib.
Такие как g_dir_open()
,
g_dir_read_name()
, g_dir_rewind()
, g_dir_close()
.
typedef enum { G_FILE_ERROR_EXIST, G_FILE_ERROR_ISDIR, G_FILE_ERROR_ACCES, G_FILE_ERROR_NAMETOOLONG, G_FILE_ERROR_NOENT, G_FILE_ERROR_NOTDIR, G_FILE_ERROR_NXIO, G_FILE_ERROR_NODEV, G_FILE_ERROR_ROFS, G_FILE_ERROR_TXTBSY, G_FILE_ERROR_FAULT, G_FILE_ERROR_LOOP, G_FILE_ERROR_NOSPC, G_FILE_ERROR_NOMEM, G_FILE_ERROR_MFILE, G_FILE_ERROR_NFILE, G_FILE_ERROR_BADF, G_FILE_ERROR_INVAL, G_FILE_ERROR_PIPE, G_FILE_ERROR_AGAIN, G_FILE_ERROR_INTR, G_FILE_ERROR_IO, G_FILE_ERROR_PERM, G_FILE_ERROR_NOSYS, G_FILE_ERROR_FAILED } GFileError;
Значения соответствующие errno
кодам возвращаемым из файловых операций в UNIX.
В отличие от errno
кодов, GFileError
значения доступны во всех системах, даже в Windows. Точное значение каждого кода зависит от выполняемой вами опреции;
UNIX документация даёт больше деталей. Следующие описания error кодов взяты из руководства GNU C Library
и находятся под действие копирайта этого руководства.
Это не очень переносимо для создания подробного предположения о точных ошибках которые будут возвращены из полученной операции. Некоторые ошибки не происходят в некоторых системах и т.д., иногда есть тонкое различие в том когда система сообщит о полученной ошибке и т.д..
G_FILE_ERROR_EXIST |
Операция не разрешена; только владелец файла (или другого ресурса) или процесс со специальными привилегиями может выполнить операцию. |
G_FILE_ERROR_ISDIR |
Файл является каталогом; вы не можете открыть каталог для записи, или создать/удалить жесткую ссылку в нём. |
G_FILE_ERROR_ACCES |
Запрещённое действие; права на файл не позволяют произвести операцию. |
G_FILE_ERROR_NAMETOOLONG |
Слишком длинное имя файла. |
G_FILE_ERROR_NOENT |
Нет такого файла или каталога. Это ошибка "file doesn't exist" для обычных файлов на которые ссылаются в контекстах ожидая что они уже существуют. |
G_FILE_ERROR_NOTDIR |
Файл который не является каталогом, был запрошен как каталог. |
G_FILE_ERROR_NXIO |
Нет такого устройства или адреса. Система попыталась использовать устройство представленное файлом который вы определили и не смогла найти устройство. Это может означать что файл устройства было неправильно установлено, или физическое устройство отсутствует или неправильно подключено к компьютеру. |
G_FILE_ERROR_NODEV |
Файл имеет тип который не поддерживает отображение. |
G_FILE_ERROR_ROFS |
Каталог не может быть изменён потому, что он находится на файловой системе только для чтения. |
G_FILE_ERROR_TXTBSY |
Текстовый файл занят. |
G_FILE_ERROR_FAULT |
Вы перешли в указатель на испорченную память. (GLib не гарантирует возврат этого, не перемещайтесь в указатели на испорченную память.) |
G_FILE_ERROR_LOOP |
Слишкрм много уровней символических ссылок при поиске имени файла. Это часто указывает на циклические символические ссылки. |
G_FILE_ERROR_NOSPC |
Нет свободного пространства на устройстве; запись файла на устройство не удалась, так как диск заполнен. |
G_FILE_ERROR_NOMEM |
Нет доступной памяти. Система не может распределить виртуальную память, так как она полная. |
G_FILE_ERROR_MFILE |
Текущий процесс имеет слишком много открытых файлов и не может больше открыть ни одного. Двойные дескрипторы действительно рассчитывают до этого предела. |
G_FILE_ERROR_NFILE |
Во системе слишком много разных открытых файлов. |
G_FILE_ERROR_BADF |
Плохой дескриптор файла; например, I/O в дескриптор который был закрыт или прочитан из дескриптора открытого только для записи (или наоборот). |
G_FILE_ERROR_INVAL |
Недопустимый параметр. Используется для указания на различного рода проблемы связанные с указанием неправильных параметров библиотечных функций. |
G_FILE_ERROR_PIPE |
Испорченный канал; нет процесса читающего на другом конце канала. Все библиотечные функции, которые возвращают этот код ошибки, также генерируют сигнал `SIGPIPE'; этот сигнал закрывает программу если обработан или не заблокирован. Поэтому ваша программа фактически никогда не увидит этот код пока она обрабатывает или не блокирует `SIGPIPE'. |
G_FILE_ERROR_AGAIN |
Ресурс временно не доступен; повторите запрос немного позже. |
G_FILE_ERROR_INTR |
Прерванный вызов функции; произошёл асинхронный сигнал и предотвратил завершение вызова. Когда это происходит вы должны повторить вызов снова. |
G_FILE_ERROR_IO |
Ошибка ввода/вывода; обычно используется для физических ошибок чтения или записи. То есть диск или другое физическое устройство вернуло ошибку. |
G_FILE_ERROR_PERM |
Опереция не разрешена; только владелец файла (или другого ресурса) или процесс со специальными правами может выполнить операцию. |
G_FILE_ERROR_NOSYS |
Функция не реализована; это указывает что в системе отсутствует некоторая функциональность. |
G_FILE_ERROR_FAILED |
Не соответствует ошибочному коду UNIX; это стандартный код ошибки "failed for unspecified reason" представленный во всех перечислениях GError ошибочных кодов. Возвращается если нет определённого кода. |
#define G_FILE_ERROR g_file_error_quark ()
Домен ошибки для файловых операций. Ошибки в этом домене из перечисления GFileError. Смотрите GError для информации о доменах ошибки.
typedef enum { G_FILE_TEST_IS_REGULAR = 1 << 0, G_FILE_TEST_IS_SYMLINK = 1 << 1, G_FILE_TEST_IS_DIR = 1 << 2, G_FILE_TEST_IS_EXECUTABLE = 1 << 3, G_FILE_TEST_EXISTS = 1 << 4 } GFileTest;
Перечисление для тестирования файла используя g_file_test()
.
G_FILE_TEST_IS_REGULAR |
TRUE если файл обычный (не ссылка или каталог)
|
G_FILE_TEST_IS_SYMLINK |
TRUE если файл является символической ссылкой.
|
G_FILE_TEST_IS_DIR |
TRUE если файл является каталогом.
|
G_FILE_TEST_IS_EXECUTABLE |
TRUE если файл исполняемый.
|
G_FILE_TEST_EXISTS |
TRUE если файл существует.
Может быть или не быть обычным файлом.
|
GFileError g_file_error_from_errno (gint err_no);
Получает константу GFileError основанную на помещённой errno
.
Например, если вы поместили EEXIST
эта функция вернёт
G_FILE_ERROR_EXIST.
В отличие от значений errno
, вы можете предполагать что все значения
GFileError будут существовать при портировании.
Обычно значение GFileError происходит из GError возвращаемой из функций манипулирования файлами. Поэтому вы должны использовать
g_file_error_from_errno()
при создании
GError.
err_no : |
значение "errno" |
Возвращает : | GFileError соответствующую полученной errno
|
gboolean g_file_get_contents (const gchar *filename, gchar **contents, gsize *length, GError **error);
Читает весь файл в распределённую память, с хорошей проверкой ошибок.
Если вызов был выполнен успешно, то возвращает TRUE
и устанавливает contents
в файловый контекст, а length
в длину файлового контекста в байтах. Строка сохраняемая в contents
будет nul-завершённой,
таким образом для текстового файла вы можете поместить
NULL
для аргумента
length
. Если вызов не выполнен, то возвращает
FALSE
и устанавливает
error
. Домен ошибки это
G_FILE_ERROR. Возможные коды ошибок берутся в
перечислении GFileError. В случае ошибки,
contents
устанавливается в значение NULL
, а length
в нулевое значение.
filename : |
имя файла из которого читается содержимое, в кодировке имён файлов GLib |
contents : |
расположение для хранения распределённой строки |
length : |
расположение для хранения длины содержимого в байтах, или NULL
|
error : |
расположение для возвращаемой GError, или NULL
|
Возвращает : | TRUE при успешном выполнении,
FALSE если произошла ошибка
|
gboolean g_file_set_contents (const gchar *filename, const gchar *contents, gssize length, GError **error);
Записывает весь contents
в файл с именем filename
,
с хорошим контролем ошибок.
Если файл с именем filename
уже существует он будет переписан.
Эта запись атомарная в том смысле что сначала записывается в во временный файл который затем переименовывается в конечное имя. Помните:
filename
уже является жёсткой ссылкой,
то связь с filename
будет сломана.
А также, так как файл перезаписан, существующие права доступа, метаданные и т.д. могут быть утеряны.
Если filename
символическая ссылка,
то сама связь будет заменена на не связанный файл.
filename
уже существует и открыт.
Если вызов был успешен, возвращает TRUE
.
Если вызов неудался, возвращает FALSE
и устанавливает error
. Домен ошибки - G_FILE_ERROR.
Возможные коды ошибок берутся из перечисления
GFileError enumeration.
filename : |
имя файла для записи контекста contents ,
в кодировке имён файлов GLib
|
contents : |
строка для записи в файл |
length : |
длина contents , или -1 если contents
является nul-завершённой строкой
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE при успешном выполнении,
FALSE если произошла ошибка
|
Начиная с версии 2.8
gboolean g_file_test (const gchar *filename, GFileTest test);
Возвращает TRUE
если любой из тестов в битовом поле
test
является TRUE
.
Например, (G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)
вернёт
TRUE
если файл существует;
проверка является ли он каталогом не имеет значения, так как тест существования имеет значение
TRUE
.
С текущем набором доступных тестов, нет никакого смысла помещать больше чем один тест одновременно.
Помимо G_FILE_TEST_IS_SYMLINK
все тесты поддерживают символические тесты,
поэтому для символической ссылки на обычный файл g_file_test()
вернёт
TRUE
и для G_FILE_TEST_IS_SYMLINK
и для G_FILE_TEST_IS_REGULAR
.
Помните, для висящей символической ссылки g_file_test()
вернёт
TRUE
для G_FILE_TEST_IS_SYMLINK
и FALSE
для других флагов.
Вы никогда не должны использовать g_file_test()
для тестирования безопасности операции, потомучто всегда есть возможность условия изменяющегося прежде чем вы фактически выполнили операцию.
Например, вы можете подумать что можно использовать G_FILE_TEST_IS_SYMLINK
, чтобы определить можно ли безопасно записать в файл не опасаясь что он находится в другом месте.
Это не работает!
/* Не делайте это */ if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) { fd = g_open (filename, O_WRONLY); /* запись в fd */ }
Также помните что G_FILE_TEST_EXISTS
и
G_FILE_TEST_IS_EXECUTABLE
реализованы с использованием системного вызова access()
. Это обычно не имеет значения,
но если ваша программа имеет setuid или setgid это значит что эти тесты дадут вам ответ для реального user ID и group ID,
а не действующего user ID и group ID.
В Windows, нет символических ссылок, поэтому тест для
G_FILE_TEST_IS_SYMLINK
будет всегда возвращать FALSE
. Тест для
G_FILE_TEST_IS_EXECUTABLE
будет просто проверять что файл существует и его имя указывает что он исполняемый, проверяя известные расширения и их список
в переменной окружения PATHEXT
.
gint g_mkstemp (gchar *tmpl);
Открывает временный файл. Смотрите документацию mkstemp()
в большинстве UNIX-подобных системах.
В качестве параметра используется строка которая должна соответствовать правилам шаблонов mkstemp()
,
то есть содержать строку "XXXXXX".
g_mkstemp()
более гибкая чем mkstemp()
в которой последовательность не должна находится в самом конце шаблона. Строка X изменяется для формирования имени не существующего файла.
Строка должна быть в кодировке имён файлов GLib. Наиболее важно что в Windows она должна быть в UTF-8.
tmpl : |
шаблон имени файла |
Возвращает : | Дескриптор файла (как из open() ) для файла открытого для записи и чтения.
Файл открывается в двоичном режиме на платформах где есть различия.
Дескриптор файла должен быть закрыт с помощью close() . В случае ошибки, возвращается -1.
|
gint g_file_open_tmp (const gchar *tmpl, gchar **name_used, GError **error);
Открывает файл для записи в привилегированный каталог временных файлов
(который возвращается из g_get_tmp_dir()
).
tmpl
должен быть строкой в кодировке имён файлов GLib содержащей последовательность
шести символов 'X', также как параметр в g_mkstemp()
.
Однако в отличие от этой функции, шаблон должен быть только базовым именем,
ни какие компоненты каталога не допускаются. Если шаблон NULL
,
используется шаблон по умолчанию.
Помните что в отличие от g_mkstemp()
(и mkstemp()
)
tmpl
не изменяется, и может таким образом быть буквенной строкой только для чтения.
Фактически используется имя возвращаемое в name_used
если не-NULL
.
Эта строка должна быть освобождена с помощью g_free()
когда больше не нужна.
Возвращаемое имя находится в кодировке имён файлов GLib.
tmpl : |
Шаблон для имени файла, как в g_mkstemp() ,
только базовое имя, или NULL ,
для использования шаблона по умолчанию.
|
name_used : |
расположение для хранения фактически используемого имени |
error : |
расположение для возвращаемой GError |
Возвращает : | Дескриптор файла (как из open() )
открытого для чтения и записи. Файл открывается в двоичном режиме
на платформах где есть разница. Дескриптор файла должен быть закрыт с помощью
close() . В случае ошибки, возвращает -1 и устанавливает
error .
|
gchar* g_file_read_link (const gchar *filename, GError **error);
Читает содержимое символической ссылки filename
также как POSIX функция
readlink()
. Возвращаемая строка находится в кодировке используемой для имён файлов.
Использует g_filename_to_utf8()
для конвертации в UTF-8.
filename : |
символическая ссылка |
error : |
размещение для возвращаемой GError |
Возвращает : | Вновь распределённая строка с содержимым символической ссылки,
или NULL если произошла ошибка.
|
Начиная с версии 2.4
int g_mkdir_with_parents (const gchar *pathname, int mode);
Создаёт каталог если он ещё не существует. Также создаёт необходимые промежуточные родительские каталоги.
pathname : |
имя пути в кодировке имён файлов GLib |
mode : |
права доступа для вновь созданных каталогов |
Возвращает : | 0 если каталог существует, или был полностью создан. Возвращает -1 если произошла ошибка, с установкой errno. |
Начиная с версии 2.8
GDir* g_dir_open (const gchar *path, guint flags, GError **error);
Открывает каталог для чтения. Имена файлов в каталоге могут быть найдены с помощью
g_dir_read_name()
.
path : |
путь к интересующему вас каталогу. В Unix в дисковой кодировке (on-disk encoding). В Windows в UTF-8 |
flags : |
В текущее время должен быть установлен в 0. Зарезервирован для использования в будующем. |
error : |
расположение для возвращаемой GError,
или NULL .
Если не-NULL ,
будет установлена ошибка если и только если
g_dir_open() закончилась неудачей.
|
Возвращает : | вновь распределённая GDir при успешном выполнении,
NULL при неудаче.
Если не-NULL , вы должны освободить результат с помощью
g_dir_close() когда вы закончите.
|
const gchar* g_dir_read_name (GDir *dir);
Находит имя следующего входа в каталоге. Входы '.' и '..' пропускаются. В Windows, возвращаемое имя находится в кодировке UTF-8. В Unix, она находится в дисковой кодировке (on-disk encoding).
dir : |
GDir* созданная с помощью g_dir_open()
|
Возвращает : | Имя входа или NULL
если нет больше входов. Возвращаемым значением владеет GLib и оно не должно модифицироваться или освобождаться.
|
void g_dir_rewind (GDir *dir);
Сбрасывает полученный каталог до первой записи.
Следующий вызов g_dir_read_name()
снова вернёт первый вход.
dir : |
GDir* созданная с помощью
g_dir_open()
|
void g_dir_close (GDir *dir);
Закрывает каталоги и освобождает все связанные с ними ресурсы.
dir : |
GDir* созданная с помощью
g_dir_open()
|
typedef struct _GMappedFile GMappedFile;
GMappedFile представляет отображение файла созданное с помощью
g_mapped_file_new()
.
Она имеет только закрытые элементы и не должна использоваться непосредственно.
GMappedFile* g_mapped_file_new (const gchar *filename, gboolean writable, GError **error);
Отображает файл в памяти. В UNIX, она использует функцию mmap()
.
Если writable
равна TRUE
, буфер отображения может модифицироваться, иначе она представляет ошибку для изменения отображённого буфера.
Модификации буфера невидимы для других процессов отображающих тот же файл и не записываются обратно в файл.
Помните что модификации основного файла могут затронуть содержимое
GMappedFile.
Поэтому отображение должно использоваться только если файл не будет изменён, или все модификации файла сделаны атомарно
(например используя g_file_set_contents()
).
filename : |
путь файла для загрузки, в кодировке имён файлов GLib |
writable : |
если отображение должно быть изменяемым |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённая GMappedFile
которая должна освобождаться с помощью
g_mapped_file_free() ,
или NULL если отображение не удалось.
|
Начиная с версии 2.8
void g_mapped_file_free (GMappedFile *file);
Сбрасывает буфер отображения для file
и освобождает его.
file : |
GMappedFile |
Начиная с версии 2.8
gsize g_mapped_file_get_length (GMappedFile *file);
Возвращает размер содержимого GMappedFile.
file : |
GMappedFile |
Возвращает : | размер содержимого file .
|
Начиная с версии 2.8
gchar* g_mapped_file_get_contents (GMappedFile *file);
Returns the contents of a GMappedFile.
Помните что содержимое может быть не ноль-завершённым (zero-terminated), даже если GMappedFile поддерживается текстовым файлом.
file : |
GMappedFile |
Возвращает : | содержимое file .
|
Начиная с версии 2.8
int g_open (const gchar *filename, int flags, int mode);
Оболочка для POSIX функции open()
.
Функция open()
используется для конвертации имени пути
в дескриптор файла. Помните что в POSIX системах дескриптор файла реализуется системной операцией.
В Windows, это C библиотека которая реализует open()
и дескриптор файла.
Фактическое Windows API для открытия файлов является другим.
Смотрите руководство C library для детальной информации о open()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF-8 в Windows) |
flags : |
как в open()
|
mode : |
как в open()
|
Возвращает : | новый дескриптор файла, или -1 если произошла ошибка.
Возвращаемое значение может быть использовано точно также как значение из
open() .
|
Начиная с версии 2.6
int g_rename (const gchar *oldfilename, const gchar *newfilename);
Оболочка для POSIX функции rename()
.
Функция rename()
переименовывает файл,
перемещая его между каталогами если необходимо.
Смотрите руководство для вашей C библиотеки для получения деталей о том как работает rename()
в вашей системе. Помните что в Win9x не возможно переименовать файл если файл с новым именем уже существует.
Также это не возможно вообще в Windows для открытых файлов.
oldfilename : |
имя пути в кодировке имён файлов GLib (UTF-8 в Windows) |
newfilename : |
имя пути в кодировке имён файлов GLib |
Возвращает : | 0 если переименование выполнено, -1 если произошла ошибка |
Начиная с версии 2.6
int g_mkdir (const gchar *filename, int mode);
Оболочка для POSIX функции mkdir()
.
Функция mkdir()
пытается создать каталог с полученным именем и правами доступа.
Смотрите руководство C библиотеки для больших деталей о mkdir()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF-8 в Windows) |
mode : |
права доступа для использования вновь созданного каталога |
Возвращает : | 0 если каталог был полностью создан, -1 если произошла ошибка |
Начиная с версии 2.6
int g_stat (const gchar *filename, struct stat *buf);
Оболочка для POSIX функции stat()
.
Функция stat()
возвращает информацию о файле.
Смотрите руководство C библиотеки для больших деталей о stat()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF-8 в Windows) |
buf : |
указатель на структуру stat, которая заполнена информацией о файле. |
Возвращает : | 0 если информация полностью получена, -1 если произошла ошибка |
Начиная с версии 2.6
int g_lstat (const gchar *filename, struct stat *buf);
Оболочка для POSIX функции lstat()
.
Функция lstat()
похожа на stat()
за исключением того что в случае символической ссылки она возвращает информацию о символической ссылке непосредственно,
а не о файле на который она ссылается. Если система не поддерживает символических ссылок
g_lstat()
идентична g_stat()
.
Смотрите руководство C библиотеки для больших деталей о lstat()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF-8 в Windows) |
buf : |
указатель на структуру stat, которая заполняется информацией о файле |
Возвращает : | 0 если информация была полностью получена, -1 если произошла ошибка |
Начиная с версии 2.6
int g_unlink (const gchar *filename);
Оболочка для POSIX функции unlink()
. Функция unlink()
удаляет имя из файловой системы. Если оно было последней ссылкой на
файл и нет процессов открывших его, дисковое пространство освобождается от файла.
Смотрите руководство C библиотеки для больших деталей о unlink()
.
Помните что в Windows, она не может удалить файлы которые открыты каким нибудь процессом, или отображены в памяти.
filename : |
имя пути в кодировке имён файлов GLib (UTF-8 в Windows) |
Возвращает : | 0 если имя полностью удалено, -1 если произошла ошибка |
Начиная с версии 2.6
int g_remove (const gchar *filename);
Оболочка для POSIX функции remove()
.
Функция remove()
удаляет имя файла из файловой системы.
Смотрите руководство C библиотеки для больших деталей о том как работает remove()
в вашей системе. В Unix, remove()
удаляет также каталоги, так как она вызывает
unlink()
для файлов и rmdir()
для каталогов. В Windows,
хотя remove()
в C библиотеке работает только для файлов, эта функция вызовет сначала
remove()
а затем если это не удалось rmdir()
, поэтому
работает и для файлов и для каталогов. Помните однако, что в Windows, она не сможет удалить файл который открыт
каким нибудь процессом, или отображён в память.
Если эта функция закончилась неудачно в Windows вы не можете получить слишком много из значения ошибки.
rmdir()
пробует выполниться не зависимо от того что remove()
завершилась неудачно. Любое значение errno установленное remove()
будет переписано
rmdir()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF-8 в Windows) |
Возвращает : | 0 если файл был полностью удалён, -1 если произошла ошибка |
Начиная с версии 2.6
int g_rmdir (const gchar *filename);
Оболочка для POSIX функции rmdir()
. Функция rmdir()
каталог из файловой системы.
Смотрите руководство C библиотеки для больших деталей о том как работает rmdir()
в вашей системе.
filename : |
имя пути в кодировке имён файлов GLib (UTF-8 в Windows) |
Возвращает : | 0 если каталог был полностью удалён, -1 если произошла ошибка |
Начиная с версии 2.6
FILE* g_fopen (const gchar *filename, const gchar *mode);
Оболочка для POSIX функции fopen()
. Функция fopen()
открывает файл и связывает его с новым потоком.
Смотрите руководство C библиотеки для деталей о fopen()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF8 в Windows) |
mode : |
строка describing the mode in which the file should be opened |
Возвращает : | A FILE pointer if the file was successfully
opened, or NULL if an error occurred
|
Начиная с версии 2.6
FILE* g_freopen (const gchar *filename, const gchar *mode, FILE *stream);
A wrapper for the POSIX freopen()
function. The freopen()
function
opens a file and associates it with an existing stream.
Смотрите руководство С библиотеки для больших деталей о freopen()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF8 в Windows) |
mode : |
строка describing the mode in which the file should be opened |
stream : |
an existing stream which will be reused, or NULL
|
Возвращает : | A FILE pointer if the file was successfully
opened, or NULL if an error occurred.
|
Начиная с версии 2.6
int g_chmod (const gchar *filename, int mode);
A wrapper for the POSIX chmod()
function. The chmod()
function is
used to set the permissions of a file system object. Note that on
Windows the file protection mechanism is not at all POSIX-like, and
the underlying chmod()
function in the C library just sets or
clears the READONLY attribute. It does not touch any ACL. Software
that needs to manage file permissions on Windows exactly should
use the Win32 API.
Смотрите руководство С библиотеки для больших деталей о chmod()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF8 в Windows) |
mode : |
как в chmod()
|
Возвращает : | ноль если операция полностью выполнена, -1 при ошибке. |
Начиная с версии 2.8
int g_access (const gchar *filename, int mode);
Оболочка для POSIX функции access()
.
Эта функция используется для тестирования имени пути на доступ
чтения, записи или исполнения, или просто существование.
В Windows, основная функция access()
в C библиотеке только проверяет параметр READONLY, и не смотрите
остальные ACL. Программное обеспечение, которое должно более точно
обрабатывать права доступа в Windows, должно использовать Win32 API.
Смотрите руководство С библиотеки для больших деталей о access()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF8 в Windows) |
mode : |
как в access()
|
Возвращает : | ноль если имя пути ссылается на существующий объект в файловой системе который прошёл все тесты доступа, или -1 если произошла ошибка. |
Начиная с версии 2.8
int g_creat (const gchar *filename, int mode);
Оболочка для POSIX функции creat()
.
Функция creat()
используется для конвертации
имени пути в дескриптор файла, создавая файл если необходимо.
Помните что в POSIX системах дескриптор файла реализуется операционной системой.
В Windows, это выполняет C библиотека которая реализует creat()
и дескриптор файла. Фактически Windows API для открытия файлов несколько другое.
Смотрите руководство С библиотеки для больших деталей о creat()
.
filename : |
имя пути в кодировке имён файлов GLib (UTF8 в Windows) |
mode : |
как в creat()
|
Возвращает : | новый дескриптор файла, или -1 если произошла ошибка.
Возвращаемое значение может использоваться точно также как значение из creat() .
|
Начиная с версии 2.8
int g_chdir (const gchar *path);
Оболочка для POSIX функции chdir()
.
Функция изменяет текущий каталог процесса на path
.
Смотрите руководство вашей C библиотеки для больших деталей о chdir()
.
path : |
имя пути в кодировке имён файлов GLib (UTF8 в Windows) |
Возвращает : | 0 при успешном выполнении, -1 если произошла ошибка. |
Начиная с версии 2.8
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Glob-style pattern matchingGlob-style pattern matching — Сравнение строк с шаблонами содержащими '*' (wildcard) and '?' (joker). |
#include <glib.h> GPatternSpec; GPatternSpec* g_pattern_spec_new (const gchar *pattern); void g_pattern_spec_free (GPatternSpec *pspec); gboolean g_pattern_spec_equal (GPatternSpec *pspec1, GPatternSpec *pspec2); gboolean g_pattern_match (GPatternSpec *pspec, guint string_length, const gchar *string, const gchar *string_reversed); gboolean g_pattern_match_string (GPatternSpec *pspec, const gchar *string); gboolean g_pattern_match_simple (const gchar *pattern, const gchar *string);
Функции g_pattern_match*
сравнивают строки с шаблонами содержащими '*' и '?' символы
с семантикой похожей на стандартную функцию glob()
: '*' соответствует произвольной, возможно пустой,
строке, '?' соответствует произвольному символу.
Помните что в отличие от glob()
, символ '/' может
соответствовать символу подстановки, диапазон символов '[...]', '*' , '?' не может быть отброшен для включения как литеры в шаблон.
Когда множество строк должны быть сопоставлены с одним и тем же шаблоном, лучше собрать шаблон в
GPatternSpec используя
g_pattern_spec_new()
и используя
g_pattern_match_string()
вместо
g_pattern_match_simple()
.
Это избавляет от лишних перекомпиляций шаблона.
typedef struct _GPatternSpec GPatternSpec;
GPatternSpec это 'скомпилированная' форма шаблона. Эта структура непрозрачна и её поля не должны использоваться непосредственно.
GPatternSpec* g_pattern_spec_new (const gchar *pattern);
Компилирует шаблон в GPatternSpec.
pattern : |
строка в кодировке UTF-8 завершённая нулём. |
Возвращает : | вновь распределённая GPatternSpec. |
void g_pattern_spec_free (GPatternSpec *pspec);
Освобождает память распределённую для GPatternSpec.
pspec : |
GPatternSpec. |
gboolean g_pattern_spec_equal (GPatternSpec *pspec1, GPatternSpec *pspec2);
Сравнивает две скомпилированных спецификации шаблона и возвращает соответствуют ли они одному набору строк.
pspec1 : |
GPatternSpec. |
pspec2 : |
другая GPatternSpec. |
Возвращает : | Эквивалентны ли скомпилированные шаблоны. |
gboolean g_pattern_match (GPatternSpec *pspec, guint string_length, const gchar *string, const gchar *string_reversed);
Сопоставляет строку с скомпилированным шаблоном. Помещение правильной длины данной строки обязательно.
Переворачивание строки может быть пропущено помещением NULL
,
это более эффективно если перевёрнутая версия строки для соответствия не под рукой, та как
g_pattern_match()
создаст её только если скомпилированный шаблон запросит обратное соответсвие.
Помните что, если код пользователя будет (возможно) соответствовать строке
с множеством шаблонов содержащих символы подстановки, очень высока вероятность
что некоторые шаблоны затребуют перевернутую строку. В этом случае, более эффективно
обеспечить перевёрнутую строку для исключения множественного создания этого в разных вызовах
g_pattern_match()
.
Помните так же что перевёрнутая строка в кодировке UTF-8 не может быть получена из
g_strreverse()
.
Она работает только для строк не содержащих многобайтные символы.
Glib предлагает функцию g_utf_strreverse()
для переворачивания строк в кодировке UTF-8.
pspec : |
GPatternSpec. |
string_length : |
длина string .
|
string : |
строка в кодировке UTF-8 для сопоставления. |
string_reversed : |
перевёрнутая строка string или NULL .
|
Возвращает : |
TRUE если string соответствует pspec .
|
gboolean g_pattern_match_string (GPatternSpec *pspec, const gchar *string);
Сопоставляет строку с скомпилированным шаблоном. Если строка может соответствовать больше чем одному шаблону, рассмотрите использование
g_pattern_match()
вместо этой функции
подставляя полностью перевёрнутую строку.
pspec : |
GPatternSpec. |
string : |
строка в кодировке UTF-8 для сопоставления. |
Возвращает : |
TRUE если string
соответствует pspec .
|
gboolean g_pattern_match_simple (const gchar *pattern, const gchar *string);
Сопоставляет строку с шаблоном полученным как строка.
Если эта функция вызывается в цикле, более эффективно скомпилировать шаблон один раз с помощью
g_pattern_spec_new()
и вызвать g_pattern_match_string()
.
pattern : |
шаблон в кодировке UTF-8. |
string : |
строка в кодировке UTF-8 для сопоставления. |
Возвращает : |
TRUE если string
соответствует pspec .
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GHashTable; GHashTable* g_hash_table_new (GHashFunc hash_func, GEqualFunc key_equal_func); GHashTable* g_hash_table_new_full (GHashFunc hash_func, GEqualFunc key_equal_func, GDestroyNotify key_destroy_func, GDestroyNotify value_destroy_func); guint (*GHashFunc) (gconstpointer key); gboolean (*GEqualFunc) (gconstpointer a, gconstpointer b); void g_hash_table_insert (GHashTable *hash_table, gpointer key, gpointer value); void g_hash_table_replace (GHashTable *hash_table, gpointer key, gpointer value); guint g_hash_table_size (GHashTable *hash_table); gpointer g_hash_table_lookup (GHashTable *hash_table, gconstpointer key); gboolean g_hash_table_lookup_extended (GHashTable *hash_table, gconstpointer lookup_key, gpointer *orig_key, gpointer *value); void g_hash_table_foreach (GHashTable *hash_table, GHFunc func, gpointer user_data); gpointer g_hash_table_find (GHashTable *hash_table, GHRFunc predicate, gpointer user_data); void (*GHFunc) (gpointer key, gpointer value, gpointer user_data); gboolean g_hash_table_remove (GHashTable *hash_table, gconstpointer key); gboolean g_hash_table_steal (GHashTable *hash_table, gconstpointer key); guint g_hash_table_foreach_remove (GHashTable *hash_table, GHRFunc func, gpointer user_data); guint g_hash_table_foreach_steal (GHashTable *hash_table, GHRFunc func, gpointer user_data); void g_hash_table_remove_all (GHashTable *hash_table); void g_hash_table_steal_all (GHashTable *hash_table); gboolean (*GHRFunc) (gpointer key, gpointer value, gpointer user_data); #define g_hash_table_freeze (hash_table) #define g_hash_table_thaw (hash_table) void g_hash_table_destroy (GHashTable *hash_table); GHashTable* g_hash_table_ref (GHashTable *hash_table); void g_hash_table_unref (GHashTable *hash_table); gboolean g_direct_equal (gconstpointer v1, gconstpointer v2); guint g_direct_hash (gconstpointer v); gboolean g_int_equal (gconstpointer v1, gconstpointer v2); guint g_int_hash (gconstpointer v); gboolean g_str_equal (gconstpointer v1, gconstpointer v2); guint g_str_hash (gconstpointer v);
GHashTable обеспечивает связь между ключами и значениями для наиболее быстрого поиска значения полученного ключа.
Помните что не ключи не их значения не копируются при помещении в
GHashTable,
поэтому они должны существовать для жизнеспособности GHashTable.
Это значит использование статических строк допустимо, а временные строки (например создаваемые в буферах и возвращаемые GTK+ виджетами)
должны быть скопированы с помощью g_strdup()
перед вставкой в таблицу.
Если ключи и значения распределяются динамически, вы должны обязательно убедиться в их освобождении после удаления из GHashTable, а также когда они перезаписываются при новой вставке в GHashTable. Также не желательно смешивать статические строки и динамически-распределённые строки в GHashTable, потомучто тогда трудно определить должна ли строка освобождаться.
Для создания GHashTable,
используйте g_hash_table_new()
.
Для вставки ключа и значения в GHashTable,
используйте g_hash_table_insert()
.
Для поиска значения соответствующего полученному ключу используйте
g_hash_table_lookup()
и g_hash_table_lookup_extended()
.
Для удаления ключа и значения, используйте
g_hash_table_remove()
.
Для вызова функции для каждой пары ключа и значения используйте
g_hash_table_foreach()
.
Для уничтожения GHashTable используйте
g_hash_table_destroy()
.
typedef struct _GHashTable GHashTable;
Структура GHashTable является непрозрачной структурой данных представляющей Hash Table. Доступ к ней может осуществляться только функциями описанными ниже.
GHashTable* g_hash_table_new (GHashFunc hash_func, GEqualFunc key_equal_func);
Создаёт новую GHashTable с количеством ссылок равным 1.
hash_func : |
функция для создания хэш значения из ключа. Хеш значения используются для определения места хранения ключей внутри
структуры данных GHashTable.
Функции g_direct_hash() ,
g_int_hash() и
g_str_hash()
обеспечивают некоторые основные типы ключей. Если hash_func это
NULL ,
то используется g_direct_hash() .
|
key_equal_func : |
функция проверяющая эквивалентность двух ключей. Используется при поиске ключа в
GHashTable.
Функции g_direct_equal() ,
g_int_equal() и
g_str_equal() обеспечивают основные типы ключей.
Если key_equal_func это
NULL , ключи сравниваются непосредственно в стиле
g_direct_equal() ,
но без накладных расходов вызова функции.
|
Возвращает : | новая GHashTable. |
GHashTable* g_hash_table_new_full (GHashFunc hash_func, GEqualFunc key_equal_func, GDestroyNotify key_destroy_func, GDestroyNotify value_destroy_func);
Создаёт новую GHashTable, похожа на
g_hash_table_new()
с количеством ссылок равным 1
и позволяет определять функции для освобождения памяти распределённой для ключа и значения которые получит вызов когда удалит элементы из
GHashTable.
hash_func : |
функция для создания хеш значения из ключа. |
key_equal_func : |
функция для проверки эквивалентности двух ключей. |
key_destroy_func : |
функция освобождающая распределённую память для ключа используемая при удалении элемента из
GHashTable или
NULL если вам
не нужно выполнять такую функцию.
|
value_destroy_func : |
функция освобождающая память, распределённую для значения, используемую при удалении элемента
из GHashTable или
NULL
если вам не нужно выполнять такую функцию.
|
Возвращает : | новая GHashTable. |
guint (*GHashFunc) (gconstpointer key);
Специальный тип хеш функции которая помещается в
g_hash_table_new()
когда создаётся GHashTable.
В функцию помещается ключ и она должна вернуть хеш значение guint.
Функции g_direct_hash()
, g_int_hash()
и g_str_hash()
обеспечивают
хеш-функции которые могут использоваться когда ключ gpointer, gint и
gchar* соответственно.
ПОПРАВЬТЕ МЕНЯ: Здесь необходимо больше подробностей. Хеш-значения должны быть равномерно распределены по довольно большому диапазону? Модуль берётся с размером хеш таблицы (простое число) для поиска области памяти в которую помещается ключ. Функция должна быть очень быстрой, так как вызывается для каждого разыскиваемого ключа.
key : |
ключ. |
Возвращает : | хеш значение соответствующее ключу. |
gboolean (*GEqualFunc) (gconstpointer a, gconstpointer b);
Определяет тип функции используемой для проверки эквивалентности двух значений.
Функция должна возвращать TRUE
если оба значения эквивалентны
или иначе FALSE
.
void g_hash_table_insert (GHashTable *hash_table, gpointer key, gpointer value);
Вставляет новый ключ и значение в GHashTable.
Если ключ уже существует в GHashTable
его текущее значение переписывается новым. Если вы поместите value_destroy_func
когда создаёте
GHashTable, старое значение освобождается с помощью этой функции.
Если вы поместите key_destroy_func
когда создаёте
GHashTable, помещаемый ключ освобождается с помощью этой функции.
hash_table : |
GHashTable. |
key : |
вставляемый ключ. |
value : |
значение связанное с ключом. |
void g_hash_table_replace (GHashTable *hash_table, gpointer key, gpointer value);
Вставляет новый ключ и значение в GHashTable аналогично
g_hash_table_insert()
. Разница в том, что если ключ
уже существует в GHashTable, он переписывается новым значением.
Если вы поместили value_destroy_func
когда создавали GHashTable, старое значение освобождается с помощью этой функции. Если вы поместили key_destroy_func
когда создавали GHashTable, старый ключ освобождается с помощью этой функции.
hash_table : |
GHashTable. |
key : |
ключ для вставки. |
value : |
значение связываемое с ключом. |
guint g_hash_table_size (GHashTable *hash_table);
Возвращает количество элементов находящихся в GHashTable.
hash_table : |
GHashTable. |
Возвращает : | количество пар ключ/значение в GHashTable. |
gpointer g_hash_table_lookup (GHashTable *hash_table, gconstpointer key);
Находит ключ в GHashTable.
Помните что эта функция не может отличить ключ который не представлен от ключа который представлен но имеет значение
NULL
. Если вам нужно знать о таком различии, используйте
g_hash_table_lookup_extended()
.
hash_table : |
GHashTable. |
key : |
ключ для поиска. |
Возвращает : | связанное значение, или NULL если ключ не найден.
|
gboolean g_hash_table_lookup_extended (GHashTable *hash_table, gconstpointer lookup_key, gpointer *orig_key, gpointer *value);
Находит ключ в GHashTable, возвращает оригинальный ключ и
связанное значение gboolean которое
TRUE
если ключ был найден.
Это полезно если вам нужно освободить память распределённую для оригинального ключа,
например перед вызовом g_hash_table_remove()
.
hash_table : |
GHashTable. |
lookup_key : |
ключ для поиска. |
orig_key : |
возвращает оригинальный ключ. |
value : |
возвращает значение связанное с ключом. |
Возвращает : | TRUE если ключ был найден в
GHashTable.
|
void g_hash_table_foreach (GHashTable *hash_table, GHFunc func, gpointer user_data);
Вызывает полученную функцию для каждой пары ключ/значение в
GHashTable. В функцию помещается ключ и значение каждой пары,
а также параметр user_data
. Хеш таблица не может меняться пока функция перемещается через неё
(вы не можете добавлять/удалять элементы). Для удаления всех элементов соответствующих предикату, используйте
g_hash_table_foreach_remove()
.
hash_table : |
GHashTable. |
func : |
функция вызываемая для каждой пары ключ/значение. |
user_data : |
пользовательские данные помещаемые в функцию. |
gpointer g_hash_table_find (GHashTable *hash_table, GHRFunc predicate, gpointer user_data);
Вызывает полученную функцию для пар клю/значение в GHashTable, пока
predicate
не вернёт TRUE
. В функцию помещается ключ и значение каждой пары, и полученный параметр user_data
.
Хеш таблица не может изменяться пока функция перемещается через неё (вы не можете добавлять/удалять элементы).
hash_table : |
GHashTable. |
predicate : |
функция для проверки каждой пары ключ/значение на определённое свойство. |
user_data : |
пользовательские данные помещаемые в функцию. |
Возвращает : | Значение первой возвращаемой пары ключ/значение, для которой функция вычислила
TRUE .
Если пара с требуемым свойством не найдена,
возвращается NULL .
|
Начиная с версии 2.4
void (*GHFunc) (gpointer key, gpointer value, gpointer user_data);
Определяет тип функции помещаемойв g_hash_table_foreach()
.
Она вызывается с каждой парой ключ/значение, вместе с параметром user_data
который помещается в
g_hash_table_foreach()
.
key : |
ключ. |
value : |
значение соответствующее ключу. |
user_data : |
пользовательские данные помещаемые в g_hash_table_foreach() .
|
gboolean g_hash_table_remove (GHashTable *hash_table, gconstpointer key);
Удаляет ключ и связанное с ним значение из GHashTable.
Если GHashTable был создан используя
g_hash_table_new_full()
,
ключ и значение освобождаются используя вставленную функцию уничтожения, иначе вы должны убедиться что освободили
все динамически распределённые значения самостоятельно.
hash_table : |
GHashTable. |
key : |
удаляемый ключ. |
Возвращает : | TRUE если ключ был найден и удалён из
GHashTable.
|
gboolean g_hash_table_steal (GHashTable *hash_table, gconstpointer key);
Удаляет ключ и связанное с ним значение из GHashTable, без вызова функции уничтожения ключа и значения.
hash_table : |
GHashTable. |
key : |
ключ для удаления. |
Возвращает : | TRUE если ключ был найден и удалён из
GHashTable.
|
guint g_hash_table_foreach_remove (GHashTable *hash_table, GHRFunc func, gpointer user_data);
Вызывает полученную функцию для каждой пары ключ/значение в GHashTable.
Если функция вернула TRUE
, то ключ/значение удаляется из
GHashTable.
Если ключ или значение помещаются в функцию уничтожения при создании
GHashTable, она используется для освобождения распределённой памяти
удаляемых ключей и значений.
hash_table : |
GHashTable. |
func : |
функция вызываемая для каждой пары ключ/значение. |
user_data : |
пользовательские данные помещаемые в функцию. |
Возвращает : | количество удаляемых пар ключ/значение. |
guint g_hash_table_foreach_steal (GHashTable *hash_table, GHRFunc func, gpointer user_data);
Вызывает полученную функцию для каждой пары ключ/значение в GHashTable.
Если функция вернула TRUE
, то пара ключ/значение удаляется из
GHashTable, но функция уничтожения ключа или значения не вызывается.
hash_table : |
GHashTable. |
func : |
функция вызываемая для каждой пары ключ/значение. |
user_data : |
пользовательские данные помещаемые в функцию. |
Возвращает : | количество удаляемых пар ключ/значение. |
void g_hash_table_remove_all (GHashTable *hash_table);
Удаляет все ключи и связанные с ними значения из GHashTable.
Если GHashTable была создана с использованием
g_hash_table_new_full()
,
ключи и значения освобождаются используя помещённую функцию уничтожения, иначе вы должны убедиться что любые динамически
распределённые значения освободили самостоятельно.
hash_table : |
GHashTable |
Начиная с версии 2.12
void g_hash_table_steal_all (GHashTable *hash_table);
Удаляет все ключи и связанные с ними значения из GHashTable без вызова функции уничтожения ключа и значения.
hash_table : |
GHashTable. |
Начиная с версии 2.12
gboolean (*GHRFunc) (gpointer key, gpointer value, gpointer user_data);
Определяет тип функции помещаемой в g_hash_table_foreach_remove()
.
Она вызывается с каждой парой ключ/значение, вместе с параметром user_data
помещённым в
g_hash_table_foreach_remove()
.
Она должна вернуть TRUE
если пара ключ/значение должна быть удалена из GHashTable.
key : |
ключ. |
value : |
значение связанное с ключом. |
user_data : |
пользовательские данные помещаемые в g_hash_table_remove() .
|
Возвращает : |
TRUE если пара ключ/значение должна быть удалена из GHashTable.
|
#define g_hash_table_freeze(hash_table)
g_hash_table_freeze
устарела и не должна использоваться во вновь создаваемом коде.
Эта функция устарела и будет удалена в следующих релизах GLib. Она ничего не делает.
hash_table : |
GHashTable |
#define g_hash_table_thaw(hash_table)
g_hash_table_thaw
устарела и не должна использоваться во вновь создаваемом коде.
Эта функция устарела и будет удалена в следующих релизах GLib. Она ничего не делает.
hash_table : |
GHashTable |
void g_hash_table_destroy (GHashTable *hash_table);
Уничтожает все ключи и значения в GHashTable и уменьшает количество её ссылок на 1. Если ключи и/или значения распределены динамически,
вы должны либо освободить сначала их или создать GHashTable
с уничтожающим уведомлением используя g_hash_table_new_full()
. В последнем случае функция уничтожения, помещённая вами, будет вызвана для всех ключей и значений в течении фазы разрушения.
hash_table : |
GHashTable. |
GHashTable* g_hash_table_ref (GHashTable *hash_table);
Автоматически увеличивает количество ссылок hash_table
на одну.
Эта функция MT-безопасна и может быть вызвана из любого потока.
hash_table : |
правильная GHashTable. |
Возвращает : | передачу в GHashTable. |
Начиная с версии 2.10
void g_hash_table_unref (GHashTable *hash_table);
Автоматически уменьшает количество ссылок hash_table
на одну.
Если количество ссылок сброшено до 0, все ключи и значения будут уничтожены, а вся память, распределённая
для хеш таблицы, освобождена.
Эта функция MT-безопасна и может быть вызвана из любого потока.
hash_table : |
правильная GHashTable. |
Начиная с версии 2.10
gboolean g_direct_equal (gconstpointer v1, gconstpointer v2);
Сравнивает два аргумента gpointer и возвращает
TRUE
если они равны.
Она может быть помещена в g_hash_table_new()
как параметр key_equal_func
,
используя в качестве указателя ключ в GHashTable.
v1 : |
ключ. |
v2 : |
ключ для сравнения с v1 .
|
Возвращает : | TRUE если два ключа равны.
|
guint g_direct_hash (gconstpointer v);
Конвертирует gpointer в хеш значение.
Она может быть помещена в g_hash_table_new()
как параметр hash_func
,
используя в качестве указателя ключ в GHashTable.
v : |
gpointer key |
Возвращает : | хеш значение соответствующее ключу. |
gboolean g_int_equal (gconstpointer v1, gconstpointer v2);
Сравнивает два значения gint и возвращает
TRUE
если они равны.
Она может быть помещена в g_hash_table_new()
как параметр key_equal_func
, используя в качестве указателей на целочисленные ключи в
GHashTable.
guint g_int_hash (gconstpointer v);
Конвертирует указатель на gint в хеш значение.
Она может быть помещена в g_hash_table_new()
как параметр hash_func
,
используя в качестве указателей на целочисленные значения ключи в GHashTable.
v : |
указатель на gint ключ |
Возвращает : | хеш значение соответствующее ключу. |
gboolean g_str_equal (gconstpointer v1, gconstpointer v2);
Сравнивает две строки и возвращает TRUE
если они равны.
Она может быть помещена в g_hash_table_new()
как параметр key_equal_func
, используя в качестве строк ключи в GHashTable.
v1 : |
ключ. |
v2 : |
ключ для сравнения с v1 .
|
Возвращает : | TRUE если два ключа равны.
|
guint g_str_hash (gconstpointer v);
Конвертирует строку в хеш значение.
Она может помещаться в g_hash_table_new()
как параметр hash_func
,
используя в качестве строки ключ в GHashTable.
v : |
строка ключ. |
Возвращает : | хеш значение соответствующее ключу. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GHookList; void (*GHookFinalizeFunc) (GHookList *hook_list, GHook *hook); GHook; void (*GHookFunc) (gpointer data); gboolean (*GHookCheckFunc) (gpointer data); void g_hook_list_init (GHookList *hook_list, guint hook_size); void g_hook_list_invoke (GHookList *hook_list, gboolean may_recurse); void g_hook_list_invoke_check (GHookList *hook_list, gboolean may_recurse); void g_hook_list_marshal (GHookList *hook_list, gboolean may_recurse, GHookMarshaller marshaller, gpointer marshal_data); void (*GHookMarshaller) (GHook *hook, gpointer marshal_data); void g_hook_list_marshal_check (GHookList *hook_list, gboolean may_recurse, GHookCheckMarshaller marshaller, gpointer marshal_data); gboolean (*GHookCheckMarshaller) (GHook *hook, gpointer marshal_data); void g_hook_list_clear (GHookList *hook_list); GHook* g_hook_alloc (GHookList *hook_list); #define g_hook_append ( hook_list, hook ) void g_hook_prepend (GHookList *hook_list, GHook *hook); void g_hook_insert_before (GHookList *hook_list, GHook *sibling, GHook *hook); void g_hook_insert_sorted (GHookList *hook_list, GHook *hook, GHookCompareFunc func); gint (*GHookCompareFunc) (GHook *new_hook, GHook *sibling); gint g_hook_compare_ids (GHook *new_hook, GHook *sibling); GHook* g_hook_get (GHookList *hook_list, gulong hook_id); GHook* g_hook_find (GHookList *hook_list, gboolean need_valids, GHookFindFunc func, gpointer data); gboolean (*GHookFindFunc) (GHook *hook, gpointer data); GHook* g_hook_find_data (GHookList *hook_list, gboolean need_valids, gpointer data); GHook* g_hook_find_func (GHookList *hook_list, gboolean need_valids, gpointer func); GHook* g_hook_find_func_data (GHookList *hook_list, gboolean need_valids, gpointer func, gpointer data); GHook* g_hook_first_valid (GHookList *hook_list, gboolean may_be_in_call); GHook* g_hook_next_valid (GHookList *hook_list, GHook *hook, gboolean may_be_in_call); enum GHookFlagMask; #define G_HOOK_FLAGS (hook) #define G_HOOK_FLAG_USER_SHIFT #define G_HOOK (hook) #define G_HOOK_IS_VALID (hook) #define G_HOOK_ACTIVE (hook) #define G_HOOK_IN_CALL (hook) #define G_HOOK_IS_UNLINKED (hook) GHook* g_hook_ref (GHookList *hook_list, GHook *hook); void g_hook_unref (GHookList *hook_list, GHook *hook); void g_hook_free (GHookList *hook_list, GHook *hook); gboolean g_hook_destroy (GHookList *hook_list, gulong hook_id); void g_hook_destroy_link (GHookList *hook_list, GHook *hook);
GHookList, GHook и связанные с ними функции обеспечивают поддержку для списков hook-функций. Функции могут быть добавлены и удалены из списков, а список hook-функций может быть вызван.
typedef struct { gulong seq_id; guint hook_size : 16; guint is_setup : 1; GHook *hooks; gpointer dummy3; GHookFinalizeFunc finalize_hook; gpointer dummy[2]; } GHookList;
Структура GHookList представляет список hook-функций.
gulong seq_id ; |
следующий свободный GHook id. |
guint hook_size : 16; |
размер элементов GHookList, в байтах. |
guint is_setup : 1; |
1 если GHookList была инициализирована. |
GHook *hooks ; |
первый элемент GHook в списке. |
gpointer dummy3 ; |
|
GHookFinalizeFunc finalize_hook ; |
функция вызываемая для завершающего элемента GHook. По умолчанию вызывается разрушающая функция обработчика прерывания. |
gpointer dummy [2]; |
void (*GHookFinalizeFunc) (GHookList *hook_list, GHook *hook);
Определяет тип функции вызываемой для завершающего прерывания в списке прерываний.
hook_list : |
GHookList. |
hook : |
завершающее прерывание в hook_list .
|
typedef struct { gpointer data; GHook *next; GHook *prev; guint ref_count; gulong hook_id; guint flags; gpointer func; GDestroyNotify destroy; } GHook;
Структура GHook представляет единственную hook-функцию в GHookList.
gpointer data ; |
данные помещаемые в функцию когда вызвано прерывание. |
GHook *next ; |
указатель на следующее прерывание в списке. |
GHook *prev ; |
указатель на предыдущее прерывание в списке. |
guint ref_count ; |
количество ссылок на это прерывание. |
gulong hook_id ; |
id этого прерывания, который уникален внутри этого списка. |
guint flags ; |
флаги устанавливаемые для этого прерывания. Смотрите предопределённые флаги в GHookFlagMask. |
gpointer func ; |
функция вызываемая при возникновении этого прерывания. Возможными сигнатурами для этой функции являются GHookFunc и GHookCheckFunc. |
GDestroyNotify destroy ; |
по умолчанию finalize_hook функция
GHookList вызывает этот элемент прерывания для завершения.
|
void (*GHookFunc) (gpointer data);
Определяет тип hook-функции которую может вызвать g_hook_list_invoke()
.
data : |
поле данных GHook помещаемых в hook-функцию. |
gboolean (*GHookCheckFunc) (gpointer data);
Определяет тип функции которая может быть вызвана g_hook_list_invoke_check()
.
void g_hook_list_init (GHookList *hook_list, guint hook_size);
Инициализирует GHookList. Должна вызываться после использования GHookList.
void g_hook_list_invoke_check (GHookList *hook_list, gboolean may_recurse);
Вызывает все GHook функции в GHookList.
Любая функция которая возвращает TRUE
удаляется из
GHookList.
void g_hook_list_marshal (GHookList *hook_list, gboolean may_recurse, GHookMarshaller marshaller, gpointer marshal_data);
Вызывает функцию в каждом допустимом GHook.
void (*GHookMarshaller) (GHook *hook, gpointer marshal_data);
Определяет тип функции используемой в g_hook_list_marshal()
.
hook : |
GHook. |
marshal_data : |
пользовательские данные. |
void g_hook_list_marshal_check (GHookList *hook_list, gboolean may_recurse, GHookCheckMarshaller marshaller, gpointer marshal_data);
Вызывает функцию для каждого допустимого GHook и уничтожает его если
функция возвращает FALSE
.
gboolean (*GHookCheckMarshaller) (GHook *hook, gpointer marshal_data);
Определяет тип функции используемой в g_hook_list_marshal_check()
.
void g_hook_list_clear (GHookList *hook_list);
Удаляет все GHook элементы из GHookList.
hook_list : |
GHookList. |
GHook* g_hook_alloc (GHookList *hook_list);
Распределяет место для GHook и инициализирует его.
void g_hook_insert_before (GHookList *hook_list, GHook *sibling, GHook *hook);
void g_hook_insert_sorted (GHookList *hook_list, GHook *hook, GHookCompareFunc func);
gint (*GHookCompareFunc) (GHook *new_hook, GHook *sibling);
Определяет тип функции используемой для сравнения GHook элементов в
g_hook_insert_sorted()
.
gint g_hook_compare_ids (GHook *new_hook, GHook *sibling);
Сравнивает ids двух GHook элементов, возвращает отрицательное значение если второй id больше первого.
GHook* g_hook_get (GHookList *hook_list, gulong hook_id);
Возвращает GHook с полученным id, или NULL
если он не найден.
GHook* g_hook_find (GHookList *hook_list, gboolean need_valids, GHookFindFunc func, gpointer data);
Ищет GHook в GHookList используя функцию для проверочного сравнения.
hook_list : |
GHookList. |
need_valids : |
TRUE если GHook которые были разрушены должны быть пропущены.
|
func : |
функция вызываемая для каждого GHook, которая должна возвращать
TRUE когда
GHook найден.
|
data : |
данные помещаемые в func .
|
Возвращает : | найденый GHook или
NULL если соответствующий
GHook не найден.
|
gboolean (*GHookFindFunc) (GHook *hook, gpointer data);
Определяет тип функции помещаемой в g_hook_find()
.
hook : |
GHook. |
data : |
пользовательские данные помещаемые в g_hook_find_func() .
|
Возвращает : |
TRUE если требуемый GHook был найден.
|
GHook* g_hook_find_data (GHookList *hook_list, gboolean need_valids, gpointer data);
GHook* g_hook_find_func (GHookList *hook_list, gboolean need_valids, gpointer func);
GHook* g_hook_find_func_data (GHookList *hook_list, gboolean need_valids, gpointer func, gpointer data);
GHook* g_hook_first_valid (GHookList *hook_list, gboolean may_be_in_call);
Возвращает первый GHook в
GHookList который небыл разрушен.
Количество ссылок для GHook увеличивается, поэтому вы должны вызвать
g_hook_unref()
для его восстановления когда он больше не нужен.
(Или вызвать g_hook_next_valid()
если вы двигаетесь
через GHookList.)
GHook* g_hook_next_valid (GHookList *hook_list, GHook *hook, gboolean may_be_in_call);
Возвращает следующий GHook в GHookList который небыл разрушен.
Количество ссылок для GHook уменьшается, поэтому вы должны вызвать
g_hook_unref()
для восстановления когда он больше не нужен.
(Или вызывать g_hook_next_valid()
пока не вернётся NULL
.)
typedef enum { G_HOOK_FLAG_ACTIVE = 1 << 0, G_HOOK_FLAG_IN_CALL = 1 << 1, G_HOOK_FLAG_MASK = 0x0f } GHookFlagMask;
Флаги используемые внутренней реализацией GHook.
#define G_HOOK_FLAGS(hook) (G_HOOK (hook)->flags)
Возвращает флаги hook.
hook : |
GHook. |
#define G_HOOK_FLAG_USER_SHIFT (4)
Позиция первого бита который не зарезервирован для внутреннего использования реализацией
GHook, то есть
1 << G_HOOK_FLAG_USER_SHIFT
это первый бит который
может использоваться для определённых приложением флагов.
#define G_HOOK_IS_VALID(hook)
Возвращает TRUE
если GHook допустим,
то есть он в GHookList, он активен и он был разрушен.
#define G_HOOK_ACTIVE(hook)
Возвращает TRUE
если GHook активен, который обычно TRUE
пока GHook разрушен.
#define G_HOOK_IN_CALL(hook)
Возвращает TRUE
если
GHook функция в текущий момент выполняется.
GHook* g_hook_ref (GHookList *hook_list, GHook *hook);
Увеличивает количество ссылок для GHook.
void g_hook_unref (GHookList *hook_list, GHook *hook);
Уменьшает количество ссылок GHook.
Если количество ссылок равно 0, GHook удаляется из
GHookList
и вызывается g_hook_free()
для его освобождения.
void g_hook_free (GHookList *hook_list, GHook *hook);
Вызывает GHookList
hook_free
функцию если она существует и освобождает память
распределённую для GHook.
gboolean g_hook_destroy (GHookList *hook_list, gulong hook_id);
Разрушает GHook, получая его ID.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> #include <glib/gi18n.h> #define _ (String) #define Q_ (String) #define N_ (String) const gchar* g_strip_context (const gchar *msgid, const gchar *msgval); const gchar* const * g_get_language_names (void);
GLib не требует от пользователей использовать специальный метод интернационализации.
А так как GLib сама локализована с использованием механизма
gettext()
, является естественным предложение фактического стандарта
gettext()
поддерживающего макросы в простой для использования форме.
Для использования этих макросов в приложениях, вы должны включить glib/gi18n.h
.
Для использования в библиотеке, вы должны включить glib/gi18n-lib.h
после определения макроса GETTEXT_PACKAGE соответственно для вашей библиотеки:
#define GETTEXT_PACKAGE "gtk20" #include <glib/gi18n-lib.h>
#define _(String)
Маркирует строку для перевода, заменяется переведённой строкой во время выполнения.
String : |
строка для перевода |
Начиная с версии 2.4
#define Q_(String)
Аналогично _()
, но применяет
g_strip_context()
для перевода.
Это имеет преимущество, потомучто строка может быть дополнена префиксом для гарантии уникальности и обеспечения содержимого для перевода.
Один случай использования приведён в руководстве gettext - это перевод GUI, где можно снять неоднозначность двух меню "Open" как "File|Open" и "Printer|Open". Другой способ использования - это строка "Russian" которая может иметь разный перевод в зависимости от того является ли она названием набора символов или языка. Это может быть решено при помощи "charset|Russian" и "language|Russian".
String : |
строка для перевода, с префиксом отделённым знаком '|', который не должен транслироваться |
Начиная с версии 2.4
#define N_(String)
Маркирует строку для перевода, заменяется не переведённой строкой во время выполнения. Это полезно в ситуациях где переведённые строки не могут быть использованы напрямую, например в инициализаторах строковых массивов.
{ static const char *messages[] = { N_("некоторое очень значимое сообщение"), N_("и ещё одно") }; const char *string; ... string = index > 1 ? _("сообщение по умолчанию") : gettext (messages[index]); fputs (string); ... }
String : |
строка для перевода |
Начиная с версии 2.4
const gchar* g_strip_context (const gchar *msgid, const gchar *msgval);
Вспомогательная функция для поддержки
gettext()
(смотрите Q_()
).
msgid : |
строка |
msgval : |
другая строка |
Возвращает : | msgval , если msgval
не идентичен msgid и содержит
символ '|', в этом случае возвращается указатель на подстроку msgid после первого символа '|'.
|
Начиная с версии 2.4
const gchar* const * g_get_language_names (void);
Вычисляет список применимых имён локалей, которые могут быть использованы например для конструирования locale-зависимых имён файлов или поиска путей. Возвращаемый список сортируется от самого желательного до менее желательного и всегда содержит локаль по умолчанию "C".
Например, если LANGUAGE=de:en_US, то возвращаемый список будет "de", "en_US", "en", "C".
Эта функция консультируется с переменными окружения LANGUAGE
,
LC_ALL
, LC_MESSAGES
и LANG
для поиска списка локалей определённых пользователем.
Возвращает : | NULL -завершённый массив строк которыми владеет GLib
и они не должны освобождаться или изменяться.
|
Начиная с версии 2.6
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GIOChannel; GIOChannel* g_io_channel_unix_new (int fd); gint g_io_channel_unix_get_fd (GIOChannel *channel); GIOChannel* g_io_channel_win32_new_fd (gint fd); GIOChannel* g_io_channel_win32_new_socket (gint socket); GIOChannel* g_io_channel_win32_new_messages (guint hwnd); void g_io_channel_init (GIOChannel *channel); GIOChannel* g_io_channel_new_file (const gchar *filename, const gchar *mode, GError **error); GIOStatus g_io_channel_read_chars (GIOChannel *channel, gchar *buf, gsize count, gsize *bytes_read, GError **error); GIOStatus g_io_channel_read_unichar (GIOChannel *channel, gunichar *thechar, GError **error); GIOStatus g_io_channel_read_line (GIOChannel *channel, gchar **str_return, gsize *length, gsize *terminator_pos, GError **error); GIOStatus g_io_channel_read_line_string (GIOChannel *channel, GString *buffer, gsize *terminator_pos, GError **error); GIOStatus g_io_channel_read_to_end (GIOChannel *channel, gchar **str_return, gsize *length, GError **error); GIOStatus g_io_channel_write_chars (GIOChannel *channel, const gchar *buf, gssize count, gsize *bytes_written, GError **error); GIOStatus g_io_channel_write_unichar (GIOChannel *channel, gunichar thechar, GError **error); GIOStatus g_io_channel_flush (GIOChannel *channel, GError **error); GIOStatus g_io_channel_seek_position (GIOChannel *channel, gint64 offset, GSeekType type, GError **error); enum GSeekType; GIOStatus g_io_channel_shutdown (GIOChannel *channel, gboolean flush, GError **err); enum GIOStatus; enum GIOChannelError; #define G_IO_CHANNEL_ERROR GIOChannelError g_io_channel_error_from_errno (gint en); GIOChannel* g_io_channel_ref (GIOChannel *channel); void g_io_channel_unref (GIOChannel *channel); GSource* g_io_create_watch (GIOChannel *channel, GIOCondition condition); guint g_io_add_watch (GIOChannel *channel, GIOCondition condition, GIOFunc func, gpointer user_data); guint g_io_add_watch_full (GIOChannel *channel, gint priority, GIOCondition condition, GIOFunc func, gpointer user_data, GDestroyNotify notify); enum GIOCondition; gboolean (*GIOFunc) (GIOChannel *source, GIOCondition condition, gpointer data); GIOFuncs; gsize g_io_channel_get_buffer_size (GIOChannel *channel); void g_io_channel_set_buffer_size (GIOChannel *channel, gsize size); GIOCondition g_io_channel_get_buffer_condition (GIOChannel *channel); GIOFlags g_io_channel_get_flags (GIOChannel *channel); GIOStatus g_io_channel_set_flags (GIOChannel *channel, GIOFlags flags, GError **error); enum GIOFlags; const gchar* g_io_channel_get_line_term (GIOChannel *channel, gint *length); void g_io_channel_set_line_term (GIOChannel *channel, const gchar *line_term, gint length); gboolean g_io_channel_get_buffered (GIOChannel *channel); void g_io_channel_set_buffered (GIOChannel *channel, gboolean buffered); const gchar* g_io_channel_get_encoding (GIOChannel *channel); GIOStatus g_io_channel_set_encoding (GIOChannel *channel, const gchar *encoding, GError **error); gboolean g_io_channel_get_close_on_unref (GIOChannel *channel); void g_io_channel_set_close_on_unref (GIOChannel *channel, gboolean do_close); GIOError g_io_channel_read (GIOChannel *channel, gchar *buf, gsize count, gsize *bytes_read); enum GIOError; GIOError g_io_channel_write (GIOChannel *channel, const gchar *buf, gsize count, gsize *bytes_written); GIOError g_io_channel_seek (GIOChannel *channel, gint64 offset, GSeekType type); void g_io_channel_close (GIOChannel *channel);
Тип данных GIOChannel предназначен для обеспечения переносимого метода использования файловых дескрипторов, каналов и сокетов, интегрируя их в main event loop. В настоящий момент доступна полная поддержка на UNIX платформах, поддержка для Windows выполнена только частично.
Для создания новой GIOChannel в UNIX системах используйте g_io_channel_unix_new()
.
Это работает для простых дескрипторов файла, каналов и сокетов.
Альтернативно, канал может быть создан для файла независимым от системы способом используя
g_io_channel_new_file()
.
Как только GIOChannel
создана, она может использоваться обычным способом в функциях
g_io_channel_read_chars()
, g_io_channel_write_chars()
,
g_io_channel_seek_position()
и g_io_channel_shutdown()
.
Для добавления GIOChannel в
основной цикл событий
используйте g_io_add_watch()
или g_io_add_watch_full()
. Так определяется какие события вас интересуют в
GIOChannel и обеспечивается функция которая будет вызываться каждый раз когда происходит это событие.
GIOChannel создаётся с начальным количеством ссылок равным 1.
Функции g_io_channel_ref()
и g_io_channel_unref()
могут использоваться для увеличения и уменьшения количества ссылок соответственно.
Когда количество ссылок достигло 0, GIOChannel освобождается (хотя она не закрывается автоматически,
если не создана с использованием g_io_channel_new_from_file()
).
Использование g_io_add_watch()
или g_io_add_watch_full()
увеличивает количество ссылок каналов.
Новые функции g_io_channel_read_chars()
, g_io_channel_read_line()
,
g_io_channel_read_line_string()
, g_io_channel_read_to_end()
,
g_io_channel_write_chars()
, g_io_channel_seek_position()
,
и g_io_channel_flush()
не должны использоваться совместно с устаревшими функциями
g_io_channel_read()
, g_io_channel_write()
,
и g_io_channel_seek()
в одном и том же канале.
typedef struct { } GIOChannel;
Структура данных представляющая IO Channel (канал ввода-вывода). Поля этой структуры должны рассматриваться как закрытые и могут использоваться только следующими функциями.
GIOChannel* g_io_channel_unix_new (int fd);
Создаёт новую GIOChannel полученного дескриптора файла. В UNIX системах это работает для простых файлов, каналов и сокетов.
Возвращаемая GIOChannel имеет количество ссылок равное 1.
Кодировкой по умолчанию для GIOChannel является UTF-8. Если ваша программа читает вывод из команд используя via pipe,
вам может понадобиться установить кодировку в текущую кодировку локали (смотрите
g_get_charset()
) с помощью функции g_io_channel_set_encoding()
.
Если вы хотите читать исходные двоичные данные без интерпретации, то вызовите
g_io_channel_set_encoding()
функцию с параметром кодировки равным NULL
.
Эта функция GLib доступна также в Windows, но вы должны избегать использования её в Windows. Область дескрипторов файла и сокетов перекрывается. Здесь нет способа для GLib узнать что вы подразумеваете в случае помещения в качестве аргументов в эту функцию и правильного дескриптора файла и сокета. Если это происходит то выдаётся предупреждение, а GLib предполагает что это дескриптор файла который вы подразумевали.
fd : |
дескриптор файла. |
Возвращает : | новая GIOChannel. |
gint g_io_channel_unix_get_fd (GIOChannel *channel);
Возвращает дескриптор файла GIOChannel.
В Windows эта функция вернёт дескриптор файла или сокет GIOChannel.
channel : |
GIOChannel, созданная с помощью g_io_channel_unix_new() .
|
Возвращает : | дескриптор файла GIOChannel. |
GIOChannel* g_io_channel_win32_new_fd (gint fd);
Создаёт новую GIOChannel получая дескриптор файла в Windows. Работает для дескрипторов файлов из C runtime.
Эта функция работает для дескрипторов файлов которые возвращают open()
,
creat()
, pipe()
и fileno()
вызовы в Microsoft C runtime. Для обоснованного использования этой функции ваш код должен
использовать туже C runtime которую использует GLib, которой является
msvcrt.dll. Помните что текущий компилятор Microsoft не подходит для
сборки кода который использует msvcrt.dll. Последняя версия компилятора
Microsoft которая поддерживала использование msvcrt.dll как C runtime
была версия 6. Компилятор GNU и инструменты для Windows, также известные
как Mingw, полностью поддерживают msvcrt.dll.
Если вы создали GIOChannel
для дескриптора файла и запустили её просмотр (опрос), вы не должны вызывать read()
для дескриптора файла. Это потому, что добавление опроса для дескриптора файла
реализовано в GLib на платформе Windows с помощью запуска потока который остаётся блокированным в read()
из дескриптора файла больше времени. Все читатели дескриптора файла
должны быть выполнены этим внутренним потоком GLib. Ваш код должен вызывать только
g_io_channel_read()
.
Эта функция доступна только в GLib для Windows.
fd : |
дескриптор файла библиотеки C. |
Возвращает : | новая GIOChannel. |
GIOChannel* g_io_channel_win32_new_socket (gint socket);
Создаёт новую GIOChannel получая сокет в Windows.
Эта функция работает для сокетов созданных при помощи Winsock. Она доступна только в GLib для Windows.
Опрос GSource создаёт канал просмотра для сокета помещая сокет в не блокированный режим. Это неизбежный побочный эффект реализации.
socket : |
|
Возвращает : | новая GIOChannel. |
GIOChannel* g_io_channel_win32_new_messages (guint hwnd);
Создаёт новую GIOChannel получая обработку окна в Windows.
Эта функция создаёт GIOChannel которая может использоваться для опроса сообщений Windows запрашиваемого окна.
hwnd : |
обрабатываемое окно. |
Возвращает : | новая GIOChannel. |
void g_io_channel_init (GIOChannel *channel);
Инициализирует структуру GIOChannel. Вызывается каждой из вышеупомянутых функций когда создаётся GIOChannel, а также часто необходима для разработчиков приложений (если вы создаёте новый тип GIOChannel).
channel : |
GIOChannel. |
GIOChannel* g_io_channel_new_file (const gchar *filename, const gchar *mode, GError **error);
Открывает файл filename
как GIOChannel используя режим mode
. Этот канал будет закрыт при сбросе последней ссылки на него,
поэтому нет необходимости вызывать g_io_channel_close()
(такое выполнение не вызовет никаких проблем, пока не попытается обратиться к уже закрытому каналу).
filename : |
строка содержащая имя файла. |
mode : |
Один из режимов "r", "w", "a", "r+", "w+", "a+". Тоже самое как в fopen() .
|
error : |
расположение возвращаемой ошибки типа G_FILE_ERROR .
|
Возвращает : | GIOChannel при успешном выполнении, NULL при неудаче.
|
GIOStatus g_io_channel_read_chars (GIOChannel *channel, gchar *buf, gsize count, gsize *bytes_read, GError **error);
Замена для g_io_channel_read()
с новым API.
channel : |
GIOChannel |
buf : |
буфер из которого читаются данные |
count : |
размер буфера. Помните что буфер может быть заполнен не полностью если оставшиеся данные не полный символ. |
bytes_read : |
количество читаемых байт. Может быть ноль даже при удаче, если количество < 6
а кодировка каналов не-NULL .
Это указывает что следующий символ UTF-8 слишком большой для буфера.
|
error : |
расположение возвращаемой ошибки типа GConvertError или GIOChannelError. |
Возвращает : | состояние операции. |
GIOStatus g_io_channel_read_unichar (GIOChannel *channel, gunichar *thechar, GError **error);
Эта функция не может быть вызвана для канала с NULL
кодировкой.
channel : |
GIOChannel |
thechar : |
расположение возвращаемого символа |
error : |
расположение возвращаемой ошибки типа GConvertError или GIOChannelError |
Возвращает : | GIOStatus |
GIOStatus g_io_channel_read_line (GIOChannel *channel, gchar **str_return, gsize *length, gsize *terminator_pos, GError **error);
Читает строку, включая завершающий символ(ы),
из GIOChannel во вновь распределённой строке.
str_return
будет содержать распределённую память если
возвращаемое значение G_IO_STATUS_NORMAL
.
channel : |
GIOChannel |
str_return : |
Читаемая строка из GIOChannel, включая завершающий символ. Эти данные должны освобождаться с помощью g_free()
когда больше не нужны. Это nul-terminated строка.
Если возвращаемая length равна нулю, то вместо этого она будет NULL .
|
length : |
размещение для сохранения длины читаемых данных, или NULL
|
terminator_pos : |
размещение для сохранения позиции завершающей строку, или NULL
|
error : |
расположение для возвращаемой ошибки типа GConvertError или GIOChannelError |
Возвращает : | статус операции. |
GIOStatus g_io_channel_read_line_string (GIOChannel *channel, GString *buffer, gsize *terminator_pos, GError **error);
Читает строку из GIOChannel, используя GString как буфер.
channel : |
GIOChannel |
buffer : |
GString в который записывается строка.
Если buffer уже содержит данные, они будут перезаписаны.
|
terminator_pos : |
расположение для сохранения позиции завершения строки, или NULL
|
error : |
расположение для сохранения ошибки типа GConvertError или GIOChannelError |
Возвращает : | состояние операции. |
GIOStatus g_io_channel_read_to_end (GIOChannel *channel, gchar **str_return, gsize *length, GError **error);
Читает все оставшиеся данные из файла.
channel : |
GIOChannel |
str_return : |
расположение для хранения указателя на строку содержащую
оставшиеся данные в GIOChannel. Эти данные должны освобождаться с помощью
g_free() когда больше не нужны. Эти данные
завершаются дополнительным символом nul, но могут быть другие
nuls в предыдущих данных.
|
length : |
расположение для хранения длины данных |
error : |
расположение для возвращаемой ошибки типа GConvertError или GIOChannelError |
Возвращает : | G_IO_STATUS_NORMAL при успешном выполнении.
Эта функция никогда не возвращает G_IO_STATUS_EOF .
|
GIOStatus g_io_channel_write_chars (GIOChannel *channel, const gchar *buf, gssize count, gsize *bytes_written, GError **error);
Замена для g_io_channel_write()
с новым API.
В seekable каналах с кодировкой отличающейся от NULL
или UTF-8, смешивание чтения и записи недопустимо.
Вызов g_io_channel_write_chars()
может быть сделан только в канале из которого данные были прочитаны в случае описанном в документации для g_io_channel_set_encoding()
.
channel : |
GIOChannel |
buf : |
буфер из которого записываются данные |
count : |
размер буфера. Если -1, буфер применяется для nul-terminated строки. |
bytes_written : |
количество записываемых байт. Может быть не нулевым даже если возвращаемое значение не G_IO_STATUS_NORMAL .
Если возвращаемое значение G_IO_STATUS_NORMAL и канал заблокирован, значение всегда эквивалентно count если count >= 0.
|
error : |
Расположение возвращаемой ошибки типа GConvertError или GIOChannelError |
Возвращает : | статус операции. |
GIOStatus g_io_channel_write_unichar (GIOChannel *channel, gunichar thechar, GError **error);
Эта функция не должна вызываться в канале с NULL
кодировкой.
channel : |
GIOChannel |
thechar : |
символ |
error : |
расположение возвращаемой ошибки типа GConvertError или GIOChannelError |
Возвращает : | GIOStatus |
GIOStatus g_io_channel_flush (GIOChannel *channel, GError **error);
Синхронизирует данные буфера записанные в памяти и на диске для GIOChannel.
channel : |
GIOChannel |
error : |
расположение возвращаемой ошибки типа GIOChannelError |
Возвращает : | статус операции: G_IO_CHANNEL_NORMAL, G_IO_CHANNEL_AGAIN, или G_IO_CHANNEL_ERROR. |
GIOStatus g_io_channel_seek_position (GIOChannel *channel, gint64 offset, GSeekType type, GError **error);
Замена для g_io_channel_seek()
с новым API.
channel : |
GIOChannel |
offset : |
смещение в байтах из позиции определённой с помощью type
|
type : |
GSeekType. Тип G_SEEK_CUR допустим только когда допустим вызов g_io_channel_set_encoding() .
Смотрите документацию для g_io_channel_set_encoding() для детального изучения.
|
error : |
расположение возвращаемой ошибки типа GIOChannelError |
Возвращает : | статус операции. |
typedef enum { G_SEEK_CUR, G_SEEK_SET, G_SEEK_END } GSeekType;
Перечисление определяющее начальную позицию для g_io_channel_seek_position()
операции.
GIOStatus g_io_channel_shutdown (GIOChannel *channel, gboolean flush, GError **err);
Закрывает IO канал. Любые данные ждущие обработки будут записаны на диск если параметр flush
равен TRUE
. Канал не освобождается пока последняя ссылка не сброшена с помощью g_io_channel_unref()
.
channel : |
GIOChannel |
flush : |
если TRUE , ожидающие обработки данные записываются на диск синхронизируя содержимое памяти и диска
|
err : |
расположение для хранения GIOChannelError |
Возвращает : | статус операции. |
typedef enum { G_IO_STATUS_ERROR, G_IO_STATUS_NORMAL, G_IO_STATUS_EOF, G_IO_STATUS_AGAIN } GIOStatus;
Статусы возвращаемые большинством GIOFuncs функций.
typedef enum { /* Derived from errno */ G_IO_CHANNEL_ERROR_FBIG, G_IO_CHANNEL_ERROR_INVAL, G_IO_CHANNEL_ERROR_IO, G_IO_CHANNEL_ERROR_ISDIR, G_IO_CHANNEL_ERROR_NOSPC, G_IO_CHANNEL_ERROR_NXIO, G_IO_CHANNEL_ERROR_OVERFLOW, G_IO_CHANNEL_ERROR_PIPE, /* Other */ G_IO_CHANNEL_ERROR_FAILED } GIOChannelError;
Коды ошибок возвращаемые GIOChannel операциями.
#define G_IO_CHANNEL_ERROR g_io_channel_error_quark()
Ошибочная область для GIOChannel операций. Ошибки в этой области будут из GIOChannelError перечисления. Смотрите GError для информации об ошибочных областях.
GIOChannelError g_io_channel_error_from_errno (gint en);
Конвертирует номер ошибки errno
в GIOChannelError.
en : |
номер ошибки errno , например EINVAL .
|
Возвращает : | GIOChannelError номер ошибки, например G_IO_CHANNEL_ERROR_INVAL .
|
GIOChannel* g_io_channel_ref (GIOChannel *channel);
Увеличивает количество ссылок GIOChannel.
channel : |
GIOChannel. |
Возвращает : | channel в который был помещён (Начиная с версии 2.6)
|
void g_io_channel_unref (GIOChannel *channel);
Уменьшает количество ссылок GIOChannel.
channel : |
GIOChannel. |
GSource* g_io_create_watch (GIOChannel *channel, GIOCondition condition);
Создаёт GSource которая отправляется когда встретилось condition
для данного
channel
. Например, если условие G_IO_IN, источник будет отправлен когда появятся данные доступные для чтения. g_io_add_watch()
- это более простой интерфейс для тех же самых функциональных возможностей,
в случае когда вы хотите добавить в основной цикл по умолчанию приоритет по умолчанию.
В Windows, опрос GSource создаётся для просматриваемого канала для сокета, помещая сокет в деблокированный режим. Этот побочный эффект реализации неизбежен.
channel : |
GIOChannel to watch |
condition : |
прсматриваемое условие |
Возвращает : | новая GSource |
guint g_io_add_watch (GIOChannel *channel, GIOCondition condition, GIOFunc func, gpointer user_data);
Добавляет GIOChannel в основной цикл собития с приоритетом по умолчанию.
channel : |
GIOChannel. |
condition : |
условие для просмотра. |
func : |
функция вызываемая когда условие удовлетворено. |
user_data : |
пользовательские данные помещаемые в func .
|
Возвращает : | id источника события. |
guint g_io_add_watch_full (GIOChannel *channel, gint priority, GIOCondition condition, GIOFunc func, gpointer user_data, GDestroyNotify notify);
Добавляет GIOChannel в основной цикл события с полученным приоритетом.
channel : |
GIOChannel. |
priority : |
приоритет GIOChannel источника. |
condition : |
рассматриваемое условие. |
func : |
функция вызываемая при удовлетворении условия. |
user_data : |
пользовательские данные помещаемые в func .
|
notify : |
функция вызываемая при удалении источника. |
Возвращает : | id источника события. |
typedef enum { G_IO_IN GLIB_SYSDEF_POLLIN, G_IO_OUT GLIB_SYSDEF_POLLOUT, G_IO_PRI GLIB_SYSDEF_POLLPRI, G_IO_ERR GLIB_SYSDEF_POLLERR, G_IO_HUP GLIB_SYSDEF_POLLHUP, G_IO_NVAL GLIB_SYSDEF_POLLNVAL } GIOCondition;
Побитовые комбинации представляющие рассматриваемые условия для источника события.
gboolean (*GIOFunc) (GIOChannel *source, GIOCondition condition, gpointer data);
Определяет тип функции помещаемой в g_io_add_watch()
или
g_io_add_watch_full()
, которая вызывается когда запрашиваемое условие в
GIOChannel удовлетворено.
source : |
источник события GIOChannel. |
condition : |
условие которое должно удовлетворяться. |
data : |
пользовательские данные устанавливаемые в g_io_add_watch() или g_io_add_watch_full() .
|
Возвращает : | функция должна вернуть FALSE если источник события должен быть удалён.
|
typedef struct { GIOStatus (*io_read) (GIOChannel *channel, gchar *buf, gsize count, gsize *bytes_read, GError **err); GIOStatus (*io_write) (GIOChannel *channel, const gchar *buf, gsize count, gsize *bytes_written, GError **err); GIOStatus (*io_seek) (GIOChannel *channel, gint64 offset, GSeekType type, GError **err); GIOStatus (*io_close) (GIOChannel *channel, GError **err); GSource* (*io_create_watch) (GIOChannel *channel, GIOCondition condition); void (*io_free) (GIOChannel *channel); GIOStatus (*io_set_flags) (GIOChannel *channel, GIOFlags flags, GError **err); GIOFlags (*io_get_flags) (GIOChannel *channel); } GIOFuncs;
Таблица функций используемых для обработки разных типов GIOChannel обычным способом.
gsize g_io_channel_get_buffer_size (GIOChannel *channel);
Получает размер буфера.
channel : |
GIOChannel |
Возвращает : | размер буфера. |
void g_io_channel_set_buffer_size (GIOChannel *channel, gsize size);
Устанавливает размер буфера.
channel : |
GIOChannel |
size : |
размер буфера. 0 == подобрать наилучший размер |
GIOCondition g_io_channel_get_buffer_condition (GIOChannel *channel);
Эта функция возвращает GIOCondition в зависимости от того, есть ли данные для чтения или свободное пространство для записи данных во внутренние буферы GIOChannel. Могут устанавливаться только флаги G_IO_IN
и
G_IO_OUT
.
channel : |
GIOChannel |
Возвращает : | GIOCondition |
GIOFlags g_io_channel_get_flags (GIOChannel *channel);
Получает текущие флаги для GIOChannel, включая флаги только для чтения такие как G_IO_FLAG_IS_READABLE
.
Значения флажков G_IO_FLAG_IS_READABLE
и G_IO_FLAG_IS_WRITEABLE
кэшируются для внутреннего использования каналом при его создании.
Если они позже должны измениться (например частичное завершение сокета с помощью
UNIX функции shutdown()
), пользователь должен немедленно вызвать
g_io_channel_get_flags()
для обновления внутренних значений этих флажков.
channel : |
GIOChannel |
Возвращает : | флаги которые устанавливаются в канале |
GIOStatus g_io_channel_set_flags (GIOChannel *channel, GIOFlags flags, GError **error);
Устанавливает (записываемые) флаги в channel
(flags
& G_IO_CHANNEL_SET_MASK
).
channel : |
GIOChannel. |
flags : |
флаги для установки в канал IO. |
error : |
расположение возвращаемой ошибки типа GIOChannelError. |
Возвращает : | статус операции. |
typedef enum { G_IO_FLAG_APPEND = 1 << 0, G_IO_FLAG_NONBLOCK = 1 << 1, G_IO_FLAG_IS_READABLE = 1 << 2, /* флаг доступный только для чтения */ G_IO_FLAG_IS_WRITEABLE = 1 << 3, /* флаг доступный только для чтения */ G_IO_FLAG_IS_SEEKABLE = 1 << 4, /* флаг доступный только для чтения */ G_IO_FLAG_MASK = (1 << 5) - 1, G_IO_FLAG_GET_MASK = G_IO_FLAG_MASK, G_IO_FLAG_SET_MASK = G_IO_FLAG_APPEND | G_IO_FLAG_NONBLOCK } GIOFlags;
Определяет свойства GIOChannel. Некоторые флаги можно только читать с помощью g_io_channel_get_flags()
, но нельзя изменять с помощью
g_io_channel_set_flags()
.
G_IO_FLAG_APPEND |
включает режим предварительной перемотки файла в конец (append mode), соответствует O_APPEND (смотрите документацию системного вызова UNIX ).
|
G_IO_FLAG_NONBLOCK |
включает не блокируемый режим, соответствует
O_NONBLOCK /O_NDELAY (смотрите документацию системного вызова UNIX
).
|
G_IO_FLAG_IS_READABLE |
указывает что канал читаемый. Этот флаг не может изменяться. |
G_IO_FLAG_IS_WRITEABLE |
указывает что канал записываемый. Этот флаг не может изменяться. |
G_IO_FLAG_IS_SEEKABLE |
указывает что io канал может изменять позицию доступа (seekable), то есть что в нём может использоваться функция
g_io_channel_seek_position() . Этот флаг не может изменяться.
|
G_IO_FLAG_MASK |
|
G_IO_FLAG_GET_MASK |
|
G_IO_FLAG_SET_MASK |
const gchar* g_io_channel_get_line_term (GIOChannel *channel, gint *length);
Возвращает строку которую GIOChannel использует для определения
где в файле происходит прерывание линии. Значение NULL
указывает автоматическое определение.
channel : |
GIOChannel |
length : |
расположение для возвращаемой длины завершающего строку символа |
Возвращает : | Строка завершения линии. Этим значением владеет GLib и оно не должно освобождаться. |
void g_io_channel_set_line_term (GIOChannel *channel, const gchar *line_term, gint length);
Устанавливает строку которую GIOChannel использует для определения где в файле происходит прерывание линии.
channel : |
GIOChannel |
line_term : |
Строка прерывания линии. Используйте NULL для автоматического определения.
Автоматическое определение прерывается на "\n", "\r\n", "\r", "\0", и
разделителе параграфов Unicode. Автоматическое определение не должно
использоваться ни для чего кроме каналов основанных на файлах.
|
length : |
Длина прерываемой строки. Если помещено значение -1, строка будет как предполагается nul-terminated. Эта опция позволяет прерывать строки с встроенным nuls. |
gboolean g_io_channel_get_buffered (GIOChannel *channel);
Определяет буферизуется ли channel
.
channel : |
GIOChannel. |
Возвращает : | TRUE если channel буферизуется.
|
void g_io_channel_set_buffered (GIOChannel *channel, gboolean buffered);
Состояние буферизации может быть установлено только если кодировка канала NULL
. Для любых других кодировок, канал должен буферизироваться.
Буферизированный канал может быть установлен не буферизированным только если внутренние буферы
канала были записаны на диск. Вновь созданные каналы или каналы вернувшие
G_IO_STATUS_EOF
не требуют производить такую запись. Для каналов только для записи, вызов
g_io_channel_flush()
достаточен. Для всех других каналов, буфер может быть синхронизирован с диском с помощью
вызова g_io_channel_seek_position()
.
Это включает возможность перемещения позиции типа G_SEEK_CUR
и нулевое смещение. Отметьте, это значит что каналы на основе сокетов не могут быть установлены не буферизированными как только из них начнётся чтение данных.
В небуферизованных каналах, безопасно смешивать вызовы чтения и записи из новых и старых APIs, если это необходимо для поддержки старого кода.
По умолчанию канал имеет буферизованное состояние.
channel : |
GIOChannel |
buffered : |
является ли канал буферизированным или нет |
const gchar* g_io_channel_get_encoding (GIOChannel *channel);
Получает кодировку для ввода/вывода канала. Внутренняя кодировка всегда UTF-8.
Кодировка NULL
делает канал безопасным для двоичных данных.
channel : |
GIOChannel |
Возвращает : | строка содержащая кодировку, строкой владеет GLib и она не должна освобождаться. |
GIOStatus g_io_channel_set_encoding (GIOChannel *channel, const gchar *encoding, GError **error);
Устанавливает кодировку для ввода/вывода канала. Внутренняя кодировка всегда UTF-8. Кодировка по умолчанию для внешних файлов UTF-8.
Кодировка NULL
безопасна для использования двоичных данных.
Кодировка может быть установлена только если выполняются следующие условия:
1. Канал был только что создан и операции чтения или записи не проводились.
2. Канал только для записи.
3. Канал это файл, а указатель файла был только что установлен с помощью вызова
g_io_channel_seek_position()
.
(Это записывает все внутренние буферы на диск.)
4. Текущая кодировка NULL
или UTF-8.
5. Одна из функций (новый API) чтения возвратила G_IO_STATUS_EOF
(или, в случае g_io_channel_read_to_end()
, G_IO_STATUS_NORMAL
).
6. Одна из функций g_io_channel_read_chars()
или g_io_channel_read_unichar()
вернула G_IO_STATUS_AGAIN
или G_IO_STATUS_ERROR
. Это может быть полезно в случае
G_CONVERT_ERROR_ILLEGAL_SEQUENCE
.
Возвращение одного из этих статусов из g_io_channel_read_line()
,
g_io_channel_read_line_string()
, или g_io_channel_read_to_end()
не гарантирует что кодировка может быть изменена.
Каналы которые не соответствуют одному из выше упомянутых условий не могут вызывать
g_io_channel_seek_position()
со смещением G_SEEK_CUR
,
и если они "seekable", не могут вызывать g_io_channel_write_chars()
после вызова одной из функций API "read".
channel : |
GIOChannel |
encoding : |
тип кодировки |
error : |
размещение для хранения ошибки типа GConvertError. |
Возвращает : | G_IO_STATUS_NORMAL если кодировка была полностью установлена.
|
gboolean g_io_channel_get_close_on_unref (GIOChannel *channel);
Определяет будет ли закрыт любой файл/сокет связанный с каналом channel
когда channel
будет разрушен при удалении последней ссылки на него. По умолчанию значение TRUE
для каналов созданных с помощью g_io_channel_new_file()
, а FALSE
для всех других каналов.
channel : |
GIOChannel. |
Возвращает : | будет ли закрыт канал при удалении последней ссылки на структуру данных GIOChannel. |
void g_io_channel_set_close_on_unref (GIOChannel *channel, gboolean do_close);
Установка этого флажка в TRUE
для канала который уже закрыт может вызвать проблемы.
channel : |
GIOChannel |
do_close : |
закрывается ли канал при удалении последней ссылки на структуру данных GIOChannel.
Значение по умолчанию TRUE для каналов созданных с помощью g_io_channel_new_file() ,
а FALSE для всех других каналов.
|
GIOError g_io_channel_read (GIOChannel *channel, gchar *buf, gsize count, gsize *bytes_read);
g_io_channel_read
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_read_chars()
вместо неё.
Читает данные из GIOChannel.
channel : |
GIOChannel. |
buf : |
буфер из которого читаются данные (which should be at least count bytes long). |
count : |
количество байт читаемых из GIOChannel. |
bytes_read : |
возвращает фактическое количество прочтенных байт. |
Возвращает : | G_IO_ERROR_NONE если операция была успешно выполнена.
|
typedef enum { G_IO_ERROR_NONE, G_IO_ERROR_AGAIN, G_IO_ERROR_INVAL, G_IO_ERROR_UNKNOWN } GIOError;
GIOError используется только устаревшими функциями g_io_channel_read()
,
g_io_channel_write()
, и g_io_channel_seek()
.
GIOError g_io_channel_write (GIOChannel *channel, const gchar *buf, gsize count, gsize *bytes_written);
g_io_channel_write
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_write_chars()
вместо неё.
Записывает данные в GIOChannel.
channel : |
a GIOChannel. |
buf : |
буфер содержащий данные для записи. |
count : |
количество байт для записи. |
bytes_written : |
количество фактически записанных байт. |
Возвращает : | G_IO_ERROR_NONE если операция полностью выполнена.
|
GIOError g_io_channel_seek (GIOChannel *channel, gint64 offset, GSeekType type);
g_io_channel_seek
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_seek_position()
вместо неё.
Устанавливает текущую позицию в GIOChannel, подобна стандартной библиотечной функции fseek()
.
channel : |
GIOChannel. |
offset : |
смещение в байтах, которое добавляется в позицию определённую type
|
type : |
позиция в файе, которая может быть G_SEEK_CUR (текущая позиция),
G_SEEK_SET (начало файла), или G_SEEK_END (конец файла).
|
Возвращает : | G_IO_ERROR_NONE если операция выполнена успешно.
|
void g_io_channel_close (GIOChannel *channel);
g_io_channel_close
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_io_channel_shutdown()
вместо неё.
Закрывает IO канал. Любые данные ожидающие обработки записываются на диск,
игнорируя ошибки. Канал не будет освобождён пока не сброшена последняя ссылка с помощью
g_io_channel_unref()
.
channel : |
GIOChannel |
gtk_input_add_full() , gtk_input_remove() , gdk_input_add() ,
gdk_input_add_full() , gdk_input_remove() |
Удобные функции для создания GIOChannel и добавления его в основной цикл события. |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GKeyFile; #define G_KEY_FILE_ERROR enum GKeyFileError; enum GKeyFileFlags; GKeyFile* g_key_file_new (void); void g_key_file_free (GKeyFile *key_file); void g_key_file_set_list_separator (GKeyFile *key_file, gchar separator); gboolean g_key_file_load_from_file (GKeyFile *key_file, const gchar *file, GKeyFileFlags flags, GError **error); gboolean g_key_file_load_from_data (GKeyFile *key_file, const gchar *data, gsize length, GKeyFileFlags flags, GError **error); gboolean g_key_file_load_from_data_dirs (GKeyFile *key_file, const gchar *file, gchar **full_path, GKeyFileFlags flags, GError **error); gchar* g_key_file_to_data (GKeyFile *key_file, gsize *length, GError **error); gchar* g_key_file_get_start_group (GKeyFile *key_file); gchar** g_key_file_get_groups (GKeyFile *key_file, gsize *length); gchar** g_key_file_get_keys (GKeyFile *key_file, const gchar *group_name, gsize *length, GError **error); gboolean g_key_file_has_group (GKeyFile *key_file, const gchar *group_name); gboolean g_key_file_has_key (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error); gchar* g_key_file_get_value (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error); gchar* g_key_file_get_string (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error); gchar* g_key_file_get_locale_string (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *locale, GError **error); gboolean g_key_file_get_boolean (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error); gint g_key_file_get_integer (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error); gdouble g_key_file_get_double (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error); gchar** g_key_file_get_string_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gsize *length, GError **error); gchar** g_key_file_get_locale_string_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *locale, gsize *length, GError **error); gboolean* g_key_file_get_boolean_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gsize *length, GError **error); gint* g_key_file_get_integer_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gsize *length, GError **error); gdouble* g_key_file_get_double_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gsize *length, GError **error); gchar* g_key_file_get_comment (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error); void g_key_file_set_value (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *value); void g_key_file_set_string (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *string); void g_key_file_set_locale_string (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *locale, const gchar *string); void g_key_file_set_boolean (GKeyFile *key_file, const gchar *group_name, const gchar *key, gboolean value); void g_key_file_set_integer (GKeyFile *key_file, const gchar *group_name, const gchar *key, gint value); void g_key_file_set_double (GKeyFile *key_file, const gchar *group_name, const gchar *key, gdouble value); void g_key_file_set_string_list (GKeyFile *key_file, const gchar *group_name, const gchar *key); void g_key_file_set_locale_string_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *locale); void g_key_file_set_boolean_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gboolean list[], gsize length); void g_key_file_set_integer_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gint list[], gsize length); void g_key_file_set_double_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gdouble list[], gsize length); void g_key_file_set_comment (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *comment, GError **error); void g_key_file_remove_group (GKeyFile *key_file, const gchar *group_name, GError **error); void g_key_file_remove_key (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error); void g_key_file_remove_comment (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
GKeyFile позволяет вам анализировать, редактировать или создавать файлы содержащие группы пар ключ-значение, которые мы называем key files за неимением лучшего названия. Несколько спецификаций freedesktop.org используют ключевые фйлы, например Desktop Entry Specification и Icon Theme Specification.
Синтаксис ключевых файлов детально описан в Desktop Entry Specification, вот короткое описание: Ключевые файлы содержат группы пар ключ-значение, сопровождаемые коментариями.
# это простой пример # здесь мог бы быть комментарий для первой группы [Первая группа] Name=Key File Example\tthis value shows\nescaping # Локализованные строки хранятся в нескольких парах ключ-значение Welcome=Hello Welcome[de]=Hallo Welcome[fr]=Bonjour Welcome[it]=Ciao [Другая группа] Numbers=2;20;-200;0 Booleans=true;false;true;true
Строки начинающиеся со знака '#' и пустые строки рассматриваются как комментарии.
Группы начинаются заглавными строками содержащими имя группы заключённое в '[' и ']', а заканчиваются началом следующей группы или концом файла. Каждая пара ключ-значение должна находится в группе.
Пары ключевых значений в основном имеют форму key=value
,
за исключением локализованных строк, которые имеют форму key[locale]=value
.
Пробелы после или до знака '=' игнорируются. Символ новый строки, табуляции, перевод каретки или обратный слэш
обозначаются как \n, \t, \r, и \\, соответственно. Для сохранения начальных и завершающих пробелов,
их можно обозначить как \s.
Ключи файла могут хранить строки (возможно с локализованными вариантами), целочисленные, логические значения и их списки. Списки разделяются символом разделителя, обычно ';' или ','. Для использования символа разделителя списка в значениях списка, его нужно обозначить предустановленным обратным слэшем.
Этот синтаксис подобен .ini
файлам обычно встречающимся в Windows,
но есть некоторые важные различия:
.ini
файлы используют символ ';' для начала комментариев,
ключевые файлы используют символ '#'.
Ключевые файлы допускают только комментарии перед первой группой.
Ключевые файлы всегда в кодировке UTF-8.
Имена Ключей и Групп чувствительны к регистру, например группа с именем [GROUP]
отличается от группы [group]
.
typedef struct _GKeyFile GKeyFile;
Структура GKeyFile содержит только закрытые поля и не должна использоваться непосредственно.
#define G_KEY_FILE_ERROR g_key_file_error_quark()
Домен ошибки для анализатора ключевых файлов. Ошибки в этом домене из перечисления GKeyFileError. Смотрите GError для информации о доменах ошибки.
typedef enum { G_KEY_FILE_ERROR_UNKNOWN_ENCODING, G_KEY_FILE_ERROR_PARSE, G_KEY_FILE_ERROR_NOT_FOUND, G_KEY_FILE_ERROR_KEY_NOT_FOUND, G_KEY_FILE_ERROR_GROUP_NOT_FOUND, G_KEY_FILE_ERROR_INVALID_VALUE } GKeyFileError;
Коды ошибок возвращаемые анализатором ключевых файлов.
typedef enum { G_KEY_FILE_NONE = 0, G_KEY_FILE_KEEP_COMMENTS = 1 << 0, G_KEY_FILE_KEEP_TRANSLATIONS = 1 << 1 } GKeyFileFlags;
Флаги влияющие на анализ.
GKeyFile* g_key_file_new (void);
Создаёт новый пустой объект GKeyFile.
Используйте g_key_file_load_from_file()
,
g_key_file_load_from_data()
или
g_key_file_load_from_data_dirs()
для чтения существующего ключевого файла.
Возвращает : | пустой GKeyFile. |
Начиная с версии 2.6
void g_key_file_free (GKeyFile *key_file);
Освобождает GKeyFile.
key_file : |
GKeyFile |
Начиная с версии 2.6
void g_key_file_set_list_separator (GKeyFile *key_file, gchar separator);
Устанавливает символ используемый для разделения значений в списках. Обычно ';' или ',' используются в качестве разделителя. По умолчанию разделителем списков является ';'.
key_file : |
GKeyFile |
separator : |
разделитель |
Начиная с версии 2.6
gboolean g_key_file_load_from_file (GKeyFile *key_file, const gchar *file, GKeyFileFlags flags, GError **error);
Загружает ключевой файл в пустую структуру GKeyFile.
Если файл не загружен, то устанавливается error
в
GFileError или
GKeyFileError.
key_file : |
пустая структура GKeyFile |
file : |
путь имени файла для загрузки, в кодировке имён файлов GLib |
flags : |
флаги из GKeyFileFlags |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если ключевой файл был загружен,
FALSE если нет.
|
Начиная с версии 2.6
gboolean g_key_file_load_from_data (GKeyFile *key_file, const gchar *data, gsize length, GKeyFileFlags flags, GError **error);
Загружает ключевой файл из памяти в пустую структуру
GKeyFile.
Если объект не создан, то устанавливается error
в
GKeyFileError.
key_file : |
пустая структура GKeyFile |
data : |
ключевой файл загружаемый из памяти. |
length : |
длина data в байтах
|
flags : |
флаги из GKeyFileFlags |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если ключевой файл был загружен,
FALSE если нет.
|
Начиная с версии 2.6
gboolean g_key_file_load_from_data_dirs (GKeyFile *key_file, const gchar *file, gchar **full_path, GKeyFileFlags flags, GError **error);
Эта функция находит ключевой файл с именем file
в путях возвращаемых из
g_get_user_data_dir()
и
g_get_system_data_dirs()
,
загружает файл в key_file
и возвращает полный путь файла в
full_path
. Если файл не загружен то устанавливается error
в
GFileError или
GKeyFileError.
key_file : |
пустая структура GKeyFile |
file : |
относительный путь к фалу для анализа |
full_path : |
расположение для возвращаемой строки содержащей полный путь файла,
или NULL
|
flags : |
флаги из GKeyFileFlags |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | TRUE если ключевой файл был загружен,
FALSE если нет
|
Начиная с версии 2.6
gchar* g_key_file_to_data (GKeyFile *key_file, gsize *length, GError **error);
Эта функция выводит key_file
как строку.
key_file : |
GKeyFile |
length : |
расположение для длины возвращаемой строки, или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённая строка содержащая контекст GKeyFile |
Начиная с версии 2.6
gchar* g_key_file_get_start_group (GKeyFile *key_file);
Возвращает имя начальной группы файла.
key_file : |
GKeyFile |
Возвращает : | Начальная группа ключевого файла. |
Начиная с версии 2.6
gchar** g_key_file_get_groups (GKeyFile *key_file, gsize *length);
Возвращает все группы ключевого файла загруженного из key_file
.
Массив возвращаемых групп будет NULL
-завершённым,
поэтому length
опционально может быть NULL
.
key_file : |
GKeyFile |
length : |
расположение для количества возвращаемых групп, или NULL
|
Возвращает : | вновь распределённый NULL -завершённый массив строк.
Используйте g_strfreev() для его освобождения.
|
Начиная с версии 2.6
gchar** g_key_file_get_keys (GKeyFile *key_file, const gchar *group_name, gsize *length, GError **error);
Возвращает все ключи для группы с именем group_name
.
Массив возвращаемых ключей будет NULL
-завершённым,
поэтому length
опционально может быть NULL
. Даже если group_name
не найдена, возвращается NULL
и устанавливается error
в G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
key_file : |
GKeyFile |
group_name : |
имя группы |
length : |
расположение для возвращаемого количества возвращённых ключей,
или NULL
|
error : |
расположение для GError,
или NULL
|
Возвращает : | вновь распределённый NULL -завершённый массив
строк. Используйте g_strfreev()
для его освобождения.
|
Начиная с версии 2.6
gboolean g_key_file_has_group (GKeyFile *key_file, const gchar *group_name);
Определяет имеет ли ключевой файл группу group_name
.
key_file : |
GKeyFile |
group_name : |
имя группы |
Возвращает : | TRUE если
group_name часть key_file ,
иначе FALSE .
|
Начиная с версии 2.6
gboolean g_key_file_has_key (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Определяет имеет ли ключевой файл ключ key
в группе group_name
.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
имя ключа |
error : |
расположение для возвращаемой GError |
Возвращает : | TRUE если key
часть group_name ,
иначе FALSE .
|
Начиная с версии 2.6
gchar* g_key_file_get_value (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Возвращает значение связанное с key
в group_name
.
В случае когда ключ не найден, возвращает NULL
и устанавливает
error
в G_KEY_FILE_ERROR_KEY_NOT_FOUND. В случае когда group_name
не найдена, возвращает
NULL
и устанавливает
error
в
G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённая строка, или NULL
если определённый ключ не найден.
|
Начиная с версии 2.6
gchar* g_key_file_get_string (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Возвращает значение связанное с key
в group_name
.
Когда ключ не найден, возвращает NULL
и устанавливает
error
в
G_KEY_FILE_ERROR_KEY_NOT_FOUND.
В случае если group_name
не найдена, возвращает
NULL
и устанавливает
error
в G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
error : |
расположение возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённая строка или NULL
если определённый ключ не найден.
|
Начиная с версии 2.6
gchar* g_key_file_get_locale_string (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *locale, GError **error);
Возвращает значение связанное с key
в group_name
переведённое в полученную locale
если возможно.
Если locale
это NULL
,
то используется текущая локаль.
Если key
не найден, то возвращает NULL
и устанавливает error
в
G_KEY_FILE_ERROR_KEY_NOT_FOUND.
Если значение связанное с key
не может интерпретироваться или не найден подходящий перевод,
то возвращается не переведённое значение.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
locale : |
локаль или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | вновь распределённая строка или NULL
если определённый ключ не найден.
|
Начиная с версии 2.6
gboolean g_key_file_get_boolean (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Возвращает значение связанное с key
в group_name
как логическое.
Если key
не найден то возвращаемое значение не определено и устанавливается
error
в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значение связанное с key
не интерпретируется как логическое, то возвращаемое значение также не определено и устанавливается error
в
G_KEY_FILE_ERROR_INVALID_VALUE.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
error : |
расположение для возвращаемой GError |
Возвращает : | логическое значение связанное с ключом |
Начиная с версии 2.6
gint g_key_file_get_integer (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Возвращает значение связанное с key
в group_name
как целочисленное. Если group_name
это NULL
, то используется начальная группа (start_group).
Если key
не найден, то возвращаемое значение не определено и устанавливается
error
в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значение связанное с key
не интерпретируется как целочисленное, то возвращаемое значение также не определено и устанавливается error
в
G_KEY_FILE_ERROR_INVALID_VALUE.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
error : |
расположение для возвращаемой GError |
Возвращает : | целочисленное значение связанное с ключом. |
Начиная с версии 2.6
gdouble g_key_file_get_double (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Возвращает значение связанное с key
в group_name
как double.
Если group_name
это NULL
, используется начальная группа (start_group).
Если key
не найден, то возвращаемое значение не определено и устанавливается
error
в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значение связанное с key
не интерпретируется как double, то возвращаемое значение также не определено и устанавливается error
в
G_KEY_FILE_ERROR_INVALID_VALUE.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
error : |
расположение для возвращаемой GError |
Возвращает : | double значение связанное с ключом. |
Начиная с версии 2.12
gchar** g_key_file_get_string_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gsize *length, GError **error);
Возвращает значение связанное с key
в group_name
.
В случае когда ключ не найден, возвращает NULL
и устанавливает
error
в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Если group_name
не найдена, возвращает NULL
и устанавливает error
в G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
length : |
расположение для количества возвращаемых строк, или NULL
|
error : |
расположение для возвращаемой GError,
или NULL
|
Возвращает : | NULL -завершённый строковый массив или
NULL если определённый ключ не найден.
Массив должен освобождаться с помощью g_strfreev() .
|
Начиная с версии 2.6
gchar** g_key_file_get_locale_string_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *locale, gsize *length, GError **error);
Возвращает значение связанное с key
в group_name
переводя в полученную locale
если возможно. Если locale
это
NULL
, то используется текущая локаль.
Если key
не найден, то возвращает NULL
и устанавливает error
в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Если значения связанные с key
не могут интерпретироваться или не подлежат переводу, то возвращает не переведённые значения.
Возвращённый массив NULL
-завершённый,
поэтому length
может опционально быть NULL
.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
locale : |
локаль |
length : |
расположение для количества возвращаемых строк или NULL
|
error : |
расположение для возвращаемой GError или NULL
|
Возвращает : | вновь распределённый NULL -завершённый массив строк
или NULL если ключ не найден.
Строковый массив должен освобождаться с помощью g_strfreev() .
|
Начиная с версии 2.6
gboolean* g_key_file_get_boolean_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gsize *length, GError **error);
Возвращает значение связанное с key
в group_name
как список логических. Если group_name
это NULL
, используется начальная группа (start_group).
Если key
не найден, то возвращаемое значение не определено и устанавливается
error
в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значения связанные с key
не интерпретируются как логические, то возвращаемое значение также не определено и устанавливается error
в
G_KEY_FILE_ERROR_INVALID_VALUE.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
length : |
количество возвращаемых логических |
error : |
расположение для возвращаемой GError |
Возвращает : | логические значения связанные с ключом |
Начиная с версии 2.6
gint* g_key_file_get_integer_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gsize *length, GError **error);
Возвращает значения связанные с key
в group_name
как список целочисленных.
Если key
не найден, то возвращаемое значение не определено и устанавливается
error
в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значения связанные с key
не интерпретируются как целочисленные, то возвращаемое значение также не определено и устанавливается error
в
G_KEY_FILE_ERROR_INVALID_VALUE.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
length : |
количество возвращаемых целочисленных |
error : |
расположение для возвращаемой GError |
Возвращает : | целочисленные значения связанные с ключом |
Начиная с версии 2.6
gdouble* g_key_file_get_double_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gsize *length, GError **error);
Возвращает значение связанное с key
в group_name
как
doubles. Если group_name
это NULL
, используется начальная группа.
Если key
не найден, то возвращаемое значение не определено и устанавливается
error
в G_KEY_FILE_ERROR_KEY_NOT_FOUND. Аналогично, если значения связанные с key
не интерпретируются как doubles, то возвращаемое значение также не определено и error
устанавливается в
G_KEY_FILE_ERROR_INVALID_VALUE.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
length : |
количество возвращаемых doubles |
error : |
расположение для возвращаемой GError |
Возвращает : | значения связанные с key как double |
Начиная с версии 2.12
gchar* g_key_file_get_comment (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Находит комментарий выше key
из group_name
.
Если key
это NULL
,
то comment
будет прочитан сверху group_name
.
Если и key
и group_name
являются NULL, то
comment
будет прочитан сверху первой группы в файле.
key_file : |
GKeyFile |
group_name : |
имя группы, или NULL
|
key : |
ключ |
error : |
расположение для возвращаемой GError |
Возвращает : | комментарий который должен быть освобождён с помощью g_free()
|
Начиная с версии 2.6
void g_key_file_set_value (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *value);
Связывает новое значение с key
в group_name
.
Если key
не найден, то он создаётся. Если group_name
не найдена, то она создаётся.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
value : |
строка |
Начиная с версии 2.6
void g_key_file_set_string (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *string);
Связывает новое строковое значение с key
в group_name
.
Если key
не найден, то он создаётся. Если group_name
не найдена, то она создаётся.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
string : |
строка |
Начиная с версии 2.6
void g_key_file_set_locale_string (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *locale, const gchar *string);
Связывает строковое значение с key
и locale
в
group_name
. Если перевод для key
не найден,
то он создаётся.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
locale : |
локаль |
string : |
строка |
Начиная с версии 2.6
void g_key_file_set_boolean (GKeyFile *key_file, const gchar *group_name, const gchar *key, gboolean value);
Связывает новое логическое значение с key
в group_name
.
Если key
не найден, он создаётся.
Начиная с версии 2.6
void g_key_file_set_integer (GKeyFile *key_file, const gchar *group_name, const gchar *key, gint value);
Связывает новое целочисленное значение с key
в group_name
.
Если key
не найден, то он создаётся.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
value : |
целочисленное значение |
Начиная с версии 2.6
void g_key_file_set_double (GKeyFile *key_file, const gchar *group_name, const gchar *key, gdouble value);
Связывает новое значение double с key
в group_name
.
Если key
не найден, он создаётся. Если group_name
это NULL
, используется начальная группа.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
value : |
значение double |
Начиная с версии 2.12
void g_key_file_set_string_list (GKeyFile *key_file, const gchar *group_name, const gchar *key);
Связывает список строковых значений с key
в group_name
.
Если key
не найден, то он создаётся. Если group_name
не найдена, то она создаётся.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
Начиная с версии 2.6
void g_key_file_set_locale_string_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *locale);
Связывает список строковых значений с key
и locale
в
group_name
. Если перевод для key
не найден, то он создаётся.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
locale : |
локаль |
Начиная с версии 2.6
void g_key_file_set_boolean_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gboolean list[], gsize length);
Связывает список логических значений с key
в group_name
.
Если key
не найден, то он создаётся.
Если group_name
это NULL
, то используется начальная группа (start_group).
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
list : |
массив логических значений |
length : |
длина list
|
Начиная с версии 2.6
void g_key_file_set_integer_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gint list[], gsize length);
Связывает список целочисленных значений с key
в group_name
.
Если key
не найден, то он создаётся.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
list : |
массив целочисленных значений |
length : |
количество целочисленных значений в list
|
Начиная с версии 2.6
void g_key_file_set_double_list (GKeyFile *key_file, const gchar *group_name, const gchar *key, gdouble list[], gsize length);
Связывает список значений double с key
в group_name
.
Если key
не найден, то он создаётся.
Если group_name
это NULL
, то используется начальная группа.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
ключ |
list : |
массив double значений |
length : |
количество double значений в list
|
Начиная с версии 2.12
void g_key_file_set_comment (GKeyFile *key_file, const gchar *group_name, const gchar *key, const gchar *comment, GError **error);
Размещает комментарий выше key
из group_name
.
Если key
это NULL
,
то comment
будет записан вверху group_name
.
Если и key
и group_name
являются NULL,
то comment
будет записан сверху первой группы в файле.
key_file : |
GKeyFile |
group_name : |
имя группы, или NULL
|
key : |
ключ |
comment : |
комментарий |
error : |
расположение для возвращаемой GError |
Начиная с версии 2.6
void g_key_file_remove_group (GKeyFile *key_file, const gchar *group_name, GError **error);
Удаляет определённую группу, group_name
, из ключевого файла.
Начиная с версии 2.6
void g_key_file_remove_key (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Удаляет key
в group_name
из ключевого файла.
key_file : |
GKeyFile |
group_name : |
имя группы |
key : |
имя ключа для удаления |
error : |
расположение для возвращаемой GError
или NULL
|
Начиная с версии 2.6
void g_key_file_remove_comment (GKeyFile *key_file, const gchar *group_name, const gchar *key, GError **error);
Удаляет комментарий выше key
из group_name
.
key_file : |
GKeyFile |
group_name : |
имя группы, или NULL
|
key : |
ключ |
error : |
расположение для возвращаемой GError |
Начиная с версии 2.6
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Keyed Data ListsKeyed 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()
.
typedef struct _GData GData;
Структура GData - это непрозрачная структура данных представляющая Keyed Data List. доступ к ней должен осуществляться только с помощью следующих функций.
void g_datalist_init (GData **datalist);
Сбрасывает список данных в NULL
.
Она не освобождает память и не вызывает функции уничтожения.
datalist : |
указатель на указатель в списке данных. |
#define g_datalist_id_set_data(dl, q, d)
Устанавливает данные соответствующие указанному GQuark идентификатору. Любые предыдущие данные с тем же ключом - удаляются, и это вызывает функцию уничтожения.
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 .
|
gpointer g_datalist_id_get_data (GData **datalist, GQuark key_id);
Находит элемент данных соответствующий key_id
.
#define g_datalist_id_remove_data(dl, q)
Удаляет элемент, используя его GQuark идентификатор.
dl : |
список данных. |
q : |
GQuark идентификатор элемента данных. |
gpointer g_datalist_id_remove_no_notify (GData **datalist, GQuark key_id);
Удаляет элемент, без вызова функции уничтожения.
#define g_datalist_set_data(dl, k, d)
Устанавливает элемент данных соответствующий указанному строковому идентификатору.
dl : |
список данных. |
k : |
строка для идентификации элемента данных. |
d : |
элемент данных, или NULL
для удаления любых предыдущих элементов соответствующих k .
|
#define g_datalist_set_data_full(dl, k, d, f)
Устанавливает элемент данных соответствующий указанной строке идентификатору, и функцию вызываемую при удалении элемента данных.
dl : |
список данных. |
k : |
строка для идентификации элемента данных. |
d : |
элемент данных, или NULL
для удаления любых предыдущих элементов соответствующих k .
|
f : |
Функция вызываемая при удалении элемента данных. Эта функция вызывается с элементом данных и может использоваться для освобождения
любой распределённой для него памяти. Если d это
NULL , то
f должен также быть
NULL .
|
#define g_datalist_get_data(dl, k)
Выдаёт элемент данных, используя его строку идентификатор.
Это медленнее чем g_datalist_id_get_data()
потомучто строка сначала конвертируется в GQuark.
dl : |
список данных. |
k : |
строка идентификатор элемента данных. |
Возвращает : | элемент данных, или NULL если он не найден.
|
#define g_datalist_remove_data(dl, k)
Удаляет элемент используя его строковый идентификатор. Элемент данных уничтожается функцией если она была установлена.
dl : |
список данных. |
k : |
строка идентификатор элемента данных. |
#define g_datalist_remove_no_notify(dl, k)
Удаляет элемент, без вызова уничтожающей функции.
dl : |
список данных. |
k : |
строка идентификатор элемента данных. |
void g_datalist_foreach (GData **datalist, GDataForeachFunc func, gpointer user_data);
Вызывает указанную функцию для каждого элемента данных в списке данных.
Функция вызывается на каждым элементом данных с GQuark
идентификатором и данными, вместе с параметром user_data
.
Помните что эта функция потоко-небезопасна. Поэтому если datalist
не может быть
защищён от любых изменений в течении выполнения этой функции, она не должна вызываться.
datalist : |
список данных. |
func : |
функция вызываемая для каждого элемента данных. |
user_data : |
пользовательские данные помещаемые в функцию. |
void g_datalist_clear (GData **datalist);
Освобождает все элементы данных в списке данных. Элементы данных уничтожаются функциями вызываемыми если она была установлена.
datalist : |
список данных. |
void g_datalist_set_flags (GData **datalist, guint flags);
Включает значение флажка для списка данных. Эта функция используется для хранения небольшого числа логических флажков в объекте со списком данных без использования любого дополнительного пространства. Она в основном бесполезна, кроме ситуаций когда пространство сильно уплотнено. (Она в основном типе GObject, например.)
datalist : |
указатель на расположение которое содержит список |
flags : |
флажки для включения. Значения флажков ограничены
G_DATALIST_FLAGS_MASK
(в настоящее время 3; представляя два возможных логических флажка).
Значение для flags которое не соответствует маске - ошибика.
|
Начиная с версии 2.8
void g_datalist_unset_flags (GData **datalist, guint flags);
Выключает значения флажка для списка данных.
Смотрите g_datalist_unset_flags()
datalist : |
указатель на расположение которое содержит список |
flags : |
флажки для выключения. Значения флажков ограничены
G_DATALIST_FLAGS_MASK
(в настоящее время 3: представляя два возможных логических флажка).
Значение для flags которое не соответствует маске - ошибка.
|
Начиная с версии 2.8
guint g_datalist_get_flags (GData **datalist);
Определяет значения флажков упакованных вместе со списком данных.
Смотрите g_datalist_set_flags()
.
datalist : |
указатель на расположение которое содержит список |
Возвращает : | флажки списка данных |
Начиная с версии 2.8
#define G_DATALIST_FLAGS_MASK 0x3
Битовая маска которая ограничивает возможные флажки помещаемые в
g_datalist_set_flags()
.
Помещаемые значения флажков где флажки & ~G_DATALIST_FLAGS_MASK != 0 - это ошибка.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GScanner; GScanner* g_scanner_new (const GScannerConfig *config_templ); GScannerConfig; void g_scanner_input_file (GScanner *scanner, gint input_fd); void g_scanner_sync_file_offset (GScanner *scanner); void g_scanner_input_text (GScanner *scanner, const gchar *text, guint text_len); GTokenType g_scanner_peek_next_token (GScanner *scanner); GTokenType g_scanner_get_next_token (GScanner *scanner); guint g_scanner_cur_line (GScanner *scanner); guint g_scanner_cur_position (GScanner *scanner); GTokenType g_scanner_cur_token (GScanner *scanner); GTokenValue g_scanner_cur_value (GScanner *scanner); gboolean g_scanner_eof (GScanner *scanner); guint g_scanner_set_scope (GScanner *scanner, guint scope_id); void g_scanner_scope_add_symbol (GScanner *scanner, guint scope_id, const gchar *symbol, gpointer value); void g_scanner_scope_foreach_symbol (GScanner *scanner, guint scope_id, GHFunc func, gpointer user_data); gpointer g_scanner_scope_lookup_symbol (GScanner *scanner, guint scope_id, const gchar *symbol); void g_scanner_scope_remove_symbol (GScanner *scanner, guint scope_id, const gchar *symbol); #define g_scanner_freeze_symbol_table (scanner) #define g_scanner_thaw_symbol_table (scanner) gpointer g_scanner_lookup_symbol (GScanner *scanner, const gchar *symbol); void g_scanner_warn (GScanner *scanner, const gchar *format, ...); void g_scanner_error (GScanner *scanner, const gchar *format, ...); void g_scanner_unexp_token (GScanner *scanner, GTokenType expected_token, const gchar *identifier_spec, const gchar *symbol_spec, const gchar *symbol_name, const gchar *message, gint is_error); void (*GScannerMsgFunc) (GScanner *scanner, gchar *message, gboolean error); void g_scanner_destroy (GScanner *scanner); enum GTokenType; union GTokenValue; enum GErrorType; #define G_CSET_a_2_z #define G_CSET_A_2_Z #define G_CSET_DIGITS #define G_CSET_LATINC #define G_CSET_LATINS #define g_scanner_add_symbol ( scanner, symbol, value ) #define g_scanner_remove_symbol ( scanner, symbol ) #define g_scanner_foreach_symbol ( scanner, func, data )
typedef struct { /* неиспользуемые поля */ gpointer user_data; guint max_parse_errors; /* g_scanner_error() инкрементирует это поле */ guint parse_errors; /* имя входного потока, показываемое обработчиком сообщения по умолчанию */ const gchar *input_name; /* quarked data */ GData *qdata; /* ссылка на конфигурацию сканера */ GScannerConfig *config; /* поля заполняемые после g_scanner_get_next_token() */ GTokenType token; GTokenValue value; guint line; guint position; /* поля заполняемые после g_scanner_peek_next_token() */ GTokenType next_token; GTokenValue next_value; guint next_line; guint next_position; /* рассматриваются как закрытые */ GHashTable *symbol_table; gint input_fd; const gchar *text; const gchar *text_end; gchar *buffer; guint scope_id; /* функция обработчик для _warn и _error */ GScannerMsgFunc msg_handler; } GScanner;
Структура данных представляющая лексический сканер.
Вы должны установить input_name
после создания
сканера, та как оно используется обработчиком сообщений по умолчанию когда отображаются предупреждения и ошибки
Если вы сканируете файл, имя файла будет хорошим выбором для этого.
Поля user_data
и
max_parse_errors
неиспользуются.
Если вам нужно связать дополнительные данные со сканером вы можете поместить их сюда.
Если вам нужно использовать собственный обработчик сообщений вы можете установить его в поле
msg_handler
. Тип функции обработки сообщений определяет
GScannerMsgFunc.
GScanner* g_scanner_new (const GScannerConfig *config_templ);
Создаёт новую GScanner.
Структура config_templ
определяет начальные установки сканера,
которые копируются в структуру GScanner поле config
.
Для использования настроек по умолчанию вы можете поместить NULL
.
config_templ : |
начальные настройки сканера. |
Возвращает : | новая GScanner. |
typedef struct { /* Наборы символов */ gchar *cset_skip_characters; /* по умолчанию: " \t\n" */ gchar *cset_identifier_first; gchar *cset_identifier_nth; gchar *cpair_comment_single; /* по умолчанию: "#\n" */ /* Чувствителен ли поиск символа к регистру? */ guint case_sensitive : 1; /* Логическое значение для настройки "на лету" * конфигурации правил сканирования. */ guint skip_comment_multi : 1; /* C подобный комментарий */ guint skip_comment_single : 1; /* единственная строка комментария */ guint scan_comment_multi : 1; /* сканировать множество строк коментария? */ guint scan_identifier : 1; guint scan_identifier_1char : 1; guint scan_identifier_NULL : 1; guint scan_symbols : 1; guint scan_binary : 1; guint scan_octal : 1; guint scan_float : 1; guint scan_hex : 1; /* `0x0ff0' */ guint scan_hex_dollar : 1; /* `$0ff0' */ guint scan_string_sq : 1; /* string: 'anything' */ guint scan_string_dq : 1; /* string: "\\-escapes!\n" */ guint numbers_2_int : 1; /* bin, octal, hex => int */ guint int_2_float : 1; /* int => G_TOKEN_FLOAT? */ guint identifier_2_string : 1; guint char_2_token : 1; /* возвращать G_TOKEN_CHAR? */ guint symbol_2_token : 1; guint scope_0_fallback : 1; /* позволить 0 контекст поиска? */ guint store_int64 : 1; /* использовать значение.v_int64 вместо v_int */ guint padding_dummy; } GScannerConfig;
Определяет настройки GScanner.
cset_skip_characters
определяет символы которые сканер должен пропускать
(по умолчанию символы пробелов:
пробел, табуляцию, перевод каретки и перевод строки).
cset_identifier_first
определяет символы которые могут начинать идентификаторы
(по умолчанию это G_CSET_a_2_z, "_", и
G_CSET_A_2_Z).
cset_identifier_nth
определяет символы которые могут использоваться в идентификаторах
после первого символа (по умолчанию это G_CSET_a_2_z, "_0123456789", G_CSET_A_2_Z, G_CSET_LATINS,
G_CSET_LATINC).
cpair_comment_single
определяет символы начала и конца единственной строки коментария.
По умолчанию это "#\n" который означает что единственная строка комментария начинается с '#' и продолжается до '\n' (конец строки).
case_sensitive
определяет чувствительность символов к регистру
(по умолчанию FALSE
).
skip_comment_multi
определяет пропускать ли многострочные комментарии и не возвращать как лексемы
(по умолчанию TRUE
).
skip_comment_single
определяет пропускать ли однострочные комментарии и не возвращать как лексемы
(по умолчанию TRUE
).
scan_comment_multi
определяет распознавать ли многострочные комментарии
(по умолчанию TRUE
).
scan_identifier
определяет распознавать ли идентификатор
(по умолчанию TRUE
).
scan_identifier_1char
определяет распознавать ли единственный символ идентификатора
(по умолчанию FALSE
).
scan_identifier_NULL
определяет возвращать ли
NULL
как G_TOKEN_IDENTIFIER_NULL.
(по умолчанию FALSE
).
scan_symbols
определяет распознавать ли символы
(по умолчанию TRUE
).
scan_binary
определяет распознавать ли двоичные числа
(по умолчанию FALSE
).
scan_octal
определяет распознавать ли восьмеричные числа
(по умолчанию TRUE
).
scan_float
определяет распознавать ли числа с плавающей точкой
(по умолчанию TRUE
).
scan_hex
определяет распознавать ли шестнадцатеричные числа
(по умолчанию TRUE
).
scan_hex_dollar
определяет распознавать ли '$' как префикс для шестнадцатеричных чисел
(по умолчанию FALSE
).
scan_string_sq
определяет заключена ли строка в одиночные кавычки
(по умолчанию TRUE
).
scan_string_dq
определяет заключена ли строка в двойные кавычки
(по умолчанию TRUE
).
numbers_2_int
определяет должны ли двоичные, восьмеричные и шестнадцатеричные
числа передаваться как G_TOKEN_INT (по умолчанию TRUE
).
int_2_float
определяет передаются ли все числа как
G_TOKEN_FLOAT (по умолчанию FALSE
).
identifier_2_string
определяет передаётся ли идентификатор как строка
(по умолчанию FALSE
).
char_2_token
определяет передаются символы устанавливая token = ch
или как G_TOKEN_CHAR
(по умолчанию TRUE
).
symbol_2_token
определяет передаются ли символы установленными как
token = v_symbol
или как G_TOKEN_SYMBOL (по умолчанию FALSE
).
scope_0_fallback
определяет разыскивается ли символ
для контекста по умолчанию в дополнение к текущему контексту
(по умолчанию FALSE
).
void g_scanner_input_file (GScanner *scanner, gint input_fd);
Подготавливает файл для сканирования.
scanner : |
GScanner. |
input_fd : |
дискриптор файла. |
void g_scanner_sync_file_offset (GScanner *scanner);
Перематывает файловый дескриптор в текущую позицию буфера и позволяет читать файл с начала буфера. Это полезно когда используется третичный сканер файлового дескриптора, который прикрепляется к текущей позиции сканера.
scanner : |
GScanner. |
void g_scanner_input_text (GScanner *scanner, const gchar *text, guint text_len);
Подготавливает для сканирования текстовый буфер.
scanner : |
GScanner. |
text : |
текстовый буфер для сканирования. |
text_len : |
длина текстового буфера. |
GTokenType g_scanner_peek_next_token (GScanner *scanner);
Получает следующую лексему, не удаляя её из потока ввода.
Символьные данные помещаются в
next_token
,
next_value
,
next_line
, и
next_position
поля структуры GScanner.
Помните что пока лексема не удалена из входного потока (то есть
следующий вызов g_scanner_get_next_token()
будет возвращать туже лексему),
она не будет переоценена. Это может привести к удивительным результатам
когда изменяется контекст заглядывания за следующую лексему. Получение
следующей лексемы после переключения контекста вернёт то что рассматривалось ранее,
независимо от любых символов которые могут быть добавлены или удалены в новом контексте.
scanner : |
GScanner. |
Возвращает : | тип лексемы. |
GTokenType g_scanner_get_next_token (GScanner *scanner);
Получает следующую лексему удаляя её из входного потока.
Символьные данные помещаются в
token
,
value
,
line
, и
position
поля структуры GScanner.
scanner : |
GScanner. |
Возвращает : | тип лексемы. |
guint g_scanner_cur_line (GScanner *scanner);
Получает текущую строку во входном потоке (подсчёт начинается с 1).
scanner : |
GScanner. |
Возвращает : | текущая строка. |
guint g_scanner_cur_position (GScanner *scanner);
Получает текущую позицию в текущей строке (подсчёт начинается с 0).
scanner : |
GScanner. |
Возвращает : | текущая позиция в строке. |
GTokenType g_scanner_cur_token (GScanner *scanner);
Получает текущий тип лексемы.
Это просто поле token
в структуре GScanner.
scanner : |
GScanner. |
Возвращает : | текущий тип лексемы. |
GTokenValue g_scanner_cur_value (GScanner *scanner);
Получает текущее значение лексемы.
Это просто поле value
в структуре GScanner.
scanner : |
GScanner. |
Возвращает : | текущее значение лексемы. |
gboolean g_scanner_eof (GScanner *scanner);
Возвращает TRUE
если сканер достиг конца файла или текстового буфера.
guint g_scanner_set_scope (GScanner *scanner, guint scope_id);
Устанавливает текущий контекст.
scanner : |
GScanner. |
scope_id : |
новый id контекста. |
Возвращает : | старый id контекста. |
void g_scanner_scope_add_symbol (GScanner *scanner, guint scope_id, const gchar *symbol, gpointer value);
Добавляет символ в полученный контекст.
scanner : |
GScanner. |
scope_id : |
id контектса. |
symbol : |
добавляемый символ. |
value : |
значение символа. |
void g_scanner_scope_foreach_symbol (GScanner *scanner, guint scope_id, GHFunc func, gpointer user_data);
Вызывает полученную функцию для каждой пары символ/значение в полученном контексте
GScanner.
Функция помещает символ и значение каждой пары и полученный параметр user_data
.
scanner : |
GScanner. |
scope_id : |
id контекста. |
func : |
функция вызываемая для каждой пары символ/значение. |
user_data : |
пользовательские данные помещаемые в функцию. |
gpointer g_scanner_scope_lookup_symbol (GScanner *scanner, guint scope_id, const gchar *symbol);
Находит символ в контексте и возвращает его значение. Если символа нет в контексте, возвращает
NULL
.
void g_scanner_scope_remove_symbol (GScanner *scanner, guint scope_id, const gchar *symbol);
Удаляет символ из контекста.
scanner : |
GScanner. |
scope_id : |
id контекста. |
symbol : |
символ для удаления. |
#define g_scanner_freeze_symbol_table(scanner)
g_scanner_freeze_symbol_table
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Этот макрос ничего не делает.
scanner : |
GScanner. |
#define g_scanner_thaw_symbol_table(scanner)
g_scanner_thaw_symbol_table
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Этот макрос ничего не делает.
scanner : |
GScanner. |
gpointer g_scanner_lookup_symbol (GScanner *scanner, const gchar *symbol);
Находит символ в текущем контексте и возвращает его значение. Если символ не находится в текущем контексте, то возвращает
NULL
.
void g_scanner_warn (GScanner *scanner, const gchar *format, ...);
Выводит предупреждающее сообщение через обработчик сообщений GScanner.
scanner : |
GScanner. |
format : |
формат сообщения. Смотрите документацию для .
|
... : |
параметры вставляемые в строку формата. |
void g_scanner_error (GScanner *scanner, const gchar *format, ...);
Выводит сообщение об ошибке через обработчик сообщений GScanner.
scanner : |
GScanner. |
format : |
формат сообщения. Смотрите документацию для .
|
... : |
параметры вставляемые в строку формата. |
void g_scanner_unexp_token (GScanner *scanner, GTokenType expected_token, const gchar *identifier_spec, const gchar *symbol_spec, const gchar *symbol_name, const gchar *message, gint is_error);
Выводит сообщение через msg_handler сканера, реагируя на неожиданную лексему во входном потоке.
Помните что вы не должны вызывать
g_scanner_peek_next_token()
сопровождаемый g_scanner_unexp_token()
без промежуточного вызова g_scanner_get_next_token()
,
поскольку g_scanner_unexp_token()
оценивает
текущую лексему (не просматриваемую лексему) для создания части сообщения.
scanner : |
GScanner. |
expected_token : |
ожидаемая лексема. |
identifier_spec : |
строка описывающая как пользователю сканера обращаться к идентификаторам
(NULL для идентификатора по умолчанию).
Это используется если expected_token равен G_TOKEN_IDENTIFIER
или G_TOKEN_IDENTIFIER_NULL.
|
symbol_spec : |
строка описывающая как пользователь сканера обращается к символам
(NULL по умолчанию к "symbol").
Это используется если expected_token равен G_TOKEN_SYMBOL
или какому нибудь символьному значению больше чем G_TOKEN_LAST.
|
symbol_name : |
имя символа, если текущая сканируемая лексема является символом. |
message : |
строка сообщения выводимая в конце предупреждения/ошибки, или NULL .
|
is_error : |
если TRUE выводится как ошибка.
Если FALSE выводится как предупреждение.
|
void (*GScannerMsgFunc) (GScanner *scanner, gchar *message, gboolean error);
Определяет тип функции обработчика сообщений.
void g_scanner_destroy (GScanner *scanner);
Освобождает всю память используемую GScanner.
scanner : |
GScanner. |
typedef enum { G_TOKEN_EOF = 0, G_TOKEN_LEFT_PAREN = '(', G_TOKEN_RIGHT_PAREN = ')', G_TOKEN_LEFT_CURLY = '{', G_TOKEN_RIGHT_CURLY = '}', G_TOKEN_LEFT_BRACE = '[', G_TOKEN_RIGHT_BRACE = ']', G_TOKEN_EQUAL_SIGN = '=', G_TOKEN_COMMA = ',', G_TOKEN_NONE = 256, G_TOKEN_ERROR, G_TOKEN_CHAR, G_TOKEN_BINARY, G_TOKEN_OCTAL, G_TOKEN_INT, G_TOKEN_HEX, G_TOKEN_FLOAT, G_TOKEN_STRING, G_TOKEN_SYMBOL, G_TOKEN_IDENTIFIER, G_TOKEN_IDENTIFIER_NULL, G_TOKEN_COMMENT_SINGLE, G_TOKEN_COMMENT_MULTI, G_TOKEN_LAST } GTokenType;
Возможные типы лексем возвращаемые из каждого вызова g_scanner_get_next_token()
.
union GTokenValue { gpointer v_symbol; gchar *v_identifier; gulong v_binary; gulong v_octal; gulong v_int; guint64 v_int64; gdouble v_float; gulong v_hex; gchar *v_string; gchar *v_comment; guchar v_char; guint v_error; };
Объединение содержащее значения лексем.
typedef enum { G_ERR_UNKNOWN, G_ERR_UNEXP_EOF, G_ERR_UNEXP_EOF_IN_STRING, G_ERR_UNEXP_EOF_IN_COMMENT, G_ERR_NON_DIGIT_IN_CONST, G_ERR_DIGIT_RADIX, G_ERR_FLOAT_RADIX, G_ERR_FLOAT_MALFORMED } GErrorType;
Возможные ошибки, используются в поле v_error
GTokenValue, когда лексема равна G_TOKEN_ERROR.
#define G_CSET_a_2_z "abcdefghijklmnopqrstuvwxyz"
Набор алфавитных символов ASCII в нижнем регистре. Используется для определения допустимых идентификаторов символов в GScannerConfig.
#define G_CSET_A_2_Z "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
Набор алфавитных символов ASCII в верхнем регистре. Используется для определения допустимых идентификаторов символов в GScannerConfig.
#define G_CSET_DIGITS "0123456789"
Набор цифр. Используется для определения допустимых идентификаторов символов в GScannerConfig.
#define G_CSET_LATINC
Набор алфавитных символов ISO 8859-1 в верхнем регистре которые не являются символами ASCII. Используется для определения допустимых идентификаторов символов в GScannerConfig.
#define G_CSET_LATINS
Набор алфавитных символов ISO 8859-1 в нижнем регистре которые не являются символами ASCII. Используется для определения допустимых идентификаторов символов в GScannerConfig.
#define g_scanner_add_symbol( scanner, symbol, value )
g_scanner_add_symbol
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте вместо неё g_scanner_scope_add_symbol()
.
Добавляет символ к контексту по умолчанию.
scanner : |
GScanner. |
symbol : |
добавляемый символ. |
value : |
значение символа. |
#define g_scanner_remove_symbol( scanner, symbol )
g_scanner_remove_symbol
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде.
Используйте вместо неё g_scanner_scope_remove_symbol()
.
Удаляет символ из контекста по умолчанию.
scanner : |
GScanner. |
symbol : |
удаляемый символ. |
#define g_scanner_foreach_symbol( scanner, func, data )
g_scanner_foreach_symbol
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде.
Используйте вместо неё g_scanner_scope_foreach_symbol()
.
Вызываемая функция для каждого символа в контексте по умолчанию.
scanner : |
GScanner. |
func : |
функция вызываемая для каждого символа. |
data : |
данные помещаемые в функцию. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Limits of Basic TypesLimits of Basic Types — Переносимый метод определения лимитов стандартных типов. |
#include <glib.h> #define G_MININT #define G_MAXINT #define G_MAXUINT #define G_MINSHORT #define G_MAXSHORT #define G_MAXUSHORT #define G_MINLONG #define G_MAXLONG #define G_MAXULONG #define G_MININT8 #define G_MAXINT8 #define G_MAXUINT8 #define G_MININT16 #define G_MAXINT16 #define G_MAXUINT16 #define G_MININT32 #define G_MAXINT32 #define G_MAXUINT32 #define G_MININT64 #define G_MAXINT64 #define G_MAXUINT64 #define G_MAXSIZE #define G_MINFLOAT #define G_MAXFLOAT #define G_MINDOUBLE #define G_MAXDOUBLE
Эти макросы обеспечивают переносимый метод определения лимитов типов одинаковых стандартных целочисленных и чисел с плавающей точкой.
#define G_MININT8 ((gint8) 0x80)
Минимальное значение которое может содержать gint8.
Начиная с версии 2.4
#define G_MAXINT8 ((gint8) 0x7f)
Максимальное значение которое может содержать gint8.
Начиная с версии 2.4
#define G_MAXUINT8 ((guint8) 0xff)
Максимальное значение которое может содержать guint8.
Начиная с версии 2.4
#define G_MININT16 ((gint16) 0x8000)
Минимальное значение которое может содержать gint16.
Начиная с версии 2.4
#define G_MAXINT16 ((gint16) 0x7fff)
Максимальное значение которое может содержать gint16.
Начиная с версии 2.4
#define G_MAXUINT16 ((guint16) 0xffff)
Максимальное значение которое может содержать guint16.
Начиная с версии 2.4
#define G_MININT32 ((gint32) 0x80000000)
Минимальное значение которое может содержать gint32.
Начиная с версии 2.4
#define G_MAXINT32 ((gint32) 0x7fffffff)
Максимальное значение которое может содержать gint32.
Начиная с версии 2.4
#define G_MAXUINT32 ((guint32) 0xffffffff)
Максимальное значение которое может содержать guint32.
Начиная с версии 2.4
#define G_MININT64 ((gint64) G_GINT64_CONSTANT(0x8000000000000000))
Минимальное значение которое может содержать gint64.
#define G_MAXINT64 G_GINT64_CONSTANT(0x7fffffffffffffff)
Максимальное значение которое может содержать gint64.
#define G_MAXUINT64 G_GINT64_CONSTANT(0xffffffffffffffffU)
Максимальное значение которое может содержать guint64.
#define G_MAXSIZE G_MAXUINT
Максимальное значение которое может содержать gsize.
Начиная с версии 2.4
#define G_MINFLOAT FLT_MIN
Минимальное положительное значение которое может содержать gfloat.
Если вас интересует наименьшее значение которое может содержать gfloat, используйте -G_MAX_FLOAT.
#define G_MINDOUBLE DBL_MIN
Минимальное положительное значение которое может содержать gdouble.
Если вас интересует наименьшее значение которое может содержать gdouble, используйте -G_MAXDOUBLE.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> #define g_new (struct_type, n_structs) #define g_new0 (struct_type, n_structs) #define g_renew (struct_type, mem, n_structs) #define g_try_new (struct_type, n_structs) #define g_try_new0 (struct_type, n_structs) #define g_try_renew (struct_type, mem, n_structs) gpointer g_malloc (gulong n_bytes); gpointer g_malloc0 (gulong n_bytes); gpointer g_realloc (gpointer mem, gulong n_bytes); gpointer g_try_malloc (gulong n_bytes); gpointer g_try_malloc0 (gulong n_bytes); gpointer g_try_realloc (gpointer mem, gulong n_bytes); void g_free (gpointer mem); extern gboolean g_mem_gc_friendly; #define g_alloca (size) #define g_newa (struct_type, n_structs) #define g_memmove (dest,src,len) gpointer g_memdup (gconstpointer mem, guint byte_size); GMemVTable; void g_mem_set_vtable (GMemVTable *vtable); gboolean g_mem_is_system_malloc (void); extern GMemVTable *glib_mem_profiler_table; void g_mem_profile (void);
Эти функции обеспечивают поддержку распределения и освобождения памяти.
Если любой вызов распределения памяти завершается неудачно, приложение закрывается. Это означает что нет необходимости проверять успешность выполнения вызова.
#define g_new(struct_type, n_structs)
Распределяет n_structs
элементов типа struct_type
.
Возвращаемый указатель приводится к указателю для данного типа.
Если n_structs
равен 0, то возвращается NULL
.
Так как возвращаемый указатель уже приведён к правильному типу, обычно не требуется явное приведение, это может скрыть ошибки распределения памяти.
struct_type : |
тип элементов для распределения. |
n_structs : |
количество элементов для распределения. |
Возвращает : | указатель для распределенной памяти, приведённый к указателю типа struct_type .
|
#define g_new0(struct_type, n_structs)
Распределяет n_structs
элементов типа struct_type
, инициализирует в 0's.
Возвращаемый указатель приведён к указателю полученного типа.
Если n_structs
равен 0 возвращается NULL
.
Так как возвращаемый указатель уже приведён к правильному типу, обычно не требуется явное приведение, это может скрыть ошибки распределения памяти.
struct_type : |
тип элементов для распределения. |
n_structs : |
количество элементов для распределения. |
Возвращает : | указатель для распределённой памяти, приведённый к указателю типа struct_type .
|
#define g_renew(struct_type, mem, n_structs)
Перераспределяет память указанную параметром mem
,
так чтобы она имела свободное пространство для n_structs
элементов типа struct_type
. Возвращает новый адрес памяти,
которая возможно была перемещена.
struct_type : |
тип элементов для распределения. |
mem : |
текущая распределённая память. |
n_structs : |
количество элементов для распределения. |
Возвращает : | указатель на вновь распределенную память, приведен к указателю типа struct_type .
|
#define g_try_new(struct_type, n_structs)
Пытается распределить n_structs
элементов типа struct_type
и возвращает
NULL
если неудаётся.
В отличие от g_new()
, которая закрывает программу при неудаче.
Возвращаемый указатель приведён к указателю полученного типа.
Если n_structs
равен 0 возвращается NULL
.
struct_type : |
тип элементов для распределения. |
n_structs : |
количество элементов для рапределения. |
Возвращает : | указатель на распределенную память, приведённый к указателю типа struct_type .
|
Начиная с версии 2.8
#define g_try_new0(struct_type, n_structs)
Пытается распределить n_structs
элементов типа struct_type
, инициализируя 0
и возвращает NULL
при неудаче. В отличие от g_new0()
, которая закрывает программу при неудаче.
Возвращаемый указатель приводится к указателю полученного типа.
Если n_counts
равен 0, то возвращается NULL
.
struct_type : |
тип элементов для распределения. |
n_structs : |
количество элементов для рапределения. |
Возвращает : | указатель на распределенную память, приведённый к указателю типа struct_type .
|
Начиная с версии 2.8
#define g_try_renew(struct_type, mem, n_structs)
Пытается перераспределить память указанную параметром mem
,
так чтобы появилось пространство для n_structs
элементов типа struct_type
и возвращает NULL
при неудаче.
В отличие от g_renew()
, которая закрывает программу при неудаче.
Возвращает новый адрес памяти, которая могла быть перемещена.
struct_type : |
тип элементов для распределения. |
mem : |
текущее распределение памяти. |
n_structs : |
количество элементов для рапределения. |
Возвращает : | указатель на вновь распределённую память, приведённый к указателю типа struct_type .
|
Начиная с версии 2.8
gpointer g_malloc (gulong n_bytes);
Распределяет n_bytes
байт памяти.
Если n_bytes
равен 0, возвращает NULL
.
n_bytes : |
количество байт для распределения. |
Возвращает : | указатель на распределённую память. |
gpointer g_malloc0 (gulong n_bytes);
Распределяет n_bytes
байт памяти, инициализируя 0's.
Если n_bytes
равен 0, возвращает NULL
.
n_bytes : |
количество байт для распределения. |
Возвращает : | указатель на распределённую память. |
gpointer g_realloc (gpointer mem, gulong n_bytes);
Перераспределяет память указанную параметром mem
,
так чтобы было свободное пространство для
n_bytes
байт памяти.
Возвращает новый адрес памяти, которая могла быть перемещена.
mem
может быть NULL
, в этом случае предполагается нулевая длина.
n_bytes
может быть 0, в этом случае возвращается NULL
.
mem : |
память для перераспределения. |
n_bytes : |
новый размер памяти в байтах. |
Возвращает : | новый адрес распределённой памяти. |
gpointer g_try_malloc (gulong n_bytes);
Пытается распределить n_bytes
, и возвращает NULL
при неудаче.
В отличие от g_malloc()
, которая закрывает программу при неудаче.
n_bytes : |
количество байт для распределения. |
Возвращает : | распределённую память или NULL .
|
gpointer g_try_malloc0 (gulong n_bytes);
Пытается распределить n_bytes
, инициализируя 0's, и возвращает NULL
при неудаче.
В отличие от g_malloc0()
, которая закрывает программу при неудаче.
n_bytes : |
количество байт для распределения. |
Возвращает : | распределённую память или NULL .
|
Начиная с версии 2.8
gpointer g_try_realloc (gpointer mem, gulong n_bytes);
Пытается перераспределить mem
в новый размер
n_bytes
, и возвращает NULL
при неудаче.
В отличие от g_realloc()
, которая закрывает программу при неудаче.
Если mem
равен NULL
, работает также как g_try_malloc()
.
void g_free (gpointer mem);
Освобождает память указанную параметром mem
.
Если mem
равен NULL
, то функция ничего не делает.
mem : |
память для освобождения. |
extern gboolean g_mem_gc_friendly;
Эта переменная равна TRUE
если переменная окружения G_DEBUG
включает ключ gc-friendly.
#define g_alloca(size)
Распределяет size
байт в стек; эти байты освобождаются когда
текущий кадр стека очищается. Этот макрос по существу просто оболочка функции
предоставляемой в большинстве
вариантов UNIX.
Поэтому он обеспечивает те же самые преимущества и ловушки как alloca()
:
alloca()
+ |
|
+ она не вызывает фрагментации памяти, в пределах её области, разделяемые |
|
- распределяемый размер должен вписываться в текущий кадр стека. Например в потоковом окружении
Linux, размер стека посредством потока ограничен 2 мегабайтами,
поэтому разряжен при использовании |
|
- неудачное распределение из-за недостатка пространства в стеке не указывается возвращением
|
|
- особое внимание должно быть уделено при смешивании
|
size : |
количество байт для распределения. |
Возвращает : | пространство для size байт, распределяемое в стеке
|
#define g_newa(struct_type, n_structs)
Оболочка g_alloca()
в более типо-безопасной манере.
struct_type : |
тип участка памяти для распределения |
n_structs : |
Количество участков для распределения |
Возвращает : | указатель на пространство стека для n_structs участков типа struct_type
|
#define g_memmove(dest,src,len)
Копирует блок памяти длиной len
байт, из src
в dest
.
Источник и адресат могут перекрываться.
Для использования этой функции вы должны самостоятельно включить
string.h
, потому что этот макрос обычно простое решение для
memmove()
и GLib не будет включать
string.h
за вас.
dest : |
адресат для копируемых байт. |
src : |
источник копируемых байт. |
len : |
количество копируемых байт. |
gpointer g_memdup (gconstpointer mem, guint byte_size);
Распределяет byte_size
байт памяти и копирует byte_size
байт из mem
. Если mem
равен NULL
возвращается NULL
.
typedef struct { gpointer (*malloc) (gsize n_bytes); gpointer (*realloc) (gpointer mem, gsize n_bytes); void (*free) (gpointer mem); /* опционально; устанавливается в NULL если не используется! */ gpointer (*calloc) (gsize n_blocks, gsize n_block_bytes); gpointer (*try_malloc) (gsize n_bytes); gpointer (*try_realloc) (gpointer mem, gsize n_bytes); } GMemVTable;
Устанавливает функцию используемую для распределения памяти. Также GMemVTable может использоваться
для всех распределений в той же самой программе; вызов g_mem_set_vtable()
,
если он существует, должен быть приоритетным для любого использования GLib.
malloc () |
функция используемая для распределения памяти. |
realloc () |
функция используемая для перераспределения памяти. |
free () |
функция используемая для освобождения памяти. |
calloc () |
функция используемая для распределения памяти заполняемой нулями (allocating zero-filled memory). |
try_malloc () |
функция используемая для распределения памяти без обработки ошибок по умолчанию. |
try_realloc () |
функция используемая для перераспределения памяти без обработки ошибок по умолчанию. |
void g_mem_set_vtable (GMemVTable *vtable);
Заставляет GMemVTable использовать для распределения памяти. Вы можете это использовать для обеспечения выбора функций
распределения памяти. Эти функции должны вызываться перед использованием любых других функций GLib. Параметр vtable
нужен только для обеспечения
, malloc()
, и realloc()
функций; GLib может по умолчанию обеспечить реализацию других.
Реализации free()
и malloc()
должны возвращать
realloc()
NULL
при неудаче,
GLib обрабатывает контроль ошибок за вас. vtable
копируется,
поэтому не сохраняется после вызова этой функции.
vtable : |
таблица функций распределения памяти. |
gboolean g_mem_is_system_malloc (void);
Проверяет использует ли программа распределения памяти g_malloc()
системную реализацию malloc. Если возвращает TRUE
память распределяемая с помощью malloc()
взаимозаменяема памятью распределяемой с использованием g_malloc()
.
Эта функция полезна для избежания дополнительных копий распределения памяти возвращаемой с помощью
не-GLib-based API.
Разные функции распределения могут быть установлены с помощью g_mem_set_vtable()
.
Возвращает : | если TRUE , malloc() и g_malloc() могут использоваться совместно.
|
extern GMemVTable *glib_mem_profiler_table;
GMemVTable содержит
профилированные варианты функций распределения памяти.
Используйте их вместе с g_mem_profile()
для получения информации об образце распределения памяти вашей программой.
void g_mem_profile (void);
Определяет суммарное использование памяти.
Она выдаёт частоту распределений различных размеров, общее количество распределённых байт, общее количество освобождённых байт и разницу между двумя предыдущими значениями, то есть количество всё ещё используемых байт.
Помните что эта функция не определит ничего пока вы предварительно не установите
glib_mem_profiler_table с помощью g_mem_set_vtable()
.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Memory AllocatorsMemory Allocators — deprecated way to allocate chunks of memory for GList, GSList and GNode. |
#include <glib.h> GAllocator; GAllocator* g_allocator_new (const gchar *name, guint n_preallocs); void g_allocator_free (GAllocator *allocator);
Prior to 2.10, GAllocator was used as an efficient way to allocate small pieces of memory for use with the GList, GSList and GNode data structures. Начиная с версии 2.10, it has been completely replaced by the slice allocator and deprecated.
typedef struct _GAllocator GAllocator;
GAllocator
устарела и не должна использоваться во вновь создаваемом коде.
The GAllocator struct contains private data. and should only be accessed using the following functions.
GAllocator* g_allocator_new (const gchar *name, guint n_preallocs);
g_allocator_new
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator
instead
Creates a new GAllocator.
name : |
the name of the GAllocator. This name is used to set the name of the GMemChunk used by the GAllocator, and is only used for debugging. |
n_preallocs : |
the number of elements in each block of memory allocated.
Larger blocks mean less calls to g_malloc() , but some memory may be wasted.
(GLib uses 128 elements per block by default.) The value must be between 1
and 65535.
|
Возвращает : | a new GAllocator. |
void g_allocator_free (GAllocator *allocator);
g_allocator_free
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator
instead
Frees all of the memory allocated by the GAllocator.
allocator : |
GAllocator. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GMemChunk; #define G_ALLOC_AND_FREE #define G_ALLOC_ONLY GMemChunk* g_mem_chunk_new (const gchar *name, gint atom_size, gulong area_size, gint type); gpointer g_mem_chunk_alloc (GMemChunk *mem_chunk); gpointer g_mem_chunk_alloc0 (GMemChunk *mem_chunk); void g_mem_chunk_free (GMemChunk *mem_chunk, gpointer mem); void g_mem_chunk_destroy (GMemChunk *mem_chunk); #define g_mem_chunk_create (type, pre_alloc, alloc_type) #define g_chunk_new (type, chunk) #define g_chunk_new0 (type, chunk) #define g_chunk_free (mem, mem_chunk) void g_mem_chunk_reset (GMemChunk *mem_chunk); void g_mem_chunk_clean (GMemChunk *mem_chunk); void g_blow_chunks (void); void g_mem_chunk_info (void); void g_mem_chunk_print (GMemChunk *mem_chunk);
Memory chunks provide an space-efficient way to allocate equal-sized
pieces of memory, called atoms. However, due to the administrative
overhead (in particular for G_ALLOC_AND_FREE, and when used from multiple
threads), they are in practise often slower than direct use of g_malloc()
.
Therefore, memory chunks have been deprecated in favor of the
slice allocator,
which has been added in 2.10. All internal uses of memory chunks in
GLib have been converted to the g_slice
API.
There are two types of memory chunks, G_ALLOC_ONLY, and G_ALLOC_AND_FREE.
G_ALLOC_ONLY chunks only allow allocation of atoms. The atoms can never be freed individually. The memory chunk can only be free in its entirety.
G_ALLOC_AND_FREE chunks do allow atoms to be freed individually. The disadvantage of this is that the memory chunk has to keep track of which atoms have been freed. This results in more memory being used and a slight degradation in performance.
To create a memory chunk use g_mem_chunk_new()
or the convenience macro
g_mem_chunk_create()
.
To allocate a new atom use g_mem_chunk_alloc()
, g_mem_chunk_alloc0()
,
or the convenience macros g_chunk_new()
or g_chunk_new0()
.
To free an atom use g_mem_chunk_free()
, or the convenience macro
g_chunk_free()
. (Atoms can only be freed if the memory chunk is created
with the type set to G_ALLOC_AND_FREE.)
To free any blocks of memory which are no longer being used, use
g_mem_chunk_clean()
. To clean all memory chunks, use g_blow_chunks()
.
To reset the memory chunk, freeing all of the atoms, use g_mem_chunk_reset()
.
To destroy a memory chunk, use g_mem_chunk_destroy()
.
To help debug memory chunks, use g_mem_chunk_info()
and g_mem_chunk_print()
.
Пример 3. Using a GMemChunk
GMemChunk *mem_chunk; gchar *mem[10000]; gint i; /* Create a GMemChunk with atoms 50 bytes long, and memory blocks holding 100 bytes. Note that this means that only 2 atoms fit into each memory block and so isn't very efficient. */ mem_chunk = g_mem_chunk_new ("test mem chunk", 50, 100, G_ALLOC_AND_FREE); /* Now allocate 10000 atoms. */ for (i = 0; i < 10000; i++) { mem[i] = g_chunk_new (gchar, mem_chunk); /* Fill in the atom memory with some junk. */ for (j = 0; j < 50; j++) mem[i][j] = i * j; } /* Now free all of the atoms. Note that since we are going to destroy the GMemChunk, this wouldn't normally be used. */ for (i = 0; i < 10000; i++) { g_mem_chunk_free (mem_chunk, mem[i]); } /* We are finished with the GMemChunk, so we destroy it. */ g_mem_chunk_destroy (mem_chunk);
Пример 4. Using a GMemChunk with data structures
GMemChunk *array_mem_chunk; GRealArray *array; /* Create a GMemChunk to hold GRealArray structures, using the g_mem_chunk_create() convenience macro. We want 1024 atoms in each memory block, and we want to be able to free individual atoms. */ array_mem_chunk = g_mem_chunk_create (GRealArray, 1024, G_ALLOC_AND_FREE); /* Allocate one atom, using the g_chunk_new() convenience macro. */ array = g_chunk_new (GRealArray, array_mem_chunk); /* We can now use array just like a normal pointer to a structure. */ array->data = NULL; array->len = 0; array->alloc = 0; array->zero_terminated = (zero_terminated ? 1 : 0); array->clear = (clear ? 1 : 0); array->elt_size = elt_size; /* We can free the element, so it can be reused. */ g_chunk_free (array, array_mem_chunk); /* We destroy the GMemChunk when we are finished with it. */ g_mem_chunk_destroy (array_mem_chunk);
typedef struct _GMemChunk GMemChunk;
GMemChunk
устарела и не должна использоваться во вновь создаваемом коде.
The GMemChunk struct is an opaque data structure representing a memory chunk. It should be accessed only through the use of the following functions.
#define G_ALLOC_AND_FREE 2
G_ALLOC_AND_FREE
устарела и не должна использоваться во вновь создаваемом коде.
Specifies the type of a GMemChunk.
Used in g_mem_chunk_new()
and g_mem_chunk_create()
to specify that atoms
will be freed individually.
#define G_ALLOC_ONLY 1
G_ALLOC_ONLY
устарела и не должна использоваться во вновь создаваемом коде.
Specifies the type of a GMemChunk.
Used in g_mem_chunk_new()
and g_mem_chunk_create()
to specify that atoms
will never be freed individually.
GMemChunk* g_mem_chunk_new (const gchar *name, gint atom_size, gulong area_size, gint type);
g_mem_chunk_new
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice allocator
instead
Creates a new GMemChunk.
name : |
строка to identify the GMemChunk. It is not copied so it
should be valid for the lifetime of the GMemChunk. It is only used in
g_mem_chunk_print() , which is used for debugging.
|
atom_size : |
the size, in bytes, of each element in the GMemChunk. |
area_size : |
the size, in bytes, of each block of memory allocated to contain the atoms. |
type : |
the type of the GMemChunk. G_ALLOC_AND_FREE is used if the atoms will be freed individually. G_ALLOC_ONLY should be used if atoms will never be freed individually. G_ALLOC_ONLY is quicker, since it does not need to track free atoms, but it obviously wastes memory if you no longer need many of the atoms. |
Возвращает : | the new GMemChunk. |
gpointer g_mem_chunk_alloc (GMemChunk *mem_chunk);
g_mem_chunk_alloc
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_alloc()
instead
Allocates an atom of memory from a GMemChunk.
mem_chunk : |
GMemChunk. |
Возвращает : | a pointer to the allocated atom. |
gpointer g_mem_chunk_alloc0 (GMemChunk *mem_chunk);
g_mem_chunk_alloc0
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_alloc0()
instead
Allocates an atom of memory from a GMemChunk, setting the memory to 0.
mem_chunk : |
GMemChunk. |
Возвращает : | a pointer to the allocated atom. |
void g_mem_chunk_free (GMemChunk *mem_chunk, gpointer mem);
g_mem_chunk_free
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_free1()
instead
Frees an atom in a GMemChunk. This should only be called if the GMemChunk was created with G_ALLOC_AND_FREE. Otherwise it will simply return.
mem_chunk : |
GMemChunk. |
mem : |
a pointer to the atom to free. |
void g_mem_chunk_destroy (GMemChunk *mem_chunk);
g_mem_chunk_destroy
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Frees all of the memory allocated for a GMemChunk.
mem_chunk : |
GMemChunk. |
#define g_mem_chunk_create(type, pre_alloc, alloc_type)
g_mem_chunk_create
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
A convenience macro for creating a new GMemChunk.
It calls g_mem_chunk_new()
, using the given type to create the GMemChunk
name. The atom size is determined using
, and the
area size is calculated by multiplying the sizeof()
pre_alloc
parameter with
the atom size.
type : |
the type of the atoms, typically a structure name. |
pre_alloc : |
the number of atoms to store in each block of memory. |
alloc_type : |
the type of the GMemChunk. G_ALLOC_AND_FREE is used if the atoms will be freed individually. G_ALLOC_ONLY should be used if atoms will never be freed individually. G_ALLOC_ONLY is quicker, since it does not need to track free atoms, but it obviously wastes memory if you no longer need many of the atoms. |
Возвращает : | the new GMemChunk. |
#define g_chunk_new(type, chunk)
g_chunk_new
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_new()
instead
A convenience macro to allocate an atom of memory from a GMemChunk.
It calls g_mem_chunk_alloc()
and casts the returned atom to a pointer to
the given type, avoiding a type cast in the source code.
#define g_chunk_new0(type, chunk)
g_chunk_new0
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_new0()
instead
A convenience macro to allocate an atom of memory from a GMemChunk.
It calls g_mem_chunk_alloc0()
and casts the returned atom to a pointer to
the given type, avoiding a type cast in the source code.
#define g_chunk_free(mem, mem_chunk)
g_chunk_free
has been deprecated since version 2.10 and should not be used in newly-written code. Use g_slice_free()
instead
A convenience macro to free an atom of memory from a GMemChunk.
It simply switches the arguments and calls g_mem_chunk_free()
It is included simply to complement the other convenience macros, g_chunk_new()
and g_chunk_new0()
.
mem : |
a pointer to the atom to be freed. |
mem_chunk : |
GMemChunk. |
void g_mem_chunk_reset (GMemChunk *mem_chunk);
g_mem_chunk_reset
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Resets a GMemChunk to its initial state. It frees all of the currently allocated blocks of memory.
mem_chunk : |
GMemChunk. |
void g_mem_chunk_clean (GMemChunk *mem_chunk);
g_mem_chunk_clean
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Frees any blocks in a GMemChunk which are no longer being used.
mem_chunk : |
GMemChunk. |
void g_blow_chunks (void);
g_blow_chunks
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Calls g_mem_chunk_clean()
on all GMemChunk objects.
void g_mem_chunk_info (void);
g_mem_chunk_info
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Outputs debugging information for all GMemChunk objects currently in use.
It outputs the number of GMemChunk objects currently allocated,
and calls g_mem_chunk_print()
to output information on each one.
void g_mem_chunk_print (GMemChunk *mem_chunk);
g_mem_chunk_print
has been deprecated since version 2.10 and should not be used in newly-written code. Use the slice
allocator instead
Outputs debugging information for a GMemChunk.
It outputs the name of the GMemChunk (set with g_mem_chunk_new()
),
the number of bytes used, and the number of blocks of memory allocated.
mem_chunk : |
GMemChunk. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Memory SlicesMemory Slices — Эффективный способ распределения групп эквивалентных по размеру участков памяти. |
#include <glib.h> gpointer g_slice_alloc (gsize block_size); gpointer g_slice_alloc0 (gsize block_size); void g_slice_free1 (gsize block_size, gpointer mem_block); void g_slice_free_chain_with_offset (gsize block_size, gpointer mem_chain, gsize next_offset); #define g_slice_new (type) #define g_slice_new0 (type) #define g_slice_free (type, mem) #define g_slice_free_chain (type, mem_chain, next)
Слайсы памяти обеспечивают пространственно-эффективный и многопроцессорно-масштабируемый путь для распределения равных по размеру частей памяти, так же как оригинальный GMemChunks (from GLib <= 2.8), избегая чрезмерной траты памяти, потери масштабируемости и проблем выполнения.
Для достижения этих целей, распределитель слайсов использует сложный,
многоуровневый дизайн который был создан благодаря распределителю слайсов Bonwick's
[5].
Он использует posix_memalign()
для оптимизированного
распределения множества участков одинакового размера и имеет посредством потока
свободные списки (так называемый уровень журналирования)
для быстрого удовлетворения запросов распределения уже известных размеров структур.
Это сопровождается дополнительным логическим кэшированием, чтобы иметь свободную память
в течении некоторого времени перед возвращением в систему. Память которая не используется
из-за ограничений выравнивания, используется для колоризации кэша
(произвольное распределение адресов участка) для улучшенного использования кэша CPU.
Кэширующий уровень распределителя слайсов самостоятельно адаптируется к высокой конкуренции
блокирования для улучшения масштабируемости.
Распределитель слайсов может распределять небольшие блоки в два указателя, и в отличие от
malloc()
, он не резервирует дополнительное пространство в блоке.
Для блоков большого размера, g_slice_new()
и g_slice_alloc()
автоматически делегируют
к системной реализации malloc()
. Для вновь создаваемого кода рекомендуется использовать новый
g_slice
API вместо g_malloc()
и подобных, пока объекты не изменяют размер в течении их жизненного цикла и размер объекта используемый во время распределения
остаётся доступным когда освобождается.
Пример 1. Использование распределителя слайсов
gchar *mem[10000]; gint i; /* Распределяем 10000 блоков. */ for (i = 0; i < 10000; i++) { mem[i] = g_slice_alloc (50); /* Fill in the memory with some junk. */ for (j = 0; j < 50; j++) mem[i][j] = i * j; } /* Освобождаем все блоки. */ for (i = 0; i < 10000; i++) { g_slice_free1 (50, mem[i]); }
Пример 2. Использование распределителя слайсов со структурами данных
GRealArray *array; /* Распределяем один блок, используя макрос g_slice_new(). */ array = g_slice_new (GRealArray); /* Теперь мы можем использовать массив как обычный указатель на структуру. */ array->data = NULL; array->len = 0; array->alloc = 0; array->zero_terminated = (zero_terminated ? 1 : 0); array->clear = (clear ? 1 : 0); array->elt_size = elt_size; /* Мы можем освобождать блок, поэтому он может использоваться многократно. */ g_slice_free (GRealArray, array);
gpointer g_slice_alloc (gsize block_size);
Распределяет блок памяти из распределителя слайсов. Адрес полученного блока, как гарантируется, будет выравнен по крайней мере 2 * sizeof (void*). Помните что основной механизм распределения слайсов может быть изменён с помощью переменной окружения G_SLICE=always-malloc.
block_size : |
количество байт для распределения |
Возвращает : | указатель на распределённую память block |
Начиная с версии 2.10
gpointer g_slice_alloc0 (gsize block_size);
Распределяет блок памяти через g_slice_alloc()
и инициализирует возвращаемую память 0.
Помните что основной механизм распределения слайсов может быть изменён с помощью переменной окружения
G_SLICE=always-malloc.
block_size : |
количество байт для распределения |
Возвращает : | указатель на распределённый блок |
Начиная с версии 2.10
void g_slice_free1 (gsize block_size, gpointer mem_block);
Освобождает блок памяти. Память должна быть распределена через
g_slice_alloc()
или g_slice_alloc0()
,
а block_size
должен соответствовать размеру определённому при распределении.
Помните что существующее поведение может быть изменено с помощью переменной окружения
G_DEBUG=gc-friendly.
block_size : |
размер блока |
mem_block : |
указатель на блок для освобождения |
Начиная с версии 2.10
void g_slice_free_chain_with_offset (gsize block_size, gpointer mem_chain, gsize next_offset);
Освобождает связанный список блоков памяти структуры имеющей тип type
.
Блоки памяти должны быть одинакового размера, распределённые через
g_slice_alloc()
или
g_slice_alloc0()
и связаны вместе указателем next
(также как в GSList).
Смещение поля next
передаётся в каждый блок как третий аргумент.
Помните что существующее поведение может быть изменено с помощью переменной окружения
G_DEBUG=gc-friendly.
block_size : |
размер блоков |
mem_chain : |
указатель на первый блок в цепочке |
next_offset : |
поле смещения next в блоках
|
Начиная с версии 2.10
#define g_slice_new(type)
Удобный макрос для распределения блоков памяти из распределителя слайсов.
Он вызывает g_slice_alloc()
с
sizeof (type
) и приводит возвращаемый указатель к указателю данного типа,
избегая приведения типа в исходном коде.
Помните что основной механизм распределения слайсов может быть изменён с помощью переменной окружения
G_SLICE=always-malloc.
type : |
тип для распределения, обычно имя структуры |
Возвращает : | указатель на распределённый блок, приведённый к указателю type .
|
Начиная с версии 2.10
#define g_slice_new0(type)
Удобный макрос для распределения блока памяти из распределителя слайсов и установки памяти в 0.
Он вызывает g_slice_alloc0()
с sizeof (type
) и приводит возвращаемый указатель к указателю полученного типа,
избегая приведения указателя в исходном коде.
Помните что основной механизм распределения слайсов может быть изменён с помощью переменной окружения
G_SLICE=always-malloc.
type : |
тип для распределения, обычно имя структуры |
Возвращает : | указатель на распределённый блок, приведённый к указателю type .
|
Начиная с версии 2.10
#define g_slice_free(type, mem)
Удобный макрос для освобождения блока памяти который был распределён из распределителя слайсов.
Он вызывает g_slice_free1()
используя sizeof (type)
как размер блока.
Помните что существующее поведение может быть изменено с помощью переменной окружения
G_DEBUG=gc-friendly.
type : |
тип блока для освобождения, обычно имя структуры |
mem : |
указатель на блок для освобождения |
Начиная с версии 2.10
#define g_slice_free_chain(type, mem_chain, next)
Освобождает связанный список блоков памяти структуры имеющей тип type
.
Блоки памяти должны быть одинакового размера, распределены через
g_slice_alloc()
или
g_slice_alloc0()
и связаны вместе указателем
next
(так же как в GSList).
Имя поля next
в type
помещают как третий аргумент.
Помните что существующее поведение может быть изменено с помощью переменной окружения
G_DEBUG=gc-friendly.
type : |
тип mem_chain блоков
|
mem_chain : |
указатель на первый блок цепочки |
next : |
имя поля следующего указателя в type
|
Начиная с версии 2.10
[5] [Bonwick94] Jeff Bonwick, The slab allocator: Кэширующий объекты распределитель памяти ядра. USENIX 1994, и [Bonwick01] Bonwick and Jonathan Adams, Magazines and vmem: Расширенное распределение слайсов для множества процессоров и произвольных ресурсов. USENIX 2001
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Регистрация сообщенийMessage Logging — Универсальная поддержка для регистрации сообщений с разным уровнем важности. |
#include <glib.h> #define G_LOG_DOMAIN #define G_LOG_FATAL_MASK #define G_LOG_LEVEL_USER_SHIFT void (*GLogFunc) (const gchar *log_domain, GLogLevelFlags log_level, const gchar *message, gpointer user_data); enum GLogLevelFlags; void g_log (const gchar *log_domain, GLogLevelFlags log_level, const gchar *format, ...); void g_logv (const gchar *log_domain, GLogLevelFlags log_level, const gchar *format, va_list args); #define g_message (...) #define g_warning (...) #define g_critical (...) #define g_error (...) #define g_debug (...) guint g_log_set_handler (const gchar *log_domain, GLogLevelFlags log_levels, GLogFunc log_func, gpointer user_data); void g_log_remove_handler (const gchar *log_domain, guint handler_id); GLogLevelFlags g_log_set_always_fatal (GLogLevelFlags fatal_mask); GLogLevelFlags g_log_set_fatal_mask (const gchar *log_domain, GLogLevelFlags fatal_mask); void g_log_default_handler (const gchar *log_domain, GLogLevelFlags log_level, const gchar *message, gpointer unused_data); GLogFunc g_log_set_default_handler (GLogFunc log_func, gpointer user_data);
Эти функции обеспечивают поддержку для регистрации сообщений об ошибках или отладочных сообщений.
Есть несколько встроенных уровней сообщений определённых в GLogLevelFlags. Они могут быть дополнены определёнными пользователем уровнями.
#define G_LOG_DOMAIN ((gchar*) 0)
Определяет область регистрации.
Для приложений обычно используется по умолчанию NULL
(или "") область.
Библиотеки должны определять это так, чтобы любые сообщения которые они регистрируют
можно было отличить от сообщений из других библиотек или кода приложений.
Но избегайте определения их в общих заголовочных файлах.
Например, GTK+ использует это в своём Makefile.am:
INCLUDES = -DG_LOG_DOMAIN=\"Gtk\"
#define G_LOG_FATAL_MASK (G_LOG_FLAG_RECURSION | G_LOG_LEVEL_ERROR)
Регистрационные уровни GLib которые рассматриваются фатальными по умолчанию.
#define G_LOG_LEVEL_USER_SHIFT (8)
Смещение регистрационного уровня для определения пользователем уровней регистрации (0-7 использует GLib).
void (*GLogFunc) (const gchar *log_domain, GLogLevelFlags log_level, const gchar *message, gpointer user_data);
Определяет прототип функции обработчика журнала регистрации.
log_domain : |
область регистрации сообщения. |
log_level : |
регистрационный уровень сообщения (включая фатальный и рекурсивный флаги). |
message : |
сообщение для обработки. |
user_data : |
пользовательские данные, устанавливаемые в g_log_set_handler() .
|
typedef enum { /* регистрационные флаги */ G_LOG_FLAG_RECURSION = 1 << 0, G_LOG_FLAG_FATAL = 1 << 1, /* уровни регистрации GLib */ G_LOG_LEVEL_ERROR = 1 << 2, /* всегда фатально */ G_LOG_LEVEL_CRITICAL = 1 << 3, G_LOG_LEVEL_WARNING = 1 << 4, G_LOG_LEVEL_MESSAGE = 1 << 5, G_LOG_LEVEL_INFO = 1 << 6, G_LOG_LEVEL_DEBUG = 1 << 7, G_LOG_LEVEL_MASK = ~(G_LOG_FLAG_RECURSION | G_LOG_FLAG_FATAL) } GLogLevelFlags;
Флаги определяющие уровень регистрации сообщений.
void g_log (const gchar *log_domain, GLogLevelFlags log_level, const gchar *format, ...);
Регистрирует ошибку или отладочное сообщение.
Если уровень регистрации фатальный, вызывается функция abort()
для завершения программы.
log_domain : |
область регистрации, обычно G_LOG_DOMAIN. |
log_level : |
уровень регистрации, или из GLogLevelFlags или уровень определённый пользователем. |
format : |
форматированное сообщение. Смотрите документацию printf() .
|
... : |
параметры вставляемые в форматированную строку. |
void g_logv (const gchar *log_domain, GLogLevelFlags log_level, const gchar *format, va_list args);
Регистрирует ошибку или отладочное сообщение.
Если уровень регистрации установлен фатальный, вызывается функция abort()
для завершения программы.
log_domain : |
область регистрации. |
log_level : |
уровень регистрации. |
format : |
форматированная строка. Смотрите документацию printf() .
|
args : |
параметры вставляемые в форматированную строку. |
#define g_message(...)
Удобная функция/макрокоманда для регистрации обычных сообщений.
... : |
форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf() )
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
#define g_warning(...)
Удобная функция/макрокоманда для регистрации предупреждающих сообщений.
Вы можете создать фатальное предупреждение во время выполнения установив переменную окружения G_DEBUG
(смотрите Running GLib Applications).
... : |
форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf() )
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
#define g_critical(...)
Регистрирует критическое предупреждение "critical warning" (G_LOG_LEVEL_CRITICAL). Определяется приложением чем отличается критическое от обычного предупреждения.
Вы можете вызвать g_log_set_always_fatal()
чтобы выйти из программы при критическом предупреждении,
затем использовать g_critical()
для фатальных ошибок, например.
Вы также можете сделать критическое предупреждение фатальным установив во время выполнения переменную окружения G_DEBUG
(смотрите
Running GLib Applications).
... : |
форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf() )
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
#define g_error(...)
Удобная функция/макрокоманда для регистрации сообщения об ошибке.
Сообщение об ошибке всегда фатально, приводит к вызову функции
abort()
для завершения приложения.
Эта функция приводит к дампу ядра (core dump); не используйте её для
ошибок о которых вы знаете. Использование этой функции указывает ошибку
в вашей программе, то есть на ошибочное условие выполнения.
... : |
форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf() )
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
#define g_debug(...)
Удобная функция/макрокоманда для регистрации отладочных сообщений.
... : |
форматированная строка, сопровождаемая параметрами вставляемыми в форматированную строку (как в printf() )
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
|
... : |
Начиная с версии 2.6
guint g_log_set_handler (const gchar *log_domain, GLogLevelFlags log_levels, GLogFunc log_func, gpointer user_data);
Устанавливает обработчик журналов регистрации для области установленного уровня регистрации.
Для обработки фатальных и рекурсивных сообщений параметр log_levels
должен комбинироваться с битовыми флагами G_LOG_FLAG_FATAL и G_LOG_FLAG_RECURSION.
Помните, что, так как уровень регистрации G_LOG_LEVEL_ERROR всегда фатальный, чтобы установить обработчик для этого уровня регистрации вы должны скомбинировать его с G_LOG_FLAG_FATAL.
Пример 13. Добавление обработчика журнала регистрации для всех предупреждающих сообщений в области (приложении) по умолчанию
g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
Пример 14. Добавление обработчика журнала регистрации для всех критических сообщений из GTK+
g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
Пример 15. Добавление обработчика журнала регистраций для всех сообщений из GLib
g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
log_domain : |
область регистрации, или NULL для области приложения по умолчанию "".
|
log_levels : |
уровень регистрации для применения обработчика. Для обработки фатальных и рекурсивных сообщений скомбинируйте регистрационные уровни с битовыми флагами G_LOG_FLAG_FATAL и G_LOG_FLAG_RECURSION. |
log_func : |
функция обработки регистрации. |
user_data : |
данные помещаемые в обработчик регистрации. |
Возвращает : | id нового обработчика. |
void g_log_remove_handler (const gchar *log_domain, guint handler_id);
Удаляет обработчик регистрации.
log_domain : |
область регистрации. |
handler_id : |
id обработчика, который возвращает g_log_set_handler() .
|
GLogLevelFlags g_log_set_always_fatal (GLogLevelFlags fatal_mask);
Устанавливает сообщение уровень которого всегда является фатальным, в любой области регистрации.
Когда сообщение с этим уровнем зарегистрировано приложение закрывается.
Вы можете только установить фатальные уровни определенные в GLib.
G_LOG_LEVEL_ERROR
всегда фатально.
Вы можете также сделать некоторое сообщение фатальным установив во время выполнения переменную окружения G_DEBUG
(смотрите
Running GLib Applications).
fatal_mask : |
маска содержащая биты установленные для каждого уровня ошибки которая будет фатальной. |
Возвращает : | старая фатальная маска. |
GLogLevelFlags g_log_set_fatal_mask (const gchar *log_domain, GLogLevelFlags fatal_mask);
Устанавливает регистрационный уровень который является фатальным в полученной области.
G_LOG_LEVEL_ERROR
всегда фатально.
log_domain : |
регистрационная область. |
fatal_mask : |
новая фатальная маска. |
Возвращает : | старая фатальная маска для области регистрации. |
void g_log_default_handler (const gchar *log_domain, GLogLevelFlags log_level, const gchar *message, gpointer unused_data);
Обработчик регистрации по умолчанию устанавливается GLib; g_log_set_default_handler()
позволяет установить альтернативу обработчика регистрации по умолчанию.
Эта функция используется если нет обработчика регистраций установленного для специальной области
и комбинации регистрационного уровня. Она выводит сообщения в stderr или stdout
и если регистрационный уровень фатальный она вызывает abort()
.
stderr используется для уровней G_LOG_LEVEL_ERROR
, G_LOG_LEVEL_CRITICAL
,
G_LOG_LEVEL_WARNING
и G_LOG_LEVEL_MESSAGE
. stdout используется для остальных.
log_domain : |
регистрационная область сообщения. |
log_level : |
уровень сообщения. |
message : |
сообщение. |
unused_data : |
данные помещённые из g_log() которые не использованы.
|
GLogFunc g_log_set_default_handler (GLogFunc log_func, gpointer user_data);
Устанавливает обработчик журнала регистраций по умолчанию если нет обработчика установленного для специальной области регистрации и комбинации уровня регистрации. По умолчанию, GLib использует
g_log_default_handler()
как обработчик журнала регистрации.
log_func : |
функция обработчика регистрации. |
user_data : |
данные помещаемые в обработчик регистрации. |
Возвращает : | предыдущий обработчик регистрации по умолчанию |
Начиная с версии 2.6
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
|
#include <glib.h> #define G_INLINE_FUNC #define G_STMT_START #define G_STMT_END #define G_BEGIN_DECLS #define G_END_DECLS #define G_N_ELEMENTS (arr) #define G_VA_COPY (ap1,ap2) #define G_STRINGIFY (macro_or_string) #define G_GNUC_EXTENSION #define G_GNUC_CONST #define G_GNUC_PURE #define G_GNUC_MALLOC #define G_GNUC_DEPRECATED #define G_GNUC_NORETURN #define G_GNUC_UNUSED #define G_GNUC_PRINTF ( format_idx, arg_idx ) #define G_GNUC_SCANF ( format_idx, arg_idx ) #define G_GNUC_FORMAT ( arg_idx ) #define G_GNUC_NULL_TERMINATED #define G_GNUC_WARN_UNUSED_RESULT #define G_GNUC_FUNCTION #define G_GNUC_PRETTY_FUNCTION #define G_GNUC_NO_INSTRUMENT #define G_HAVE_GNUC_VISIBILITY #define G_GNUC_INTERNAL #define G_LIKELY (expr) #define G_UNLIKELY (expr) #define G_STRLOC #define G_STRFUNC #define G_GINT16_MODIFIER #define G_GINT16_FORMAT #define G_GUINT16_FORMAT #define G_GINT32_MODIFIER #define G_GINT32_FORMAT #define G_GUINT32_FORMAT #define G_GINT64_MODIFIER #define G_GINT64_FORMAT #define G_GUINT64_FORMAT #define G_GSIZE_MODIFIER #define G_GSIZE_FORMAT #define G_GSSIZE_FORMAT
Эти макросы обеспечивают много специфичных улучшений которые не часто нужны разработчикам программ.
#define G_INLINE_FUNC
Этот макрос используется для экспорта прототипов функций, таким образом они могут быть связаны
с внешними версиями когда включение в заголовок (inlining) не выполнено. Файл который реализует
функции должен определить G_IMPLEMENTS_INLINES
перед включением заголовков которые содержат G_INLINE_FUNC
деклорации.
Так как inlining очень зависит от компилятора, правильно использовать этот макрос очень сложно.
Этот макрос часто принимается для замены ключевого слова; ключевое слово уже объявлено переносимым способом в glib заголовках и может использоваться обычно.
#define G_STMT_START
Используется внутри многооператорного макроса так чтобы он мог быть использован в местах, где компилятором ожидается только один оператор.
#define G_STMT_END
Используется внутри многооператорного макроса так чтобы он мог быть использован в местах, где компилятором ожидается только один оператор.
#define G_BEGIN_DECLS
Используется (наряду с G_END_DECLS) для ограничения (bracket) заголовочных файлов. Если используемый компилятор
это C++ компилятор, добавляется extern "C"
рядом с заголовком.
#define G_END_DECLS
Используется (наряду с G_BEGIN_DECLS) для ограничения заголовочных файлов. Если используемый компилятор
это C++ компилятор, добавляется extern "C"
рядом с заголовком.
#define G_N_ELEMENTS(arr) (sizeof (arr) / sizeof ((arr)[0]))
Определяет количество элементов в массиве. Массив должен быть объявлен чтобы компилятор знал его размер во время компиляции; этот макрос не будет работать на массиве распределённом в динамической памяти, только статические массивы или массивы в стеке.
arr : |
массив |
#define G_VA_COPY(ap1,ap2)
Переносимый способ копирования va_list переменных.
Чтобы использовать эту функцию, вы должны включить string.h
самостоятельно, потому что эта команда может использовать
, а GLib не включит memmove()
string.h
за вас.
ap1 : |
переменная va_list помещаемая в виде копии ap2 .
|
ap2 : |
va_list. |
#define G_STRINGIFY(macro_or_string) G_STRINGIFY_ARG (macro_or_string)
Принимает макрос или строку и преобразует в строку.
macro_or_string : |
макрос или строка. |
#define G_GNUC_EXTENSION
Расширение для __extension__
когда в качестве компилятора используется
gcc.
Это просто сообщает gcc не предупреждать о следующем
не стандартном коде когда выполняется компиляция с опцией -pedantic
.
#define G_GNUC_CONST
Расширение для GNU C const
параметра функции если компилятор
gcc. Объявляет функцию как константу включающую
лучшую оптимизацию вызываемой функции. Константная функция не проверяет никаких значений
кроме параметров, и влияет только на возвращаемое значение. Детали смотрите в документации GNU C.
Функция которая имеет указанные аргументы и проверяет указанные данные не должна объявляться константой. Аналогично, функция которая вызвана не константной функцией обычно не должна быть константной. Это не имеет смысла для функций констант возвращающих (void) пустое значение.
#define G_GNUC_PURE
Расширение для GNU C pure
параметра функции если компилятор
gcc.
Объявление функции как полное включение (pure enables) улучшает оптимизацию вызова функции.
Полные (pure) функции имеют влияние только на возвращаемое значение а возвращаемое значение
зависит только от параметров и/или глобальных переменных.
Детали смотрите в документации GNU C.
#define G_GNUC_MALLOC
Расширение для GNU C malloc
параметра функции если компилятор
gcc. Объявление функции с включением malloc улучшает
оптимизацию функции. Функция может иметь параметр malloc, если возвращаемый указатель гарантировано
не связан с любым другим указателем когда возвращается функцией
(на практике, это означает вновь распределяемую память).
Подробности смотрите в документации GNU C.
Начиная с версии 2.6
#define G_GNUC_DEPRECATED
Расширение для GNU C deprecated
параметра для компилятора
gcc.
Он может использоваться для маркировки определения типа (typedefs),
переменных и функций как устаревших.
Когда вызывается с опцией -Wdeprecated
, компилятор будет предупреждать
когда используется устаревший интерфейс.
Подробности смотрите в документации GNU C.
Начиная с версии 2.2
#define G_GNUC_NORETURN
Расширение для GNU C noreturn
параметра функции, если компилятор
gcc. Он используется для объявления функции
когда нет возвращаемого значения.
Включает оптимизацию функции и предотвращает возможные предупреждения компилятора.
Детали смотрите в документации GNU C.
#define G_GNUC_UNUSED
Расширение GNU C unused
параметра функции, если компилятор
gcc.
Используется для объявления функций которые никогда не используются.
Предотвращает возможные предупреждения компилятора. Подробности смотрите в документации GNU C.
#define G_GNUC_PRINTF( format_idx, arg_idx )
Расширение для GNU C format
параметра функции, если компилятор
gcc. Используется для объявления функций которые
принимают разное количество аргументов с таким же синтаксисом как у
.
Позволяет компилятору контролировать типы помещаемых аргументов в функцию.
Подробности смотрите в GNU C.
printf()
gint g_snprintf (gchar *string, gulong n, gchar const *format, ...) G_GNUC_PRINTF (3, 4);
format_idx : |
перечень аргументов соответствующий форматируемой строке. (Нумерация аргументов начинается с 1). |
arg_idx : |
первый из форматируемых параметров. |
#define G_GNUC_SCANF( format_idx, arg_idx )
Расширение GNU C format
параметра функции, если компилятор gcc.
Используется для объявления функций которые принимают переменное количество аргументов,
с таким же синтаксисом как у
.
Позволяет компилятору проверять тип помещаемых в функцию аргументов.
Подробности смотрите в документации GNU C.
scanf()
format_idx : |
перечень аргументов соответствующий форматируемой строке. (Нумерация аргументов начинается с 1). |
arg_idx : |
первый из форматируемых параметров. |
#define G_GNUC_FORMAT( arg_idx )
Расширение GNU C format_arg
параметра функции, если компилятор
gcc.
Этот атрибут функции определяет что функция принимает форматированную строку в стиле функций
, printf()
,
scanf()
или strftime()
и модифицирует так, чтобы результат можно было
поместить в strfmon()
,
printf()
,
scanf()
или strftime()
функцию
(с оставшимися параметрами в формате функции так же,
как если они были бы не модифицированной строкой).
Подробности смотрите в документации GNU C.
strfmon()
gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
arg_idx : |
порядковый номер аргумента. |
#define G_GNUC_NULL_TERMINATED
Расширение GNU C sentinel
параметра функции, если компилятор
gcc, или "" если нет. Этот параметр функции применяется только к variadic функциям и инструктирует компилятор проверить что список аргументов завершается явным NULL
.
Подробности смотрите в документации GNU C.
Начиная с версии 2.8
#define G_GNUC_WARN_UNUSED_RESULT
Расширение GNU C warn_unused_ersult
параметра функции, если компилятор
gcc, или "" если нет. Этот параметр функции заставляет
компилятор сообщать предупреждение, если результат вызова функции игнорируется.
Подробности смотрите в документации GNU C.
Начиная с версии 2.10
#define G_GNUC_FUNCTION
Расширение GNU C __FUNCTION__
переменной, если компилятор
gcc, или "" если нет.
GNU C __FUNCTION__
переменная содержит имя текущей функции.
Подробности смотрите в документации GNU C.
#define G_GNUC_PRETTY_FUNCTION
Расширение для GNU C __PRETTY_FUNCTION__
переменной, если компилятор
gcc, или "" если нет.
GNU C __PRETTY_FUNCTION__
переменная содержит имя текущей функции.
Для C программ это тоже самое как переменная __FUNCTION__
,
но для C++ включается дополнительная информация, такая как прототип и класс функции.
Подробности смотрите в документации GNU C.
#define G_GNUC_NO_INSTRUMENT
Расширение GNU C no_instrument_function
параметра функции, если
компилятор gcc. Функция с этим параметром
не будет инструментом для профилирования, когда компилятор вызывается с опцией
-finstrument-functions
.
Подробности смотрите в документации GNU C.
#define G_HAVE_GNUC_VISIBILITY 1
Этот макрос определяется как 1, если компилятор поддерживает ELF видимость атрибутов (на данный момент только gcc).
Начиная с версии 2.6
#define G_GNUC_INTERNAL __attribute__((visibility("hidden")))
Расширение GNU C visibility(hidden)
параметра, если компилятор
поддерживает это (в настоящее время только gcc).
Этот параметр может использоваться для маркировки библиотечных функций как используемые только
внутри библиотеки, чтобы не создавать не эффективный ввод PLT.
Помните что статичные функции не нуждаются в подобной маркировки.
Подробности смотрите в документации GNU C.
Начиная с версии 2.6
#define G_LIKELY(expr)
Подсказывает компилятору что логическое выражение вероятно эквивалентно значению true. Компилятор может использовать эту информацию для оптимизации.
if (G_LIKELY (random()
!= 1))
g_print ("not one");
expr : |
логическое выражение |
Начиная с версии 2.2
#define G_UNLIKELY(expr)
Подсказывает компилятору что логическое выражение вероятно не равно значению true. Компилятор может использовать эту информацию для оптимизации.
if (G_UNLIKELY (random()
== 1))
g_print ("a random one");
expr : |
логическое выражение |
Начиная с версии 2.2
#define G_STRFUNC
Дополняется до строки идентифицирующей текущую функцию.
Начиная с версии 2.4
#define G_GINT16_MODIFIER "h"
Платформо-зависимая длина модификатора для создания преобразуемых модификаторов
printf()
для значений типов
gint16 или
guint16. Это строковые литералы,
но не включающие знак процента, так что вы можете добавить точность и длину модификатора
между знаком процента и преобразующим спецификатором и прибавить с переди преобразованный спецификатор.
Следующий пример печатает "0x7b";
gint16 value = 123; g_print ("%#" G_GINT16_MODIFIER "x", value);
Начиная с версии 2.4
#define G_GINT16_FORMAT "hi"
Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gint16. Это строковый литерал, но не включает знак процента, таким образом вы можете добавлять точность и длину модификатора между знаком процента и спецификатором преобразования.
gint16 in; gint32 out; sscanf ("42", "%" G_GINT16_FORMAT, &in) out = in * 1000; g_print ("%" G_GINT32_FORMAT, out);
#define G_GUINT16_FORMAT "hu"
Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа guint16. Смотрите также G_GINT16_FORMAT.
#define G_GINT32_MODIFIER ""
Платформо-зависимая длина модификатора для создания преобразуемых спецификаторов
printf()
для значений типов gint32 или guint32.
Смотрите также G_GINT16_MODIFIER.
Начиная с версии 2.4
#define G_GINT32_FORMAT "i"
Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gint32. Смотрите также G_GINT16_FORMAT.
#define G_GUINT32_FORMAT "u"
Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа guint32. Смотрите также G_GINT16_FORMAT.
#define G_GINT64_MODIFIER "ll"
Зависящая от платформы длина модификатора для создания спецификаторов преобразования
printf()
для значений типов
gint64 или
guint64.
Смотрите также G_GINT16_MODIFIER.
Некоторые платформы не поддерживают печать 64 битных целочисленных, даже если поддерживают типы. На таких платформах G_GINT64_MODIFIER не определяется.
Начиная с версии 2.4
#define G_GINT64_FORMAT "lli"
Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gint64. Смотрите также G_GINT16_FORMAT.
Некоторые платформы не поддерживают сканирование и печать 64 битных целочисленных,
даже если поддерживают типы. На таких платформах
G_GINT64_FORMAT не определяется.
Помните что scanf()
может не поддерживать 64 битные целочисленные,
даже если
G_GINT64_FORMAT определён. Из-за плохой обработки ошибок,
scanf()
не рекомендуется для использования в анализе так или иначе;
вместо неё возможно использование g_strtoull()
.
#define G_GUINT64_FORMAT "llu"
Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа guint64. Смотрите также G_GINT16_FORMAT.
Некоторые платформы не поддерживают сканирование и печать 64 битных целочисленных,
даже если поддерживают типы. На таких платформах
G_GUINT64_FORMAT не определяется.
Помните что scanf()
может не поддерживать 64 битные целочисленные,
даже если
G_GUINT64_FORMAT определён. Из-за плохой обработки ошибок,
scanf()
не рекомендуется для использования в анализе так или иначе;
вместо неё возможно использование g_strtoull()
.
#define G_GSIZE_MODIFIER ""
Платформо-зависимая длина модификатора для создания спецификаторов
printf()
для значений типов
gsize или
gssize.
Смотрите также G_GINT16_MODIFIER.
Начиная с версии 2.6
#define G_GSIZE_FORMAT "u"
Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gsize. Смотрите также G_GINT16_FORMAT.
Начиная с версии 2.6
#define G_GSSIZE_FORMAT "i"
Это платформо-зависимый спецификатор преобразования для сканирования и печати значений типа gssize. Смотрите также G_GINT16_FORMAT.
Начиная с версии 2.6
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Miscellaneous Utility FunctionsMiscellaneous Utility Functions — Набор портируемых сервисных функций. |
#include <glib.h> const gchar* g_get_application_name (void); void g_set_application_name (const gchar *application_name); gchar* g_get_prgname (void); void g_set_prgname (const gchar *prgname); const gchar* g_getenv (const gchar *variable); gboolean g_setenv (const gchar *variable, const gchar *value, gboolean overwrite); void g_unsetenv (const gchar *variable); gchar** g_listenv (void); const gchar* g_get_user_name (void); const gchar* g_get_real_name (void); const gchar* g_get_user_cache_dir (void); const gchar* g_get_user_data_dir (void); const gchar* g_get_user_config_dir (void); const gchar* const * g_get_system_data_dirs (void); const gchar* const * g_get_system_config_dirs (void); const gchar* g_get_host_name (void); const gchar* g_get_home_dir (void); const gchar* g_get_tmp_dir (void); gchar* g_get_current_dir (void); const gchar* g_basename (const gchar *file_name); #define g_dirname gboolean g_path_is_absolute (const gchar *file_name); const gchar* g_path_skip_root (const gchar *file_name); gchar* g_path_get_basename (const gchar *file_name); gchar* g_path_get_dirname (const gchar *file_name); gchar* g_build_filename (const gchar *first_element, ...); gchar* g_build_filenamev (gchar **args); gchar* g_build_path (const gchar *separator, const gchar *first_element, ...); gchar* g_build_pathv (const gchar *separator, gchar **args); gchar* g_find_program_in_path (const gchar *program); gint g_bit_nth_lsf (gulong mask, gint nth_bit); gint g_bit_nth_msf (gulong mask, gint nth_bit); guint g_bit_storage (gulong number); guint g_spaced_primes_closest (guint num); void g_atexit (GVoidFunc func); guint g_parse_debug_string (const gchar *string, const GDebugKey *keys, guint nkeys); GDebugKey; void (*GVoidFunc) (void); void (*GFreeFunc) (gpointer data); void g_qsort_with_data (gconstpointer pbase, gint total_elems, gsize size, GCompareDataFunc compare_func, gpointer user_data); void g_nullify_pointer (gpointer *nullify_location);
const gchar* g_get_application_name (void);
Получает удобочитаемое имя приложения, установленное с помощью
g_set_application_name()
.
Это имя должно быть локализовано если возможно и передано для отображения пользователю. В отличие от
g_get_prgname()
,
которая получает не локализованное имя. Если
g_set_application_name()
не была вызвана, возвращается результат из
g_get_prgname()
(который может быть NULL
если g_set_prgname()
также не была вызвана).
Возвращает : | удобочитаемое имя программы. Может вернутся NULL
|
Начиная с версии 2.2
void g_set_application_name (const gchar *application_name);
Устанавливает удобочитаемое имя для приложения. Это имя должно быть локализовано если возможно и предоставлено для отображения пользователю.
В отличие от g_set_prgname()
,
которая устанавливает не локализованное имя.
g_set_prgname()
будет вызвана автоматически функцией gtk_init()
,
но g_set_application_name()
не будет.
Помните что из соображений потокобезопасности, эти функции должны вызываться только один раз.
Имя приложения используется в таком контексте как сообщения об ошибках (error messages), или при отображении имени приложения в списке задач.
application_name : |
локализованное имя приложения |
gchar* g_get_prgname (void);
Получает имя программы. Это имя должно быть не локализовано, в отличие от
g_get_application_name()
.
(Если вы используете GDK или GTK+ имя программы устанавливает gdk_init()
,
которую вызывает gtk_init()
. Имя программы находится в последнем компоненте argv[0]
.)
Возвращает : | имя программы. Возвращаемая строка принадлежит GLib и не должна освобождаться или модифицироваться. |
void g_set_prgname (const gchar *prgname);
Устанавливает имя программы. Это имя не должно быть локализовано, в отличие от
g_set_application_name()
.
Помните что из соображений потокобезопасности эта функция должна вызываться один раз.
prgname : |
имя программы. |
const gchar* g_getenv (const gchar *variable);
Возвращает значение переменной окружения. Имя и значение находятся в кодировке имён файлов GLib. В UNIX, это фактически означает байты которые могут или не могут быть в некотором последовательном наборе символов или кодировке. В Windows, это UTF-8. В Windows, в случае когда переменная окружения содержит ссылку на другие переменные окружения, они рассширяются.
variable : |
переменная окружения для получения значения, в кодировке имён файлов GLib. |
Возвращает : | значение переменной окружения, или NULL если
переменная окружения не найдена. Возвращаемая строка может быть переписана следующим вызовом
g_getenv() ,
g_setenv() или
g_unsetenv() .
|
gboolean g_setenv (const gchar *variable, const gchar *value, gboolean overwrite);
Устанавливает переменную окружения. И значение переменной и её имя должны быть в кодировке имён файлов GLib. В UNIX, это означает что они могут быть в любой последовательности байт. В Windows, они должны быть в UTF-8.
Помните что в некоторых системах, когда переменные перезаписаны, память используется для предыдущих переменных и их значения не изменяется.
variable : |
переменная окружения для установки, не должна содержать '='. |
value : |
значение для устанавливаемой переменной. |
overwrite : |
изменять ли переменную если она уже существует. |
Возвращает : | FALSE
если переменная окружения не может быть установлена.
|
Начиная с версии 2.4
void g_unsetenv (const gchar *variable);
Удаляет переменную окружения.
Помните что в некоторых системах, когда перезаписывается переменная, память используемая для предыдущих переменных и их значения не изменяется. Кроме того, эта функция не гарантирует потокобезопасную работу.
variable : |
переменная окружения для удаления, не должна содержать '='. |
Начиная с версии 2.4
gchar** g_listenv (void);
Получает имена всех установленных переменных окружения.
Возвращает : | NULL -завершённый список строк который должен освобождаться
с помощью g_strfreev() .
Программы которые должны быть портированы в Windows обычно должны использовать эту функцию и
g_getenv()
вместо использования массива переменных окружения непосредственно из библиотеки C. В Windows, строки в массиве переменных окружения
находятся в системной кодировке, тогда как в большинстве обычных случаев для переменных окружения в программах GLib вам понадобится
использовать кодировку UTF-8 которую обеспечивает эта функция и g_getenv() .
|
Начиная с версии 2.8
const gchar* g_get_user_name (void);
Получает текущее имя пользователя. Кодировка возвращаемой строки определяется системой. В UNIX, это может быть предпочтительно кодировка имён файлов, или что-то ещё, и нет никакой гарантии что это даже не противоречит машине. В Windows, это всегда UTF-8.
Возвращает : | текущее имя пользователя. |
const gchar* g_get_real_name (void);
Получает реальное имя пользователя. Оно обычно берётся из пользовательского ввода в файле passwd
.
Кодировка возвращаемой строки определяется системой. (В Windows, это всегда UTF-8.)
Если реальное имя пользователя не определено, то возвращается строка "Unknown".
Возвращает : | реальное имя пользователя. |
const gchar* g_get_user_cache_dir (void);
Возвращает основной каталог в котором хранятся несущественные, кэшируемые, специфические данные для определённого пользователя.
На UNIX платформах это определяется используя механизм описанный в XDG Base Directory Specification
Возвращает : | строка которой владеет GLib и которую не нужно освобождать или модифицировать. |
Начиная с версии 2.6
const gchar* g_get_user_data_dir (void);
Возвращает основной каталог для доступа приложений к данным на подобие значков которые настроены для определённого пользователя.
На UNIX платформах это определяется с использованием механизма описанного в XDG Base Directory Specification
Возвращает : | строка которой владеет GLib и которую не нужно освобождать или модифицировать. |
Начиная с версии 2.6
const gchar* g_get_user_config_dir (void);
Возвращает основной каталог в котором хранится конфигурационная информация приложений для определённого пользователя, такая как свойства (preferences) и настройки (settings).
На UNIX платформах это определяется с использованием механизма описанного в XDG Base Directory Specification
Возвращает : | строка которой владеет GLib и которую не нужно освобождать или изменять. |
Начиная с версии 2.6
const gchar* const * g_get_system_data_dirs (void);
Возвращает упорядоченный список основных каталогов для доступа приложений к общесистемным данным.
На UNIX платформах это определяется с помощью механизма описанного в XDG Base Directory Specification
В Windows первыми элементами списка являются Application Data (Данные приложения) и Documents folders (Каталог документов) для All Users (Всех пользователей). (Это определено только в Windows 2000 или более поздних версиях и не представлено в списках других версий Windows.) Смотрите документацию для CSIDL_COMMON_APPDATA и CSIDL_COMMON_DOCUMENTS.
Затем следует "общий" подкаталог в инсталяционном каталоге для пакета содержащего DLL который вызывает эта функция, если он может быть определён.
В конце список содержит "общий" подкаталог в инсталяционном каталоге для GLib, и в инсталяционном каталоге пакет приложений файлов .exe.
Инсталяционные каталоги выше определяются поиском каталога где расположены модули (DLL или EXE). Если имя каталога "bin", используется его родитель, иначе непосредственно сам каталог.
Помните что возвращаемый Windows список может зависеть от того где вызвать эту функцию.
Возвращает : | NULL -завершённый массив строк которым владеет GLib
и который не нужно освобождать или изменять.
|
Начиная с версии 2.6
const gchar* const * g_get_system_config_dirs (void);
Возвращает упорядоченный список общих каталогов в которых доступна общесистемная, конфигурационная, информация.
На UNIX платформах это определяется с использованием механизма описанного в XDG Base Directory Specification
Возвращает : | NULL -завершённый массив строк которым владеет GLib
и который не должен освобождаться или изменятся.
|
Начиная с версии 2.6
const gchar* g_get_host_name (void);
Возвращает имя машины.
Возвращаемое имя - не обязательно полностью-компетентное имя домена, или даже представленное в DNS или в некотором другом сервисе имён вообще. Оно не должно даже быть уникальным в вашей локальной сети или сайте, но обычно это так. Вызывающие программы не должны полагаться на возвращаемое значение, имеющее специфическое свойство как уникальность, в целях безопасности. Даже если имя машины изменено в процессе выполнения приложения, возвращаемое значение из функции не изменяется. Возвращаемой строкой владеет GLib и её не нужно освобождать или изменять. Если нет определённого имени, по умолчанию возвращается зафиксированная строка "localhost".
Возвращает : | узловое имя машины (host name). |
Начиная с версии 2.8
const gchar* g_get_home_dir (void);
Возвращает текущий домашний каталог пользователя.
Помните что в отличие от традиционных UNIX инструментов, эта функция предпочитает ввод passwd
через переменную окружения HOME
.
Возвращает : | текущий домашний каталог пользователя. |
const gchar* g_get_tmp_dir (void);
Возвращает каталог используемый для временных файлов. Она использует для этого переменную окружения TMPDIR
,
TMP
и TEMP
в соответствующем порядке. Если они не определены,
то возвращается "/tmp" в UNIX и "C:\" в Windows.
Кодировка возвращаемой строки зависит от системы. В Windows, это всегда UTF-8.
Возвращаемое значение никогда не будет NULL
.
Возвращает : | каталог для временных файлов. |
gchar* g_get_current_dir (void);
Возвращает текущий каталог. Возвращаемая строка должна быть освобождена когда больше не нужна. Кодировка возвращаемой строки зависит от системы. В Windows, это всегда UTF-8.
Возвращает : | текущий каталог. |
const gchar* g_basename (const gchar *file_name);
g_basename
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде.
Вместо неё используйте g_path_get_basename()
, но помните что g_path_get_basename()
распределяет новую память для возвращаемой строки, в отличие от этот функции которая возвращает указатель в параметре.
Возвращает имя файла без любых компонентов каталога. Она возвращает указатель на полученную строку имени файла.
file_name : |
имя файла. |
Возвращает : | имя файла без любых компонентов каталога. |
#define g_dirname
g_dirname
устарела и не должна использоваться во вновь создаваемом коде.
Эта функция устарела и будет удалена в следующих версиях GLib.
Вместо неё используйте g_path_get_dirname()
.
Возвращает компоненты каталога имени файла. Если имя файла не имеет компонентов каталога, то возвращает ".". Возвращаемая строка должна быть освобождена когда будет больше не нужна.
Возвращает : | компоненты каталога для файла. |
gboolean g_path_is_absolute (const gchar *file_name);
Возвращает TRUE
если полученное имя файла file_name
является абсолютным,
то есть оно содержит полный путь из корневого каталога, такой как "/usr/local"
в UNIX или "C:\windows" в Windows системах.
file_name : |
имя файла. |
Возвращает : | TRUE
если file_name является абсолютным именем.
|
const gchar* g_path_skip_root (const gchar *file_name);
Возвращает указатель в file_name
после корневого компонента,
то есть после "/" в UNIX или "C:\" в Windows. Если file_name
не является абсолютным именем,
то возвращается NULL
.
file_name : |
имя файла. |
Возвращает : | указатель в file_name после корневого компонента.
|
gchar* g_path_get_basename (const gchar *file_name);
Возвращает последний компонент имени файла. Если file_name
завершается разделителем каталога
она возвращает компонент перед последним слэшем. Если
file_name
содержит только разделители каталога (а в Windows,
возможно букву диска), возвращается единственный разделитель. Если
file_name
пустой, она возвращает ".".
file_name : |
имя файла. |
Возвращает : | вновь распределённая строка содержащая последний компонент имени файла. |
gchar* g_path_get_dirname (const gchar *file_name);
Возвращает компонент каталога имени файла. Если имя файла не имеет компонент каталога то возвращается ".". Возвращаемая строка должна быть освобождена когда будет больше не нужна.
file_name : |
имя файла. |
Возвращает : | компонент каталога имени файла. |
gchar* g_build_filename (const gchar *first_element, ...);
Создаёт имя файла из ряда элементов используя правильный разделитель для имён файлов.
В Unix, эта функция ведёт себя аналогично g_build_path
(G_DIR_SEPARATOR_S, first_element, ....)
.
В Windows, она учитывает что может быть либо обратный слэш
(\
), либо слэш (/
)
может использоваться как разделитель имен файлов, но в остальном ведёт себя как в Unix.
Когда необходимо вставить разделитель в имя пути файла, используется один из последних
предварительно установленный в параметрах (читается слева на право).
Не делается никаких попыток сделать результирующие имя файла абсолютным путём. Если первый элемент является относительным путём, результат тоже будет относительным путём.
gchar* g_build_filenamev (gchar **args);
Ведёт себя также как g_build_filename()
, но принимает элементы пути как строковый массив, вместо массива аргументов.
Эта функция в основном полезна для языковых привязок.
args : |
NULL -завершённый массив строк содержащих элементы пути.
|
Возвращает : | вновь распределённая строка которую нужно освобождать с помощью g_free() .
|
Начиная с версии 2.8
gchar* g_build_path (const gchar *separator, const gchar *first_element, ...);
Создаёт имя из ряда элементов используя separator
как
разделитель между элементами. В границах между двумя элементами,
любые возникшие завершающие разделители в первом элементе, или возникшие
ведущие разделители во втором элементе удаляются и остаётся только одна копия вставленного разделителя.
Пустые элементы игнорируются.
Количество начальных разделителей в результате тоже самое как количество копий разделителя в первом не пустом элементе.
Количество завершающих копий разделителя в результате такое же как количество
завершающих копий разделителя в последнем не пустом элементе.
(Определение количества завершающих копий выполняется без вытеснения начальных копий,
поэтому если разделитель ABA
, ABABA
имеет одну завершающую копию.)
Однако, если есть только один не пустой элемент, а в нём нет никаких символов и никаких частей начальных или завершающих разделителей, то результатом будет оригинальное значение этого элемента.
Кроме этого для определения количества начальных или завершающих копий разделителя, элементы содержащие только копии разделителя игнорируются.
gchar* g_build_pathv (const gchar *separator, gchar **args);
Ведёт себя также как g_build_path()
,
но принимает элементы пути как строковый массив, вместо массива аргументов.
Эта функция в основном полезна для языковых привязок (language bindings).
separator : |
строка используемая как разделитель элементов пути. |
args : |
NULL -завершённый массив строк содержащий элементы пути.
|
Возвращает : | вновь распределённая строка которую нужно освобождать с помощью g_free() .
|
Начиная с версии 2.8
gchar* g_find_program_in_path (const gchar *program);
Определяет первую исполняемую именованную program
в пути пользователя,
тем же способом что execvp()
определила бы это. Возвращает распределённую строку с абсолютным именем,
или NULL
если программа не найдена в пути.
Если program
уже является абсолютным путём, возвращает копию
program
если program
существует и может исполняться,
иначе NULL
.
В Windows, если program
не имеет суффикса типа файла,
проверит суффиксы .exe, .cmd, .bat и .com, и суффиксы в переменной окружения PATHEXT
.
В Windows, она находит файл тем же способом как CreateProcess()
.
Это значит -- сначала в каталоге из которого исполняемая программа была загружена,
затем в текущем каталоге, затем в системном каталоге Windows 32-bit, затем в каталоге Windows
и в конце в каталоге указанном переменной окружения PATH
.
Если программа найдена, то возвращаемое значение содержит полное имя включая типовой суффикс.
program : |
имя программы в кодировке имён файлов GLib |
Возвращает : | абсолютный путь, или NULL
|
gint g_bit_nth_lsf (gulong mask, gint nth_bit);
Находит позицию первого набора бит в mask
, ищет вверх от (но не включая)
nth_bit
. Биты нумеруются с 0 (самый младший)
до sizeof(gulong) * 8 - 1 (31 или 63, обычно).
Для начала поиска с нулевого бита (0th bit), установите nth_bit
в -1.
mask : |
gulong содержащий флаги. |
nth_bit : |
номер бита с которого начинается поиск. |
Возвращает : | индекс первого набора бит которые больше чем nth_bit .
|
gint g_bit_nth_msf (gulong mask, gint nth_bit);
Находит позицию первого набора бит в mask
, ищет вниз от (но не включая)
nth_bit
. Биты нумеруются с 0 (наименьшее значение)
до sizeof(gulong) * 8 - 1 (31 или 63, обычно).
Для поиска с последнего бита, установите nth_bit
в -1 или GLIB_SIZEOF_LONG * 8.
mask : |
gulong содержащий флаги. |
nth_bit : |
номер бита от которого начинается поиск. |
Возвращает : | индекс первого набора бит которые меньше чем nth_bit .
|
guint g_bit_storage (gulong number);
Получает количество бит используемое для содержания number
,
например если number
это 4, то необходимо 3 бита.
number : |
guint. |
Возвращает : | количество бит используемое для содержания number .
|
guint g_spaced_primes_closest (guint num);
Получает наименьшее простое число из внутреннего массива простых чисел, которое больше чем num
.
Это используется внутри GLib для расчёта оптимального размера GHashTable.
Внутренний массив простых чисел имеет диапазон от 11 до 13845163 such that each prime is approximately 1.5-2 times the previous prime.
num : |
guint. |
Возвращает : | наименьшее простое число из внутреннего массива простых чисел которое меньше чем num .
|
void g_atexit (GVoidFunc func);
Специальная функция вызываемая для нормального завершения программы.
Начиная с GLib 2.8.2, в Windows g_atexit()
фактически макрокоманда препроцессора которая вызывает функцию atexit()
в библиотеке C.
Это значит что в случае когда код вызова g_atexit()
,
то есть atexit()
, находится в DLL, функция будет вызвана когда DLL отделена от программы.
Это обычно имеет больше смысла, чем вызов функции когда GLib DLL отдельна,
что происходило раньше когда g_atexit()
была функцией в GLib DLL.
Поведение atexit()
в контексте динамически загружаемых модулей
формально не определено и непредсказуемо.
В POSIX системах, вызов g_atexit()
(или atexit()
) в динамически загружаемом модуле который выгружается перед завершением программы
может вызвать крах при выходе из программы.
Некоторые POSIX системы реализуют atexit()
как Windows,
и имеют динамически загружаемый модуль поддерживающий собственную цепочку atexit которая вызывается когда модуль выгружен.
В других POSIX системах, перед выгрузкой динамически загружаемого модуля, регистрируется atexit функция (если есть) находящаяся в этом вызванном модуле, вне зависимости от нахождения зарегистрированного кода. Это по видимому самый надёжный подход.
Как видно из вышеупомянутого, для лучшей портируемости стоит избегать вызова
g_atexit()
(или atexit()
) кроме как из основной исполняемой программы.
func : |
функция для вызова нормального завершения программы. |
guint g_parse_debug_string (const gchar *string, const GDebugKey *keys, guint nkeys);
Анализирует строку содержащую параметры отладки в guint
,
содержащий битовые флаги. Это используется в GDK и GTK+ для анализа параметров отладки помещаемых в командную строку
или через переменные окружения.
typedef struct { gchar *key; guint value; } GDebugKey;
Связывает строку с битовым флагом.
Используется в g_parse_debug_string()
.
void (*GVoidFunc) (void);
Декларация функции которая не принимает аргументов и ничего не возвращает.
Она используется для определения что специального типа функция помещена в g_atexit()
.
void (*GFreeFunc) (gpointer data);
Декларация типа функции которая принимает в качестве аргумента указатель произвольных данных и не возвращает никакого значения. В текущий момент не используется в GLib или GTK+.
data : |
указатель данных. |
void g_qsort_with_data (gconstpointer pbase, gint total_elems, gsize size, GCompareDataFunc compare_func, gpointer user_data);
Тоже самое как стандартная C функция qsort()
, но
подпрограмма сравнения принимает параметр пользовательских данных.
pbase : |
начало массива для сортировки |
total_elems : |
элементы в массиве |
size : |
размер каждого элемента |
compare_func : |
функция для сравнения элементов |
user_data : |
данные для помещения в compare_func
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GNode; GNode* g_node_new (gpointer data); GNode* g_node_copy (GNode *node); gpointer (*GCopyFunc) (gconstpointer src, gpointer data); GNode* g_node_copy_deep (GNode *node, GCopyFunc copy_func, gpointer data); GNode* g_node_insert (GNode *parent, gint position, GNode *node); GNode* g_node_insert_before (GNode *parent, GNode *sibling, GNode *node); GNode* g_node_insert_after (GNode *parent, GNode *sibling, GNode *node); #define g_node_append (parent, node) GNode* g_node_prepend (GNode *parent, GNode *node); #define g_node_insert_data (parent, position, data) #define g_node_insert_data_before (parent, sibling, data) #define g_node_append_data (parent, data) #define g_node_prepend_data (parent, data) void g_node_reverse_children (GNode *node); void g_node_traverse (GNode *root, GTraverseType order, GTraverseFlags flags, gint max_depth, GNodeTraverseFunc func, gpointer data); enum GTraverseFlags; gboolean (*GNodeTraverseFunc) (GNode *node, gpointer data); void g_node_children_foreach (GNode *node, GTraverseFlags flags, GNodeForeachFunc func, gpointer data); void (*GNodeForeachFunc) (GNode *node, gpointer data); GNode* g_node_get_root (GNode *node); GNode* g_node_find (GNode *root, GTraverseType order, GTraverseFlags flags, gpointer data); GNode* g_node_find_child (GNode *node, GTraverseFlags flags, gpointer data); gint g_node_child_index (GNode *node, gpointer data); gint g_node_child_position (GNode *node, GNode *child); #define g_node_first_child (node) GNode* g_node_last_child (GNode *node); GNode* g_node_nth_child (GNode *node, guint n); GNode* g_node_first_sibling (GNode *node); #define g_node_next_sibling (node) #define g_node_prev_sibling (node) GNode* g_node_last_sibling (GNode *node); #define G_NODE_IS_LEAF (node) #define G_NODE_IS_ROOT (node) guint g_node_depth (GNode *node); guint g_node_n_nodes (GNode *root, GTraverseFlags flags); guint g_node_n_children (GNode *node); gboolean g_node_is_ancestor (GNode *node, GNode *descendant); guint g_node_max_height (GNode *root); void g_node_unlink (GNode *node); void g_node_destroy (GNode *root); void g_node_push_allocator (gpointer dummy); void g_node_pop_allocator (void);
Структура GNode и связанные с ней функции обеспечивают N-ary дерево структур данных, где узлы в дереве могут содержать произвольные данные.
Для создания нового дерева используйте g_node_new()
.
Для вставки узлов в дерево используйте g_node_insert()
,
g_node_insert_before()
,
g_node_append()
и
g_node_prepend()
.
Для создания нового узла и вставки его в дерево используйте
g_node_insert_data()
,
g_node_insert_data_before()
,
g_node_append_data()
и
g_node_prepend_data()
.
Для реверса дочерних элементов узла используйте
g_node_reverse_children()
.
Для поиска узла используйте g_node_get_root()
, g_node_find()
, g_node_find_child()
,
g_node_child_index()
, g_node_child_position()
,
g_node_first_child()
, g_node_last_child()
,
g_node_nth_child()
, g_node_first_sibling()
, g_node_prev_sibling()
,
g_node_next_sibling()
или g_node_last_sibling()
.
Для получения информации об узле или дереве используйте G_NODE_IS_LEAF()
,
G_NODE_IS_ROOT()
, g_node_depth()
, g_node_n_nodes()
, g_node_n_children()
,
g_node_is_ancestor()
or g_node_max_height()
.
Для обхода дерева, вызывая функцию для каждого посещяемого узла при обходе, используйте
g_node_traverse()
или
g_node_children_foreach()
.
Для удаления узла или дочернего дерева из дерева используйте
g_node_unlink()
или
g_node_destroy()
.
typedef struct { gpointer data; GNode *next; GNode *prev; GNode *parent; GNode *children; } GNode;
Структура GNode представляет один узел в
N-ary Tree.
Поле data
содержит фактические данные в узле.
Поля next
и prev
указывают на дочерние узлы (дочерние - это другие GNode с тем же родителем).
Поле parent
указывает на родителя GNode,
или NULL
если
GNode является корнем дерева.
Поле children
указывает на первую дочернюю GNode.
Другие дочерние узлы связываются используя указатель next
каждого дочернего узла.
GNode* g_node_new (gpointer data);
Создаёт новую GNode содержащую полученные данные. Используется для создания первого узла в дереве.
data : |
данные нового узла. |
Возвращает : | новый GNode. |
GNode* g_node_copy (GNode *node);
Рекурсивно копирует GNode
(но не делает глубоких копий данных в узлах,
смотрите g_node_copy_deep()
если вам это нужно).
gpointer (*GCopyFunc) (gconstpointer src, gpointer data);
Функция этой сигнатуры используется для копирования узла данных выполняя глубокую копию дерева.
src : |
указатель на данные которые должны быть скопированны. |
data : |
дополнительные данные. |
Возвращает : | указатель на копию. |
Начиная с версии 2.4
GNode* g_node_copy_deep (GNode *node, GCopyFunc copy_func, gpointer data);
Рекурсивно копирует GNode и его данные.
node : |
GNode |
copy_func : |
функция вызываемая для копирования данных внутри каждого узла,
или NULL
для использования оригинальных данных.
|
data : |
данные помещаемые в copy_func
|
Возвращает : | новый GNode содержащий копии данных в
node .
|
Начиная с версии 2.4
GNode* g_node_insert (GNode *parent, gint position, GNode *node);
Вставляет GNode ниже родителя в указанную позицию.
GNode* g_node_insert_before (GNode *parent, GNode *sibling, GNode *node);
Вставляет GNode ниже родителя перед указанным соседом.
GNode* g_node_insert_after (GNode *parent, GNode *sibling, GNode *node);
Вставляет GNode ниже родителя после указанного соседа.
#define g_node_append(parent, node)
Вставляет GNode как последний дочерний указанного родителя.
GNode* g_node_prepend (GNode *parent, GNode *node);
Вставляет GNode как первый дочерний указанного родителя.
#define g_node_insert_data(parent, position, data)
Вставляет новый GNode в указанную позицию.
#define g_node_insert_data_before(parent, sibling, data)
Вставляет новый GNode перед указанным соседом.
#define g_node_append_data(parent, data)
Вставляет новый GNode как последний дочерний указанного родителя.
#define g_node_prepend_data(parent, data)
Вставляет новый GNode как первый дочерний указанного родителя.
void g_node_reverse_children (GNode *node);
Переворачивает порядок дочерних GNode. (Она не меняет порядок внуков.)
node : |
GNode. |
void g_node_traverse (GNode *root, GTraverseType order, GTraverseFlags flags, gint max_depth, GNodeTraverseFunc func, gpointer data);
Обходит дерево начиная с указанного корня GNode.
Она вызывает указанную функцию для каждого посещяемого узла.
Обход может быть прекращён в любой точке когда TRUE
вернётся из func
.
root : |
корень GNode дерева для обхода. |
order : |
порядок в котором посещаются узлы - G_IN_ORDER ,
G_PRE_ORDER ,
G_POST_ORDER , или
G_LEVEL_ORDER .
|
flags : |
какие типы дочерних узлов будут посещены,
один из вариантов - G_TRAVERSE_ALL ,
G_TRAVERSE_LEAVES и
G_TRAVERSE_NON_LEAVES .
|
max_depth : |
максимальная глубина обхода. Узлы на этой глубине не будут посещаться. Если max_depth равна -1 посещаются все узлы в дереве. Если глубина 1, посещается только корень. Если глубина 2, посещаются корень и его дочерние узлы. И так далее. |
func : |
функция вызываемая для каждого посещённого элемента GNode. |
data : |
пользовательские данные помещаемые в функцию. |
typedef enum { G_TRAVERSE_LEAVES = 1 << 0, G_TRAVERSE_NON_LEAVES = 1 << 1, G_TRAVERSE_ALL = G_TRAVERSE_LEAVES | G_TRAVERSE_NON_LEAVES, G_TRAVERSE_MASK = 0x03, G_TRAVERSE_LEAFS = G_TRAVERSE_LEAVES, G_TRAVERSE_NON_LEAFS = G_TRAVERSE_NON_LEAVES } GTraverseFlags;
Определяет какие узлы посещаются при выполнении некоторых функций дерева,
включая g_node_traverse()
и
g_node_find()
.
G_TRAVERSE_LEAVES |
только вершины узлов должны посещаться. Это название было введено в версии 2.6,
ранние версии использовали G_TRAVERSE_LEAFS .
|
G_TRAVERSE_NON_LEAVES |
только не вершины должны посещаться. Это имя введено в версии 2.6,
в ранних версиях использовалось G_TRAVERSE_NON_LEAFS .
|
G_TRAVERSE_ALL |
все узлы должны посещаться. |
G_TRAVERSE_MASK |
|
G_TRAVERSE_LEAFS |
идентично G_TRAVERSE_LEAVES
|
G_TRAVERSE_NON_LEAFS |
идентично G_TRAVERSE_NON_LEAVES
|
gboolean (*GNodeTraverseFunc) (GNode *node, gpointer data);
Определяет тип функции помещаемой в g_node_traverse()
.
Функция вызывается с каждым посещённым узлом, который передают вместе с пользовательскими данными в
g_node_traverse()
.
Если функция возвращает TRUE
, то обход прекращается.
node : |
GNode. |
data : |
пользовательские данные помещаемые в g_node_traverse() .
|
Возвращает : |
TRUE для остановки обхода.
|
void g_node_children_foreach (GNode *node, GTraverseFlags flags, GNodeForeachFunc func, gpointer data);
Вызывает функцию для каждого дочернего GNode. Помните что она не опускается ниже дочерних узлов.
node : |
GNode. |
flags : |
какие типы дочерних элементов посещаются, один из
G_TRAVERSE_ALL ,
G_TRAVERSE_LEAVES и
G_TRAVERSE_NON_LEAVES .
|
func : |
функция вызываемая для каждого посещённого узла. |
data : |
пользовательские данные помещаемые в функцию. |
void (*GNodeForeachFunc) (GNode *node, gpointer data);
Определяет тип функции помещаемой в g_node_children_foreach()
.
Функция вызываемая для каждого дочернего узла, вместе с пользовательскими данными которые помещаются в
g_node_children_foreach()
.
node : |
GNode. |
data : |
пользовательские данные помещаемые в g_node_children_foreach() .
|
GNode* g_node_get_root (GNode *node);
Определяет корень дерева.
node : |
GNode. |
Возвращает : | корень дерева. |
GNode* g_node_find (GNode *root, GTraverseType order, GTraverseFlags flags, gpointer data);
Находит GNode в дереве.
root : |
корневой GNode дерева для поиска. |
order : |
порядок в котором посещаются узлы - G_IN_ORDER ,
G_PRE_ORDER ,
G_POST_ORDER , или
G_LEVEL_ORDER .
|
flags : |
какой тип дочернего элемента должен быть найден, один из
G_TRAVERSE_ALL ,
G_TRAVERSE_LEAVES и
G_TRAVERSE_NON_LEAVES .
|
data : |
данные для поиска. |
Возвращает : | найденный GNode, или
NULL если данные не найдены.
|
GNode* g_node_find_child (GNode *node, GTraverseFlags flags, gpointer data);
Находит первый дочерний GNode с указанными данными.
node : |
GNode. |
flags : |
какой тип дочерних узлов разыскивается, один из
G_TRAVERSE_ALL ,
G_TRAVERSE_LEAVES и
G_TRAVERSE_NON_LEAVES .
|
data : |
данные для поиска. |
Возвращает : | найденный дочерний GNode, или
NULL если данные не найдены.
|
gint g_node_child_index (GNode *node, gpointer data);
Определяет позицию первого дочернего GNode который содержит указанные данные.
node : |
GNode. |
data : |
данные для поиска. |
Возвращает : | номер дочернего node который содержит data ,
или -1 если данные не найдены.
|
gint g_node_child_position (GNode *node, GNode *child);
Определяет позицию GNode относительно его соседей.
child
должен быть дочерним по отношению к node
.
Первый дочерний нумеруется 0, второй 1, и так далее.
node : |
GNode. |
child : |
дочерний по отношению к node .
|
Возвращает : | позиция child относительно его соседей.
|
GNode* g_node_nth_child (GNode *node, guint n);
Определяет дочерний GNode, используя указанный номер.
Первый это номер 0. Если номер слишком большой, возвращает NULL
.
node : |
GNode. |
n : |
номер желаемого дочернего элемента. |
Возвращает : | дочерний node с номером n .
|
GNode* g_node_first_sibling (GNode *node);
Определяет первый соседний GNode. Это может быть сам узел.
node : |
GNode. |
Возвращает : | первый соседний node .
|
GNode* g_node_last_sibling (GNode *node);
Определяет последнего соседа GNode. Это может быть сам узел.
node : |
GNode. |
Возвращает : | последний соседний node .
|
guint g_node_depth (GNode *node);
Определяет глубину GNode.
Если node
это NULL
глубина равна 0.
Корневой узел имеет глубину равную 1.
Для дочерних элементов корневого узла глубина равна 2. И так далее.
guint g_node_n_nodes (GNode *root, GTraverseFlags flags);
Определяет количество узлов в дереве.
root : |
GNode. |
flags : |
какие типы дочерних элементов подсчитываются, один из вариантов
G_TRAVERSE_ALL ,
G_TRAVERSE_LEAVES и
G_TRAVERSE_NON_LEAVES .
|
Возвращает : | количество узлов в дереве. |
guint g_node_n_children (GNode *node);
Определяет количество дочерних GNode.
node : |
GNode. |
Возвращает : | количество дочерних node .
|
gboolean g_node_is_ancestor (GNode *node, GNode *descendant);
Возвращает TRUE
если
node
предок descendant
.
Это правильно если узел является родителем descendant
, или если узел является родителем родителя
descendant
и так далее.
guint g_node_max_height (GNode *root);
Определяет максимальную высоту всех переходов от GNode. Это максимальное расстояние от GNode до всех вершин.
Если root
это NULL
,
возвращается 0. Если root
не имеет дочерних элементов, возвращается 1.
Если root
имеет дочерние элементы, возвращается 2. И так далее.
root : |
GNode. |
Возвращает : | максимальная высота дерева от root .
|
void g_node_unlink (GNode *node);
Сбрасывает ссылки GNode из дерева, получая в качестве результата два разделённых дерева.
node : |
GNode для разлинковки, который становится корнем нового дерева. |
void g_node_destroy (GNode *root);
Удаляет GNode и дочерние элементы из дерева, освобождает любую распределённую память.
root : |
корень дерева/поддерева для уничтожения. |
void g_node_push_allocator (gpointer dummy);
g_node_push_allocator
устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде.
Она ничего не делает, так как GNode конвертируется в
slice allocator
Устанавливает распределитель для распределения элементов GNode.
Использует g_node_pop_allocator()
для восстановления предыдущего распределителя.
Помните что эта функция не доступна если GLib была скомпилирована с опцией --disable-mem-pools
dummy : |
GAllocator для распределения элементов GNode. |
void g_node_pop_allocator (void);
g_node_pop_allocator
устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде.
Она ничего не делает, так как GNode конвертируется в
slice allocator
Восстанавливает предыдущий GAllocator, используется при распределении элементов GNode.
Помните что эта функция не доступна если GLib скомпилирована с опцией --disable-mem-pools
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> #define G_IEEE754_FLOAT_BIAS #define G_IEEE754_DOUBLE_BIAS union GFloatIEEE754; union GDoubleIEEE754; #define G_E #define G_LN2 #define G_LN10 #define G_PI #define G_PI_2 #define G_PI_4 #define G_SQRT2 #define G_LOG_2_BASE_10
GLib предлагает математические константы такие как G_PI для значения pi; большинство платформ имеют их в C библиотеке, но некоторые нет, GLib версии всегда включают их.
Множества GFloatIEEE754 и GDoubleIEEE754 используются для доступности знаков, десятичных точек (mantissa) и степеней IEEE floats и doubles. Эти множества определяются как соответствующие для данной платформы. IEEE floats и doubles поддерживаются (используются для хранения) по крайней мере Intel, PPC и Sparc.
Для справки: http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html
#define G_IEEE754_FLOAT_BIAS (127)
Смотрите http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html
#define G_IEEE754_DOUBLE_BIAS (1023)
Смотрите http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html
union GFloatIEEE754 { gfloat v_float; struct { guint mantissa : 23; guint biased_exponent : 8; guint sign : 1; } mpn; };
Множества GFloatIEEE754 и GDoubleIEEE754 используются для доступности знаков, десятичных точек (mantissa) и степеней IEEE floats и doubles. Эти множества определяются как соответствующие для данной платформы. IEEE floats и doubles поддерживаются (используются для хранения) по крайней мере Intel, PPC и Sparc.
Для справки:http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html
union GDoubleIEEE754 { gdouble v_double; struct { guint mantissa_low : 32; guint mantissa_high : 20; guint biased_exponent : 11; guint sign : 1; } mpn; };
The GFloatIEEE754 and GDoubleIEEE754 используются для доступности знаков, десятичных точек (mantissa) и степеней IEEE floats и doubles. Эти множества определяются как соответствующие для данной платформы. IEEE floats и doubles поддерживаются (используются для хранения) по крайней мере Intel, PPC и Sparc.
Для справки:http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html
#define G_LN10 2.3025850929940456840179914546843642076011014886288
Естевственный логарифм 10.
#define G_PI 3.1415926535897932384626433832795028841971693993751
Значение pi (соотношение окружности круга к диаметру).
#define G_LOG_2_BASE_10 (0.30102999566398119521)
Используется для дурачеств с форматом float, смотрите http://cch.loria.fr/documentation/IEEE754/numerical_comp_guide/ncg_math.doc.html
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Pointer ArraysPointer Arrays — Массив указателей для любого типа данных, который увеличивается автоматически при добавлении элементов. |
#include <glib.h> GPtrArray; GPtrArray* g_ptr_array_new (void); GPtrArray* g_ptr_array_sized_new (guint reserved_size); void g_ptr_array_add (GPtrArray *array, gpointer data); gboolean g_ptr_array_remove (GPtrArray *array, gpointer data); gpointer g_ptr_array_remove_index (GPtrArray *array, guint index_); gboolean g_ptr_array_remove_fast (GPtrArray *array, gpointer data); gpointer g_ptr_array_remove_index_fast (GPtrArray *array, guint index_); void g_ptr_array_remove_range (GPtrArray *array, guint index_, guint length); void g_ptr_array_sort (GPtrArray *array, GCompareFunc compare_func); void g_ptr_array_sort_with_data (GPtrArray *array, GCompareDataFunc compare_func, gpointer user_data); void g_ptr_array_set_size (GPtrArray *array, gint length); #define g_ptr_array_index (array,index_) gpointer* g_ptr_array_free (GPtrArray *array, gboolean free_seg); void g_ptr_array_foreach (GPtrArray *array, GFunc func, gpointer user_data);
Массивы указателей похожи на простые массивы, но используются только для хранения указатедей.
Если вы удалите элементы из массива, элементы из конца массива переместятся в свободное пространство освобождённое удалёнными элементами. Это значит что вы не должны полагаться на сохраняющуюся нумерацию специфичных элементов. Вы должны быть так же внимательны удаляя элементы при перемещении через массив.
Для создания массива указателей, используйте g_ptr_array_new()
.
Для добавления элементов в массив указателей, используйте g_ptr_array_add()
.
Для удаления элементов из массива указателей, используйте g_ptr_array_remove()
,
g_ptr_array_remove_index()
, или
g_ptr_array_remove_index_fast()
.
Для доступа к элементам в массиве указателей, используйте g_ptr_array_index()
.
Для установки размера массива указателей, используйте g_ptr_array_set_size()
.
Для освобождения массива указателей, используйте g_ptr_array_free()
.
Пример 7. Using a GPtrArray
GPtrArray *gparray; gchar *string1 = "one", *string2 = "two", *string3 = "three"; gparray = g_ptr_array_new (); g_ptr_array_add (gparray, (gpointer) string1); g_ptr_array_add (gparray, (gpointer) string2); g_ptr_array_add (gparray, (gpointer) string3); if (g_ptr_array_index (gparray, 0) != (gpointer) string1) g_print ("ERROR: got %p instead of %p\n", g_ptr_array_index (gparray, 0), string1); g_ptr_array_free (gparray, TRUE);
typedef struct { gpointer *pdata; guint len; } GPtrArray;
Содержит общедоступные поля массива указателей.
GPtrArray* g_ptr_array_new (void);
Создаёт новый GPtrArray.
Возвращает : | новый GPtrArray. |
GPtrArray* g_ptr_array_sized_new (guint reserved_size);
Создаёт новый GPtrArray
с предварительно распределенными reserved_size
указателями.
Это исключает частое перераспределение, если вы собираетесь добавить много указателей в массив.
Однако помните, размер массива остаётся 0.
reserved_size : |
количество предварительно распределённых указателей. |
Возвращает : | новый GPtrArray. |
void g_ptr_array_add (GPtrArray *array, gpointer data);
Добавляет указатель в конец массива указателей. Массив будет автоматически увеличен, если это необходимо.
array : |
GPtrArray. |
data : |
добавляемый указатель. |
gboolean g_ptr_array_remove (GPtrArray *array, gpointer data);
Удаляет первый найденный полученный указатель из массива. Следующие элементы перемещаются вниз на одно место.
Она возвращает TRUE
если указатель был удалён, или
FALSE
если указатель не найден.
gpointer g_ptr_array_remove_index (GPtrArray *array, guint index_);
Удаляет указатель с полученным номером из массива указателей. Следующие элементы перемещаются на одну позицию вниз.
array : |
GPtrArray. |
index_ : |
номер указателя для удаления. |
Возвращает : | указатель который был удалён. |
gboolean g_ptr_array_remove_fast (GPtrArray *array, gpointer data);
Удаляет первый обнаруженный указатель, полученный в качестве параметра, из массива указателей.
Оставшиеся элементы в массиве используются для заполнения пространства, поэтому эта функция не сохраняет порядок массива.
Но она быстрее чем g_ptr_array_remove()
.
Возвращает TRUE
если указатель был удалён,
или FALSE
если указатель не найден в массиве.
gpointer g_ptr_array_remove_index_fast (GPtrArray *array, guint index_);
Удаляет указатель с полученным номером из массива указателей.
Оставшиеся элементы в массиве используются для заполнения пространства, поэтому эта функция не сохраняет порядок в массиве.
Но она быстрее чем
g_ptr_array_remove_index()
.
array : |
GPtrArray. |
index_ : |
номер указателя для удаления. |
Возвращает : | указатель который был удалён. |
void g_ptr_array_remove_range (GPtrArray *array, guint index_, guint length);
Удаляет полученное количество указателей начиная с полученного номера из GPtrArray. Следующие элементы перемещаются закрывая пустоту.
array : |
GPtrArray .
|
index_ : |
номер первого указателя для удаления. |
length : |
количество указателей для удаления. |
Начиная с версии 2.4
void g_ptr_array_sort (GPtrArray *array, GCompareFunc compare_func);
Сортирует массив, используя compare_func
которая должна быть в стиле
функции сравнения qsort()
(возвращает отрицательное если первый arg меньше чем второй arg,
ноль если они равны, положительное если первый arg больше чем второй arg).
Если оба сравниваемых элемента массива равны, их положение в порядке сортировки массива неопределено.
Функция сравнения для g_ptr_array_sort()
не принимает указатели из массива как аргументы, она принимает указатели на указатели в массиве.
array : |
GPtrArray. |
compare_func : |
функция сравнения. |
void g_ptr_array_sort_with_data (GPtrArray *array, GCompareDataFunc compare_func, gpointer user_data);
Похожа на g_ptr_array_sort()
,
но функция сравнения имеет дополнительный аргумент пользовательских данных.
Функция сравнения для g_ptr_array_sort_with_data()
не принимает указатели из массива как аргументы, она принимает указатели на указатели в массиве.
array : |
GPtrArray. |
compare_func : |
функция сравнения. |
user_data : |
данные помещаемые в compare_func .
|
void g_ptr_array_set_size (GPtrArray *array, gint length);
Устанавливает размер массива, расширяя его если необходимо.
Новые элементы устанавливаются в NULL
.
array : |
GPtrArray. |
length : |
новый размер массива указателей. |
#define g_ptr_array_index(array,index_)
Возвращает указатель с полученным номером массива указателей.
array : |
GPtrArray. |
index_ : |
номер возвращаемого указателя. |
Возвращает : | указатель с полученным номером. |
gpointer* g_ptr_array_free (GPtrArray *array, gboolean free_seg);
Освобождает всю память распределённую для массива указателей.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> typedef GQuark; GQuark g_quark_from_string (const gchar *string); GQuark g_quark_from_static_string (const gchar *string); const gchar* g_quark_to_string (GQuark quark); GQuark g_quark_try_string (const gchar *string); const gchar* g_intern_string (const gchar *string); const gchar* g_intern_static_string (const gchar *string);
Кварк является связью между строками и целочисленными идентификаторами. Получая либо строку, либо GQuark идентификатор, можно найти либо то, либо другое.
Кварки используются и для Datasets и для Keyed Data Lists.
Для создания нового кварка из строки, используйте g_quark_from_string()
или
g_quark_from_static_string()
.
Для поиска строки соответствующей полученному GQuark,
используйте g_quark_to_string()
.
Для поиска GQuark соответствующего полученной строке,
используйте g_quark_try_string()
.
Другой способ использования для строкового пула поддерживающего функции кварка интернирования строки,
использование g_intern_string()
или
g_intern_static_string()
.
Интернированная строка это канонически представленная строка. Одно важно преимущество интернированных строк в том,
что они могут сравниваться на эквивалентность с помощью простого сравнения указателя, в отличие от использования
strcmp()
.
typedef guint32 GQuark;
GQuark это уникальный целочисленный идентификатор специфичной строки.
GQuark g_quark_from_string (const gchar *string);
Определяет GQuark идентификатор указанной строки. Если строка не имеет текущего связанного с ней GQuark, создаётся новый GQuark, используя копию строки.
string : |
строка. |
Возвращает : | GQuark идентификатор строки. |
GQuark g_quark_from_static_string (const gchar *string);
Определяет GQuark идентификатор указанной (статичной) строки. Если строка не имеет связанного с ней GQuark, создаётся новый GQuark, связывая с указанной строкой.
Помните что эта функция идентична g_quark_from_string()
,
исключая то, что если новый GQuark создан, используется сама строка, а не
её копия. Это сохраняет память, но может использоваться только если строка всегда существует.
Она может использоваться со статически распределёнными строками в основной программе, но не со статически распределённой памятью в
динамически загружаемых модулях, если вы планируете выгружать модуль снова (например не используйте эту функцию в движках GTK+ тем).
string : |
строка. |
Возвращает : | GQuark идентификатор строки. |
const gchar* g_quark_to_string (GQuark quark);
Определяет строку связанную с полученным GQuark.
GQuark g_quark_try_string (const gchar *string);
Определяет GQuark связанный с полученной строкой, или 0 если строка не связана с GQuark.
Если вы хотите чтобы GQuark был создан, если он не существует, используйте
g_quark_from_string()
,
или g_quark_from_static_string()
.
const gchar* g_intern_string (const gchar *string);
Возвращает каноническое представление string
. Интернированные строки могут сравниваться
на эквивалентность с помощью сравнения указателей, вместо использования strcmp()
.
string : |
строка |
Возвращает : | каноническое представление строки |
Начиная с версии 2.10
const gchar* g_intern_static_string (const gchar *string);
Возвращает каноническое представление string
. Интернированные строки могут сравниваться на
эквивалентность с помощью сравнения указателей, вместо использования strcmp()
.
g_intern_static_string()
не копирует строку,
однако string
не должна освобождаться или изменяться.
string : |
статичная строка |
Возвращает : | каноническое представление строки |
Начиная с версии 2.10
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GRand; GRand* g_rand_new_with_seed (guint32 seed); GRand* g_rand_new_with_seed_array (const guint32 *seed, guint seed_length); GRand* g_rand_new (void); GRand* g_rand_copy (GRand *rand_); void g_rand_free (GRand *rand_); void g_rand_set_seed (GRand *rand_, guint32 seed); void g_rand_set_seed_array (GRand *rand_, const guint32 *seed, guint seed_length); #define g_rand_boolean (rand_) guint32 g_rand_int (GRand *rand_); gint32 g_rand_int_range (GRand *rand_, gint32 begin, gint32 end); gdouble g_rand_double (GRand *rand_); gdouble g_rand_double_range (GRand *rand_, gdouble begin, gdouble end); void g_random_set_seed (guint32 seed); #define g_random_boolean () guint32 g_random_int (void); gint32 g_random_int_range (gint32 begin, gint32 end); gdouble g_random_double (void); gdouble g_random_double_range (gdouble begin, gdouble end);
Следующие функции позволяют вам использовать портируемый, быстрый и хороший генератор псевдо-случайных чисел (PRNG). Он использует Mersenne Twister PRNG, который первоначально был разработан Makoto Matsumoto и Takuji Nishimura. Детальная информация может быть найдена на www.math.keio.ac.jp/~matumoto/emt.html.
Если вам просто нужен случайный номер, вы вызываете функции
g_random_*
, которые создают глобально используемую
GRand и используется внутренне согласно функций
g_rand_*
. Всякий раз когда вам необходим поток репродуктивных случайных чисел, вам лучше
создать непосредственно GRand и напрямую использовать функции
g_rand_*
, которые будут также немного быстрее. Инициализация
GRand с определённым начальным числом производит одинаковую серию случайных чисел на всех платформах.
Они могут также использоваться как начальные числа например игр.
Функции g_rand*_range
возвращают одинаково распределённые случайные числа высокого качества,
тогда как например (
часто не приводит к одинаковому распределению чисел.
g_random_int()
%max)
GLib изменил алгоритм отбора для генератора псевдо-случайных чисел Mersenne Twister,
который используется для GRand и GRandom.
Это было необходимо, потому что некоторые начальные числа ведут к очень плохим псевдо-случайным потокам.
Также псевдо-случайные целочисленные сгенерированные с помощью g_rand*
будут иметь немного лучший эквивалент распределения в новой версии GLib.
_int_range()
Оригинальный алгоритм отбора и генерации, который может быть найден в GLib 2.0.x,
может быть использован вместо нового с помощью установки переменной окружения
G_RANDOM_VERSION
в значение '2.0'. Используйте алгоритм
GLib-2.0 только если вам необходимо точно воспроизвести последовательность
чисел сгенерированных с помощью Glib-2.0.
typedef struct _GRand GRand;
Структура GRand является непрозрачной структурой данных.
Доступ к ней возможен только с помощью функций g_rand_*
.
GRand* g_rand_new_with_seed (guint32 seed);
Создаёт новый генератор случайного числа инициализированный с помощью seed
.
seed : |
значение для инициализации генератора случайного числа. |
Возвращает : | новый GRand. |
GRand* g_rand_new_with_seed_array (const guint32 *seed, guint seed_length);
Создаёт новый генератор случайного числа инициализированный с помощью seed
.
seed : |
массив начальных чисел для инициализации генератора случайного числа. |
seed_length : |
длина массива начальных чисел для инициализации генератора случайного числа. |
Возвращает : | новый GRand. |
Начиная с версии 2.4
GRand* g_rand_new (void);
Создаёт генератор случайного числа инициализированный с помощью начального числа принятого из /dev/urandom
(если существует) или из текущего времени (как аварийный режим).
Возвращает : | новый GRand. |
GRand* g_rand_copy (GRand *rand_);
Копирует GRand в новый с тем же самым состоянием как прежде. Таким образом вы можете сделать снимок (snapshot) генератора случайного числа для воспроизведения в будущем.
Начиная с версии 2.4
void g_rand_free (GRand *rand_);
Освобождает память распределённую для GRand.
rand_ : |
GRand. |
void g_rand_set_seed (GRand *rand_, guint32 seed);
Устанавливает начальное число для генератора случайных чисел GRand в значение seed
.
rand_ : |
GRand. |
seed : |
значение для переинициализации генератора случайного числа. |
void g_rand_set_seed_array (GRand *rand_, const guint32 *seed, guint seed_length);
Инициализирует генератор случайного числа массивом longs. Массив может иметь произвольный размер, но только первые 624 значения принимаются во внимание. Эта функция полезна если вы имеете много начальных чисел низкой энтропии, или если требуется больше чем 32 разрядная энтропия для вашего приложения.
rand_ : |
GRand. |
seed : |
массив для инициализации |
seed_length : |
длина массива |
Начиная с версии 2.4
#define g_rand_boolean(rand_)
Возвращает произвольное gboolean из rand_
.
Это соответствует броску монеты без смещения.
guint32 g_rand_int (GRand *rand_);
Возвращает следующее произвольное guint32 из rand_
одинаково распределённое в диапазоне [0..2^32-1].
rand_ : |
GRand. |
Возвращает : | Произвольное число. |
gint32 g_rand_int_range (GRand *rand_, gint32 begin, gint32 end);
Возвращает следующее произвольное gint32 из rand_
одинаково распределённое в диапазоне [begin
..end
-1].
rand_ : |
GRand. |
begin : |
нижняя граница интервала. |
end : |
верхняя граница интервала. |
Возвращает : | Произвольное число. |
gdouble g_rand_double (GRand *rand_);
Возвращает следующее произвольное gdouble из rand_
одинаково распределённое в диапазоне [0..1).
rand_ : |
GRand. |
Возвращает : | Произвольное число. |
gdouble g_rand_double_range (GRand *rand_, gdouble begin, gdouble end);
Возвращает следующее произвольное gdouble из rand_
одинаково распределённое в диапазоне [begin
..end
).
rand_ : |
GRand. |
begin : |
нижняя граница интервала. |
end : |
верхняя граница интервала. |
Возвращает : | Произвольное число. |
void g_random_set_seed (guint32 seed);
Устанавливает начальное число для глобального генератора случайных чисел,
который используется функциями g_random_*
, в значение seed
.
seed : |
значение для переинициализации глобального генератора случайных чисел. |
#define g_random_boolean()
Возвращает произвольное gboolean. Это соответствует броску монеты без смещения.
Возвращает : | произвольное gboolean. |
guint32 g_random_int (void);
Возвращает произвольное guint32 одинаково распределённое в диапазоне [0..2^32-1].
Возвращает : | Произвольное число. |
gint32 g_random_int_range (gint32 begin, gint32 end);
Возвращает произвольное gint32 одинаково распределённое в диапазоне
[begin
..end
-1].
begin : |
нижняя граница интервала. |
end : |
верхняя граница интервала. |
Возвращает : | Произвольное число. |
gdouble g_random_double (void);
Возвращает произвольное gdouble одинаково распределённое в диапазоне [0..1).
Возвращает : | Произвольное число. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Relations and TuplesRelations and Tuples — Таблицы данных которые могут быть проиндексированы любым количеством полей. |
#include <glib.h> GRelation; GRelation* g_relation_new (gint fields); void g_relation_index (GRelation *relation, gint field, GHashFunc hash_func, GEqualFunc key_equal_func); void g_relation_insert (GRelation *relation, ...); gboolean g_relation_exists (GRelation *relation, ...); gint g_relation_count (GRelation *relation, gconstpointer key, gint field); GTuples* g_relation_select (GRelation *relation, gconstpointer key, gint field); gint g_relation_delete (GRelation *relation, gconstpointer key, gint field); void g_relation_destroy (GRelation *relation); void g_relation_print (GRelation *relation); GTuples; void g_tuples_destroy (GTuples *tuples); gpointer g_tuples_index (GTuples *tuples, gint index_, gint field);
GRelation - это таблица данных которая может быть проиндексирована любым количеством полей, точнее как простые таблицы базы данных. GRelation содержит множество записей, называемых кортежами. каждая запись содержит множество полей. Записи не сортируются, поэтому невозможно найти запись по порядковому номеру.
Помните что GRelation таблицы в настоящее время лимитированы двумя полями.
Для создания GRelation, используйте g_relation_new()
.
Для определения какие поля должны проиндексироваться, используйте g_relation_index()
.
Помните что её нужно вызывать прежде чем любой кортеж будет добавлен в GRelation.
Для добавления записей в GRelation используйте
g_relation_insert()
.
Для определения есть ли данная запись в GRelation,
используйте g_relation_exists()
.
Помните что поля сравниваются непосредственно, поэтому указатели должны указывать в туже самую позицию
(то есть разные копии одной и той же строки не будут соответсвовать.)
Для подсчёта количества записей которые имеют специфичное значение в указанном поле, используйте
g_relation_count()
.
Для получения всех записей которые имеют специфичное значение в указанном поле, используйте
g_relation_select()
.
Для доступа к полям получившихся записей, используйте
g_tuples_index()
.
Для освобождения получившихся записей используйте
g_tuples_destroy()
.
Для удаления всех записей которые имеют специфичное значение в указанном поле, используйте
g_relation_delete()
.
Для уничтожения GRelation, используйте
g_relation_destroy()
.
Для помощи отслеживания объектов GRelation,
используйте g_relation_print()
.
typedef struct _GRelation GRelation;
Структура GRelation - это непрозрачная структура данных представляющая Relation. Доступ к ней должен осуществляться только следующими функциями.
GRelation* g_relation_new (gint fields);
Создаёт новую GRelation с указанным количеством полей. Помните что текущее количество полей должно быть 2.
fields : |
количество полей. |
Возвращает : | новая GRelation. |
void g_relation_index (GRelation *relation, gint field, GHashFunc hash_func, GEqualFunc key_equal_func);
Создаёт индекс указанного поля. Помните что её нужно вызвать перед добавлением любых записей в GRelation.
relation : |
GRelation. |
field : |
индексируемое поле, подсчёт с 0. |
hash_func : |
функция для производства хеш значения из поля данных. |
key_equal_func : |
функция для сравнения двух значений указанного поля. |
void g_relation_insert (GRelation *relation, ...);
Вставляет запись в GRelation.
relation : |
GRelation. |
... : |
поля добавляемой записи. Должно соответствовать количеству полей в GRelation, и типу gpointer или gconstpointer. |
gboolean g_relation_exists (GRelation *relation, ...);
Возвращает TRUE
если запись с указанным значением существует в
GRelation.
Помните что значения сравниваются непосредственно, поэтому, например, две копии одной и той же строки не будут соответствовать.
gint g_relation_count (GRelation *relation, gconstpointer key, gint field);
Возвращает количество кортежей в GRelation которые имеют указанное значение в указанном поле.
relation : |
GRelation. |
key : |
значение для сравнения. |
field : |
поле в каждой записи для сопоставления. |
Возвращает : | количество соответствий. |
GTuples* g_relation_select (GRelation *relation, gconstpointer key, gint field);
Возвращает все кортежи которые имеют указанный ключ в указанном поле.
Используйте g_tuples_index()
для доступа к возвращаемым записям.
Возвращаемые записи должны быть освобождены с помощью
g_tuples_destroy()
.
relation : |
GRelation. |
key : |
значение для сравнения. |
field : |
поле в каждой записи для сопоставления. |
Возвращает : | записи (кортежи) которые соответствуют. |
gint g_relation_delete (GRelation *relation, gconstpointer key, gint field);
Удаляет любые записи из GRelation которые имеют указанный ключ в указанном поле.
relation : |
GRelation. |
key : |
значение для сравнения. |
field : |
поле каждой записи для сопоставления. |
Возвращает : | количество удалённых записей. |
void g_relation_destroy (GRelation *relation);
Уничтожает GRelation, освобождает всю распределённую память. Однако, она не освобождает память распределённую для кортежей данных, поэтому вы должны освободить их соответственно первыми.
relation : |
GRelation. |
void g_relation_print (GRelation *relation);
Выводит информацию о всех записях в GRelation, также как о индексах. Это для отладки.
relation : |
GRelation. |
typedef struct { guint len; } GTuples;
Структура GTuples используется для возвращаемых записей
(или кортежей) из GRelation
с помощью g_relation_select()
.
Она содержит только одно общедоступное поле - количество записей которые соответствуют.
Для доступа к соответствующим записям вы должны использовать g_tuples_index()
.
guint len ; |
количество записей которое соответствует. |
void g_tuples_destroy (GTuples *tuples);
Освобождает записи которые были возвращены g_relation_select()
.
Она должна всегда вызываться после g_relation_select()
когда вы закончите с записями.
Записи не удаляются из GRelation.
tuples : |
кортежи данных для освобождения. |
gpointer g_tuples_index (GTuples *tuples, gint index_, gint field);
Получает поля из записей возвращённых g_relation_select()
.
Она возвращает указанное поле записи по указанному индексу.
Возвращаемое значение не должно изменяться.
tuples : |
кортеж данных, возвращаемый g_relation_select() .
|
index_ : |
индекс записи. |
field : |
возвращаемое поле. |
Возвращает : | поле записи. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> enum GShellError; #define G_SHELL_ERROR gboolean g_shell_parse_argv (const gchar *command_line, gint *argcp, gchar ***argvp, GError **error); gchar* g_shell_quote (const gchar *unquoted_string); gchar* g_shell_unquote (const gchar *quoted_string, GError **error);
typedef enum { /* несоответствие или иначе искажённое квотирование */ G_SHELL_ERROR_BAD_QUOTING, /* анализируемая строка пустая */ G_SHELL_ERROR_EMPTY_STRING, G_SHELL_ERROR_FAILED } GShellError;
Коды ошибок возвращаемые функциями оболочки (shell functions).
#define G_SHELL_ERROR g_shell_error_quark ()
Домен ошибки для функций оболочки. Ошибки в этом домене из перечисления GShellError. Смотрите GError для информации о доменах ошибки.
gboolean g_shell_parse_argv (const gchar *command_line, gint *argcp, gchar ***argvp, GError **error);
Анализирует командную строку в одномерном массиве параметров, аналогичным с
shell способом, но без многих расширений выполняемых shell
(переменные, globs, операторы, расширение файлового имени,
и т.д. не поддерживаются). Результат определяется в том же самом стиля как
вы могли бы получить из UNIX98 /bin/sh, пока ввод не содержит не поддерживаемых
shell расширений. Если ввод содержит такие расширения, они помещаются буквально.
Возможные ошибки происходят из G_SHELL_ERROR
домена. Освобождается одномерный массив с помощью g_strfreev()
.
gchar* g_shell_quote (const gchar *unquoted_string);
Квотирует строку так чтобы оболочка (/bin/sh) интерпретировала её как unquoted_string
.
Если вы поместите имя файла в оболочку, например, вы должны сначала квотировать его с помощью этой функции.
Возвращаемое значение должно освобождаться с помощью g_free()
.
Используемый стиль квотирования не определён (могут использоваться или одинарные или двойные кавычки).
unquoted_string : |
строка литерал |
Возвращает : | квотированная строка |
gchar* g_shell_unquote (const gchar *quoted_string, GError **error);
Снимает квотирование строки как если бы это сделала оболочка (/bin/sh).
Обрабатывает кавычки только; если строка содержит file globs, арифметические операторы,
переменные, обратные кавычки, переназначения, или другие специальные shell особенности,
результат будет отличаться от реального результата который дала бы shell
(переменные, обратные кавычки, и т.д. будут помещены как литералы вместо интерпретации).
Эта функция гарантировано завершается успешно если применяется результат
g_shell_quote()
.
Если она завершилась неудачей, то возвращает NULL
и устанавливает ошибку. quoted_string
не должен фактически содержать кавычки или escaped текст;
g_shell_unquote()
просто проходит через строку
и снимает квотирование (unquotes/unescapes) как если бы это сделала shell-оболочка. Обрабатываются и двойные и одинарные кавычки,
а так же escapes включая завершающий символ новой строки. Возвращаемое значение должно освобождаться с помощью
g_free()
.
Возможные ошибки находятся в домене G_SHELL_ERROR.
Shell правила квотирования немного странные. Единственные кавычки сохраняют литеральную строку в точности. escape-последовательность не допускается; даже \' - если вы хотите иметь ' в квотированном тексте, вы можете сделать примерно так 'foo'\''bar'. Двойные кавычки позволяют $, `, ", \, и символ новой строки выделять обратным слэшем. Иначе двойные кавычки сохраняют всё буквально.
quoted_string : |
shell-quoted строка |
error : |
расположение для возвращаемой ошибки или NULL |
Возвращает : | unquoted строка |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> enum GMarkupError; #define G_MARKUP_ERROR enum GMarkupParseFlags; GMarkupParseContext; GMarkupParser; gchar* g_markup_escape_text (const gchar *text, gssize length); gchar* g_markup_printf_escaped (const char *format, ...); gchar* g_markup_vprintf_escaped (const char *format, va_list args); gboolean g_markup_parse_context_end_parse (GMarkupParseContext *context, GError **error); void g_markup_parse_context_free (GMarkupParseContext *context); void g_markup_parse_context_get_position (GMarkupParseContext *context, gint *line_number, gint *char_number); const gchar* g_markup_parse_context_get_element (GMarkupParseContext *context); GMarkupParseContext* g_markup_parse_context_new (const GMarkupParser *parser, GMarkupParseFlags flags, gpointer user_data, GDestroyNotify user_data_dnotify); gboolean g_markup_parse_context_parse (GMarkupParseContext *context, const gchar *text, gssize text_len, GError **error);
Анализатор "GMarkup" предназначен для анализа простого формата разметки подмножества XML. Это небольшой, эффективный, лёгкий в использовании анализатор. Он не должен использоваться если вы хотите интегрироваться с другими приложениями генерирующими полномасштабный XML. Однако, он очень полезен для файлов данных программы, конфигурационных файлов и т.д. где вы знаете что ваше приложение будет единственным пишущим в файл. Полномасштабные анализаторы XML должны быть в состоянии анализировать подмножество используемое GMarkup, поэтому вы сможете легко перейти к полномасштабному анализатору позже, если возникнет необходимость.
GMarkup не гарантирует сигнал об ошибке на любом недопустимом XML; анализатор может принять документ XML который не будет проанализирован. Однако, XML документы которые не в формате[4] рассматриваются как недопустимые документы GMarkup.
Упращение XML включает:
Допускается только кодировка UTF-8.
Нет объектов определяемых пользователем.
Инструкции выполнения, комментарии и doctype объявления "проходят" но никогда не интерпретируются.
Нет DTD или проверки правильности.
Форматированная разметка поддерживает:
Элементы
Атрибуты
5 стандартных объектов: & < > " '
Символьные ссылки
Разделы помеченные как CDATA
typedef enum { G_MARKUP_ERROR_BAD_UTF8, G_MARKUP_ERROR_EMPTY, G_MARKUP_ERROR_PARSE, /* These three are primarily intended for specific GMarkupParser * implementations to set. */ G_MARKUP_ERROR_UNKNOWN_ELEMENT, G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, G_MARKUP_ERROR_INVALID_CONTENT } GMarkupError;
Коды ошибок возвращаемые анализатором разметки.
G_MARKUP_ERROR_BAD_UTF8 |
анализируемый текст не был в допустимой UTF-8 |
G_MARKUP_ERROR_EMPTY |
документ пустой, или содержит только пробелы |
G_MARKUP_ERROR_PARSE |
документ был плохо сформирован |
G_MARKUP_ERROR_UNKNOWN_ELEMENT |
ошибка устанавливается функциями GMarkupParser; неизвестный элемент |
G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE |
ошибка устанавливаться функциями GMarkupParser; неизвестный атрибут |
G_MARKUP_ERROR_INVALID_CONTENT |
ошибка устанавливается функциями GMarkupParser; кое-что неправильно в содержимом документе, например недопустимое значение атрибута |
#define G_MARKUP_ERROR g_markup_error_quark ()
Домен ошибки для анализатора разметки. Ошибки в этом домене будут из перечисления GMarkupError. Смотрите GError для информации о доменах ошибки.
typedef enum { G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG = 1 << 0, G_MARKUP_TREAT_CDATA_AS_TEXT = 1 << 1 } GMarkupParseFlags;
Флаги которые влияют на поведение анализатора.
typedef struct _GMarkupParseContext GMarkupParseContext;
Контекст анализатора используемый для анализа потока байт которые вы ожидаете в содержимом размеченного текста.
Смотрите g_markup_parse_context_new()
,
GMarkupParser и так далее, для получения подробностей.
typedef struct { /* Вызов для открывающего тега <foo bar="baz"> */ void (*start_element) (GMarkupParseContext *context, const gchar *element_name, const gchar **attribute_names, const gchar **attribute_values, gpointer user_data, GError **error); /* Вызов для закрывающего тега </foo> */ void (*end_element) (GMarkupParseContext *context, const gchar *element_name, gpointer user_data, GError **error); /* Вызов для символьных данных */ /* текст не nul-завершённый */ void (*text) (GMarkupParseContext *context, const gchar *text, gsize text_len, gpointer user_data, GError **error); /* Вызов для строк которые должны быть повторно сохранены дословно * в том же самом месте, но не являются иначе истолкованными. * В настоящий момент это включает комментарии и исполняемые инструкции. */ /* текст не nul-завершённый. */ void (*passthrough) (GMarkupParseContext *context, const gchar *passthrough_text, gsize text_len, gpointer user_data, GError **error); /* Вызов ошибки, включая один из методов установленный в vtable. * GError не должна освобождаться. */ void (*error) (GMarkupParseContext *context, GError *error, gpointer user_data); } GMarkupParser;
Любые поля в GMarkupParser могут быть
NULL
, в этом случае они будут игнорироваться.
За исключением error
функции, любые callback-функции могут установить; особенно ошибки
G_MARKUP_ERROR_UNKNOWN_ELEMENT
, G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE
,
и G_MARKUP_ERROR_INVALID_CONTENT
предназначены для установки из этих callback-функций. Если вы установили ошибку из callback-функции,
g_markup_parse_context_parse()
сообщит что ошибка вернулась в вызывающую программу.
start_element () |
Callback-функция вызываемая при обнаружении элемента открывающего тега. |
end_element () |
Callback-функция вызываемая при обнаружении элемента закрывающего тега.
Помните что она также вызывается для пустых тегов, например <empty/> .
|
text () |
Callback-функция вызываемая при обнаружении некоторого текста (текст всегда находится внутри элементов).
Помните что текст элемента может распространяться на множество вызовов этой функции.
Если установлен флаг G_MARKUP_TREAT_CDATA_AS_TEXT ,
эта функция также вызывается для содержимого раздела помеченного как CDATA.
|
passthrough () |
Callback-функция вызываемая для комментариев, исполняемых инструкций
и doctype деклараций; если вы перезаписываете анализируемый документ,
текст записывается в туже самую позицию. Если установлен флаг
G_MARKUP_TREAT_CDATA_AS_TEXT , эта функция также вызывается для раздела помеченного как CDATA.
|
error () |
Callback-функция вызываемая когда происходит ошибка. |
gchar* g_markup_escape_text (const gchar *text, gssize length);
Ограничивает текст так чтобы анализатор разметки анализировал его дословно. Меньше чем, больше чем, амперсанд и т.д. заменяются соответствующими объектами. Эта функция обычно используется когда записываемый вывод файла должен быть проанализирован анализатором разметки.
Помните что эта функция не защищает пробелы и конец строк от обработки согласно правилам XML для нормализации концов строк и значений атрибутов.
text : |
некоторый текст в UTF-8 |
length : |
длина text в байтах, или -1 если текст nul-завершённый
|
Возвращает : | вновь распределённая строка с ограниченным текстом (escaped text) |
gchar* g_markup_printf_escaped (const char *format, ...);
Форматирует аргументы согласно format
,
ограничивает всю строку и символьные аргументы в стиле
g_markup_escape_text()
.
Это полезно когда вам нужно вставить буквенную строку в вывод в стиле XML, не беспокоясь о том, что строки могут иметь
собственную разметку.
const char *store = "Fortnum & Mason"; const char *item = "Tea"; char *output; output = g_markup_printf_escaped ("<purchase>" "<store>%s</store>" "<item>%s</item>" "</purchase>", store, item);
format : |
строка формата в стиле printf()
|
... : |
аргументы для вставки в строку формата |
Возвращает : | Вновь распределённый результат операции форматирвания.
Освобождается с помощью g_free() .
|
Начиная с версии 2.4
gchar* g_markup_vprintf_escaped (const char *format, va_list args);
Форматирует данные в args
согласно format
,
ограничивает все строки и символьные аргументы в стиле
g_markup_escape_text()
.
Смотрите g_markup_printf_escaped()
.
format : |
строка формата в стиле printf()
|
args : |
список аргументов переменных, подобных vprintf()
|
Возвращает : | Вновь распределённый результат операции фоматирования.
Освобождается с помощью g_free() .
|
Начиная с версии 2.4
gboolean g_markup_parse_context_end_parse (GMarkupParseContext *context, GError **error);
Сигнализирует GMarkupParseContext
что все данные были предоставлены в анализируемый контекст с помощью
g_markup_parse_context_parse()
.
Эта функция сообщает об ошибке если документ неполон, например если есть открытые элементы.
context : |
GMarkupParseContext |
error : |
расположение возвращаемой GError |
Возвращает : | TRUE при успешном выполнении,
FALSE если была установлена ошибка
|
void g_markup_parse_context_free (GMarkupParseContext *context);
Освобождает GMarkupParseContext. Может быть вызвана из функций GMarkupParser.
context : |
GMarkupParseContext |
void g_markup_parse_context_get_position (GMarkupParseContext *context, gint *line_number, gint *char_number);
Находит текущий номер строки и количество символов в этой строке. Предназначена для использования с сообщениями об ошибках; нет определённой семантики составляющей "текущий" номер строки, кроме "лучший номер который мы смогли придумать для сообщения об ошибке".
context : |
GMarkupParseContext |
line_number : |
расположение для возвращаемого номера строки,
или NULL
|
char_number : |
расположение для возвращаемого количества символов в строке,
или NULL
|
const gchar* g_markup_parse_context_get_element (GMarkupParseContext *context);
Находит имя текущего открытого элемента.
context : |
GMarkupParseContext |
Возвращает : | имя текущего открытого элемента, или NULL
|
Начиная с версии 2.2
GMarkupParseContext* g_markup_parse_context_new (const GMarkupParser *parser, GMarkupParseFlags flags, gpointer user_data, GDestroyNotify user_data_dnotify);
Создаёт новый анализатор контекста. Анализатор контекста используется для анализа размеченных документов. Вы можете направить любое количество документов в контекст, пока не произойдёт ошибка; как только происходит ошибка, анализатор контекста не сможет продолжать анализ текста (вы должны освободить его и создать новый анализатор контекста).
parser : |
GMarkupParser |
flags : |
один или больше GMarkupParseFlags |
user_data : |
пользовательские данные помещаемые в функции GMarkupParser |
user_data_dnotify : |
пользовательские данные разрушающего уведомления вызываемого когда анализатор контекста освобождён |
Возвращает : | новый GMarkupParseContext |
gboolean g_markup_parse_context_parse (GMarkupParseContext *context, const gchar *text, gssize text_len, GError **error);
Заполняет некоторые данные в GMarkupParseContext. Данные не должны быть в допустимой UTF-8; будет сообщено об ошибке если они будут недопустимы. Данные не должны быть полным документом; вы можете подавать документ в анализатор инкрементно, через множество вызовов этой функции. Обычно, поскольку вы получаете данные через сетевое подключение или файл, вы направляете каждую полученную часть данных в эту функцию, прерывая процесс если происходит ошибка. Как только происходит ошибка, никакие данные больше не могут быть направлены в GMarkupParseContext; все ошибки фатальны.
context : |
GMarkupParseContext |
text : |
часть анализируемого текста |
text_len : |
длина text в байтах
|
error : |
расположение для возвращаемой GError |
Возвращает : | FALSE если произошла ошибка,
TRUE при успешном выполнении
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Singly-Linked ListsSingly-Linked Lists — Связанные списки содержащие целочисленные значения или указатели на данные, с ограничением итерации только в одном направлении. |
#include <glib.h> GSList; GSList* g_slist_alloc (void); GSList* g_slist_append (GSList *list, gpointer data); GSList* g_slist_prepend (GSList *list, gpointer data); GSList* g_slist_insert (GSList *list, gpointer data, gint position); GSList* g_slist_insert_before (GSList *slist, GSList *sibling, gpointer data); GSList* g_slist_insert_sorted (GSList *list, gpointer data, GCompareFunc func); GSList* g_slist_remove (GSList *list, gconstpointer data); GSList* g_slist_remove_link (GSList *list, GSList *link_); GSList* g_slist_delete_link (GSList *list, GSList *link_); GSList* g_slist_remove_all (GSList *list, gconstpointer data); void g_slist_free (GSList *list); void g_slist_free_1 (GSList *list); #define g_slist_free1 guint g_slist_length (GSList *list); GSList* g_slist_copy (GSList *list); GSList* g_slist_reverse (GSList *list); GSList* g_slist_insert_sorted_with_data (GSList *list, gpointer data, GCompareDataFunc func, gpointer user_data); GSList* g_slist_sort (GSList *list, GCompareFunc compare_func); GSList* g_slist_sort_with_data (GSList *list, GCompareDataFunc compare_func, gpointer user_data); GSList* g_slist_concat (GSList *list1, GSList *list2); void g_slist_foreach (GSList *list, GFunc func, gpointer user_data); GSList* g_slist_last (GSList *list); #define g_slist_next (slist) GSList* g_slist_nth (GSList *list, guint n); gpointer g_slist_nth_data (GSList *list, guint n); GSList* g_slist_find (GSList *list, gconstpointer data); GSList* g_slist_find_custom (GSList *list, gconstpointer data, GCompareFunc func); gint g_slist_position (GSList *list, GSList *llink); gint g_slist_index (GSList *list, gconstpointer data); void g_slist_push_allocator (gpointer dummy); void g_slist_pop_allocator (void);
Структура GSList и связанные с ней функции обеспечивают стандартный односвязный список структур данных.
Каждый элемент в списке содержит часть данных, вместе с указателем который привязывает следующий элемент в списке. Используя этот указатель можно перемещаться по списку только в одном направлении (в отличие от двусвязных списков которые позволяют перемещение в двух направлениях).
Данные содержащиеся в каждом элементе могут быть либо целочисленными значениями, используя один из Type Conversion Macros, либо просто указателями на любой тип данных.
Список элементов распределяется slice allocator, что более эффективно чем индивидуальное распределение элементов.
Помните что функции GSList предполагают помещение указателя на первый элемент в списке. Функции которые вставляют элементы, возвращают новое начало списка, которое может иметь изменения.
Нет функции для создания GSList.
NULL
рассматривается как пустой список,
поэтому вы можете установить GSList* в
NULL
.
Для добавления элементов, используйте g_slist_append()
, g_slist_prepend()
, g_slist_insert()
и g_slist_insert_sorted()
.
Для удаления элементов, используйте g_slist_remove()
.
Для поиска элементов в списке используйте g_slist_last()
, g_slist_next()
,
g_slist_nth()
, g_slist_nth_data()
, g_slist_find()
и
g_slist_find_custom()
.
Для поиска номера элемента используйте g_slist_position()
и g_slist_index()
.
Для вызова функции для каждого элемента в списке используйте g_slist_foreach()
.
Для освобождения элементов списка, используйте g_slist_free()
.
typedef struct { gpointer data; GSList *next; } GSList;
Структура GSList используется для каждого элемента в односвязном списке.
gpointer data ; |
содержит элементы данных, которые могут указывать на любой тип данных, или любое целочисленное значение используя Type Conversion Macros. |
GSList *next ; |
содержит ссылку на следующий элемент в списке. |
GSList* g_slist_alloc (void);
Распределяет свободное пространство для одного элемента GSList.
Она вызывается с помощью g_slist_append()
, g_slist_prepend()
, g_slist_insert()
и
g_slist_insert_sorted()
функций
и очень редко используется самостоятельно.
Возвращает : | указатель на вновь распределённый элемент GSList. |
GSList* g_slist_append (GSList *list, gpointer data);
Добавляет новый элемент в конец списка.
Возвращает значение начала списка, которое может измениться, поэтому убедитесь что вы сохранили новое значение.
Помните что g_slist_append()
перебирает все элементы в списке для поиска конца, это не эффективно когда добавляется много элементов.
Основная идиома избежать неэффективности в прикреплении элементов сначала перевернутого списка и последующее
переворачивание обратно когда все элементы добавлены.
/* Помните что это инициализирует пустой список. */ GSList *list = NULL, *number_list = NULL; /* Это список строк. */ list = g_slist_append (list, "first"); list = g_slist_append (list, "second"); /* Это список целочисленных. */ number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
GSList* g_slist_prepend (GSList *list, gpointer data);
Добавляет новый элемент в начало списка.
Возвращает значение нового начала списка, которое может меняться, поэтому убедитесь что вы сохранили новое значение.
/* Помните что это инициализирует пустой список. */ GSList *list = NULL; list = g_slist_prepend (list, "last"); list = g_slist_prepend (list, "first");
GSList* g_slist_insert (GSList *list, gpointer data, gint position);
Вставляет новый элемент в данную позицию списка.
GSList* g_slist_insert_before (GSList *slist, GSList *sibling, gpointer data);
Вставляет узел перед sibling
содержащим data
.
Возвращает новый первый элемент списка.
slist : |
GSList. |
sibling : |
узел для вставки перед data .
|
data : |
данные помещаемые во вновь вставленный узел. |
Возвращает : | новый первый элемент списка. |
GSList* g_slist_insert_sorted (GSList *list, gpointer data, GCompareFunc func);
Вставляет новый элемент в список, используя полученную функцию сравнения для определения его позиции.
GSList* g_slist_remove (GSList *list, gconstpointer data);
Удаляет элемент из GSList. Если два элемента содержат одинаковые данные, удаляет только первый. Если нет элементов содержащих данные, GSList не изменяется.
GSList* g_slist_remove_link (GSList *list, GSList *link_);
Удаляет элемент из GSList, не освобождая элемент.
Ссылка на следующий элемент у удаляемого устанавливается в
NULL
,
так как он сам становится списком с единственным элементом.
GSList* g_slist_delete_link (GSList *list, GSList *link_);
Удаляет узел list
. Возвращает новый первый элемент списка.
list : |
GSList. |
link_ : |
узел для удаления. |
Возвращает : | новый первый элемент list .
|
GSList* g_slist_remove_all (GSList *list, gconstpointer data);
Удаляет все узлы списка с данными data
. Возвращает новый первый элемент списка.
В отличие от g_slist_remove()
которая удаляет только первый узел соответствующий полученным данным.
list : |
GSList. |
data : |
данные для удаления. |
Возвращает : | новый первый элемент list .
|
void g_slist_free (GSList *list);
Освобождает всю память используемую GSList. Освобождает элементы возвращаемые распределителем слайсов.
list : |
GSList. |
void g_slist_free_1 (GSList *list);
Освобождает один элемент GSList.
Её полезно использовать после g_slist_remove_link()
.
list : |
элемент GSList. |
#define g_slist_free1
Макрос который делает тоже самое что и g_slist_free_1()
.
Начиная с версии 2.10
GSList* g_slist_copy (GSList *list);
Копирует GSList.
Помните что это "пустая" копия. Если список элементов содержит указатели на данные, то указатели копируются, а фактические данные нет.
list : |
GSList. |
Возвращает : | копия list .
|
GSList* g_slist_insert_sorted_with_data (GSList *list, gpointer data, GCompareDataFunc func, gpointer user_data);
Вставляет новый элемент в список, использует полученную функцию сравнения для определения позиции.
list : |
GSList. |
data : |
данные для нового элемента. |
func : |
функция сравнивающая элементы в списке. Она должна возвращать число > 0 если первый параметр располагается после второго параметра при сортировке. |
user_data : |
данные помещаемые в функцию сравнения. |
Возвращает : | новое начало GSList.
Начиная с версии 2.10
|
GSList* g_slist_sort (GSList *list, GCompareFunc compare_func);
Сортирует GSList используя полученную функцию сравнения.
list : |
GSList. |
compare_func : |
функция сравнения используемая для сортировки GSList. Эта функция принимает данные из 2 элементов GSList и должна вернуть 0 если они равны, отрицательное значение если первый элемент располагается перед вторым, или положительное значение если первый элемент располагается после второго. |
Возвращает : | начало отсортированной GSList. |
GSList* g_slist_sort_with_data (GSList *list, GCompareDataFunc compare_func, gpointer user_data);
Подобна g_slist_sort()
,
но сравнивающая функция принимает аргумент пользовательских данных.
list : |
GSList |
compare_func : |
сравнивающая функция. |
user_data : |
данные помещаемые в функцию сравнения. |
Возвращает : | новый первый элемент списка. |
GSList* g_slist_concat (GSList *list1, GSList *list2);
Добавляет второй GSList в конец первого GSList. Помните что элементы второго GSList не копируются. Они используются непосредственно.
void g_slist_foreach (GSList *list, GFunc func, gpointer user_data);
Вызывает функцию для каждого элемента GSList.
list : |
GSList. |
func : |
функция вызываемая для каждого элемента данных. |
user_data : |
пользовательские данные для помещения в функцию. |
#define g_slist_next(slist)
Удобный макрос для получения следующего элемента в GSList.
GSList* g_slist_nth (GSList *list, guint n);
Определяет элемент в указанной позиции GSList.
gpointer g_slist_nth_data (GSList *list, guint n);
Определяет данные элемента в указанной позиции.
GSList* g_slist_find (GSList *list, gconstpointer data);
Находит элемент в GSList который содержит указанные данные.
GSList* g_slist_find_custom (GSList *list, gconstpointer data, GCompareFunc func);
Ищет элемент в GSList, используя полученную функцию для поиска желаемого элемента. Она перемещается по списку, вызов полученной функции должен вернуть 0 когда желаемый элемент найден. Функция принимает два gconstpointer аргумента, данные элемента GSList как первый аргумент и полученные пользовательские данные.
gint g_slist_position (GSList *list, GSList *llink);
Определяет позицию полученного элемента в GSList (начиная с 0).
gint g_slist_index (GSList *list, gconstpointer data);
Получает позицию элемента содержащего полученные данные (начиная с 0).
list : |
GSList. |
data : |
данные для поиска. |
Возвращает : | номер элемента содержащего данные, или -1 если данные не найдены. |
void g_slist_push_allocator (gpointer dummy);
g_slist_push_allocator
устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде.
Она ничего не делает, так как GSList конвертирован в
slice allocator
Устанавливает распределитель используемый для распределения элементов GSList.
Использует g_slist_pop_allocator()
для восстановления предыдущих распределений.
Помните что эта функция не доступна если GLib скомпилирована с опцией --disable-mem-pools
dummy : |
GAllocator используемый для распределения элементов GSList. |
void g_slist_pop_allocator (void);
g_slist_pop_allocator
устарела начиная с версии 2.10 и не должна использоваться во вновь создаваемом коде.
Она ничего не делает, так как GSList конвертирован в
slice allocator
Восстанавливает предыдущий GAllocator, используемый для распределения элементов GSList.
Помните что эта функция не доступна если GLib скомпилирована с опцией --disable-mem-pools
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> enum GSpawnError; #define G_SPAWN_ERROR enum GSpawnFlags; void (*GSpawnChildSetupFunc) (gpointer user_data); gboolean g_spawn_async_with_pipes (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, GPid *child_pid, gint *standard_input, gint *standard_output, gint *standard_error, GError **error); gboolean g_spawn_async (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, GPid *child_pid, GError **error); gboolean g_spawn_sync (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, gchar **standard_output, gchar **standard_error, gint *exit_status, GError **error); gboolean g_spawn_command_line_async (const gchar *command_line, GError **error); gboolean g_spawn_command_line_sync (const gchar *command_line, gchar **standard_output, gchar **standard_error, gint *exit_status, GError **error); void g_spawn_close_pid (GPid pid);
typedef enum { G_SPAWN_ERROR_FORK, /* fork failed due to lack of memory */ G_SPAWN_ERROR_READ, /* read or select on pipes failed */ G_SPAWN_ERROR_CHDIR, /* changing to working dir failed */ G_SPAWN_ERROR_ACCES, /* execv() returned EACCES */ G_SPAWN_ERROR_PERM, /* execv() returned EPERM */ G_SPAWN_ERROR_2BIG, /* execv() returned E2BIG */ G_SPAWN_ERROR_NOEXEC, /* execv() returned ENOEXEC */ G_SPAWN_ERROR_NAMETOOLONG, /* "" "" ENAMETOOLONG */ G_SPAWN_ERROR_NOENT, /* "" "" ENOENT */ G_SPAWN_ERROR_NOMEM, /* "" "" ENOMEM */ G_SPAWN_ERROR_NOTDIR, /* "" "" ENOTDIR */ G_SPAWN_ERROR_LOOP, /* "" "" ELOOP */ G_SPAWN_ERROR_TXTBUSY, /* "" "" ETXTBUSY */ G_SPAWN_ERROR_IO, /* "" "" EIO */ G_SPAWN_ERROR_NFILE, /* "" "" ENFILE */ G_SPAWN_ERROR_MFILE, /* "" "" EMFLE */ G_SPAWN_ERROR_INVAL, /* "" "" EINVAL */ G_SPAWN_ERROR_ISDIR, /* "" "" EISDIR */ G_SPAWN_ERROR_LIBBAD, /* "" "" ELIBBAD */ G_SPAWN_ERROR_FAILED /* other fatal failure, error->message * should explain */ } GSpawnError;
Коды ошибок возвращаемые при выполнении процессов.
#define G_SPAWN_ERROR g_spawn_error_quark ()
Домен ошибки для порождения процессов. Ошибки в этом домене будут из перечисления GSpawnError. Смотрите GError для информации о доменах ошибки.
typedef enum { G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 << 0, G_SPAWN_DO_NOT_REAP_CHILD = 1 << 1, /* look for argv[0] in the path i.e. use execvp() */ G_SPAWN_SEARCH_PATH = 1 << 2, /* Dump output to /dev/null */ G_SPAWN_STDOUT_TO_DEV_NULL = 1 << 3, G_SPAWN_STDERR_TO_DEV_NULL = 1 << 4, G_SPAWN_CHILD_INHERITS_STDIN = 1 << 5, G_SPAWN_FILE_AND_ARGV_ZERO = 1 << 6 } GSpawnFlags;
Флаги помещаемые в g_spawn_sync()
, g_spawn_async()
и g_spawn_async_with_pipes()
.
G_SPAWN_LEAVE_DESCRIPTORS_OPEN |
дескриптор открытого родительского файла будет унаследован дочерним процессом; иначе все дескрипторы кроме stdin/stdout/stderr
будут закрыты перед вызовом в дочернем процессе.
|
G_SPAWN_DO_NOT_REAP_CHILD |
дочерний процесс не будет автоматически получен; вы должны вызвать
или обработать SIGCHLD
самостоятельно, или дочерний процесс станет зомби.
|
G_SPAWN_SEARCH_PATH |
argv[0] не должен быть абсолютным путём,
он будет найден в пользовательском PATH .
|
G_SPAWN_STDOUT_TO_DEV_NULL |
стандартный вывод из дочернего процесса будет отменён, вместо направления в тоже расположение родительского стандартного вывода. |
G_SPAWN_STDERR_TO_DEV_NULL |
стандартные ошибки дочернего процесса будут отменены. |
G_SPAWN_CHILD_INHERITS_STDIN |
дочерний процесс унаследует стандартный ввод родителя
(по умолчанию, стандартный дочерний ввод прикреплён к /dev/null ).
|
G_SPAWN_FILE_AND_ARGV_ZERO |
первый элемент argv это выполняемый файл, остальные элементы являются фактически одномерным массивом
параметров для помещения в файл.
Обычно g_spawn_async_with_pipes()
использует argv[0] как файл для выполнения и передаёт все argv
в дочерний процесс.
|
void (*GSpawnChildSetupFunc) (gpointer user_data);
Определяет тип установочной функции помещаемой в
g_spawn_async()
,
g_spawn_sync()
и
g_spawn_async_with_pipes()
.
На POSIX платформах она вызывается в дочернем процессе после того как GLib выполнит все запланированные установки, но перед вызовом
.
В POSIX, действия принятые в этой функции, затронут таким образом только дочерний процесс, а не родителя.
exec()
В Windows функция вызывается в родительском процессе. Её полноценность в Windows таким образом сомнительна. В большинстве случаев выполнение функции установки в родительском процессе может иметь плохой эффект, вы должны быть очень осторожны когда портируете программы в Windows использующие дочерние функции установки.
user_data : |
пользовательские данные помещаемые в функцию. |
gboolean g_spawn_async_with_pipes (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, GPid *child_pid, gint *standard_input, gint *standard_output, gint *standard_error, GError **error);
Выполняет дочернюю программу асинхронно (ваша программа не будет блокирована для выхода из дочернего процесса).
Дочерняя программа определяет только аргументы которые должны быть предоставлены массивом
argv
. argv
должен быть NULL
-завершённым массивом строк,
для помещения как одномерный массив в дочерний процесс. Первая строка в argv
является названием программы для выполнения. По умолчанию имя программы должно быть полным путём;
переменная PATH
оболочки (shell) будет использоваться для поиска только если вы поместите флаг
G_SPAWN_SEARCH_PATH
.
Помните что в Windows все строки или одномерные строковые массивы аргументов
для этой функции и других g_spawn*() функций находятся в кодировке UTF-8, кодировка
имён файлов GLib. Unicode символы которые не являются частью системной кодовой страницы
которые передают в одномерном массиве аргументов будут корректно доступны в порождённой
программе только если она использует широкий символьный API для поиска в её командной строке.
Для C программ собранных с помощью инструментария Microsoft's достаточно создать программу имея
wmain()
вместо main()
.
wmain()
имеет широкий символ одномерного массива как параметр.
По крайней мере в настоящее время mingw не поддерживает wmain()
,
поэтому если вы используете mingw для разработки порождаемых программ, то должны вызвать
недокументированную функцию __wgetmainargs()
для получения
широкого символа аргументов одномерного массива и окружения. Смотрите gspawn-win32-helper.c в
GLib исходниках или init.c в исходниках программы mingw для определения прототипа этой функции.
Альтернативно вы можете найти широкий символ командной строки системного уровня Win32
помещаемый в порождённую программу используя функцию GetCommandLineW()
.
В Windows нижний уровень API создания дочерних процессов
не использует одномерный массив аргументов, но использует командную строку. Семейство функций библиотеки C
CreateProcess()
spawn*()
(которые вызывают в конечном счёте
g_spawn_async_with_pipes()
)
помещают элементы одномерного массива аргументов вместе в командную строку, а во время выполнения C код делает соответствующую реконструкцию
одномерного массива аргументов из командной строки для помещения в main()
. Осложнения возникают когда вы имеете
элементы одномерного массива аргументов которые содержат пробелы заключённые в двойные кавычки.
Функции spawn*()
не делают никакого квотирования или выхода, но с другой стороны код запуска закрывает кавычки
и не выходит чтобы позволить получить аргументы с включёнными пробелами или двойными кавычками. Для работы вокруг этой ассиметрии,
g_spawn_async_with_pipes()
выполнит
квотирование и прервёт элементы одномерного массива аргументов которые нужны ей перед вызовом функции C runtime
spawn()
.
envp
это
NULL
-завершённый массив строк, где каждая строка
имеет форму KEY=VALUE
. Это будет окружением дочернего процесса. Если
envp
это NULL
,
дочерний процесс наследует окружение его родителя.
flags
должен быть поразрядным ИЛИ любых флагов которые должны влиять на поведение функции.
G_SPAWN_DO_NOT_REAP_CHILD
означает что
дочерний процесс не будет автоматически выполнен; вы должны использовать источник GChildWatch для получения
уведомления об уничтожении дочернего процесса. В конечном счёте вы должны вызвать
g_spawn_close_pid()
в
child_pid
, для освобождения ресурсов связанных с дочерним процессом.
(В Unix, используется источник GChildWatch равноценный вызову waitpid()
или обрабатывается сигнал SIGCHLD
вручную. В Windows, вызов
g_spawn_close_pid()
равноценно вызову
CloseHandle()
для обработки возвращаемого child_pid
).
G_SPAWN_LEAVE_DESCRIPTORS_OPEN
означает что родительский дескриптор открытого файла будет унаследован дочерним процессом; иначе все дескрипторы кроме stdin/stdout/stder
будут закрыты перед вызовом exec()
в дочернем процессе.
G_SPAWN_SEARCH_PATH
означает что argv[0]
не должен быть абсолютным путём, он будет найден в пользовательской переменной
PATH
.
G_SPAWN_STDOUT_TO_DEV_NULL
означает что стандартный вывод дочернего процесса будет отменён, он будет направлен в тоже расположение что и стандартный вывод родительского
процесса. Если вы используете этот флаг, standard_output
должен быть NULL
.
G_SPAWN_STDERR_TO_DEV_NULL
означает что дочерний стандартный поток error будет отменён, вместо этого он будет направлен в тоже расположение что и стандартный поток
error родительского процесса. Если вы используете этот флаг, standard_error
должен быть
NULL
.
G_SPAWN_CHILD_INHERITS_STDIN
означает что дочерний процесс будет наследовать родительский стандартный поток ввода (input)
(по умолчанию, стандартный поток ввода дочернего процесса прикреплён к /dev/null).
Если вы используете этот флаг, standard_input
должен быть
NULL
.
G_SPAWN_FILE_AND_ARGV_ZERO
означает что первый элемент argv
является исполняемым файлом, в то время как остальные элементы
являются фактически одномерным массивом аргументов помещаемых в файл.
Обычно g_spawn_async_with_pipes()
использует argv
[0] как исполняемый файл, и помещает остальные
argv
в дочерний процесс.
child_setup
и user_data
являются функцией и пользовательскими данными. На POSIX платформах,
функция вызывается в дочернем процессе после выполнения GLib всех запланированных установок
(включая создание каналов, закрытие дескрипторов файлов, etc.) но перед вызовом
exec()
. Таким образом, child_setup
вызывается перед вызовом exec()
в дочернем процессе. Очевидно что действия принятые в этой функции затронут
только дочерний процесс, но не родителя. В Windows, нет разделения fork()
и exec()
функциональности. Дочерний процесс создаётся и выполняется единственным API вызовом, CreateProcess()
.
child_setup
вызывается в родительском процессе как раз перед созданием дочернего процесса.
Вы должны внимательно рассмотреть то что вы делаете в child_setup
если вы планируете переносить свою программу в Windows.
Если не-NULL
, child_pid
будет заполнен в Unix с помощью ID дочернего процесса. Вы можете использовать ID процесса для отправки сигналов дочернему процессу,
или для waitpid()
если вы определили флаг
G_SPAWN_DO_NOT_REAP_CHILD
.
В Windows, child_pid
будет заполнен с помощью обработки дочернего процесса только если вы определили
флаг G_SPAWN_DO_NOT_REAP_CHILD
.
Вы сможете тогда обратиться к дочернему процессу используя Win32 API, например ожидать его завершения с помощью функций
WaitFor*()
, или например проверить его код завершения с помощью
GetExitCodeProcess()
. Вы должны завершить обработку с помощью CloseHandle()
или g_spawn_close_pid()
когда вы больше не нуждаетесь в ней.
Если не-NULL
, standard_input
, standard_output
, standard_error
расположения будут заполнены дескрипторами файлов для записи в стандартном потоке ввода дочерних процессов или для чтения в стандартном потоке вывода или для стандартного потока error.
Вызывающий g_spawn_async_with_pipes()
должен закрыть этот дескриптор файла когда он больше не нужен. Если эти параметры равны NULL
, соответственно канал не будет создан.
Если standard_input
равен NULL, стандартный ввод дочернего процесса прикреплён к /dev/null
пока не установлен G_SPAWN_CHILD_INHERITS_STDIN
.
Если standard_error
равен NULL, стандартный поток error дочернего процесса направлен в тоже расположение что и стандартный поток error родительского процесса пока не установлен G_SPAWN_STDERR_TO_DEV_NULL
.
Если standard_output
равен NULL, стандартный вывод дочернего процесса направлен в то же расположение что и стандартный вывод родительского процесса пока не установлен G_SPAWN_STDOUT_TO_DEV_NULL
.
error
может быть NULL
для игнорирования ошибок, или не-NULL
для сообщения об ошибках.
Если error установлен, функция возвращает FALSE
. Об ошибках сообщается даже если они происходят в дочернем процессе
(например если исполняемый файл в argv[0]
небыл найден). Обычно поле message
возвращаемой ошибки должно отображаться пользователям. Возможные ошибки указаны в домене G_SPAWN_ERROR.
Если произошла ошибка, child_pid
, standard_input
, standard_output
,
и standard_error
не будут заполнены допустимыми значениями.
Если child_pid
не-NULL
и не происходит ошибки то возвращаемый pid должен быть закрыт с помощью g_spawn_close_pid()
.
working_directory : |
текущий рабочий каталог дочернего процесса, или NULL
для наследования родительского, в кодировке имён файлов GLib
|
argv : |
одномерный массив аргументов дочернего процесса, в кодировке имён файлов GLib |
envp : |
окружение дочернего процесса, или NULL
для наследования родительского, в кодировке имён файлов GLib
|
flags : |
флаги из GSpawnFlags |
child_setup : |
функция запускаемая в дочернем процессе перед exec()
|
user_data : |
пользовательские данные для child_setup
|
child_pid : |
расположение для возвращаемого ID дочернего процесса, или
NULL
|
standard_input : |
расположение возвращаемого дескриптора файла для записи стандартным потоком stdin дочернего процесса,
или NULL
|
standard_output : |
расположение возвращаемого дескриптора файла для чтения стандартным потоком stdout дочернего процесса,
или NULL
|
standard_error : |
расположение возвращаемого дескриптора файла для чтения стандартным потоком stderr дочернего процесса,
или NULL
|
error : |
расположение для возвращаемой ошибки |
Возвращает : | TRUE при успешном выполнении,
FALSE если была установлена ошибка
|
gboolean g_spawn_async (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, GPid *child_pid, GError **error);
Смотрите g_spawn_async_with_pipes()
для полного описания; эта функция просто вызывает g_spawn_async_with_pipes()
без всяких каналов.
working_directory : |
текущий рабочий каталог дочернего процесса, или NULL
для наследования родительского
|
argv : |
одномерный массив аргументов дочернего процесса |
envp : |
окружение дочернего процесса, или NULL
для наследования родительского
|
flags : |
флаги из GSpawnFlags |
child_setup : |
функция для запуска в дочернем процессе перед exec()
|
user_data : |
пользовательские данные для child_setup
|
child_pid : |
расположение для возвращаемого ID дочернего процесса, или NULL
|
error : |
расположение для возвращаемой ошибки |
Возвращает : | TRUE при успешном выполнении,
FALSE если установлена ошибка
|
gboolean g_spawn_sync (const gchar *working_directory, gchar **argv, gchar **envp, GSpawnFlags flags, GSpawnChildSetupFunc child_setup, gpointer user_data, gchar **standard_output, gchar **standard_error, gint *exit_status, GError **error);
Выполняет дочерний процесс синхронно (ждёт выхода из дочернего процесса перед возвращением).
Весь вывод из дочернего процесса сохраняется в standard_output
и standard_error
,
если эти параметры не-NULL
. Если exit_status
не-NULL
, статус выхода из дочернего процесса сохраняется как если бы было возвращено waitpid()
; стандартные UNIX макросы такие как WIFEXITED()
и WEXITSTATUS()
должны использоваться для оценки состояния выхода. Если произошла ошибка, нет данных возвращённых в standard_output
, standard_error
, или exit_status
.
Эта функция вызывает g_spawn_async_with_pipes()
внутренне; смотрите полные детали в других параметрах и детали как эти функции работают в Windows.
working_directory : |
текущий рабочий каталог дочернего процесса, или NULL
для наследования родительского
|
argv : |
одномерный массив аргументов дочернего процесса |
envp : |
окружение дочернего процесса, или NULL
для наследования родительского
|
flags : |
флаги из GSpawnFlags |
child_setup : |
функция для запуска в дочернем процессе перед exec()
|
user_data : |
пользовательские данные для child_setup
|
standard_output : |
расположение возвращаемого дочернего потока output |
standard_error : |
расположение возвращаемых дочерних сообщений об ошибках |
exit_status : |
расположение для возвращаемого статуса выхода дочернего процесса, который возвращается из waitpid()
|
error : |
расположение для возвращаемой ошибки |
Возвращает : | TRUE при успешном выполнении,
FALSE если была установлена ошибка.
|
gboolean g_spawn_command_line_async (const gchar *command_line, GError **error);
Простая версия g_spawn_async()
которая анализирует командную строку с помощью
g_shell_parse_argv()
и направляет в g_spawn_async()
.
Выполняет командную строку в фоновом режиме. В отличие от
g_spawn_async()
, флаг
G_SPAWN_SEARCH_PATH
включен,
другие флаги нет.
Помните что G_SPAWN_SEARCH_PATH
может иметь безопасные включения, поэтому рассмотрите непосредственное использование
g_spawn_async()
если возможно.
Возможные ошибки указаны в g_shell_parse_argv()
и g_spawn_async()
.
Встречаются те же проблемы в Windows применении, что и для g_spawn_command_line_sync()
.
gboolean g_spawn_command_line_sync (const gchar *command_line, gchar **standard_output, gchar **standard_error, gint *exit_status, GError **error);
Простая версия g_spawn_sync()
с удалёнными мало-используемыми параметрами, принимает командную строку вместо одномерного массива аргументов.
Смотрите g_spawn_sync()
для изучения всех деталей.
command_line
будет анализироваться с помощью
g_shell_parse_argv()
.
В отличие от g_spawn_sync()
, флаг
G_SPAWN_SEARCH_PATH
включен. Помните что G_SPAWN_SEARCH_PATH
может иметь безопасные включения, поэтому рассмотрите непосредственное использование
g_spawn_sync()
если возможно.
Возможные ошибки происходят из g_spawn_sync()
и
from g_shell_parse_argv()
.
Если exit_status
не-NULL
, статус выхода дочернего процесса сохраняется как возвращаемый waitpid()
;
стандартные UNIX макросы WIFEXITED()
и WEXITSTATUS()
должны использоваться для оценки статуса выхода.
В Windows, пожалуйста помните включение g_shell_parse_argv()
анализирующую command_line
. Анализ выполняется согласно правилам оболочки Unix,
а не правил командного интерпретатора Windows.
Пробел является разделителем, и backslashes является специальным. Поэтому вы не можете прост поместить
command_line
содержащую канонический Windows путь, как "c:\\program files\\app\\app.exe",
поскольку backslashes будут подавлены, и пробелы будут действовать как разделители. Вам нужно заключать такие пути в одиночные кавычки,
например "'c:\\program files\\app\\app.exe' 'e:\\folder\\argument.txt'".
command_line : |
командная строка |
standard_output : |
расположение возвращаемого дочернего потока output |
standard_error : |
расположение возвращаемых дочерних ошибок |
exit_status : |
расположение для возвращаемого статуса выхода дочернего процесса, который возвращает waitpid()
|
error : |
расположение для возвращаемых ошибок |
Возвращает : | TRUE при успешном выполнении,
FALSE если установлена ошибка
|
void g_spawn_close_pid (GPid pid);
На некоторых платформах, особенно WIN32, тип GPid
представляет ресурс который должен быть закрыт для предотвращения утечки ресурсов.
g_spawn_close_pid()
предназначена для этих целей. Она должна использоваться на всех платформах, даже при том что она ничего не делает в UNIX.
pid : |
идентификатор процесса для закрытия |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> #define G_OS_WIN32 #define G_OS_BEOS #define G_OS_UNIX #define G_DIR_SEPARATOR #define G_DIR_SEPARATOR_S #define G_IS_DIR_SEPARATOR (c) #define G_SEARCHPATH_SEPARATOR #define G_SEARCHPATH_SEPARATOR_S #define TRUE #define FALSE #define NULL #define MIN (a, b) #define MAX (a, b) #define ABS (a) #define CLAMP (x, low, high) #define G_STRUCT_MEMBER (member_type, struct_p, struct_offset) #define G_STRUCT_MEMBER_P (struct_p, struct_offset) #define G_STRUCT_OFFSET (struct_type, member) #define G_MEM_ALIGN #define G_CONST_RETURN
#define G_OS_WIN32
Этот макрос определяется только в Windows. Поэтому вы можете группировать Windows-специфичный код в "#ifdef G_OS_WIN32".
#define G_OS_BEOS
Этот макрос определяется только в BeOS. Поэтому вы можете группировать BeOS-специфичный код в "#ifdef G_OS_BEOS".
#define G_OS_UNIX
Этот макрос определяется только в UNIX. Поэтому вы можете группировать UNIX-специфичный код в #ifdef G_OS_UNIX".
#define G_DIR_SEPARATOR
Символ разделения каталогов. Это '/' в UNIX и '\' в Windows.
#define G_DIR_SEPARATOR_S
Разделитель каталогов как строка. Это "/" в UNIX и "\" в Windows.
#define G_IS_DIR_SEPARATOR(c)
Проверяет является ли символ разделителем каталогов.
Возвращает
TRUE
для '/' в UNIX
и для '\' или '/' в Windows.
c : |
символ |
Начиная с версии 2.6
#define G_SEARCHPATH_SEPARATOR
Символ разделитель пути поиска. Это ':' в UNIX и ';' в Windows.
#define G_SEARCHPATH_SEPARATOR_S
Строка разделитель в пути поиска. Это ":" в UNIX и ";" в Windows.
#define MIN(a, b) (((a) < (b)) ? (a) : (b))
Находит меньшее из a
и b
.
a : |
числовое значение. |
b : |
числовое значение. |
Возвращает : | наименьшее из a и b .
|
#define MAX(a, b) (((a) > (b)) ? (a) : (b))
Находит наибольшее из a
и b
.
a : |
числовое значение. |
b : |
числовое значение. |
Возвращает : | наибольшее из a и b .
|
#define ABS(a) (((a) < 0) ? -(a) : (a))
Расчитывает абсолютное значение a
.
Абсолютное значение это простое число без отрицательного знака.
Например,
ABS(-10) равно 10.
ABS(10) также равно 10.
a : |
числовое значение. |
Возвращает : | абсолютное значение a .
|
#define CLAMP(x, low, high) (((x) > (high)) ? (high) : (((x) < (low)) ? (low) : (x)))
Находит x
между установленными лимитами low
и high
.
Например,
CLAMP(5, 10, 15) это 10.
CLAMP(15, 5, 10) это 10.
CLAMP(20, 15, 25) это 20.
x : |
промежуточное числовое значение. |
low : |
допустимое минимальное значение. |
high : |
допустимое максимальное значение. |
Возвращает : | значение x заключенное между диапазоном low и high .
|
#define G_STRUCT_MEMBER(member_type, struct_p, struct_offset)
Возвращает элемент структуры в полученном смещении, используя полученный тип.
member_type : |
типовое поле структуры. |
struct_p : |
указатель в структуре. |
struct_offset : |
смещение поля от начала структуры, в байтах. |
Возвращает : | элемент структуры. |
#define G_STRUCT_MEMBER_P(struct_p, struct_offset)
Возвращает указатель без типа для полученного смещения структуры.
struct_p : |
указатель в структуре. |
struct_offset : |
смещение от начала структуры, в байтах. |
Возвращает : | указатель без типа struct_p плюс struct_offset байт.
|
#define G_STRUCT_OFFSET(struct_type, member)
Возвращает смещение в байтах элемента структуры.
struct_type : |
тип структуры, например GtkWidget. |
member : |
поле структуры, например window .
|
Возвращает : | смещение элемента от начала struct_type .
|
#define G_MEM_ALIGN
Указывает количество байт по которым будет распределена память в текущей платформе.
#define G_CONST_RETURN
Если G_DISABLE_CONST_RETURNS
определён, этот макрос не выполняется.
По умолчанию, макрос расширяется до const
. Макрос
должен использоваться для помещения const
в функции
возвращающие значения которые не должны изменяться. В основном этот макрос
позволяет использовать включение const
для возвращаемых
константных строк по умолчанию, пока программист не отключит это.
Этот макрос должен использоваться только для возвращаемых значений и для
out параметров, он не действует для
in параметров.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GStringChunk; GStringChunk* g_string_chunk_new (gsize size); gchar* g_string_chunk_insert (GStringChunk *chunk, const gchar *string); gchar* g_string_chunk_insert_const (GStringChunk *chunk, const gchar *string); gchar* g_string_chunk_insert_len (GStringChunk *chunk, const gchar *string, gssize len); void g_string_chunk_free (GStringChunk *chunk);
Строковый блок используется для хранения групп строк. Память распределяется блоками и когда строки добавляются в GStringChunk они копируются в следующую свободную позицию в блоке. Когда блок заполняется распределяется следующий блок.
Когда сохраняется большое количество строк, строковые блоки более эффективны чем использование
g_strdup()
,
так как необходимо меньше вызовов
,
и при распределении тратится меньше памяти на накладные расходы.
malloc()
Добавление строк с помощью g_string_chunk_insert_const()
, также позволяет удалять дубликаты.
Для создания новой GStringChunk
используется g_string_chunk_new()
.
Для добавления строк в GStringChunk
используется g_string_chunk_insert()
.
Для добавления строк в GStringChunk,
но без дубликатов уже существующих строк в GStringChunk,
используется g_string_chunk_insert_const()
.
Для освобождения элементов GStringChunk
используется g_string_chunk_free()
.
Она не позволяет освобождать отдельные строки.
typedef struct _GStringChunk GStringChunk;
Непрозрачная структура данных представляющая строковый блок (String Chunks). Она должна использоваться только при помощи следующих функций.
GStringChunk* g_string_chunk_new (gsize size);
Создаёт новый GStringChunk.
size : |
размер по умолчанию блока памяти который распределён для хранения строк. Если определённая строка больше чем этот размер по умолчанию, то для неё будет распределён блок большего размера. |
Возвращает : | новый GStringChunk. |
gchar* g_string_chunk_insert (GStringChunk *chunk, const gchar *string);
Добавляет копию string
в GStringChunk.
Возвращает указатель на новую копию строки в GStringChunk.
Символы в строке могут быть изменены, если необходимо, однако вы не должны изменять ничего после завершения строки.
В отличие g_string_chunk_insert_const()
,
эта функция не контролирует дубликаты.
А также строки добавленные с помощью g_string_chunk_insert()
не будут найдены с помощью g_string_chunk_insert_const()
при поиске дубликатов.
chunk : |
GStringChunk. |
string : |
строка для добавления. |
Возвращает : | указатель на копию string внутри
GStringChunk.
|
gchar* g_string_chunk_insert_const (GStringChunk *chunk, const gchar *string);
Добавляет копию string
в GStringChunk, если такая же строка уже не добавлена в GStringChunk с помощью g_string_chunk_insert_const()
.
Эта функция полезна если вам нужно копировать большое количество строк но не нужно тратить пространство хранилища под дубликаты. Но вы должны помнить что здесь могут быть указатели на туже строку и поэтому любые изменения в строках должны выполняться очень осторожно.
Помните что g_string_chunk_insert_const()
не будет возвращать указатель на строку добавленную с помощью
g_string_chunk_insert()
,
даже если они соответствуют.
chunk : |
GStringChunk. |
string : |
строка для добавления. |
Возвращает : | указатель на новую или существующую копию string внутри
GStringChunk.
|
gchar* g_string_chunk_insert_len (GStringChunk *chunk, const gchar *string, gssize len);
Добавляет копию первых len
байт string
в GStringChunk.
Копия nul-завершённая.
Символы в строке могут изменяться, если необходимо, однако вы не должны делать никаких изменений после завершения строки.
chunk : |
GStringChunk |
string : |
байты для вставки |
len : |
количество байт string для вставки,
или -1 для вставки nul-завершённой строки.
|
Возвращает : | указатель на копию string внутри
GStringChunk
|
Начиная с версии 2.4
void g_string_chunk_free (GStringChunk *chunk);
Освобождает всю память распределённую GStringChunk.
После вызова g_string_chunk_free()
запрещается
доступ к любым строкам которые содержались внутри.
chunk : |
GStringChunk. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> #include <glib/gprintf.h> gchar* g_strdup (const gchar *str); gchar* g_strndup (const gchar *str, gsize n); gchar** g_strdupv (gchar **str_array); gchar* g_strnfill (gsize length, gchar fill_char); gchar* g_stpcpy (gchar *dest, const char *src); gchar* g_strstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle); gchar* g_strrstr (const gchar *haystack, const gchar *needle); gchar* g_strrstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle); gboolean g_str_has_prefix (const gchar *str, const gchar *prefix); gboolean g_str_has_suffix (const gchar *str, const gchar *suffix); gsize g_strlcpy (gchar *dest, const gchar *src, gsize dest_size); gsize g_strlcat (gchar *dest, const gchar *src, gsize dest_size); gchar* g_strdup_printf (const gchar *format, ...); gchar* g_strdup_vprintf (const gchar *format, va_list args); gint g_printf (gchar const *format, ...); gint g_vprintf (gchar const *format, va_list args); gint g_fprintf (FILE *file, gchar const *format, ...); gint g_vfprintf (FILE *file, gchar const *format, va_list args); gint g_sprintf (gchar *string, gchar const *format, ...); gint g_vsprintf (gchar *string, gchar const *format, va_list args); gint g_snprintf (gchar *string, gulong n, gchar const *format, ...); gint g_vsnprintf (gchar *string, gulong n, gchar const *format, va_list args); gint g_vasprintf (gchar **string, gchar const *format, va_list args); gsize g_printf_string_upper_bound (const gchar *format, va_list args); gboolean g_ascii_isalnum (gchar c); gboolean g_ascii_isalpha (gchar c); gboolean g_ascii_iscntrl (gchar c); gboolean g_ascii_isdigit (gchar c); gboolean g_ascii_isgraph (gchar c); gboolean g_ascii_islower (gchar c); gboolean g_ascii_isprint (gchar c); gboolean g_ascii_ispunct (gchar c); gboolean g_ascii_isspace (gchar c); gboolean g_ascii_isupper (gchar c); gboolean g_ascii_isxdigit (gchar c); gint g_ascii_digit_value (gchar c); gint g_ascii_xdigit_value (gchar c); gint g_ascii_strcasecmp (const gchar *s1, const gchar *s2); gint g_ascii_strncasecmp (const gchar *s1, const gchar *s2, gsize n); gchar* g_ascii_strup (const gchar *str, gssize len); gchar* g_ascii_strdown (const gchar *str, gssize len); gchar g_ascii_tolower (gchar c); gchar g_ascii_toupper (gchar c); GString* g_string_ascii_up (GString *string); GString* g_string_ascii_down (GString *string); gchar* g_strup (gchar *string); gchar* g_strdown (gchar *string); gint g_strcasecmp (const gchar *s1, const gchar *s2); gint g_strncasecmp (const gchar *s1, const gchar *s2, guint n); gchar* g_strreverse (gchar *string); gint64 g_ascii_strtoll (const gchar *nptr, gchar **endptr, guint base); guint64 g_ascii_strtoull (const gchar *nptr, gchar **endptr, guint base); #define G_ASCII_DTOSTR_BUF_SIZE gdouble g_ascii_strtod (const gchar *nptr, gchar **endptr); gchar* g_ascii_dtostr (gchar *buffer, gint buf_len, gdouble d); gchar* g_ascii_formatd (gchar *buffer, gint buf_len, const gchar *format, gdouble d); gdouble g_strtod (const gchar *nptr, gchar **endptr); gchar* g_strchug (gchar *string); gchar* g_strchomp (gchar *string); #define g_strstrip ( string ) gchar* g_strdelimit (gchar *string, const gchar *delimiters, gchar new_delimiter); #define G_STR_DELIMITERS gchar* g_strescape (const gchar *source, const gchar *exceptions); gchar* g_strcompress (const gchar *source); gchar* g_strcanon (gchar *string, const gchar *valid_chars, gchar substitutor); gchar** g_strsplit (const gchar *string, const gchar *delimiter, gint max_tokens); gchar** g_strsplit_set (const gchar *string, const gchar *delimiters, gint max_tokens); void g_strfreev (gchar **str_array); gchar* g_strconcat (const gchar *string1, ...); gchar* g_strjoin (const gchar *separator, ...); gchar* g_strjoinv (const gchar *separator, gchar **str_array); guint g_strv_length (gchar **str_array); const gchar* g_strerror (gint errnum); const gchar* g_strsignal (gint signum);
Этот раздел описывает множество сервисных функций для создания, дублирования и манипулирования строками.
Помните что функции g_printf()
, g_fprintf()
, g_sprintf()
, g_snprintf()
,
g_vprintf()
, g_vfprintf()
, g_vsprintf()
и g_vsnprintf()
объявлены в заголовочном файле gprintf.h
который не включён в glib.h
(иначе использование glib.h
привлекло бы stdio.h
), поэтому вы должны явно включить <glib/gprintf.h>
чтобы использовать GLib printf()
функции.
Во время использования printf()
функций для строк формата UTF-8,
обратите внимание что точность параметра %Ns
интерпретируется в
количество байт, а не символов для печати.
В добавок к этому, реализация GNU libc printf()
функций имеет "особеность"
прверять что полученная строка для %Ns
параметра состоит из целого числа символов в текущей кодировке. Поэтому если вы не уверены что всегда используется UTF-8 locale или знаете что ваш текст находится в ASCII, избегайте использования %Ns
.
Если вы намереваетесь отформатировать строки в несколько столбцов, то
%Ns
не подходит для этого в любом случае, так как он не принимает во внимание широкие символы (смотрите g_unichar_iswide()
).
gchar* g_strdup (const gchar *str);
Дублирует строку.
Если параметр str
равен NULL
возвращает NULL
.
Возвращаемая строка должна освобождаться когда больше не нужна.
str : |
строка для дублирования. |
Возвращает : | вновь распределённая копия str .
|
gchar* g_strndup (const gchar *str, gsize n);
Дублирует первые n
символов строки, возвращает вновь распределённый буфер длиной n
+ 1 символ который всегда nul-terminated.
Если str
меньше чем n
символов, буфер дополняется нулями (nuls).
Если str
равен NULL
возвращается NULL
.
Возвращаемая строка должна освобождаться когда больше не нужна.
str : |
строка для частичного дублирования. |
n : |
максимальное количество символов для копирования из строки str .
|
Возвращает : | вновь распределённый буфер содержащий первые n символов строки str ,
nul-завершённый.
|
gchar** g_strdupv (gchar **str_array);
Копирует NULL
-завершённый массив строк. Новый массив освобождается сначала освобождая каждую строку, затем непосредственно сам массив.
g_strfreev()
делает это за вас. Если вызвать с значением NULL
, g_strdupv()
просто вернёт NULL
.
gchar* g_strnfill (gsize length, gchar fill_char);
Создаёт новую строку длинной length
символов на всю длину заполненную символами fill_char
.
Возвращаемая строка должна освобождаться когда больше не нужна.
length : |
длина новой строки. |
fill_char : |
символ для заполнения строки. |
Возвращает : | вновь распределённая строка заполненная fill_char .
|
gchar* g_stpcpy (gchar *dest, const char *src);
Копирует nul-завершённую строку в буфер dest, включая замыкающий nul и возвращает указатель на завершающий nul байт. Это полезно при соединении нескольких строк вместе без необходимости неоднократного сканирования конца.
dest : |
буфер назначения. |
src : |
исходная строка. |
Возвращает : | указатель на завершающий нулевой байт. |
gchar* g_strstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle);
Ищет строку haystack
до первого появления строки needle
, ограничивая длину поиска значением haystack_len
.
haystack : |
строка. |
haystack_len : |
максимальная длина haystack .
|
needle : |
строка для поиска. |
Возвращает : | указатель на найденное совпадение, или
NULL если ничего не найдено.
|
gchar* g_strrstr (const gchar *haystack, const gchar *needle);
Ищет строку haystack
до последнего совпадения строки needle
.
haystack : |
nul-завершённая строка. |
needle : |
nul-завершённая строка для поиска. |
Возвращает : | указатель на найденное совпадение, или
NULL если ничего не найдено.
|
gchar* g_strrstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle);
Ищет строку haystack
до последнего совпадения строки
needle
, ограничивая длину поиска значением
haystack_len
.
haystack : |
nul-завершённая строка. |
haystack_len : |
максимальная длина haystack .
|
needle : |
nul-завершённая строка для поиска. |
Возвращает : | указатель на найденное совпадение, или
NULL если ничего не найдено.
|
gboolean g_str_has_prefix (const gchar *str, const gchar *prefix);
Определяет начинается ли строка str
с префикса prefix
.
str : |
nul-завершённая строка. |
prefix : |
nul-завершённый префикс для поиска. |
Возвращает : | TRUE если str начинается с prefix , иначе FALSE .
|
Начиная с версии 2.2
gboolean g_str_has_suffix (const gchar *str, const gchar *suffix);
Определяет заканчивается ли строка str
суффиксом suffix
.
str : |
nul-завершённая строка. |
suffix : |
nul-завершённый суффикс для поиска. |
Возвращает : | TRUE если str заканчивается suffix , иначе FALSE .
|
Начиная с версии 2.2
gsize g_strlcpy (gchar *dest, const gchar *src, gsize dest_size);
Переносимая оболочка для вызова strlcpy()
на системах которые имеют эту функцию она просто вызывает её, а на системах где нет strlcpy()
эмулирует её. Копирует src
в dest
; dest
гарантированно будет
nul-завершённой; src
должна быть nul-terminated; dest_size
является размером буфера, а не количеством символов для копирования. Предостережение: strlcpy()
более безопасна чем
strcpy()
или strncpy()
, но если вы действительно хотите избежать проблем, то лучше используйте g_strdup()
.
dest : |
буфер назначения |
src : |
исходный буфер |
dest_size : |
длина dest в байтах
|
Возвращает : | длина src
|
gsize g_strlcat (gchar *dest, const gchar *src, gsize dest_size);
Переносимая оболочка функции strlcat()
, на системах где нет этой функции она её эмулирует.
Добавляет nul-завершённую строку src
в dest
, гарантирует nul-заврершённую dest
. Полный размер dest
не превышает
dest_size
. Предостережение: это возможно более безопасная альтернатива для strcat()
или
strncat()
, но для действительно безопасного соединения лучше использовать g_strconcat()
.
dest : |
буфер назначения, уже содержащий одну nul-завершённую строку |
src : |
исходный буфер |
dest_size : |
длина буфера dest в байтах (не размер существующей строки внутри dest )
|
Возвращает : | длина src плюс начальная длина строки в dest
|
gchar* g_strdup_printf (const gchar *format, ...);
Аналогична для стандартной C функции sprintf()
но безопасней,
так как она рассчитывает максимальное требуемое пространство и распределяет память содержащую результат.
Возвращаемая строка должна освобождаться когда больше не нужна.
format : |
стандартная строка формата printf() , но помните
опасность строковой точности.
|
... : |
параметры вставляемые в форматируемую строку. |
Возвращает : | вновь распределённая строка содержащая результат. |
gchar* g_strdup_vprintf (const gchar *format, va_list args);
Похожа на стандартную C функцию vsprintf()
но безопасней,
так как она рассчитывает максимальное требуемое свободное пространство и распределяет память содержащую результат.
Возвращаемая строка должна освобождаться когда больше не нужна.
Смотрите также g_vasprintf()
, которая отличается некоторой функциональностью, но дополняет возвращаемый результат длинной распредделённой строки.
format : |
стандартная строка формата printf() , но помните
проблемы точности строк.
|
args : |
список параметров для вставки в форматируемую строку. |
Возвращает : | вновь распределённая строка содержащая результат. |
gint g_printf (gchar const *format, ...);
Реализация стандартной функции printf()
которая поддерживает параметры позиционирования, как определено в Single Unix Specification.
format : |
стандартная строка формата printf() , но помните о
проблеме точности строк.
|
... : |
аргументы для вставки в вывод (output). |
Возвращает : | количество напечатанных символов. |
Начиная с версии 2.2
gint g_vprintf (gchar const *format, va_list args);
Реализация стандартной функции vprintf()
которая поддерживает параметры позиционирования, как определено в Single Unix Specification.
format : |
стандартная строка формата printf() , но помните о
проблеме точности строк.
|
args : |
список аргументов вставляемых в вывод. |
Возвращает : | количество напечатанных символов. |
Начиная с версии 2.2
gint g_fprintf (FILE *file, gchar const *format, ...);
Реализация стандартной функции fprintf()
которая поддерживает параметры позиционирования, как определено в Single Unix Specification.
file : |
поток для записи. |
format : |
стандартная строка формата printf() , но помните о
проблеме точности строк.
|
... : |
аргументы вставляемые в вывод. |
Возвращает : | количество напечатанных символов. |
Начиная с версии 2.2
gint g_vfprintf (FILE *file, gchar const *format, va_list args);
Реализация стандартной функции fprintf()
которая поддерживает параметры позиционирования, как определено в Single Unix Specification.
file : |
попыток для записи. |
format : |
стандартная строка формата printf() , но помните о
проблеме точности строк.
|
args : |
список аргументов для вставки в вывод. |
Возвращает : | количество напечатанных символов. |
Начиная с версии 2.2
gint g_sprintf (gchar *string, gchar const *format, ...);
Реализация стандартной функции sprintf()
которая поддерживает параметры позиционирования, как определено в Single Unix Specification.
string : |
буфер для содержания вывода. |
format : |
стандартная строка формата printf() , но помните о
проблеме точности строк.
|
... : |
аргументы для вставки в вывод. |
Возвращает : | количество напечатанных символов. |
Начиная с версии 2.2
gint g_vsprintf (gchar *string, gchar const *format, va_list args);
Реализация стандартной функции vsprintf()
которая поддерживает
параметры позиционирования, как определено в Single Unix Specification.
string : |
буфер для содержания вывода. |
format : |
стандартная строка формата printf() , но помните о
проблеме точности строк.
|
args : |
список аргументов вставляемых в вывод. |
Возвращает : | количество напечатанных символов. |
Начиная с версии 2.2
gint g_snprintf (gchar *string, gulong n, gchar const *format, ...);
Более безопасный вариант стандартной функции sprintf()
. Гарантирует что вывод не превысит n
символов (включая завершающий нулевой символ (nul character)), поэтому переполнение буфера невозможно.
Смотрите также g_strdup_printf()
.
В версиях GLib до 1.2.3, эта функция может возвращать -1 если вывод был усечён, а усечённая строка может быть не nul-завершённой. В версии до 1.3.12, эта функция возвращает длину строки вывода.
Возвращаемое значение g_snprintf()
согласуется с функцией snprintf()
как стандартизировано в ISO C99. Помните что это отличается от традиционной
snprintf()
, которая возвращает длину строки вывода.
Форматируемая строка может содержать параметры позиционирования, как определено в Single Unix Specification.
string : |
буфер для содержания вывода. |
n : |
максимальное количество производимых символов (включая символ завершения nul). |
format : |
стандартная строка формата printf() , но помните о
проблеме точности строк.
|
... : |
аргументы для вставки в вывод. |
Возвращает : | количество произведённых символов если бы буфер был достаточно большим. |
gint g_vsnprintf (gchar *string, gulong n, gchar const *format, va_list args);
Более безопасный вариант стандартной функции vsprintf()
. Вывод гарантировано не превысит n
символов (включая завершающий символ),
поэтому переполнение буфера не возможно.
Смотрите также g_strdup_vprintf()
.
В версиях GLib до 1.2.3, эта функция может возвращать -1 если вывод был усечён, а усечённая строка может быть не nul-завершённой. В версии до 1.3.12, эта функция возвращает длину строки вывода.
Возвращаемое значение g_vsnprintf()
согласуется с функцией vsnprintf()
как стандартизировано в ISO C99. Помните что это отличается от традиционной
vsnprintf()
, которая возвращает длину строки вывода.
Форматируемая строка может содержать параметры позиционирования, как описано в Single Unix Specification.
string : |
буфер для вывода. |
n : |
максимальное количество символов (включая завершающий nul символ). |
format : |
стандартная строка формата printf() , но помните о
проблеме точности строк.
|
args : |
список аргументов для вставки в вывод. |
Возвращает : | количество символов которые должны быть произведены если буфер окажется больше чем необходимо. |
gint g_vasprintf (gchar **string, gchar const *format, va_list args);
Реализация функции GNU vasprintf()
которая поддерживает параметры позиционирования, как описано в Single Unix Specification.
Эта функция похожа на g_vsprintf()
, но она распределяет строку содержащую вывод, а не помещает вывод в буфер распределённый вами заранее.
string : |
расположение для возвращаемой вновь распределённой строки. |
format : |
стандартная строка формата printf() , но помните о
проблеме точности строк.
|
args : |
список аргументов для вставки в вывод. |
Возвращает : | количество напечатанных символов. |
Начиная с версии 2.4
gsize g_printf_string_upper_bound (const gchar *format, va_list args);
Расчитывает необходимое пространство необходимое для сохранения вывода функции sprintf()
.
format : |
форматируемая строка. Смотрите документацию printf() .
|
args : |
параметры для вставки в форматируемую строку. |
Возвращает : | максимальное пространство необходимое для сохранения форматируемой строки. |
gboolean g_ascii_isalnum (gchar c);
Определяет являются ли символы алфавитно-цифровыми.
В отличие от стандартной библиотечной C функции isalnum()
, эта функция распознаёт только стандартные ASCII символы и игнорирует локаль, возвращает
FALSE
для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int,
поэтому не вызывайте её в конце файла EOF
и не нужно приводить к guchar перед помещением возможно не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c алфавитно-цифровой символ ASCII.
|
gboolean g_ascii_isalpha (gchar c);
Определяет является ли символ алфавитным (то есть буквой).
В отличие от стандартной библиотечной функции isalpha()
, эта распознаёт только стандартные ASCII буквы и игнорирует локаль, возвращает
FALSE
для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, а не int,
поэтому не вызывается в конце файла EOF
и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c является алфавитным ASCII символом.
|
gboolean g_ascii_iscntrl (gchar c);
Определяет является ли символ управляющим символом.
В отличие от стандартной библиотечной функции iscntrl()
, эта рассматривает только стандартные символы управления ASCII и игнорирует локаль,
возвращает FALSE
для всех не-ASCII символов. Также в отличие от стандартной функции, эта принимает char, вместо int,
поэтому не вызывается в конце файла EOF
и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c является управляющим символом ASCII.
|
gboolean g_ascii_isdigit (gchar c);
Определяет является ли символ цифрой (0-9).
В отличие от стандартной библиотечной функции isdigit()
,
эта принимает char, вместо int, поэтому не вызывается в конце файла EOF
и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c является ASCII цифрой.
|
gboolean g_ascii_isgraph (gchar c);
Определяет является ли символ печатным и не прбелом.
В отличие от стандартной библиотечной функции isgraph()
,
эта распознаёт только стандартные символы ASCII и игнорирует локаль,
возвращает FALSE
для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции, эта принимает char, вместо int,
поэтому не должна вызываться в конце файла EOF
и не требует приведения типа к guchar перед помещением возможно не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c это ASCII печатный символ отличающийся от пробела.
|
gboolean g_ascii_islower (gchar c);
Определяет является ли символ буквой ASCII в нижнем регистре.
В отличие от стандартной библиотечной функции islower()
,
эта принимает только стандартные ASCII символы и игнорирует локаль (locale),
возвращает FALSE
для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции,
эта принимает char, а не int,
поэтому не вызывайте её на EOF
, и нет необходимости приведения к guchar
перед помещением возможно не-ASCII символа в функцию.
c : |
любой символ |
Возвращает : |
TRUE если c это ASCII символ в нижнем регистре
|
gboolean g_ascii_isprint (gchar c);
Определяет является ли символ печатным символом.
В отличие от стандартной библиотечной функции isprint()
,
эта принимает только стандартные ASCII символы и игнорирует локаль,
возвращает FALSE
для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции,
эта принимает char, а не int,
поэтому не вызывайте её в EOF
и не нужно приводить к guchar перед помещением возможно не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c это печатный ASCII символ.
|
gboolean g_ascii_ispunct (gchar c);
Определяет является ли символ символом пунктуации.
В отличие от стандартной библиотечной функции ispunct()
,
это принимает только стандартные ASCII символы и игнорирует локаль,
возвращает FALSE
для всех не-ASCII символов. Также в отличие от стандартной библиотечной функции,
эта принимает char, а не int,
поэтому не вызывайте её в EOF
и не нужно приводить к guchar перед помещением возможно не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c это ASCII символ пунктуации.
|
gboolean g_ascii_isspace (gchar c);
Определяет является ли символ символом табуляции, пробела или символом пустой строки (white-space character).
В отличие от стандартной библиотечной функции isspace()
,
эта принимает только стандартные ASCII символы white-space и игнорирует локаль,
возвращает FALSE
для всех не-ASCII символов. Также в отличие от стандартной
библиотечной функции, эта принимает char, а не int,
поэтому не вызывайте её в EOF
и не нужно приводить тип к guchar перед помещением
возможно не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c это ASCII white-space символ
|
gboolean g_ascii_isupper (gchar c);
Определяет является ли символ символом ASCII верхнего регистра.
В отличие от стандартной библиотечной функции isupper()
,
это принимает только стандартные ASCII символы и игнорирует локаль,
возвращает FALSE
для всех не-ASCII символов. Также в отличие от стандартной
библиотечной функции, эта принимает тип char, а не int,
поэтому не вызывайте её в EOF
и не нужно приводить тип к guchar
перед помещением возможно не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c это ASCII символ верхнего регистра
|
gboolean g_ascii_isxdigit (gchar c);
Определяет является ли символ шестнадцатеричным-цифровым символом.
В отличие от стандартной библиотечной функции isxdigit()
,
эта принимает тип char, а не int, поэтому
не нужно вызывать её в EOF
и не нужно приводить тип к guchar перед помещением вохможно
не-ASCII символа.
c : |
любой символ |
Возвращает : |
TRUE если c это ASCII шестнадцатеричный-цифровой символ.
|
gint g_ascii_digit_value (gchar c);
Определяет числовое значение символа в виде десятичной цифры.
Отличается от g_unichar_digit_value()
потому что принимает тип
char, поэтому не беспокойтесь о дополнительном знаке (+ или -) если символы
со знаком.
c : |
ASCII символ. |
Возвращает : | Если c десятичная цифра (согласно
g_ascii_isdigit() ), её числовое значение.
Иначе, -1.
|
gint g_ascii_xdigit_value (gchar c);
Определяет числовое значение символа как шестнадцатеричное число.
Отличается от g_unichar_xdigit_value()
так как принимает символ, поэтому нет смысла беспокоится о знаке если символы со знаком.
c : |
ASCII символ. |
Возвращает : | Если c шестнадцатеричное число (согласно
g_ascii_isxdigit() ), его числовое значение.
Иначе, -1.
|
gint g_ascii_strcasecmp (const gchar *s1, const gchar *s2);
Сравнивает две строки, игнорирует регистр ASCII символов.
В отличие от BSD функции strcasecmp()
, эта принимает только стандартные
ASCII буквы и игнорирует локаль, обрабатывая все не-ASCII
байты как будто они не буквы.
Эта функция должна использоваться только в строках кодировка байт которых соответствует ASCII литерам всегда представляя самих себя. Это включает UTF-8 и ISO-8859-* символы, но не двойную кодировку байт как в Windows Codepage 932, где завершающий байт двух-байтовых символов включает все ASCII буквы. Если вы сравниваете две CP932 строки используя эту функцию, то вы получите неправильный результат.
s1 : |
строка для сравнения с s2 .
|
s2 : |
строка для сравнения с s1 .
|
Возвращает : | 0 если строки соответсвуют, отрицательное значение если s1 < s2 ,
или положительное значение если s1 > s2 .
|
gint g_ascii_strncasecmp (const gchar *s1, const gchar *s2, gsize n);
Сравнивает s1
и s2
, игнорирует регистр ASCII символов и любые
символы после первых n
в каждой строке.
В отличие от BSD функции strcasecmp()
, эта функция понимает только стандартные
ASCII буквы и игнорирует локаль, обрабатывая все не-ASCII символы как не буквы.
Тоже самое предупреждение как и для g_ascii_strcasecmp()
: Используйте эту функцию только для строк известной кодировки где байты соответствуют ASCII литерам и представляют самих себя.
s1 : |
строка для сравнения с s2 .
|
s2 : |
строка для сравнения с s1 .
|
n : |
количество символов для сравнения. |
Возвращает : | 0 если строки соответсвуют, отрицательное значение если s1 < s2 ,
или положительное значение если s1 > s2 .
|
gchar* g_ascii_strup (const gchar *str, gssize len);
Конвертирует все символы нижнего регистра ASCII букв в верхний регистр букв ASCII.
str : |
строка. |
len : |
длина str в байтах, или -1 если str nul-завершённая.
|
Возвращает : | вновь распределёная строка, все символы нижнего регистра в str
преобразуются в верхний регистр, семантика которой точно соответствует g_ascii_toupper() .
(Помните что это отличается от старой g_strup() ,
которая изменяла строку на месте.)
|
gchar* g_ascii_strdown (const gchar *str, gssize len);
Конвертирует все символы ASCII верхнего регистра в символы ASCII нижнего регистра.
str : |
строка. |
len : |
длина str в байтах, или -1 если str nul-завершённая.
|
Возвращает : | вновь распределённая строка, все символы верхнего регистра
str конвертированы в символы нижнего регистра, с семантикой
точно соответствующей g_ascii_tolower() . (Помните
это не похоже на старую g_strdown() , которая изменялся строку на месте.)
|
gchar g_ascii_tolower (gchar c);
Конвертирует символ в нижний регистр ASCII.
В отличие от стандартной библиотечной функции tolower()
, эта принимает
только стандартные ASCII буквы и игнорирует локаль, возвращает все
не-ASCII символы не изменёнными, даже если они являются буквами нижнего
регистра в специальном наборе символов. Также в отличие от стандартной
библиотечной функции, эта принимает и возвращает тип char, а не int, поэтому
не вызывайте её в EOF
и не беспокойтесь о приведении типа к guchar
перед помещением возможно не-ASCII символа.
c : |
любой символ. |
Возвращает : | результат конвертации c в нижний регистр.
Если c не ASCII буква верхнего регистра,
c возвращается не изменённым.
|
gchar g_ascii_toupper (gchar c);
Ковертирует символ в ASCII верхнего регистра.
В отличие от стандартной библиотечной функции toupper()
, эта
принимает только стандартные ASCII буквы и игнорирует локаль, возвращает
все не-ASCII символы без изменений, даже если они являются символами
верхнего регистра в специальном наборе символов. Также в отличие от стандартной
библиотечной функции, эта принимает и возвращает тип char, а не int, поэтому
не вызывайте её в EOF
и не беспокойтесь о приведении типа к guchar
перед помещением в неё возможно не-ASCII символа.
c : |
любой символ. |
Возвращает : | результат конвертации c в верхний регистр.
Если c не ASCII буква нижнего регистра,
c возвращается без изменений.
|
GString* g_string_ascii_up (GString *string);
Конвертирует все буквы ASCII нижнего регистра в буквы верхнего регистра ASCII.
string : |
GString |
Возвращает : | помещённый указатель на string , в которой все символы нижнего регистра
конвертированы в верхний регистр на месте, с семантикой
которая соответствует g_ascii_toupper.
|
GString* g_string_ascii_down (GString *string);
Конвертирует все буквы верхнего регистра ASCII в нижний регистр букв ASCII.
string : |
GString |
Возвращает : | помещённый указатель на string , в которой все символы верхнего регистра
конвертированы в нижний регистр на месте, с семантикой
соответствующей g_ascii_tolower.
|
gchar* g_strup (gchar *string);
g_strup
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Эта функция неисправна по причинам обсуждаемым в
документации g_strncasecmp()
- используйте вместо неё g_ascii_strup()
или g_utf8_strup()
.
Конвертирует строку в верхний регистр.
string : |
строка для конвертации. |
Возвращает : | конвертированную строку |
gchar* g_strdown (gchar *string);
g_strdown
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Эта функция полностью неисправна по причинам
обсуждаемым в документации g_strncasecmp()
- используйте вместо неё g_ascii_strdown()
или g_utf8_strdown()
.
Конвертирует строку в нижний регистр.
string : |
строка для конвертации. |
Возвращает : | строка |
gint g_strcasecmp (const gchar *s1, const gchar *s2);
g_strcasecmp
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Смотрите g_strncasecmp()
для обсуждения
причины по которой не рекомендуется использовать эту функцию и чем её заменить.
Не чувствительное к регистру сравнение строк, соответствует стандартной функции
strcasecmp()
на платформах которые поддерживают её.
s1 : |
строка. |
s2 : |
a строка для сравнения с s1 .
|
Возвращает : | 0 если строки соответсвуют, отрицательное значение если s1 < s2 ,
или положительное значение если s1 > s2 .
|
gint g_strncasecmp (const gchar *s1, const gchar *s2, guint n);
g_strncasecmp
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде.
Проблема g_strncasecmp()
в том что она вызывает для сравнения toupper()
/tolower()
.
Эти функции являются локаль-специфичными (locale-specific) и оперируют одним байтом.
Однако, это не позволяет правильно обрабатывать возможности I18N так как требуются многобайтные символы.
Поэтому g_strncasecmp()
не работает правильно если ваша строка гарантировано в ASCII, так как это
зависит от локали (locale-sensitive), и она неправильно работает если ваша строка локализована,
так как она не работает на большинстве кодировок, включая UTF-8, EUC-JP, и т.д..
Пэтому есть две заменяющие функции: g_ascii_strncasecmp()
,
которая работает только в ASCII и не зависит от локали, а так же
g_utf8_casefold()
, которая хорошо подходит для сортировки без учета регистра UTF-8.
Сравнение строк без учёта регистра, соответствует стандартной функции
strncasecmp()
на платформах которые её поддерживают.
Она похожа на g_strcasecmp()
за исключением того что сравнивает только первые n
символов в строках.
s1 : |
строка. |
s2 : |
a строка для сравнения с s1 .
|
n : |
максимальное число символов для сравнения. |
Возвращает : | 0 если строки эквивалентны, отрицательное значение если s1 < s2 ,
или положительное значение если s1 > s2 .
|
gchar* g_strreverse (gchar *string);
Переворачивает строку.
Например, g_strreverse ("abcdef")
выдаст результат "fedcba".
Помните что g_strreverse()
не работает в UTF-8 строках содержащих многобайтные символы.
Для этих случаев используйте g_utf8_strreverse()
.
string : |
строка для переворота. |
Возвращает : | указатель помещённый как
gint64 g_ascii_strtoll (const gchar *nptr, gchar **endptr, guint base);
Конвертирует строку в значение gint64.
Эта функция ведёт себя как стандартная функция strtoll()
выполняемая в C локали. Она выполняет это без фактического
изменения текущей локали, так как это было бы не потоко-безопасным (thread-safe).
Эта функция обычно используется когда читаются конфигурационные файлы
или другой не пользовательский ввод который должен быть независим от локали.
Для обработки пользовательского ввода вы должны обычно использовать
чувствительную к локали (locale-sensitive) системную функцию strtoll()
.
Если текущее значение вызвало бы переполнение буфера, возвращается G_MAXINT64
или G_MININT64
,
а ERANGE
сохраняется в errno
. Если base вне допустимого диапазона,
возвращается ноль, а EINVAL
сохраняется в errno
. Если преобразование строки не удалось, возвращается ноль, а
endptr
возвращает nptr
(если endptr
это не-NULL
).
nptr : |
строка для конвертации в числовое значение. |
endptr : |
если не-NULL , возвращается символ после
последнего символа используемого в преобразовании.
|
base : |
используется для преобразования, 2..36 или 0 |
Возвращает : | gint64 значение или ноль при ошибке. |
Начиная с версии 2.12
guint64 g_ascii_strtoull (const gchar *nptr, gchar **endptr, guint base);
Конвертирует строку в значение guint64.
Эта функция ведёт себя также как стандартная strtoull()
выполняющаяся в C локали. Она работает без фактического изменения
текущей локали, так как это было бы не потоко-безопасным (thread-safe).
Эта функция обычно используется при чтении конфигурационных файлов
или другого не пользовательского ввода который должен быть независимым от локали.
Для обработки пользовательского ввода вы должны обычно использовать чувствительную к локали
(locale-sensitive) системную функцию strtoull()
.
Если правильное значение вызывает переполнение буфера, то возвращается G_MAXUINT64
,
а ERANGE
сохраняется в errno
. Если base вне допустимого диапазона,
возвращается ноль, а EINVAL
сохраняется в errno
. Если преобразование строки не удалось,
возвращается ноль, а endptr
возвращает nptr
(если endptr
не-NULL
).
nptr : |
строка для конвертации to a numeric value. |
endptr : |
если не-NULL , возвращается символ после последнего
используемого при конвертации.
|
base : |
используется для преобразования, 2..36 или 0 |
Возвращает : | значение guint64 или ноль в error. |
Начиная с версии 2.2
#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)
Правильный размер буфера для помещения в g_ascii_dtostr()
.
Этого гарантированно достаточно для всего вывода функции в системах с
64bit IEEE-совместимым doubles.
Обычное использование выглядит так:
char buf[G_ASCII_DTOSTR_BUF_SIZE]; fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
gdouble g_ascii_strtod (const gchar *nptr, gchar **endptr);
Конвертирует строку в gdouble значение.
Эта функция ведёт себя как стандартная функция strtod()
работающая в C лосали. Она работает без фактического изменения
текущей локали, так как это было бы не потоко-безопасным (thread-safe).
Эта функция обычно используется когда читаются конфигурационные файлы
или другой не пользовательский ввод который должен быть не зависим от локали.
Для обработки ввода пользователя вы должны обычно использовать
чувствительную к локали системную функцию strtod()
.
Для конвертации из gdouble в строку чувствительным к локали способом, используйте g_ascii_dtostr()
.
Если правильное значение вызвало бы переполнение буфера, возвращается плюс или минус HUGE_VAL
(соответсвенно значению со знаком), а ERANGE
сохраняется в errno
. Если правильное значение
вызвало бы антипереполнение буфера (underflow), возвращается ноль и ERANGE
сохраняется в errno
.
Эта функция сбрасывает errno
перед вызовом strtod()
так, чтобы вы могли надёжно обнаружить
переполнение или антипереполнение буфера.
gchar* g_ascii_dtostr (gchar *buffer, gint buf_len, gdouble d);
Конвертирует gdouble в строку, используя '.' как десятичную точку.
Эта функция генерирует достаточно точно конвертированную
с помощью g_ascii_strtod()
строку, получая то же машинное число (machine-number)
(на машинах с IEEE совместимым 64bit doubles). Гарантирует что результирующая строка
не будет больше чем G_ASCII_DTOSTR_BUF_SIZE
байт.
buffer : |
Буфер для размещения строки результата |
buf_len : |
Размер буфера. |
d : |
gdouble для конвертации |
Возвращает : | Указатель на буфер с конвертированной строкой. |
gchar* g_ascii_formatd (gchar *buffer, gint buf_len, const gchar *format, gdouble d);
Конвертирует gdouble в строку, используя '.' как
десятичную точку. Для форматирования числа вы помещаете строку формата в стиле
printf()
. Допускаются спецификаторы преобразования 'e', 'E', 'f', 'F', 'g' и 'G'.
Если вы просто хотите преобразовать в последовательную форму значение в строке, используйте g_ascii_dtostr()
.
buffer : |
Буфер для размещения строки результата |
buf_len : |
Размер буфера. |
format : |
Формат в стиле printf() используемый для конвертации.
|
d : |
gdouble для конвертации |
Возвращает : | Указатель на буфер с конвертированной строкой. |
gdouble g_strtod (const gchar *nptr, gchar **endptr);
Конвертирует строку в gdouble значение.
Она вызывает стандартную функцию strtod()
для обработки конвертации, но
если строка конвертирована не полностью она пытается конвертировать снова с помощью
g_ascii_strtod()
и возвращает лучшее соответствие.
Эта функция должна использоваться редко. В обычных ситуациях когда читаются
числа не для применения человеком используется
g_ascii_strtod()
.
Вы должны её использовать только когда знаете что ожидается оба формата чисел и в локали и в C формате.
Убедитесь что вы не поместили строки такие как разделённые запятыми списки значений,
так как запятая может интерпретироваться как десятичная точка в некоторых локалях, вызывая неожиданный результат.
gchar* g_strchug (gchar *string);
Удаляет все символы табуляций (whitespace) из строки, но перемещает символы вперёд.
Эта функция не распределяет и не перераспределяет никакую память; она изменяет string
на месте. Указатель на string
возвращается чтобы позволить вложенные функции.
Также смотрите g_strchomp()
и g_strstrip()
.
string : |
строка из которой удаляются табуляции. |
Возвращает : |
string .
|
gchar* g_strchomp (gchar *string);
Удаляет замыкающие табуляции из строки.
Эта функция не распределяет и не перераспределяет никакую память; она изменяет string
на месте. Указатель на string
возвращается чтобы позволить вложенные функции.
Также смотрите g_strchug()
и g_strstrip()
.
string : |
строка to remove the trailing whitespace from. |
Возвращает : |
string .
|
#define g_strstrip( string )
Удаляет начальные и завершающие пробелы (whitespace) из строки. Смотрите g_strchomp()
и
g_strchug()
.
string : |
строка из которой удаляются начальные и завершающие пробелы (whitespace). |
gchar* g_strdelimit (gchar *string, const gchar *delimiters, gchar new_delimiter);
Конвертирует любые разделительные символы (delimiter characters) в string
в new_delimiter
.
Любые найденные в string
символы delimiters
изменяются на new_delimiter
. Изменяет строку string
на месте и возвращает непосредственно
string
, а не копию. Возвращаемое значение позволяет вложение, такое как
g_ascii_strup (g_strdelimit (str, "abc", '?'))
.
string : |
строка для конвертации. |
delimiters : |
строка содержащая текущие разделители, или NULL для
использования стандартных разделителей определённых в G_STR_DELIMITERS.
|
new_delimiter : |
новые разделительные символы. |
Возвращает : |
string .
|
#define G_STR_DELIMITERS "_-|> <."
Стандартные разделительные символы используемые в g_strdelimit()
.
gchar* g_strescape (const gchar *source, const gchar *exceptions);
Выводит специальные символы '\b', '\f', '\n', '\r', '\t', '\' и
'"' в строке source
и вставляет перед ними '\'.
Дополнительно все символы в диапазоне 0x01-0x1F (все ниже SPACE) м в диапазоне 0x7F-0xFF (все не-ASCII символы) заменяются с помощью
'\' сопровождаемого их восьмеричным представлением. Символы поставляемые в exceptions
не выводятся.
g_strcompress()
выполняет обратную конвертацию.
source : |
строка для вывода. |
exceptions : |
строка of characters not to escape in source .
|
Возвращает : | вновь распределённая копия source с определёнными символами вывода. Смотрите выше.
|
gchar* g_strcompress (const gchar *source);
Заменяет все escape-символы их однобайтными эквивалентами. Вы полняет обратную конвертацию для
g_strescape()
.
source : |
строка для сжатия. |
Возвращает : | вновь распределённая копия source в которой все escape-символы
сжаты.
|
gchar* g_strcanon (gchar *string, const gchar *valid_chars, gchar substitutor);
Каждый символ в string
, если символ не valid_chars
,
заменяет символом substitutor
. Изменяет строку string
на месте
и возвращает непосредственно string
, а не копию. Возвращаемое значение допускает вложенность,
такую как g_ascii_strup (g_strcanon (str, "abc", '?'))
.
string : |
nul-завершённый массив байт. |
valid_chars : |
байты разрешённые в string .
|
substitutor : |
символ заменяющий запрещённые байты. |
Возвращает : |
string .
|
gchar** g_strsplit (const gchar *string, const gchar *delimiter, gint max_tokens);
Разбивает строку на максимум max_tokens
частей, используя разделитель
delimiter
. Если max_tokens
достигнут, остаток строки string
прикрепляется к последней лексеме.
Как специальный случай, результатом разбиения пустой строки "" является пустой вектор,
а не вектор содержащий единственную строку. Причиной такого специального случая является то,
что обычно представление пустого вектора полезнее чем обработка пустых элементов. Если вам нужно
представить пустые элементы, вы должны проверить пустую строку перед вызовом
g_strsplit()
.
string : |
строка для разбиения. |
delimiter : |
строка определяющая места разбиения строки.
Разделитель не включается ни в одну из результирующих строк, пока не достигнут
max_tokens .
|
max_tokens : |
максимальное число частей для разбиения string .
Если меньше чем 1, строка разбивается полностью.
|
Возвращает : | вновь распределённый NULL -завершённый массив строк.
Используйте g_strfreev() для его освобождения.
|
gchar** g_strsplit_set (const gchar *string, const gchar *delimiters, gint max_tokens);
Разбивает string
на множество лексем не содержащих любой из символов
в delimiter
. Лексемы это (возможно пустые) длинные строки которые не содержат любой из символов
находящихся в delimiters
. Если достигнут max_tokens
,
остаток предложения прикрепляется к последней лексеме.
Например результатом g_strsplit_set ("abc:def/ghi", ":/", -1) будет
NULL
-завершённый вектор содержащий дерево строк "abc", "def",
и "ghi".
Результатом g_strsplit_set (":def/ghi:", ":/", -1) NULL
-завершённый
вектор содержащий четыре строки "", "def", "ghi", и "".
Как специальный случай, результатом разбиения пустой строки "" является пустой вектор,
а не вектор содержащий единственную строку. Причиной такого специального случая является то,
что обычно представление пустого вектора полезнее чем обработка пустых элементов. Если вам нужно
представить пустые элементы, вы должны проверить пустую строку перед вызовом
g_strsplit()
.
Помните что эта функция работает с байтами а не с символами, поэтому она не может использоваться для разграничения UTF-8 строк чем нибудь кроме ASCII символов.
string : |
строка для разбиения на лексемы |
delimiters : |
nul-завершённая строка содержащая байты которые используются для разбиения строки. |
max_tokens : |
максимальное число лексем для разбиения string .
Если меньше 1, строка разбивается полностью
|
Возвращает : | вновь распределённый NULL -завершённый массив строк.
Используйте g_strfreev() для его освобождения.
|
Начиная с версии 2.4
void g_strfreev (gchar **str_array);
Освобождает NULL
-завершённый массив строк, и непосредственно массив.
Если вызвана для значения NULL
, g_strfreev()
просто возвращается.
str_array : |
NULL -завершённый массив строк для освобождения.
|
gchar* g_strconcat (const gchar *string1, ...);
Соединяет все полученные строки в одну длинную строку. Возвращаемая строка должна быть освобождена когда больше не нужна.
Переменный список параметров must должен завершаться NULL
.
Если вы забудете о NULL
, g_strconcat()
добавит к ваше строке произвольный участок памяти.
gchar* g_strjoin (const gchar *separator, ...);
Объединяет множество строк вместе в форме одной длинной строки, с необязательным разделителем
separator
вставляемым между ними.
gchar* g_strjoinv (const gchar *separator, gchar **str_array);
Объединяет множество строк вместе в форме одной длинной строки, с необязательным
separator
вставляемым между каждой из них.
guint g_strv_length (gchar **str_array);
Возвращает длину полученного NULL
-завершённого
массива строк str_array
.
str_array : |
NULL -завершённый массив строк.
|
Возвращает : | длина str_array .
|
Начиная с версии 2.6
const gchar* g_strerror (gint errnum);
Возвращает строку соответствующую данному коду ошибки (error code), например "no such process".
Эта функция включена так как не все платформы поддерживают функцию
strerror()
.
errnum : |
номер системной ошибки. Смотрите стандарт C errno
документацию.
|
Возвращает : | строка описывающая кодовую ошибку.
Если данный код ошибки не известен, возвращается "unknown error (<code>)".
Строка может использоваться только до следующего вызова g_strerror() .
|
const gchar* g_strsignal (gint signum);
Возвращает строку описывающую полученный сигнал, например "Segmentation fault".
Эта функция включена так как не на всех платформах поддерживается функция
strsignal()
.
signum : |
номер сигнала. Смотрите signal
документацию.
|
Возвращает : | строка описывающая сигнал.
Если сигнал не известен, возвращается "unknown signal (<signum>)".
Строка может использоваться только до следующего вызова g_strsignal() .
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GString; GString* g_string_new (const gchar *init); GString* g_string_new_len (const gchar *init, gssize len); GString* g_string_sized_new (gsize dfl_size); GString* g_string_assign (GString *string, const gchar *rval); #define g_string_sprintf #define g_string_sprintfa void g_string_printf (GString *string, const gchar *format, ...); void g_string_append_printf (GString *string, const gchar *format, ...); GString* g_string_append (GString *string, const gchar *val); GString* g_string_append_c (GString *string, gchar c); GString* g_string_append_unichar (GString *string, gunichar wc); GString* g_string_append_len (GString *string, const gchar *val, gssize len); GString* g_string_prepend (GString *string, const gchar *val); GString* g_string_prepend_c (GString *string, gchar c); GString* g_string_prepend_unichar (GString *string, gunichar wc); GString* g_string_prepend_len (GString *string, const gchar *val, gssize len); GString* g_string_insert (GString *string, gssize pos, const gchar *val); GString* g_string_insert_c (GString *string, gssize pos, gchar c); GString* g_string_insert_unichar (GString *string, gssize pos, gunichar wc); GString* g_string_insert_len (GString *string, gssize pos, const gchar *val, gssize len); GString* g_string_erase (GString *string, gssize pos, gssize len); GString* g_string_truncate (GString *string, gsize len); GString* g_string_set_size (GString *string, gsize len); gchar* g_string_free (GString *string, gboolean free_segment); GString* g_string_up (GString *string); GString* g_string_down (GString *string); guint g_string_hash (const GString *str); gboolean g_string_equal (const GString *v, const GString *v2);
GString подобна стандартной C string, за исключением того что она автоматически увеличивается при добавлении или вставке текста. Также, она хранит длину строки, поэтому может использоваться для двоичных данных с включением нулевых байт.
typedef struct { gchar *str; gsize len; gsize allocated_len; } GString;
Структура GString содержит общедоступные поля
GString.
Поле str
указывает на символьные данные.
Он может меняться при добавлении текста.
Поле len
содержит длину строки,
не включая завершающий нулевой байт.
Поле str
nul-завершённое и поэтому может быть использовано как обычная C string.
Но она может перемещаться когда в строку добавляется или вставляется текст.
GString* g_string_new (const gchar *init);
Создаёт новую GString, инициализируя полученной строкой.
init : |
инициализируемый текст для копирования в строку. |
Возвращает : | новая GString. |
GString* g_string_new_len (const gchar *init, gssize len);
Создаёт новую GString с длиной len
байт буфера init
. Поскольку длина обеспечена, init
не должен быть nul-завершённым и может содержать встроенные nul байты.
init : |
начальное содержимое строки. |
len : |
длина init для использования.
|
Возвращает : | новая GString. |
GString* g_string_sized_new (gsize dfl_size);
Создаёт новую GString, с достаточным пространством для
dfl_size
байт.
Это полезно если вы добавляете много текста в строку и не хотите перераспределять её слишком часто.
dfl_size : |
размер свободного пространства которое содержит распределённая строка. |
Возвращает : | новая GString. |
GString* g_string_assign (GString *string, const gchar *rval);
Копирует байты из строки в GString,
уничтожает любое предыдущее содержимое. Она скорее похожа на стандартную функцию strcpy()
,
за исключением того, что вам не нужно беспокоится о наличии достаточного пространства для копируемой строки.
#define g_string_sprintf
g_string_sprintf
устарела и не должна использоваться во вновь создаваемом коде.
Эта функция переименована в g_string_printf()
.
Записывает форматированную строку в GString.
Подобна стандартной функции sprintf()
,
за исключением того, что буфер GString автоматически расширяется для
вмещения результата.
Предыдущее содержимое GString уничтожается.
#define g_string_sprintfa
g_string_sprintfa
устарела и не должна использоваться во вновь создаваемом коде. This function has been renamed to g_string_append_printf()
.
Добавляет форматированную строку в конец GString.
Эта функция подобна g_string_sprintf()
,
за исключением того, что текст добавляется к GString.
void g_string_printf (GString *string, const gchar *format, ...);
Записывает форматированную строку в GString.
Это подобно стандартной функции sprintf()
,
за исключением того, что буфер GString автоматически
расширяется для вмещения результата.
Предыдущее содержимое GString уничтожается.
string : |
GString. |
format : |
строка формата. Смотрите документацию printf() .
|
... : |
параметры вставляемые в форматируемую строку. |
void g_string_append_printf (GString *string, const gchar *format, ...);
Добавляет форматированную строку в конец GString.
Эта функция подобна g_string_printf()
,
за исключением того, что текст добавляется к GString.
string : |
GString. |
format : |
строка формата. Смотрите документацию printf() .
|
... : |
параметры вставляемые в форматируемую строку. |
GString* g_string_append (GString *string, const gchar *val);
Добавляет строку в конец GString, расширяя её если необходимо.
GString* g_string_append_c (GString *string, gchar c);
Добавляет бай в конец GString, расширяя её если необходимо.
GString* g_string_append_unichar (GString *string, gunichar wc);
Конвертирует Unicode символ в UTF-8, и добавляет его в строку.
string : |
GString |
wc : |
Unicode символ |
Возвращает : | string
|
GString* g_string_append_len (GString *string, const gchar *val, gssize len);
Добавляет len
байт val
в string
. Поскольку len
обеспечена,
val
может содержать встроенные nuls и не должна быть nul-завершённой.
GString* g_string_prepend (GString *string, const gchar *val);
Добавляет строку в начало GString, расширяя её если необходимо.
GString* g_string_prepend_c (GString *string, gchar c);
Добавляет байт в начало GString, расширяя её если необходимо.
GString* g_string_prepend_unichar (GString *string, gunichar wc);
Конвертирует Unicode символ в UTF-8, и добавляет его в начало строки.
string : |
GString. |
wc : |
Unicode символ. |
Возвращает : | string .
|
GString* g_string_prepend_len (GString *string, const gchar *val, gssize len);
Добавляет len
байт val
в string
. Поскольку len
обеспечена,
val
может содержать встроенные nuls и не должна быть nul-завершённой.
GString* g_string_insert (GString *string, gssize pos, const gchar *val);
Вставляет копию строки в GString, расширяя её если необходимо.
GString* g_string_insert_c (GString *string, gssize pos, gchar c);
Вставляет байт в GString, расширяя её если необходимо.
GString* g_string_insert_unichar (GString *string, gssize pos, gunichar wc);
Конвертирует Unicode символ в UTF-8, и вставляет его в строку в указанную позицию.
string : |
GString |
pos : |
позиция в которую вставляется символ, или -1 для добавления в конец строки. |
wc : |
Unicode символ |
Возвращает : | string
|
GString* g_string_insert_len (GString *string, gssize pos, const gchar *val, gssize len);
Вставляет len
байт val
в string
в позицию pos
. Поскольку len
обеспечена,
val
может содержать встроенные nuls и не должна быть nul-завершённой.
Если pos
это -1, байты вставляются в конец строки.
GString* g_string_erase (GString *string, gssize pos, gssize len);
Удаляет len
байт из GString,
сначала позиции pos
.
Остальная часть GString смещается вниз для заполнения пустоты.
GString* g_string_truncate (GString *string, gsize len);
Вырезает окончание GString, оставляя первые len
байт.
GString* g_string_set_size (GString *string, gsize len);
Устанавливает длину GString. Если длина меньше чем текущая, строка будет обрезана. Если длина больше чем текущая, содержимое вновь добавленного пространства неопределено. (Однако, как всегда, string->str[string->len] будет nul байтом.)
string : |
GString |
len : |
новая длина |
Возвращает : | string
|
gchar* g_string_free (GString *string, gboolean free_segment);
Освобождает память распределённую для GString.
Если free_segment
это TRUE
она так же освобождает символьные данные.
GString* g_string_up (GString *string);
g_string_up
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде.
Эта функция использует locale-специфичную функцию toupper()
, которая почти никогда не является
правильным выбором.
Используйте g_string_ascii_up()
или
g_utf8_strup()
вместо неё.
Конвертирует GString в верхний регистр.
GString* g_string_down (GString *string);
g_string_down
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде.
Эта функция использует locale-специфичную функцию tolower()
, которая почти никогда не является
правильным выбором.
Используйте g_string_ascii_down()
или
g_utf8_strdown()
вместо неё.
Конвертирует GString в нижний регистр.
guint g_string_hash (const GString *str);
Создаёт новый хеш код для str
; для использования с
GHashTable.
str : |
строка для хеширования. |
Возвращает : | хеш код для str .
|
gboolean g_string_equal (const GString *v, const GString *v2);
Сравнивает две строки на эквивалентность, возвращает TRUE
если они равны.
Для использования с GHashTable.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GMainLoop; GMainLoop* g_main_loop_new (GMainContext *context, gboolean is_running); GMainLoop* g_main_loop_ref (GMainLoop *loop); void g_main_loop_unref (GMainLoop *loop); void g_main_loop_run (GMainLoop *loop); void g_main_loop_quit (GMainLoop *loop); gboolean g_main_loop_is_running (GMainLoop *loop); GMainContext* g_main_loop_get_context (GMainLoop *loop); #define g_main_new (is_running) #define g_main_destroy (loop) #define g_main_run (loop) #define g_main_quit (loop) #define g_main_is_running (loop) #define G_PRIORITY_HIGH #define G_PRIORITY_DEFAULT #define G_PRIORITY_HIGH_IDLE #define G_PRIORITY_DEFAULT_IDLE #define G_PRIORITY_LOW GMainContext; GMainContext* g_main_context_new (void); GMainContext* g_main_context_ref (GMainContext *context); void g_main_context_unref (GMainContext *context); GMainContext* g_main_context_default (void); gboolean g_main_context_iteration (GMainContext *context, gboolean may_block); #define g_main_iteration (may_block) gboolean g_main_context_pending (GMainContext *context); #define g_main_pending () GSource* g_main_context_find_source_by_id (GMainContext *context, guint source_id); GSource* g_main_context_find_source_by_user_data (GMainContext *context, gpointer user_data); GSource* g_main_context_find_source_by_funcs_user_data (GMainContext *context, GSourceFuncs *funcs, gpointer user_data); void g_main_context_wakeup (GMainContext *context); gboolean g_main_context_acquire (GMainContext *context); void g_main_context_release (GMainContext *context); gboolean g_main_context_is_owner (GMainContext *context); gboolean g_main_context_wait (GMainContext *context, GCond *cond, GMutex *mutex); gboolean g_main_context_prepare (GMainContext *context, gint *priority); gint g_main_context_query (GMainContext *context, gint max_priority, gint *timeout_, GPollFD *fds, gint n_fds); gint g_main_context_check (GMainContext *context, gint max_priority, GPollFD *fds, gint n_fds); void g_main_context_dispatch (GMainContext *context); void g_main_context_set_poll_func (GMainContext *context, GPollFunc func); GPollFunc g_main_context_get_poll_func (GMainContext *context); gint (*GPollFunc) (GPollFD *ufds, guint nfsd, gint timeout_); void g_main_context_add_poll (GMainContext *context, GPollFD *fd, gint priority); void g_main_context_remove_poll (GMainContext *context, GPollFD *fd); gint g_main_depth (void); GSource* g_main_current_source (void); #define g_main_set_poll_func (func) GSource* g_timeout_source_new (guint interval); GSource* g_timeout_source_new_seconds (guint interval); guint g_timeout_add (guint interval, GSourceFunc function, gpointer data); guint g_timeout_add_full (gint priority, guint interval, GSourceFunc function, gpointer data, GDestroyNotify notify); guint g_timeout_add_seconds (guint interval, GSourceFunc function, gpointer data); GSource* g_idle_source_new (void); guint g_idle_add (GSourceFunc function, gpointer data); guint g_idle_add_full (gint priority, GSourceFunc function, gpointer data, GDestroyNotify notify); gboolean g_idle_remove_by_data (gpointer data); typedef GPid; void (*GChildWatchFunc) (GPid pid, gint status, gpointer data); GSource* g_child_watch_source_new (GPid pid); guint g_child_watch_add (GPid pid, GChildWatchFunc function, gpointer data); guint g_child_watch_add_full (gint priority, GPid pid, GChildWatchFunc function, gpointer data, GDestroyNotify notify); GPollFD; GSource; void (*GSourceDummyMarshal) (void); GSourceFuncs; GSourceCallbackFuncs; GSource* g_source_new (GSourceFuncs *source_funcs, guint struct_size); GSource* g_source_ref (GSource *source); void g_source_unref (GSource *source); void g_source_set_funcs (GSource *source, GSourceFuncs *funcs); guint g_source_attach (GSource *source, GMainContext *context); void g_source_destroy (GSource *source); gboolean g_source_is_destroyed (GSource *source); void g_source_set_priority (GSource *source, gint priority); gint g_source_get_priority (GSource *source); void g_source_set_can_recurse (GSource *source, gboolean can_recurse); gboolean g_source_get_can_recurse (GSource *source); guint g_source_get_id (GSource *source); GMainContext* g_source_get_context (GSource *source); void g_source_set_callback (GSource *source, GSourceFunc func, gpointer data, GDestroyNotify notify); gboolean (*GSourceFunc) (gpointer data); void g_source_set_callback_indirect (GSource *source, gpointer callback_data, GSourceCallbackFuncs *callback_funcs); void g_source_add_poll (GSource *source, GPollFD *fd); void g_source_remove_poll (GSource *source, GPollFD *fd); void g_source_get_current_time (GSource *source, GTimeVal *timeval); gboolean g_source_remove (guint tag); gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs, gpointer user_data); gboolean g_source_remove_by_user_data (gpointer user_data);
Основной цикл событий управляет всеми возможными источниками событий
для GLib и GTK+ приложений. Эти события могут исходить из любого числа
различных типов источников таких как файловые дескрипторы (простые файлы,
каналы или сокеты) и таймауты. Новые типы источников событий также могут
быть добавлены используя g_source_attach()
.
Чтобы разрешить обработку множества независимых наборов источников в различных потоках (threads), каждый источник ассоциируется с GMainContext. GMainContext может выполняться только в единственном потоке, но источники могут добавляться в него и удаляться из него из других потоков.
Каждому источнику события назначается приоритет. Приоритет по умолчанию, G_PRIORITY_DEFAULT, равен 0. Значения меньше чем 0 обозначают более высокие приоритеты. Значения больше чем 0 обозначают более низкие приоритеты. События из источников с высоким приоритетом всегда выполняются перед событиями из источников с более низким приоритетом.
Бездействующие (Idle) функции могут быть также добавлены с присвоением приоритета. Они выполняются всякий раз когда события с более высоким приоритетом не готовы к выполнению.
Тип данных GMainLoop представляет основной цикл события.
GMainLoop
создаётся с помощью g_main_loop_new()
. После добавления исходных источников событий,
вызывается g_main_loop_run()
. Это непрерывно проверяет новые события из каждого источника событий
и отправляет их на обработку. Наконец, обработка события из одного из источников приводит к вызову
g_main_loop_quit()
для выхода из основного цикла, а g_main_loop_run()
завершает работу.
Это позволяет создавать новые экземпляры GMainLoop рекурсивно. Часто используется в GTK+ приложениях при показе модальных диалоговых окон. Помните что источники события связаны со специфичным GMainContext, и будут проверены и посланы для всех основных циклов связанных с этим GMainContext.
GTK+ содержит оболочки некоторых из этих функций, например gtk_main()
,
gtk_main_quit()
и gtk_events_pending()
.
Одна из необычных особенностей функциональности основного цикла GTK+
в том, что могут создаваться новые типы источников событий в
дополнение к встроенным типам источников событий. Новый тип источника событий
используется для обработки GDK событий. Новый тип источника создаётся с помощью
наследования из
GSource
структуры. Наследуемый тип источника представляется структурой которая имеет
в качестве первого элемента структуру
GSource, а также другие элементы специфичные для нового
типа источника. Для создания экземпляра нового типа источника, вызывается
g_source_new()
помещая размер наследуемой структуры
и таблицы функций. Эти
GSourceFuncs определяют поведение нового типа источника.
Новые типы источников в основном взаимодействуют с основным контекстом двумя способами.
Они подготавливают функцию в
GSourceFuncs способную установить тайм аут для определения
максимального промежутка времени бездействия основного цикла перед повторной проверкой.
Кроме того, или в дополнение, источник может добавить файловый дескриптор для установки
проверки основного контекста используя g_source_add_poll()
.
Одиночная итерация
GMainContext может быть выполнена с помощью
g_main_context_iteration()
. В некоторых случаях,
вместо этого желательно более точное управление деталями работы основного цикла,
например объединяя
GMainLoop с внешним основным циклом. В этом случае,
вы можете вызвать непосредственно составные функции
g_main_context_iteration()
. Этими функциями являются
g_main_context_prepare()
,
g_main_context_query()
,
g_main_context_check()
и
g_main_context_dispatch()
.
Операции этих функций могут быть лучше рассмотрены в терминах диаграммы состояния, как показано на Рисунке 1, “Состояния основного контекста”.
typedef struct _GMainLoop GMainLoop;
Структура GMainLoop непрозрачный тип данных представляющий основной цикл события GLib или GTK+ приложений.
GMainLoop* g_main_loop_new (GMainContext *context, gboolean is_running);
Создаёт новую структуру GMainLoop.
context : |
GMainContext (если NULL , используется контекст по умолчанию).
|
is_running : |
устанавливается в TRUE указывая на то, что цикл выполняется. Это не очень важно с момента вызова
g_main_loop_run() который установит это значение в
TRUE в любом случае.
|
Возвращает : | новый GMainLoop. |
GMainLoop* g_main_loop_ref (GMainLoop *loop);
Увеличивает счёт ссылок объекта GMainLoop на одну.
loop : |
GMainLoop |
Возвращает : | loop
|
void g_main_loop_unref (GMainLoop *loop);
Уменьшает количество ссылок на объект GMainLoop на одну. Если результат ноль, освобождает цикл и всю связанную с ним память.
loop : |
GMainLoop |
void g_main_loop_run (GMainLoop *loop);
Выполняет основной цикл до тех пор пока не вызвана g_main_loop_quit()
.
Если вызвана для потока (thread) GMainContext циклов, то выполняет событие из цикла, или просто ждёт.
loop : |
GMainLoop |
void g_main_loop_quit (GMainLoop *loop);
Останавливает выполнение GMainLoop. Любые вызовы g_main_loop_run()
для цикла будут возвращены.
loop : |
GMainLoop |
gboolean g_main_loop_is_running (GMainLoop *loop);
Выясняет выполняется ли в данный момент основной цикл через g_main_loop_run()
.
GMainContext* g_main_loop_get_context (GMainLoop *loop);
Возвращает GMainContext цикла (loop)
.
loop : |
GMainLoop. |
Возвращает : | GMainContext цикла loop
|
#define g_main_new(is_running)
g_main_new
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_new()
вместо неё.
Создаёт новый GMainLoop для основного цикла по умолчанию.
is_running : |
устанавливается в значение TRUE указывая что основной цикл выполняется. Это не очень полезно с момента вызова
g_main_run() которая установит TRUE в любом случае.
|
Возвращает : | новый GMainLoop. |
#define g_main_destroy(loop)
g_main_destroy
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_unref()
вместо неё.
Освобождает память распределённую для GMainLoop.
loop : |
GMainLoop. |
#define g_main_run(loop)
g_main_run
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_run()
вместо неё.
Выполняет основной цикл до остановки.
loop : |
GMainLoop. |
#define g_main_quit(loop)
g_main_quit
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_quit()
вместо неё.
Останавливает GMainLoop. Если g_main_run()
был вызван для выполнения GMainLoop, он будет возвращен.
loop : |
GMainLoop. |
#define g_main_is_running(loop)
g_main_is_running
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_loop_is_running()
вместо неё.
Проверяет выполняется ли основной цикл.
#define G_PRIORITY_HIGH -100
Используется для повышения приоритета источников событий. Не используется внутри GLib или GTK+.
#define G_PRIORITY_DEFAULT 0
Используется для приоритета по умолчанию для источника события.
В GLib этот приоритет используется когда добавляется функция-таймаут с помощью
g_timeout_add()
.
В GDK этот приоритет используется для событий из X server.
#define G_PRIORITY_HIGH_IDLE 100
Используется для повышения приоритета idle функций. GTK+ используется G_PRIORITY_HIGH_IDLE + 10 для операций изменения размера, а G_PRIORITY_HIGH_IDLE + 20 операций перерисовки. (Это выполняется для гарантии что любое изменение размера обрабатывается перед любой перерисовкой, чтобы виджеты не перерисовывались лишний раз.)
#define G_PRIORITY_DEFAULT_IDLE 200
Используется для приоритета idle функций по умолчанию.
В GLib этот приоритет используется когда добавляются idle функции с помощью g_idle_add()
.
#define G_PRIORITY_LOW 300
Этот очень медленный приоритет используется для фоновых задач. Не используется внутри GLib или GTK+.
typedef struct _GMainContext GMainContext;
Структура GMainContext это непрозрачный тип данных представляющий наборы источников для обработки в основном цикле.
GMainContext* g_main_context_new (void);
Создаёт новую GMainContext структуру.
Возвращает : | новая GMainContext |
GMainContext* g_main_context_ref (GMainContext *context);
Увеличивает число ссылок на GMainContext объект на одну.
context : |
GMainContext |
Возвращает : | помещённый context (Начиная с версии 2.6)
|
void g_main_context_unref (GMainContext *context);
Уменьшает количество ссылок на GMainContext объект на одну. Если результат ноль, освобождает контекст и всю связанную с ним память.
context : |
GMainContext |
GMainContext* g_main_context_default (void);
Возвращает основной контекст по умолчанию. Основной контекст используется для функции основного цикла, когда основной цикл явно не определён.
Возвращает : | основной контекст по умолчанию. |
gboolean g_main_context_iteration (GMainContext *context, gboolean may_block);
Выполняет единственную итерацию для данного основного цикла. Это включает проверку готовы ли
любые источники событий к обработке, если нет готовых источников событий и
may_block
равен TRUE
, ждёт подготовки источника, затем отсылает самый высокий
приоритет источнику событий который уже готов. Помните, что даже когда
may_block
равен TRUE
,
фукция g_main_context_iteration()
всё же может вернуть
FALSE
, так как
ожидание может быть прервано не только когда будет готов источник событий, но и по другим причинам.
context : |
GMainContext (если NULL , используется контекст по умолчанию)
|
may_block : |
можно ли заблокировать вызов. |
Возвращает : | TRUE если события были отправлены.
|
#define g_main_iteration(may_block)
g_main_iteration
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_context_iteration()
вместо неё.
Выполняет единственную итерацию для GMainContext по умолчанию.
may_block : |
устанавливается в значение TRUE если нужна блокировка (то есть ожидание) пока источник события не будет готов.
Возвращается после обработки источника. Если установлено в FALSE возвращается немедленно если нет источника для обработки.
|
Возвращает : |
TRUE если ещё есть события на рассмотрении.
|
gboolean g_main_context_pending (GMainContext *context);
Проверяет имеют ли источники ожидающие обработки события для данного контекста.
context : |
GMainContext (если NULL , используется контекст по умолчанию)
|
Возвращает : | TRUE если есть события на рассмотрении.
|
#define g_main_pending()
g_main_pending
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_context_pending()
вместо неё.
Проверяет есть ли события ожидающие обработки для GMainContext по умолчанию.
Возвращает : |
TRUE если есть события ожидающие обработки.
|
GSource* g_main_context_find_source_by_id (GMainContext *context, guint source_id);
Находит GSource данной пары контекста и ID.
context : |
GMainContext (если NULL , используется контекст по умолчанию)
|
source_id : |
ID источника, который возвращает g_source_get_id() .
|
Возвращает : | GSource если найден, иначе NULL
|
GSource* g_main_context_find_source_by_user_data (GMainContext *context, gpointer user_data);
Находит источник с полученными пользовательскими данными для callback-функции. Если существует множество источников с такими пользовательскими данными, будет возвращён первый найденный.
context : |
GMainContext |
user_data : |
user_data для callback-функции. |
Возвращает : | источник, если найден, иначе NULL
|
GSource* g_main_context_find_source_by_funcs_user_data (GMainContext *context, GSourceFuncs *funcs, gpointer user_data);
Находит источник с данной исходной функцией и пользовательскими данными. Если существует множество источников с такими же функциями и данными, возвращается первый найденный.
context : |
GMainContext (если NULL , используется контекст по умолчанию).
|
funcs : |
source_funcs помещаемая в g_source_new() .
|
user_data : |
пользовательские данные из callback-функции. |
Возвращает : | источник, если был найден, иначе NULL
|
void g_main_context_wakeup (GMainContext *context);
Если context
в настоящее время ожидает в poll()
, прерывает
poll()
, и продолжает интерактивный процесс.
context : |
GMainContext |
gboolean g_main_context_acquire (GMainContext *context);
Попытается стать владельцем указанного контекста. Если кто то другой владеет контекстом,
немедленно возвращает FALSE
. Владение является правильной рекурсией: владелец может запросить владение снова и отменить
владение когда g_main_context_release()
вызывается столько же раз сколько g_main_context_acquire()
.
Вы должны быть владельцем контекста прежде чем вы сможете вызвать
g_main_context_prepare()
, g_main_context_query()
,
g_main_context_check()
, g_main_context_dispatch()
.
context : |
GMainContext |
Возвращает : | TRUE если операция выполнена и поток теперь владеет данным context .
|
void g_main_context_release (GMainContext *context);
Отменяет владение контекстом предварительно полученное потоком с помощью
g_main_context_acquire()
. Если контекст был получен множество раз, отменяет владение только когда
g_main_context_release()
вызван соответствующее количество раз.
context : |
GMainContext |
gboolean g_main_context_is_owner (GMainContext *context);
Определяет владеет ли этот поток (рекурсивно) GMaincontext. Это полезно
знать перед ожиданием в другом потоке который может быть блокирован для получения владения данным context
.
context : |
GMainContext |
Возвращает : | TRUE если текущий поток владеет context .
|
Начиная с версии 2.10
gboolean g_main_context_wait (GMainContext *context, GCond *cond, GMutex *mutex);
Пытается получить владение определенным контекстом,
так же как с помощью g_main_context_acquire()
. Но если другой поток владеет контекстом, автоматически сбрасывается в mutex
и ждёт в cond
пока этот владелец освободит владение или пока
cond
просигнализирует попытаться снова стать владельцем.
context : |
GMainContext |
cond : |
переменное условие |
mutex : |
взаимное исключение, имеющееся в настоящий момент |
Возвращает : | TRUE если операция выполнена, и данный поток теперь владеет context .
|
gboolean g_main_context_prepare (GMainContext *context, gint *priority);
Подготавливает для опроса источник внутри основного цикла. Результирующая информация для опроса определяется с помощью вызова g_main_context_query()
.
context : |
GMainContext |
priority : |
расположение для хранения приоритета готового источника с высоким приоритетом. |
Возвращает : | TRUE если некоторый источник готов для предварительной отправки опроса.
|
gint g_main_context_query (GMainContext *context, gint max_priority, gint *timeout_, GPollFD *fds, gint n_fds);
Определяет информацию необходимую для опроса этого основного цикла.
context : |
GMainContext |
max_priority : |
максимальный приоритет источника для проверки |
timeout_ : |
расположение для хранения пауз используемых в опросах |
fds : |
расположение для хранения GPollFD отчётов опросов. |
n_fds : |
длина fds .
|
Возвращает : | количество отчётов фактически сохрнённых в fds ,
или, если больше чем n_fds отчётов для хранения, количество отчётов которое необходимо сохранить.
|
gint g_main_context_check (GMainContext *context, gint max_priority, GPollFD *fds, gint n_fds);
Помещает результат опроса обратно в основной цикл.
context : |
GMainContext |
max_priority : |
максимальное число приоритета источника для проверки |
fds : |
массив GPollFD's которые были помещены в последний вызов
g_main_context_query()
|
n_fds : |
значение возвращаемое функцией g_main_context_query()
|
Возвращает : | TRUE если некоторый источник готов для отправки.
|
void g_main_context_dispatch (GMainContext *context);
Отправляет все ожидающие обработки источники.
context : |
GMainContext |
void g_main_context_set_poll_func (GMainContext *context, GPollFunc func);
Устанавливает функцию используемую для обработки опроса дескриптора файла. Используется вместо
poll()
системой вызовов
(или функцией замены GLib's, которая используется когда poll()
не доступен).
Эта функция может использоваться для интеграции GLib цикла события с внешним циклом события.
context : |
GMainContext |
func : |
функция для вызова опроса всех дескрипторов файла |
GPollFunc g_main_context_get_poll_func (GMainContext *context);
Получает функцию опроса установленную с помощью g_main_context_set_poll_func()
.
context : |
GMainContext |
Возвращает : | функция опроса |
gint (*GPollFunc) (GPollFD *ufds, guint nfsd, gint timeout_);
Определяет тип функции помещаемой в g_main_context_set_poll_func()
.
Семантика функции должна соответствовать системному вызову
.
poll()
ufds : |
массив GPollFD элементов. |
nfsd : |
количество элементов в ufds .
|
timeout_ : |
максимальное время ожидания события дескриптора файла. Отрицательное значение указывает на бесконечное время ожидания. |
Возвращает : | количество GPollFD элементов которые имеют события или сообщения об ошибках, или -1 если произошла ошибка. |
void g_main_context_add_poll (GMainContext *context, GPollFD *fd, gint priority);
Добавляет дескриптор файла в набор дескрипторов файлов опрашиваемых для данного контекста. Это очень редко используется непосредственно. Вместо этого обычно источник события использует
g_source_add_poll()
.
context : |
GMainContext (или NULL для контекста по умолчанию)
|
fd : |
GPollFD структура содержащая информацию о дескрипторах файла для просмотра. |
priority : |
приоритет для этого дескриптора файла должен быть таким же как приоритет используемый для
g_source_attach()
чтобы убедиться что дескриптор файла будет опрошен всякий раз когда может понадобиться результат.
|
void g_main_context_remove_poll (GMainContext *context, GPollFD *fd);
Удаляет дескриптор файла из набора дескрипторов файла опрашиваемых для определенного контекста.
context : |
GMainContext |
fd : |
GPollFD предварительно добавленный с помощью g_main_context_add_poll()
|
gint g_main_depth (void);
Возвращает значение основного цикла рекурсии в текущем потоке
Возвращает : | глубину стека вызовов для
g_main_context_dispatch() в любом GMainContext текущего потока. Таким образом, когда вызов из верхнего уровня,
она выдаёт 0. Когда вызов изнутри callback-функции g_main_context_iteration()
(или g_main_loop_run() , и т.д.) она возвращает 1. Когда вызов изнутри callback-функции для рекурсивного вызова
g_main_context_iterate() , она возвращает 2. И так далее.
Эта функция полезна в ситуациях описанных ниже:
Представьте чрезвычайно простую систему "сборки мусора".
Пример 1.
static GList *free_list;
gpointer
allocate_memory (gsize size)
{
gpointer result = g_malloc (size);
free_list = g_list_prepend (free_list, result);
return result;
}
void
free_allocated_memory (void)
{
GList *l;
for (l = free_list; l; l = l->next);
g_free (l->data);
g_list_free (free_list);
free_list = NULL;
}
[...]
while (TRUE);
{
g_main_context_iteration (NULL, TRUE);
Это работает в приложении, однако, если вы захотите сделать тоже самое в библиотеке,
возникнет много проблем, так как вы не можете больше контролировать основной цикл.
Вы можете подумать, что можно просто использовать idle функцию создав вызов для
Пример 2. gpointer allocate_memory (gsize size) { FreeListBlock *block = g_new (FreeListBlock, 1);\ block->mem = g_malloc (size); block->depth =
Есть искушение использовать
|
GSource* g_main_current_source (void);
Возвращает текущий источник для этого потока.
Возвращает : | текущий источник или NULL .
|
Начиная с версии 2.12
#define g_main_set_poll_func(func)
g_main_set_poll_func
устарела начиная с версии 2.2 и не должна использоваться во вновь создаваемом коде. Используйте g_main_context_set_poll_func()
вместо неё.
Устанавливает функцию используемую для обработки опроса дескрипторов файла основного контекста по умолчанию.
func : |
функция для вызова опроса всех дескрипторов файла. |
GSource* g_timeout_source_new (guint interval);
Создаёт новый источник пауз.
Источник первоначально не связан ни с каким GMainContext
и должен быть добавлен с помощью g_source_attach()
перед выполнением этой функции.
interval : |
интервал времени ожидания в милесекундах. |
Возвращает : | вновь созданный источник времени ожидания |
GSource* g_timeout_source_new_seconds (guint interval);
Создаёт новый источник времени ожидания.
Первоначально не связан ни с каким GMainContext
и должен быть добавлен с помощью g_source_attach()
перед выполнением.
Точность данного источника времени ожидания измеряется в секундах.
interval : |
интервал времени ожидания в секундах |
Возвращает : | вновь созданный источник времени ожидания |
Начиная с версии 2.14
guint g_timeout_add (guint interval, GSourceFunc function, gpointer data);
Заставляет вызывать функцию с равномерными интервалами, с приоритетом по умолчанию G_PRIORITY_DEFAULT.
Функция вызывается до тех пор пока не возвращено FALSE
, в этой точке время ожидания автоматически уничтожается и
функция больше не вызывается. Первый вызов функции выполняется в конце первого
interval
.
Помните что функции паузы могут быть отсрочены, из-за обработки других событий источника. Таким образом нельзя рассчитывать на точную синхронизацию. После каждого вызова функции паузы, время следующей паузы пересчитывается исходя из текущего времени и данного интервала (это не учитывает время потерянное во время задержек).
Если вы хотите иметь таймер в "секундах" и не беспокоиться о точном времени первого вызова таймера,
используйте функцию g_timeout_add_seconds()
; она позволяет большую оптимизацию и более эффективное использование мощностей системы.
interval : |
время между вызовами функции, в миллисекундах (1/1000 секунды) |
function : |
вызываемая функция |
data : |
данные помещаемые в function
|
Возвращает : | ID (больше чем 0) источника события. |
guint g_timeout_add_full (gint priority, guint interval, GSourceFunc function, gpointer data, GDestroyNotify notify);
Заставляет вызывать функцию с регулярными интервалами, с данным приоритетом.
Функция вызывается до тех пор пока возвращено значение
FALSE
, в этой точке время ожидания автоматически уничтожается и функция больше не вызывается. Функция notify
вызывается когда пауза уничтожена. Первый вызов функции происходит в конце первого interval
.
Помните что функции паузы могут быть отсрочены, из-за обработки других событий источника. Таким образом нельзя рассчитывать на точную синхронизацию. После каждого вызова функции паузы, время следующей паузы пересчитывается исходя из текущего времени и данного интервала (это не учитывает время потерянное во время задержек).
priority : |
приоритет idle источника. Обычно в диапазоне между G_PRIORITY_DEFAULT_IDLE и G_PRIORITY_HIGH_IDLE. |
interval : |
время между вызовами функций, в миллисекундах (1/1000 секунды) |
function : |
вызываемая функция |
data : |
данные помещаемые в function
|
notify : |
функция вызываемая когда интервал удалён, или NULL
|
Возвращает : | ID (больше 0) источника события. |
guint g_timeout_add_seconds (guint interval, GSourceFunc function, gpointer data);
Вызывает функцию через равномерные интервалы, с приоритетом по умолчанию,
G_PRIORITY_DEFAULT. Функция вызывается до тех пор пока не возвращено значение
FALSE
,
в этой точке интервал автоматически уничтожается и функция больше не вызывается.
В отличии от g_timeout_add()
, эта функция оперирует секундной точностью. Начальная точка таймера определяется
реализацией и реализация как ожидается соберёт множество таймеров в группу, чтобы они все
запускались в одно время. Чтобы позволить эту группировку, interval
для первого таймера округляется и может отклониться на одну секунду от указанного интервала.
Последующие итерации таймера будут в общем выполняться в указанном интервале.
Помните что тайм аут функции могут быть отсрочены, из-за обработки других источников событий.
Таким образом на них нельзя рассчитывать при точной синхронизации. После каждого вызова тайм аут
функции, время следующей паузы пересчитывается исходя из текущего времени и полученного интервала
interval
Если вам нужны более точные расчеты нежели секунды, используйте вместо этой функции
g_timeout_add()
.
Группирование таймеров для старта в одно и тоже время приводит к более эффективному использованию
CPU, поэтому если ваш таймер в секундах и находится в множестве однотипных и вам не требуется
запуск первого таймера с точностью до 1 секунды, использование
g_timeout_add_second()
предпочтительней чем g_timeout_add()
.
interval : |
время между запусками функций, в секундах |
function : |
функция для вызова |
data : |
данные для помещения в function
|
Возвращает : | ID (больше чем 0) источника события. |
Начиная с версии 2.14
GSource* g_idle_source_new (void);
Создаёт новый пустой (idle) источник.
Источник первоначально не связан ни с каким GMainContext
и должен быть добавлен в него с помощью g_source_attach()
перед выполнением. Помните что приоритетом по
умолчанию idle источника является
G_PRIORITY_DEFAULT_IDLE
, тогда как другие источники по умолчанию имеют приоритет
G_PRIORITY_DEFAULT
.
Возвращает : | вновь созданный пустой (idle) источник |
guint g_idle_add (GSourceFunc function, gpointer data);
Добавляет функцию которая вызывается каждый раз когда нет обрабатываемого события с более высоким
приоритетом в основном цикле по умолчанию. Функция получает по умолчанию idle приоритет,
G_PRIORITY_DEFAULT_IDLE.
Если функция возвращает FALSE
она автоматически удаляется из списка источника событий и больше не вызывается.
function : |
функция для вызова |
data : |
данные для помещения в function .
|
Возвращает : | ID (больше 0) источника события. |
guint g_idle_add_full (gint priority, GSourceFunc function, gpointer data, GDestroyNotify notify);
Добавляет функцию для вызова когда нет события с более высоким приоритетом на рассмотрении.
Если функция возвращает FALSE
, то автоматически удаляется из списка источника событий и больше не вызывается.
priority : |
приоритет idle источника. Обычно в диапазоне между G_PRIORITY_DEFAULT_IDLE и G_PRIORITY_HIGH_IDLE. |
function : |
функция для вызова |
data : |
данные помещаемые в function
|
notify : |
функция вызываемая при удалении idle функции, или NULL
|
Возвращает : | ID (больше 0) источника события. |
gboolean g_idle_remove_by_data (gpointer data);
Удаляет idle функцию с полученными данными.
data : |
данные для idle источников callback-функций. |
Возвращает : | TRUE если idle
источник найден и удалён.
|
typedef int GPid;
Тип содержащий идентификатор процесса. В Unix, процессы идентифицируются с помощью process id (целочисленное), в то время как в Windows используются маркеры процесса (которые являются указателями).
void (*GChildWatchFunc) (GPid pid, gint status, gpointer data);
Тип функций для вызова при существовании дочерних процессов.
pid : |
id дочернего процесса |
status : |
Информация состояния дочернего процесса, более подробную информацию об этом поле смотрите в waitpid(2) |
data : |
пользовательские данные помещаемые в g_child_watch_add()
|
GSource* g_child_watch_source_new (GPid pid);
Создаёт новый child_watch источник.
Первоначально источник не связан ни с каким GMainContext
и должен быть добавлен в него с помощью g_source_attach()
перед использованием.
Помните, что дочерний процесс наблюдения может использоваться только совместно с
g_spawn...
когда используется флаг G_SPAWN_DO_NOT_REAP_CHILD
.
Помните, что на платформах где GPid должен быть явно закрыт
(смотрите g_spawn_close_pid()
) pid
не должен закрываться пока источник активен. Обычно, вам нужно вызывать
g_spawn_close_pid()
в callback-функции для источника.
Помните также что использование g_child_watch_source_new()
не совместимо с вызовом waitpid(-1)
в приложении.
Вызов waitpid()
для индивидуального pids будет прекрасно работать.
pid : |
process id дочернего процесса для наблюдения. В Windows, МАРКЕР (HANDLE) для процесса наблюдения (который фактически не является дочерним). |
Возвращает : | вновь созданный дочерний процесс наблюдения |
Начиная с версии 2.4
guint g_child_watch_add (GPid pid, GChildWatchFunc function, gpointer data);
Устанавливает функцию для вызова при существовании дочернего процесса указанного с помощью pid
,
с приоритетом по умолчанию G_PRIORITY_DEFAULT.
Помните что на платформах где GPid должен быть явно закрыт (смотрите g_spawn_close_pid()
) pid
не должен закрываться пока источник активен. Обычно, вам потребуется вызвать
g_spawn_close_pid()
в callback-функции для источника.
GLib поддерживает только один вызов callback-функции через process id.
pid : |
process id дочернего процесса для наблюдения |
function : |
функция для вызова |
data : |
данные помещаемые в function
|
Возвращает : | ID (больше 0) источника события. |
Начиная с версии 2.4
guint g_child_watch_add_full (gint priority, GPid pid, GChildWatchFunc function, gpointer data, GDestroyNotify notify);
Устанавливает функцию вызываемую когда дочерний процесс указанный с помощью pid
существует, с приоритетом по умолчанию G_PRIORITY_DEFAULT.
Помните что на платформах где GPid должен быть закрыт явно (смотрите g_spawn_close_pid()
) pid
не должен закрываться пока источник активен. Обычно, вам необходимо вызвать g_spawn_close_pid()
в callback-функции для источника.
GLib поддерживает только единственный вызов callback-функции через process id.
priority : |
приоритет idle источника. Обычно в диапазоне между G_PRIORITY_DEFAULT_IDLE и G_PRIORITY_HIGH_IDLE. |
pid : |
process id дочернего процесса для наблюдения |
function : |
вызываемая функция |
data : |
данные помещаемые в function
|
notify : |
функция вызываемая при удалении idle функции, или NULL
|
Возвращает : | ID (больше 0) источника события. |
Начиная с версии 2.4
typedef struct { gint fd; gushort events; gushort revents; } GPollFD;
gint fd; | дескриптор файла для опроса (или МАРКЕР (HANDLE) на Win32 платформах). |
|
поразарядная комбинация флажков из GIOCondition,
определяющая события для опроса. Обычно для чтения из дескриптора файла вы должны использовать
G_IO_IN | G_IO_HUP | G_IO_ERR , а для записи вы должны
использовать G_IO_OUT | G_IO_ERR .
|
|
поразрядная комбинация флажков из GIOCondition, возвращаемая из функции
указывая какие события произошли.
|
typedef struct { } GSource;
Структура GSource непрозрачного типа данных представляющих источник события.
void (*GSourceDummyMarshal) (void);
Это просто метка для GClosureMarshal, которая не используется по причине зависимостей.
typedef struct { gboolean (*prepare) (GSource *source, gint *timeout_); gboolean (*check) (GSource *source); gboolean (*dispatch) (GSource *source, GSourceFunc callback, gpointer user_data); void (*finalize) (GSource *source); /* Может быть NULL */ /* Для использования g_source_set_closure */ GSourceFunc closure_callback; GSourceDummyMarshal closure_marshal; /* Фактически тип GClosureMarshal */ } GSourceFuncs;
Структура GSourceFuncs содержит таблицу функций используемых для обработки источника события основным способом.
prepare |
Вызывается перед опросом всех дескрипторов файла. Если источник может определить что он готов
(не ждет результата вызова )
он должен вернуть TRUE .
Он также может вернуть значение timeout_ которое должно быть максимальным временем ожидания (в миллесекундах) помещаемым в вызов .
Фактический используемый тайм аут будет равен -1 если все источники вернут -1, или он будет меньше всех возвращённых значений timeout_ которые были >= 0.
|
check |
Вызывается после опроса всех дескрипторов файла.
Источник должен вернуть TRUE если он готов для отправки.
Помните что пройдёт некоторое время так как была вызвана предварительно подготовленная функция,
поэтому источник должен проверяться снова.
|
dispatch |
Вызывается после отправки источника события, после того как он возвратил TRUE или в prepare или check функции. Функция dispatch помещает callback-функцию и данные. callback-функция может быть
NULL если источник никогда не связывается с callback-функцией используя g_source_set_callback() . Функция dispatch должна вызывать callback-функцию с user_data и независимо от дополнительных параметров необходимых для этого типа источника события.
|
finalize | Вызывается когда источник окончательно реализован (finalized). |
Для idle источников, функции prepare и check всегда возвращают TRUE
указывая что источник всегда готов к обработке.
Функция prepare также возвращает значение тайм аута равное 0, чтобы гарантировать что вызов
не заблокируется (так как это было бы впустую потраченным временем которое можно потратить на idle функцию).
poll()
Для источников, обе функции prepare и check возвращают TRUE
если интервал тайм аута истек.
Функция prepare также возвращает значение таймаута, чтобы гарантировать что вызов
не блокируется слишком долго и не пропустит следующий таймаут.
poll()
Для источников дескриптора файлов, функция prepare обычно возвращает FALSE
,
так как нужно ждать пока
будет вызвана перед определением нужно ли обрабатывать какое нибудь событие. Это установит возвращённый тайм аут в значение -1 указывая что не знает как долго блокирован вызов
poll()
.
В функции check, проверяет результат вызова poll()
чтобы видеть встречалось ли необходимое условие, и возвращает poll()
TRUE
.
typedef struct { void (*ref) (gpointer cb_data); void (*unref) (gpointer cb_data); void (*get) (gpointer cb_data, GSource *source, GSourceFunc *func, gpointer *data); } GSourceCallbackFuncs;
Структура GSourceCallbackFuncs содержит функции для управления callback-объектами.
ref () |
Вызывается при добавлении ссылки на callback-объект. |
unref () |
Вызывается при сбросе ссылки на callback-объект. |
get () |
Вызывается для извлечения callback-функции и данных из callback-объекта. |
GSource* g_source_new (GSourceFuncs *source_funcs, guint struct_size);
Содаёт новую структуру GSource.
Размер определяется для создания структур полученных из GSource который содержит дополнительные данные.
Помещаемый размер должен быть как минимум sizeof (GSource)
.
Первоначально источник не связан ни с каким GMainContext
и должен быть добавлен в него с помощью g_source_attach()
перед использованием.
GSource* g_source_ref (GSource *source);
Увеличивает количество ссылок источника на одну.
source : |
GSource |
Возвращает : | source
|
void g_source_unref (GSource *source);
Уменьшает количество ссылок источника на одну. Если в результате получается ноль, источник и связанная с ним память освобождаются.
source : |
GSource |
void g_source_set_funcs (GSource *source, GSourceFuncs *funcs);
Отсоединяет функции от источника (может использоваться для отмены выполнения по умолчанию).
source : |
GSource |
funcs : |
новый GSourceFuncs |
Начиная с версии 2.12
guint g_source_attach (GSource *source, GMainContext *context);
Добавляет GSource в
context
так чтобы он выполнялся внутри контекста.
source : |
GSource |
context : |
GMainContext (если NULL , используется контекст по умолчанию)
|
Возвращает : | ID (больше 0) для источника внутри GMainContext. |
void g_source_destroy (GSource *source);
Удаляет источник из его GMainContext, если есть, и маркирует его как уничтоженный. Источник не может в последствии добавляться в другой контекст.
source : |
GSource |
gboolean g_source_is_destroyed (GSource *source);
Определяет уничтожен ли source
.
Это важно когда вы оперируете с вашими объектами внутри idle обработчиков, но при этом возможно освободили объект перед отправкой вашего idle обработчика.
static gboolean idle_callback (gpointer data) { SomeWidget *self = data; GDK_THREADS_ENTER (); /* заполняется самостоятельно */ self->idle_id = 0; GDK_THREADS_LEAVE (); return FALSE; } static void some_widget_do_stuff_later (SomeWidget *self) { self->idle_id = g_idle_add (idle_callback, self); } static void some_widget_finalize (GObject *object) { SomeWidget *self = SOME_WIDGET (object); if (self->idle_id) g_source_remove (self->idle_id); G_OBJECT_CLASS (parent_class)->finalize (object); }
Этот пример завершится неудачей в много-потоковом приложении если виджет уничтожен перед запуском idle обработчика из-за использования после освобождения в обратном вызове. Решение этой специфической проблемы в том, чтобы проверить уничтожен ли уже источник в обратном вызове.
static gboolean idle_callback (gpointer data) { SomeWidget *self = data;GDK_THREADS_ENTER()
; if (!g_source_is_destroyed (g_main_current_source()
)) { /* заполняется самостоятельно */ }GDK_THREADS_LEAVE()
; return FALSE; }
Начиная с версии 2.12
void g_source_set_priority (GSource *source, gint priority);
Устанавливает приоритет источника. Во время выполнения основного цикла, источник отправляется если готов и нет готовых источников с более высоким приоритетом (с меньшим номером).
source : |
GSource |
priority : |
новый приоритет. |
gint g_source_get_priority (GSource *source);
Определяет приоритет источника.
source : |
GSource |
Возвращает : | приоритет источника |
void g_source_set_can_recurse (GSource *source, gboolean can_recurse);
Устанавливает может ли источник вызываться рекурсивно. Если параметр can_recurse
равен TRUE
, то во время отправки источник обрабатывается обычно. Иначе, все процессы источника блокируются до возвращения функции отправки.
source : |
GSource |
can_recurse : |
разрешена ли рекурсия для данного источника |
gboolean g_source_get_can_recurse (GSource *source);
Проверяет разрешено ли источнику вызываться рекурсивно.
(смотрите g_source_set_can_recurse())
.
source : |
GSource |
Возвращает : | разрешена ли рекурсия. |
guint g_source_get_id (GSource *source);
Возвращает число ID для специального источника. ID источника это положительное целое которое является уникальным внутри определённого контекста основного цикла. Обратное преобразование из ID
в источник выполняется с помощью g_main_context_find_source_by_id()
.
source : |
GSource |
Возвращает : | ID (больше 0) для источника |
GMainContext* g_source_get_context (GSource *source);
Определяет GMainContext с которым связан источник. Вызов этой функции для уничтоженного источника недопустим.
source : |
GSource |
Возвращает : | GMainContext с которым связан источник, или NULL если контекст не имеет добавленного источника.
|
void g_source_set_callback (GSource *source, GSourceFunc func, gpointer data, GDestroyNotify notify);
Устанавливает callback-функцию для источника. callback-функция для источника вызывается из dispatch функции источников.
Точный тип func
зависит от типа источника; то есть вы не
должны рассчитывать на func
вызванную с data
как её первый параметр.
Обычно вам не нужно использовать эту функцию. Вместо неё используйте функции определённого типа для используемого вами типа источника.
source : |
источник |
func : |
callback-функция |
data : |
данные помещаемые в callback-функцию |
notify : |
функция вызываемая когда data больше не используются,
или NULL .
|
gboolean (*GSourceFunc) (gpointer data);
Конкретизирует тип функции помещаемой в g_timeout_add()
, g_timeout_add_full()
,
g_idle_add()
и g_idle_add_full()
.
data : |
данные помещаемые в функцию, устанавливаются когда источник создаётся одной из упомянутых выше функцией. |
Возвращает : | должна вернуть FALSE если источник должен быть удалён.
|
void g_source_set_callback_indirect (GSource *source, gpointer callback_data, GSourceCallbackFuncs *callback_funcs);
Устанавливает callback-функцию хранения данных как refcounted callback
"object". Это используется внутренне. Помните что вызов
g_source_set_callback_indirect()
предполагает, что начат подсчёт ссылок на callback_data
, и поэтому callback_funcs->unref
будет в конечном счёте вызван больше чем callback_funcs->ref
.
source : |
источник |
callback_data : |
указатель для данных callback-объекта "object" |
callback_funcs : |
функция для подсчёта ссылок callback_data
и получения callback-функции и данных
|
void g_source_add_poll (GSource *source, GPollFD *fd);
Добавляет дескриптор в набор опрашиваемых дескрипторов файла для данного источника.
Это полезно комбинировать с g_source_new()
для добавления источника события.
Функция проверки источников события обычно проверяет поле
revents
в GPollFD структуре и возвращает TRUE
если события должны быть обработаны.
void g_source_remove_poll (GSource *source, GPollFD *fd);
Удаляет дескриптор файла из набора опрашиваемых дескрипторов файла для данного источника.
source : |
GSource |
fd : |
GPollFD структура предварительно помещённая в g_source_add_poll() .
|
void g_source_get_current_time (GSource *source, GTimeVal *timeval);
Определяет "текущее время" для использования при проверки источника.
Преимущество вызова этой функции перед вызовом g_get_current_time()
заключается в проверке
множества источников, GLib может кэшировать единственное значение вместо необходимости неоднократного получения системного времени.
gboolean g_source_remove (guint tag);
Удаляет источник с полученным id из основного контекста по умолчанию.
Идентификатор (id)
GSource получается при помощи g_source_get_id()
, или возвращается функциями g_source_attach()
, g_idle_add()
, g_idle_add_full()
,
g_timeout_add()
, g_timeout_add_full()
, g_child_watch_add()
,
g_child_watch_add_full()
, g_io_add_watch()
и g_io_add_watch_full()
.
Смотрите также g_source_destroy()
.
tag : |
ID удаляемого источника. |
Возвращает : | TRUE если источник найден и удалён.
|
gboolean g_source_remove_by_funcs_user_data (GSourceFuncs *funcs, gpointer user_data);
Удаляет источник из контекста основного цикла по умолчанию с данными функциями источника и пользовательскими данными. Если существует множество источников с одинаковыми функциями источника и пользовательскими данными, будет удалён только один.
funcs : |
source_funcs помещаемые в g_source_new()
|
user_data : |
пользовательские данные для callback-функции |
Возвращает : | TRUE если источник найден и удалён.
|
gboolean g_source_remove_by_user_data (gpointer user_data);
Удаляет источник из контекста основного цикла по умолчанию с полученными пользовательскими данными для callback-функции. Если существует множество одинаковых источников с такими же пользовательскими данными, удаляется только один.
user_data : |
user_data для callback-функции. |
Возвращает : | TRUE если источник найден и удалён.
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GThreadPool; GThreadPool* g_thread_pool_new (GFunc func, gpointer user_data, gint max_threads, gboolean exclusive, GError **error); void g_thread_pool_push (GThreadPool *pool, gpointer data, GError **error); void g_thread_pool_set_max_threads (GThreadPool *pool, gint max_threads, GError **error); gint g_thread_pool_get_max_threads (GThreadPool *pool); guint g_thread_pool_get_num_threads (GThreadPool *pool); guint g_thread_pool_unprocessed (GThreadPool *pool); void g_thread_pool_free (GThreadPool *pool, gboolean immediate, gboolean wait); void g_thread_pool_set_max_unused_threads (gint max_threads); gint g_thread_pool_get_max_unused_threads (void); guint g_thread_pool_get_num_unused_threads (void); void g_thread_pool_stop_unused_threads (void); void g_thread_pool_set_sort_function (GThreadPool *pool, GCompareDataFunc func, gpointer user_data); void g_thread_pool_set_max_idle_time (guint interval); guint g_thread_pool_get_max_idle_time (void);
Иногда вам нужна асинхронная работа, прекращение работы и продолжение работы вашего потока. Если это происходит часто, накладные расходы запуска и уничтожения процесса каждый раз могут быть слишком высоки. В таких случаях хорошей идеей является многократное использование уже существующих потоков. Но реализация этого может быть утомительной и подвержена ошибкам.
Поэтому для вашего удобства GLib обеспечивает пулы потоков. Дополнительное преимущество в том, что потоки могут использоваться совместно разными подсистемами вашей программы, когда используется GLib.
Для создания нового пула потоков используется g_thread_pool_new()
.
Освобождается созданный пул потоков с помощью g_thread_pool_free()
.
Если вам нужно выполнить определённую задачу внутри потокового пула, вызовите g_thread_pool_push()
.
Для получения текущего количества выполняемых потоков используйте
g_thread_pool_get_num_threads()
. Для получения количества ещё не обработанных задач
используйте g_thread_pool_unprocessed()
. Для управления максимальным количеством потоков
пула, используйте g_thread_pool_get_max_threads()
и g_thread_pool_set_max_threads()
.
Наконец вы можете контролировать количество неиспользуемых потоков, которые поддерживаются
GLib для использования в будущем. Текущее количество может быть выбрано с помощью
g_thread_pool_get_num_unused_threads()
. Максимальное количество может контролироваться
с помощью g_thread_pool_get_max_unused_threads()
и g_thread_pool_set_max_unused_threads()
.
Все текущие неиспользуемые потоки могут быть остановлены при помощи g_thread_pool_stop_unused_threads()
.
typedef struct { GFunc func; gpointer user_data; gboolean exclusive; } GThreadPool;
Структура GThreadPool представляет потоковый пул. Она имеет шесть общих доступных только для чтения элементов, но скрытая структура больше, поэтому вы не должны копировать эту структуру.
GThreadPool* g_thread_pool_new (GFunc func, gpointer user_data, gint max_threads, gboolean exclusive, GError **error);
Эта функция создаёт новый потоковый пул.
Каждый раз при вызове g_thread_pool_push()
, или создаётся новый поток
или повторно используется один из неиспользуемых. Большинство max_threads
потоков
выполняются параллельно для этого потокового пула. max_threads
= -1
позволяет безлимитное создание потоков для этого пула. Вновь созданный или
повторно используемый поток выполняет функцию func
с двумя аргументами.
Первый для g_thread_pool_push()
а второй user_data
.
Параметр exclusive
определяет, владеет ли всеми исключительными потоками пул,
или потоки доступны глобально. Если exclusive
равен TRUE
, max_threads
потоки
начинаются немедленно и они будут выполняться исключительно для этого пула
пока он не разрушен g_thread_pool_free()
. Если exclusive
равен FALSE
,
потоки создаются когда необходимы и доступны всем не исключительным потоковым пулам.
Это подразумевает что max_threads
может не быть -1 для исключительных потоковых пулов.
error
может быть NULL
для игнорирования ошибок, или не-NULL
для сообщения об ошибках.
Ошибка может произойти только когда exclusive
установлен в TRUE
и не все max_threads
могут быть созданы.
func : |
функция выполняемая в потоке нового потокового пула |
user_data : |
пользовательские данные передаваемые в функцию func при каждом вызове
|
max_threads : |
максимальное количество потоков для параллельного выполнения в новом потоковом пуле, -1 означает отсутствие лимита |
exclusive : |
должен ли этот пул быть исключительным? |
error : |
расположение возвращаемой ошибки |
Возвращает : | новую GThreadPool |
void g_thread_pool_push (GThreadPool *pool, gpointer data, GError **error);
Вставляет data
в список задач для выполнения пулом pool
. Когда количество
выполняемых потоков меньше чем максимально допустимое, новый поток запускается
(или повторно выполняется) с параметрами полученными в
g_thread_pool_new()
. Иначе data
остаются в очереди пока поток в этом пуле не завершит предыдущие задачи и не начнет
обрабатывать data
.
error
может быть NULL
для игнорирования ошибок, или не-NULL
для сообщения об ошибках.
Ошибка может произойти только когда новый поток не может быть создан.
В этом случае data
просто вставляются в начало очереди для выполнения.
pool : |
GThreadPool |
data : |
новая задача для pool
|
error : |
расположение для возвращаемой ошибки |
void g_thread_pool_set_max_threads (GThreadPool *pool, gint max_threads, GError **error);
Устанавливает максимально допустимое число потоков для pool
. Значение -1 означает безлимитное количество потоков.
Установка max_threads
в значение 0 означает полную
остановку работы pool
. Пул замораживается до тех пор пока
значение max_threads
не будет установлено в не-нулевое значение.
Поток никогда не завершается во время выполнения вызова func
, которая поставляется
g_thread_pool_new()
. Вместо этого максимальное число потоков имеет эффект только для распределения новых потоков в
g_thread_pool_push()
.
Новый поток распределяется каждый раз, когда текущее количество выполняемых потоков в пуле меньше
pool
меньше чем максимальное число.
error
может быть NULL
для игнорирования ошибок, или не-NULL
для сообщения об ошибках.
Ошибка происходит только когда новый поток не может быть создан.
pool : |
GThreadPool |
max_threads : |
новое максимальное число потоков для pool
|
error : |
расположение возвращаемой ошибки |
gint g_thread_pool_get_max_threads (GThreadPool *pool);
Возвращает максимальное число потоков для pool
.
pool : |
GThreadPool |
Возвращает : | максимальное число потоков |
guint g_thread_pool_get_num_threads (GThreadPool *pool);
Возвращает текущее количество выполняемых потоков в pool
.
pool : |
GThreadPool |
Возвращает : | текущее количество выполняемых потоков |
guint g_thread_pool_unprocessed (GThreadPool *pool);
Возвращает количество задач остающихся не обработанными в pool
.
pool : |
GThreadPool |
Возвращает : | количество не обработанных задач |
void g_thread_pool_free (GThreadPool *pool, gboolean immediate, gboolean wait);
Освобождает все ресурсы распределённые для pool
.
Если immediate
равен TRUE
, нет новых задач обрабатываемых в pool
. Иначе pool
не освободиться до тех пор пока последняя задача не обработана.
Однако помните, поток не прерывается в пуле пока выполняет задачу. Все потоки выполняющие свои
задачи завершают их перед тем как pool
будет освобождён.
Если wait
равен TRUE
, функции не возвращают прежде чем все обрабатываемые задачи
(зависит от immediate
, все или только выполняемые в
текущий момент) будут готовы. Иначе функции возвращаются немедленно.
После вызова этой функции pool
не должен больше использоваться.
pool : |
GThreadPool |
immediate : |
должен ли пул pool завершиться немедленно?
|
wait : |
должна ли функция ждать завершения всех задач? |
void g_thread_pool_set_max_unused_threads (gint max_threads);
Устанавливает максимальное количество неиспользуемых потоков в max_threads
. Если
max_threads
равен -1, количество неиспользуемых потоков не лимитировано.
max_threads : |
максимальное число неиспользуемых потоков |
gint g_thread_pool_get_max_unused_threads (void);
Возвращает максимально допустимое число неиспользуемых потоков.
Возвращает : | максимальное число неиспользуемых потоков |
guint g_thread_pool_get_num_unused_threads (void);
Возвращает текущее количество неиспользуемых потоков.
Возвращает : | текущее число неиспользуемых потоков |
void g_thread_pool_stop_unused_threads (void);
Останавливает все текущие неиспользуемые потоки. Это не меняет максимальное число
неиспользуемых потоков. Эта функция может использоваться для регулярной остановки всех
неиспользуемых потоков например из g_timeout_add()
.
void g_thread_pool_set_sort_function (GThreadPool *pool, GCompareDataFunc func, gpointer user_data);
Устанавливает функцию для сортировки списка задач. Это позволяет обрабатывать задачи с приоритетом
определяемым с помощью func
, а не только в порядке в котором они были добавлены в пул.
Помните, если максимальное количество потоков больше 1, порядок выполнения потоков не может быть гарантирован на 100%. Потоки планируются операционной системой и выполняются в случайном порядке. Не предполагайте что потоки выполняются в порядке их создания.
pool : |
GThreadPool |
func : |
GCompareDataFunc используемая для сортировки списка задач. При передаче в функцию две задачи, она должна возвращать 0 если порядок в котором обрабатываются задачи не важен, отрицательное значение если первая задача должна быть обработана перед второй или положительное если вторая задача должна обрабатываться перед первой. |
user_data : |
пользовательские данные помещаемые в func .
|
Начиная с версии 2.10
void g_thread_pool_set_max_idle_time (guint interval);
Эта функция устанавливает максимальный interval
ожидания потоком новых задач в пуле перед остановкой. Эта функция похожа на вызов
g_thread_pool_stop_unused_threads()
с регулярным таймаутом, но выполняется на основании потока.
Установка interval
в 0, не останавливает бездействующие потоки.
Эта функция создаёт g_async_queue_timed_pop()
используя
interval
.
interval : |
максимальный interval (1/1000 секунды) бездействия потока.
|
Начиная с версии 2.10
guint g_thread_pool_get_max_idle_time (void);
Эта функция возвращает максимальный interval
ожидания потоком новых задач в пуле перед остановкой.
Если функция вернула 0, потоки ожидающие новые задачи в пуле не останавливаются.
Возвращает : | максимальный interval ожидания потоком новых задач в пуле перед остановкой (1/1000 секунды).
|
Начиная с версии 2.10
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
ПотокиThreads — Абстракция потока; включает потоки, различные взаимоисключения (mutexes), условия и поток закрытых данных. |
#include <glib.h> #define G_THREADS_ENABLED #define G_THREADS_IMPL_POSIX #define G_THREADS_IMPL_NONE #define G_THREAD_ERROR enum GThreadError; GThreadFunctions; void g_thread_init (GThreadFunctions *vtable); gboolean g_thread_supported (); gpointer (*GThreadFunc) (gpointer data); enum GThreadPriority; GThread; GThread* g_thread_create (GThreadFunc func, gpointer data, gboolean joinable, GError **error); GThread* g_thread_create_full (GThreadFunc func, gpointer data, gulong stack_size, gboolean joinable, gboolean bound, GThreadPriority priority, GError **error); GThread* g_thread_self (void); gpointer g_thread_join (GThread *thread); void g_thread_set_priority (GThread *thread, GThreadPriority priority); void g_thread_yield (); void g_thread_exit (gpointer retval); void g_thread_foreach (GFunc thread_func, gpointer user_data); GMutex; GMutex* g_mutex_new (); void g_mutex_lock (GMutex *mutex); gboolean g_mutex_trylock (GMutex *mutex); void g_mutex_unlock (GMutex *mutex); void g_mutex_free (GMutex *mutex); GStaticMutex; #define G_STATIC_MUTEX_INIT void g_static_mutex_init (GStaticMutex *mutex); void g_static_mutex_lock (GStaticMutex *mutex); gboolean g_static_mutex_trylock (GStaticMutex *mutex); void g_static_mutex_unlock (GStaticMutex *mutex); GMutex* g_static_mutex_get_mutex (GStaticMutex *mutex); void g_static_mutex_free (GStaticMutex *mutex); #define G_LOCK_DEFINE (name) #define G_LOCK_DEFINE_STATIC (name) #define G_LOCK_EXTERN (name) #define G_LOCK (name) #define G_TRYLOCK (name) #define G_UNLOCK (name) GStaticRecMutex; #define G_STATIC_REC_MUTEX_INIT void g_static_rec_mutex_init (GStaticRecMutex *mutex); void g_static_rec_mutex_lock (GStaticRecMutex *mutex); gboolean g_static_rec_mutex_trylock (GStaticRecMutex *mutex); void g_static_rec_mutex_unlock (GStaticRecMutex *mutex); void g_static_rec_mutex_lock_full (GStaticRecMutex *mutex, guint depth); guint g_static_rec_mutex_unlock_full (GStaticRecMutex *mutex); void g_static_rec_mutex_free (GStaticRecMutex *mutex); GStaticRWLock; #define G_STATIC_RW_LOCK_INIT void g_static_rw_lock_init (GStaticRWLock *lock); void g_static_rw_lock_reader_lock (GStaticRWLock *lock); gboolean g_static_rw_lock_reader_trylock (GStaticRWLock *lock); void g_static_rw_lock_reader_unlock (GStaticRWLock *lock); void g_static_rw_lock_writer_lock (GStaticRWLock *lock); gboolean g_static_rw_lock_writer_trylock (GStaticRWLock *lock); void g_static_rw_lock_writer_unlock (GStaticRWLock *lock); void g_static_rw_lock_free (GStaticRWLock *lock); GCond; GCond* g_cond_new (); void g_cond_signal (GCond *cond); void g_cond_broadcast (GCond *cond); void g_cond_wait (GCond *cond, GMutex *mutex); gboolean g_cond_timed_wait (GCond *cond, GMutex *mutex, GTimeVal *abs_time); void g_cond_free (GCond *cond); GPrivate; GPrivate* g_private_new (GDestroyNotify destructor); gpointer g_private_get (GPrivate *private_key); void g_private_set (GPrivate *private_key, gpointer data); GStaticPrivate; #define G_STATIC_PRIVATE_INIT void g_static_private_init (GStaticPrivate *private_key); gpointer g_static_private_get (GStaticPrivate *private_key); void g_static_private_set (GStaticPrivate *private_key, gpointer data, GDestroyNotify notify); void g_static_private_free (GStaticPrivate *private_key); GOnce; enum GOnceStatus; #define G_ONCE_INIT #define g_once (once, func, arg)
Потоки действуют почти как процессы, но в отличии от процессов все потоки одного процесса совместно используют одну и туже память. Это хорошо, поскольку обеспечивает простую взаимосвязь между вовлечёнными потоками через общую память, и это плохо, потому что могут происходить странные вещи (так называемый "Heisenbugs") если программа спроектирована не достаточно внимательно. В частности из-за параллельной природы потоков, выполняемый код не может выполняться в разных потоках, если программист явно не назначил это через синхронизацию примитивов.
Цель связанных с потоком функций в GLib заключается в обеспечении переносимого способа создания многопоточных программ. Есть примитивы для взаимоисключений для защиты доступа к участкам памяти (GMutex, GStaticMutex, G_LOCK_DEFINE, GStaticRecMutex и GStaticRWLock). Есть примитивы для переменных условий позволяющие синхронизацию потоков (GCond). Есть примитивы для закрытых потоковых данных - данных которые каждый поток имеет закрытый экземпляр (GPrivate, GStaticPrivate). И не в последнюю очередь есть примитивы для портативного создания и управления потоками (GThread).
Вы должны вызывать g_thread_init()
перед выполнением любых других функций GLib в потоковых GLib программах. После этого,
GLib полностью потоко-безопасен (все глобальные данные автоматически блокируются), но
индивидуальные экземпляры структур данных не блокируются автоматически по причине выполнения.
Поэтому, например вы должны координировать доступ к одной и той же
GHashTable
из множества потоков. Известно два исключения из этого правила
GMainLoop и GAsyncQueue,
которые являются потоко-безопасными и не нуждаются в
дальнейшей блокировки на уровне приложения для доступности из множества потоков.
#define G_THREADS_ENABLED
Этот макрос определяется если GLib была скомпилирована с поддержкой потоков. Это не означает
обязательную доступность реализации потоков, но это значит что необходимая инфраструктура на месте
и как только вы обеспечите реализацию потоков в
g_thread_init()
,
GLib станет потоко-безопасной. Если G_THREADS_ENABLED не определён, то Glib не может быть безопасной для много-поточности.
#define G_THREADS_IMPL_POSIX
Этот макрос определяется если используется стиль потоков POSIX.
#define G_THREADS_IMPL_NONE
Этот макрос определяется если нет используемой реализации потоков. Вы можете однако обеспечить это
с помощью g_thread_init()
для создания безопасной много-поточности GLib.
#define G_THREAD_ERROR g_thread_error_quark ()
Область ошибок в подсистеме потоков GLib.
typedef enum { G_THREAD_ERROR_AGAIN /* Ресурс временно не доступен */ } GThreadError;
Возможные ошибки связанные с функциями потока.
typedef struct { GMutex* (*mutex_new) (void); void (*mutex_lock) (GMutex *mutex); gboolean (*mutex_trylock) (GMutex *mutex); void (*mutex_unlock) (GMutex *mutex); void (*mutex_free) (GMutex *mutex); GCond* (*cond_new) (void); void (*cond_signal) (GCond *cond); void (*cond_broadcast) (GCond *cond); void (*cond_wait) (GCond *cond, GMutex *mutex); gboolean (*cond_timed_wait) (GCond *cond, GMutex *mutex, GTimeVal *end_time); void (*cond_free) (GCond *cond); GPrivate* (*private_new) (GDestroyNotify destructor); gpointer (*private_get) (GPrivate *private_key); void (*private_set) (GPrivate *private_key, gpointer data); void (*thread_create) (GThreadFunc func, gpointer data, gulong stack_size, gboolean joinable, gboolean bound, GThreadPriority priority, gpointer thread, GError **error); void (*thread_yield) (void); void (*thread_join) (gpointer thread); void (*thread_exit) (void); void (*thread_set_priority)(gpointer thread, GThreadPriority priority); void (*thread_self) (gpointer thread); gboolean (*thread_equal) (gpointer thread1, gpointer thread2); } GThreadFunctions;
Эта таблица функций используется g_thread_init()
для инициализации системы потоков.
Функции в таблице непосредственно используются их копиями с предустановленным в названиях g_* (описаны в данном документе). Например, если вы вызвали g_mutex_new()
, тогда будет вызвана mutex_new()
из таблицы g_thread_init()
.
Не используйте эту структуры если не уверены в том что делаете.
void g_thread_init (GThreadFunctions *vtable);
Если вы используете GLib из более одного потока, вы должны инициализировать систему потоков
вызовом g_thread_init()
. В основном вам нужно вызывать g_thread_init (NULL)
.
Не вызывайте g_thread_init()
с не-NULL
параметром если не уверены в том что делаете.
g_thread_init()
не должна вызываться непосредственно или косвенно как callback из GLib. Также взаимоисключения не могут
блокироваться в течении вызова g_thread_init()
.
g_thread_init()
можно вызвать только один раз. Второй вызов вернёт ошибку. Если вы хотите убедиться в том что
система потоков инициализирована, вы можете сделать следующее:
if (!g_thread_supported ()) g_thread_init (NULL);
После этой команды либо инициализируется система потоков либо, ели нет доступной системы потоков в GLib (то есть либо G_THREADS_ENABLED не определён, либо определён G_THREADS_IMPL_NONE), программа будет отменена.
Если нет доступной системы потоков и параметр vtable
равен NULL
, или если не все элементы vtable
являются не-NULL
, то g_thread_init()
будет отменён.
Для использования g_thread_init()
в вашей программе, вы должны привязаться к библиотекам которые выдаёт команда
pkg-config --libs gthread-2.0.
Это не касается остальных связанных с потоками функций GLib. Они могут использоваться без привязки
к потоковым библиотекам.
vtable : |
таблица функций типа GThreadFunctions, которые обеспечивают точки входа в используемую систему потоков. |
gboolean g_thread_supported ();
Эта функция возвращает TRUE
если система потоков инициализирована, а
FALSE
если нет.
Эта функция является фактически макрокомандой. Однако, кроме захвата адреса её можно использовать как функуию.
Возвращает : |
TRUE , если система потоков инициализирована.
|
gpointer (*GThreadFunc) (gpointer data);
Определяет тип функций func
помещаемых в
g_thread_create()
или
g_thread_create_full()
.
data : |
данные помещаемые в поток. |
Возвращает : | значение возвращаемое потоком, которое будет возвращено
g_thread_join() .
|
typedef enum { G_THREAD_PRIORITY_LOW, G_THREAD_PRIORITY_NORMAL, G_THREAD_PRIORITY_HIGH, G_THREAD_PRIORITY_URGENT } GThreadPriority;
Определяет приоритет потока.
Не гарантируется что потоки с разными приоритетами будут вести себя соответственно. В некоторых системах (например Linux) нет приоритетов потоков. В других системах (например Solaris) существует разное планирование для разных приоритетов. В основном пытайтесь избегать зависимости от приоритетов.
typedef struct { } GThread;
GThread структура представляет выполняемый поток. Она имеет три общих элемента доступных только для чтения, но основных в структуре больше, поэтому вы не должны копировать эту структуру.
Ресурсы для объединяемого потока реализуются не полностью пока для этого потока вызвана
g_thread_join()
.
GThread* g_thread_create (GThreadFunc func, gpointer data, gboolean joinable, GError **error);
Эта функция создаёт новый поток с приоритетом по умолчанию.
Если joinable
равен TRUE
, вы можете подождать завершения потоков вызывающих
g_thread_join()
. Иначе поток просто исчезнет когда она завершиться.
Новый поток выполняет функцию func
с параметром
data
. Если поток был создан успешно, он возвращается.
error
может быть NULL
для игнорирования ошибок, или не-NULL
для сообщения об ошибках. Ошибка устанавливается только если функция возвращает NULL
.
func : |
функция выполняемая в новом потоке. |
data : |
аргумент поставляемый новому потоку. |
joinable : |
должен ли поток быть объединяемым? |
error : |
размещение для возвращаемой ошибки. |
Возвращает : | новый GThread при успешном выполнении. |
GThread* g_thread_create_full (GThreadFunc func, gpointer data, gulong stack_size, gboolean joinable, gboolean bound, GThreadPriority priority, GError **error);
Эта функция создаёт поток с приоритетом priority
.
Если реализация потока поддерживает это, поток получает размер стека
stack_size
или значение по умолчанию для текущей платформы,
если stack_size
это 0.
Если joinable
равно TRUE
, вы можете подождать завершения вызова
g_thread_join()
для потока.
Иначе поток просто исчезнет при завершении. Если bound
равен TRUE
, этот поток
будет планироваться в системной области, иначе реализация это свободно выполняемое планирование в
пределах процесса. Первый вариант более требователен к ресурсам, но в общем быстрее.
В некоторых системах (например Linux) все потоки связаны.
Новый поток выполняет функцию func
с аргументом
data
. Если поток был успешно создан, он возвращается.
error
может быть NULL
для игнорирования ошибок, или не-NULL
для сообщения об ошибках. Ошибка устанавливается, только если функция вернула NULL
.
Не гарантируется что потоки с разными приоритетами будут вести себя соответственно.
В некоторых системах (например Linux) нет приоритетов потоков.
В других системах (например Solaris) существует разное планирование для разных приоритетов.
В основном пытайтесь избегать зависимости от приоритетов.
Используйте G_THREAD_PRIORITY_NORMAL
здесь как значение по умолчанию.
Используйте g_thread_create_full()
только если вы действительно не можете использовать
g_thread_create()
вместо неё.
g_thread_create()
не применяет stack_size
, bound
, и priority
как аргументы, поскольку они должны использоваться только если это явно не избежно.
func : |
функция для выполнения в новом потоке. |
data : |
аргумент поставляемый в новый поток. |
stack_size : |
размер стека для нового потока. |
joinable : |
должен ли этот поток быть объединяемым? |
bound : |
должен ли этот поток привязываться к системе потоков? |
priority : |
приоритет потока. |
error : |
расположение для возвращаемой ошибки. |
Возвращает : | новый GThread при удачном выполнении. |
GThread* g_thread_self (void);
Эта функция возвращает GThread соответствующий вызываемому потоку.
Возвращает : | текущий поток. |
gpointer g_thread_join (GThread *thread);
Ждёт завершения thread
, то есть функции func
, полученной в g_thread_create()
, возврат или g_thread_exit()
вызванный thread
.
Все ресурсы thread
включая структуру GThread освобождаются.
thread
должен быть создан с joinable
=TRUE
в g_thread_create()
. Значение возвращаемое func
или полученное в
g_thread_exit()
thread
возвращается этой функцией.
thread : |
GThread из которого ожидается результат. |
Возвращает : | возвращаемое потоком значение. |
void g_thread_set_priority (GThread *thread, GThreadPriority priority);
Изменяет приоритет thread
в значение priority
.
Не гарантируется что потоки с разными приоритетами будут вести себя соответственно. В некоторых системах (например Linux) нет приоритетов потоков. В других системах (например Solaris) существует разное планирование для разных приоритетов. В основном пытайтесь избегать зависимости от приоритетов.
thread : |
GThread. |
priority : |
новый приоритет для thread .
|
void g_thread_yield ();
Позволяет запланировать другой поток.
Эта функция часто используется как метод для создания занятого ожидания менее вредным. Но в большинстве случаев есть лучше методы для этого. Поэтому в основном вы не должны использовать эту функцию.
void g_thread_exit (gpointer retval);
Выход из текущего потока. Если другой поток ожидает завершение этого потока используя функцию
g_thread_join()
и
текущий поток является совмещённым, то ожидающий поток будет разбужен и получит
retval
как возвращаемое значение
g_thread_join()
.
Если текущий поток не совмещён, retval
игнорируется.
Вызов
g_thread_exit (retval);
эквивалентен вызову
return retval;
в функции func
, полученной в g_thread_create()
.
Никогда не вызывайте g_thread_exit()
внутри потока GThreadPool, так как это запутает расчеты и приведёт к нежелательным последствиям.
retval : |
значение возвращаемое этим потоком. |
void g_thread_foreach (GFunc thread_func, gpointer user_data);
Вызывает thread_func
на всех существующих структурах GThread. Помните, что потоки могут
принять решение о выходе в то время как thread_func
выполняется, поэтому без близкого знания продолжительности жизни внешних потоков,
thread_func
не имеет доступа к указателю GThread*
помещаемому в первый аргумент. Однако, thread_func
не будет вызвана для потоков выход из которых уже совершён.
Из-за проверок жизненного цикла потока, эта функция имеет сложности при выполнении которые взводятся в степень количества существующих потоков.
thread_func : |
функция вызываемая для всех структур GThread |
user_data : |
второй аргумент для thread_func
|
Начиная с версии 2.10
typedef struct _GMutex GMutex;
Структура GMutex - закрытая структура данных представляющая взаимоисключения (mutex - mutual exclusion). Она может использоваться для защиты данных от совместного доступа. Возьмём например следующую функцию:
Пример 3. Функция которая не будет работать в потоковом окружении
int give_me_next_number () { static int current_number = 0; /* теперь выполняем очень cложное вычисление для расчёта нового числа, это может быть например генератор случайных чисел */ current_number = calc_next_number (current_number); return current_number; }
Просто заметить что это не будет работать в многопоточных приложениях. Переменная current_number должна быть защищена от совместного доступа. Первая наивная реализация могла бы быть такой:
Пример 4. Не правильный способ создания потоко-безопасной функции
int give_me_next_number () { static int current_number = 0; int ret_val; static GMutex * mutex = NULL; if (!mutex) mutex = g_mutex_new (); g_mutex_lock (mutex); ret_val = current_number = calc_next_number (current_number); g_mutex_unlock (mutex); return ret_val; }
Похоже что это должно работать, но есть условие гонки пока создаётся взаимоисключение и этот код не может надежно работать. Пожалуйста не используйте эту конструкцию в собственных программах! Вот одно работающее решение:
Пример 5. A correct thread-safe function
static GMutex *give_me_next_number_mutex = NULL; /* эта функция должна быть вызвана перед любым вызовом give_me_next_number () она должна вызываться только один раз. */ void init_give_me_next_number () { g_assert (give_me_next_number_mutex == NULL); give_me_next_number_mutex = g_mutex_new (); } int give_me_next_number () { static int current_number = 0; int ret_val; g_mutex_lock (give_me_next_number_mutex); ret_val = current_number = calc_next_number (current_number); g_mutex_unlock (give_me_next_number_mutex); return ret_val; }
GStaticMutex обеспечивает более простой и безопасный способ выполнения этого.
Если вы хотите использовать взаимоисключения и ваш код должен также работать не вызывая сначала
g_thread_init()
,
то вы не можете использовать GMutex, так как
g_mutex_new()
требует инициализации системы потоков.
Вместо этого используйте GStaticMutex.
Доступ к GMutex должен производиться только с помощью функций описанных ниже.
Все g_mutex_*
функции фактически являются макрокомандами.
Кроме взятия адреса, вы можете однако использовать их как будто они являются функциями.
GMutex* g_mutex_new ();
Создаёт новую структуру GMutex.
Эта функция прерывается если не вызвана g_thread_init()
.
Возвращает : | новая структура GMutex. |
void g_mutex_lock (GMutex *mutex);
Блокирует mutex
. Если mutex
уже блокирован другим потоком, то текущий поток блокируется пока mutex
не будет разблокирован.
Эта функция может использоваться даже если g_thread_init()
не была вызвана, в этом случае она не делает ничего.
GMutex не гарантирует не рекурсию не её отсутсвие, то есть поток может зависнуть вызывая g_mutex_lock()
, если она уже заблокировала mutex
.
Используйте GStaticRecMutex, если вам нужны рекурсивные взаимоисключения.
mutex : |
GMutex. |
gboolean g_mutex_trylock (GMutex *mutex);
Пытается блокировать mutex
. Если mutex
уже заблокирован другим потоком, она немедленно возвращает FALSE
. Иначе блокируется mutex
и возвращается TRUE
.
Эта функция может использоваться даже если g_thread_init()
не была вызвана,
в этом случае она немедленно вернёт TRUE
.
GMutex не гарантирует рекурсию не её отсутсвие,
то есть возвращаемое значение g_mutex_trylock()
может быть и FALSE
и
TRUE
, если текущий поток уже заблокировал mutex
.
Используйте GStaticRecMutex, если вам нужны рекурсивные взаимоисключения.
void g_mutex_unlock (GMutex *mutex);
Разблокирует mutex
. Если другой поток блокирован в g_mutex_lock()
вызовом для mutex
, то он будет разбужен и сможет заблокировать mutex
самостоятельно.
Эта функция может использоваться даже если g_thread_init()
не была вызвана, в этом случае она ничего не делает.
mutex : |
GMutex. |
typedef struct _GStaticMutex GStaticMutex;
GStaticMutex работает также как GMutex, но имеет одно существенное преимущество. Она не должна создаваться во время выполнения как GMutex,
а может быть определена во время компиляции. Вот более короткий и более безопасный пример нашей
функции
:
give_me_next_number()
Пример 6. Использование GStaticMutex для упрощения потокобезопасного программирования
int give_me_next_number () { static int current_number = 0; int ret_val; static GStaticMutex mutex = G_STATIC_MUTEX_INIT; g_static_mutex_lock (&mutex); ret_val = current_number = calc_next_number (current_number); g_static_mutex_unlock (&mutex); return ret_val; }
Иногда вам может понадобиться создавать динамические взаимоисключения. Если вы не хотите
предварительно вызывать g_thread_init()
, потому что ваш код должен также использоваться в не потоковых программах,
вы не сможете использовать g_mutex_new()
а также GMutex,
так как требуется предварительный вызов g_thread_init()
. В этом случае вы также можете использовать GStaticMutex.
Она должна быть инициализирована перед использованием с помощью g_static_mutex_init()
и освобождена с помощью g_static_mutex_free()
когда нет больше никаких освобождаемых распределённых ресурсов.
Даже при том, что GStaticMutex не непрозрачная структура, она должна использоваться только следующими функциями, так как она определяется по разному на разных платформах.
Все функции g_static_mutex_*
могут использоваться даже если не
была вызвана g_thread_init()
.
Все функции g_static_mutex_*
фактически являются макросами.
Однако, кроме взятия адреса, вы можете использовать их как функции.
#define G_STATIC_MUTEX_INIT
С помощью этого макроса должна инициализироваться GStaticMutex, перед использованием.
Этот макрос может использоваться для инициализации переменной, но он не может присваиваться
переменной. В этом случае вы должны использовать
g_static_mutex_init()
.
GStaticMutex my_mutex = G_STATIC_MUTEX_INIT;
void g_static_mutex_init (GStaticMutex *mutex);
Инициализирует mutex
. Альтернативно его можно инициализировать с помощью
G_STATIC_MUTEX_INIT.
mutex : |
GStaticMutex для инициализации. |
void g_static_mutex_lock (GStaticMutex *mutex);
Работает как g_mutex_lock()
, но для GStaticMutex.
mutex : |
GStaticMutex. |
gboolean g_static_mutex_trylock (GStaticMutex *mutex);
Работает как g_mutex_trylock()
, но для GStaticMutex.
mutex : |
GStaticMutex. |
Возвращает : |
TRUE , если GStaticMutex может быть заблокирован.
|
void g_static_mutex_unlock (GStaticMutex *mutex);
Работает как g_mutex_unlock()
, но для GStaticMutex.
mutex : |
GStaticMutex. |
GMutex* g_static_mutex_get_mutex (GStaticMutex *mutex);
Для некоторых операций (как g_cond_wait()
) вы должны использовать GMutex
вместо GStaticMutex.
Эта функция соответственно возвращает GMutex для mutex
.
mutex : |
GStaticMutex. |
Возвращает : | GMutex соответствующий mutex .
|
void g_static_mutex_free (GStaticMutex *mutex);
Освобождает все ресурсы распределённые для mutex
.
Вы не должны вызывать эту функцию для GStaticMutex с неограниченным жизненным циклом, то есть для объектов объявленных как 'static', но если GStaticMutex является членом структуры и структура освобождается, вы должны также освободить GStaticMutex.
mutex : |
GStaticMutex для освобождения. |
#define G_LOCK_DEFINE(name)
Макрос G_LOCK_
* обеспечивает удобный интерфейс для
GStaticMutex
с преимуществом распространения для программ скомпилированных без поддержки потоков GLib, сохраняя
код и память. G_LOCK_DEFINE определяет блокировку. Он может появляться там же где могут появляться переменные в программах,
то есть в первом блоке функции или вне функций. Параметр name
будет изменён для получения имени GStaticMutex. Это значит что вы можете использовать имена существующих переменных как
параметр - например имя переменной вы можете защитить с помощью блокировки. Рассмотрим наш пример
с использованием give_me_next_number()
G_LOCK_
* macros:
Пример 7. Использование удобного макроса G_LOCK_
*
G_LOCK_DEFINE (current_number); int give_me_next_number () { static int current_number = 0; int ret_val; G_LOCK (current_number); ret_val = current_number = calc_next_number (current_number); G_UNLOCK (current_number); return ret_val; }
name : |
имя блокировки. |
#define G_LOCK_DEFINE_STATIC(name)
Работает также как G_LOCK_DEFINE, но создаёт статический объект.
name : |
имя блокировки. |
#define G_LOCK_EXTERN(name)
Объявляет блокировку, которая определена с помощью G_LOCK_DEFINE в другом модуле.
name : |
имя блокировки. |
#define G_LOCK(name)
Работает также как g_mutex_lock()
, но для блокировки определённой с помощьюG_LOCK_DEFINE.
name : |
имя блокировки. |
#define G_TRYLOCK(name)
Работает также как g_mutex_trylock()
, но для блокировки определённой с помощью G_LOCK_DEFINE.
name : |
имя блокировки. |
Возвращает : |
TRUE , если блокировка может быть блокирована.
|
#define G_UNLOCK(name)
Работает также как g_mutex_unlock()
, но для блокировки определённой с помощью G_LOCK_DEFINE.
name : |
имя блокировки. |
typedef struct { } GStaticRecMutex;
GStaticRecMutex работает также как GStaticMutex, но он может быть блокирован множество раз одним потоком.
Если вы ввели его n раз, вы должны разблокировать его n раз позволяя другим потокам блокировать его.
Исключением является функция g_static_rec_mutex_unlock_full()
: она позволяет вам разблокировать GStaticRecMutex на всю глубину полностью, (то есть на то количество раз на которое был заблокирован этот объект mutex).
Глубина может позже использоваться для восстановления состояния GStaticRecMutex с помощью вызова
g_static_rec_mutex_lock_full()
.
Даже при том, что GStaticRecMutex не является закрытой, она должна использоваться только следующими функциями.
Все функции g_static_rec_mutex_*
могут использоваться даже если не
была вызвана g_thread_init()
.
#define G_STATIC_REC_MUTEX_INIT { G_STATIC_MUTEX_INIT }
GStaticRecMutex должна быть инициализирована с помощью макроса перед использованием.
Этот макрос может использоваться для инициализации переменных, но он не должен назначаться переменным. Для этого случая используется g_static_rec_mutex_init()
.
GStaticRecMutex my_mutex = G_STATIC_REC_MUTEX_INIT;
void g_static_rec_mutex_init (GStaticRecMutex *mutex);
GStaticRecMutex должна инициализироваться с помощью этой функции перед использованием. Альтернативно вы можете инициализировать её с помощью G_STATIC_REC_MUTEX_INIT.
mutex : |
GStaticRecMutex для инициализации. |
void g_static_rec_mutex_lock (GStaticRecMutex *mutex);
Блокирует mutex
. Если mutex
уже заблокирован другим потоком, текущий поток будет заблокирован пока mutex
не разблокируется. Если mutex
уже заблокирован вызываемым потоком, эта функция увеличит глубину блокировки mutex
и немедленно возвратит.
mutex : |
GStaticRecMutex для блокирования. |
gboolean g_static_rec_mutex_trylock (GStaticRecMutex *mutex);
Пытается блокировать mutex
. Если mutex
уже заблокирован другим потоком,
она немедленно возвращает FALSE
. Иначе mutex
блокируется и возвращается TRUE
. Если mutex
уже заблокирован вызываемым потоком, эта функция увеличивает глубину блокировки mutex
и немедленно возвращает TRUE
.
mutex : |
GStaticRecMutex для блокировки. |
Возвращает : |
TRUE , если mutex может быть заблокирован.
|
void g_static_rec_mutex_unlock (GStaticRecMutex *mutex);
Разблокирует mutex
. Другой поток может быть допущен к блокировки mutex
только когда он будет разблокирован такое же количество раз сколько раз был заблокирован перед этим.
Если mutex
полностью разблокирован а другой поток блокирован в g_static_rec_mutex_lock()
вызове для mutex
, он будет разбужен и сможет заблокировать mutex
самостоятельно.
mutex : |
GStaticRecMutex для разблокирования. |
void g_static_rec_mutex_lock_full (GStaticRecMutex *mutex, guint depth);
Работает также как вызов g_static_rec_mutex_lock()
для mutex
depth
раз.
mutex : |
GStaticRecMutex для разблокирования. |
depth : |
количество разблокирований для полного разблокирования. |
guint g_static_rec_mutex_unlock_full (GStaticRecMutex *mutex);
Полностью разблокирует mutex
. Если другой поток блокирован в g_static_rec_mutex_lock()
вызове для mutex
, он будет разбужен и сможет заблокировать mutex
самостоятельно. Эта функция возвращает количество раз которое mutex
был заблокирован текущим потоком.
Для восстановления состояния перед вызовом g_static_rec_mutex_unlock_full()
вы можете вызвать
g_static_rec_mutex_lock_full()
с глубиной возвращаемой этой функцией.
mutex : |
GStaticRecMutex для полного разблокирования. |
Возвращает : | количество раз которым mutex был заблокирован текущим процессом.
|
void g_static_rec_mutex_free (GStaticRecMutex *mutex);
Освобождает все ресурсы распределённые для GStaticRecMutex.
Вы не должны вызывать эту функцию для GStaticRecMutex с безграничным жизненным циклом, то есть для объектов объявленных как 'static', но если GStaticRecMutex является членом освобождаемой структуры, вы должны также освободить GStaticRecMutex.
mutex : |
GStaticRecMutex для освобождения. |
typedef struct { } GStaticRWLock;
Структура GStaticRWLock представляет блокировку чтения-записи. Блокировка чтения-записи может использоваться для защиты данных которые некоторые части кода только читают, в то время как другие также записывают. В таких ситуациях конечно лучше чтобы читать могли несколько процессов/потоков одновременно, а писать только один. Рассмотрим следующий пример:
Пример 8. Массив с функциями доступа
GStaticRWLock rwlock = G_STATIC_RW_LOCK_INIT; GPtrArray *array; gpointer my_array_get (guint index) { gpointer retval = NULL; if (!array) return NULL; g_static_rw_lock_reader_lock (&rwlock); if (index < array->len) retval = g_ptr_array_index (array, index); g_static_rw_lock_reader_unlock (&rwlock); return retval; } void my_array_set (guint index, gpointer data) { g_static_rw_lock_writer_lock (&rwlock); if (!array) array = g_ptr_array_new (); if (index >= array->len) g_ptr_array_set_size (array, index+1); g_ptr_array_index (array, index) = data; g_static_rw_lock_writer_unlock (&rwlock); }
Этот пример демонстрирует массив доступ к которому позволен многим "читателям"
(
функция) одновременно,
тогда как "писателям" (my_array_get()
функция)
он доступен только одному за раз и только если нет "читателей" обращающихся к массиву в текущий
момент. Это из-за потенциальной опасности изменения размера массива. При таком использовании функции полностью безопасны в много-поточности.
my_array_set()
В большинстве случаев, "писатель" должен иметь преимущество перед "читателями". Это значит, для этой реализации, как только "писатель" захочет блокировать данные никому из "читателей" не позволено блокировать их, хотя "читателям" которые уже блокировали данные конечно позволено завершить свои операции. Как только последний "читатель" разблокировал данные, "писатель" блокирует их.
Даже при том, что структура GStaticRWLock не является закрытой, доступ к ней должен осуществляться только с помощью функций описанных ниже.
Все функции g_static_rw_lock_*
могут использоваться даже если
g_thread_init()
не была вызвана.
Блокировка чтение-запись имеет приоритет над взаимоисключениями (mutex). Например, обе
g_static_rw_lock_reader_lock()
и g_static_rw_lock_reader_unlock()
должны блокировать и разблокировать GStaticMutex, поэтому по крайней мере дважды блокируется и разблокируется
GStaticRWLock который в свою очередь блокирует и разблокирует GStaticMutex. Таким образом структуры данных которые доступны для множества "читателей"
и которые сохраняют блокировку в течении длительного времени оправдывают GStaticRWLock. Выше упомянутый пример вероятней всего
намного лучше использовать с GStaticMutex.
#define G_STATIC_RW_LOCK_INIT { G_STATIC_MUTEX_INIT, NULL, NULL, 0, FALSE, 0, 0 }
GStaticRWLock должна быть инициализирована макросом перед использованием. Этот макрос может использоваться для инициализации переменных, но он не должен присваиваться переменным. В этом случае вы должны использовать
g_static_rw_lock_init()
.
GStaticRWLock my_lock = G_STATIC_RW_LOCK_INIT;
void g_static_rw_lock_init (GStaticRWLock *lock);
GStaticRWLock должна быть инициализирована с помощью этой функции перед использованием. Альтернативно вы можете инициализировать её с помощью G_STATIC_RW_LOCK_INIT.
lock : |
GStaticRWLock для инициализации. |
void g_static_rw_lock_reader_lock (GStaticRWLock *lock);
Блокирует lock
для чтения. Могут быть бесконечные параллельные блокировки для одновременного чтения GStaticRWLock. Если lock
уже заблокирован для записи другим потоком или если другой поток уже ожидает блокировки lock
для записи, эта функция будет блокирована пока lock
не разблокирует другой поток записи и никакие другие потоки не ожидают блокировки lock
. Эта блокировка должна разблокироваться с помощью g_static_rw_lock_reader_unlock()
.
GStaticRWLock не имеет рекурсии. Это может показаться возможным для рекурсивной блокировки чтения, но может привести к зависанию из-за привилегий "писателя".
lock : |
GStaticRWLock для блокировки чтения. |
gboolean g_static_rw_lock_reader_trylock (GStaticRWLock *lock);
Пытается блокировать lock
для чтения. Если lock
уже заблокирован для записи другим потоком или другой поток уже ожидает блокировку lock
для записи, немедленно возвращает FALSE
. Иначе блокирует
lock
для чтения и возвращает TRUE
. Эта блокировка должна разблокироваться с помощью g_static_rw_lock_reader_unlock()
.
lock : |
GStaticRWLock для блокирования чтения. |
Возвращает : |
TRUE , если lock можно блокировать для чтения.
|
void g_static_rw_lock_reader_unlock (GStaticRWLock *lock);
Разблокирует lock
. Если поток ожидает блокировку lock
для записи и все блокировки для чтения были разблокированы,
ожидающий поток пробуждается и может заблокировать lock
для записи.
lock : |
GStaticRWLock для разблокирования после чтения. |
void g_static_rw_lock_writer_lock (GStaticRWLock *lock);
Блокирует lock
для записи. Если lock
уже заблокирован для записи или чтения другим потоком, эта функция блокируется до тех пор пока lock
полностью не разблокируется а затем блокирует lock
для записи. Пока эта функция ожидает блокировки lock
, другие потоки не могут блокировать lock
для чтения. Когда lock
заблокирован для записи, другие потоки не могут блокировать lock
(не для чтения не для записи). Эта блокировка должна разблокироваться с помощью g_static_rw_lock_writer_unlock()
.
lock : |
GStaticRWLock блокируемая для записи. |
gboolean g_static_rw_lock_writer_trylock (GStaticRWLock *lock);
Пытается блокировать lock
для записи. Если lock
уже заблокирован (для записи или чтенияg) другим потоком, она немедленно возвращает FALSE
.
Иначе блокирует lock
для записи и возвращает TRUE
.
Эта блокировка должна быть разблокирована с помощью g_static_rw_lock_writer_unlock()
.
lock : |
GStaticRWLock блокируемая для записи. |
Возвращает : |
TRUE , если lock может блокироваться для записи.
|
void g_static_rw_lock_writer_unlock (GStaticRWLock *lock);
Разблокирует lock
. Если поток ожидает блокировки lock
для записи и все блокировки для чтения разблокированы, ожидающий поток просыпается и может блокировать lock
для записи. Если не тпотоков ожидающих блокировки lock
для записи, а некоторые потоки ожидают блокировку lock
для чтения, ожидающие потоки просыпаются и могут блокировать lock
для чтения.
lock : |
GStaticRWLock для разблокирования после записи. |
void g_static_rw_lock_free (GStaticRWLock *lock);
Освобождает все ресурсы распределённые для lock
.
Вы не должны вызывать эту функцию для GStaticRWLock с безграничным жизненным циклом, то есть для объектов объявленных статическими 'static', но если GStaticRWLock является частью структуры и структура освобождается, то вы также должны освободить GStaticRWLock.
lock : |
GStaticRWLock для освобождения. |
typedef struct _GCond GCond;
Структура GCond является закрытой структурой данных представляющих условие. Потоки могут блокироваться на GCond если они обнаружат определённое ложное условие. Если другие потоки изменяют состояние этого условия они сообщают GCond и тогда ожидающий поток просыпается.
Пример 9. Использование GCond для блокировки потока пока условие не удавлетворено
GCond* data_cond = NULL; /* Должен быть где-нибудь инициализирован */ GMutex* data_mutex = NULL; /* Должен быть где-нибудь инициализирован */ gpointer current_data = NULL; void push_data (gpointer data) { g_mutex_lock (data_mutex); current_data = data; g_cond_signal (data_cond); g_mutex_unlock (data_mutex); } gpointer pop_data () { gpointer data; g_mutex_lock (data_mutex); while (!current_data) g_cond_wait (data_cond, data_mutex); data = current_data; current_data = NULL; g_mutex_unlock (data_mutex); return data; }
Теперь, каждый раз когда поток вызывает
, он будет ждать пока current_data будет не-pop_data()
NULL
, то есть пока какой-нибудь поток вызовет
.
push_data()
Важно использовать g_cond_wait()
и g_cond_timed_wait()
функции только внутри цикла который проверяет правильность условия.
Не гарантируется что ожидающий поток будет искать условие выполнения после пробуждения,
даже если сообщающий поток сбросит условие в это состояние: другой поток может переключить
условие прежде чем ожидающий поток проснётся, даже если само условие защищено с помощью GMutex, как описано выше.
GCond доступна только через функции описанные далее.
Все g_cond_*
функции фактически являются макросами.
Однако, за исключением взятия адреса, вы можете использовать их как функции.
GCond* g_cond_new ();
Создаёт новую GCond. Эта функция прерывается, если не была вызвана g_thread_init()
.
Возвращает : | новая GCond. |
void g_cond_signal (GCond *cond);
Если потоки ожидают условие cond
, только один из них пробуждается. Хорошая практика удерживать блокировку ожидающего потока пока вызывается эта функция, хотя и необязательно.
Эта функция может использоваться даже если g_thread_init()
не была вызвана, в этом случае она ничего не делает.
cond : |
GCond. |
void g_cond_broadcast (GCond *cond);
Если потоки ожидают условие cond
, все они пробуждаются. Хорошей практикой является блокирование ожидающих потоков некоторым взаимоисключением (mutex), пока вызывается эта функция, хотя не обязательно.
Эта функция может использоваться даже если g_thread_init()
не была вызвана, в этом случае она ничего не делает.
cond : |
GCond. |
void g_cond_wait (GCond *cond, GMutex *mutex);
Заставляет поток ждать условие cond
. Взаимоисключение mutex
разблокируется перед отключением и блокируется после возобнавления.
Эта функция может использоваться даже если g_thread_init()
не была вызвана, в этом случае она немедленно возвращает результат.
gboolean g_cond_timed_wait (GCond *cond, GMutex *mutex, GTimeVal *abs_time);
Заставляет поток ждать условия пробуждения cond
, но не дольше чем определено параметром abs_time
. Взаимоисключение mutex
разблокируется перед отключением и блокируется снова после возобнавления.
Если abs_time
равен NULL
, g_cond_timed_wait()
действует как g_cond_wait()
.
Эта функция может использоваться даже если g_thread_init()
не была вызвана, в этом случае она немедленно возвращает TRUE
.
Для простоты вычисления abs_time
может использоваться комбинация g_get_current_time()
и g_time_val_add()
.
typedef struct _GPrivate GPrivate;
Структура GPrivate является закрытой структурой данных представляющая индивидуальные ключевые данные для потоков. Потоки таким образом могут устанавливать и получать указатели которые индивидуальны для текущего потока.
Возьмём наш выше приведенный пример
.
Предположим что мы не хотим чтобы переменная give_me_next_number()
current_number
распределялясь между потоками, а вместо этого была бы индивидуальной для каждого потока.
Это можно сделать следующим образом:
Пример 10. Using GPrivate for per-thread data
GPrivate* current_number_key = NULL; /* Должна быть где-нибудь инициализирована */ /* с помощью g_private_new (g_free); */ int give_me_next_number () { int *current_number = g_private_get (current_number_key); if (!current_number) { current_number = g_new (int,1); *current_number = 0; g_private_set (current_number_key, current_number); } *current_number = calc_next_number (*current_number); return *current_number; }
Здесь указатель принадлежащий ключу current_number_key
читается. Если он равен NULL
, то не устанавливается. Затем получаем память для целочисленного значения,
привязываем эту память к указателю и записываем указатель обратно.
Теперь мы имеем целочисленное значение которое индивидуально для текущего потока.
К структуре GPrivate должны обращаться только следующие функции.
Все функции g_private_*
фактически являются макросами.
Однако, за исключением взятия адреса, вы можете использовать их как обычные функции.
GPrivate* g_private_new (GDestroyNotify destructor);
Создаёт новую GPrivate. Если destructor
не-NULL
, то указывает на разрушающую функцию.
Каждый раз когда поток завершается и ключевой указатель соответствующий этому образцу GPrivate не является NULL
, разрушающая функция вызывается с этим указателем в качестве параметра.
destructor
используется иначе чем notify
в
g_static_private_set()
.
GPrivate не может освобождаться. Вместо этого используйте её повторно, или используйте GStaticPrivate.
Эта функция прерывается если g_thread_init()
не была вызвана.
gpointer g_private_get (GPrivate *private_key);
Возвращает ключевой указатель private_key
для текущего потока.
Если g_private_set()
не была вызвана для текущего private_key
и потока, этот указатель будет NULL
.
Эта функция может использоваться даже если g_thread_init()
не была вызвана,
в этом случае она возвращает значение private_key
приведённый к gpointer.
private_key : |
GPrivate. |
Возвращает : | соответсвующий указатель. |
void g_private_set (GPrivate *private_key, gpointer data);
Устанавливает ключевой указатель private_key
для текущего потока.
Эта функция может использоваться даже если g_thread_init()
не была вызвана,
в этом случае будет установлен private_key
в data
приведенный к GPrivate*.
private_key : |
GPrivate. |
data : |
новый указатель. |
typedef struct { } GStaticPrivate;
GStaticPrivate
работает также как GPrivate,
но имеет одно существенное приимущество. Она не должна создаваться во время выполнения как
GPrivate, а может быть определена во время компиляции. Это подобно различию между
GMutex и GStaticMutex. Теперь взглянем на наш пример
с использованием GStaticPrivate:
give_me_next_number()
Пример 11. Использование GStaticPrivate в качестве потоковых данных
int give_me_next_number () { static GStaticPrivate current_number_key = G_STATIC_PRIVATE_INIT; int *current_number = g_static_private_get (¤t_number_key); if (!current_number) { current_number = g_new (int,1); *current_number = 0; g_static_private_set (¤t_number_key, current_number, g_free); } *current_number = calc_next_number (*current_number); return *current_number; }
#define G_STATIC_PRIVATE_INIT
Все GStaticPrivate перед использованием должны быть инициализированы этим макросом.
GStaticPrivate my_private = G_STATIC_PRIVATE_INIT;
void g_static_private_init (GStaticPrivate *private_key);
Инициализирует private_key
. Альтернативно вы можете инициализировать его с помощью
G_STATIC_PRIVATE_INIT.
private_key : |
GStaticPrivate для инициализации. |
gpointer g_static_private_get (GStaticPrivate *private_key);
Работает также как g_private_get()
только для GStaticPrivate.
Эта функция работает даже если g_thread_init()
не была вызвана.
private_key : |
GStaticPrivate. |
Возвращает : | соответствующий указатель. |
void g_static_private_set (GStaticPrivate *private_key, gpointer data, GDestroyNotify notify);
Устанавливает ключевой указатель private_key
для текущего потока и функцию notify
вызываемую с этим указателем (NULL
или не-NULL
),
каждый раз когда указатель установлен снова или каждый раз когда текущий поток завершается.
Эта функция работает даже если g_thread_init()
не была вызвана.
Если g_thread_init()
вызвана позже, то data
ключевые для private_key
будут унаследованы только основным потоком, то есть тем который вызван g_thread_init()
.
notify
используется иначе чем destructor
в
g_private_new()
.
private_key : |
GStaticPrivate. |
data : |
новый указатель. |
notify : |
функция вызываемая с указателем каждый раз когда завершается текущий поток или указатель устанавливается снова. |
void g_static_private_free (GStaticPrivate *private_key);
Освобождает все ресурсы распределённые для private_key
.
Вы не должны вызывать эту функцию для GStaticPrivate с неограниченным жизненным циклом, то есть для объявленной статично 'static', но если GStaticPrivate член структуры и структура освобождается, вы должны также освободить GStaticPrivate.
private_key : |
освобождаемая GStaticPrivate. |
typedef struct { volatile GOnceStatus status; volatile gpointer retval; } GOnce;
Структура GOnce контролирует одноразовую функцию инициализации. Любые одноразовые функции инициализации должны иметь собственную уникальную структуру GOnce.
volatile GOnceStatus status ; |
состояние GOnce |
volatile gpointer retval ; |
возвращаемое значение, если status
равен G_ONCE_STATUS_READY
|
Начиная с версии 2.4
typedef enum { G_ONCE_STATUS_NOTCALLED, G_ONCE_STATUS_PROGRESS, G_ONCE_STATUS_READY } GOnceStatus;
Возвможные состояния одноразовых функций инициализации контролируемые структурой GOnce.
G_ONCE_STATUS_NOTCALLED |
функция не была вызвана. |
G_ONCE_STATUS_PROGRESS |
вызов функции происходит в текущий момент. |
G_ONCE_STATUS_READY |
функия вызвана. |
Начиная с версии 2.4
#define G_ONCE_INIT { G_ONCE_STATUS_NOTCALLED, NULL }
GOnce должна быть инициализирована перед использованием с помощью этого макроса.
GOnce my_once = G_ONCE_INIT;
Начиная с версии 2.4
#define g_once(once, func, arg)
Первый вызов с полученной структурой GOnce struct вызывает функцию func
с полученным аргументом. Последующие вызовы g_once()
с той же структурой GOnce не вызывают func
снова, а возвращают сохранённый результат первого вызова.
Возвращаемое из g_once()
состояние once
будет
G_ONCE_STATUS_READY
.
Например, взаимоисключение или ключевые потоковые данные должны быть созданы только один раз.
В потоковом окружении, вызов g_once()
гарантирует что инициализация преобразована в последовательную форму через множество потоков.
gpointer
get_debug_flags()
{
static GOnce my_once = G_ONCE_INIT;
g_once (&my_once, parse_debug_flags, NULL);
return my_once.retval;
}
once : |
структура GOnce |
func : |
GThreadFunc функция ассоциированная с once . Эта функция вызывается только один раз,
не зависимо от количества раз помещения структуры GOnce в g_once() .
|
arg : |
данные помещаемые в func
|
Начиная с версии 2.4
GThreadPool | Объединённые потоки. |
GAsyncQueue | Отправка асинхронных сообщений между потоками. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GTimer; GTimer* g_timer_new (void); void g_timer_start (GTimer *timer); void g_timer_stop (GTimer *timer); void g_timer_continue (GTimer *timer); gdouble g_timer_elapsed (GTimer *timer, gulong *microseconds); void g_timer_reset (GTimer *timer); void g_timer_destroy (GTimer *timer);
GTimer записывает начальное время и подсчитывает микросекунды прошедшие с этого времени. Это выполняется по разному на разных платформах и может быть сложно получить правильное соответсвие, поэтому GTimer обеспечивает переносимый/удобный интерфейс.
GTimer* g_timer_new (void);
Создаёт новый таймер и начинает отсчёт
(то есть g_timer_start()
не явно вызывается для вас).
Возвращает : | новая структура GTimer. |
void g_timer_start (GTimer *timer);
Отмечает начальное время, так, чтобы следующие вызовы g_timer_elapsed()
сообщали время прошедшее с момента вызова g_timer_start()
.
g_timer_new()
автоматически отмечает начальное время,
поэтому нет необходимости вызывать g_timer_start()
сразу после создания таймера.
timer : |
GTimer. |
void g_timer_stop (GTimer *timer);
Отмечает конечное время, поэтому вызовы g_timer_elapsed()
будут возвращать разницу между конечным и начальным временем.
timer : |
GTimer. |
void g_timer_continue (GTimer *timer);
Возобнавляет работу таймера который был предварительно остановлен с помощью
g_timer_stop()
.
g_timer_stop()
должна быть вызвана перед использованием этой функции.
timer : |
GTimer. |
Начиная с версии 2.4
gdouble g_timer_elapsed (GTimer *timer, gulong *microseconds);
Если timer
был запущен но не остановлен, получает время так как таймер был запущен.
Если timer
был остановлен, получает прошедшее время между между временем начала и временем остановки.
Возвращаемое значение является количеством прошедших секунд, включая любую дробную часть.
Параметр microseconds
бесполезен.
void g_timer_reset (GTimer *timer);
Эта функция бесполезна; достаточно вызвать g_timer_start()
для уже
запущенного таймера для сброса начального времени,
поэтому g_timer_reset()
нет смысла использовать.
timer : |
GTimer. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> GTrashStack; void g_trash_stack_push (GTrashStack **stack_p, gpointer data_p); gpointer g_trash_stack_pop (GTrashStack **stack_p); gpointer g_trash_stack_peek (GTrashStack **stack_p); guint g_trash_stack_height (GTrashStack **stack_p);
GTrashStack это эффективный способ сохранить стек неиспользуемых распределённых участков памяти. Каждый участок памяти должен быть достаточно большим для вмещения gpointer. Это позволяет поддержку стека без дополнительного пространства, так как стек указателей может быть сохранён внутри участка памяти.
Нет функции для создания GTrashStack.
NULL
GTrashStack*
это совершенно правильный пустой стек.
typedef struct { GTrashStack *next; } GTrashStack;
Каждый участок памяти, который помещён в стек, приводится к GTrashStack*.
GTrashStack *next ; |
указатель на предыдущий элемент стека,
сохраняется в первом sizeof (gpointer)
байте элемента.
|
void g_trash_stack_push (GTrashStack **stack_p, gpointer data_p);
Помещает участок памяти в GTrashStack.
stack_p : |
указатель на GTrashStack. |
data_p : |
участок памяти помещаемый в стек. |
gpointer g_trash_stack_pop (GTrashStack **stack_p);
Выталкивает участок памяти из GTrashStack.
stack_p : |
указатель на GTrashStack. |
Возвращает : | верхний элемент стека. |
gpointer g_trash_stack_peek (GTrashStack **stack_p);
Возвращает верхний элемент GTrashStack,
который может быть NULL
.
stack_p : |
указатель на GTrashStack. |
Возвращает : | верхний элемент стека. |
guint g_trash_stack_height (GTrashStack **stack_p);
Возвращает высоту GTrashStack. Помните что выполнение этой функции имеет сложность O(N), где N означает количество элементов стека.
stack_p : |
указатель на GTrashStack. |
Возвращает : | высота стека. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Макросы преобразования типовType Conversion Macros — Переносимый способ хранения целочисленных в указателях переменных. |
#include <glib.h> #define GINT_TO_POINTER (i) #define GPOINTER_TO_INT (p) #define GUINT_TO_POINTER (u) #define GPOINTER_TO_UINT (p) #define GSIZE_TO_POINTER (s) #define GPOINTER_TO_SIZE (p)
Часто GLib, GTK+ и другие библиотеки позволяют вам помещать "пользовательские данные" в callback-функции, в форме void указателей. Время от времени вам необходимо помещать целочисленные вместо указателей. Вы можете разместить целочисленное примерно так:
int *ip = g_new (int, 1); *ip = 42;
Но это не удобно и требует в последствии освобождать память.
Указатели имеют размер всегда 32 бита (На всех платформах.GLib подразумевает поддержку). Поэтому вы можете хранить небольшие 32-битные целочисленные значения в указателях. Вы бы могли попробовать следующий способ, но он не верен:
gpointer p; int i; p = (void*) 42; i = (int) p;
Ещё раз напоминаем пример выше не правильный, не копируйте его. Проблема в том, что на некоторых системах вы должны сделать так:
gpointer p; int i; p = (void*) (long) 42; i = (int) (long) p;
Поэтому GPOINTER_TO_INT()
, GINT_TO_POINTER()
, и т.д. сделают эти вещи правильно на текущей платформе.
ВЫ НЕ МОЖЕТЕ ХРАНИТЬ УКАЗАТЕЛИ В ЦЕЛЫХ ЧИСЛАХ. ЭТО НЕ ПЕРЕНОСИМО НИ В КАКОЙ ФОРМЕ. Эти макросы позволяют хранить ТОЛЬКО целочисленные в указателях, и хранят только 32 битные целочисленные; значения целочисленных за пределами диапазона 32-бит будут искажены.
#define GINT_TO_POINTER(i) ((gpointer) (i))
Помещает целочисленное в тип указателя.
Помните, ВЫ НЕ МОЖЕТЕ СОХРАНЯТЬ УКАЗАТЕЛИ В ЦЕЛОЧИСЛЕННЫХ. ЭТО НЕ ПЕРЕНОСИМЫЙ СПОСОБ ФОРМИРОВАНИЯ ИЛИ ФОРМЫ. Эти макросы позволяют хранить ТОЛЬКО целочисленные в указателях, и хранят только 32 битные целочисленные; значения целочисленных за пределами диапазона 32-бит будут искажены.
i : |
целочисленное для помещения в указатель. |
#define GPOINTER_TO_INT(p) ((gint) (p))
Извлекает целочисленное из указателя. Это целочисленное должно быть предварительно помещено
в указатель с помощью GINT_TO_POINTER()
.
Помните, ВЫ НЕ МОЖЕТЕ СОХРАНЯТЬ УКАЗАТЕЛИ В ЦЕЛОЧИСЛЕННЫХ. ЭТО НЕ ПЕРЕНОСИМЫЙ СПОСОБ ФОРМИРОВАНИЯ ИЛИ ФОРМЫ. Эти макросы позволяют хранить ТОЛЬКО целочисленные в указателях, и хранят только 32 битные целочисленные; значения целочисленных за пределами диапазона 32-бит будут искажены.
p : |
указатель содержащий целочисленное. |
#define GUINT_TO_POINTER(u) ((gpointer) (u))
Помещает целочисленное без знака в тип указателя.
u : |
целочисленное без знака для помещения в указатель. |
#define GPOINTER_TO_UINT(p) ((guint) (p))
Извлекает целочисленное без знака из указателя. Целочисленное должно быть предварительно
помещено в указатель с помощью GUINT_TO_POINTER()
.
p : |
указатель содержащий целочисленное без знака. |
#define GSIZE_TO_POINTER(s) ((gpointer) (gsize) (s))
Помещает gsize в тип указателя.
s : |
gsize для помещения в указатель. |
#define GPOINTER_TO_SIZE(p) ((gsize) (p))
Извлекает gsize из указателя. Предварительно gsize должен быть помещён в указатель с помощью GSIZE_TO_POINTER()
.
p : |
указатель для извлечения gsize. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Unicode ManipulationUnicode Manipulation — функции оперирующие на Unicode символах и UTF-8 строках. |
#include <glib.h> typedef gunichar; typedef gunichar2; gboolean g_unichar_validate (gunichar ch); gboolean g_unichar_isalnum (gunichar c); gboolean g_unichar_isalpha (gunichar c); gboolean g_unichar_iscntrl (gunichar c); gboolean g_unichar_isdigit (gunichar c); gboolean g_unichar_isgraph (gunichar c); gboolean g_unichar_islower (gunichar c); gboolean g_unichar_isprint (gunichar c); gboolean g_unichar_ispunct (gunichar c); gboolean g_unichar_isspace (gunichar c); gboolean g_unichar_isupper (gunichar c); gboolean g_unichar_isxdigit (gunichar c); gboolean g_unichar_istitle (gunichar c); gboolean g_unichar_isdefined (gunichar c); gboolean g_unichar_iswide (gunichar c); gboolean g_unichar_iswide_cjk (gunichar c); gunichar g_unichar_toupper (gunichar c); gunichar g_unichar_tolower (gunichar c); gunichar g_unichar_totitle (gunichar c); gint g_unichar_digit_value (gunichar c); gint g_unichar_xdigit_value (gunichar c); enum GUnicodeType; GUnicodeType g_unichar_type (gunichar c); enum GUnicodeBreakType; GUnicodeBreakType g_unichar_break_type (gunichar c); void g_unicode_canonical_ordering (gunichar *string, gsize len); gunichar* g_unicode_canonical_decomposition (gunichar ch, gsize *result_len); gboolean g_unichar_get_mirror_char (gunichar ch, gunichar *mirrored_ch); enum GUnicodeScript; GUnicodeScript g_unichar_get_script (gunichar ch); #define g_utf8_next_char (p) gunichar g_utf8_get_char (const gchar *p); gunichar g_utf8_get_char_validated (const gchar *p, gssize max_len); gchar* g_utf8_offset_to_pointer (const gchar *str, glong offset); glong g_utf8_pointer_to_offset (const gchar *str, const gchar *pos); gchar* g_utf8_prev_char (const gchar *p); gchar* g_utf8_find_next_char (const gchar *p, const gchar *end); gchar* g_utf8_find_prev_char (const gchar *str, const gchar *p); glong g_utf8_strlen (const gchar *p, gssize max); gchar* g_utf8_strncpy (gchar *dest, const gchar *src, gsize n); gchar* g_utf8_strchr (const gchar *p, gssize len, gunichar c); gchar* g_utf8_strrchr (const gchar *p, gssize len, gunichar c); gchar* g_utf8_strreverse (const gchar *str, gssize len); gboolean g_utf8_validate (const gchar *str, gssize max_len, const gchar **end); gchar* g_utf8_strup (const gchar *str, gssize len); gchar* g_utf8_strdown (const gchar *str, gssize len); gchar* g_utf8_casefold (const gchar *str, gssize len); gchar* g_utf8_normalize (const gchar *str, gssize len, GNormalizeMode mode); enum GNormalizeMode; gint g_utf8_collate (const gchar *str1, const gchar *str2); gchar* g_utf8_collate_key (const gchar *str, gssize len); gchar* g_utf8_collate_key_for_filename (const gchar *str, gssize len); gunichar2* g_utf8_to_utf16 (const gchar *str, glong len, glong *items_read, glong *items_written, GError **error); gunichar* g_utf8_to_ucs4 (const gchar *str, glong len, glong *items_read, glong *items_written, GError **error); gunichar* g_utf8_to_ucs4_fast (const gchar *str, glong len, glong *items_written); gunichar* g_utf16_to_ucs4 (const gunichar2 *str, glong len, glong *items_read, glong *items_written, GError **error); gchar* g_utf16_to_utf8 (const gunichar2 *str, glong len, glong *items_read, glong *items_written, GError **error); gunichar2* g_ucs4_to_utf16 (const gunichar *str, glong len, glong *items_read, glong *items_written, GError **error); gchar* g_ucs4_to_utf8 (const gunichar *str, glong len, glong *items_read, glong *items_written, GError **error); gint g_unichar_to_utf8 (gunichar c, gchar *outbuf);
Эта секция описывает множество функций для работы с
Unicode символами и строками. Они аналогичны традиционной классификации
символа ctype.h
и функциям приведения и
преобразования, UTF-8 аналогичны таким же строковым функциям,
функции выполнения нормализации, преобразование регистра и сопоставление в
UTF-8 строках и наконец функции для преобразования между UTF-8, UTF-16 и UCS-4 кодировками Unicode.
Реализация Unicode функций в GLib базируется на таблице данных символов Unicode (Unicode Character Data tables), которая доступна из www.unicode.org. GLib 2.8 поддерживает Unicode 4.0, GLib 2.10 поддерживает Unicode 4.1, GLib 2.12 поддерживает Unicode 5.0.
gboolean g_unichar_validate (gunichar ch);
Проверяет является ли ch
допустимым символом Unicode. Любые возможные целочисленные значения
ch
не будут допустимы. 0 рассматривается как правильный символ,
хотя обычно он является концом строки.
ch : |
Unicode символ |
Возвращает : | TRUE если ch является допустимым Unicode символом.
|
gboolean g_unichar_isalnum (gunichar c);
Определяет является ли символ алфавитно-цифровым.
Получая некоторый UTF-8 текст, определяет значение символа с помощью
g_utf8_get_char()
.
c : |
Unicode символ |
Возвращает : | TRUE если c является алфавитно-цифровым символом
|
gboolean g_unichar_isalpha (gunichar c);
Определяет является ли символ алфавитным (то есть буквой).
Получая некоторый UTF-8 текст, определяет значение символа с помощью
g_utf8_get_char()
.
c : |
Unicode символ |
Возвращает : | TRUE если c является алфавитным символом
|
gboolean g_unichar_iscntrl (gunichar c);
Определяет является ли символ управляющим символом.
Получая некоторый UTF-8 текст, определяет значение символа с помощью
g_utf8_get_char()
.
c : |
Unicode символ |
Возвращает : | TRUE если c является управляющим символом
|
gboolean g_unichar_isdigit (gunichar c);
Определяет является ли символ числовым (то есть цифрой). Это распространяется на
ASCII 0-9 а так же цифры в других языках/сценариях. Получая некоторый UTF-8 текст,
определяет значение символа с помощью g_utf8_get_char()
.
c : |
Unicode символ |
Возвращает : | TRUE если c является цифрой
|
gboolean g_unichar_isgraph (gunichar c);
Определяет является ли символ печатным и не пробелом
(возвращает FALSE
для управляющих символов,
символов форматирования, и пробелов). Похожа на g_unichar_isprint()
, но возвращает TRUE
для пробелов.
Получая некоторый UTF-8 текст, определяет значение символа с помощью
g_utf8_get_char()
.
c : |
Unicode символ |
Возвращает : | TRUE если c является печатным символом отличающимся от пробела
|
gboolean g_unichar_islower (gunichar c);
Определяет является ли символ буквой в нижнем регистре.
Получая некоторый UTF-8 текст, определяет значение символа с помощью
g_utf8_get_char()
.
c : |
Unicode символ |
Возвращает : | TRUE если c является буквой нижнего регистра
|
gboolean g_unichar_isprint (gunichar c);
Определяет является ли символ печатным.
В отличие от g_unichar_isgraph()
, возвращает TRUE
для пробелов.
Получая некоторый UTF-8 текст, определяет значение символа с помощью
g_utf8_get_char()
.
c : |
Unicode символ |
Возвращает : | TRUE если c является печатным
|
gboolean g_unichar_ispunct (gunichar c);
Определяет является ли символ символом пунктуации или знаком.
Получая некоторый UTF-8 текст, определяет значение символа с помощью
g_utf8_get_char()
.
c : |
Unicode символ |
Возвращает : | TRUE если c является символом пунктуации или знаком
|
gboolean g_unichar_isspace (gunichar c);
Определяет является ли символ пробелом, табуляцией, или строковым разделителем
(перевод строки, возврат каретки, и т.д.). Получая некоторый UTF-8 текст, определяет
значение символа с помощью g_utf8_get_char()
.
(Помните: не нужно использовать это для прерывания слова; вы должны использовать Pango или эквивалент для получения правильного прерывания слова, алгоритм довольно сложен.)
c : |
Unicode символ |
Возвращает : | TRUE если c является символом пробела
|
gboolean g_unichar_isupper (gunichar c);
Определяет является ли символ символом верхнего регистра.
c : |
Unicode символ |
Возвращает : | TRUE если c является символом верхнего регистра
|
gboolean g_unichar_isxdigit (gunichar c);
Определяет является ли символ шестнадцатеричным числом.
c : |
Unicode символ. |
Возвращает : | TRUE если символ является шестнадцатеричным числом
|
gboolean g_unichar_istitle (gunichar c);
Определяет является ли символ символом заголовочного регистра (titlecase). Некоторые символы в Unicode которые являются составными, такие как DZ диаграф имеют три варианта регистра вместо двух. Форма заголовочного регистра (titlecase) используется в начале слова, где только первый символ напечатан только прописными буквами. Форма заголовочного регистра (titlecase) из DZ диаграфа это U+01F2 ЛАТИНСКАЯ ПРОПИСНАЯ БУКВА D СО СТРОЧНОЙ БУКВОЙ Z.
c : |
Unicode символ |
Возвращает : | TRUE если символ в заголовочном регистре (titlecase)
|
gboolean g_unichar_isdefined (gunichar c);
Определяет является ли полученный символ назначенным в Unicode стандарте.
c : |
Unicode символ |
Возвращает : | TRUE если символ имеет назначенное значение
|
gboolean g_unichar_iswide (gunichar c);
Определяет если символ обычно отрисовывается в ячейке двойной ширины.
c : |
Unicode символ |
Возвращает : | TRUE если символ широкий
|
gboolean g_unichar_iswide_cjk (gunichar c);
Определяет если символ обычно отрисовывается в ячейке двойной ширины
устаревшей East Asian локали. Если символ шире согласно
g_unichar_iswide()
,
то он также сообщает ширину этой функции, но обратное не обязательно верно. Смотрите
Unicode Standard
Annex 11 для детального изучения.
c : |
Unicode символ |
Возвращает : | TRUE если символ шириной устаревшей East Asian локали
|
Начиная с версии 2.12
gunichar g_unichar_toupper (gunichar c);
Конвертирует символ в верхний регистр.
c : |
Unicode символ |
Возвращает : | результат конвертации c в верхний регистр.
Если c не является символом нижнего регистра или заголовочного регистра (titlecase),
или не имеет эквивалента в верхнем регистре, c возвращается без изменений.
|
gunichar g_unichar_tolower (gunichar c);
Конвертирует символ в нижний регистр.
c : |
Unicode символ. |
Возвращает : | результат конвертации c в нижний регистр.
Если c не является символом верхнего регистра или заголовочного регистра (titlecase),
или не имеет эквивалента в нижнем регистре, то c возвращается без изменений.
|
gunichar g_unichar_totitle (gunichar c);
Конвертирует символ в заголовочный регистр.
c : |
Unicode символ |
Возвращает : | результат конвертации c в заголовочный регистр.
Если c не является символом верхнего регистра или символом нижнего регистра,
то c возвращается без изменений.
|
gint g_unichar_digit_value (gunichar c);
Определяет числовое значение символа как десятичное число.
c : |
Unicode символ |
Возвращает : | Если c десятичное число (согласно
g_unichar_isdigit() ), его числовое значение.
Иначе, -1.
|
gint g_unichar_xdigit_value (gunichar c);
Определяет числовое значение символа как шестнадцатеричное число.
c : |
Unicode символ |
Возвращает : | Если c это шестнадцатеричное число (согласно
g_unichar_isxdigit() ), его цифровое значение.
Иначе, -1.
|
typedef enum { G_UNICODE_CONTROL, G_UNICODE_FORMAT, G_UNICODE_UNASSIGNED, G_UNICODE_PRIVATE_USE, G_UNICODE_SURROGATE, G_UNICODE_LOWERCASE_LETTER, G_UNICODE_MODIFIER_LETTER, G_UNICODE_OTHER_LETTER, G_UNICODE_TITLECASE_LETTER, G_UNICODE_UPPERCASE_LETTER, G_UNICODE_COMBINING_MARK, G_UNICODE_ENCLOSING_MARK, G_UNICODE_NON_SPACING_MARK, G_UNICODE_DECIMAL_NUMBER, G_UNICODE_LETTER_NUMBER, G_UNICODE_OTHER_NUMBER, G_UNICODE_CONNECT_PUNCTUATION, G_UNICODE_DASH_PUNCTUATION, G_UNICODE_CLOSE_PUNCTUATION, G_UNICODE_FINAL_PUNCTUATION, G_UNICODE_INITIAL_PUNCTUATION, G_UNICODE_OTHER_PUNCTUATION, G_UNICODE_OPEN_PUNCTUATION, G_UNICODE_CURRENCY_SYMBOL, G_UNICODE_MODIFIER_SYMBOL, G_UNICODE_MATH_SYMBOL, G_UNICODE_OTHER_SYMBOL, G_UNICODE_LINE_SEPARATOR, G_UNICODE_PARAGRAPH_SEPARATOR, G_UNICODE_SPACE_SEPARATOR } GUnicodeType;
Это возможная классификация символа из спецификации Unicode. Смотрите http://www.unicode.org/Public/UNIDATA/UnicodeData.html.
GUnicodeType g_unichar_type (gunichar c);
Класифицирует Unicode символ по типу.
c : |
Unicode символ |
Возвращает : | тип символа. |
typedef enum { G_UNICODE_BREAK_MANDATORY, G_UNICODE_BREAK_CARRIAGE_RETURN, G_UNICODE_BREAK_LINE_FEED, G_UNICODE_BREAK_COMBINING_MARK, G_UNICODE_BREAK_SURROGATE, G_UNICODE_BREAK_ZERO_WIDTH_SPACE, G_UNICODE_BREAK_INSEPARABLE, G_UNICODE_BREAK_NON_BREAKING_GLUE, G_UNICODE_BREAK_CONTINGENT, G_UNICODE_BREAK_SPACE, G_UNICODE_BREAK_AFTER, G_UNICODE_BREAK_BEFORE, G_UNICODE_BREAK_BEFORE_AND_AFTER, G_UNICODE_BREAK_HYPHEN, G_UNICODE_BREAK_NON_STARTER, G_UNICODE_BREAK_OPEN_PUNCTUATION, G_UNICODE_BREAK_CLOSE_PUNCTUATION, G_UNICODE_BREAK_QUOTATION, G_UNICODE_BREAK_EXCLAMATION, G_UNICODE_BREAK_IDEOGRAPHIC, G_UNICODE_BREAK_NUMERIC, G_UNICODE_BREAK_INFIX_SEPARATOR, G_UNICODE_BREAK_SYMBOL, G_UNICODE_BREAK_ALPHABETIC, G_UNICODE_BREAK_PREFIX, G_UNICODE_BREAK_POSTFIX, G_UNICODE_BREAK_COMPLEX_CONTEXT, G_UNICODE_BREAK_AMBIGUOUS, G_UNICODE_BREAK_UNKNOWN, G_UNICODE_BREAK_NEXT_LINE, G_UNICODE_BREAK_WORD_JOINER, G_UNICODE_BREAK_HANGUL_L_JAMO, G_UNICODE_BREAK_HANGUL_V_JAMO, G_UNICODE_BREAK_HANGUL_T_JAMO, G_UNICODE_BREAK_HANGUL_LV_SYLLABLE, G_UNICODE_BREAK_HANGUL_LVT_SYLLABLE } GUnicodeBreakType;
Это классификация возможных прерываний строк.
Пять типов корейской азбуки (Hangul) добавлены в Unicode 4.1, поэтому были введены
в GLib 2.10. Помните что новые типы могут быть добавлены в будущем.
Приложения должны быть готовы обрабатывать не известные значения.
Они могут расцениваться как G_UNICODE_BREAK_UNKNOWN
.
Смотрите http://www.unicode.org/unicode/reports/tr14/.
GUnicodeBreakType g_unichar_break_type (gunichar c);
Определяет тип прерывания c
. c
должен быть Unicode символом
(для извлечения символа из текста в кодировке UTF-8, используйте
g_utf8_get_char()
).
Тип прерывания используется для поиска конца слова и строки ("границы текста"), Pango реализует алгоритмы разрешения границ Unicode
и обычно вы должны использовать функции такие как pango_break()
вместо того, чтобы беспокоится о типе границы самостоятельно.
c : |
Unicode символ |
Возвращает : | тип границы c
|
void g_unicode_canonical_ordering (gunichar *string, gsize len);
Расчитывает канонический порядок строки на месте. Это перераспределяет разложение символов в строке согласно их классам объединения. Смотрите руководство Unicode для большей информации.
string : |
строка в кодировке UCS-4. |
len : |
максимальная длина строки string для использования.
|
gunichar* g_unicode_canonical_decomposition (gunichar ch, gsize *result_len);
Расчитывает каноническую декомпозицию символа Unicode.
ch : |
Unicode символ. |
result_len : |
расположение для хранения длины возвращаемого значения. |
Возвращает : | вновь распределённая строка Unicode символов.
result_len устанавливается в результирующую длину строки.
|
gboolean g_unichar_get_mirror_char (gunichar ch, gunichar *mirrored_ch);
В Unicode, некоторые символы являются зеркальными (mirrored). Это значит что их изображение является отражённым горизонтально в тексте который расположен с право на лево. Например, "(" стал бы зеркальным отражением, ")", в тексте с обратной ориентацией (right-to-left).
Если ch
имеет зеркальное свойство Unicode и есть другой символ unicode
который обычно имеет глиф являющийся зеркальным изображением ch
's
глифа и параметр mirrored_ch
установлен, он помещает символ в адрес указанный
mirrored_ch
. Иначе размещается оригинальный символ.
ch : |
Unicode символ |
mirrored_ch : |
расположение для хранения отражённого символа |
Возвращает : | TRUE если ch
имеет зеркальный символ, иначе FALSE
|
Начиная с версии 2.4
typedef enum { /* ISO 15924 code */ G_UNICODE_SCRIPT_INVALID_CODE = -1, G_UNICODE_SCRIPT_COMMON = 0, /* Zyyy */ G_UNICODE_SCRIPT_INHERITED, /* Qaai */ G_UNICODE_SCRIPT_ARABIC, /* Arab */ G_UNICODE_SCRIPT_ARMENIAN, /* Armn */ G_UNICODE_SCRIPT_BENGALI, /* Beng */ G_UNICODE_SCRIPT_BOPOMOFO, /* Bopo */ G_UNICODE_SCRIPT_CHEROKEE, /* Cher */ G_UNICODE_SCRIPT_COPTIC, /* Qaac */ G_UNICODE_SCRIPT_CYRILLIC, /* Cyrl (Cyrs) */ G_UNICODE_SCRIPT_DESERET, /* Dsrt */ G_UNICODE_SCRIPT_DEVANAGARI, /* Deva */ G_UNICODE_SCRIPT_ETHIOPIC, /* Ethi */ G_UNICODE_SCRIPT_GEORGIAN, /* Geor (Geon, Geoa) */ G_UNICODE_SCRIPT_GOTHIC, /* Goth */ G_UNICODE_SCRIPT_GREEK, /* Grek */ G_UNICODE_SCRIPT_GUJARATI, /* Gujr */ G_UNICODE_SCRIPT_GURMUKHI, /* Guru */ G_UNICODE_SCRIPT_HAN, /* Hani */ G_UNICODE_SCRIPT_HANGUL, /* Hang */ G_UNICODE_SCRIPT_HEBREW, /* Hebr */ G_UNICODE_SCRIPT_HIRAGANA, /* Hira */ G_UNICODE_SCRIPT_KANNADA, /* Knda */ G_UNICODE_SCRIPT_KATAKANA, /* Kana */ G_UNICODE_SCRIPT_KHMER, /* Khmr */ G_UNICODE_SCRIPT_LAO, /* Laoo */ G_UNICODE_SCRIPT_LATIN, /* Latn (Latf, Latg) */ G_UNICODE_SCRIPT_MALAYALAM, /* Mlym */ G_UNICODE_SCRIPT_MONGOLIAN, /* Mong */ G_UNICODE_SCRIPT_MYANMAR, /* Mymr */ G_UNICODE_SCRIPT_OGHAM, /* Ogam */ G_UNICODE_SCRIPT_OLD_ITALIC, /* Ital */ G_UNICODE_SCRIPT_ORIYA, /* Orya */ G_UNICODE_SCRIPT_RUNIC, /* Runr */ G_UNICODE_SCRIPT_SINHALA, /* Sinh */ G_UNICODE_SCRIPT_SYRIAC, /* Syrc (Syrj, Syrn, Syre) */ G_UNICODE_SCRIPT_TAMIL, /* Taml */ G_UNICODE_SCRIPT_TELUGU, /* Telu */ G_UNICODE_SCRIPT_THAANA, /* Thaa */ G_UNICODE_SCRIPT_THAI, /* Thai */ G_UNICODE_SCRIPT_TIBETAN, /* Tibt */ G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL, /* Cans */ G_UNICODE_SCRIPT_YI, /* Yiii */ G_UNICODE_SCRIPT_TAGALOG, /* Tglg */ G_UNICODE_SCRIPT_HANUNOO, /* Hano */ G_UNICODE_SCRIPT_BUHID, /* Buhd */ G_UNICODE_SCRIPT_TAGBANWA, /* Tagb */ /* Unicode-4.0 additions */ G_UNICODE_SCRIPT_BRAILLE, /* Brai */ G_UNICODE_SCRIPT_CYPRIOT, /* Cprt */ G_UNICODE_SCRIPT_LIMBU, /* Limb */ G_UNICODE_SCRIPT_OSMANYA, /* Osma */ G_UNICODE_SCRIPT_SHAVIAN, /* Shaw */ G_UNICODE_SCRIPT_LINEAR_B, /* Linb */ G_UNICODE_SCRIPT_TAI_LE, /* Tale */ G_UNICODE_SCRIPT_UGARITIC, /* Ugar */ /* Unicode-4.1 additions */ G_UNICODE_SCRIPT_NEW_TAI_LUE, /* Talu */ G_UNICODE_SCRIPT_BUGINESE, /* Bugi */ G_UNICODE_SCRIPT_GLAGOLITIC, /* Glag */ G_UNICODE_SCRIPT_TIFINAGH, /* Tfng */ G_UNICODE_SCRIPT_SYLOTI_NAGRI, /* Sylo */ G_UNICODE_SCRIPT_OLD_PERSIAN, /* Xpeo */ G_UNICODE_SCRIPT_KHAROSHTHI, /* Khar */ /* Unicode-5.0 additions */ G_UNICODE_SCRIPT_UNKNOWN, /* Zzzz */ G_UNICODE_SCRIPT_BALINESE, /* Bali */ G_UNICODE_SCRIPT_CUNEIFORM, /* Xsux */ G_UNICODE_SCRIPT_PHOENICIAN, /* Phnx */ G_UNICODE_SCRIPT_PHAGS_PA, /* Phag */ G_UNICODE_SCRIPT_NKO /* Nkoo */ } GUnicodeScript;
Перечисление GUnicodeScript идентифицирует различные системы записи. Значения соответствуют именам определённым в стандарте Unicode. Перечисление было добавлено в GLib 2.14. Помните что новые типы могут быть добавлены в будущем. Приложения должны уметь обрабатывать неизвестные значения. Смотрите Unicode Standard Annex 24: Script names.
G_UNICODE_SCRIPT_INVALID_CODE |
значение никогда не возвращаемое из g_unichar_get_script()
|
G_UNICODE_SCRIPT_COMMON |
символ используемый в множестве различных писменностях |
G_UNICODE_SCRIPT_INHERITED |
маркер глифа который берёт его письменность из основного глифа к которому он прикреплён |
G_UNICODE_SCRIPT_ARABIC |
Арабский язык |
G_UNICODE_SCRIPT_ARMENIAN |
Армянский язык |
G_UNICODE_SCRIPT_BENGALI |
Бенгальский язык |
G_UNICODE_SCRIPT_BOPOMOFO |
Китайский (Bopomofo) |
G_UNICODE_SCRIPT_CHEROKEE |
Cherokee |
G_UNICODE_SCRIPT_COPTIC |
Коптский язык (Coptic) |
G_UNICODE_SCRIPT_CYRILLIC |
Кириллица (Cyrillic) |
G_UNICODE_SCRIPT_DESERET |
Deseret |
G_UNICODE_SCRIPT_DEVANAGARI |
Деванагари (Devanagari) |
G_UNICODE_SCRIPT_ETHIOPIC |
Древнеэфиопский (Ethiopic) |
G_UNICODE_SCRIPT_GEORGIAN |
Грузинский (Georgian) |
G_UNICODE_SCRIPT_GOTHIC |
Готический (Gothic) |
G_UNICODE_SCRIPT_GREEK |
Греческий (Greek) |
G_UNICODE_SCRIPT_GUJARATI |
Gujarati |
G_UNICODE_SCRIPT_GURMUKHI |
Gurmukhi |
G_UNICODE_SCRIPT_HAN |
Ханьшуй (Han) |
G_UNICODE_SCRIPT_HANGUL |
Хангул (Hangul) |
G_UNICODE_SCRIPT_HEBREW |
Иврит (Hebrew) |
G_UNICODE_SCRIPT_HIRAGANA |
Хирагана (Hiragana) |
G_UNICODE_SCRIPT_KANNADA |
Канада (Kannada) |
G_UNICODE_SCRIPT_KATAKANA |
Японская слоговая азбука катакана (Katakana) |
G_UNICODE_SCRIPT_KHMER |
Кхмер (Khmer) |
G_UNICODE_SCRIPT_LAO |
Лао (Lao) |
G_UNICODE_SCRIPT_LATIN |
Латинский (Latin) |
G_UNICODE_SCRIPT_MALAYALAM |
Малайялам (Malayalam) |
G_UNICODE_SCRIPT_MONGOLIAN |
Монгольский (Mongolian) |
G_UNICODE_SCRIPT_MYANMAR |
Myanmar |
G_UNICODE_SCRIPT_OGHAM |
Огам (Ogham) |
G_UNICODE_SCRIPT_OLD_ITALIC |
Староитальянский (Old Italic) |
G_UNICODE_SCRIPT_ORIYA |
Язык ория (Oriya) |
G_UNICODE_SCRIPT_RUNIC |
Руническое письмо (Runic) |
G_UNICODE_SCRIPT_SINHALA |
Сингальский язык (Sinhala) |
G_UNICODE_SCRIPT_SYRIAC |
Сирийский язык (Syriac) |
G_UNICODE_SCRIPT_TAMIL |
Тамильский язык (Tamil) |
G_UNICODE_SCRIPT_TELUGU |
Язык телугу (Telugu) |
G_UNICODE_SCRIPT_THAANA |
Таана (Thaana) |
G_UNICODE_SCRIPT_THAI |
Тайский язык (Thai) |
G_UNICODE_SCRIPT_TIBETAN |
Тибетский (Tibetan) |
G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL |
Канадский язык аборигенов (Canadian Aboriginal) |
G_UNICODE_SCRIPT_YI |
Идиш (Yi) |
G_UNICODE_SCRIPT_TAGALOG |
Тагальский язык (Tagalog) |
G_UNICODE_SCRIPT_HANUNOO |
Hanunoo |
G_UNICODE_SCRIPT_BUHID |
Buhid |
G_UNICODE_SCRIPT_TAGBANWA |
Tagbanwa |
G_UNICODE_SCRIPT_BRAILLE |
Шрифт Брайля (Braille) |
G_UNICODE_SCRIPT_CYPRIOT |
Киприотский (Cypriot) |
G_UNICODE_SCRIPT_LIMBU |
Limbu |
G_UNICODE_SCRIPT_OSMANYA |
Сомалийский алфавит (Osmanya) |
G_UNICODE_SCRIPT_SHAVIAN |
Shavian |
G_UNICODE_SCRIPT_LINEAR_B |
Линейный B (Linear B) |
G_UNICODE_SCRIPT_TAI_LE |
Tai Le |
G_UNICODE_SCRIPT_UGARITIC |
Ugaritic |
G_UNICODE_SCRIPT_NEW_TAI_LUE |
New Tai Lue |
G_UNICODE_SCRIPT_BUGINESE |
Buginese |
G_UNICODE_SCRIPT_GLAGOLITIC |
Glagolitic |
G_UNICODE_SCRIPT_TIFINAGH |
Tifinagh |
G_UNICODE_SCRIPT_SYLOTI_NAGRI |
Syloti Nagri |
G_UNICODE_SCRIPT_OLD_PERSIAN |
Старый персидский (Old Persian) |
G_UNICODE_SCRIPT_KHAROSHTHI |
Kharoshthi |
G_UNICODE_SCRIPT_UNKNOWN |
неизвестный указатель кода |
G_UNICODE_SCRIPT_BALINESE |
Балинизиский (Balinese) |
G_UNICODE_SCRIPT_CUNEIFORM |
Cuneiform |
G_UNICODE_SCRIPT_PHOENICIAN |
Финский (Phoenician) |
G_UNICODE_SCRIPT_PHAGS_PA |
Phags-pa |
G_UNICODE_SCRIPT_NKO |
N'Ko |
GUnicodeScript g_unichar_get_script (gunichar ch);
Находит GUnicodeScript для специфического символа
(как определено в Unicode Standard Annex 24). Проверка на правильность ch
для Unicode символа не производится; если вы поместите недопустимый символ, результат будет неопределённым.
ch : |
Unicode символ |
Возвращает : | GUnicodeScript для символа. |
Начиная с версии 2.14
#define g_utf8_next_char(p)
Пропускает следующий символ в UTF-8 строке. Строка должна быть допустимой;
это максимально быстрая макрокоманда и никакого контроля ошибок не проводится.
Вы должны использовать эту макрокоманду для посимвольной итерации строки.
Эта макрокоманда возвращает начало следующего символа UTF-8.
Перед использованием этой макрокоманды используйте g_utf8_validate()
для проверки правильности строк которые могут содержать недопустимые символы UTF-8.
p : |
указатель на начало допустимого символа UTF-8. |
gunichar g_utf8_get_char (const gchar *p);
Конвертирует последовательность байт в кодировке UTF-8 в Unicode символ.
Если p
не указывает на допустимый символ в кодировке UTF-8, результат будет неопределённым.
Если вы не уверены в том что последовательность байт является допустимым кодом Unicode символов, вы должны использовать вместо этой функции g_utf8_get_char_validated()
.
p : |
указатель на Unicode символ в кодировке UTF-8 |
Возвращает : | результирующий символ |
gunichar g_utf8_get_char_validated (const gchar *p, gssize max_len);
Конвертирует последовательность байт в кодировке UTF-8 в Unicode символ. Эта функция проверяет незаконченность символов, для недопустимых символов таких как символы которые выходят за диапазон Unicode и слишком длинных допустимых символов.
p : |
указатель на Unicode символ в кодировке UTF-8 |
max_len : |
максимальное количество байт для чтения, или -1, если нет максимума. |
Возвращает : | результирующий символ. Если p указатель на часть
последовательности конца строки которая могла начать допустимый символ,
возвращается (gunichar)-2; иначе, если p не является указателем
на допустимый в UTF-8 кодировке Unicode символ, возвращается (gunichar)-1.
|
gchar* g_utf8_offset_to_pointer (const gchar *str, glong offset);
Конвертирует из целочисленного символа смещения в указатель на позицию внутри строки.
Начиная с версии 2.10, эта функция позволяет помещать отрицательное offset
для
смещения назад. Это в основном полезно при движении с конца вместо движения вперед если offset
это последняя четверть строки, так как передвижение вперёд в три раза быстрее чем назад.
str : |
строка в кодировке UTF-8 |
offset : |
символьное смещение внутри строки str
|
Возвращает : | результирующий указатель |
glong g_utf8_pointer_to_offset (const gchar *str, const gchar *pos);
Конвертирует из указателя внутри строки в целочисленное смещение символов.
Начиная с версии 2.10, эта функция позволяет pos
быть перед
str
, и возвращает негативное смещение в этом случае.
str : |
строка в кодировке UTF-8 |
pos : |
указатель на позицию внутри str
|
Возвращает : | результирующее символьное смещение |
gchar* g_utf8_prev_char (const gchar *p);
Находит предыдущий символ UTF-8 в строке перед p
.
p
не должен быть в начале символа UTF-8. Никакая проверка не проводится для найденого
символа кроме фактической допустимости начального байта. Если p
может оказаться первым символом строки, вы должны использовать
g_utf8_find_prev_char()
вместо этой функции.
p : |
указатель на позицию в UTF-8 строке |
Возвращает : | указатель на найденный символ. |
gchar* g_utf8_find_next_char (const gchar *p, const gchar *end);
Ищет начало следующего символа UTF-8 в строке после p
.
p
не должен быть началом UTF-8 символа. Для найденного символа не проводится никакой проверки
фактической правильности символа, кроме допустимости начального байта.
gchar* g_utf8_find_prev_char (const gchar *str, const gchar *p);
Учитывая позицию p
со строкой UTF-8 str
, находит начало
предыдущего символа UTF-8 строки перед p
. Возвращает NULL
если нет символов
UTF-8 представленных в строке str
перед p
.
p
не должен быть началом UTF-8 символа. Никакой проверки не проводится
для найденного символа за исключением соответствия начального байта.
str : |
указатель на начало строки UTF-8 |
p : |
указатель на некоторую позицию внутри строки str
|
Возвращает : | указатель на найденный символ или NULL .
|
glong g_utf8_strlen (const gchar *p, gssize max);
Возвращает длину строки в символах.
p : |
указатель на начало строки UTF-8. |
max : |
максимальное число байт для проверки. Если max
меньше чем 0, то строка предположительно будет nul-завершённой.
Если max это 0, p не будет проверен и может
быть NULL .
|
Возвращает : | длина строки в символах |
gchar* g_utf8_strncpy (gchar *dest, const gchar *src, gsize n);
Как стандартная C функция strncpy()
, но копирует полученное количество символов а не байт.
Строка src
должна быть допустимым UTF-8 текстом.
(Используйте g_utf8_validate()
для всех текстов перед попыткой использования UTF-8 функций.)
dest : |
буфер для заполнения символами из src
|
src : |
строка в кодировке UTF-8 |
n : |
количество символов |
Возвращает : | dest
|
gchar* g_utf8_strchr (const gchar *p, gssize len, gunichar c);
Находит крайнее левое появление полученного символа Unicode в строке UTF-8,
ограничивая поиск в len
байт.
Если len
равен -1, допускается неограниченный поиск.
p : |
nul-завершённая строка UTF-8 |
len : |
максимальная длина p
|
c : |
Unicode символ |
Возвращает : | NULL если строка не содержит символ,
иначе, указатель на начало крайнего левого появления символа в строке.
|
gchar* g_utf8_strrchr (const gchar *p, gssize len, gunichar c);
Находит крайний правый полученный Unicode символ в строке UTF-8,
поиск ограничивается len
байтами.
Если len
это -1, допускается неограниченный поиск.
p : |
nul-завершённая строка UTF-8 |
len : |
максимальная длина p
|
c : |
Unicode символ |
Возвращает : | NULL если строка не содержит символа,
иначе, указатель на начало крайнего правого появления символа в строке.
|
gchar* g_utf8_strreverse (const gchar *str, gssize len);
Переворачивает строку в кодировке UTF-8. str
должна быть допустимым текстом в кодировке UTF-8.
(Используйте g_utf8_validate()
для всех текстов
перед попыткой использования сервисных функций UTF-8.)
Помните что в отличие от g_strreverse()
,
эта функция возвращает вновь распределённую память, которая должна быть освобождена с помощью
g_free()
когда больше не нужна.
str : |
строка в кодировке UTF-8 |
len : |
максимальная длина str для использования.
Если len < 0, то строка nul-завершённая.
|
Возвращает : | вновь распределённая строка которая является перевёрнутой строкой str .
|
Начиная с версии 2.2
gboolean g_utf8_validate (const gchar *str, gssize max_len, const gchar **end);
Утверждает правильность текста в кодировке UTF-8. str
это текст для подтверждения;
если str
nul-завершённая, то max_len
может быть -1, иначе
max_len
должен быть количеством байт для подтверждения.
Если end
это non-NULL
,
то конец подтверждённого диапазона будет сохранён здесь (то есть начало первого недопустимого символа, если некоторые байты недопустимы,
или иначе конец подтверждённого текста).
Помните что g_utf8_validate()
возвращает FALSE
если max_len
положительное и NUL был встречен перед прочтением max_len
байт.
Возвращает TRUE
если вся str
была допустимой. Многие GLib и GTK+
подпрограммы требуют допустимого ввода UTF-8;
поэтому данные прочтённые из файла или сети должны быть проверены с помощью
g_utf8_validate()
перед выполнением других действий с ними.
str : |
указатель на символьные данные |
max_len : |
максимальное количество байт для подтверждения, или -1 чтобы действовать пока не встретится NUL |
end : |
расположение для возвращаемого конца подтверждённых данных |
Возвращает : | TRUE если текст соответствует кодировке UTF-8
|
gchar* g_utf8_strup (const gchar *str, gssize len);
Конвертирует все Unicode символы строки в верхний регистр. Точный способ которым это выполняется зависит от текущей локали, и может привести к увеличению количества символов в строке. (Например, немецкая ess-zet будет изменена на SS.)
str : |
строка в кодировке UTF-8 |
len : |
длина str , в байтах, или -1 если str nul-завершённая.
|
Возвращает : | вновь распределённая строка, все символы которой конвертированы в верхний регистр. |
gchar* g_utf8_strdown (const gchar *str, gssize len);
Конвертирует все Unicode символы строки в нижний регистр. Точный способ которым это выполняется зависит от текущей локали, и может привести к изменению количества символов в строке.
str : |
строка в кодировке UTF-8 |
len : |
длина str , в байтах, или -1 если str nul-завершённая.
|
Возвращает : | вновь распределённая строка, в которой все символы конвертированы в нижний регистр. |
gchar* g_utf8_casefold (const gchar *str, gssize len);
Конвертирует строку в форму которая не зависит от регистра.
Результат не будет соответствовать никакому специальному регистру,
но может быть сравнен для равенства или упорядочен с результатом вызова
g_utf8_casefold()
для других строк.
Помните что вызов g_utf8_casefold()
сопровождаемый
g_utf8_collate()
только приближает к правильному лингвистическому регистру нечувствительному к упорядочиванию,
однако это достаточно хорошо. Получение более точного и правильного результата требует более сложной функции сопоставления
которая принимает во внимание чувствительность к регистру. GLib в настоящее время не поддерживает такую функцию.
str : |
строка в кодировке UTF-8 |
len : |
длина str , в байтах, или -1 если str nul-завершённая.
|
Возвращает : | вновь распределённая строка, которая является регистронезависимой str .
|
gchar* g_utf8_normalize (const gchar *str, gssize len, GNormalizeMode mode);
Конвертирует строку в изначальную форму, стандартизируя такие проблемы как, представлен ли символ с акцентом как основной
и комбинирующий акцент, или как единственный составной символ. В основном вы должны вызвать
g_utf8_normalize()
перед сравнением двух Unicode строк.
Режим нормализации G_NORMALIZE_DEFAULT
только стандартизирует различия которые не затрагивают текстовое содержание, такие как упомянутые выше акценты представления.
G_NORMALIZE_ALL
также стандартизирует
символы "совместимости" в Unicode, такие как SUPERSCRIPT THREE в стандартные формы (в данном случае DIGIT THREE). Форматирование информации
может быть потеряно но в большинстве текстовых операций такие символы должны быть рассмотрены одинаково.
Например, g_utf8_collate()
нормализуется с помощью
G_NORMALIZE_ALL
как первый шаг.
G_NORMALIZE_DEFAULT_COMPOSE
и
G_NORMALIZE_ALL_COMPOSE
являются подобными G_NORMALIZE_DEFAULT
и
G_NORMALIZE_ALL
,
но возвращают результат с составными формами а не в максимально разложенной форме. Это часто полезно если вы хотите преобразовать строку
в устаревшую кодировку или поместить её в систему с меньшей способностью обрабатывать Unicode.
str : |
строка в кодировке UTF-8. |
len : |
длина str , в байтах, или -1 если str nul-завершённая.
|
mode : |
тип выполняемой нормализации. |
Возвращает : | вновь распределённая строка, которая представляет нормализованную форму str .
|
typedef enum { G_NORMALIZE_DEFAULT, G_NORMALIZE_NFD = G_NORMALIZE_DEFAULT, G_NORMALIZE_DEFAULT_COMPOSE, G_NORMALIZE_NFC = G_NORMALIZE_DEFAULT_COMPOSE, G_NORMALIZE_ALL, G_NORMALIZE_NFKD = G_NORMALIZE_ALL, G_NORMALIZE_ALL_COMPOSE, G_NORMALIZE_NFKC = G_NORMALIZE_ALL_COMPOSE } GNormalizeMode;
Определяет как трансформировать Unicode строку в каноническую форму, стандартизирует такие проблемы как представлен ли символ с акцентом основного символа и акцентом комбинирования или как единственный составной символ. Unicode строки должны в основном быть нормализованы после их сравнения.
G_NORMALIZE_DEFAULT |
стандартизирует различия которые не затрагивают текстовое содержимое, такие как описанный выше метод представления акцента. |
G_NORMALIZE_NFD |
другое имя для G_NORMALIZE_DEFAULT .
|
G_NORMALIZE_DEFAULT_COMPOSE |
тоже что G_NORMALIZE_DEFAULT ,
но с составными формами вместо максимально разложенных форм.
|
G_NORMALIZE_NFC |
другое имя для G_NORMALIZE_DEFAULT_COMPOSE .
|
G_NORMALIZE_ALL |
помимо G_NORMALIZE_DEFAULT
также стандартизирует символы "совместимости" в Unicode, такие как SUPERSCRIPT THREE для стандартных форм
(в этом случае DIGIT THREE). Форматирование информации может быть нарушено, но для большинства текстовых операций такие символы должны
быть рассмотрены одинаково.
|
G_NORMALIZE_NFKD |
другое имя для G_NORMALIZE_ALL .
|
G_NORMALIZE_ALL_COMPOSE |
аналогично G_NORMALIZE_ALL ,
но с составными формами вместо максимально разложенных форм.
|
G_NORMALIZE_NFKC |
другое имя для G_NORMALIZE_ALL_COMPOSE .
|
gint g_utf8_collate (const gchar *str1, const gchar *str2);
Сравнивает две строки для правильного использования лингвистических правил текущей локали.
Сортируя большое количество строк, она будет значительно быстрее определять ключи сопоставления с помощью
g_utf8_collate_key()
и
сравнивать ключи и сортируя с помощью strcmp()
, вместо сортировки оригинальных строк.
str1 : |
строка в кодировке UTF-8 |
str2 : |
строка в кодировке UTF-8 |
Возвращает : | < 0 если str1 сравнивается перед str2 ,
0 если сравнение эквивалентно, > 0 если str1 сравнивается после str2 .
|
gchar* g_utf8_collate_key (const gchar *str, gssize len);
Конвертирует строку в ключ сопоставления который можно сравнить
с другим ключом сравнения произведенным той же функцией используя
strcmp()
.
Результат сравнения ключей сопоставления двух строк с помощью
strcmp()
всегда будет сопоставим с результатом
сравнения оригинальных ключей с помощью g_utf8_collate()
.
str : |
строка в кодировке UTF-8. |
len : |
длина str , в байтах, или -1 если str nul-завершённая.
|
Возвращает : | вновь распределённая строка. Эта строка должна быть освобождена с помощью
g_free() когда больше не нужна.
|
gchar* g_utf8_collate_key_for_filename (const gchar *str, gssize len);
Конвертирует строку в ключ сопоставления который можно сравнить с
другим ключом произведённым этой же функцией с помощью strcmp()
.
Для правильной сортировки имён файлов, эта функция обрабатывает точку '.' как специфичный случай. Большинство словарей считают это незначительным, производя таким образом порядок "event.c" "eventgenerator.c" "event.h" вместо "event.c" "event.h" "eventgenerator.c". Кроме того, хотелось бы обрабатывать разумно числа, так чтобы "file1" "file10" "file5" сортировались как "file1" "file5" "file10".
str : |
строка в кодировке UTF-8. |
len : |
длина str , в байтах, или -1 если str nul-завершённая.
|
Возвращает : | вновь распределённая строка. Эта строка должна быть освобождена с помощью
g_free() когда больше не нужна.
|
Начиная с версии 2.8
gunichar2* g_utf8_to_utf16 (const gchar *str, glong len, glong *items_read, glong *items_written, GError **error);
Конвертирует строку из UTF-8 в UTF-16. Символ 0 будет добавлен к результату после конвертации текста.
str : |
строка в кодировке UTF-8 |
len : |
максимальная длина (количество символов) str для использования.
Если len < 0, то строка nul-завершённая.
|
items_read : |
расположение для хранения количества прочтённых байт, или
NULL .
Если NULL , то
G_CONVERT_ERROR_PARTIAL_INPUT будет возвращён в случае,
если str содержит завершённый частично символ.
Если произошла ошибка, то здесь сохраняется индекс недопустимого ввода.
|
items_written : |
расположение для хранения записанного числа gunichar2,
или NULL .
Значение сохраняемое здесь не включает завершающий 0.
|
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут происходить любые ошибки из GConvertError кроме
G_CONVERT_ERROR_NO_CONVERSION .
|
Возвращает : | указатель на вновь распределённую строку UTF-16.
Это значение может быть освобождено с помощью
g_free() . Если произошла ошибка,
NULL будет возвращён и установлена error .
|
gunichar* g_utf8_to_ucs4 (const gchar *str, glong len, glong *items_read, glong *items_written, GError **error);
Конвертирует строку из UTF-8 в 32-bit фиксированной ширины представленный как UCS-4. Заверщающий 0 будет добавлен к строке после конвертации текста.
str : |
строка в кодировке UTF-8 |
len : |
максимальная длина str для использования.
Если len < 0, то строка nul-завершённая.
|
items_read : |
расположение для хранения прочитанных байт, или NULL .
Если NULL , то G_CONVERT_ERROR_PARTIAL_INPUT будет возвращён в случае,
если str содержит завершающую часть символа. Если произошла ошибка, то здесь
сохраняется индекс недопустимого ввода.
|
items_written : |
расположение для хранения записанных символов или NULL .
Значение сохраняемое здесь не включает завершающий символ 0.
|
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут произойти любые ошибки из GConvertError
кроме
G_CONVERT_ERROR_NO_CONVERSION .
|
Возвращает : | указатель на вновь распределённую строку UCS-4.
Это значение должно быть освобождено с помощью
g_free() . Если произошла ошибка, то возвращается
NULL и устанавливается
error .
|
gunichar* g_utf8_to_ucs4_fast (const gchar *str, glong len, glong *items_written);
Конвертирует строку из UTF-8 в 32-bit представление фиксированной ширины UCS-4,
принимая правильный ввод UTF-8.
Эта функция примерно в два раза быстрее чем g_utf8_to_ucs4()
,
но не производит никакой проверки ошибок ввода.
str : |
строка в кодировке UTF-8 |
len : |
максимальная длина str для использования. Если
len < 0, то строка nul-завершённая.
|
items_written : |
расположение для хранения количества символов в результате,
или NULL .
|
Возвращает : | указатель на вновь распределённую строку UCS-4.
Это значение должно быть освобождено с помощью g_free() .
|
gunichar* g_utf16_to_ucs4 (const gunichar2 *str, glong len, glong *items_read, glong *items_written, GError **error);
Конвертирует строку из UTF-16 в UCS-4. Результат будет завершён символом 0.
str : |
строка в кодировке UTF-16 |
len : |
максимальная длина (число gunichar2) str для использования.
Если len < 0, то строка завершается символом 0.
|
items_read : |
расположение для хранения прочтенных слов, или NULL .
Если NULL , то G_CONVERT_ERROR_PARTIAL_INPUT будет возвращён в случае,
если str содержит часть завершающего символа.
Если произошла ошибка то здесь сохраняется индекс недопустимого ввода.
|
items_written : |
расположение для хранения количества записанных символов, или
NULL .
Значение сохраняемое здесь не включает завершающий символ 0.
|
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок. Могут произойти любые ошибки из
GConvertError кроме
G_CONVERT_ERROR_NO_CONVERSION .
|
Возвращает : | указатель на вновь распределённую строку UCS-4.
Это значение должно быть освобождено с помощью
g_free() . Если произошла ошибка, то возврашается
NULL и
устанавливается error .
|
gchar* g_utf16_to_utf8 (const gunichar2 *str, glong len, glong *items_read, glong *items_written, GError **error);
Конвертирует строку из UTF-16 в UTF-8. Результат будет завершён 0 байтом.
Помните что ввод находится уже в родном порядке байт (endianness),
начальный символ byte-order-mark специально не обрабатывается.
g_convert()
может быть использована для конвертации буфера байт данных UTF-16 неоднозначного порядка байт (endianess).
str : |
строка в кодировке UTF-16 |
len : |
максимальная длина (число gunichar2) str для использования.
Если len < 0, то строка завершается символом 0.
|
items_read : |
расположение для хранения количества прочитанных слов, или
NULL .
Если NULL , то G_CONVERT_ERROR_PARTIAL_INPUT будет возвращено в случае,
если str содержит часть завершающего символа.
Если произошла ошибка то здесь сохраняется индекс недопустимого ввода.
|
items_written : |
расположение для хранения количества записанных байт, или
NULL .
Значение записанное здесь не включает завершающий 0 байт.
|
error : |
расположение для хранения произошедшей ошибки,
или NULL для игнорирования ошибок.
Могут произойти любые ошибки из
GConvertError кроме
G_CONVERT_ERROR_NO_CONVERSION .
|
Возвращает : | указатель на вновь распределённую строку UTF-8.
Это значение должно быть освобождено с помощью
g_free() . Если произошла ошибка,
NULL будет возвращён и установлена error .
|
gunichar2* g_ucs4_to_utf16 (const gunichar *str, glong len, glong *items_read, glong *items_written, GError **error);
Конвертирует строку из UCS-4 в UTF-16. Символ 0 будет добавлен к результату после конвертации текста.
str : |
строка в кодировке UCS-4 |
len : |
максимальная длина (число символов) str для использования.
Если len < 0, то строка завершается символом 0.
|
items_read : |
расположение для хранения количества прочитанных байт, или NULL .
Если произошла ошибка то здесь сохраняется индекс недопустимого ввода.
|
items_written : |
расположение для хранения числа gunichar2 записей,
или NULL .
Значение сохраняемое здесь не включает завершающий 0.
|
error : |
расположение для хранения произошедшей ошибки, или
NULL для игнорирования ошибок.
Могут произойти любые ошибки из
GConvertError кроме
G_CONVERT_ERROR_NO_CONVERSION .
|
Возвращает : | указатель на вновь распределённую строку UTF-16.
Это значение должно быть освобождено с помощью
g_free() . Если произошла ошибка,
NULL будет возвращён и установлена error .
|
gchar* g_ucs4_to_utf8 (const gunichar *str, glong len, glong *items_read, glong *items_written, GError **error);
Конвертирует строку из 32-bit фиксированной ширины представленной как UCS-4. в UTF-8. Результат будет завершён 0 байтом.
str : |
строка в кодировке UCS-4 |
len : |
максимальная длина (количество символов) str для использования.
Если len < 0, то строка завершается 0 символом.
|
items_read : |
расположение для хранения количества прочитанных символов, или NULL .
|
items_written : |
расположение для хранения записанных байт или NULL .
Значение сохраняемое здесь не включает завершающий 0 байт.
|
error : |
расположение для хранения произошедшей ошибки, или NULL
для игнорирования ошибок. Могут происходить любые ошибки из
GConvertError кроме
G_CONVERT_ERROR_NO_CONVERSION .
|
Возвращает : | указатель на вновь распределённую строку UTF-8.
Это значение должно быть освобождено с помощью
g_free() . Если произошла ошибка,
NULL будет возвращён и установлена error .
В этом случае, items_read будет установлен в позицию первого недопустимого
символа ввода.
|
gint g_unichar_to_utf8 (gunichar c, gchar *outbuf);
Конвертирует единственный символ в UTF-8.
c : |
символ в кодировке Unicode |
outbuf : |
буфер вывода, должен иметь последние 6 байт свободными.
Если NULL , то длина будет вычислена и возвращена
и ничего не будет записано в буфер outbuf .
|
Возвращает : | количество записанных байт |
g_locale_to_utf8() , g_locale_from_utf8() |
Удобные функции для конвертации между UTF-8 и локальной кодировкой. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> extern const guint glib_major_version; extern const guint glib_minor_version; extern const guint glib_micro_version; extern const guint glib_binary_age; extern const guint glib_interface_age; const gchar* glib_check_version (guint required_major, guint required_minor, guint required_micro); #define GLIB_MAJOR_VERSION #define GLIB_MINOR_VERSION #define GLIB_MICRO_VERSION #define GLIB_CHECK_VERSION (major,minor,micro)
GLib обеспечивает информации о версии, в первую очередь полезно для проверки конфигурации при сборке скриптом configure. Приложения обычно не используют особенности описанные здесь.
extern const guint glib_major_version;
Основной номер библиотеки GLib. (например в GLib версии 1.2.5 это 1.)
Эта переменная находится в библиотеке, таким образом представляется библиотека GLib к которой вы привязываетесь. В отличии от макроса GLIB_MAJOR_VERSION, который представляет главную версию заголовков GLib которые вы включили.
extern const guint glib_minor_version;
Младший номер версии библиотеки GLib. (например в GLib версии 1.2.5 это 2.)
Эта переменная находится в библиотеки, таким образом представляя библиотеку GLib к которой вы привязываетесь. В отличии от макроса GLIB_MINOR_VERSION, который представляет младший номер версии заголовков GLib которые вы включили.
extern const guint glib_micro_version;
Наименьший номер версии библиотеки GLib. (например в GLib версии 1.2.5 это 5.)
Эта переменная находится в библиотеки, таким образом представляя библиотеку GLib к которой вы привязываетесь. В отличии от макроса GLIB_MICRO_VERSION, который представляет наименьший номер версии заголовков GLib которые вы включили.
extern const guint glib_binary_age;
Это бинарный возраст передаваемый в libtool. Если libtool ни о чём вам не говорит, не беспокойтесь об этом. ;-)
extern const guint glib_interface_age;
Это интерфейсный возраст передаваемый в libtool. Если libtool ни о чём вам не говорит, не беспокойтесь об этом. ;-)
const gchar* glib_check_version (guint required_major, guint required_minor, guint required_micro);
Проверяет что библиотека GLib совместима с полученной версией. В основном вы должны помещать константы GLIB_MAJOR_VERSION, GLIB_MINOR_VERSION, GLIB_MICRO_VERSION как три аргумента для этой функции; это производит проверку что используемая библиотека совместима с версией GLib приложения, или напротив были собраны модули.
Совместимость определяется двумя вещами: сначала версия
запущенной библиотеки новее чем версия
required_major.required_minor
.
required_micro
. Затем
выполняемая библиотека должна быть бинарно совместима с
версией required_major.required_minor
.required_micro
(одинаковый главный номер версии.)
required_major : |
необходимая главная версия. |
required_minor : |
необходимая младшая версия. |
required_micro : |
необходимая наименьшая версия. |
Возвращает : | NULL
если библиотека GLib совместима с полученной версией,
или строку описывающую несоответствие версий.
Возвращаемой строкой владеет GLib и она не должна модифицироваться или освобождаться.
|
Начиная с версии 2.6
#define GLIB_MAJOR_VERSION 2
Главный номер версии библиотеки GLib. Тоже самое что glib_major_version, но из заголовков используемых во время компиляции приложения, вместо библиотеки связываемой с приложением во время выполнения.
#define GLIB_MINOR_VERSION 13
Младший номер версии библиотеки GLib. Тоже самое что gtk_minor_version, но из заголовков используемых во время компиляции приложения, а не из библиотеки связываемой с приложением во время выполнения.
#define GLIB_MICRO_VERSION 0
Наименьший номер версии библиотеки GLib. Тоже самое что gtk_micro_version, но из заголовков используемых во время компиляции приложения, а не из библиотеки связываемой с приложением во время выполнения
#define GLIB_CHECK_VERSION(major,minor,micro)
Проверяет номер версии библиотеки GLib.
Возвращает TRUE
если версия заголовочных файлов GLib та же самая или более новая чем передаваемая.
Пример 1. Проверка версии библиотеки GLib
if (!GLIB_CHECK_VERSION (1, 2, 0)) g_error ("GLib version 1.2.0 or above is needed");
major : |
главный номер версии. |
minor : |
младший номер версии. |
micro : |
наименьший номер версии. |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
Вывод сообщений и функции отладкиMessage Output and Debugging Functions — Функции для вывода сообщений и помощь отладки приложений. |
#include <glib.h> void g_print (const gchar *format, ...); GPrintFunc g_set_print_handler (GPrintFunc func); void (*GPrintFunc) (const gchar *string); void g_printerr (const gchar *format, ...); GPrintFunc g_set_printerr_handler (GPrintFunc func); #define g_return_if_fail (expr) #define g_return_val_if_fail (expr,val) #define g_return_if_reached () #define g_return_val_if_reached (val) #define g_assert (expr) #define g_assert_not_reached () void g_on_error_query (const gchar *prg_name); void g_on_error_stack_trace (const gchar *prg_name); #define G_BREAKPOINT ()
void g_print (const gchar *format, ...);
Вывод форматированных сообщений через обработчик печати. По умолчанию обработчик печати просто выводит сообщения на стандартный вывод (stdout).
g_print()
не должна использоваться внутри библиотеки для отладочных сообщений,
так как они могут переадресовываться приложениями в специальные окна сообщений или даже в файлы.
Вместо неё библиотека должна использовать g_log()
, или удобные функции
g_message()
, g_warning()
и g_error()
.
format : |
форматированное сообщение. Смотрите
документацию.
|
... : |
параметры для вставки в форматированную строку. |
GPrintFunc g_set_print_handler (GPrintFunc func);
Устанавливает обработчик печати.
Любые сообщения помещаемые в g_print()
будут выводиться через новый обработчик.
Обработчик по умолчанию просто выводит сообщения на stdout.
Обеспечивая собственный обработчик вы можете перенаправить вывод, например в виджет GTK+
или файл журнала.
func : |
новый обработчик печати. |
Возвращает : | старый обработчик печати. |
void (*GPrintFunc) (const gchar *string);
Определяет тип функции обработчика печати. Их вызывают для вывода полностью отформатированной строки на output.
string : |
сообщение для вывода. |
void g_printerr (const gchar *format, ...);
Выводит отформатированные сообщения через обработчик сообщений об ошибках. По умолчанию обработчик просто выводит сообщения на stderr.
g_printerr()
не должна использоваться внутри библиотеки. Вместо неё используйте g_log()
, или удобные функции g_message()
, g_warning()
и g_error()
.
format : |
отформатированное сообщение. Смотрите документацию для .
|
... : |
параметры для вставки в форматированную строку. |
GPrintFunc g_set_printerr_handler (GPrintFunc func);
Устанавливает обработчик для печати сообщений об ошибках.
Любые сообщения помещённые в g_printerr()
будут выводиться через новый обработчик.
Обработчик по умолчанию просто выводит сообщения на stderr.
Обеспечивая собственный обработчик вы можете перенаправить вывод, например в виджет GTK+
или файл журнала.
func : |
новый обработчик сообщений об ошибках. |
Возвращает : | старый обработчик сообщений об ошибках. |
#define g_return_if_fail(expr)
Возвращается из текущей функции если выражение не верно.
Если выражение вычисляет FALSE
, регистрируется критическое сообщение и функция возвращается. Это может использоваться только в функциях которые не возвращают значение.
expr : |
выражение для проверки. |
#define g_return_val_if_fail(expr,val)
Возвращается из текущей функции, возвращая значение val
, если выражение не верно.
Если выражение вычисляет FALSE
, регистрируется критическое сообщение и возвращается val
.
expr : |
выражение для проверки. |
val : |
значение возвращаемое из текущей функции если выражение не верно. |
#define g_return_if_reached()
Регистрирует критическое сообщение и возвращается из текущей функции. Это используется только в функциях которые не возвращают значений.
#define g_return_val_if_reached(val)
Регистрирует критическое сообщение и возвращает val
.
val : |
значение возвращаемое из текущей функции. |
#define g_assert(expr)
Отладочный макрос для завершения приложения если выражение неправильно. Если выражение неправильно (то есть логическое выражение не верно), регистрируется сообщение об ошибке и приложение закрывается.
Макрос можно отключить в завершающем релизе определив G_DISABLE_ASSERT при компиляции приложения.
expr : |
проверяемое выражение. |
#define g_assert_not_reached()
Отладочный макрос для прекращения выполнения приложения при его достижении. Если он достигнут, регистрируется сообщение об ошибке и приложение закрывается.
Макрос можно отключить при окончательной реализации с помощью определения G_DISABLE_ASSERT при компиляции приложения.
void g_on_error_query (const gchar *prg_name);
Подсказка ввода для пользователя [E]xit, [H]alt, показать [S]tack trace или [P]roceed
.
Эта функция только для отладки использования. Следующий пример демонстрирует как её можно использовать совместно с функцией g_log()
.
#include <glib.h> static void log_handler (const gchar *log_domain, GLogLevelFlags log_level, const gchar *message, gpointer user_data) { g_log_default_handler (log_domain, log_level, message, user_data); g_on_error_query (MY_PROGRAM_NAME); } int main (int argc, char *argv[]) { g_log_set_handler (MY_LOG_DOMAIN, G_LOG_LEVEL_WARNING | G_LOG_LEVEL_ERROR | G_LOG_LEVEL_CRITICAL, log_handler, NULL); /* ... */
Если [E]xit выбран, приложение закрывается с помощью вызова _exit(0)
.
Если выбрано [H]alt, приложение входит в бесконечный цикл.
Бесконечный цикл можно остановить только уничтожив приложение,
или установив glib_on_error_halt в FALSE
(возможно через отладчик).
Если выбрано [S]tack trace, вызывается g_on_error_stack_trace()
. Это вызывает
gdb, который присоединяется к текущему процессу и показывает распечатку стека (stack trace).
Подсказка ввода показывается снова.
Если выбрано [P]roceed, функция завершается возвращением.
Эта функция может вызвать разные действия на не-UNIX платформах.
prg_name : |
имя программы, необходимо отладчику gdb для опции распечатки стека ([S]tack trace option).
Если prg_name равно NULL , g_get_prgname() вызывается для получения имени
программы (которая будет работать правильно если вызваны gdk_init()
или gtk_init() ).
|
void g_on_error_stack_trace (const gchar *prg_name);
Вызывает gdb, который присоединяется к текущему процессу и показывает распечатку стека.
Вызывается функцией g_on_error_query()
когда выбрана опция [S]tack trace.
Эта функция может выполнять разные действия на не-UNIX платформах.
prg_name : |
имя програмы, нужно отладчику gdb для опции распечатки стека ([S]tack trace option).
Если prg_name равно NULL , g_get_prgname() вызывается для получения имени программы (которая будет правильно работать если вызваны gdk_init() или gtk_init() ).
|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> #define MAXPATHLEN #define pipe (phandles) gchar* g_win32_error_message (gint error); gchar* g_win32_getlocale (void); gchar* g_win32_get_package_installation_directory (gchar *package, gchar *dll_name); gchar* g_win32_get_package_installation_subdirectory (gchar *package, gchar *dll_name, gchar *subdir); guint g_win32_get_windows_version (void); gchar* g_win32_locale_filename_from_utf8 (const gchar *utf8filename); #define G_WIN32_DLLMAIN_FOR_DLL_NAME (static, dll_name) #define G_WIN32_HAVE_WIDECHAR_API () #define G_WIN32_IS_NT_BASED ()
These functions provide some level of UNIX emulation on the Windows platform. If your application really needs the POSIX APIs, we suggest you try the Cygwin project.
#define MAXPATHLEN 1024
Provided for UNIX emulation on Windows; equivalent to UNIX macro MAXPATHLEN, which is the maximum length of a filename (including full path).
#define pipe(phandles) _pipe (phandles, 4096, _O_BINARY)
Provided for UNIX emulation on Windows; see documentation for pipe() in any UNIX manual.
phandles : | file descriptors, the first one for reading, the second one for writing. |
gchar* g_win32_error_message (gint error);
Translate a Win32 error code (as returned by GetLastError()) into the corresponding message. The message is either language neutral, or in the thread's language, or the user's language, the system's language, or US English (see docs for FormatMessage()). The returned string is in UTF-8. It should be deallocated with g_free().
error : | error code. |
Возвращает : | newly-allocated error message |
gchar* g_win32_getlocale (void);
The setlocale() function in the Microsoft C library uses locale names of the form "English_United States.1252" etc. We want the UNIXish standard form "en_US", "zh_TW" etc. This function gets the current thread locale from Windows - without any encoding info - and returns it as строка of the above form for use in forming file names etc. The returned string should be deallocated with g_free().
Возвращает : | newly-allocated locale name. |
gchar* g_win32_get_package_installation_directory (gchar *package, gchar *dll_name);
Try to determine the installation directory for a software package. Typically used by GNU software packages.
package should be a short identifier for the package. Typically it is the same identifier as used for GETTEXT_PACKAGE in software configured according to GNU standards. The function first looks in the Windows Registry for the value #InstallationDirectory in the key #HKLM\Software\package, and if that value exists and is строка, returns that.
If package is NULL, or the above value isn't found in the Registry, but dll_name is non-NULL, it should name a DLL loaded into the current process. Typically that would be the name of the DLL calling this function, looking for its installation directory. The function then asks Windows what directory that DLL was loaded from. If that directory's last component is "bin" or "lib", the parent directory is returned, otherwise the directory itself. If that DLL isn't loaded, the function proceeds as if dll_name was NULL.
If both package and dll_name are NULL, the directory from where the main executable of the process was loaded is used instead in the same way as above.
package : | An identifier for a software package, or NULL, in UTF-8 |
dll_name : | The name of a DLL that a package provides, or NULL, in UTF-8 |
Возвращает : | строка containing the installation directory for package. The string is in the GLib file name encoding, i.e. UTF-8 on Windows. The return value should be freed with g_free() when not needed any longer. |
gchar* g_win32_get_package_installation_subdirectory (gchar *package, gchar *dll_name, gchar *subdir);
Returns a newly-allocated string containing the path of the subdirectory subdir in the return value from calling g_win32_get_package_installation_directory() with the package and dll_name parameters.
package : | An identifier for a software package, in UTF-8, or NULL |
dll_name : | The name of a DLL that a package provides, in UTF-8, or NULL |
subdir : | A subdirectory of the package installation directory, also in UTF-8 |
Возвращает : | строка containing the complete path to subdir inside the installation directory of package. The returned string is in the GLib file name encoding, i.e. UTF-8 on Windows. The return value should be freed with g_free() when no longer needed. |
guint g_win32_get_windows_version (void);
Returns version information for the Windows operating system the code is running on. See MSDN documentation for the GetVersion() function. To summarize, the most significant bit is one on Win9x, and zero on NT-based systems. The least significant byte is 4 on Windows NT 4, 5 on Windows XP. Software that needs really detailled version and feature information should use Win32 API like GetVersionEx() and VerifyVersionInfo().
If there is an environment variable G_WIN32_PRETEND_WIN9X defined (with any value), this function always returns a version code for Windows 9x. This is mainly an internal debugging aid for GTK+ and GLib developers, to be able to check the code paths for Windows 9x.
Возвращает : | The version information. |
Начиная с версии 2.6
gchar* g_win32_locale_filename_from_utf8 (const gchar *utf8filename);
Конвертирует filename from UTF-8 to the system codepage.
On NT-based Windows, on NTFS file systems, file names are in Unicode. It is quite possible that Unicode file names contain characters not representable in the system codepage. (For instance, Greek or Cyrillic characters on Western European or US Windows installations, or various less common CJK characters on CJK Windows installations.)
In such a case, and if the filename refers to an existing file, and the file system stores alternate short (8.3) names for directory entries, the short form of the filename is returned. Note that the "short" name might in fact be longer than the Unicode name if the Unicode name has very short pathname components containing non-ASCII characters. If no system codepage name for the file is possible, NULL is returned.
The return value is dynamically allocated and should be freed with g_free() when no longer needed.
utf8filename : | a UTF-8 encoded filename. |
Возвращает : | The converted filename, or NULL on conversion failure and lack of short names. |
Начиная с версии 2.8
#define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)
On Windows, this macro defines a DllMain() function that stores the actual DLL name that the code being compiled will be included in.
On non-Windows platforms, expands to nothing.
static : | empty or "static". |
dll_name : | the name of the (pointer to the) char array where the DLL name will be stored. If this is used, you must also include windows.h. If you need a more complex DLL entry point function, you cannot use this. |
#define G_WIN32_HAVE_WIDECHAR_API() (G_WIN32_IS_NT_BASED ())
On Windows, this macro defines an expression which evaluates to TRUE if the code is running on a version of Windows where the wide character versions of the Win32 API functions, and the wide chaacter versions of the C library functions work. (They are always present in the DLLs, but don't work on Windows 9x and Me.)
On non-Windows platforms, it is not defined.
Начиная с версии 2.6
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|---|---|---|---|
#include <glib.h> #define MAXPATHLEN #define pipe (phandles) gchar* g_win32_error_message (gint error); gchar* g_win32_getlocale (void); gchar* g_win32_get_package_installation_directory (gchar *package, gchar *dll_name); gchar* g_win32_get_package_installation_subdirectory (gchar *package, gchar *dll_name, gchar *subdir); guint g_win32_get_windows_version (void); gchar* g_win32_locale_filename_from_utf8 (const gchar *utf8filename); #define G_WIN32_DLLMAIN_FOR_DLL_NAME (static, dll_name) #define G_WIN32_HAVE_WIDECHAR_API () #define G_WIN32_IS_NT_BASED ()
Эти функции обеспечивают некоторый уровень эмуляции UNIX на Windows платыорме. Если ваше приложение реально нуждается в POSIX APIs, мы предлагаем попробовать проект Cygwin.
#define MAXPATHLEN 1024
Предусматривает эмуляцию UNIX в Windows; эквивалентна UNIX макрокоманде
MAXPATHLEN
,
которая представляет максимальную длину имени файла (включая полный путь).
#define pipe(phandles) _pipe (phandles, 4096, _O_BINARY)
Обеспечивает эмуляцию UNIX в Windows; смотрите документацию для
в любом руководстве UNIX.
pipe()
phandles : |
дескрипторы файла, первый для чтения, второй для записи. |
gchar* g_win32_error_message (gint error);
Переводит коды ошибок Win32 (которые возвращает GetLastError()
) в соответствующие сообщения.
Сообщения либо на нейтральном языке, либо на языке потоков, либо пользовательском языке, системном языке, или US English
(смотрите документацию для FormatMessage()
). Возвращаемая строка находится в кодировке UTF-8.
Она должна быть освобождена с помощью g_free()
.
error : |
код ошибки. |
Возвращает : | вновь распределённое сообщение об ошибке |
gchar* g_win32_getlocale (void);
Функция setlocale()
в библиотеке Microsoft C
использует имена локали из "English_United States.1252" и т.д.. Мы предпочитаем
стандартную UNIX форму "en_US", "zh_TW" и т.д.. Эта функция получает текущий поток
локали из Windows - без информации о кодировке - и возвращает её как строку в выше
указанной форме для использования в формировании имён файлов и т.д..
Возвращаемая строка должна освобождаться с помощью
g_free()
.
Возвращает : | вновь распределённое имя локали. |
gchar* g_win32_get_package_installation_directory (gchar *package, gchar *dll_name);
Пытается определить каталог для установки программного пакета. Обычно используется программными пакетами GNU.
package
должен быть коротким идентификатором для пакета.
Обычно это тот же идентификатор который используется для
GETTEXT_PACKAGE
в конфигурационном программном обеспечении согласно
стандартов GNU. Функция сначала ищет в Windows Registry значение #InstallationDirectory
в ключе
#HKLM\Software\
и если значение существует возвращает его.
package
Если package
это NULL
,
или выше упомянутое значение не найдено в реестре, но dll_name
не-NULL
, она должна загрузить имя DLL в текущий процесс.
Обычно это будет имя DLL вызывающей эту функцию, находящую для неё каталог установки.
Затем функция запрашивает Windows из какого каталога эта DLL была загружена. Если последний компонент этого каталога "bin" или "lib",
возвращается родительский каталог, иначе непосредственно сам каталог. Если эта DLL не загружена, функция выполняется как если бы
dll_name
был NULL
.
Если и package
и dll_name
являются
NULL
, используется основной каталог
в котором запущен процесс, вместо использования способа описанного выше.
package : |
Целочисленное для программного пакета в кодировке UTF8, или NULL ,
|
dll_name : |
Имя DLL которую обеспечивает пакет, или NULL ,
в кодировке UTF-8
|
Возвращает : | строка содержащая каталог установки для package .
Строка в кодировке имён файлов GLib, то есть UTF-8 в Windows. Возвращаемое значение должно быть освобождено
с помощью g_free() когда больше не используется.
|
gchar* g_win32_get_package_installation_subdirectory (gchar *package, gchar *dll_name, gchar *subdir);
Возвращает вновь распределённую строку содержащую путь подкаталога subdir
в возвращаемом значении из вызова g_win32_get_package_installation_directory()
с параметрами package
и
dll_name
.
package : |
Идентификатор для программного пакета, в кодировке UTF-8, или NULL
|
dll_name : |
Имя DLL которую обеспечивает пакет, в кодировке UTF-8, или NULL
|
subdir : |
подкаталог установочного каталога для пакета, так же в кодировке UTF-8 |
Возвращает : | строка содержащая полный путь к subdir внутри каталога установки
package . Возвращаемая строка находится в кодировке имён файлов GLib,
то есть UTF-8 в Windows. Возвращаемое значение должно освобождаться с помощью
g_free() когда больше не используется.
|
guint g_win32_get_windows_version (void);
Возвращает информацию о версии для исполняемого кода операционной системы Windows.
Смотрите документацию MSDN для функции GetVersion()
.
Коротко, наиболее важный бит - это один в Win9x,
и ноль в NT-based системах. Начиная с версии 2.14, GLib работает только
в NT-based системах, поэтому проверки выполняются ли ваши собственные программы в Win9x
сомнительны. Самый младший байт - это 4 в Windows NT 4, и 5 в Windows XP. Программы которым реально
необходима детальная информация о версии и особенностях, должны использовать Win32 API, например
GetVersionEx()
и VerifyVersionInfo()
.
Возвращает : | Информация о версии. |
Начиная с версии 2.6
gchar* g_win32_locale_filename_from_utf8 (const gchar *utf8filename);
Конвертирует имя файла из UTF-8 в системную кодировку.
В NT-based Windows, на файловых системах NTFS, имена файлов находятся в Unicode. Весьма возможно, что имена файлов в Unicode содержат символы не представленные в системной кодовой странице. (Например, Греческие или Кириллические символы в Восточной Европе или US Windows инсталяции, или менее общие символы CJK в CJK Windows инсталяции.)
В этом случае, и если имя файла ссылается на существующий файл, и
файловая система хранит альтернативные короткие (8.3) имена для каталогов,
возвращается короткая форма имени файла. Помните что "короткое" имя
может быть фактически длиннее чем Unicode имя, если Unicode имя имеет очень
короткий путь имени содержащий не-ASCII символы. Если нет возможного имени в системной кодировке для файла,
возвращается NULL
.
Возвращаемое значение динамически распределяется и должно быть освобождено с помощью
g_free()
когда больше не используется.
utf8filename : |
имя файла в кодировке UTF-8. |
Возвращает : | Конвертированное имя файла, или NULL
если нет короткого имени.
|
Начиная с версии 2.8
#define G_WIN32_DLLMAIN_FOR_DLL_NAME(static, dll_name)
В Windows, этот макрос определяет
функцию
которая сохраняет фактическое имя DLL для включения в компилируемый код.
DllMain()
На не-Windows платформах, ничего не делает.
static : |
свободная или "статичная". |
dll_name : |
имя (указатель на) массив символов где будет хранится имя DLL. Если это используется, вы должны так же включить
windows.h . Если вам нужно более сложную функцию точки ввода DLL, вы не должны использовать это.
|
#define G_WIN32_HAVE_WIDECHAR_API() TRUE
В Windows, этот макрос определяет выражение которое выдаёт TRUE
если код запущен в версии Windows использующей функции Win32 API широких символов, и широко-символьные версии функций библиотеки C работают.
(Они всегда присутствуют в DLLs, но не работают в Windows 9x и Me.)
На не-Windows платформах, это не определено.
Начиная с версии 2.6
#define G_WIN32_IS_NT_BASED() TRUE
В Windows, этот макрос определяет выражение которое выдаёт TRUE
если код выполняется в операционной системе на основе Windows NT.
На не-Windows платформах, это не определено.
Начиная с версии 2.6
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
Компиляция пакета GLibCompiling the GLib Package — Как самостоятельно скомпилировать GLib |
В UNIX, GLib использует стандартную систему сборки GNU, autoconf для конфигурации пакета и решения проблем переносимости, automake для создания makefiles который выполняется с помощью GNU Coding Standards и libtool для сборки общих библиотек на множестве платформ. Нормальная последовательность сборки и инсталяции GLib библиотеки такая:
./configure
make
make install
Стандартные опции представленные GNU autoconf можно передать в скрипт configure. Пожалуйста изучите autoconf документацию или запустите ./configure --help для получения информации о стандартных опциях.
GTK+ документация содержит further details о процессе сборки и способах влияния на него.
Перед компиляцией библиотеки GLib, вам необходимо иметь дополнительные инструменты и библиотеки установленные в вашей системе. Два инструмента необходимы в течении процесса сборки (которые отличаются от от инструментов используемых при создании GLib, упомянутых выше таких как autoconf) pkg-config и GNU make.
pkg-config
это инструмент для отслеживания флагов компиляции необходимых для
библиотек которые используются библиотекой GLib. (Для каждой
библиотеки, в стандартном расположении установлен текстовый файл
.pc
который содержит флаги компиляции
необходимые для данной библиотеки и номер её версии.)
Версия pkg-config
необходимая для сборки GLib указана в каталоге
зависимостей
на
GTK+ FTP
сайте.
GTK+ makefiles будет работать с разными версиями make, однако, есть некоторая тенденция небольших несовместимостей, поэтому команда разработчиков GTK+ рекомендует установить GNU make если она ещё не установлена в вашей системе и использовать именно её. (Она может называться gmake вместо make.)
GLib зависит от множества других библиотек.
Библиотека GNU
libiconv необходима для сборки GLib если ваша система
не имеет iconv()
функции для конвертации символов в разных кодировках.
Современные системы должны иметь
iconv()
, однако некоторые устаревшие системы
не имеют iconv()
. На таких системах,
вы должны установить библиотеку libiconv. Она может быть найдена на:
http://www.gnu.org/software/libiconv.
Если ваша система имеет iconv()
реализациию, но
вы хотите использовать libiconv вместо неё, то вы должны указать опцию
--with-libiconv для скрипта configure. Это заставит использовать libiconv.
Помните что если вы имеете libiconv установленную в путь поиска по умолчанию
(например в /usr/local/
), но не включаете её,
вы получите ошибку в процессе компиляции GLib, потому что
iconv.h
установленной libiconv скрывает системную
iconv.
Если вы используете родную реализацию iconv в Solaris вместо libiconv, вы должны убедиться что можете конвертировать между локальной кодировкой и UTF-8. Как минимум вам нужен пакет SUNWuiu8. Вероятно вам потребуется установить также пакеты SUNWciu8, SUNWhiu8, SUNWjiu8 и SUNWkiu8.
Родная iconv в Compaq Tru64 не поддерживает UTF-8, поэтому вам необходимо использовать вместо неё GNU libiconv. (Когда используете GNU libiconv для GLib, вы также должны использовать GNU libiconv для GNU gettext.) Это также касается связанных с ней систем.
Библиотека libintl из GNU gettext
package необходима если ваша система не имеет
gettext()
функций для обработки
базы переводимых сообщений.
Реализация потоков (thread) необходима, если вам нужно собрать GLib без поддержки потоков (thread support), что не рекомендуется. Поддержка потоков в GLib может базироваться на некой родной реализации потоков, например POSIX threads, DCE threads или Solaris threads.
В дополнение к обычным опциям, скрипт configure в библиотеке GLib поддерживает следующие аргументы:
configure
[[--enable-debug=[no|minimum|yes]]] [[--disable-gc-friendly] | [--enable-gc-friendly]] [[--disable-mem-pools] | [--enable-mem-pools]] [[--disable-threads] | [--enable-threads]] [[--with-threads=[none|posix|dce|win32]]] [[--disable-included-printf] | [--enable-included-printf]] [[--disable-visibility] | [--enable-visibility]] [[--disable-gtk-doc] | [--enable-gtk-doc]] [[--disable-man] | [--enable-man]]
--enable-debug
.
Включает разное количество отладочной поддержки. Установка в значение 'no'
отключает g_assert(), g_return_if_fail(), g_return_val_if_fail() и
контроль приведения между разными типами объектов. Установка в значение 'minimum'
отключает только контроль приведения типов. Установка в значение 'yes' включает
отладку во время выполнения.
По умолчанию используется значение 'minimum'.
Помните что значение 'no' ускоряет процесс, но опасно, поскольку имеет тенденцию
дестабилизировать даже программное обеспечение без ошибок
превращая эффект от небольших ошибок в фатальные сбои. Поэтому
--enable-debug=no
не должен
использоваться для стабильных реализаций GLib.
--disable-gc-friendly
и
--enable-gc-friendly
.
По умолчанию, а также с помощью --disable-gc-friendly
Glib не очищает память для определённых объектов прежде чем они освобождаются.
Например, Glib может решить переработать узлы GList поместив их
в освобождённый список. Однако, профилирование памяти и инструменты отладки такие как Valgrind работают лучше если
приложение не сохраняет указатели в освобождённой памяти (даже если эти указатели
больше не разыменованы), или не допускает указатели внутри
не инициализированной памяти. Опция
--enable-gc-friendly
заставляет Glib очищать
память в этой ситуации:
Когда сокращается GArray, Glib очищает память не доступную больше в массиве: сокращая массив из 10 байт в 7, последние 3 байта будут очищены. Это включает удаление единственных и множественных элементов.
Когда увеличивается GArray, Glib очищает новую часть памяти. При увеличении массива с 7 байт до 10 байт, последние 3 байта очищаются.
Выше упомянутое также относится и к GPtrArray.
Когда освобождаются узлы из GHashTable, Glib сначала очищает узел, который имеет указатель на ключ и значение сохранённое в этом узле.
Разрушая или удаляя узел GTree, Glib очищает узел, который имеет указатель на значение узлов, а также левые и правые подузлы.
Начиная c очистки памяти, значение
--disable-gc-friendly
по умолчанию.
--disable-mem-pools
и
--enable-mem-pools
.
Множество небольших участков памяти часто распределяются через пулы
в GLib и кэшируются после реализации для ускорения перераспределения.
Для разряженных систем памяти это поведение является плохим, поэтому
пулы памяти могут быть отключены, чтобы избежать чрезмерное кэширование и заставить
сопровождать атомарные участки через g_malloc()
и g_free()
функции. Код в настоящее время влияет на:
GList, GSList, GNode, распределения GHash. Функции g_list_push_allocator(), g_list_pop_allocator(), g_slist_push_allocator(), g_slist_pop_allocator(), g_node_push_allocator() и g_node_pop_allocator() не доступны.
GMemChunks в основном не эффективны.
GSignal отключает всё кэширование (потенциально очень медленный).
GType не учитывает
GTypeInfo
n_preallocs
поля больше.
GBSearchArray флажок
G_BSEARCH_ALIGN_POWER2
не функционален.
--disable-threads
и
--enable-threads
.
Не компилируйте GLib многопоточностью, тогда GLib
будет немного быстрее. Однако это не рекомендуется,
так как множество программ предполагает что GLib имеет
многопоточность.
--with-threads
.
Определяет использование многопоточной реализации.
'posix' и 'dce' могут быть взаимозаменяемыми для обозначения различных версий Posix threads. Скрипт configure попытается определить, какой из них установлен.
'none' означает что GLib будет сохранять многопоточность,
но не имеет по умолчанию реализованной
многопоточности. Это должно определяться с помощью
g_thread_init()
программистом.
--disable-included-printf
и
--enable-included-printf
.
По умолчанию скрипт configure попытается
автоматически определить использует ли C библиотека подходящий набор
функций printf()
. Точнее,
configure проверит семантику
snprintf()
на соответствие стандарту C99 и
что позиционные параметры соответствуют Single Unix
Specification. Если это не так, GLib включит реализацию
семейства функций printf()
.
Эти опции могут использоваться для непосредственного осуществления контроля
включения или не включения реализации семейства функций
printf()
.
--disable-visibility
и
--enable-visibility
.
По умолчанию, GLib использует видимые атрибуты в формате ELF для оптимизации
PLT таблицы ввода если компилятор поддерживает ELF видимые атрибуты.
Побочный эффект в том что текущая реализация при любом изменении
заголовка вызывает полную перекомпиляцию, а отсутствие includes
может быть незамечено.
Поэтому имеет смысл выключать эту особенность выполняя разработку
GLib, даже если компилятор поддерживает ELF
видимость атрибутов. Опция --disable-visibility
позволяет делать это.
--disable-gtk-doc
и
--enable-gtk-doc
.
По умолчанию скрипт configure попытается
автоматически определить установлен ли пакет
gtk-doc. Если да,
то использует его для извлечения и сборки
документации для GLib библиотеки. Эти опции
используются для непосредственного контроля должен ли применяться
gtk-doc или нет.
Если он не используется, то будут установлены предварительно сгенерированные
HTML файлы вместо сборки их на вашей машине.
--disable-man
и
--enable-man
.
По умолчанию скрипт configure попытается
автоматически определить установлен ли xsltproc
и необходимые таблицы стилей Docbook. Если установлены,
то они будут использованы для пересборки включенных страниц руководства
(man pages) из XML исходников. Эти опции могут использоваться для
непосредственного контроля должны ли страницы руководства (man pages)
пересобираться или нет. Дистрибутив включает предварительно
сгенерированные man страницы.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
Changes to GLibChanges to GLib — Incompatible changes made between successing versions of GLib |
GLib changed the seeding algorithm for the pseudo-random number
generator Mersenne Twister, as used by GRand
and GRandom. This was necessary, because some
seeds would yield very bad pseudo-random streams. Also the
pseudo-random integers generated by
g_rand*_int_range()
will have a
slightly better equal distribution with the new version of GLib.
Further information can be found at the website of the Mersenne Twister random number generator at http://www.math.keio.ac.jp/~matumoto/emt.html.
The original seeding and generation algorithms, as found in GLib
2.0.x, can be used instead of the new ones by setting the environment
variable G_RANDOM_VERSION
to the value of '2.0'. Use
the GLib-2.0 algorithms only if you have sequences of numbers generated
with Glib-2.0 that you need to reproduce exactly.
The GNOME 2.0 porting guide on http://developer.gnome.org has some more detailed discussion of porting from 1.2 to 2.0. See the section on GLib.
The event loop functionality GMain has extensively been revised to support multiple separate main loops in separate threads. All sources (timeouts, idle functions, etc.) are associated with a GMainContext.
Compatibility functions exist so that most application code dealing with the main loop will continue to work. However, code that creates new custom types of sources will require modification.
The main changes here are:
Sources are now exposed as GSource *, rather than simply as numeric ids.
New types of sources are created by structure "derivation" from
GSource, so the source_data
parameter to the GSource virtual functions has been
replaced with a GSource *.
Sources are first created, then later added to a specific GMainContext.
Dispatching has been modified so both the callback and data are passed
in to the dispatch()
virtual function.
To go along with this change, the vtable for
GIOChannel has changed and
add_watch()
has been replaced by
create_watch()
.
g_list_foreach()
and
g_slist_foreach()
have been changed so they
are now safe against removal of the current item, not the next item.
It's not recommended to mutate the list in the callback to these functions in any case.
GDate now works in UTF-8, not in the current locale.
If you want to use it with the encoding of the locale, you need to convert
strings using g_locale_to_utf8()
first.
g_strsplit()
has been fixed to:
include trailing empty tokens, rather than stripping them
split into a maximum of max_tokens
tokens, rather
than max_tokens + 1
Code depending on either of these bugs will need to be fixed.
Deprecated functions that got removed:
g_set_error_handler()
,
g_set_warning_handler()
,
g_set_message_handler()
, use
g_log_set_handler()
instead.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
Компиляция приложений GLibCompiling GLib Applications — Как скомпилировать ваше GLib приложение |
Для компиляции GLib приложений, вам необходимо сообщить компилятору где находятся заголовочные файлы и библиотека GLib. Это выполняется с помощью утилиты pkg-config.
В следующем примере демонстрируется как использовать pkg-config (фактический вывод в вашей системе может отличаться):
$ pkg-config --cflags glib-2.0 -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include $ pkg-config --libs glib-2.0 -L/usr/lib -lm -lglib-2.0
Если ваше приложение использует потоки (threads) или GObject особенности, оно может быть скомпилировано и слинковано с помощью опций возвращаемых следующими вызовами pkg-config:
$ pkg-config --cflags --libs gthread-2.0 $ pkg-config --cflags --libs gobject-2.0
Если ваше приложение использует модули, оно может быть слинковано и скомпилировано с помощью опций возвращаемых одним из следующих вызовов pkg-config:
$ pkg-config --cflags --libs gmodule-no-export-2.0 $ pkg-config --cflags --libs gmodule-2.0
Отличие между двумя этими gmodule-2.0 в добавляемом флажке
--export-dynamic
к линковщику, который зачастую ненужен.
Простой способ компиляции программ - это использование "backticks" особенности оболочки. Если вы заключите команду в обратные одинарные кавычки (backticks) (не одиночные кавычки), то вывод будет перенаправлен в командную строку перед выполнением основной команды. Таким образом для компиляции GLib Hello, World, вы должны напечатать следующее:
$ cc `pkg-config --cflags --libs glib-2.0` hello.c -o hello
Если вы уверены что ваша программа не использует устаревших функций,
вы можете определить символ препроцессора G_DISABLE_DEPRECATED
используя опцию командной строки -DG_DISABLE_DEPRECATED=1
.
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
Cross-компиляция пакета GLibCross-compiling the GLib Package — Как скомпилировать пакет GLib для разных платформ. |
Cross-компиляция это процесс компиляции программ или библиотек на разных архитектурах или операционных системах на которых они будут выполняться. GLib немного сложна для cross-компиляции чем большинство пакетов потому что большая часть GLib о скрытых различиях между разными системами.
Данные замечания разъясняют специфику cross-компиляции GLib; основную информацию о cross-компиляции, смотрите в autoconf info pages.
GLib попытается обнаружить как можно больше информации о целевой системе с помощью компиляции и линковки программ ничего фактически не выполняя; однако, некоторая информация необходимая GLib не доступна таким способом. Эту информацию нужно обеспечить для скрипта configure через "cache file" или с помощью настроек переменных в вашем окружении.
Как пример использования кэш файла (cache file), при cross-компиляции для "MingW32" Win32 окружения на Linux системе, создаём файл 'win32.cache' со следующим содержимым:
glib_cv_long_long_format=I64 glib_cv_stack_grows=no
Затем выполняем следующие команды:
PATH=/path/to/mingw32-compiler/bin:$PATH chmod a-w win32.cache # prevent configure from changing it ./configure --cache-file=win32.cache --host=mingw32
Полный список переменных кэш файла следующий. Большинство из этого не нужно устанавливать в большинстве случаев.
glib_cv_long_long_format=[ll/q/I64].
Формат используемой printf()
и
scanf()
для 64 bit целых. "ll" это
стандарт C99, что означает использование библиотеки 'trio'
которую GLib соберёт если ваша printf()
недостаточно функциональна.
Не нужно устанавливать если вы собираетесь компилировать с использованием trio.
glib_cv_stack_grows=[yes/no]. Увеличение стека вверх или вниз. Для большинства необходимо "no", некоторые архитектуры, такие как PA-RISC нуждаются в "yes".
glib_cv_working_bcopy=[yes/no].
Может ли ваш bcopy()
обрабатывать перекрывающиеся
копии. Нужно установить только если вы не имеете
memmove()
. (Очень вряд ли)
glib_cv_sane_realloc=[yes/np].
Соответствует ли ваш realloc()
ANSI C
и может ли обрабатывать NULL
как первый аргумент.
По умолчанию "yes" и вероятно не потребуется переустанавливать.
glib_cv_have_strlcpy=[yes/no].
Имеете ли вы strlcpy()
соответствующую
OpenBSD. По умолчанию "no", что является безопасным, поэтому GLib использует
встроенную версию в этом случае.
glib_cv_va_val_copy=[yes/no].
Может ли va_list копироваться как указатель. Если
установлено в "no", то используется memcopy()
.
Имеет смысл только если у вас нет va_copy()
или
__va_copy()
. (Поэтому не имеет значения для GCC.)
По умолчанию "yes" что намного чаще необходимо чем "no".
glib_cv_rtldglobal_broken=[yes/no]. Обнаруживается ли ошибка в OSF/1 v5.0. По умолчанию "no".
glib_cv_uscore=[yes/no].
Нужно ли подчёркивание перед символами при поиске их
через dlsym()
. Необходимо для установки только
если система использует
dlopen()
/dlsym()
.
ac_cv_func_posix_getpwuid_r=[yes/no]. Имеете ли вы функцию getpwuid_r (в вашей C библиотеке, а не библиотеке потока) которая соответствует спецификации POSIX. (Берёт 'struct passwd **' как последний параметр)
ac_cv_func_nonposix_getpwuid_r=[yes/no].
Имеете ли вы какой нибудь вариант getpwuid_r()
который не соответствует спецификации POSIX, но мог бы использоваться GLib
(or might segfault.) Нужно установить только если
ac_cv_func_posix_getpwuid_r
не установлен.
Безопасней устанавливать в "no".
glib_cv_use_pid_surrogate=[yes/no].
Используется ли setpriority()
в PID
нити как метод для настройки приоритетов нитей (threads). Устанавливается только
при использовании POSIX threads.
ac_cv_func_printf_unix98=[yes/no].
Поддерживает ли ваше семейство printf()
стиль Unix98
%N$
параметров позиционирования. По умолчанию "no".
ac_cv_func_vsnprintf_c99=[yes/no].
Имеете ли вы vsnprintf()
с семантикой C99
(C99 семантика означает возвращение количество байт
которые должны быть записаны имея буфер достаточного размера).
По умолчанию "no".
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
glib-gettextizeglib-gettextize — утилита интернационализации gettext |
glib-gettextize
[option...] [directory]
glib-gettextize помогает подготовить исходный пакет для начала интернационализации через gettext. Это вариант gettextize которая поставляется с gettext.
glib-gettextize отличается от
gettextize тем, что не создаёт подкаталог
intl/
и не изменяет po/ChangeLog
(помните что новые версии gettextize ведут
себя таким образом когда вызваны с опцией --no-changelog
).
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
Списки рассылки и сообщения об ошибкахMailing lists and bug reports — Получение помощи по GLib |
Если вы столкнулись с ошибкой, неудобством, или пропущенной особенностью в GLib, пожалуйста отправьте сообщение об ошибке в http://bugzilla.gnome.org. Мы также будем благодарны за сообщения об ошибках или недостатках в документации GLib; поместите их напротив "docs" компонента "glib" в Bugzilla.
Пожалуйста сообщайте об ошибках даже если думаете что мы знаем о них, или не совсем уверены в деталях. Просто сообщите нам как можно больше информации которую вы имеете и если это уже обсуждалось и исправлено то мы добавим сообщение об этом.
Программа слежения за ошибками (bug tracker) должна использоваться для запросов улучшений, она не только для ошибок. Мы отслеживаем всю разработку GLib в Bugzilla, таким образом это хороший способ убедиться что разработчики GLib не забудут об этом улучшении.
Если вы разработали исправление ошибки или усовершенствование для GLib, пожалуйста отправьте
его также в Bugzilla. Bugzilla позволяет вам прикреплять файлы; пожалуйста прикрепите "заплатку"
(patch) сгенерированную утилитой diff, используя
-u
опцию для создания более читабельной "заплатки" (patch).
Все "заплатки" должны быть под лицензией GNU LGPL, поэтому убедитесь что вы уполномочены
представлять "заплатки" (patch) согласно этой лицензии.
Если вы хотите обсудить ваше исправление до или после разработки, пишите на gtk-devel-list@gnome.org. Но убедитесь в том что сообщили об этом в Bugzilla; если "заплатка" (patch) будет только в списке рассылки и не будет присутствовать в Bugzilla, она вероятней всего будет рассмотрена как ошибка.
Есть несколько адресов списков рассылки специализированных для GTK+ и связанных с ней библиотек. Дискусии о GLib в основном происходят в этих списках рассылки. Вы можете подписаться или посмотреть эти списки на http://mail.gnome.org.
gtk-list@gnome.org | gtk-list в основном относится к GTK+ (и GLib); вопросы об использовании GLib в программах, GLib с точки зрения пользователей, анонсы GLib-связанных проектов входят в диапазон данного списка рассылки. Большая часть трафика состоит из вопросов связанных с программированием с помощью GTK+. |
gtk-devel-list@gnome.org | gtk-devel-list для дискуссий непосредственно о работе в GTK+ (и GLib), он не для вопросов о том как использовать GTK+ (или GLib) в приложениях. gtk-devel-list предназначен для обсуждения "заплаток" (patches), ошибок, будущих улучшений, и так далее. |
gtk-doc-list@gnome.org | gtk-doc-list для обсуждения системы документирования gtk-doc (используется для документации GTK+ и Glib), и для работы над документацией GTK+ (и GLib). |
![]() |
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
Выполнение GLib приложенияRunning GLib Applications — Как выполнять и отлаживать GLib приложение |
GLib проверяет несколько переменных окружения в дополнение к стандартным
переменным таких как LANG
, PATH
или HOME
.
G_FILENAME_ENCODING
.
Эта переменная окружения может определять разделённый запятыми список имён
наборов символов. GLib предполагает что имена файлов находятся в кодировке первого набора
символов в этом списке вместо UTF-8. Специальная лексема "@locale" может использоваться
для определения набора символов текущей локали (locale).
G_BROKEN_FILENAMES
.
Если эта переменная окружения установлена, GLib предполагает что имена файлов находятся в
кодировке локали (locale) вместо UTF-8. G_FILENAME_ENCODING имеет приоритет над
G_BROKEN_FILENAMES.
G_MESSAGES_PREFIXED
.
Список регистрационного уровня для которого сообщения должны быть предустановленны
именем программы и PID приложения. По умолчанию с префиксом все кроме
G_LOG_LEVEL_MESSAGE
и
G_LOG_LEVEL_INFO
.
G_DEBUG
.
Если GLib сконфигурирована с --enable-debug=yes
,
эта переменная может быть установлена в список отладочных опций, которые заставят GLib
печатать различную отладочную информацию.
fatal_warnings | Заставит GLib прервать программу при первом вызове g_warning() или g_critical(). Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки. |
fatal_criticals | Заставит GLib прервать программу при первом вызове g_critical(). Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки. |
gc-friendly | Вновь распределенная память которая непосредственно не инициализирована, также как освобождаемая память будет сброшена в 0. Позволяет проверочным программам памяти и подобным программам использующим алгоритмы подобные GC (сборщик мусора) произвести более точные результаты. Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки. |
resident-modules | Все модули загруженные GModule будут сделаны постоянно находящимися в оперативной памяти. Это может быть полезно при отслеживании утечек памяти в модулях которые загружаются позже; но это может также скрыть ошибки когда к коду обращаются после обычной выгрузки модуля. Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки. |
bind-now-modules | Все модули загруженные GModule свяжут свои идентификаторы во время загрузки, даже когда код использует %G_MODULE_BIND_LAZY. Особенность опции в том, что не требуется конфигурация GLib с поддержкой отладки. |
G_SLICE
.
Эта переменная окружения позволяет переконфигурировать #GSlice
программу распределения памяти (memory allocator).
always-malloc | Это заставит все участки распределённые через g_slice_alloc() и освобожденные с помощью g_slice_free1() фактически распределяться непосредственно через вызовы g_malloc() и g_free(). Позволяет проверочным программам памяти и подобным программам использующим алгоритмы подобные GC (сборщик мусора) произвести более точные результаты. Может также связать с отладочной особенностью реализации системы malloc такой как glibc's MALLOC_CHECK_=2 для отладки кода ошибочно распределенных участков. |
G_RANDOM_VERSION
.
Если эта переменная установлена в '2.0', будут использоваться
устаревшие алгоритмы генерирования псевдо-случайных чисел из
GLib-2.0 вместо улучшенных новых. Используйте GLib-2.0
алгоритмы только если вы генерировали последовательность чисел с помощью
Glib-2.0 которую вам нужно воспроизвести в точности.
LIBCHARSET_ALIAS_DIR
.
Позволяет специфичное не стандартное расположение для
charset.aliases
файла который используется
подпрограммами конвертации наборов символов. По умолчанию расположение определяет
libdir
во время компиляции.
G_WIN32_PRETEND_WIN9X
.
Установка этой переменной в любое значение заставит g_win32_get_windows_version()
возвращать версию кода для Windows 9x. Это главным образом для внутренней
отладки GTK+ и GLib, позволяет разработчикам проверить код для Windows 9x.
Некоторые части кода содержат переменные "ловушки" которые могут быть установлены во время отладки
если GLib сконфигурирована с --enable-debug=yes
.
Такие "ловушки" приводят к непосредственной остановки кода для исследования
текущего состояния программы и отслеживания (backtrace).
В настоящее время существуют следующие переменные "ловушки":
static volatile gulong g_trap_free_size; static volatile gulong g_trap_realloc_size; static volatile gulong g_trap_malloc_size;
Если установлен размер > 0, g_free(),
g_realloc() и
g_malloc() будут прерваны, если размер
будет соответствовать размеру блока памяти. Это работает только с
g_mem_set_vtable (glib_mem_profiler_table)
во время старта,
потому что профиль памяти требует соответствия в размерах блоков памяти.
Помните что многие современные отладчики поддерживают условные точки остановки, которые выполняют аналогичные функции. Например в gdb, вы можете сделать следующее
break g_malloc condition 1 n_bytes == 20
для остановки только в g_malloc() вызове где размер распределяемого блока равен 20.
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
GLib это универсальная библиотека, которая обеспечивает много полезных типов данных, макросов, преобразований типов, строковых утилит, файловых утилит, абстракцию основного цикла и многое другое. Она работает на большинстве UNIX-подобных платформах, Windows, OS/2 и BeOS. GLib реализована на основе GNU Library General Public License (GNU LGPL).
Основная политика GLib в том, что все функции являются невидимыми и многопоточными за исключением функций манипулирующих структурными данными, где, если вы имеете два потока манипуляции одинаковыми данными структуры, они могут использовать блокировку для синхронизации своих операций.
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
Справочное описание GLib | ![]() |
---|
![]() |
![]() |
Справочное описание GLib |
---|
![]() |
![]() |
Справочное описание GLib | ![]() |
---|