Struct

GLibPtrArray

Description

struct GPtrArray {
  gpointer* pdata;
  guint len;
}

Contains the public fields of a pointer array.

Structure members
pdata

Points to the array of pointers, which may be moved when the array grows.

len

Number of pointers in the array.

Functions

g_ptr_array_add

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

g_ptr_array_copy

Makes a full (deep) copy of a GPtrArray.

since: 2.62

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

since: 2.62

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

since: 2.62

g_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-NULL). Otherwise, FALSE is returned and index_ is undefined. If needle exists multiple times in haystack, the index of the first instance is returned.

since: 2.54

g_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-NULL). Otherwise, FALSE is returned and index_ is undefined. If needle exists multiple times in haystack, the index of the first instance is returned.

since: 2.54

g_ptr_array_foreach

Calls a function for each element of a GPtrArray. func must not add elements to or remove elements from the array.

since: 2.4

g_ptr_array_free

Frees the memory allocated for the GPtrArray. If free_seg is TRUE it frees the memory block holding the elements as well. Pass FALSE if you want to free the GPtrArray wrapper but preserve the underlying array for use elsewhere. If the reference count of array is greater than one, the GPtrArray wrapper is preserved but the size of array will be set to zero.

g_ptr_array_insert

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

since: 2.40

g_ptr_array_is_null_terminated

Gets whether the array was constructed as NULL-terminated.

since: 2.74

g_ptr_array_new

Creates a new GPtrArray with a reference count of 1.

g_ptr_array_new_from_array

Creates a new GPtrArray, copying len pointers from data, and setting the array’s reference count to 1.

since: 2.76

g_ptr_array_new_from_null_terminated_array

Creates a new GPtrArray 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.

since: 2.76

g_ptr_array_new_full

Creates a new GPtrArray 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 g_ptr_array_unref(), when g_ptr_array_free() is called with free_segment set to TRUE or when removing elements.

since: 2.30

g_ptr_array_new_null_terminated

Like g_ptr_array_new_full() but also allows to set the array to be NULL terminated. A NULL terminated pointer array has an additional NULL pointer after the last element, beyond the current length.

since: 2.74

g_ptr_array_new_take

Creates a new GPtrArray with data as pointers, len as length and a reference count of 1.

since: 2.76

g_ptr_array_new_take_null_terminated

Creates a new GPtrArray with data as pointers, computing the length of it and setting the reference count to 1.

since: 2.76

g_ptr_array_new_with_free_func

Creates a new GPtrArray with a reference count of 1 and use 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.

since: 2.22

g_ptr_array_ref

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

since: 2.22

g_ptr_array_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-NULL GDestroyNotify function it is called for the removed element.

g_ptr_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 g_ptr_array_remove(). If array has a non-NULL GDestroyNotify function it is called for the removed element.

g_ptr_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-NULL GDestroyNotify 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 GDestroyNotify implementation).

g_ptr_array_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 g_ptr_array_remove_index(). If array has a non-NULL GDestroyNotify 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 GDestroyNotify implementation).

g_ptr_array_remove_range

Removes the given number of pointers starting at the given index from a GPtrArray. The following elements are moved to close the gap. If array has a non-NULL GDestroyNotify function it is called for the removed elements.

since: 2.4

g_ptr_array_set_free_func

Sets a function for freeing each element when 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.

since: 2.22

g_ptr_array_set_size

Sets the size of the array. When making the array larger, newly-added elements will be set to NULL. When making it smaller, if array has a non-NULL GDestroyNotify function then it will be called for the removed elements.

g_ptr_array_sized_new

Creates a new GPtrArray 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.

g_ptr_array_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 first arg is greater than second arg).

g_ptr_array_sort_values

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 first arg is greater than second arg).

since: 2.76

g_ptr_array_sort_values_with_data

Like g_ptr_array_sort_values(), but the comparison function has an extra user data argument.

since: 2.76

g_ptr_array_sort_with_data

Like g_ptr_array_sort(), but the comparison function has an extra user data argument.

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

since: 2.64

g_ptr_array_steal_index

Removes the pointer at the given index from the pointer array. The following elements are moved down one place. The GDestroyNotify for array is not called on the removed element; ownership is transferred to the caller of this function.

since: 2.58

g_ptr_array_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 g_ptr_array_steal_index(). The GDestroyNotify for array is not called on the removed element; ownership is transferred to the caller of this function.

since: 2.58

g_ptr_array_unref

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

since: 2.22