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
public class List extends Record
The #GList struct is used for each element in a doubly-linked list.

https://docs.gtk.org/glib/struct.List.html

  • Field Details

    • DATA

      public static final String 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

      public static final String NEXT
      contains the link to the next element in the list
      See Also:

    • PREV

      public static final String PREV
      contains the link to the previous element in the list
      See Also:

  • Constructor Details

  • Method Details

    • getClassHandler

      public static ClassHandler getClassHandler()

    • setFieldData

      public 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]

    • getFieldData

      public Pointer 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

      public void setFieldNext(List next)
      contains the link to the next element in the list

    • getFieldNext

      public List getFieldNext()
      contains the link to the next element in the list

    • setFieldPrev

      public void setFieldPrev(List prev)
      contains the link to the previous element in the list

    • getFieldPrev

      public List getFieldPrev()
      contains the link to the previous element in the list

    • alloc

      public static 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

      public static List append(@Nonnull List list, @Nullable Pointer 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. 
      <!-- 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 #GList
      data - the data for the new element
      Returns:
      either @list or the new start of the #GList if @list was %NULL

    • concat

      public static List concat(@Nonnull List list1, @Nonnull List 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: 
      <!-- 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 list
      list2 - 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

      public static List copy(@Nonnull List 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.
      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

      public static List copyDeep(@Nonnull List list, List.OnCopyFunc func, @Nullable Pointer 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: 
      <!-- 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 list
      func - a copy function used to copy every element in the list
      user_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

      public static List deleteLink(@Nonnull List list, @Nonnull List 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.
      Parameters:
      list - a #GList, this must point to the top of the list
      link_ - node to delete from @list
      Returns:
      the (possibly changed) start of the #GList

    • find

      public static List find(@Nonnull List list, @Nullable Pointer data)
      Finds the element in a #GList which contains the given data.
      Parameters:
      list - a #GList, this must point to the top of the list
      data - the element data to find
      Returns:
      the found #GList element, or %NULL if it is not found

    • findCustom

      public static List findCustom(@Nonnull List list, @Nullable Pointer data, List.OnCompareFunc 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.
      Parameters:
      list - a #GList, this must point to the top of the list
      data - user data passed to the function
      func - 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

      public static List first(@Nonnull List list)
      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

      public static void foreach(@Nonnull List list, List.OnFunc func, @Nullable Pointer 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.
      Parameters:
      list - a #GList, this must point to the top of the list
      func - the function to call with each element's data
      user_data - user data to pass to the function

    • free

      public static void free(@Nonnull List 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: 
      <!-- 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

      public static void free1(@Nonnull List 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().
      Parameters:
      list - a #GList element

    • freeFull

      public static void freeFull(@Nonnull 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.

      @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 #GList
      free_func - the function to be called to free each element's data

    • index

      public static int index(@Nonnull List list, @Nullable Pointer data)
      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 list
      data - the data to find
      Returns:
      the index of the element containing the data, or -1 if the data is not found

    • insert

      public static List insert(@Nonnull List list, @Nullable Pointer data, int position)
      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 list
      data - 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.
      Returns:
      the (possibly changed) start of the #GList

    • insertBefore

      public static List insertBefore(@Nonnull List list, @Nonnull List sibling, @Nullable Pointer data)
      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 list
      sibling - 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
      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 list
      sibling - the list element before which the new element is inserted or %NULL to insert at the end of the list
      link_ - 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 list
      data - 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.
      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 list
      data - 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.
      user_data - user data to pass to comparison function
      Returns:
      the (possibly changed) start of the #GList

    • last

      public static List last(@Nonnull List list)
      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

      public static int length(@Nonnull List 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.
      Parameters:
      list - a #GList, this must point to the top of the list
      Returns:
      the number of elements in the #GList

    • nth

      public static List nth(@Nonnull List list, int 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.
      Parameters:
      list - a #GList, this must point to the top of the list
      n - the position of the element, counting from 0
      Returns:
      the element, or %NULL if the position is off the end of the #GList

    • nthData

      public static Pointer nthData(@Nonnull List list, int 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.
      Parameters:
      list - a #GList, this must point to the top of the list
      n - the position of the element
      Returns:
      the element's data, or %NULL if the position is off the end of the #GList

    • nthPrev

      public static List nthPrev(@Nonnull List list, int n)
      Gets the element @n places before @list.
      Parameters:
      list - a #GList
      n - the position of the element, counting from 0
      Returns:
      the element, or %NULL if the position is off the end of the #GList

    • position

      public static int position(@Nonnull List list, @Nonnull List llink)
      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 list
      llink - an element in the #GList
      Returns:
      the position of the element in the #GList, or -1 if the element is not found

    • prepend

      public static List prepend(@Nonnull List list, @Nullable Pointer 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. 
      <!-- 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 list
      data - the data for the new element
      Returns:
      a pointer to the newly prepended element, which is the new start of the #GList

    • remove

      public static List remove(@Nonnull List list, @Nullable Pointer 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.
      Parameters:
      list - a #GList, this must point to the top of the list
      data - the data of the element to remove
      Returns:
      the (possibly changed) start of the #GList

    • removeAll

      public static List removeAll(@Nonnull List list, @Nullable Pointer 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.
      Parameters:
      list - a #GList, this must point to the top of the list
      data - data to remove
      Returns:
      the (possibly changed) start of the #GList

    • removeLink

      public static List removeLink(@Nonnull List list, @Nonnull List 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: 
      <!-- 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 list
      llink - an element in the #GList
      Returns:
      the (possibly changed) start of the #GList

    • reverse

      public static List reverse(@Nonnull List list)
      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

      public static List sort(@Nonnull List list, List.OnCompareFunc compare_func)
      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 list
      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.
      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 list
      compare_func - comparison function
      user_data - user data to pass to comparison function
      Returns:
      the (possibly changed) start of the #GList