mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-12-22 15:59:24 +01:00
468 lines
7.9 KiB
Plaintext
468 lines
7.9 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Doubly-Linked Lists
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
linked lists containing integer values or pointers to data, with the ability
|
|
to iterate over the list in both directions
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
The #GList structure and its associated functions provide a standard
|
|
doubly-linked list data structure.
|
|
</para>
|
|
<para>
|
|
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
|
|
<link linkend="glib-Singly-Linked-lists">Singly-Linked Lists</link>
|
|
which only allows movement through the list in the forward direction).
|
|
</para>
|
|
<para>
|
|
The data contained in each element can be either integer values, by using one
|
|
of the
|
|
<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
|
|
or simply pointers to any type of data.
|
|
</para>
|
|
<para>
|
|
List elements are allocated from the <link linkend="glib-Memory-Slices">slice
|
|
allocator</link>, which is more efficient than allocating elements
|
|
individually.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
There is no function to create a #GList. %NULL is considered to be the empty
|
|
list so you simply set a #GList* to %NULL.
|
|
</para>
|
|
<para>
|
|
To add elements, use g_list_append(), g_list_prepend(), g_list_insert()
|
|
and g_list_insert_sorted().
|
|
</para>
|
|
<para>
|
|
To remove elements, use g_list_remove().
|
|
</para>
|
|
<para>
|
|
To find elements in the list use g_list_first(), g_list_last(), g_list_next(),
|
|
g_list_previous(), g_list_nth(), g_list_nth_data(), g_list_find() and
|
|
g_list_find_custom().
|
|
</para>
|
|
<para>
|
|
To find the index of an element use g_list_position() and g_list_index().
|
|
</para>
|
|
<para>
|
|
To call a function for each element in the list use g_list_foreach().
|
|
</para>
|
|
<para>
|
|
To free the entire list, use g_list_free().
|
|
</para>
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
<!-- ##### SECTION Stability_Level ##### -->
|
|
|
|
|
|
<!-- ##### STRUCT GList ##### -->
|
|
<para>
|
|
The #GList struct is used for each element in a doubly-linked list.
|
|
</para>
|
|
|
|
@data: holds the element's data, which can be a pointer to any kind of data,
|
|
or any integer value using the
|
|
<link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>.
|
|
@next: contains the link to the next element in the list.
|
|
@prev: contains the link to the previous element in the list.
|
|
|
|
<!-- ##### FUNCTION g_list_append ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_prepend ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_insert ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@position:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_insert_before ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@sibling:
|
|
@data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_insert_sorted ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@func:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_remove ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_remove_link ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@llink:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_delete_link ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@link_:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_remove_all ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_free ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_alloc ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@Returns: a pointer to the newly-allocated #GList element.
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_free_1 ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
|
|
|
|
<!-- ##### MACRO g_list_free1 ##### -->
|
|
<para>
|
|
Another name for g_list_free_1().
|
|
</para>
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_length ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_copy ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_reverse ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_sort ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@compare_func:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GCompareFunc ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@a: a value.
|
|
@b: a value to compare with.
|
|
@Returns: negative value if @a < @b; zero if @a = @b; positive value
|
|
if @a > @b.
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_insert_sorted_with_data ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@func:
|
|
@user_data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_sort_with_data ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@compare_func:
|
|
@user_data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GCompareDataFunc ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@a: a value.
|
|
@b: a value to compare with.
|
|
@user_data: user data to pass to comparison function.
|
|
@Returns: negative value if @a < @b; zero if @a = @b; positive value
|
|
if @a > @b.
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_concat ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list1:
|
|
@list2:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_foreach ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@func:
|
|
@user_data:
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GFunc ##### -->
|
|
<para>
|
|
Specifies the type of functions passed to g_list_foreach() and
|
|
g_slist_foreach().
|
|
</para>
|
|
|
|
@data: the element's data.
|
|
@user_data: user data passed to g_list_foreach() or g_slist_foreach().
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_first ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_last ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### MACRO g_list_previous ##### -->
|
|
<para>
|
|
A convenience macro to gets the previous element in a #GList.
|
|
</para>
|
|
|
|
@list: an element in a #GList.
|
|
@Returns: the previous element, or %NULL if there are no previous elements.
|
|
|
|
|
|
<!-- ##### MACRO g_list_next ##### -->
|
|
<para>
|
|
A convenience macro to gets the next element in a #GList.
|
|
</para>
|
|
|
|
@list: an element in a #GList.
|
|
@Returns: the next element, or %NULL if there are no more elements.
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_nth ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@n:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_nth_data ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@n:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_nth_prev ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@n:
|
|
@Returns:
|
|
|
|
|
|
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_find ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_find_custom ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@func:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_position ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@llink:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_index ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@list:
|
|
@data:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_push_allocator ##### -->
|
|
<para>
|
|
Sets the allocator to use to allocate #GList elements.
|
|
Use g_list_pop_allocator() to restore the previous allocator.
|
|
</para>
|
|
<para>
|
|
Note that this function is not available if GLib has been compiled
|
|
with <option>--disable-mem-pools</option>
|
|
</para>
|
|
|
|
@allocator: the #GAllocator to use when allocating #GList elements.
|
|
@Deprecated: 2.10: It does nothing, since #GList has been
|
|
converted to the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
|
|
|
|
<!-- ##### FUNCTION g_list_pop_allocator ##### -->
|
|
<para>
|
|
Restores the previous #GAllocator, used when allocating #GList elements.
|
|
</para>
|
|
<para>
|
|
Note that this function is not available if GLib has been compiled
|
|
with <option>--disable-mem-pools</option>
|
|
</para>
|
|
|
|
@Deprecated: 2.10: It does nothing, since #GList has been
|
|
converted to the <link linkend="glib-Memory-Slices">slice allocator</link>
|
|
|
|
|