About my projects, examples and tutorials
Gnome::Glib::N-Array

Gnome::Glib::N-Array

Description

Contains the public fields of a GArray.

Class initialization

new

:native-object

Create an object using a native object from an object of the same type found elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object() :$native-object! )

Functions

append-vals

Adds $len elements onto the end of the array.

method append-vals ( N-Object $array, gpointer $data, UInt() $len --> N-Object )

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

  • $data; a pointer to the elements to append to the end of the array.

  • $len; the number of elements to append.

Return value; the Gnome::Glib::N-Array.

Checks whether $target exists in $array by performing a binary search based on the given comparison function $compare-func which get pointers to items as arguments. If the element is found, True is returned and the element’s index is returned in $out-match-index (if non-undefined). Otherwise, False is returned and $out-match-index 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 Gnome::Glib::N-Array:

method binary-search ( N-Object $array, gpointer $target, &compare-func, Array[Int] $out-match-index --> Bool )

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

  • $target; a pointer to the item to look up..

  • &compare-func; A Gnome::Glib::T-types used to locate $target.. Tthe function must be specified with following signature; :( gpointer $a, gpointer $b -- gint )>.

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

Return value; True if $target is one of the elements of $array, False otherwise..

copy

Create a shallow copy of a Gnome::Glib::N-Array. If the array elements consist of pointers to data, the pointers are copied but the actual data is not.

method copy ( N-Object $array --> N-Object )

  • $array; A Gnome::Glib::N-Array.

Return value; A copy of $array..

free

Frees the memory allocated for the Gnome::Glib::N-Array. If $free-segment is True it frees the memory block holding the elements as well. Pass False if you want to free the Gnome::Glib::N-Array wrapper but preserve the underlying array for use elsewhere. If the reference count of $array is greater than one, the Gnome::Glib::N-Array 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 $free-seg is True and no $clear-func function has been set for $array.

This function is not thread-safe. If using a Gnome::Glib::N-Array from multiple threads, use only the atomic .ref() and .unref() functions.

method free ( N-Object $array, Bool() $free-segment --> Str )

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

  • $free-segment; if True the actual element 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()..

get-element-size

Gets the size of the elements in $array.

method get-element-size ( N-Object $array --> UInt )

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

Return value; Size of each element, in bytes.

insert-vals

Inserts $len elements into a Gnome::Glib::N-Array 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 undefined if (and only if) $len is zero. If $len is zero, this function is a no-op.

method insert-vals ( N-Object $array, UInt() $index, gpointer $data, UInt() $len --> N-Object )

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

  • $index; the index to place the elements at.

  • $data; a pointer to the elements to insert.

  • $len; the number of elements to insert.

Return value; the Gnome::Glib::N-Array.

new

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

method new ( Bool() $zero-terminated, Bool() $clear, UInt() $element-size --> N-Object )

  • $zero-terminated; True if the array should have an extra element at the end which is set to 0.

  • $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; the new Gnome::Glib::N-Array.

prepend-vals

Adds $len elements onto the start of the array. $data may be undefined if (and only if) $len is zero. If $len is zero, this function is a no-op.

This operation is slower than .append-vals() since the existing elements in the array have to be moved to make space for the new elements.

method prepend-vals ( N-Object $array, gpointer $data, UInt() $len --> N-Object )

  • $array; a Gnome::Glib::N-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.

Return value; the Gnome::Glib::N-Array.

ref

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

method ref ( N-Object $array --> N-Object )

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

Return value; The passed in Gnome::Glib::N-Array.

remove-index

Removes the element at the given index from a Gnome::Glib::N-Array. The following elements are moved down one place.

method remove-index ( N-Object $array, UInt() $index --> N-Object )

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

  • $index; the index of the element to remove.

Return value; the Gnome::Glib::N-Array.

remove-index-fast

Removes the element at the given index from a Gnome::Glib::N-Array. The last element in the array is used to fill in the space, so this function does not preserve the order of the Gnome::Glib::N-Array. But it is faster than .remove-index().

method remove-index-fast ( N-Object $array, UInt() $index --> N-Object )

  • $array; a $GArray

  • $index; the index of the element to remove.

Return value; the Gnome::Glib::N-Array.

remove-range

Removes the given number of elements starting at the given index from a Gnome::Glib::N-Array. The following elements are moved to close the gap.

method remove-range ( N-Object $array, UInt() $index, UInt() $length --> N-Object )

  • $array; a $GArray

  • $index; the index of the first element to remove.

  • $length; the number of elements to remove.

Return value; the Gnome::Glib::N-Array.

set-clear-func

Sets a function to clear an element of $array.

The $clear-func 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. $clear-func will be passed a pointer to the element to clear, rather than the element itself.

Note that in contrast with other uses of Gnome::Glib::T-types functions, $clear-func is expected to clear the contents of the array element it is given, but not free the element itself.

method set-clear-func ( N-Object $array, &clear-func )

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

  • &clear-func; a function to clear an element of $array. Tthe function must be specified with following signature; :( gpointer $data ).

set-size

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.

method set-size ( N-Object $array, UInt() $length --> N-Object )

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

  • $length; the new size of the Gnome::Glib::N-Array.

Return value; the Gnome::Glib::N-Array.

sized-new

Creates a new Gnome::Glib::N-Array with $reserved-size 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.

method sized-new ( Bool() $zero-terminated, Bool() $clear, UInt() $element-size, UInt() $reserved-size --> N-Object )

  • $zero-terminated; 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.

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

  • $reserved-size; number of elements preallocated.

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

sort

Sorts a Gnome::Glib::N-Array using $compare-func 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.

method sort ( N-Object $array, &compare-func )

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

  • &compare-func; comparison function. Tthe function must be specified with following signature; :( gpointer $a, gpointer $b -- gint )>.

sort-with-data

Like .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.

method sort-with-data ( N-Object $array, &compare-func, gpointer $user-data )

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

  • &compare-func; comparison function. Tthe function must be specified with following signature; :( gpointer $a, gpointer $b, gpointer $user-data -- gint )>.

  • $user-data; data to pass to $compare-func.

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.

If the array was created with the $zero-terminate 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:

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

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

  • $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()..

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 unref ( N-Object $array )

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