Arrays

Arrays — Массивы произвольных элементов, которые автоматически увеличиваются при добавлении элементов.

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


#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

typedef struct {
  gchar *data;
  guint len;
} GArray;

Содержит общедоступные поля массива.

gchar *`data`;	указатель на элемент данных. Данные могут быть перемещены при добавлении элементов в GArray.
guint `len`;	количество элементов в GArray.

g_array_new ()

GArray*     g_array_new                     (gboolean zero_terminated,
                                             gboolean clear_,
                                             guint element_size);

Создаёт новый GArray.

`zero_terminated` :	`TRUE` если массив должен иметь в конце дополнительный элемент который установлен в 0.
`clear_` :	`TRUE` если элементы GArray должны автоматически очищаться до 0 при распределении.
`element_size` :	размер каждого элемента в байтах.
Возвращает :	новый GArray.

g_array_sized_new ()

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.

g_array_append_val()

#define     g_array_append_val(a,v)

Добавляет значение в конец массива. Массив будет увеличивать размер автоматически, если необходимо.

Примечание

g_array_append_val() это макрос который использует ссылку на значение параметра v. Это значит что вы не можете использовать его с литеральными значениями, такими как "27". Вы должны использовать переменные.

`a` :	GArray.
`v` :	значение для добавления в GArray.
Возвращает :	GArray.

g_array_append_vals ()

GArray*     g_array_append_vals             (GArray *array,
                                             gconstpointer data,
                                             guint len);

Добавляет len элементов в конец массива.

`array` :	GArray.
`data` :	указатель на элементы добавляемые в конец массива.
`len` :	количество элементов для добавления.
Возвращает :	GArray.

g_array_prepend_val()

#define     g_array_prepend_val(a,v)

Добавляет значение в начало массива. Массив будет автоматически увеличиваться, если необходимо.

Эта операция медленнее чем g_array_append_val() так как существующие элементы в массиве будут перемещаться освобождая пространство для нового элемента.

Примечание

g_array_prepend_val() это макрос который использует ссылку на значение параметра v. Это значит вы не можете использовать его с литеральными значениями, такими как "27". Вы должны использовать переменные.

`a` :	GArray.
`v` :	значение для подстановки в GArray.
Возвращает :	GArray.

g_array_prepend_vals ()

GArray*     g_array_prepend_vals            (GArray *array,
                                             gconstpointer data,
                                             guint len);

Добавляет len элементов в начало массива.

Эта операция медленнее чем g_array_append_vals(), так как существующие элементы в массиве будут перемещаться освобождая пространство для новых элементов.

`array` :	GArray.
`data` :	указатель на элементы вставляемые в начало массива.
`len` :	количество вставляемых элементов.
Возвращает :	GArray.

g_array_insert_val()

#define     g_array_insert_val(a,i,v)

Вставляет элемент в массив в указанную позицию.

Примечание

g_array_insert_val() это макрос который использует ссылку на значение параметра v. Это значит что вы не можете использовать его с литеральными значениями такими как "27". Вы должны использовать переменные.

`a` :	GArray.
`i` :	позиция для помещения элемента.
`v` :	значение вставляемое в массив.
Возвращает :	GArray.

g_array_insert_vals ()

GArray*     g_array_insert_vals             (GArray *array,
                                             guint index_,
                                             gconstpointer data,
                                             guint len);

Вставляет len элементов в GArray в указанную позицию.

`array` :	GArray.
`index_` :	позиция для помещения элементов.
`data` :	указатель на вставляемые элементы.
`len` :	количество вставляемых элементов.
Возвращает :	GArray.

g_array_remove_index ()

GArray*     g_array_remove_index            (GArray *array,
                                             guint index_);

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

`array` :	GArray.
`index_` :	позиция удаляемого элемента.
Возвращает :	GArray.

g_array_remove_index_fast ()

GArray*     g_array_remove_index_fast       (GArray *array,
                                             guint index_);

Удаляет элемент из указанной позиции в GArray. Оставшиеся элементы в массиве используются для заполнения пространства, поэтому эта функция не сохраняет порядок GArray. Но она быстрее чем g_array_remove_index().

`array` :	`GArray`.
`index_` :	позиция удаляемого элемента.
Возвращает :	GArray.

g_array_remove_range ()

GArray*     g_array_remove_range            (GArray *array,
                                             guint index_,
                                             guint length);

Удаляет полученное количество элементов начиная с указанной позиции GArray. Следующие элементы перемещаются заполняя пустоту.

`array` :	`GArray`.
`index_` :	позиция первого удаляемого элемента.
`length` :	количество удаляемых элементов.
Возвращает :	GArray.

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

g_array_sort ()

void        g_array_sort                    (GArray *array,
                                             GCompareFunc compare_func);

Сортирует GArray используя compare_func которая должна быть в стиле функции сравнения qsort() (возвращает значение меньше нуля если первый arg меньше чем второй arg, ноль если они равны, больше нуля если первый arg больше чем второй arg).

Если два сравниваемых элемента массива равны, их порядок сортировки в массиве неопределён.

`array` :	GArray.
`compare_func` :	функция сравнения.

g_array_sort_with_data ()

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

g_array_index()

#define     g_array_index(a,t,i)

Возвращает элемент GArray в указанной позиции. Возвращаемое значение приводится к указанному типу.

Пример 6. Getting указатель на element in a GArray

  EDayViewEvent *event;

  /* Возвращает указатель на третий элемент в массиве структур EDayViewEvent. */
  event = &g_array_index (events, EDayViewEvent, 3);

`a` :	GArray.
`t` :	тип элементов.
`i` :	позиция возвращаемого элемента.
Возвращает :	элемент GArray в позиции `i`.

g_array_set_size ()

GArray*     g_array_set_size                (GArray *array,
                                             guint length);

Устанавливает размер массива, расширяя его если необходимо. Если массив создаётся с clear_ установленным в TRUE, новые элементы устанавливаются в 0.

`array` :	GArray.
`length` :	новый размер GArray.
Возвращает :	GArray.

g_array_free ()

gchar*      g_array_free                    (GArray *array,
                                             gboolean free_segment);

Освобождает память распределённую для GArray. Если free_segment это TRUE она также освобождает блок памяти содержащей элементы. Поместите FALSE если вы хотите освободить оболочку GArray, но тем ни менее сохранить для использования основной массив.

Примечание

Если массив элементов содержит динамически распределённую память, она должна освобождаться первой.

`array` :	GArray.
`free_segment` :	если `TRUE` фактические элементы данных также освобождаются.
Возвращает :	элементы данных если `free_segment` это `FALSE`, иначе `NULL`

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