GLib.PtrArray
Description: Reference for GLib.PtrArray

### Struct

# GLibPtrArray

#### Description [src]

    struct GPtrArray {
      gpointer* pdata;
      guint len;
    }

Contains the public fields of a `GPtrArray`.

###### Structure members

`pdata:` `gpointer*`

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

`len:` `guint`

  The 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_segment` 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

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

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

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