Package org.gnome.glib

Class PtrArray

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.glib.PtrArray

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class PtrArray
extends ProxyInstance

Contains the public fields of a pointer array.

Constructor Summary

Constructors

Constructor	Description
PtrArray()	Allocate a new PtrArray.
PtrArray(Arena arena)	Allocate a new PtrArray.
PtrArray(MemorySegment address)	Create a PtrArray proxy instance for the provided memory address.
PtrArray(MemorySegment pdata, int len)	Allocate a new PtrArray with the fields set to the provided values.
PtrArray(MemorySegment pdata, int len, Arena arena)	Allocate a new PtrArray with the fields set to the provided values.

Method Summary

Modifier and Type	Method	Description
static void	add(MemorySegment[] array, @Nullable MemorySegment data)	Adds a pointer to the end of the pointer array.
static MemorySegment[]	copy(MemorySegment[] array, @Nullable CopyFunc func)	Makes a full (deep) copy of a GPtrArray.
static void	extend(MemorySegment[] arrayToExtend, MemorySegment[] array, @Nullable CopyFunc func)	Adds all pointers of array to the end of the array arrayToExtend.
static void	extendAndSteal(MemorySegment[] arrayToExtend, MemorySegment[] 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.
static boolean	find(MemorySegment[] haystack, @Nullable MemorySegment needle, @Nullable Out<Integer> index)	Checks whether needle exists in haystack.
static boolean	findWithEqualFunc(MemorySegment[] haystack, @Nullable MemorySegment needle, @Nullable EqualFunc equalFunc, @Nullable Out<Integer> index)	Checks whether needle exists in haystack, using the given equalFunc.
static void	foreach(MemorySegment[] array, Func func)	Calls a function for each element of a GPtrArray.
static MemorySegment	free(MemorySegment[] array, boolean freeSeg)	Frees the memory allocated for the GPtrArray.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static Type	getType()	Get the GType of the PtrArray class
static void	insert(MemorySegment[] array, int index, @Nullable MemorySegment data)	Inserts an element into the pointer array at the given index.
static boolean	isNullTerminated(MemorySegment[] array)	Gets whether the array was constructed as null-terminated.
static MemorySegment[]	new_()	Creates a new GPtrArray with a reference count of 1.
static MemorySegment[]	newFromArray(@Nullable MemorySegment[] data, @Nullable CopyFunc copyFunc)	Creates a new GPtrArray, copying len pointers from data, and setting the array’s reference count to 1.
static MemorySegment[]	newFromNullTerminatedArray(@Nullable MemorySegment[] 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.
static MemorySegment[]	newFull(int reservedSize)	Creates a new GPtrArray with reservedSize pointers preallocated and a reference count of 1.
static MemorySegment[]	newNullTerminated(int reservedSize, boolean nullTerminated)	Like g_ptr_array_new_full() but also allows to set the array to be null terminated.
static MemorySegment[]	newTake(@Nullable MemorySegment[] data)	Creates a new GPtrArray with data as pointers, len as length and a reference count of 1.
static MemorySegment[]	newTakeNullTerminated(@Nullable MemorySegment[] data)	Creates a new GPtrArray with data as pointers, computing the length of it and setting the reference count to 1.
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 g_ptr_array_unref(), when g_ptr_array_free() is called with freeSegment set to true or when removing elements.
int	readLen()	Read the value of the field len.
MemorySegment	readPdata()	Read the value of the field pdata.
static MemorySegment[]	ref(MemorySegment[] array)	Atomically increments the reference count of array by one.
static boolean	remove(MemorySegment[] array, @Nullable MemorySegment data)	Removes the first occurrence of the given pointer from the pointer array.
static boolean	removeFast(MemorySegment[] array, @Nullable MemorySegment data)	Removes the first occurrence of the given pointer from the pointer array.
static MemorySegment	removeIndex(MemorySegment[] array, int index)	Removes the pointer at the given index from the pointer array.
static MemorySegment	removeIndexFast(MemorySegment[] array, int index)	Removes the pointer at the given index from the pointer array.
static MemorySegment[]	removeRange(MemorySegment[] array, int index, int length)	Removes the given number of pointers starting at the given index from a GPtrArray.
static void	setFreeFunc(MemorySegment[] array)	Sets a function for freeing each element when array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with freeSegment set to true or when removing elements.
static void	setSize(MemorySegment[] array, int length)	Sets the size of the array.
static MemorySegment[]	sizedNew(int reservedSize)	Creates a new GPtrArray with reservedSize pointers preallocated and a reference count of 1.
static void	sort(MemorySegment[] array, 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).
static void	sortValues(MemorySegment[] array, 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).
static void	sortValuesWithData(MemorySegment[] array, CompareDataFunc compareFunc)	Like g_ptr_array_sort_values(), but the comparison function has an extra user data argument.
static void	sortWithData(MemorySegment[] array, CompareDataFunc compareFunc)	Like g_ptr_array_sort(), but the comparison function has an extra user data argument.
static MemorySegment	steal(MemorySegment[] 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.
static MemorySegment	stealIndex(MemorySegment[] array, int index)	Removes the pointer at the given index from the pointer array.
static MemorySegment	stealIndexFast(MemorySegment[] array, int index)	Removes the pointer at the given index from the pointer array.
static void	unref(MemorySegment[] array)	Atomically decrements the reference count of array by one.
void	writeLen(int len)	Write a value in the field len.
void	writePdata(MemorySegment pdata)	Write a value in the field pdata.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

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 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(MemorySegment[] array,
 @Nullable
 @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 GPtrArray

data - the pointer to add

copy

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

Makes a full (deep) copy of a GPtrArray.

func, as a GCopyFunc, 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 GDestroyNotify for its elements as array. The copy will also be null terminated if (and only if) the source array is.

Parameters:

array - GPtrArray to duplicate

func - a copy function used to copy every element in the array

Returns:

a deep copy of the initial GPtrArray.

extend

public static void extend(MemorySegment[] arrayToExtend,
 MemorySegment[] array,
 @Nullable
 @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 GCopyFunc, 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 GPtrArray.

array - a GPtrArray to add to the end of arrayToExtend.

func - a copy function used to copy every element in the array

extendAndSteal

public static void extendAndSteal(MemorySegment[] arrayToExtend,
 MemorySegment[] 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 g_ptr_array_free(), 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 GPtrArray.

array - a GPtrArray to add to the end of arrayToExtend.

find

public static boolean find(MemorySegment[] haystack,
 @Nullable
 @Nullable MemorySegment needle,
 @Nullable
 @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 g_ptr_array_find_with_equal_func().

Parameters:

haystack - pointer array to be searched

needle - pointer to look for

index - return location for the index of the element, if found

Returns:

true if needle is one of the elements of haystack

findWithEqualFunc

public static boolean findWithEqualFunc(MemorySegment[] haystack,
 @Nullable
 @Nullable MemorySegment needle,
 @Nullable
 @Nullable EqualFunc equalFunc,
 @Nullable
 @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 - pointer array to be searched

needle - 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 - return location for the index of the element, if found

Returns:

true if needle is one of the elements of haystack

foreach

public static void foreach(MemorySegment[] array,
 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 GPtrArray

func - the function to call for each array element

free

public static MemorySegment free(MemorySegment[] array,
 boolean freeSeg)

Frees the memory allocated for the GPtrArray. If freeSeg 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 freeSeg is true and no GDestroyNotify function has been set for array.

Note that if the array is null terminated and freeSeg 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 g_ptr_array_ref() and g_ptr_array_unref() functions.

Parameters:

array - a GPtrArray

freeSeg - if true the actual pointer array is freed as well

Returns:

the pointer array if freeSeg is false, otherwise null. The pointer array should be freed using g_free().

insert

public static void insert(MemorySegment[] array,
 int index,
 @Nullable
 @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 GPtrArray

index - the index to place the new element at, or -1 to append

data - the pointer to add.

isNullTerminated

public static boolean isNullTerminated(MemorySegment[] array)

Gets 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 g_ptr_array_new_null_terminated(). It will not return true for normal arrays which have had a null element appended to them.

Parameters:

array - the GPtrArray

Returns:

true if the array is made to be null terminated.

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
 @Nullable MemorySegment[] data,
 @Nullable
 @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 g_ptr_array_unref(), when g_ptr_array_free() 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, or null for an empty array

copyFunc - a copy function used to copy every element in the array or null.

Returns:

A new GPtrArray

newFromNullTerminatedArray

public static MemorySegment[] newFromNullTerminatedArray(@Nullable
 @Nullable MemorySegment[] data,
 @Nullable
 @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 set elementFreeFunc for freeing each element when the array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() 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; or null for an empty array

copyFunc - a copy function used to copy every element in the array or null.

Returns:

A new GPtrArray

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 set elementFreeFunc for freeing each element when the array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with freeSegment set to true or when removing elements.

Parameters:

reservedSize - number of pointers preallocated

Returns:

A new GPtrArray

newNullTerminated

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

Like g_ptr_array_new_full() 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 - 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 - whether to make the array as null terminated.

Returns:

A new GPtrArray

newTake

public static MemorySegment[] newTake(@Nullable
 @Nullable MemorySegment[] 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 g_free().

It also sets elementFreeFunc for freeing each element when the array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() 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, or null for an empty array

Returns:

A new GPtrArray

newTakeNullTerminated

public static MemorySegment[] newTakeNullTerminated(@Nullable
 @Nullable MemorySegment[] 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 g_free().

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 g_ptr_array_unref(), when g_ptr_array_free() 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, or null for an empty array

Returns:

A new GPtrArray

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 g_ptr_array_unref(), when g_ptr_array_free() is called with freeSegment set to true or when removing elements.

Returns:

A new GPtrArray

ref

public static MemorySegment[] ref(MemorySegment[] 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 GPtrArray

Returns:

The passed in GPtrArray

remove

public static boolean remove(MemorySegment[] array,
 @Nullable
 @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 GDestroyNotify 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 GPtrArray

data - the pointer to remove

Returns:

true if the pointer is removed, false if the pointer is not found in the array

removeFast

public static boolean removeFast(MemorySegment[] array,
 @Nullable
 @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 g_ptr_array_remove(). If array has a non-null GDestroyNotify 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 GPtrArray

data - the pointer to remove

Returns:

true if the pointer was found in the array

removeIndex

public static MemorySegment removeIndex(MemorySegment[] 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 GDestroyNotify 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 GDestroyNotify implementation).

Parameters:

array - a GPtrArray

index - the index of the pointer to remove

Returns:

the pointer which was removed

removeIndexFast

public static MemorySegment removeIndexFast(MemorySegment[] 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 g_ptr_array_remove_index(). If array has a non-null GDestroyNotify 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 GDestroyNotify implementation).

Parameters:

array - a GPtrArray

index - the index of the pointer to remove

Returns:

the pointer which was removed

removeRange

public static MemorySegment[] removeRange(MemorySegment[] 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 GDestroyNotify function it is called for the removed elements.

Parameters:

array - a GPtrArray

index - the index of the first pointer to remove

length - the number of pointers to remove

Returns:

the array

setFreeFunc

public static void setFreeFunc(MemorySegment[] array)

Sets a function for freeing each element when array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with freeSegment set to true or when removing elements.

Parameters:

array - A GPtrArray

setSize

public static void setSize(MemorySegment[] 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 GDestroyNotify function then it will be called for the removed elements.

Parameters:

array - a GPtrArray

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 - number of pointers preallocated

Returns:

the new GPtrArray

sort

public static void sort(MemorySegment[] array,
 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 g_ptr_array_sort() doesn't take the pointers from the array as arguments, it takes pointers to the pointers in the array.

Use g_ptr_array_sort_values() if you want to use normal GCompareFuncs, 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 GPtrArray

compareFunc - comparison function

sortValues

public static void sortValues(MemorySegment[] array,
 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 GPtrArray

compareFunc - a GCompareFunc comparison function

sortValuesWithData

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

Like g_ptr_array_sort_values(), but the comparison function has an extra user data argument.

This is guaranteed to be a stable sort.

Parameters:

array - a GPtrArray

compareFunc - a GCompareDataFunc comparison function

sortWithData

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

Like g_ptr_array_sort(), but the comparison function has an extra user data argument.

Note that the comparison function for g_ptr_array_sort_with_data() doesn't take the pointers from the array as arguments, it takes pointers to the pointers in the array.

Use g_ptr_array_sort_values_with_data() if you want to use normal GCompareDataFuncs, 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 GPtrArray

compareFunc - comparison function

steal

public static MemorySegment steal(MemorySegment[] array,
 @Nullable
 @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 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 GDestroyNotify 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 GPtrArray.

len - pointer to retrieve the number of elements of the original array

Returns:

the element data, which should be freed using g_free(). This may be null if the array doesn’t have any elements (i.e. if *len is zero).

stealIndex

public static MemorySegment stealIndex(MemorySegment[] array,
 int index)

Removes the pointer at the given index from the pointer array. The following elements are moved down one place. The GDestroyNotify for array is not called on the removed element; ownership is transferred to the caller of this function.

Parameters:

array - a GPtrArray

index - the index of the pointer to steal

Returns:

the pointer which was removed

stealIndexFast

public static MemorySegment stealIndexFast(MemorySegment[] 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 g_ptr_array_steal_index(). The GDestroyNotify for array is not called on the removed element; ownership is transferred to the caller of this function.

Parameters:

array - a GPtrArray

index - the index of the pointer to steal

Returns:

the pointer which was removed

unref

public static void unref(MemorySegment[] array)

Atomically decrements the reference count of array by one. If the reference count drops to 0, the effect is the same as calling g_ptr_array_free() with freeSegment set to true. This function is thread-safe and may be called from any thread.

Parameters:

array - A GPtrArray