Gnome::Glib::T-array

#------------------------------------------------------------------------------- #--[Class Initialization]------------------------------------------------------- #-------------------------------------------------------------------------------

Class initialization

new

Initialization of a type class is simple and only needed when the standalone functions are used.

method new ( )

#------------------------------------------------------------------------------- #--[Record Structure]----------------------------------------------------------- #-------------------------------------------------------------------------------

Record N-Bytes

This is an opaque type of which fields are not available.

class N-Bytes:auth<github:MARTIMM>:api<2> is export is repr('CStruct') { }

#------------------------------------------------------------------------------- #--[Record Structure Documentation]--------------------------------------------- #-------------------------------------------------------------------------------

Record N-Array

class N-Array:auth<github:MARTIMM>:api<2> is export is repr('CStruct') {

has Str $.data;
    has guint $.len;
  }

• data; a pointer to the element data. The data may be moved as elements are added to the Gnome::Glib::N-Array.

• len; the number of elements in the Gnome::Glib::N-Array not including the possible terminating zero element.

#------------------------------------------------------------------------------- #--[Record Structure Documentation]--------------------------------------------- #-------------------------------------------------------------------------------

Record N-PtrArray

class N-PtrArray:auth<github:MARTIMM>:api<2> is export is repr('CStruct') {

has CArray[gpointer] $.pdata;
    has guint $.len;
  }

• pdata; points to the array of pointers, which may be moved when the array grows

• len; number of pointers in the array

#------------------------------------------------------------------------------- #--[Record Structure Documentation]--------------------------------------------- #-------------------------------------------------------------------------------

Record N-ByteArray

class N-ByteArray:auth<github:MARTIMM>:api<2> is export is repr('CStruct') {

has  $.data;
    has guint $.len;
  }

• data; a pointer to the element data. The data may be moved as elements are added to the Gnome::Glib::N-ByteArray

• len; the number of elements in the Gnome::Glib::N-ByteArray

#------------------------------------------------------------------------------- #--[Standalone Functions]------------------------------------------------------- #-------------------------------------------------------------------------------

Standalone Functions

#-------------------------------------------------------------------------------

array-new-take

Creates a new Gnome::Glib::N-Array 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 Gnome::Glib::N-Array 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 Gnome::Glib::T-types function to perform such task.

Do not use it if $len or $element-size are greater than G_MAXUINT. Gnome::Glib::N-Array stores the length of its data in #guint, which may be shorter than #gsize.

method array-new-take ( gpointer $data, Int() $len, Bool() $clear, Int() $element-size --> N-Object )

• $data; (transfer ownership: full) an array of elements of $element-size, or undefined for an empty array.

• $len; the number of elements in $data.

• $clear; True if Gnome::Glib::N-Array elements should be automatically cleared to 0 when they are allocated.

• $element-size; the size of each element in bytes.

Return value; A new Gnome::Glib::N-Array.

#-------------------------------------------------------------------------------

array-new-take-zero-terminated

Creates a new Gnome::Glib::N-Array 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 Gnome::Glib::N-Array 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 undefined 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 Gnome::Glib::T-types function to perform such task.

Do not use it if $data length or $element-size are greater than G_MAXUINT. Gnome::Glib::N-Array stores the length of its data in #guint, which may be shorter than #gsize.

method array-new-take-zero-terminated ( gpointer $data, Bool() $clear, Int() $element-size --> N-Object )

• $data; an array of elements of $element-size.

• $clear; True if Gnome::Glib::N-Array elements should be automatically cleared to 0 when they are allocated.

• $element-size; the size of each element in bytes.

Return value; A new Gnome::Glib::N-Array.

#-------------------------------------------------------------------------------

byte-array-free

Frees the memory allocated by the Gnome::Glib::N-ByteArray. If $free-segment is True it frees the actual byte data. If the reference count of $array is greater than one, the Gnome::Glib::N-ByteArray wrapper is preserved but the size of $array will be set to zero.

method byte-array-free ( N-Object $array, Bool() $free-segment --> Array[Int] )

• $array; a Gnome::Glib::N-ByteArray

• $free-segment; if True the actual byte data is freed as well.

Return value; the element data if $free-segment is False, otherwise undefined. The element data should be freed using g_free()..

#-------------------------------------------------------------------------------

byte-array-free-to-bytes

Transfers the data from the Gnome::Glib::N-ByteArray into a new immutable Gnome::Glib::T-array.

The Gnome::Glib::N-ByteArray is freed unless the reference count of $array is greater than one, the Gnome::Glib::N-ByteArray wrapper is preserved but the size of $array will be set to zero.

This is identical to using .new-take() and g_byte_array_free() together.

method byte-array-free-to-bytes ( N-Object $array --> N-Object )

• $array; (transfer ownership: full) a Gnome::Glib::N-ByteArray

Return value; a new immutable Gnome::Glib::T-array representing same byte data that was in the array.

#-------------------------------------------------------------------------------

byte-array-new

Creates a new Gnome::Glib::N-ByteArray with a reference count of 1.

method byte-array-new (--> N-Object )

Return value; the new Gnome::Glib::N-ByteArray.

#-------------------------------------------------------------------------------

byte-array-new-take

Creates a byte array containing the $data. After this call, $data belongs to the Gnome::Glib::N-ByteArray 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().

Do not use it if $len is greater than G_MAXUINT. Gnome::Glib::N-ByteArray stores the length of its data in #guint, which may be shorter than #gsize.

method byte-array-new-take ( Array[Int] $data, Int() $len --> N-Object )

• $data; (transfer ownership: full) byte data for the array.

• $len; length of $data.

Return value; a new Gnome::Glib::N-ByteArray.

#-------------------------------------------------------------------------------

byte-array-steal

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.

method byte-array-steal ( N-Object $array, Array[gsize] $len --> Array[Int] )

• $array; a Gnome::Glib::N-ByteArray.

• $len; (transfer ownership: full) pointer to retrieve the number of elements of the original array.

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

#-------------------------------------------------------------------------------

byte-array-unref

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.

method byte-array-unref ( N-Object $array )

• $array; A Gnome::Glib::N-ByteArray

#-------------------------------------------------------------------------------

ptr-array-find

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-undefined). 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().

method ptr-array-find ( N-Object $haystack, gpointer $needle, Array[Int] $index --> Bool )

• $haystack; pointer array to be searched

• $needle; pointer to look for.

• $index; (transfer ownership: full) return location for the index of the element, if found.

Return value; True if $needle is one of the elements of $haystack.

#-------------------------------------------------------------------------------

ptr-array-find-with-equal-func

Checks whether $needle exists in $haystack, using the given $equal-func. If the element is found, True is returned and the element’s index is returned in $index- (if non-undefined). Otherwise, False is returned and $index- is undefined. If $needle exists multiple times in $haystack, the index of the first instance is returned. $equal-func is called with the element from the array as its first parameter, and $needle as its second parameter. If $equal-func is undefined, pointer equality is used.

method ptr-array-find-with-equal-func ( N-Object $haystack, gpointer $needle, &equal-func, Array[Int] $index --> Bool )

• $haystack; pointer array to be searched

• $needle; pointer to look for.

• &equal-func; the function to call for each element, which should return True when the desired element is found; or undefined to use pointer equality. Tthe function must be specified with following signature; :( gpointer $a, gpointer $b -- gboolean )>.

• $index; (transfer ownership: full) return location for the index of the element, if found.

Return value; True if $needle is one of the elements of $haystack.

#-------------------------------------------------------------------------------

ptr-array-new-from-array

Creates a new Gnome::Glib::N-PtrArray, 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 $copy-func is provided, then it is used to copy each element before adding them to the new array. If it is undefined then the pointers are copied directly.

It also sets $element-free-func for freeing each element when the array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with $free-segment set to True or when removing elements.

Do not use it if $len is greater than G_MAXUINT. Gnome::Glib::N-PtrArray stores the length of its data in #guint, which may be shorter than #gsize.

method ptr-array-new-from-array ( Array $data, Int() $len, &copy-func, gpointer $copy-func-user-data, &element-free-func --> N-Object )

• $data; an array of pointers, or undefined for an empty array.

• $len; the number of pointers in $data.

• &copy-func; a copy function used to copy every element in the array or undefined.. Tthe function must be specified with following signature; :( gpointer $src, gpointer $data -- gpointer )>.

• $copy-func-user-data; user data passed to $copy-func, or undefined.

• &element-free-func; a function to free elements on $array destruction or undefined. Tthe function must be specified with following signature; :( gpointer $data ).

Return value; A new Gnome::Glib::N-PtrArray.

#-------------------------------------------------------------------------------

ptr-array-new-from-null-terminated-array

Creates a new Gnome::Glib::N-PtrArray 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 $copy-func is provided, then it is used to copy the data in the new array. It also set $element-free-func for freeing each element when the array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with $free-segment set to True or when removing elements.

Do not use it if the $data has more than G_MAXUINT elements. Gnome::Glib::N-PtrArray stores the length of its data in #guint, which may be shorter than #gsize.

method ptr-array-new-from-null-terminated-array ( Array $data, &copy-func, gpointer $copy-func-user-data, &element-free-func --> N-Object )

• $data; an array of pointers, undefined terminated; or undefined for an empty array.

• &copy-func; a copy function used to copy every element in the array or undefined.. Tthe function must be specified with following signature; :( gpointer $src, gpointer $data -- gpointer )>.

• $copy-func-user-data; user data passed to $copy-func, or undefined.

• &element-free-func; a function to free elements on $array destruction or undefined. Tthe function must be specified with following signature; :( gpointer $data ).

Return value; A new Gnome::Glib::N-PtrArray.

#-------------------------------------------------------------------------------

ptr-array-new-take

Creates a new Gnome::Glib::N-PtrArray 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 Gnome::Glib::N-PtrArray 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 $element-free-func for freeing each element when the array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with $free-segment set to True or when removing elements.

Do not use it if $len is greater than G_MAXUINT. Gnome::Glib::N-PtrArray stores the length of its data in #guint, which may be shorter than #gsize.

method ptr-array-new-take ( Array $data, Int() $len, &element-free-func --> N-Object )

• $data; (transfer ownership: full) an array of pointers, or undefined for an empty array.

• $len; the number of pointers in $data.

• &element-free-func; A function to free elements on $array destruction or undefined. Tthe function must be specified with following signature; :( gpointer $data ).

Return value; A new Gnome::Glib::N-PtrArray.

#-------------------------------------------------------------------------------

ptr-array-new-take-null-terminated

Creates a new Gnome::Glib::N-PtrArray 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 Gnome::Glib::N-PtrArray 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 undefined element is found.

It also sets $element-free-func for freeing each element when the array is destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called with $free-segment set to True or when removing elements.

Do not use it if the $data length is greater than G_MAXUINT. Gnome::Glib::N-PtrArray stores the length of its data in #guint, which may be shorter than #gsize.

method ptr-array-new-take-null-terminated ( Array $data, &element-free-func --> N-Object )

• $data; (transfer ownership: full) an array of pointers, undefined terminated, or undefined for an empty array.

• &element-free-func; a function to free elements on $array destruction or undefined. Tthe function must be specified with following signature; :( gpointer $data ).

Return value; A new Gnome::Glib::N-PtrArray.