Pointer Arrays

Pointer 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);

Детали

GPtrArray

typedef struct {
  gpointer *pdata;
  guint	    len;
} GPtrArray;

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

gpointer *`pdata`;	пункты в массиве указателей, которые могут быть перемещёны при увеличении массива.
guint `len`;	количество указателей в массиве.

g_ptr_array_new ()

GPtrArray*  g_ptr_array_new                 (void);

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

Возвращает :

новый GPtrArray.

g_ptr_array_sized_new ()

GPtrArray*  g_ptr_array_sized_new           (guint reserved_size);

Создаёт новый GPtrArray с предварительно распределенными reserved_size указателями. Это исключает частое перераспределение, если вы собираетесь добавить много указателей в массив. Однако помните, размер массива остаётся 0.

`reserved_size` :	количество предварительно распределённых указателей.
Возвращает :	новый GPtrArray.

g_ptr_array_add ()

void        g_ptr_array_add                 (GPtrArray *array,
                                             gpointer data);

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

`array` :	GPtrArray.
`data` :	добавляемый указатель.

g_ptr_array_remove ()

gboolean    g_ptr_array_remove              (GPtrArray *array,
                                             gpointer data);

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

Она возвращает TRUE если указатель был удалён, или FALSE если указатель не найден.

`array` :	GPtrArray.
`data` :	указатель для удаления.
Возвращает :	`TRUE` если указатель удалён. `FALSE` если указатель не найден в массиве.

g_ptr_array_remove_index ()

gpointer    g_ptr_array_remove_index        (GPtrArray *array,
                                             guint index_);

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

`array` :	GPtrArray.
`index_` :	номер указателя для удаления.
Возвращает :	указатель который был удалён.

g_ptr_array_remove_fast ()

gboolean    g_ptr_array_remove_fast         (GPtrArray *array,
                                             gpointer data);

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

Возвращает TRUE если указатель был удалён, или FALSE если указатель не найден в массиве.

`array` :	GPtrArray.
`data` :	указатель для удаления.
Возвращает :	`TRUE` если был найден в массиве.

g_ptr_array_remove_index_fast ()

gpointer    g_ptr_array_remove_index_fast   (GPtrArray *array,
                                             guint index_);

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

`array` :	GPtrArray.
`index_` :	номер указателя для удаления.
Возвращает :	указатель который был удалён.

g_ptr_array_remove_range ()

void        g_ptr_array_remove_range        (GPtrArray *array,
                                             guint index_,
                                             guint length);

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

`array` :	`GPtrArray`.
`index_` :	номер первого указателя для удаления.
`length` :	количество указателей для удаления.

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

g_ptr_array_sort ()

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` :	функция сравнения.

g_ptr_array_sort_with_data ()

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

g_ptr_array_set_size ()

void        g_ptr_array_set_size            (GPtrArray *array,
                                             gint length);

Устанавливает размер массива, расширяя его если необходимо. Новые элементы устанавливаются в NULL.

`array` :	GPtrArray.
`length` :	новый размер массива указателей.

g_ptr_array_index()

#define     g_ptr_array_index(array,index_)

Возвращает указатель с полученным номером массива указателей.

`array` :	GPtrArray.
`index_` :	номер возвращаемого указателя.
Возвращает :	указатель с полученным номером.

g_ptr_array_free ()

gpointer*   g_ptr_array_free                (GPtrArray *array,
                                             gboolean free_seg);

Освобождает всю память распределённую для массива указателей.

`array` :	GPtrArray.
`free_seg` :	если `TRUE` массив указателей (`pdata`) освобождается.
Возвращает :	`NULL` если `free_seg` это `TRUE`, иначе возвращает массив указателей (`pdata`).

g_ptr_array_foreach ()

void        g_ptr_array_foreach             (GPtrArray *array,
                                             GFunc func,
                                             gpointer user_data);

Вызывает функцию для каждого элемента GPtrArray.

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

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

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