Package org.gnome.glib

Class Array

java.lang.Object

io.github.jwharm.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(MemorySegment[] array, MemorySegment data, int len)	Adds len elements onto the end of the array.
static boolean	binarySearch(MemorySegment[] array, @Nullable MemorySegment target, 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 get pointers to items as arguments.
static MemorySegment[]	copy(MemorySegment[] array)	Create a shallow copy of a GArray.
static String	free(MemorySegment[] array, boolean freeSegment)	Frees the memory allocated for the GArray.
static int	getElementSize(MemorySegment[] array)	Gets the size of the elements in array.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static Type	getType()	Get the GType of the Array class
static MemorySegment[]	insertVals(MemorySegment[] 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[] 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(MemorySegment[] 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(MemorySegment[] 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(MemorySegment[] array)	Atomically increments the reference count of array by one.
static MemorySegment[]	removeIndex(MemorySegment[] array, int index)	Removes the element at the given index from a GArray.
static MemorySegment[]	removeIndexFast(MemorySegment[] array, int index)	Removes the element at the given index from a GArray.
static MemorySegment[]	removeRange(MemorySegment[] array, int index, int length)	Removes the given number of elements starting at the given index from a GArray.
static void	setClearFunc(MemorySegment[] array)	Sets a function to clear an element of array.
static MemorySegment[]	setSize(MemorySegment[] 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(MemorySegment[] array, 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(MemorySegment[] array, CompareDataFunc compareFunc)	Like g_array_sort(), but the comparison function receives 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 void	unref(MemorySegment[] 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 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

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 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(MemorySegment[] array,
 MemorySegment data,
 int len)

Adds len elements onto the end of the array.

Parameters:

array - a GArray

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(MemorySegment[] array,
 @Nullable
 @Nullable MemorySegment target,
 CompareFunc compareFunc,
 @Nullable
 @Nullable Out<Integer> outMatchIndex)

Checks whether target exists in array by performing a binary search based on the given comparison function compareFunc which get 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. If target exists multiple times in array, the index of the first instance is returned. 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 search 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 - a GArray.

target - a pointer to the item to look up.

compareFunc - A GCompareFunc used to locate target.

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

Returns:

true if target is one of the elements of array, false otherwise.

copy

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

Create 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 - A GArray.

Returns:

A copy of array.

free

public static String free(MemorySegment[] 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 freeSeg 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 g_array_ref() and g_array_unref() functions.

Parameters:

array - a GArray

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

Returns:

the element data if freeSegment is false, otherwise null. The element data should be freed using g_free().

getElementSize

public static int getElementSize(MemorySegment[] array)

Gets the size of the elements in array.

Parameters:

array - A GArray

Returns:

Size of each element, in bytes

insertVals

public static MemorySegment[] insertVals(MemorySegment[] array,
 int index,
 @Nullable
 @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 - a GArray

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 - true if the array should have an extra element at the end which is set to 0

clear - true if 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
 @Nullable MemorySegment[] 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 g_free().

In case the elements need to be cleared when the array is freed, use g_array_set_clear_func() to set a GDestroyNotify 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, or null for an empty array

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

elementSize - the size of each element in bytes

Returns:

A new GArray

newTakeZeroTerminated

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

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 g_array_set_clear_func() to set a GDestroyNotify 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

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

elementSize - the size of each element in bytes

Returns:

A new GArray

prependVals

public static MemorySegment[] prependVals(MemorySegment[] array,
 @Nullable
 @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 g_array_append_vals() since the existing elements in the array have to be moved to make space for the new elements.

Parameters:

array - a GArray

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(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 GArray

Returns:

The passed in GArray

removeIndex

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

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

Parameters:

array - a GArray

index - the index of the element to remove

Returns:

the GArray

removeIndexFast

public static MemorySegment[] removeIndexFast(MemorySegment[] 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 g_array_remove_index().

Parameters:

array - a GArray

index - the index of the element to remove

Returns:

the GArray

removeRange

public static MemorySegment[] removeRange(MemorySegment[] 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 - a GArray

index - the index of the first element to remove

length - the number of elements to remove

Returns:

the GArray

setClearFunc

public static void setClearFunc(MemorySegment[] 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 GDestroyNotify 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 - A GArray

setSize

public static MemorySegment[] setSize(MemorySegment[] 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 - a GArray

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 - true if the array should have an extra element at the end with all bits cleared

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

elementSize - size of each element in the array

reservedSize - number of elements preallocated

Returns:

the new GArray

sort

public static void sort(MemorySegment[] array,
 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 - a GArray

compareFunc - comparison function

sortWithData

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

Like g_array_sort(), 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 - a GArray

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.

If the array was created with the zeroTerminate property set to true, the returned data is zero terminated too.

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 - a GArray.

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

Returns:

the element data, which should be freed using g_free().

unref

public static void unref(MemorySegment[] array)

Atomically decrements the reference count of array by one. If the reference count drops to 0, all memory allocated by the array is released. This function is thread-safe and may be called from any thread.

Parameters:

array - A GArray