Package org.gnome.glib

Class Array

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.glib.Array

All Implemented Interfaces:

Proxy

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

Contains the public fields of a GArray.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
static MemorySegment[]	appendVals(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data, int len)	Adds len elements onto the end of the array.
static boolean	binarySearch(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment target, @Nullable CompareFunc compareFunc, @Nullable Out<Integer> outMatchIndex)	Checks whether target exists in array by performing a binary search based on the given comparison function compareFunc which gets pointers to items as arguments.
static MemorySegment[]	copy(@Nullable MemorySegment @Nullable [] array)	Creates a shallow copy of a GArray.
static String	free(@Nullable MemorySegment @Nullable [] array, boolean freeSegment)	Frees the memory allocated for the GArray.
static int	getElementSize(@Nullable MemorySegment @Nullable [] array)	Gets the size of the elements in array.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static @Nullable Type	getType()	Get the GType of the Array class
static MemorySegment[]	insertVals(@Nullable MemorySegment @Nullable [] array, int index, @Nullable MemorySegment data, int len)	Inserts len elements into a GArray at the given index.
static MemorySegment[]	new_(boolean zeroTerminated, boolean clear, int elementSize)	Creates a new GArray with a reference count of 1.
static MemorySegment[]	newTake(@Nullable MemorySegment @Nullable [] data, boolean clear, long elementSize)	Creates a new GArray with data as array data, len as length and a reference count of 1.
static MemorySegment[]	newTakeZeroTerminated(@Nullable MemorySegment @Nullable [] data, boolean clear, long elementSize)	Creates a new GArray with data as array data, computing the length of it and setting the reference count to 1.
static MemorySegment[]	prependVals(@Nullable MemorySegment @Nullable [] array, @Nullable MemorySegment data, int len)	Adds len elements onto the start of the array.
String	readData()	Read the value of the field data.
int	readLen()	Read the value of the field len.
static MemorySegment[]	ref(@Nullable MemorySegment @Nullable [] array)	Atomically increments the reference count of array by one.
static MemorySegment[]	removeIndex(@Nullable MemorySegment @Nullable [] array, int index)	Removes the element at the given index from a GArray.
static MemorySegment[]	removeIndexFast(@Nullable MemorySegment @Nullable [] array, int index)	Removes the element at the given index from a GArray.
static MemorySegment[]	removeRange(@Nullable MemorySegment @Nullable [] array, int index, int length)	Removes the given number of elements starting at the given index from a GArray.
static void	setClearFunc(@Nullable MemorySegment @Nullable [] array)	Sets a function to clear an element of array.
static MemorySegment[]	setSize(@Nullable MemorySegment @Nullable [] array, int length)	Sets the size of the array, expanding it if necessary.
static MemorySegment[]	sizedNew(boolean zeroTerminated, boolean clear, int elementSize, int reservedSize)	Creates a new GArray with reservedSize elements preallocated and a reference count of 1.
static void	sort(@Nullable MemorySegment @Nullable [] array, @Nullable CompareFunc compareFunc)	Sorts a GArray using compareFunc which should be a qsort()-style comparison function (returns less than zero for first arg is less than second arg, zero for equal, greater zero if first arg is greater than second arg).
static void	sortWithData(@Nullable MemorySegment @Nullable [] array, @Nullable CompareDataFunc compareFunc)	Like sort(java.lang.foreign.MemorySegment[], org.gnome.glib.CompareFunc), but the comparison function receives an extra user data argument.
static @Nullable MemorySegment	steal(@Nullable MemorySegment @Nullable [] array, @Nullable Out<Long> len)	Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller.
static void	unref(@Nullable MemorySegment @Nullable [] array)	Atomically decrements the reference count of array by one.
void	writeData(String data, Arena _arena)	Write a value in the field data.
void	writeLen(int len)	Write a value in the field len.

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

Array

public Array(MemorySegment address)

Create a Array proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Array

public Array(Arena arena)

Allocate a new Array.

Parameters:

arena - to control the memory allocation scope

Array

public Array()

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

Array

public Array(String data,
 int len,
 Arena arena)

Allocate a new Array with the fields set to the provided values.

Parameters:

data - value for the field data

len - value for the field len

arena - to control the memory allocation scope

Array

public Array(String data,
 int len)

Allocate a new Array with the fields set to the provided values. The memory is allocated with Arena.ofAuto().

Parameters:

data - value for the field data

len - value for the field len

Method Details

getType

public static @Nullable Type getType()

Get the GType of the Array class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readData

public String readData()

Read the value of the field data.

Returns:

The value of the field data

writeData

public void writeData(String data,
 Arena _arena)

Write a value in the field data.

Parameters:

data - The new value for the field data

_arena - to control the memory allocation scope

readLen

public int readLen()

Read the value of the field len.

Returns:

The value of the field len

writeLen

public void writeLen(int len)

Write a value in the field len.

Parameters:

len - The new value for the field len

appendVals

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

Adds len elements onto the end of the array.

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

Parameters:

array - an array

data - a pointer to the elements to append to the end of the array

len - the number of elements to append

Returns:

The GArray

binarySearch

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

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

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

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

   return *_a - *_b;
 }
 ...
 gint i = 424242;
 guint matched_index;
 gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index);
 ...
 

Parameters:

array - an array

target - a pointer to the item to look up

compareFunc - a comparison function to locate target

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

Returns:

true if target is one of the elements of array; false otherwise

Since:

2.62

copy

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

Creates a shallow copy of a GArray. If the array elements consist of pointers to data, the pointers are copied but the actual data is not.

Parameters:

array - an array

Returns:

The copy of array

Since:

2.62

free

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

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

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

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

Parameters:

array - an array

freeSegment - if true, the actual element data is freed as well

Returns:

The allocated element data if freeSegment is false, otherwise NULL

getElementSize

public static int getElementSize(@Nullable MemorySegment @Nullable [] array)

Gets the size of the elements in array.

Parameters:

array - an array

Returns:

The size of each element, in bytes

Since:

2.22

insertVals

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

Inserts len elements into a GArray at the given index.

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

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

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

Parameters:

array - an array

index - the index to place the elements at

data - a pointer to the elements to insert

len - the number of elements to insert

Returns:

The GArray

new_

public static MemorySegment[] new_(boolean zeroTerminated,
 boolean clear,
 int elementSize)

Creates a new GArray with a reference count of 1.

Parameters:

zeroTerminated - if true, the array should have an extra element at the end which is set to 0

clear - if true, GArray elements should be automatically cleared to 0 when they are allocated

elementSize - the size of each element in bytes

Returns:

The new GArray

newTake

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

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

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

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

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

Parameters:

data - an array of elements of elementSize

clear - if true, GArray elements should be automatically cleared to 0 when they are allocated

elementSize - the size of each element in bytes

Returns:

The new GArray

Since:

2.76

newTakeZeroTerminated

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

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

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

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

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

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

Parameters:

data - an array of elements of elementSize, NULL terminated

clear - if true, GArray elements should be automatically cleared to 0 when they are allocated

elementSize - the size of each element in bytes

Returns:

The new GArray

Since:

2.76

prependVals

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

Adds len elements onto the start of the array.

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

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

Parameters:

array - an array

data - a pointer to the elements to prepend to the start of the array

len - the number of elements to prepend, which may be zero

Returns:

The GArray

ref

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

Atomically increments the reference count of array by one. This function is thread-safe and may be called from any thread.

Parameters:

array - an array

Returns:

The passed in GArray

Since:

2.22

removeIndex

public static MemorySegment[] removeIndex(@Nullable MemorySegment @Nullable [] array,
 int index)

Removes the element at the given index from a GArray. The following elements are moved down one place.

Parameters:

array - an array

index - the index of the element to remove

Returns:

The GArray

removeIndexFast

public static MemorySegment[] removeIndexFast(@Nullable MemorySegment @Nullable [] array,
 int index)

Removes the element at the given index from a GArray. The last element in the array is used to fill in the space, so this function does not preserve the order of the GArray. But it is faster than removeIndex(java.lang.foreign.MemorySegment[], int).

Parameters:

array - an array

index - the index of the element to remove

Returns:

The GArray

removeRange

public static MemorySegment[] removeRange(@Nullable MemorySegment @Nullable [] array,
 int index,
 int length)

Removes the given number of elements starting at the given index from a GArray. The following elements are moved to close the gap.

Parameters:

array - an array

index - the index of the first element to remove

length - the number of elements to remove

Returns:

The GArray

Since:

2.4

setClearFunc

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

Sets a function to clear an element of array.

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

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

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

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

 // main code
 GArray *garray = g_array_new (FALSE, FALSE, sizeof (ArrayElement));
 g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear);
 // assign data to the structure
 g_array_free (garray, TRUE);
 

Parameters:

array - an array

Since:

2.32

setSize

public static MemorySegment[] setSize(@Nullable MemorySegment @Nullable [] array,
 int length)

Sets the size of the array, expanding it if necessary. If the array was created with clear set to true, the new elements are set to 0.

Parameters:

array - an array

length - the new size of the GArray

Returns:

The GArray

sizedNew

public static MemorySegment[] sizedNew(boolean zeroTerminated,
 boolean clear,
 int elementSize,
 int reservedSize)

Creates a new GArray with reservedSize elements preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many elements to the array. Note however that the size of the array is still 0.

Parameters:

zeroTerminated - if true, the array should have an extra element at the end with all bits cleared

clear - if true, all bits in the array should be cleared to 0 on allocation

elementSize - the size of each element in the array

reservedSize - the number of elements preallocated

Returns:

The new GArray

sort

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

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

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

Parameters:

array - an array

compareFunc - a comparison function

sortWithData

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

Like sort(java.lang.foreign.MemorySegment[], org.gnome.glib.CompareFunc), but the comparison function receives an extra user data argument.

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

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

Parameters:

array - an array

compareFunc - a comparison function

steal

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

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

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

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

A short example of use:

...
 gpointer data;
 gsize data_len;
 data = g_array_steal (some_array, &data_len);
 ...
 

Parameters:

array - an array

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

Returns:

The allocated element data

Since:

2.64

unref

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

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

Parameters:

array - an array

Since:

2.22