Package ch.bailu.gtk.glib

Class SList

java.lang.Object
ch.bailu.gtk.type.Type
ch.bailu.gtk.type.Pointer
ch.bailu.gtk.type.Record
ch.bailu.gtk.glib.SList
All Implemented Interfaces:
PointerInterface
public class SList extends Record
The #GSList struct is used for each element in the singly-linked
list.

https://docs.gtk.org/glib/struct.SList.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:

  • 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(SList next)
      contains the link to the next element in the list.

    • getFieldNext

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

    • alloc

      public static SList alloc()
      Allocates space for one #GSList element. It is called by the
      g_slist_append(), g_slist_prepend(), g_slist_insert() and
      g_slist_insert_sorted() functions and so is rarely used on its own.
      Returns:
      a pointer to the newly-allocated #GSList element.

    • append

      public static SList append(@Nonnull SList list, @Nullable Pointer data)
      Adds a new element on to the end of the list.

      The return value is the new start of the list, which may
      have changed, so make sure you store the new value.

      Note that g_slist_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 prepend
      the elements and reverse the list when all elements have been added. 
      <!-- language="C" -->
 // Notice that these are initialized to the empty list.
 GSList *list = NULL, *number_list = NULL;
 
 // This is a list of strings.
 list = g_slist_append (list, "first");
 list = g_slist_append (list, "second");
 
 // This is a list of integers.
 number_list = g_slist_append (number_list, GINT_TO_POINTER (27));
 number_list = g_slist_append (number_list, GINT_TO_POINTER (14));
      Parameters:
      list - a #GSList
      data - the data for the new element
      Returns:
      the new start of the #GSList

    • concat

      public static SList concat(@Nonnull SList list1, @Nonnull SList list2)
      Adds the second #GSList onto the end of the first #GSList.
      Note that the elements of the second #GSList are not copied.
      They are used directly.
      Parameters:
      list1 - a #GSList
      list2 - the #GSList to add to the end of the first #GSList
      Returns:
      the start of the new #GSList

    • copy

      public static SList copy(@Nonnull SList list)
      Copies a #GSList.

      Note that this is a "shallow" copy. If the list elements
      consist of pointers to data, the pointers are copied but
      the actual data isn't. See g_slist_copy_deep() if you need
      to copy the data as well.
      Parameters:
      list - a #GSList
      Returns:
      a copy of @list

    • copyDeep

      public static SList copyDeep(@Nonnull SList list, SList.OnCopyFunc func, @Nullable Pointer user_data)
      Makes a full (deep) copy of a #GSList.

      In contrast with g_slist_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_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL);


      And, to entirely free the new list, you could do: 
      <!-- language="C" -->
 g_slist_free_full (another_list, g_object_unref);
      Parameters:
      list - a #GSList
      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:
      a full copy of @list, use g_slist_free_full() to free it

    • deleteLink

      public static SList deleteLink(@Nonnull SList list, @Nonnull SList link_)
      Removes the node link_ from the list and frees it.
      Compare this to g_slist_remove_link() which removes the node
      without freeing it.

      Removing arbitrary nodes from a singly-linked list requires time
      that is proportional to the length of the list (ie. O(n)). If you
      find yourself using g_slist_delete_link() frequently, you should
      consider a different data structure, such as the doubly-linked
      #GList.
      Parameters:
      list - a #GSList
      link_ - node to delete
      Returns:
      the new head of @list

    • find

      public static SList find(@Nonnull SList list, @Nullable Pointer data)
      Finds the element in a #GSList which
      contains the given data.
      Parameters:
      list - a #GSList
      data - the element data to find
      Returns:
      the found #GSList element, or %NULL if it is not found

    • findCustom

      public static SList findCustom(@Nonnull SList list, @Nullable Pointer data, SList.OnCompareFunc func)
      Finds an element in a #GSList, 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 #GSList element's data as the first argument and the
      given user data.
      Parameters:
      list - a #GSList
      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 #GSList element, or %NULL if it is not found

    • foreach

      public static void foreach(@Nonnull SList list, SList.OnFunc func, @Nullable Pointer user_data)
      Calls a function for each element of a #GSList.

      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 #GSList
      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 SList list)
      Frees all of the memory used by a #GSList.
      The freed elements are returned to the slice allocator.

      If list elements contain dynamically-allocated memory,
      you should either use g_slist_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" -->
 GSList *list_of_borrowed_things = …;  /<!-- -->* (transfer container) *<!-- -->/
 g_slist_free (g_steal_pointer (&list_of_borrowed_things));
      Parameters:
      list - the first link of a #GSList

    • free1

      public static void free1(@Nonnull SList list)
      Frees one #GSList element.
      It is usually used after g_slist_remove_link().
      Parameters:
      list - a #GSList element

    • freeFull

      public static void freeFull(@Nonnull SList list, SList.OnDestroyNotify free_func)
      Convenience method, which frees all the memory used by a #GSList, and
      calls the specified destroy function 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" -->
 GSList *list_of_owned_things = …;  /<!-- -->* (transfer full) (element-type GObject) *<!-- -->/
 g_slist_free_full (g_steal_pointer (&list_of_owned_things), g_object_unref);
      Parameters:
      list - the first link of a #GSList
      free_func - the function to be called to free each element's data

    • index

      public static int index(@Nonnull SList list, @Nullable Pointer data)
      Gets the position of the element containing
      the given data (starting from 0).
      Parameters:
      list - a #GSList
      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 SList insert(@Nonnull SList list, @Nullable Pointer data, int position)
      Inserts a new element into the list at the given position.
      Parameters:
      list - a #GSList
      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 new start of the #GSList

    • insertBefore

      public static SList insertBefore(@Nonnull SList slist, @Nonnull SList sibling, @Nullable Pointer data)
      Inserts a node before @sibling containing @data.
      Parameters:
      slist - a #GSList
      sibling - node to insert @data before
      data - data to put in the newly-inserted node
      Returns:
      the new head of the list.

    • insertSorted

      public static SList insertSorted(@Nonnull SList list, @Nullable Pointer data, SList.OnCompareFunc func)
      Inserts a new element into the list, using the given
      comparison function to determine its position.
      Parameters:
      list - a #GSList
      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 new start of the #GSList

    • insertSortedWithData

      public static SList insertSortedWithData(@Nonnull SList list, @Nullable Pointer data, SList.OnCompareDataFunc func, @Nullable Pointer user_data)
      Inserts a new element into the list, using the given
      comparison function to determine its position.
      Parameters:
      list - a #GSList
      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 - data to pass to comparison function
      Returns:
      the new start of the #GSList

    • last

      public static SList last(@Nonnull SList list)
      Gets the last element in a #GSList.

      This function iterates over the whole list.
      Parameters:
      list - a #GSList
      Returns:
      the last element in the #GSList, or %NULL if the #GSList has no elements

    • length

      public static int length(@Nonnull SList list)
      Gets the number of elements in a #GSList.

      This function iterates over the whole list to
      count its elements. To check whether the list is non-empty, it is faster to
      check @list against %NULL.
      Parameters:
      list - a #GSList
      Returns:
      the number of elements in the #GSList

    • nth

      public static SList nth(@Nonnull SList list, int n)
      Gets the element at the given position in a #GSList.
      Parameters:
      list - a #GSList
      n - the position of the element, counting from 0
      Returns:
      the element, or %NULL if the position is off the end of the #GSList

    • nthData

      public static Pointer nthData(@Nonnull SList list, int n)
      Gets the data of the element at the given position.
      Parameters:
      list - a #GSList
      n - the position of the element
      Returns:
      the element's data, or %NULL if the position is off the end of the #GSList

    • position

      public static int position(@Nonnull SList list, @Nonnull SList llink)
      Gets the position of the given element
      in the #GSList (starting from 0).
      Parameters:
      list - a #GSList
      llink - an element in the #GSList
      Returns:
      the position of the element in the #GSList, or -1 if the element is not found

    • prepend

      public static SList prepend(@Nonnull SList list, @Nullable Pointer data)
      Adds a new element on to the start of the list.

      The return value is the new start of the list, which
      may have changed, so make sure you store the new value. 
      <!-- language="C" -->
 // Notice that it is initialized to the empty list.
 GSList *list = NULL;
 list = g_slist_prepend (list, "last");
 list = g_slist_prepend (list, "first");
      Parameters:
      list - a #GSList
      data - the data for the new element
      Returns:
      the new start of the #GSList

    • remove

      public static SList remove(@Nonnull SList list, @Nullable Pointer data)
      Removes an element from a #GSList.
      If two elements contain the same data, only the first is removed.
      If none of the elements contain the data, the #GSList is unchanged.
      Parameters:
      list - a #GSList
      data - the data of the element to remove
      Returns:
      the new start of the #GSList

    • removeAll

      public static SList removeAll(@Nonnull SList list, @Nullable Pointer data)
      Removes all list nodes with data equal to @data.
      Returns the new head of the list. Contrast with
      g_slist_remove() which removes only the first node
      matching the given data.
      Parameters:
      list - a #GSList
      data - data to remove
      Returns:
      new head of @list

    • removeLink

      public static SList removeLink(@Nonnull SList list, @Nonnull SList link_)
      Removes an element from a #GSList, without
      freeing the element. The removed element's next
      link is set to %NULL, so that it becomes a
      self-contained list with one element.

      Removing arbitrary nodes from a singly-linked list
      requires time that is proportional to the length of the list
      (ie. O(n)). If you find yourself using g_slist_remove_link()
      frequently, you should consider a different data structure,
      such as the doubly-linked #GList.
      Parameters:
      list - a #GSList
      link_ - an element in the #GSList
      Returns:
      the new start of the #GSList, without the element

    • reverse

      public static SList reverse(@Nonnull SList list)
      Reverses a #GSList.
      Parameters:
      list - a #GSList
      Returns:
      the start of the reversed #GSList

    • sort

      public static SList sort(@Nonnull SList list, SList.OnCompareFunc compare_func)
      Sorts a #GSList using the given comparison function. The algorithm
      used is a stable sort.
      Parameters:
      list - a #GSList
      compare_func - the comparison function used to sort the #GSList. This function is passed the data from 2 elements of the #GSList 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 #GSList

    • sortWithData

      public static SList sortWithData(@Nonnull SList list, SList.OnCompareDataFunc compare_func, @Nullable Pointer user_data)
      Like g_slist_sort(), but the sort function accepts a user data argument.
      Parameters:
      list - a #GSList
      compare_func - comparison function
      user_data - data to pass to comparison function
      Returns:
      new head of the list