N-Array
#------------------------------------------------------------------------------- #--[Class Description]---------------------------------------------------------- #-------------------------------------------------------------------------------
Gnome::Glib::N-Array
Description
Contains the public fields of a GArray.
#------------------------------------------------------------------------------- #--[Class Initialization]------------------------------------------------------- #-------------------------------------------------------------------------------
Class initialization
new
:native-object
Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.
multi method new ( N-Object :$native-object! )
#------------------------------------------------------------------------------- #--[Functions]------------------------------------------------------------------ #-------------------------------------------------------------------------------
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.
#-------------------------------------------------------------------------------
binary-search
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
Truethe 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;
Trueif the array should have an extra element at the end which is set to 0.$clear;
Trueif 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;
Trueif the array should have an extra element at the end with all bits cleared.$clear;
Trueif 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