19.2. Doubly Linked Lists

The following functions are used to create, manage, and destroy standard doubly linked lists. Each element in the list contains a piece of data, together with pointers which link to the previous and next elements in the list. This enables easy movement in either direction through the list. The data item is of type "gpointer", which means the data can be a pointer to your real data or (through casting) a numeric value (but do not assume that int and gpointer have the same size!). These routines internally allocate list elements in blocks, which is more efficient than allocating elements individually.

There is no function to specifically create a list. Instead, simply create a variable of type GList* and set its value to NULL; NULL is considered to be the empty list.

To add elements to a list, use the g_list_append(), g_list_prepend(), g_list_insert(), or g_list_insert_sorted() routines. In all cases they accept a pointer to the beginning of the list, and return the (possibly changed) pointer to the beginning of the list. Thus, for all of the operations that add or remove elements, be sure to save the returned value!

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

This adds a new element (with value data) onto the end of the list.

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

This adds a new element (with value data) to the beginning of the list.

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

This inserts a new element (with value data) into the list at the given position. If position is 0, this is just like g_list_prepend(); if position is less than 0, this is just like g_list_append().

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

This removes the element in the list with the value data; if the element isn't there, the list is unchanged.

void g_list_free( GList *list );

This frees all of the memory used by a GList. If the list elements refer to dynamically-allocated memory, then they should be freed first.

There are many other GLib functions that support doubly linked lists; see the glib documentation for more information. Here are a few of the more useful functions' signatures:

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

GList *g_list_reverse( GList *list );

GList *g_list_nth( GList *list,
                   gint   n );
			   
GList *g_list_find( GList    *list,
                    gpointer  data );

GList *g_list_last( GList *list );

GList *g_list_first( GList *list );

gint g_list_length( GList *list );

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