| <!-- ##### SECTION Title ##### --> |
| Pointer Arrays |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| arrays of pointers to any type of data, which grow automatically as new |
| elements are added. |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| Pointer Arrays are similar to Arrays but are used only for storing pointers. |
| </para> |
| <note> |
| <para> |
| If you remove elements from the array, elements at the end of the array |
| are moved into the space previously occupied by the removed element. |
| This means that you should not rely on the index of particular elements |
| remaining the same. You should also be careful when deleting elements while |
| iterating over the array. |
| </para> |
| </note> |
| <para> |
| To create a pointer array, use g_ptr_array_new(). |
| </para> |
| <para> |
| To add elements to a pointer array, use g_ptr_array_add(). |
| </para> |
| <para> |
| To remove elements from a pointer array, use g_ptr_array_remove(), |
| g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). |
| </para> |
| <para> |
| To access an element of a pointer array, use g_ptr_array_index(). |
| </para> |
| <para> |
| To set the size of a pointer array, use g_ptr_array_set_size(). |
| </para> |
| <para> |
| To free a pointer array, use g_ptr_array_free(). |
| </para> |
| <example> |
| <title>Using a <structname>GPtrArray</structname></title> |
| <programlisting> |
| GPtrArray *gparray; |
| gchar *string1 = "one", *string2 = "two", *string3 = "three"; |
| |
| gparray = g_ptr_array_new (<!-- -->); |
| g_ptr_array_add (gparray, (gpointer) string1); |
| g_ptr_array_add (gparray, (gpointer) string2); |
| g_ptr_array_add (gparray, (gpointer) string3); |
| |
| if (g_ptr_array_index (gparray, 0) != (gpointer) string1) |
| g_print ("ERROR: got %p instead of %p\n", |
| g_ptr_array_index (gparray, 0), string1); |
| |
| g_ptr_array_free (gparray, TRUE); |
| </programlisting></example> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### STRUCT GPtrArray ##### --> |
| <para> |
| Contains the public fields of a pointer array. |
| </para> |
| |
| @pdata: points to the array of pointers, which may be moved when the array grows. |
| @len: number of pointers in the array. |
| |
| <!-- ##### FUNCTION g_ptr_array_new ##### --> |
| <para> |
| Creates a new #GPtrArray. |
| </para> |
| |
| @Returns: the new #GPtrArray. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_sized_new ##### --> |
| <para> |
| Creates a new #GPtrArray with @reserved_size pointers |
| preallocated. 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. |
| </para> |
| |
| @reserved_size: number of pointers preallocated. |
| @Returns: the new #GPtrArray. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_add ##### --> |
| <para> |
| Adds a pointer to the end of the pointer array. |
| The array will grow in size automatically if necessary. |
| </para> |
| |
| @array: a #GPtrArray. |
| @data: the pointer to add. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_remove ##### --> |
| <para> |
| Removes the first occurrence of the given pointer from the pointer array. |
| The following elements are moved down one place. |
| </para> |
| <para> |
| It returns %TRUE if the pointer was removed, or %FALSE if the pointer |
| was not found. |
| </para> |
| |
| @array: a #GPtrArray. |
| @data: the pointer to remove. |
| @Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found |
| in the array. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_remove_index ##### --> |
| <para> |
| Removes the pointer at the given index from the pointer array. |
| The following elements are moved down one place. |
| </para> |
| |
| @array: a #GPtrArray. |
| @index_: the index of the pointer to remove. |
| @Returns: the pointer which was removed. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_remove_fast ##### --> |
| <para> |
| 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(). |
| </para> |
| <para> |
| It returns %TRUE if the pointer was removed, or %FALSE if the pointer |
| was not found. |
| </para> |
| |
| @array: a #GPtrArray. |
| @data: the pointer to remove. |
| @Returns: %TRUE if the pointer was found in the array. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### --> |
| <para> |
| 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(). |
| </para> |
| |
| @array: a #GPtrArray. |
| @index_: the index of the pointer to remove. |
| @Returns: the pointer which was removed. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_remove_range ##### --> |
| <para> |
| Removes the given number of pointers starting at the given index from a |
| #GPtrArray. The following elements are moved to close the gap. |
| </para> |
| |
| @array: a @GPtrArray. |
| @index_: the index of the first pointer to remove. |
| @length: the number of pointers to remove. |
| @Since: 2.4 |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_sort ##### --> |
| <para> |
| 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). |
| </para> |
| <para> |
| If two array elements compare equal, their order in the sorted array is |
| undefined. |
| </para> |
| <note><para> |
| 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. |
| </para></note> |
| |
| @array: a #GPtrArray. |
| @compare_func: comparison function. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_sort_with_data ##### --> |
| <para> |
| Like g_ptr_array_sort(), but the comparison function has an extra user data |
| argument. |
| </para> |
| <note><para> |
| 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. |
| </para></note> |
| |
| @array: a #GPtrArray. |
| @compare_func: comparison function. |
| @user_data: data to pass to @compare_func. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_set_size ##### --> |
| <para> |
| Sets the size of the array, expanding it if necessary. |
| New elements are set to %NULL. |
| </para> |
| |
| @array: a #GPtrArray. |
| @length: the new length of the pointer array. |
| |
| |
| <!-- ##### MACRO g_ptr_array_index ##### --> |
| <para> |
| Returns the pointer at the given index of the pointer array. |
| </para> |
| |
| @array: a #GPtrArray. |
| @index_: the index of the pointer to return. |
| @Returns: the pointer at the given index. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_free ##### --> |
| <para> |
| Frees all of the memory allocated for the pointer array. |
| </para> |
| |
| @array: a #GPtrArray. |
| @free_seg: if %TRUE the array of pointers (@pdata) is freed. |
| @Returns: %NULL if @free_seg is %TRUE, otherwise the array of |
| pointers (@pdata) is returned. |
| |
| |
| <!-- ##### FUNCTION g_ptr_array_foreach ##### --> |
| <para> |
| |
| </para> |
| |
| @array: |
| @func: |
| @user_data: |
| |
| |