Functions
g_ptr_array_new ()
GPtrArray *
g_ptr_array_new (void);
Creates a new GPtrArray with a reference count of 1.
g_ptr_array_steal ()
gpointer *
g_ptr_array_steal (GPtrArray *array,
gsize *len);
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 GDestroyNotify 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:
Returns
the element data, which should be
freed using g_free().
[transfer full]
Since: 2.64
g_ptr_array_sized_new ()
GPtrArray *
g_ptr_array_sized_new (guint reserved_size);
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_copy ()
GPtrArray *
g_ptr_array_copy (GPtrArray *array,
GCopyFunc func,
gpointer user_data);
Makes a full (deep) copy of a GPtrArray.
func
, as a GCopyFunc, takes two arguments, the data to be copied
and a user_data
pointer. On common processor architectures, it's safe to
pass NULL 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 NULL, then only the pointers (and not what they are
pointing to) are copied to the new GPtrArray.
The copy of array
will have the same GDestroyNotify for its elements as
array
.
Returns
a deep copy of the initial GPtrArray.
[transfer full]
Since: 2.62
g_ptr_array_new_full ()
GPtrArray *
g_ptr_array_new_full (guint reserved_size,
GDestroyNotify element_free_func);
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_ref ()
GPtrArray *
g_ptr_array_ref (GPtrArray *array);
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_unref ()
void
g_ptr_array_unref (GPtrArray *array);
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
g_ptr_array_add ()
void
g_ptr_array_add (GPtrArray *array,
gpointer data);
Adds a pointer to the end of the pointer array. The array will grow
in size automatically if necessary.
g_ptr_array_extend ()
void
g_ptr_array_extend (GPtrArray *array_to_extend,
GPtrArray *array,
GCopyFunc func,
gpointer user_data);
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 GCopyFunc, takes two arguments, the data to be copied
and a user_data
pointer. On common processor architectures, it's safe to
pass NULL 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 NULL, then only the pointers (and not what they are
pointing to) are copied to the new GPtrArray.
Since: 2.62
g_ptr_array_extend_and_steal ()
void
g_ptr_array_extend_and_steal (GPtrArray *array_to_extend,
GPtrArray *array);
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 g_ptr_array_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.
Since: 2.62
g_ptr_array_insert ()
void
g_ptr_array_insert (GPtrArray *array,
gint index_,
gpointer data);
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_remove ()
gboolean
g_ptr_array_remove (GPtrArray *array,
gpointer data);
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.
It returns TRUE if the pointer was removed, or FALSE if the
pointer was not found.
Returns
TRUE if the pointer is removed, FALSE if the pointer
is not found in the array
g_ptr_array_remove_index ()
gpointer
g_ptr_array_remove_index (GPtrArray *array,
guint 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).
Returns
the pointer which was removed.
[nullable]
g_ptr_array_remove_fast ()
gboolean
g_ptr_array_remove_fast (GPtrArray *array,
gpointer data);
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.
It returns TRUE if the pointer was removed, or FALSE if the
pointer was not found.
Returns
TRUE if the pointer was found in the array
g_ptr_array_remove_index_fast ()
gpointer
g_ptr_array_remove_index_fast (GPtrArray *array,
guint index_);
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).
Returns
the pointer which was removed.
[nullable]
g_ptr_array_remove_range ()
GPtrArray *
g_ptr_array_remove_range (GPtrArray *array,
guint index_,
guint length);
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_steal_index ()
gpointer
g_ptr_array_steal_index (GPtrArray *array,
guint 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.
Returns
the pointer which was removed.
[transfer full][nullable]
Since: 2.58
g_ptr_array_steal_index_fast ()
gpointer
g_ptr_array_steal_index_fast (GPtrArray *array,
guint index_);
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.
Returns
the pointer which was removed.
[transfer full][nullable]
Since: 2.58
g_ptr_array_sort ()
void
g_ptr_array_sort (GPtrArray *array,
GCompareFunc compare_func);
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 g_ptr_array_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.
g_ptr_array_sort_with_data ()
void
g_ptr_array_sort_with_data (GPtrArray *array,
GCompareDataFunc compare_func,
gpointer user_data);
Like g_ptr_array_sort(), but the comparison function has an extra
user data argument.
Note that the comparison function for g_ptr_array_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.
g_ptr_array_set_size ()
void
g_ptr_array_set_size (GPtrArray *array,
gint length);
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_index()
#define g_ptr_array_index(array,index_)
Returns the pointer at the given index of the pointer array.
This does not perform bounds checking on the given index_
,
so you are responsible for checking it against the array length.
Returns
the pointer at the given index
g_ptr_array_free ()
gpointer *
g_ptr_array_free (GPtrArray *array,
gboolean free_seg);
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.
If array contents point to dynamically-allocated memory, they should
be freed separately if free_seg
is TRUE and no GDestroyNotify
function has been set for array
.
This function is not thread-safe. If using a GPtrArray from multiple
threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref()
functions.
Returns
the pointer array if free_seg
is FALSE, otherwise NULL.
The pointer array should be freed using g_free().
g_ptr_array_foreach ()
void
g_ptr_array_foreach (GPtrArray *array,
GFunc func,
gpointer user_data);
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_find ()
gboolean
g_ptr_array_find (GPtrArray *haystack,
gconstpointer needle,
guint *index_);
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.
This does pointer comparisons only. If you want to use more complex equality
checks, such as string comparisons, use g_ptr_array_find_with_equal_func().
[skip]
Returns
TRUE if needle
is one of the elements of haystack
Since: 2.54
g_ptr_array_find_with_equal_func ()
gboolean
g_ptr_array_find_with_equal_func (GPtrArray *haystack,
gconstpointer needle,
GEqualFunc equal_func,
guint *index_);
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.
equal_func
is called with the element from the array as its first parameter,
and needle
as its second parameter. If equal_func
is NULL, pointer
equality is used.
[skip]
Returns
TRUE if needle
is one of the elements of haystack
Since: 2.54