Class Array

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.glib.Array
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class Array extends ProxyInstance
Contains the public fields of a GArray.

  • Constructor Details

    • Array

      public Array(MemorySegment address)
      Create a Array proxy instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Array

      public Array(Arena arena)
      Allocate a new Array.
      Parameters:
      arena - to control the memory allocation scope

    • Array

      public Array()
      Allocate a new Array. The memory is allocated with Arena.ofAuto().

    • Array

      public Array(String data, int len, Arena arena)
      Allocate a new Array with the fields set to the provided values.
      Parameters:
      data - value for the field data
      len - value for the field len
      arena - to control the memory allocation scope

    • Array

      public Array(String data, int len)
      Allocate a new Array with the fields set to the provided values. The memory is allocated with Arena.ofAuto().
      Parameters:
      data - value for the field data
      len - value for the field len

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Array class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • readData

      public String readData()
      Read the value of the field data.
      Returns:
      The value of the field data

    • writeData

      public void writeData(String data, Arena _arena)
      Write a value in the field data.
      Parameters:
      data - The new value for the field data
      _arena - to control the memory allocation scope

    • readLen

      public int readLen()
      Read the value of the field len.
      Returns:
      The value of the field len

    • writeLen

      public void writeLen(int len)
      Write a value in the field len.
      Parameters:
      len - The new value for the field len

    • appendVals

      public static MemorySegment[] appendVals(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data, int len)

      Adds len elements onto the end of the array.

      data may be NULL if (and only if) len is zero. If len is zero, this function is a no-op.

      Parameters:
      array - an array
      data - a pointer to the elements to append to the end of the array
      len - the number of elements to append
      Returns:
      The GArray

    • binarySearch

      public static boolean binarySearch(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment target, @Nullable CompareFunc compareFunc, @Nullable Out<Integer> outMatchIndex)

      Checks whether target exists in array by performing a binary search based on the given comparison function compareFunc which gets pointers to items as arguments. If the element is found, true is returned and the element’s index is returned in outMatchIndex (if non-NULL). Otherwise, false is returned and outMatchIndex is undefined. This search is using a binary search, so the array must absolutely be sorted to return a correct result (if not, the function may produce false-negative).

      This example defines a comparison function and searches an element in a GArray:

      static gint
cmpint (gconstpointer a, gconstpointer b)
{
  const gint *_a = a;
  const gint *_b = b;

  return *_a - *_b;
}
...
gint i = 424242;
guint matched_index;
gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index);
...
      Parameters:
      array - an array
      target - a pointer to the item to look up
      compareFunc - a comparison function to locate target
      outMatchIndex - the return location for the index of the element, if found
      Returns:
      true if target is one of the elements of array; false otherwise
      Since:
      2.62

    • copy

      public static MemorySegment[] copy(@Nullable MemorySegment @Nullable [] array)
      Creates a shallow copy of a GArray. If the array elements consist of pointers to data, the pointers are copied but the actual data is not.
      Parameters:
      array - an array
      Returns:
      The copy of array
      Since:
      2.62

    • free

      public static String free(@Nullable MemorySegment @Nullable [] array, boolean freeSegment)

      Frees the memory allocated for the GArray. If freeSegment is true it frees the memory block holding the elements as well. Pass false if you want to free the GArray wrapper but preserve the underlying array for use elsewhere. If the reference count of array is greater than one, the GArray wrapper is preserved but the size of array will be set to zero.

      If array contents point to dynamically-allocated memory, they should be freed separately if freeSegment is true and no clearFunc function has been set for array.

      This function is not thread-safe. If using a GArray from multiple threads, use only the atomic ref(MemorySegment[]) and unref(MemorySegment[]) functions.

      Parameters:
      array - an array
      freeSegment - if true, the actual element data is freed as well
      Returns:
      The allocated element data if freeSegment is false, otherwise NULL

    • getElementSize

      public static int getElementSize(@Nullable MemorySegment @Nullable [] array)
      Gets the size of the elements in array.
      Parameters:
      array - an array
      Returns:
      The size of each element, in bytes
      Since:
      2.22

    • insertVals

      public static MemorySegment[] insertVals(@Nullable MemorySegment @Nullable [] array, int index, @Nullable MemorySegment data, int len)

      Inserts len elements into a GArray at the given index.

      If index is greater than the array’s current length, the array is expanded. The elements between the old end of the array and the newly inserted elements will be initialised to zero if the array was configured to clear elements; otherwise their values will be undefined.

      If index is less than the array’s current length, new entries will be inserted into the array, and the existing entries above index will be moved upwards.

      data may be NULL if (and only if) len is zero. If len is zero, this function is a no-op.

      Parameters:
      array - an array
      index - the index to place the elements at
      data - a pointer to the elements to insert
      len - the number of elements to insert
      Returns:
      The GArray

    • new_

      public static MemorySegment[] new_(boolean zeroTerminated, boolean clear, int elementSize)
      Creates a new GArray with a reference count of 1.
      Parameters:
      zeroTerminated - if true, the array should have an extra element at the end which is set to 0
      clear - if true, GArray elements should be automatically cleared to 0 when they are allocated
      elementSize - the size of each element in bytes
      Returns:
      The new GArray

    • newTake

      public static MemorySegment[] newTake(@Nullable MemorySegment @Nullable [] data, boolean clear, long elementSize)

      Creates a new GArray with data as array data, len as length and a reference count of 1.

      This avoids having to copy the data manually, when it can just be inherited. After this call, data belongs to the GArray and may no longer be modified by the caller. The memory of data has to be dynamically allocated and will eventually be freed with GLib.free(MemorySegment).

      In case the elements need to be cleared when the array is freed, use setClearFunc(MemorySegment[]) to set a GLib.DestroyNotify function to perform such task.

      Do not use it if len or elementSize are greater than G_MAXUINT. GArray stores the length of its data in guint, which may be shorter than gsize.

      Parameters:
      data - an array of elements of elementSize
      clear - if true, GArray elements should be automatically cleared to 0 when they are allocated
      elementSize - the size of each element in bytes
      Returns:
      The new GArray
      Since:
      2.76

    • newTakeZeroTerminated

      public static MemorySegment[] newTakeZeroTerminated(@Nullable MemorySegment @Nullable [] data, boolean clear, long elementSize)

      Creates a new GArray with data as array data, computing the length of it and setting the reference count to 1.

      This avoids having to copy the data manually, when it can just be inherited. After this call, data belongs to the GArray and may no longer be modified by the caller. The memory of data has to be dynamically allocated and will eventually be freed with GLib.free(MemorySegment).

      The length is calculated by iterating through data until the first NULL element is found.

      In case the elements need to be cleared when the array is freed, use setClearFunc(MemorySegment[]) to set a GLib.DestroyNotify function to perform such task.

      Do not use it if data length or elementSize are greater than G_MAXUINT. GArray stores the length of its data in guint, which may be shorter than gsize.

      Parameters:
      data - an array of elements of elementSize, NULL terminated
      clear - if true, GArray elements should be automatically cleared to 0 when they are allocated
      elementSize - the size of each element in bytes
      Returns:
      The new GArray
      Since:
      2.76

    • prependVals

      public static MemorySegment[] prependVals(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data, int len)

      Adds len elements onto the start of the array.

      data may be NULL if (and only if) len is zero. If len is zero, this function is a no-op.

      This operation is slower than appendVals(MemorySegment[], MemorySegment, int) since the existing elements in the array have to be moved to make space for the new elements.

      Parameters:
      array - an array
      data - a pointer to the elements to prepend to the start of the array
      len - the number of elements to prepend, which may be zero
      Returns:
      The GArray

    • ref

      public static MemorySegment[] ref(@Nullable MemorySegment @Nullable [] array)
      Atomically increments the reference count of array by one. This function is thread-safe and may be called from any thread.
      Parameters:
      array - an array
      Returns:
      The passed in GArray
      Since:
      2.22

    • removeIndex

      public static MemorySegment[] removeIndex(@Nullable MemorySegment @Nullable [] array, int index)
      Removes the element at the given index from a GArray. The following elements are moved down one place.
      Parameters:
      array - an array
      index - the index of the element to remove
      Returns:
      The GArray

    • removeIndexFast

      public static MemorySegment[] removeIndexFast(@Nullable MemorySegment @Nullable [] array, int index)
      Removes the element at the given index from a GArray. The last element in the array is used to fill in the space, so this function does not preserve the order of the GArray. But it is faster than removeIndex(MemorySegment[], int).
      Parameters:
      array - an array
      index - the index of the element to remove
      Returns:
      The GArray

    • removeRange

      public static MemorySegment[] removeRange(@Nullable MemorySegment @Nullable [] array, int index, int length)
      Removes the given number of elements starting at the given index from a GArray. The following elements are moved to close the gap.
      Parameters:
      array - an array
      index - the index of the first element to remove
      length - the number of elements to remove
      Returns:
      The GArray
      Since:
      2.4

    • setClearFunc

      public static void setClearFunc(@Nullable MemorySegment @Nullable [] array)

      Sets a function to clear an element of array.

      The clearFunc will be called when an element in the array data segment is removed and when the array is freed and data segment is deallocated as well. clearFunc will be passed a pointer to the element to clear, rather than the element itself.

      Note that in contrast with other uses of GLib.DestroyNotify functions, clearFunc is expected to clear the contents of the array element it is given, but not free the element itself.

      typedef struct
{
  gchar *str;
  GObject *obj;
} ArrayElement;

static void
array_element_clear (ArrayElement *element)
{
  g_clear_pointer (&element->str, g_free);
  g_clear_object (&element->obj);
}

// main code
GArray *garray = g_array_new (FALSE, FALSE, sizeof (ArrayElement));
g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear);
// assign data to the structure
g_array_free (garray, TRUE);
      Parameters:
      array - an array
      Since:
      2.32

    • setSize

      public static MemorySegment[] setSize(@Nullable MemorySegment @Nullable [] array, int length)
      Sets the size of the array, expanding it if necessary. If the array was created with clear set to true, the new elements are set to 0.
      Parameters:
      array - an array
      length - the new size of the GArray
      Returns:
      The GArray

    • sizedNew

      public static MemorySegment[] sizedNew(boolean zeroTerminated, boolean clear, int elementSize, int reservedSize)
      Creates a new GArray with reservedSize elements preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many elements to the array. Note however that the size of the array is still 0.
      Parameters:
      zeroTerminated - if true, the array should have an extra element at the end with all bits cleared
      clear - if true, all bits in the array should be cleared to 0 on allocation
      elementSize - the size of each element in the array
      reservedSize - the number of elements preallocated
      Returns:
      The new GArray

    • sort

      public static void sort(@Nullable MemorySegment @Nullable [] array, @Nullable CompareFunc compareFunc)

      Sorts a GArray using compareFunc which should be a qsort()-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater zero if first arg is greater than second arg).

      This is guaranteed to be a stable sort since version 2.32.

      Parameters:
      array - an array
      compareFunc - a comparison function

    • sortWithData

      public static void sortWithData(@Nullable MemorySegment @Nullable [] array, @Nullable CompareDataFunc compareFunc)

      Like sort(MemorySegment[], CompareFunc), but the comparison function receives an extra user data argument.

      This is guaranteed to be a stable sort since version 2.32.

      There used to be a comment here about making the sort stable by using the addresses of the elements in the comparison function. This did not actually work, so any such code should be removed.

      Parameters:
      array - an array
      compareFunc - a comparison function

    • steal

      public static @Nullable MemorySegment steal(@Nullable MemorySegment @Nullable [] array, @Nullable Out<Long> len)

      Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller.

      Note that if the array was created with the zeroTerminate property set to true, this may still return NULL if the length of the array was zero and data was not yet allocated.

      If array elements contain dynamically-allocated memory, the array elements should also be freed by the caller.

      A short example of use:

      ...
gpointer data;
gsize data_len;
data = g_array_steal (some_array, &data_len);
...
      Parameters:
      array - an array
      len - a pointer to retrieve the number of elements of the original array
      Returns:
      The allocated element data
      Since:
      2.64

    • unref

      public static void unref(@Nullable MemorySegment @Nullable [] array)
      Atomically decrements the reference count of array by one. If the reference count drops to 0, the effect is the same as calling free(MemorySegment[], boolean) with freeSegment set to true. This function is thread-safe and may be called from any thread.
      Parameters:
      array - an array
      Since:
      2.22