Package ch.bailu.gtk.glib
Class List
java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.type.Record
ch.bailu.gtk.glib.List
- All Implemented Interfaces:
PointerInterface
The #GList struct is used for each element in a doubly-linked list.
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic interface
static interface
static interface
static interface
static interface
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
holds the element's data, which can be a pointer to any kind
of data, or any integer value using the
[Type Conversion Macros][glib-Type-Conversion-Macros]static final String
contains the link to the next element in the liststatic final String
contains the link to the previous element in the list -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic List
alloc()
Allocates space for one #GList element.static List
Adds a new element on to the end of the list.static List
Adds the second #GList onto the end of the first #GList.static List
Copies a #GList.static List
copyDeep
(List list, List.OnCopyFunc func, Pointer user_data) Makes a full (deep) copy of a #GList.static List
deleteLink
(List list, List link_) Removes the node link_ from the list and frees it.static List
Finds the element in a #GList which contains the given data.static List
findCustom
(List list, Pointer data, List.OnCompareFunc func) Finds an element in a #GList, using a supplied function to
find the desired element.static List
Gets the first element in a #GList.static void
foreach
(List list, List.OnFunc func, Pointer user_data) Calls a function for each element of a #GList.static void
Frees all of the memory used by a #GList.static void
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.static void
freeFull
(List list, List.OnDestroyNotify free_func) Convenience method, which frees all the memory used by a #GList,
and calls @free_func on every element's data.static ClassHandler
holds the element's data, which can be a pointer to any kind
of data, or any integer value using the
[Type Conversion Macros][glib-Type-Conversion-Macros]contains the link to the next element in the listcontains the link to the previous element in the liststatic int
Gets the position of the element containing
the given data (starting from 0).static List
Inserts a new element into the list at the given position.static List
insertBefore
(List list, List sibling, Pointer data) Inserts a new element into the list before the given position.static List
insertBeforeLink
(List list, List sibling, List link_) Inserts @link_ into the list before the given position.static List
insertSorted
(List list, Pointer data, List.OnCompareFunc func) Inserts a new element into the list, using the given comparison
function to determine its position.static List
insertSortedWithData
(List list, Pointer data, List.OnCompareDataFunc func, Pointer user_data) Inserts a new element into the list, using the given comparison
function to determine its position.static List
Gets the last element in a #GList.static int
Gets the number of elements in a #GList.static List
Gets the element at the given position in a #GList.static Pointer
Gets the data of the element at the given position.static List
Gets the element @n places before @list.static int
Gets the position of the given element
in the #GList (starting from 0).static List
Prepends a new element on to the start of the list.static List
Removes an element from a #GList.static List
Removes all list nodes with data equal to @data.static List
removeLink
(List list, List llink) Removes an element from a #GList, without freeing the element.static List
Reverses a #GList.void
setFieldData
(Pointer 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][glib-Type-Conversion-Macros]void
setFieldNext
(List next) contains the link to the next element in the listvoid
setFieldPrev
(List prev) contains the link to the previous element in the liststatic List
sort
(List list, List.OnCompareFunc compare_func) Sorts a #GList using the given comparison function.static List
sortWithData
(List list, List.OnCompareDataFunc compare_func, Pointer user_data) Like g_list_sort(), but the comparison function accepts
a user data argument.Methods inherited from class ch.bailu.gtk.type.Pointer
asCPointer, cast, connectSignal, disconnectSignals, disconnectSignals, equals, hashCode, throwIfNull, throwNullPointerException, toString, unregisterCallbacks, unregisterCallbacks
Methods inherited from class ch.bailu.gtk.type.Type
asCPointer, asCPointer, asCPointerNotNull, asJnaPointer, asJnaPointer, asPointer, asPointer, cast, cast, throwIfNull
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods inherited from interface ch.bailu.gtk.type.PointerInterface
asCPointerNotNull, asJnaPointer, asPointer, isNotNull, isNull
-
Field Details
-
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][glib-Type-Conversion-Macros]- See Also:
-
NEXT
contains the link to the next element in the list- See Also:
-
PREV
contains the link to the previous element in the list- See Also:
-
-
Constructor Details
-
List
-
List
public List()
-
-
Method Details
-
getClassHandler
-
setFieldData
holds the element's data, which can be a pointer to any kind
of data, or any integer value using the
[Type Conversion Macros][glib-Type-Conversion-Macros] -
getFieldData
holds the element's data, which can be a pointer to any kind
of data, or any integer value using the
[Type Conversion Macros][glib-Type-Conversion-Macros] -
setFieldNext
contains the link to the next element in the list -
getFieldNext
contains the link to the next element in the list -
setFieldPrev
contains the link to the previous element in the list -
getFieldPrev
contains the link to the previous element in the list -
alloc
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.- Returns:
- a pointer to the newly-allocated #GList element
-
append
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.
<!-- language="C" --> // Notice that these are initialized to the empty list. GList *string_list = NULL, *number_list = NULL; // This is a list of strings. string_list = g_list_append (string_list, "first"); string_list = g_list_append (string_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));
- Parameters:
list
- a pointer to a #GListdata
- the data for the new element- Returns:
- either @list or the new start of the #GList if @list was %NULL
-
concat
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:<!-- language="C" --> list = g_list_remove_link (list, llink); list = g_list_concat (llink, list);
- Parameters:
list1
- a #GList, this must point to the top of the listlist2
- the #GList to add to the end of the first #GList, this must point to the top of the list- Returns:
- the start of the new #GList, which equals @list1 if not %NULL
-
copy
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.- Parameters:
list
- a #GList, this must point to the top of the list- Returns:
- the start of the new list that holds the same data as @list
-
copyDeep
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:<!-- language="C" --> another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
And, to entirely free the new list, you could do:<!-- language="C" --> g_list_free_full (another_list, g_object_unref);
- Parameters:
list
- a #GList, this must point to the top of the listfunc
- a copy function used to copy every element in the listuser_data
- user data passed to the copy function @func, or %NULL- Returns:
- the start of the new list that holds a full copy of @list, use g_list_free_full() to free it
-
deleteLink
Removes the node link_ from the list and frees it.
Compare this to g_list_remove_link() which removes the node
without freeing it.- Parameters:
list
- a #GList, this must point to the top of the listlink_
- node to delete from @list- Returns:
- the (possibly changed) start of the #GList
-
find
Finds the element in a #GList which contains the given data.- Parameters:
list
- a #GList, this must point to the top of the listdata
- the element data to find- Returns:
- the found #GList element, or %NULL if it is not found
-
findCustom
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.- Parameters:
list
- a #GList, this must point to the top of the listdata
- user data passed to the functionfunc
- 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
-
first
Gets the first element in a #GList.- Parameters:
list
- any #GList element- Returns:
- the first element in the #GList, or %NULL if the #GList has no elements
-
foreach
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.- Parameters:
list
- a #GList, this must point to the top of the listfunc
- the function to call with each element's datauser_data
- user data to pass to the function
-
free
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:<!-- language="C" --> GList *list_of_borrowed_things = …; /<!-- -->* (transfer container) *<!-- -->/ g_list_free (g_steal_pointer (&list_of_borrowed_things));
- Parameters:
list
- the first link of a #GList
-
free1
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().- Parameters:
list
- a #GList element
-
freeFull
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:<!-- language="C" --> GList *list_of_owned_things = …; /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/ g_list_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
- Parameters:
list
- the first link of a #GListfree_func
- the function to be called to free each element's data
-
index
Gets the position of the element containing
the given data (starting from 0).- Parameters:
list
- a #GList, this must point to the top of the listdata
- the data to find- Returns:
- the index of the element containing the data, or -1 if the data is not found
-
insert
Inserts a new element into the list at the given position.- Parameters:
list
- a pointer to a #GList, this must point to the top of the listdata
- the data for the new elementposition
- 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 (possibly changed) start of the #GList
-
insertBefore
Inserts a new element into the list before the given position.- Parameters:
list
- a pointer to a #GList, this must point to the top of the listsibling
- the list element before which the new element is inserted or %NULL to insert at the end of the listdata
- the data for the new element- Returns:
- the (possibly changed) start of the #GList
-
insertBeforeLink
public static List insertBeforeLink(@Nonnull List list, @Nullable List sibling, @Nonnull List link_) Inserts @link_ into the list before the given position.- Parameters:
list
- a pointer to a #GList, this must point to the top of the listsibling
- the list element before which the new element is inserted or %NULL to insert at the end of the listlink_
- the list element to be added, which must not be part of any other list- Returns:
- the (possibly changed) start of the #GList
-
insertSorted
public static List insertSorted(@Nonnull List list, @Nullable Pointer data, List.OnCompareFunc 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().- Parameters:
list
- a pointer to a #GList, this must point to the top of the already sorted listdata
- the data for the new elementfunc
- 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 (possibly changed) start of the #GList
-
insertSortedWithData
public static List insertSortedWithData(@Nonnull List list, @Nullable Pointer data, List.OnCompareDataFunc func, @Nullable Pointer 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().- Parameters:
list
- a pointer to a #GList, this must point to the top of the already sorted listdata
- the data for the new elementfunc
- 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- Returns:
- the (possibly changed) start of the #GList
-
last
Gets the last element in a #GList.- Parameters:
list
- any #GList element- Returns:
- the last element in the #GList, or %NULL if the #GList has no elements
-
length
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.- Parameters:
list
- a #GList, this must point to the top of the list- Returns:
- the number of elements in the #GList
-
nth
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.- Parameters:
list
- a #GList, this must point to the top of the listn
- the position of the element, counting from 0- Returns:
- the element, or %NULL if the position is off the end of the #GList
-
nthData
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.- Parameters:
list
- a #GList, this must point to the top of the listn
- the position of the element- Returns:
- the element's data, or %NULL if the position is off the end of the #GList
-
nthPrev
Gets the element @n places before @list.- Parameters:
list
- a #GListn
- the position of the element, counting from 0- Returns:
- the element, or %NULL if the position is off the end of the #GList
-
position
Gets the position of the given element
in the #GList (starting from 0).- Parameters:
list
- a #GList, this must point to the top of the listllink
- an element in the #GList- Returns:
- the position of the element in the #GList, or -1 if the element is not found
-
prepend
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.
<!-- language="C" --> // Notice that it is initialized to the empty list. GList *list = NULL; list = g_list_prepend (list, "last"); list = g_list_prepend (list, "first");
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.- Parameters:
list
- a pointer to a #GList, this must point to the top of the listdata
- the data for the new element- Returns:
- a pointer to the newly prepended element, which is the new start of the #GList
-
remove
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.- Parameters:
list
- a #GList, this must point to the top of the listdata
- the data of the element to remove- Returns:
- the (possibly changed) start of the #GList
-
removeAll
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.- Parameters:
list
- a #GList, this must point to the top of the listdata
- data to remove- Returns:
- the (possibly changed) start of the #GList
-
removeLink
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:<!-- language="C" --> list = g_list_remove_link (list, llink); free_some_data_that_may_access_the_list_again (llink->data); g_list_free (llink);
- Parameters:
list
- a #GList, this must point to the top of the listllink
- an element in the #GList- Returns:
- the (possibly changed) start of the #GList
-
reverse
Reverses a #GList.
It simply switches the next and prev pointers of each element.- Parameters:
list
- a #GList, this must point to the top of the list- Returns:
- the start of the reversed #GList
-
sort
Sorts a #GList using the given comparison function. The algorithm
used is a stable sort.- Parameters:
list
- a #GList, this must point to the top of the listcompare_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.- Returns:
- the (possibly changed) start of the #GList
-
sortWithData
public static List sortWithData(@Nonnull List list, List.OnCompareDataFunc compare_func, @Nullable Pointer user_data) Like g_list_sort(), but the comparison function accepts
a user data argument.- Parameters:
list
- a #GList, this must point to the top of the listcompare_func
- comparison functionuser_data
- user data to pass to comparison function- Returns:
- the (possibly changed) start of the #GList
-