Description
The GList structure and its associated functions provide a standard
doubly-linked list data structure.
Each element in the list contains a piece of data, together with
pointers which link to the previous and next elements in the list.
Using these pointers it is possible to move through the list in both
directions (unlike the singly-linked GSList,
which only allows movement through the list in the forward direction).
The double linked list does not keep track of the number of items
and does not keep track of both the start and end of the list. If
you want fast access to both the start and the end of the list,
and/or the number of items in the list, use a
GQueue instead.
The data contained in each element can be either integer values, by
using one of the Type Conversion Macros,
or simply pointers to any type of data.
List elements are allocated from the slice allocator,
which is more efficient than allocating elements individually.
Note that most of the GList functions expect to be passed a pointer
to the first element in the list. The functions which insert
elements return the new start of the list, which may have changed.
There is no function to create a GList. NULL is considered to be
a valid, empty list so you simply set a GList* to NULL to initialize
it.
To add elements, use g_list_append(), g_list_prepend(),
g_list_insert() and g_list_insert_sorted().
To visit all elements in the list, use a loop over the list:
To call a function for each element in the list, use g_list_foreach().
To loop over the list and modify it (e.g. remove a certain element)
a while loop is more appropriate, for example:
To remove elements, use g_list_remove().
To navigate in a list, use g_list_first(), g_list_last(),
g_list_next(), g_list_previous().
To find elements in the list use g_list_nth(), g_list_nth_data(),
g_list_find() and g_list_find_custom().
To find the index of an element use g_list_position() and
g_list_index().
To free the entire list, use g_list_free() or g_list_free_full().
Functions
g_list_append ()
GList *
g_list_append (GList *list,
gpointer data);
Adds a new element on to the end of the list.
Note that the return value is the new start of the list,
if list
was empty; make sure you store the new value.
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 use g_list_prepend() and reverse
the list with g_list_reverse() when all elements have been added.
Returns
either list
or the new start of the GList if list
was NULL
g_list_prepend ()
GList *
g_list_prepend (GList *list,
gpointer data);
Prepends a new element on to the start of the list.
Note that the return value is the new start of the list,
which will have changed, so make sure you store the new value.
Do not use this function to prepend a new element to a different
element than the start of the list. Use g_list_insert_before() instead.
Returns
a pointer to the newly prepended element, which is the new
start of the GList
g_list_insert ()
GList *
g_list_insert (GList *list,
gpointer data,
gint position);
Inserts a new element into the list at the given position.
Returns
the (possibly changed) start of the GList
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.
Returns
the (possibly changed) start of the GList
g_list_insert_before_link ()
GList *
g_list_insert_before_link (GList *list,
GList *sibling,
GList *link_);
Inserts link_
into the list before the given position.
Returns
the (possibly changed) start of the GList
Since: 2.62
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.
If you are adding many new elements to a list, and the number of
new elements is much larger than the length of the list, use
g_list_prepend() to add the new items and sort the list afterwards
with g_list_sort().
Returns
the (possibly changed) start of the GList
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.
Returns
the (possibly changed) start of the GList
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.
This function is for example used to move an element in the list
(see the example for g_list_concat()) or to remove an element in
the list before freeing its data:
Returns
the (possibly changed) start of the GList
g_list_delete_link ()
GList *
g_list_delete_link (GList *list,
GList *link_);
Removes the node link_ from the list and frees it.
Compare this to g_list_remove_link() which removes the node
without freeing it.
Returns
the (possibly changed) start of the GList
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.
Returns
the (possibly changed) start of the GList
g_list_free ()
void
g_list_free (GList *list);
Frees all of the memory used by a GList.
The freed elements are returned to the slice allocator.
If list elements contain dynamically-allocated memory, you should
either use g_list_free_full() or free them manually first.
It can be combined with g_steal_pointer() to ensure the list head pointer
is not left dangling:
g_list_free_full ()
void
g_list_free_full (GList *list,
GDestroyNotify free_func);
Convenience method, which frees all the memory used by a GList,
and calls free_func
on every element's data.
free_func
must not modify the list (eg, by removing the freed
element from it).
It can be combined with g_steal_pointer() to ensure the list head pointer
is not left dangling — this also has the nice property that the head pointer
is cleared before any of the list elements are freed, to prevent double frees
from free_func
:
Since: 2.28
g_clear_list ()
void
g_clear_list (GList **list_ptr,
GDestroyNotify destroy);
Clears a pointer to a GList, freeing it and, optionally, freeing its elements using destroy
.
list_ptr
must be a valid pointer. If list_ptr
points to a null GList, this does nothing.
[skip]
Since: 2.64
g_list_free_1 ()
void
g_list_free_1 (GList *list);
Frees one GList element, but does not update links from the next and
previous elements in the list, so you should not call this function on an
element that is currently part of a list.
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.
This function iterates over the whole list to count its elements.
Use a GQueue instead of a GList if you regularly need the number
of items. To check whether the list is non-empty, it is faster to check
list
against NULL.
Returns
the number of elements in the 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 is not. See g_list_copy_deep() if you need
to copy the data as well.
Returns
the start of the new list that holds the same data as list
g_list_copy_deep ()
GList *
g_list_copy_deep (GList *list,
GCopyFunc func,
gpointer user_data);
Makes a full (deep) copy of a GList.
In contrast with g_list_copy(), this function uses func
to make
a copy of each list element, in addition to copying the list
container itself.
func
, as a GCopyFunc, takes two arguments, the data to be copied
and a user_data
pointer. On common processor architectures, it's safe to
pass NULL as user_data
if the copy function takes only one argument. You
may get compiler warnings from this though if compiling with GCC’s
-Wcast-function-type warning.
For instance, if list
holds a list of GObjects, you can do:
And, to entirely free the new list, you could do:
Returns
the start of the new list that holds a full copy of list
,
use g_list_free_full() to free it
Since: 2.34
g_list_reverse ()
GList *
g_list_reverse (GList *list);
Reverses a GList.
It simply switches the next and prev pointers of each element.
Returns
the start of the reversed GList
g_list_sort ()
GList *
g_list_sort (GList *list,
GCompareFunc compare_func);
Sorts a GList using the given comparison function. The algorithm
used is a stable sort.
Returns
the (possibly changed) start of the GList
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.
Returns
negative value if a
< b
; zero if a
= b
; positive
value if a
> b
g_list_insert_sorted_with_data ()
GList *
g_list_insert_sorted_with_data (GList *list,
gpointer data,
GCompareDataFunc func,
gpointer user_data);
Inserts a new element into the list, using the given comparison
function to determine its position.
If you are adding many new elements to a list, and the number of
new elements is much larger than the length of the list, use
g_list_prepend() to add the new items and sort the list afterwards
with g_list_sort().
Returns
the (possibly changed) start of the GList
Since: 2.10
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.
Returns
negative value if a
< b
; zero if a
= b
; positive
value if a
> b
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.
This function is for example used to move an element in the list.
The following example moves an element to the top of the list:
Returns
the start of the new GList, which equals list1
if not NULL
g_list_foreach ()
void
g_list_foreach (GList *list,
GFunc func,
gpointer user_data);
Calls a function for each element of a GList.
It is safe for func
to remove the element from list
, but it must
not modify any part of the list after that element.
g_list_first ()
GList *
g_list_first (GList *list);
Gets the first element in a GList.
Returns
the first element in the GList,
or NULL if the GList has no elements
g_list_last ()
GList *
g_list_last (GList *list);
Gets the last element in a GList.
Returns
the last element in the GList,
or NULL if the GList has no elements
g_list_previous()
#define g_list_previous(list)
A convenience macro to get the previous element in a GList.
Note that it is considered perfectly acceptable to access
list->prev
directly.
Returns
the previous element, or NULL if there are no previous
elements
g_list_next()
#define g_list_next(list)
A convenience macro to get the next element in a GList.
Note that it is considered perfectly acceptable to access
list->next
directly.
Returns
the next element, or NULL if there are no more elements
g_list_nth ()
GList *
g_list_nth (GList *list,
guint n);
Gets the element at the given position in a GList.
This iterates over the list until it reaches the n
-th position. If you
intend to iterate over every element, it is better to use a for-loop as
described in the GList introduction.
Returns
the element, or NULL if the position is off
the end of the GList
g_list_nth_data ()
gpointer
g_list_nth_data (GList *list,
guint n);
Gets the data of the element at the given position.
This iterates over the list until it reaches the n
-th position. If you
intend to iterate over every element, it is better to use a for-loop as
described in the GList introduction.
Returns
the element's data, or NULL if the position
is off the end of the GList
g_list_nth_prev ()
GList *
g_list_nth_prev (GList *list,
guint n);
Gets the element n
places before list
.
Returns
the element, or NULL if the position is
off the end of the GList
g_list_find ()
GList *
g_list_find (GList *list,
gconstpointer data);
Finds the element in a GList which contains the given data.
Returns
the found GList element, or NULL if it is not found
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.
Returns
the found GList element, or NULL if it is not found
g_list_position ()
gint
g_list_position (GList *list,
GList *llink);
Gets the position of the given element
in the GList (starting from 0).
Returns
the position of the element in the GList,
or -1 if the element is not found
g_list_index ()
gint
g_list_index (GList *list,
gconstpointer data);
Gets the position of the element containing
the given data (starting from 0).
Returns
the index of the element containing the data,
or -1 if the data is not found