Name

GList

typedef struct {
  gpointer data;
  GList *next;
  GList *prev;
} GList;

The GList struct is used for each element in a doubly-linked list.

g_list_append ()

GList*      g_list_append                   (GList *list, gpointer data);

Adds a new element on to the end of the list. Note that g_list_append() has to traverse the entire list to find the end, which is inefficient when adding multiple elements. A common idiom to avoid the inefficiency is to prepend the elements and reverse the list when all elements have been added.

Note: The return value is the new start of the list, which may have changed, so make sure to store the new value.

  /* Notice that these are initialized to the empty list. */
  GList *list = NULL, *number_list = NULL;

  /* This is a list of strings. */
  list = g_list_append (list, "first");
  list = g_list_append (list, "second");

  /* This is a list of integers. */
  number_list = g_list_append (number_list, GINT_TO_POINTER (27));
  number_list = g_list_append (number_list, GINT_TO_POINTER (14));

g_list_prepend ()

GList*      g_list_prepend                  (GList *list, gpointer data);

Adds a new element on to the start of the list.

  /* Notice that it is initialized to the empty list. */
  GList *list = NULL;
  list = g_list_prepend (list, "last");
  list = g_list_prepend (list, "first");

g_list_insert ()

GList*      g_list_insert                   (GList *list, gpointer data, gint position);

Inserts a new element into the list at the given position.

g_list_insert_before ()

GList*      g_list_insert_before            (GList *list, GList *sibling, gpointer data);

Inserts a new element into the list before the given position.

g_list_insert_sorted ()

GList*      g_list_insert_sorted            (GList *list, gpointer data, GCompareFunc func);

Inserts a new element into the list, using the given comparison function to determine its position.

g_list_remove ()

GList*      g_list_remove                   (GList *list, gconstpointer data);

Removes an element from a GList. If two elements contain the same data, only the first is removed. If none of the elements contain the data, the GList is unchanged.

g_list_remove_link ()

GList*      g_list_remove_link              (GList *list, GList *llink);

Removes an element from a GList, without freeing the element. The removed element's prev and next links are set to NULL, so that it becomes a self-contained list with one element.

g_list_delete_link ()

GList*      g_list_delete_link              (GList *list, GList *link_);

Deletes the node link_ from list.

g_list_remove_all ()

GList*      g_list_remove_all               (GList *list, gconstpointer data);

Removes all list nodes with data equal to data. Returns the new head of the list. Contrast with g_list_remove() which removes only the first node matching the given data.

g_list_free ()

void        g_list_free                     (GList *list);

Frees all of the memory used by a GList. The freed elements are added to the GAllocator free list.

Note: If list elements contain dynamically-allocated memory, they should be freed first.

g_list_alloc ()

GList*      g_list_alloc                    (void);

Allocates space for one GList element. It is called by g_list_append(), g_list_prepend(), g_list_insert() and g_list_insert_sorted() and so is rarely used on its own.

g_list_free_1 ()

void        g_list_free_1                   (GList *list);

Frees one GList element. It is usually used after g_list_remove_link().

g_list_length ()

guint       g_list_length                   (GList *list);

Gets the number of elements in a GList.

g_list_copy ()

GList*      g_list_copy                     (GList *list);

Copies a GList.

Note that this is a "shallow" copy. If the list elements consist of pointers to data, the pointers are copied but the actual data isn't.

g_list_reverse ()

GList*      g_list_reverse                  (GList *list);

Reverses a GList. It simply switches the next and prev pointers of each element.

g_list_sort ()

GList*      g_list_sort                     (GList *list, GCompareFunc compare_func);

Sorts a GList using the given comparison function.

GCompareFunc ()

gint        (*GCompareFunc)                 (gconstpointer a, gconstpointer b);

Specifies the type of a comparison function used to compare two values. The function should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second.

g_list_sort_with_data ()

GList*      g_list_sort_with_data           (GList *list, GCompareDataFunc compare_func, gpointer user_data);

Like g_list_sort(), but the comparison function accepts a user data argument.

GCompareDataFunc ()

gint        (*GCompareDataFunc)             (gconstpointer a, gconstpointer b, gpointer user_data);

Specifies the type of a comparison function used to compare two values. The function should return a negative integer if the first value comes before the second, 0 if they are equal, or a positive integer if the first value comes after the second.

g_list_concat ()

GList*      g_list_concat                   (GList *list1, GList *list2);

Adds the second GList onto the end of the first GList. Note that the elements of the second GList are not copied. They are used directly.

g_list_foreach ()

void        g_list_foreach                  (GList *list, GFunc func, gpointer user_data);

Calls a function for each element of a GList.

GFunc ()

void        (*GFunc)                        (gpointer data, gpointer user_data);

Specifies the type of functions passed to g_list_foreach() and g_slist_foreach().

g_list_first ()

GList*      g_list_first                    (GList *list);

Gets the first element in a GList.

g_list_last ()

GList*      g_list_last                     (GList *list);

Gets the last element in a GList.

g_list_previous()

#define     g_list_previous(list)

A convenient macro to get the previous element in a GList.

g_list_next()

#define     g_list_next(list)

A convenient macro to get the next element in a GList.

g_list_nth ()

GList*      g_list_nth                      (GList *list, guint n);

Gets the element at the given position in a GList.

g_list_nth_data ()

gpointer    g_list_nth_data                 (GList *list, guint n);

Gets the data of the element at the given position.

g_list_nth_prev ()

GList*      g_list_nth_prev                 (GList *list, guint n);

Gets the element n places before list.

g_list_find ()

GList*      g_list_find                     (GList *list, gconstpointer data);

Finds the element in a GList which contains the given data.

g_list_find_custom ()

GList*      g_list_find_custom              (GList *list, gconstpointer data, GCompareFunc func);

Finds an element in a GList, using a supplied function to find the desired element. It iterates over the list, calling the given function which should return 0 when the desired element is found. The function takes two gconstpointer arguments, the GList element's data as the first argument and the given user data.

g_list_position ()

gint        g_list_position                 (GList *list, GList *llink);

Gets the position of the given element in the GList (starting from 0).

g_list_index ()

gint        g_list_index                    (GList *list, gconstpointer data);

Gets the position of the element containing the given data (starting from 0).

g_list_push_allocator ()

void        g_list_push_allocator           (GAllocator *allocator);

Sets the allocator to use to allocate GList elements. Use g_list_pop_allocator() to restore the previous allocator.

Note that this function is not available if GLib has been compiled with --disable-mem-pools