Package org.gnome.glib

Class PtrArray

java.lang.Object

org.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 GPtrArray.

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(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data)	Adds a pointer to the end of the pointer array.
static MemorySegment[]	copy(@Nullable MemorySegment @Nullable [] array, @Nullable CopyFunc func)	Makes a full (deep) copy of a GPtrArray.
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.
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.
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).
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).
static void	foreach(@Nullable MemorySegment @Nullable [] array, @Nullable Func func)	Calls a function for each element of a GPtrArray.
static @Nullable MemorySegment @Nullable []	free(@Nullable MemorySegment @Nullable [] array, boolean freeSegment)	Frees the memory allocated for the GPtrArray.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static @Nullable Type	getType()	Get the GType of the PtrArray class
static void	insert(@Nullable MemorySegment @Nullable [] array, int index, @Nullable MemorySegment data)	Inserts an element into the pointer array at the given index.
static boolean	isNullTerminated(@Nullable MemorySegment @Nullable [] array)	Checks 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 @Nullable [] 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 @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.
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 newFull(int) but also allows to set the array to be NULL terminated.
static MemorySegment[]	newTake(@Nullable MemorySegment @Nullable [] data)	Creates a new GPtrArray with data as pointers, len as length and a reference count of 1.
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.
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(java.lang.foreign.MemorySegment[]), when free(java.lang.foreign.MemorySegment[], boolean) 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(@Nullable MemorySegment @Nullable [] array)	Atomically increments the reference count of array by one.
static boolean	remove(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data)	Removes the first occurrence of the given pointer from the pointer array.
static boolean	removeFast(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data)	Removes the first occurrence of the given pointer from the pointer array.
static @Nullable MemorySegment	removeIndex(@Nullable MemorySegment @Nullable [] array, int index)	Removes the pointer at the given index from the pointer array.
static @Nullable MemorySegment	removeIndexFast(@Nullable MemorySegment @Nullable [] array, int index)	Removes the pointer at the given index from the pointer array.
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.
static void	setFreeFunc(@Nullable MemorySegment @Nullable [] array)	Sets a function for freeing each element when array is destroyed either via unref(java.lang.foreign.MemorySegment[]), when free(java.lang.foreign.MemorySegment[], boolean) is called with freeSegment set to true or when removing elements.
static void	setSize(@Nullable MemorySegment @Nullable [] 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(@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).
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).
static void	sortValuesWithData(@Nullable MemorySegment @Nullable [] array, @Nullable CompareDataFunc compareFunc)	Like sortValues(java.lang.foreign.MemorySegment[], org.gnome.glib.CompareFunc), but the comparison function has an extra user data argument.
static void	sortWithData(@Nullable MemorySegment @Nullable [] array, @Nullable CompareDataFunc compareFunc)	Like sort(java.lang.foreign.MemorySegment[], org.gnome.glib.CompareFunc), but the comparison function has an extra user data argument.
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.
static @Nullable MemorySegment	stealIndex(@Nullable MemorySegment @Nullable [] array, int index)	Removes the pointer at the given index from the pointer array.
static @Nullable MemorySegment	stealIndexFast(@Nullable MemorySegment @Nullable [] array, int index)	Removes the pointer at the given index from the pointer array.
static void	unref(@Nullable MemorySegment @Nullable [] 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 org.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 @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(java.lang.foreign.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(java.lang.foreign.MemorySegment[], java.lang.foreign.MemorySegment, org.gnome.glib.EqualFunc, org.javagi.base.Out<java.lang.Integer>).

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(java.lang.foreign.MemorySegment[]) and unref(java.lang.foreign.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(java.lang.foreign.MemorySegment[]), when free(java.lang.foreign.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(java.lang.foreign.MemorySegment[]), when free(java.lang.foreign.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(java.lang.foreign.MemorySegment[]), when free(java.lang.foreign.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(java.lang.foreign.MemorySegment).

It also sets elementFreeFunc for freeing each element when the array is destroyed either via unref(java.lang.foreign.MemorySegment[]), when free(java.lang.foreign.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(java.lang.foreign.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(java.lang.foreign.MemorySegment[]), when free(java.lang.foreign.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(java.lang.foreign.MemorySegment[]), when free(java.lang.foreign.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(java.lang.foreign.MemorySegment[], java.lang.foreign.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(java.lang.foreign.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(java.lang.foreign.MemorySegment[]), when free(java.lang.foreign.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(java.lang.foreign.MemorySegment[], org.gnome.glib.CompareFunc) doesn’t take the pointers from the array as arguments, it takes pointers to the pointers in the array.

Use sortValues(java.lang.foreign.MemorySegment[], org.gnome.glib.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(java.lang.foreign.MemorySegment[], org.gnome.glib.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(java.lang.foreign.MemorySegment[], org.gnome.glib.CompareFunc), but the comparison function has an extra user data argument.

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

Use sortValuesWithData(java.lang.foreign.MemorySegment[], org.gnome.glib.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(java.lang.foreign.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(java.lang.foreign.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