|
+ |
|
|
GLib Reference Manual | @@ -46,112 +26,109 @@ Description
|---|
#include <glib.h> - GList; +struct GList; -GList* g_list_append (GList *list, - gpointer data); -GList* g_list_prepend (GList *list, - gpointer data); -GList* g_list_insert (GList *list, - gpointer data, - gint position); -GList* g_list_insert_before (GList *list, - GList *sibling, - gpointer data); -GList* g_list_insert_sorted (GList *list, - gpointer data, - GCompareFunc func); -GList* g_list_remove (GList *list, - gconstpointer data); -GList* g_list_remove_link (GList *list, - GList *llink); -GList* g_list_delete_link (GList *list, - GList *link_); -GList* g_list_remove_all (GList *list, - gconstpointer data); -void g_list_free (GList *list); +GList * g_list_append (GList *list, +gpointer data); +GList * g_list_prepend (GList *list, +gpointer data); +GList * g_list_insert (GList *list, +gpointer data, +gint position); +GList * g_list_insert_before (GList *list, +GList *sibling, +gpointer data); +GList * g_list_insert_sorted (GList *list, +gpointer data, +GCompareFunc func); +GList * g_list_remove (GList *list, +gconstpointer data); +GList * g_list_remove_link (GList *list, +GList *llink); +GList * g_list_delete_link (GList *list, +GList *link_); +GList * g_list_remove_all (GList *list, +gconstpointer data); +void g_list_free (GList *list); +void g_list_free_full (GList *list, +GDestroyNotify free_func); -GList* g_list_alloc (void); -void g_list_free_1 (GList *list); +GList * g_list_alloc (void); +void g_list_free_1 (GList *list); #define g_list_free1 -guint g_list_length (GList *list); -GList* g_list_copy (GList *list); -GList* g_list_reverse (GList *list); -GList* g_list_sort (GList *list, - GCompareFunc compare_func); -gint (*GCompareFunc) (gconstpointer a, - gconstpointer b); -GList* g_list_insert_sorted_with_data (GList *list, - gpointer data, - GCompareDataFunc func, - gpointer user_data); -GList* g_list_sort_with_data (GList *list, - GCompareDataFunc compare_func, - gpointer user_data); -gint (*GCompareDataFunc) (gconstpointer a, - gconstpointer b, - gpointer user_data); -GList* g_list_concat (GList *list1, - GList *list2); -void g_list_foreach (GList *list, - GFunc func, - gpointer user_data); -void (*GFunc) (gpointer data, - gpointer user_data); +guint g_list_length (GList *list); +GList * g_list_copy (GList *list); +GList * g_list_reverse (GList *list); +GList * g_list_sort (GList *list, +GCompareFunc compare_func); +gint (*GCompareFunc) (gconstpointer a, +gconstpointer b); +GList * g_list_insert_sorted_with_data (GList *list, +gpointer data, +GCompareDataFunc func, +gpointer user_data); +GList * g_list_sort_with_data (GList *list, +GCompareDataFunc compare_func, +gpointer user_data); +gint (*GCompareDataFunc) (gconstpointer a, +gconstpointer b, +gpointer user_data); +GList * g_list_concat (GList *list1, +GList *list2); +void g_list_foreach (GList *list, +GFunc func, +gpointer user_data); +void (*GFunc) (gpointer data, +gpointer user_data); -GList* g_list_first (GList *list); -GList* g_list_last (GList *list); +GList * g_list_first (GList *list); +GList * g_list_last (GList *list); #define g_list_previous (list) #define g_list_next (list) -GList* g_list_nth (GList *list, - guint n); -gpointer g_list_nth_data (GList *list, - guint n); -GList* g_list_nth_prev (GList *list, - guint n); +GList * g_list_nth (GList *list, +guint n); +gpointer g_list_nth_data (GList *list, +guint n); +GList * g_list_nth_prev (GList *list, +guint n); -GList* g_list_find (GList *list, - gconstpointer data); -GList* g_list_find_custom (GList *list, - gconstpointer data, - GCompareFunc func); -gint g_list_position (GList *list, - GList *llink); -gint g_list_index (GList *list, - gconstpointer data); - -void g_list_push_allocator (gpointer allocator); -void g_list_pop_allocator (void); +GList * g_list_find (GList *list, +gconstpointer data); +GList * g_list_find_custom (GList *list, +gconstpointer data, +GCompareFunc func); +gint g_list_position (GList *list, +GList *llink); +gint g_list_index (GList *list, +gconstpointer data);
-The GList structure and its associated functions provide a standard +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 Lists which +directions (unlike the Singly-Linked Lists which only allows movement through the list in the forward direction).
@@ -164,13 +141,13 @@ List elements are allocated from the GList functions expect to be passed a pointer +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
-the empty list so you simply set a GList* to NULL.
+There is no function to create a GList. NULL is considered to be
+the empty list so you simply set a GList* to NULL.
To add elements, use g_list_append(), g_list_prepend(),
@@ -192,54 +169,53 @@ To find the index of an element use g_list_foreach().
-To free the entire list, use g_list_free().
g_list_free().
+
typedef struct {
+
+struct GList
+struct GList {
gpointer data;
GList *next;
GList *prev;
-} GList;
+};
-The GList struct is used for each element in a doubly-linked list.
+The GList struct is used for each element in a doubly-linked list.
+
gpointer data;
holds the element's data, which can be a pointer to any kind
- of data, or any integer value using the Type Conversion
- Macros.
-
+holds the element's data, which can be a pointer to any kind
+of data, or any integer value using the Type Conversion
+Macros.
-GList *next;
contains the link to the next element in the list.
-
+GList *next;
contains the link to the next element in the list.
-GList *prev;
contains the link to the previous element in the list.
-
+GList *prev;
contains the link to the previous element in the list.
-
+
g_list_append ()
-GList* g_list_append (GList *list,
- gpointer data);
+GList * g_list_append (GList *list,
+ gpointer data);
Adds a new element on to the end of the list.
-
+
Note
The return value is the new start of the list, which
@@ -250,7 +226,7 @@ may have changed, so make sure you store the new value.
-
+
Note
Note that g_list_append() has to traverse the entire list
@@ -263,50 +239,68 @@ the elements and reverse the list when all elements have been added.
-
-/* Notice that these are initialized to the empty list. */
-GList *list = NULL, *number_list = NULL;
+
+
+
+
+ 1
+2
+3
+4
+5
+6
+7
+8
+9
+10
/* 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 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));
+
+
+
-/* 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);
+GList * g_list_prepend (GList *list,
+ gpointer data);
Adds a new element on to the start of the list.
-
+
Note
The return value is the new start of the list, which
@@ -317,370 +311,411 @@ may have changed, so make sure you store the new value.
-
-/* Notice that it is initialized to the empty list. */
-GList *list = NULL;
-list = g_list_prepend (list, "last");
-list = g_list_prepend (list, "first");
-
+
+
+
+
+ 1
+2
+3
+4
/* 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);
+GList * g_list_insert (GList *list,
+ gpointer data,
+ gint position);
-Inserts a new element into the list at the given position.
+Inserts a new element into the list at the given position.
+
list :
a pointer to a GList
+ a pointer to a GList
data :
the data for the new element
-
+the data for the new element
position :
the position to insert the element. If this is
- negative, or is larger than the number of elements in the
- list, the new element is added on to the end of the list.
-
+the position to insert the element. If this is
+negative, or is larger than the number of elements in the
+list, the new element is added on to the end of the list.
Returns :
the new start of the GList
+ the new start of the GList
-
+
g_list_insert_before ()
-GList* g_list_insert_before (GList *list,
- GList *sibling,
- gpointer data);
+GList * g_list_insert_before (GList *list,
+ GList *sibling,
+ gpointer data);
-Inserts a new element into the list before the given position.
+Inserts a new element into the list before the given position.
+
list :
a pointer to a GList
+ a pointer to a GList
sibling :
the list element before which the new element
- is inserted or NULL to insert at the end of the list
-
+the list element before which the new element
+is inserted or NULL to insert at the end of the list
data :
the data for the new element
-
+the data for the new element
Returns :
the new start of the GList
+ the new start of the GList
-
+
g_list_insert_sorted ()
-GList* g_list_insert_sorted (GList *list,
- gpointer data,
- GCompareFunc func);
+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.
+function to determine its position.
+
list :
a pointer to a GList
+ a pointer to a GList
data :
the data for the new element
-
+the data for the new element
func :
the function to compare elements in the list. It should
- return a number > 0 if the first parameter comes after the
- second parameter in the sort order.
-
+the function to compare elements in the list. It should
+return a number > 0 if the first parameter comes after the
+second parameter in the sort order.
Returns :
the new start of the GList
+ the new start of the GList
-
+
g_list_remove ()
-GList* g_list_remove (GList *list,
- gconstpointer data);
+GList * g_list_remove (GList *list,
+ gconstpointer data);
-Removes an element from a GList.
+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.
+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);
+GList * g_list_remove_link (GList *list,
+ GList *llink);
-Removes an element from a GList, without freeing the element.
+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.
+that it becomes a self-contained list with one element.
+
-
+
g_list_delete_link ()
-GList* g_list_delete_link (GList *list,
- GList *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.
+without freeing it.
+
-
+
g_list_remove_all ()
-GList* g_list_remove_all (GList *list,
- gconstpointer data);
+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.
+matching the given data.
+
-
+
g_list_free ()
-void g_list_free (GList *list);
+void g_list_free (GList *list);
-Frees all of the memory used by a GList.
+Frees all of the memory used by a GList.
The freed elements are returned to the slice allocator.
-
+
Note
If list elements contain dynamically-allocated memory,
-they should be freed first.
+you should either use g_list_free_full() or free them manually
+first.
+
+
-
+
+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 the specified destroy function on every element's data.
+
+
+
+list :
a pointer to a GList
+
+
+
+free_func :
the function to be called to free each element's data
+
+
+
+Since 2.28
+
+
+
g_list_alloc ()
-GList* g_list_alloc (void);
+GList * g_list_alloc (void);
-Allocates space for one GList element. It is called by
+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_insert_sorted() and so is rarely used on its own.
+
-
+
g_list_free_1 ()
-void g_list_free_1 (GList *list);
+void g_list_free_1 (GList *list);
-Frees one GList element.
-It is usually used after g_list_remove_link().
+Frees one GList element.
+It is usually used after g_list_remove_link().
+
-
+
g_list_free1
#define g_list_free1
-Another name for g_list_free_1().
+Another name for g_list_free_1().
+
-
+
g_list_length ()
-guint g_list_length (GList *list);
+guint g_list_length (GList *list);
-Gets the number of elements in a GList.
+Gets the number of elements in a GList.
-
+
Note
This function iterates over the whole list to
count its elements.
+
+
-
+
g_list_copy ()
-GList* g_list_copy (GList *list);
+GList * g_list_copy (GList *list);
-Copies a GList.
+Copies a GList.
-
+
Note
Note that this is a "shallow" copy. If the list elements
@@ -688,148 +723,147 @@ consist of pointers to data, the pointers are copied but
the actual data is not.
+
+
-
+
g_list_reverse ()
-GList* g_list_reverse (GList *list);
+GList * g_list_reverse (GList *list);
-Reverses a GList.
-It simply switches the next and prev pointers of each element.
+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);
+GList * g_list_sort (GList *list,
+ GCompareFunc compare_func);
-Sorts a GList using the given comparison function.
+Sorts a GList using the given comparison function. The algorithm
+used is a stable sort.
+
list :
a GList
+ a GList
compare_func :
the comparison function used to sort the GList.
- This function is passed the data from 2 elements of the GList
- and should return 0 if they are equal, a negative value if the
- first element comes before the second, or a positive value if
- the first element comes after the second.
-
+the comparison function used to sort the GList.
+This function is passed the data from 2 elements of the GList
+and should return 0 if they are equal, a negative value if the
+first element comes before the second, or a positive value if
+the first element comes after the second.
Returns :
the start of the sorted GList
+ the start of the sorted GList
-
+
GCompareFunc ()
-gint (*GCompareFunc) (gconstpointer a,
- gconstpointer b);
+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.
+integer if the first value comes after the second.
+
a :
a value.
-
+a value.
b :
a value to compare with.
-
+a value to compare with.
Returns :
negative value if a < b; zero if a = b; positive
- value if a > b.
-
+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);
+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.
+function to determine its position.
+
list :
a pointer to a GList
+ a pointer to a GList
data :
the data for the new element
-
+the data for the new element
func :
the function to compare elements in the list.
- It should return a number > 0 if the first parameter
- comes after the second parameter in the sort order.
-
+the function to compare elements in the list.
+It should return a number > 0 if the first parameter
+comes after the second parameter in the sort order.
user_data :
user data to pass to comparison function.
-
+user data to pass to comparison function.
Returns :
the new start of the GList
-
+ the new start of the GList
@@ -837,518 +871,463 @@ function to determine its position.
Since 2.10
-
+
g_list_sort_with_data ()
-GList* g_list_sort_with_data (GList *list,
- GCompareDataFunc compare_func,
- gpointer user_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.
+a user data argument.
+
-
+
GCompareDataFunc ()
-gint (*GCompareDataFunc) (gconstpointer a,
- gconstpointer b,
- gpointer user_data);
+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.
+integer if the first value comes after the second.
+
a :
a value.
-
+a value.
b :
a value to compare with.
-
+a value to compare with.
user_data :
user data to pass to comparison function.
-
+user data to pass to comparison function.
Returns :
negative value if a < b; zero if a = b; positive
- value if a > b.
-
+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);
+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.
+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);
+void g_list_foreach (GList *list,
+ GFunc func,
+ gpointer user_data);
-Calls a function for each element of a GList.
+Calls a function for each element of a GList.
+
-
+
GFunc ()
-void (*GFunc) (gpointer data,
- gpointer user_data);
+void (*GFunc) (gpointer data,
+ gpointer user_data);
Specifies the type of functions passed to g_list_foreach() and
-g_slist_foreach().
+g_slist_foreach().
+
data :
the element's data.
-
+the element's data.
user_data :
user data passed to g_list_foreach() or
- g_slist_foreach().
-
+user data passed to g_list_foreach() or
+g_slist_foreach().
-
+
g_list_first ()
-GList* g_list_first (GList *list);
+GList * g_list_first (GList *list);
-Gets the first element in a GList.
+Gets the first element in a GList.
+
-
+
g_list_last ()
-GList* g_list_last (GList *list);
+GList * g_list_last (GList *list);
-Gets the last element in a GList.
+Gets the last element in a GList.
+
-
+
g_list_previous()
#define g_list_previous(list)
-A convenience macro to get the previous element in a GList.
+A convenience macro to get the previous element in a GList.
+
-
+
g_list_next()
#define g_list_next(list)
-A convenience macro to get the next element in a GList.
+A convenience macro to get the next element in a GList.
+
-
+
g_list_nth ()
-GList* g_list_nth (GList *list,
- guint n);
+GList * g_list_nth (GList *list,
+ guint n);
-Gets the element at the given position in a GList.
+Gets the element at the given position in a GList.
+
-
+
g_list_nth_data ()
-gpointer g_list_nth_data (GList *list,
- guint n);
+gpointer g_list_nth_data (GList *list,
+ guint n);
-Gets the data of the element at the given position.
+Gets the data of the element at the given position.
+
-
+
g_list_nth_prev ()
-GList* g_list_nth_prev (GList *list,
- guint n);
+GList * g_list_nth_prev (GList *list,
+ guint n);
-Gets the element n places before list.
+Gets the element n places before list.
+
-
+
g_list_find ()
-GList* g_list_find (GList *list,
- gconstpointer data);
+GList * g_list_find (GList *list,
+ gconstpointer data);
-Finds the element in a GList which
-contains the given 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);
+GList * g_list_find_custom (GList *list,
+ gconstpointer data,
+ GCompareFunc func);
-Finds an element in a GList, using a supplied function to
+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.
+the GList element's data as the first argument and the
+given user data.
+
list :
a GList
+ a GList
data :
user data passed to the function
-
+user data passed to the function
func :
the function to call for each element.
- It should return 0 when the desired element is found
-
+the function to call for each element.
+It should return 0 when the desired element is found
Returns :
the found GList element, or NULL if it is not found
-
+the found GList element, or NULL if it is not found
-
+
g_list_position ()
-gint g_list_position (GList *list,
- GList *llink);
+gint g_list_position (GList *list,
+ GList *llink);
Gets the position of the given element
-in the GList (starting from 0).
+in the GList (starting from 0).
+
-
+
g_list_index ()
-gint g_list_index (GList *list,
- gconstpointer data);
+gint g_list_index (GList *list,
+ gconstpointer data);
Gets the position of the element containing
-the given data (starting from 0).
+the given data (starting from 0).
+
-
-
-g_list_push_allocator ()
-void g_list_push_allocator (gpointer allocator);
-
-Warning
-g_list_push_allocator has been deprecated since version 2.10 and should not be used in newly-written code. It does nothing, since GList has been converted
- to the slice
- 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
-
-
-allocator :
the GAllocator to use when allocating GList elements.
-
-
-
-
-
-
-g_list_pop_allocator ()
-void g_list_pop_allocator (void);
-
-Warning
-g_list_pop_allocator has been deprecated since version 2.10 and should not be used in newly-written code. It does nothing, since GList has been converted
- to the slice
- allocator
-
-
-Restores the previous GAllocator, used when allocating GList
-elements.
-
-
-Note that this function is not available if GLib has been compiled
-with --disable-mem-pools
-
+ Generated by GTK-Doc V1.18