Class PtrArray

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

  • Constructor Details

    • PtrArray

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

    • PtrArray

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

    • PtrArray

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

    • PtrArray

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

    • PtrArray

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

  • Method Details

    • getType

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

    • getMemoryLayout

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

    • readPdata

      public MemorySegment readPdata()
      Read the value of the field pdata.
      Returns:
      The value of the field pdata

    • writePdata

      public void writePdata(MemorySegment pdata)
      Write a value in the field pdata.
      Parameters:
      pdata - The new value for the field pdata

    • 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

    • add

      public static void add(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data)
      Adds a pointer to the end of the pointer array. The array will grow in size automatically if necessary.
      Parameters:
      array - a pointer array
      data - the pointer to add

    • copy

      public static MemorySegment[] copy(@Nullable MemorySegment @Nullable [] array, @Nullable CopyFunc func)

      Makes a full (deep) copy of a GPtrArray.

      func, as a GLib.CopyFunc, takes two arguments, the data to be copied and a userData pointer. On common processor architectures, it’s safe to pass NULL as userData 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.

      If func is NULL, then only the pointers (and not what they are pointing to) are copied to the new GPtrArray.

      The copy of array will have the same GLib.DestroyNotify for its elements as array. The copy will also be NULL terminated if (and only if) the source array is.

      Parameters:
      array - a pointer array to duplicate
      func - a copy function used to copy every element in the array
      Returns:
      The deep copy of the initial GPtrArray
      Since:
      2.62

    • extend

      public static void extend(@Nullable MemorySegment @Nullable [] arrayToExtend, @Nullable MemorySegment @Nullable [] array, @Nullable CopyFunc func)

      Adds all pointers of array to the end of the array arrayToExtend. The array will grow in size automatically if needed. arrayToExtend is modified in-place.

      func, as a GLib.CopyFunc, takes two arguments, the data to be copied and a userData pointer. On common processor architectures, it’s safe to pass NULL as userData 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.

      If func is NULL, then only the pointers (and not what they are pointing to) are copied to the new GPtrArray.

      Whether arrayToExtend is NULL terminated stays unchanged by this function.

      Parameters:
      arrayToExtend - a pointer array
      array - a pointer array to add to the end of arrayToExtend
      func - a copy function used to copy every element in the array
      Since:
      2.62

    • extendAndSteal

      public static void extendAndSteal(@Nullable MemorySegment @Nullable [] arrayToExtend, @Nullable MemorySegment @Nullable [] array)

      Adds all the pointers in array to the end of arrayToExtend, transferring ownership of each element from array to arrayToExtend and modifying arrayToExtend in-place. array is then freed.

      As with free(MemorySegment[], boolean), array will be destroyed if its reference count is 1. If its reference count is higher, it will be decremented and the length of array set to zero.

      Parameters:
      arrayToExtend - a pointer array
      array - a pointer array to add to the end of arrayToExtend
      Since:
      2.62

    • find

      public static boolean find(@Nullable MemorySegment @Nullable [] haystack, @Nullable MemorySegment needle, @Nullable Out<Integer> index)

      Checks whether needle exists in haystack. If the element is found, true is returned and the element’s index is returned in index (if non-NULL). Otherwise, false is returned and index is undefined. If needle exists multiple times in haystack, the index of the first instance is returned.

      This does pointer comparisons only. If you want to use more complex equality checks, such as string comparisons, use findWithEqualFunc(MemorySegment[], MemorySegment, EqualFunc, Out).

      Parameters:
      haystack - the pointer array to be searched
      needle - the pointer to look for
      index - the return location for the index of the element, if found
      Returns:
      true if needle is one of the elements of haystack; false otherwise
      Since:
      2.54

    • findWithEqualFunc

      public static boolean findWithEqualFunc(@Nullable MemorySegment @Nullable [] haystack, @Nullable MemorySegment needle, @Nullable EqualFunc equalFunc, @Nullable Out<Integer> index)

      Checks whether needle exists in haystack, using the given equalFunc. If the element is found, true is returned and the element’s index is returned in index (if non-NULL). Otherwise, false is returned and index is undefined. If needle exists multiple times in haystack, the index of the first instance is returned.

      equalFunc is called with the element from the array as its first parameter, and needle as its second parameter. If equalFunc is NULL, pointer equality is used.

      Parameters:
      haystack - the pointer array to be searched
      needle - the pointer to look for
      equalFunc - the function to call for each element, which should return true when the desired element is found; or NULL to use pointer equality
      index - the return location for the index of the element, if found
      Returns:
      true if needle is one of the elements of haystack; false otherwise
      Since:
      2.54

    • foreach

      public static void foreach(@Nullable MemorySegment @Nullable [] array, @Nullable Func func)
      Calls a function for each element of a GPtrArray. func must not add elements to or remove elements from the array.
      Parameters:
      array - a pointer array
      func - the function to call for each array element
      Since:
      2.4

    • free

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

      Frees the memory allocated for the GPtrArray. If freeSegment is true it frees the memory block holding the elements as well. Pass false if you want to free the GPtrArray wrapper but preserve the underlying array for use elsewhere. If the reference count of array is greater than one, the GPtrArray 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 GLib.DestroyNotify function has been set for array.

      Note that if the array is NULL terminated and freeSegment is false then this will always return an allocated NULL terminated buffer. If pdata is previously NULL, a new buffer will be allocated.

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

      Parameters:
      array - a pointer array
      freeSegment - if true, the actual pointer array is freed as well
      Returns:
      The allocated pointer array if freeSegment is false, otherwise NULL.

    • insert

      public static void insert(@Nullable MemorySegment @Nullable [] array, int index, @Nullable MemorySegment data)
      Inserts an element into the pointer array at the given index. The array will grow in size automatically if necessary.
      Parameters:
      array - a pointer array
      index - the index to place the new element at, or -1 to append
      data - the pointer to add
      Since:
      2.40

    • isNullTerminated

      public static boolean isNullTerminated(@Nullable MemorySegment @Nullable [] array)

      Checks whether the array was constructed as NULL-terminated.

      This will only return true for arrays constructed by passing true to the null_terminated argument of newNullTerminated(int, boolean). It will not return true for normal arrays which have had a NULL element appended to them.

      Parameters:
      array - a pointer array
      Returns:
      true if the array is made to be NULL terminated; false otherwise
      Since:
      2.74

    • new_

      public static MemorySegment[] new_()
      Creates a new GPtrArray with a reference count of 1.
      Returns:
      The new GPtrArray

    • newFromArray

      public static MemorySegment[] newFromArray(@Nullable MemorySegment @Nullable [] data, @Nullable CopyFunc copyFunc)

      Creates a new GPtrArray, copying len pointers from data, and setting the array’s reference count to 1.

      This avoids having to manually add each element one by one.

      If copyFunc is provided, then it is used to copy each element before adding them to the new array. If it is NULL then the pointers are copied directly.

      It also sets elementFreeFunc for freeing each element when the array is destroyed either via unref(MemorySegment[]), when free(MemorySegment[], boolean) is called with freeSegment set to true or when removing elements.

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

      Parameters:
      data - an array of pointers
      copyFunc - a copy function used to copy every element in the array
      Returns:
      The new GPtrArray
      Since:
      2.76

    • newFromNullTerminatedArray

      public static MemorySegment[] newFromNullTerminatedArray(@Nullable MemorySegment @Nullable [] data, @Nullable CopyFunc copyFunc)

      Creates a new GPtrArray copying the pointers from data after having computed the length of it and with a reference count of 1. This avoids having to manually add each element one by one. If copyFunc is provided, then it is used to copy the data in the new array. It also sets elementFreeFunc for freeing each element when the array is destroyed either via unref(MemorySegment[]), when free(MemorySegment[], boolean) is called with freeSegment set to true or when removing elements.

      Do not use it if the data has more than G_MAXUINT elements. GPtrArray stores the length of its data in guint, which may be shorter than gsize.

      Parameters:
      data - an array of pointers, NULL terminated
      copyFunc - a copy function used to copy every element in the array
      Returns:
      The new GPtrArray
      Since:
      2.76

    • newFull

      public static MemorySegment[] newFull(int reservedSize)
      Creates a new GPtrArray with reservedSize pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0. It also sets elementFreeFunc for freeing each element when the array is destroyed either via unref(MemorySegment[]), when free(MemorySegment[], boolean) is called with freeSegment set to true or when removing elements.
      Parameters:
      reservedSize - the number of pointers preallocated
      Returns:
      The new GPtrArray
      Since:
      2.30

    • newNullTerminated

      public static MemorySegment[] newNullTerminated(int reservedSize, boolean nullTerminated)

      Like newFull(int) but also allows to set the array to be NULL terminated. A NULL terminated pointer array has an additional NULL pointer after the last element, beyond the current length.

      GPtrArray created by other constructors are not automatically NULL terminated.

      Note that if the array’s length is zero and currently no data array is allocated, then pdata will still be NULL. GPtrArray will only NULL terminate pdata, if an actual array is allocated. It does not guarantee that an array is always allocated. In other words, if the length is zero, then pdata may either point to a NULL terminated array of length zero or be NULL.

      Parameters:
      reservedSize - the number of pointers preallocated. If nullTerminated is TRUE, the actually allocated buffer size is reservedSize plus 1, unless reservedSize is zero, in which case no initial buffer gets allocated.
      nullTerminated - if true, make the array NULL terminated
      Returns:
      The new GPtrArray
      Since:
      2.74

    • newTake

      public static MemorySegment[] newTake(@Nullable MemorySegment @Nullable [] data)

      Creates a new GPtrArray with data as pointers, len as length and a reference count of 1.

      This avoids having to copy such data manually. After this call, data belongs to the GPtrArray 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).

      It also sets elementFreeFunc for freeing each element when the array is destroyed either via unref(MemorySegment[]), when free(MemorySegment[], boolean) is called with freeSegment set to true or when removing elements.

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

      Parameters:
      data - an array of pointers
      Returns:
      The new GPtrArray
      Since:
      2.76

    • newTakeNullTerminated

      public static MemorySegment[] newTakeNullTerminated(@Nullable MemorySegment @Nullable [] data)

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

      This avoids having to copy such data manually. After this call, data belongs to the GPtrArray 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.

      It also sets elementFreeFunc for freeing each element when the array is destroyed either via unref(MemorySegment[]), when free(MemorySegment[], boolean) is called with freeSegment set to true or when removing elements.

      Do not use it if the data length is greater than G_MAXUINT. GPtrArray stores the length of its data in guint, which may be shorter than gsize.

      Parameters:
      data - an array of pointers, NULL terminated
      Returns:
      The new GPtrArray
      Since:
      2.76

    • newWithFreeFunc

      public static MemorySegment[] newWithFreeFunc()
      Creates a new GPtrArray with a reference count of 1 and use elementFreeFunc for freeing each element when the array is destroyed either via unref(MemorySegment[]), when free(MemorySegment[], boolean) is called with freeSegment set to true or when removing elements.
      Returns:
      The new GPtrArray
      Since:
      2.22

    • 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 - a pointer array
      Returns:
      The passed in GPtrArray
      Since:
      2.22

    • remove

      public static boolean remove(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data)

      Removes the first occurrence of the given pointer from the pointer array. The following elements are moved down one place. If array has a non-NULL GLib.DestroyNotify function it is called for the removed element.

      It returns true if the pointer was removed, or false if the pointer was not found.

      Parameters:
      array - a pointer array
      data - the pointer to remove
      Returns:
      true if the pointer is found and removed; false otherwise

    • removeFast

      public static boolean removeFast(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data)

      Removes the first occurrence of the given pointer from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than remove(MemorySegment[], MemorySegment). If array has a non-NULL GLib.DestroyNotify function it is called for the removed element.

      It returns true if the pointer was removed, or false if the pointer was not found.

      Parameters:
      array - a pointer array
      data - the pointer to remove
      Returns:
      true if the pointer is found and removed; false otherwise

    • removeIndex

      public static @Nullable MemorySegment removeIndex(@Nullable MemorySegment @Nullable [] array, int index)
      Removes the pointer at the given index from the pointer array. The following elements are moved down one place. If array has a non-NULL GLib.DestroyNotify function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the GLib.DestroyNotify implementation).
      Parameters:
      array - a pointer array
      index - the index of the pointer to remove
      Returns:
      The pointer which was removed

    • removeIndexFast

      public static @Nullable MemorySegment removeIndexFast(@Nullable MemorySegment @Nullable [] array, int index)
      Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than removeIndex(MemorySegment[], int). If array has a non-NULL GLib.DestroyNotify function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the GLib.DestroyNotify implementation).
      Parameters:
      array - a pointer array
      index - the index of the pointer to remove
      Returns:
      The pointer which was removed

    • removeRange

      public static MemorySegment[] removeRange(@Nullable MemorySegment @Nullable [] array, int index, int length)
      Removes the given number of pointers starting at the given index from a GPtrArray. The following elements are moved to close the gap. If array has a non-NULL GLib.DestroyNotify function it is called for the removed elements.
      Parameters:
      array - a pointer array
      index - the index of the first pointer to remove
      length - the number of pointers to remove
      Returns:
      The array
      Since:
      2.4

    • setFreeFunc

      public static void setFreeFunc(@Nullable MemorySegment @Nullable [] array)
      Sets a function for freeing each element when array is destroyed either via unref(MemorySegment[]), when free(MemorySegment[], boolean) is called with freeSegment set to true or when removing elements.
      Parameters:
      array - a pointer array
      Since:
      2.22

    • setSize

      public static void setSize(@Nullable MemorySegment @Nullable [] array, int length)
      Sets the size of the array. When making the array larger, newly-added elements will be set to NULL. When making it smaller, if array has a non-NULL GLib.DestroyNotify function then it will be called for the removed elements.
      Parameters:
      array - a pointer array
      length - the new length of the pointer array

    • sizedNew

      public static MemorySegment[] sizedNew(int reservedSize)
      Creates a new GPtrArray with reservedSize pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0.
      Parameters:
      reservedSize - the number of pointers preallocated
      Returns:
      The new GPtrArray

    • sort

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

      Sorts the array, 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 than zero if first arg is greater than second arg).

      Note that the comparison function for sort(MemorySegment[], CompareFunc) doesn’t take the pointers from the array as arguments, it takes pointers to the pointers in the array.

      Use sortValues(MemorySegment[], CompareFunc) if you want to use normal GLib.CompareFunc instances, otherwise here is a full example of use:

      typedef struct
{
  gchar *name;
  gint size;
} FileListEntry;

static gint
sort_filelist (gconstpointer a, gconstpointer b)
{
  const FileListEntry *entry1 = *((FileListEntry **) a);
  const FileListEntry *entry2 = *((FileListEntry **) b);

  return g_ascii_strcasecmp (entry1->name, entry2->name);
}

…
g_autoptr (GPtrArray) file_list = NULL;

// initialize file_list array and load with many FileListEntry entries
...
// now sort it with
g_ptr_array_sort (file_list, sort_filelist);

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

      Parameters:
      array - a pointer array
      compareFunc - a comparison function

    • sortValues

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

      Sorts the array, 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 than zero if first arg is greater than second arg).

      This is guaranteed to be a stable sort.

      Parameters:
      array - a pointer array
      compareFunc - a comparison function
      Since:
      2.76

    • sortValuesWithData

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

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

      This is guaranteed to be a stable sort.

      Parameters:
      array - a pointer array
      compareFunc - a comparison function
      Since:
      2.76

    • sortWithData

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

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

      Note that the comparison function for sortWithData(MemorySegment[], CompareDataFunc) doesn’t take the pointers from the array as arguments, it takes pointers to the pointers in the array.

      Use sortValuesWithData(MemorySegment[], CompareDataFunc) if you want to use normal GLib.CompareDataFunc instances, otherwise here is a full example of use:

      typedef enum { SORT_NAME, SORT_SIZE } SortMode;

typedef struct
{
  gchar *name;
  gint size;
} FileListEntry;

static gint
sort_filelist (gconstpointer a, gconstpointer b, gpointer user_data)
{
  gint order;
  const SortMode sort_mode = GPOINTER_TO_INT (user_data);
  const FileListEntry *entry1 = *((FileListEntry **) a);
  const FileListEntry *entry2 = *((FileListEntry **) b);

  switch (sort_mode)
    {
    case SORT_NAME:
      order = g_ascii_strcasecmp (entry1->name, entry2->name);
      break;
    case SORT_SIZE:
      order = entry1->size - entry2->size;
      break;
    default:
      order = 0;
      break;
    }
  return order;
}

...
g_autoptr (GPtrArray) file_list = NULL;
SortMode sort_mode;

// initialize file_list array and load with many FileListEntry entries
...
// now sort it with
sort_mode = SORT_NAME;
g_ptr_array_sort_with_data (file_list,
                            sort_filelist,
                            GINT_TO_POINTER (sort_mode));

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

      Parameters:
      array - a pointer array
      compareFunc - a comparison function

    • steal

      public static @Nullable MemorySegment @Nullable [] steal(@Nullable MemorySegment @Nullable [] array)

      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 is NULL terminated this may still return NULL if the length of the array was zero and pdata was not yet allocated.

      Even if set, the GLib.DestroyNotify function will never be called on the current contents of the array and the caller is responsible for freeing the array elements.

      An example of use:

      g_autoptr(GPtrArray) chunk_buffer = g_ptr_array_new_with_free_func (g_bytes_unref);

// Some part of your application appends a number of chunks to the pointer array.
g_ptr_array_add (chunk_buffer, g_bytes_new_static ("hello", 5));
g_ptr_array_add (chunk_buffer, g_bytes_new_static ("world", 5));

…

// Periodically, the chunks need to be sent as an array-and-length to some
// other part of the program.
GBytes **chunks;
gsize n_chunks;

chunks = g_ptr_array_steal (chunk_buffer, &n_chunks);
for (gsize i = 0; i < n_chunks; i++)
  {
    // Do something with each chunk here, and then free them, since
    // g_ptr_array_steal() transfers ownership of all the elements and the
    // array to the caller.
    …

    g_bytes_unref (chunks[i]);
  }

g_free (chunks);

// After calling g_ptr_array_steal(), the pointer array can be reused for the
// next set of chunks.
g_assert (chunk_buffer->len == 0);
      Parameters:
      array - a pointer array
      Returns:
      The allocated element data. This may be NULLif the array doesn’t have any elements (i.e. if *len is zero).
      Since:
      2.64

    • stealIndex

      public static @Nullable MemorySegment stealIndex(@Nullable MemorySegment @Nullable [] array, int index)
      Removes the pointer at the given index from the pointer array. The following elements are moved down one place. The GLib.DestroyNotify for array is not called on the removed element; ownership is transferred to the caller of this function.
      Parameters:
      array - a pointer array
      index - the index of the pointer to steal
      Returns:
      The pointer which was removed
      Since:
      2.58

    • stealIndexFast

      public static @Nullable MemorySegment stealIndexFast(@Nullable MemorySegment @Nullable [] array, int index)
      Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than stealIndex(MemorySegment[], int). The GLib.DestroyNotify for array is not called on the removed element; ownership is transferred to the caller of this function.
      Parameters:
      array - a pointer array
      index - the index of the pointer to steal
      Returns:
      The pointer which was removed
      Since:
      2.58

    • 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 - a pointer array
      Since:
      2.22