#------------------------------------------------------------------------------- #--[Class Description]---------------------------------------------------------- #-------------------------------------------------------------------------------

Gnome::Glib::N-PtrArray

Description

Contains the public fields of a pointer array.

#------------------------------------------------------------------------------- #--[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

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

add

Adds a pointer to the end of the pointer array. The array will grow in size automatically if necessary.

method add ( N-Object $array, gpointer $data )

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

• $data; the pointer to add.

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

copy

Makes a full (deep) copy of a Gnome::Glib::N-PtrArray. $func, as a Gnome::Glib::T-types, takes two arguments, the data to be copied and a $user-data pointer. On common processor architectures, it's safe to pass undefined as $user-data if the copy function takes only one argument. You may get compiler warnings from this though if compiling with GCC’s -Wcast-function-type warning.

If $func is undefined, then only the pointers (and not what they are pointing to) are copied to the new Gnome::Glib::N-PtrArray.

The copy of $array will have the same Gnome::Glib::T-types for its elements as $array.

method copy ( N-Object $array, &func, gpointer $user-data --> N-Object )

• $array; Gnome::Glib::N-PtrArray to duplicate

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

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

Return value; a deep copy of the initial Gnome::Glib::N-PtrArray..

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

extend

Adds all pointers of $array to the end of the array $array-to-extend. The array will grow in size automatically if needed. $array-to-extend is modified in-place. $func, as a Gnome::Glib::T-types, takes two arguments, the data to be copied and a $user-data pointer. On common processor architectures, it's safe to pass undefined as $user-data if the copy function takes only one argument. You may get compiler warnings from this though if compiling with GCC’s -Wcast-function-type warning.

If $func is undefined, then only the pointers (and not what they are pointing to) are copied to the new Gnome::Glib::N-PtrArray.

method extend ( N-Object $array-to-extend, N-Object $array, &func, gpointer $user-data )

• $array-to-extend; a Gnome::Glib::N-PtrArray.

• $array; a Gnome::Glib::N-PtrArray to add to the end of $array-to-extend.

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

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

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

extend-and-steal

Adds all the pointers in $array to the end of $array-to-extend, transferring ownership of each element from $array to $array-to-extend and modifying $array-to-extend in-place. $array is then freed.

As with .free(), $array will be destroyed if its reference count is 1. If its reference count is higher, it will be decremented and the length of $array set to zero.

method extend-and-steal ( N-Object $array-to-extend, N-Object $array )

• $array-to-extend; a Gnome::Glib::N-PtrArray.

• $array; (transfer ownership: container) a Gnome::Glib::N-PtrArray to add to the end of $array-to-extend.

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

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 .find-with-equal-func().

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

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

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

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

foreach

Calls a function for each element of a Gnome::Glib::N-PtrArray. $func must not add elements to or remove elements from the array.

method foreach ( N-Object $array, &func, gpointer $user-data )

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

• &func; the function to call for each array element. Tthe function must be specified with following signature; :( gpointer $data, gpointer $user-data ).

• $user-data; user data to pass to the function.

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

free

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

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

method free ( N-Object $array, Bool() $free-seg --> Array )

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

• $free-seg; if True the actual pointer array is freed as well.

Return value; the pointer array if $free-seg is False, otherwise undefined. The pointer array should be freed using g_free()..

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

insert

Inserts an element into the pointer array at the given index. The array will grow in size automatically if necessary.

method insert ( N-Object $array, Int() $index, gpointer $data )

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

• $index; the index to place the new element at, or -1 to append.

• $data; the pointer to add..

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

new

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

method new (--> N-Object )

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

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

new-full

Creates a new Gnome::Glib::N-PtrArray with $reserved-size pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0. It also set $element-free-func for freeing each element when the array is destroyed either via .unref(), when .free() is called with $free-segment set to True or when removing elements.

method new-full ( UInt() $reserved-size, &element-free-func --> N-Object )

• $reserved-size; number of pointers preallocated.

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

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

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

new-with-free-func

Creates a new Gnome::Glib::N-PtrArray with a reference count of 1 and use $element-free-func for freeing each element when the array is destroyed either via .unref(), when .free() is called with $free-segment set to True or when removing elements.

method new-with-free-func ( &element-free-func --> N-Object )

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

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

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

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-PtrArray

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

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

remove

Removes the first occurrence of the given pointer from the pointer array. The following elements are moved down one place. If $array has a non-undefined Gnome::Glib::T-types function it is called for the removed element.

It returns True if the pointer was removed, or False if the pointer was not found.

method remove ( N-Object $array, gpointer $data --> Bool )

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

• $data; the pointer to remove.

Return value; True if the pointer is removed, False if the pointer is not found in the array.

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

remove-fast

Removes the first occurrence of the given pointer from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than .remove(). If $array has a non-undefined Gnome::Glib::T-types function it is called for the removed element.

It returns True if the pointer was removed, or False if the pointer was not found.

method remove-fast ( N-Object $array, gpointer $data --> Bool )

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

• $data; the pointer to remove.

Return value; True if the pointer was found in the array.

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

remove-index

Removes the pointer at the given index from the pointer array. The following elements are moved down one place. If $array has a non-undefined Gnome::Glib::T-types function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the Gnome::Glib::T-types implementation).

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

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

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

Return value; the pointer which was removed.

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

remove-index-fast

Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than .remove-index(). If $array has a non-undefined Gnome::Glib::T-types function it is called for the removed element. If so, the return value from this function will potentially point to freed memory (depending on the Gnome::Glib::T-types implementation).

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

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

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

Return value; the pointer which was removed.

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

remove-range

Removes the given number of pointers starting at the given index from a Gnome::Glib::N-PtrArray. The following elements are moved to close the gap. If $array has a non-undefined Gnome::Glib::T-types function it is called for the removed elements.

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

• $array; a $GPtrArray

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

• $length; the number of pointers to remove.

Return value; the $array.

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

set-free-func

Sets a function for freeing each element when $array is destroyed either via .unref(), when .free() is called with $free-segment set to True or when removing elements.

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

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

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

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

set-size

Sets the size of the array. When making the array larger, newly-added elements will be set to undefined. When making it smaller, if $array has a non-undefined Gnome::Glib::T-types function then it will be called for the removed elements.

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

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

• $length; the new length of the pointer array.

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

sized-new

Creates a new Gnome::Glib::N-PtrArray with $reserved-size pointers preallocated and a reference count of 1. This avoids frequent reallocation, if you are going to add many pointers to the array. Note however that the size of the array is still 0.

method sized-new ( UInt() $reserved-size --> N-Object )

• $reserved-size; number of pointers preallocated.

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

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

sort

Sorts the 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 than zero if irst arg is greater than second arg).

Note that the comparison function for .sort() doesn't take the pointers from the array as arguments, it takes pointers to the pointers in the array. Here is a full example of usage:

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

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

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

• &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 has an extra user data argument.

Note that the comparison function for .sort-with-data() doesn't take the pointers from the array as arguments, it takes pointers to the pointers in the array. Here is a full example of use:

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

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

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

• &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.

Even if set, the Gnome::Glib::T-types function will never be called on the current contents of the array and the caller is responsible for freeing the array elements.

An example of use:

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

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

• $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(). This may be undefined if the array doesn’t have any elements (i.e. if *len is zero)..

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

steal-index

Removes the pointer at the given index from the pointer array. The following elements are moved down one place. The Gnome::Glib::T-types for $array is *not* called on the removed element; ownership is transferred to the caller of this function.

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

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

• $index; the index of the pointer to steal.

Return value; the pointer which was removed.

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

steal-index-fast

Removes the pointer at the given index from the pointer array. The last element in the array is used to fill in the space, so this function does not preserve the order of the array. But it is faster than .steal-index(). The Gnome::Glib::T-types for $array is *not* called on the removed element; ownership is transferred to the caller of this function.

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

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

• $index; the index of the pointer to steal.

Return value; the pointer which was removed.

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

unref

Atomically decrements the reference count of $array by one. If the reference count drops to 0, the effect is the same as calling .free() with $free-segment set to True. This function is thread-safe and may be called from any thread.

method unref ( N-Object $array )

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