1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 arrays of pointers to any type of data, which grow automatically as new
8 <!-- ##### SECTION Long_Description ##### -->
10 Pointer Arrays are similar to Arrays but are used only for storing pointers.
14 If you remove elements from the array, elements at the end of the array
15 are moved into the space previously occupied by the removed element.
16 This means that you should not rely on the index of particular elements
17 remaining the same. You should also be careful when deleting elements while
18 iterating over the array.
22 To create a pointer array, use g_ptr_array_new().
25 To add elements to a pointer array, use g_ptr_array_add().
28 To remove elements from a pointer array, use g_ptr_array_remove(),
29 g_ptr_array_remove_index() or g_ptr_array_remove_index_fast().
32 To access an element of a pointer array, use g_ptr_array_index().
35 To set the size of a pointer array, use g_ptr_array_set_size().
38 To free a pointer array, use g_ptr_array_free().
41 <title>Using a <structname>GPtrArray</structname></title>
44 gchar *string1 = "one", *string2 = "two", *string3 = "three";
46 gparray = g_ptr_array_new (<!-- -->);
47 g_ptr_array_add (gparray, (gpointer) string1);
48 g_ptr_array_add (gparray, (gpointer) string2);
49 g_ptr_array_add (gparray, (gpointer) string3);
51 if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
52 g_print ("ERROR: got %p instead of %p\n",
53 g_ptr_array_index (gparray, 0), string1);
55 g_ptr_array_free (gparray, TRUE);
56 </programlisting></example>
58 <!-- ##### SECTION See_Also ##### -->
63 <!-- ##### SECTION Stability_Level ##### -->
66 <!-- ##### STRUCT GPtrArray ##### -->
68 Contains the public fields of a pointer array.
71 @pdata: points to the array of pointers, which may be moved when the array grows.
72 @len: number of pointers in the array.
74 <!-- ##### FUNCTION g_ptr_array_new ##### -->
76 Creates a new #GPtrArray with a reference count of 1.
79 @Returns: the new #GPtrArray.
82 <!-- ##### FUNCTION g_ptr_array_sized_new ##### -->
84 Creates a new #GPtrArray with @reserved_size pointers
85 preallocated and a reference count of 1. This avoids frequent reallocation,
86 if you are going to add many pointers to the array. Note however that the size
87 of the array is still 0.
90 @reserved_size: number of pointers preallocated.
91 @Returns: the new #GPtrArray.
94 <!-- ##### FUNCTION g_ptr_array_new_with_free_func ##### -->
103 <!-- ##### FUNCTION g_ptr_array_set_free_func ##### -->
112 <!-- ##### FUNCTION g_ptr_array_ref ##### -->
121 <!-- ##### FUNCTION g_ptr_array_unref ##### -->
129 <!-- ##### FUNCTION g_ptr_array_add ##### -->
131 Adds a pointer to the end of the pointer array.
132 The array will grow in size automatically if necessary.
135 @array: a #GPtrArray.
136 @data: the pointer to add.
139 <!-- ##### FUNCTION g_ptr_array_remove ##### -->
141 Removes the first occurrence of the given pointer from the pointer array.
142 The following elements are moved down one place.
143 If @array has a non-%NULL #GDestroyNotify function it is called for
147 It returns %TRUE if the pointer was removed, or %FALSE if the pointer
151 @array: a #GPtrArray.
152 @data: the pointer to remove.
153 @Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found
157 <!-- ##### FUNCTION g_ptr_array_remove_index ##### -->
159 Removes the pointer at the given index from the pointer array.
160 The following elements are moved down one place.
161 If @array has a non-%NULL #GDestroyNotify function it is called for
165 @array: a #GPtrArray.
166 @index_: the index of the pointer to remove.
167 @Returns: the pointer which was removed.
170 <!-- ##### FUNCTION g_ptr_array_remove_fast ##### -->
172 Removes the first occurrence of the given pointer from the pointer array.
173 The last element in the array is used to fill in the space, so this function
174 does not preserve the order of the array. But it is faster than
175 g_ptr_array_remove().
176 If @array has a non-%NULL #GDestroyNotify function it is called for
180 It returns %TRUE if the pointer was removed, or %FALSE if the pointer
184 @array: a #GPtrArray.
185 @data: the pointer to remove.
186 @Returns: %TRUE if the pointer was found in the array.
189 <!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
191 Removes the pointer at the given index from the pointer array.
192 The last element in the array is used to fill in the space, so this function
193 does not preserve the order of the array. But it is faster than
194 g_ptr_array_remove_index().
195 If @array has a non-%NULL #GDestroyNotify function it is called for
199 @array: a #GPtrArray.
200 @index_: the index of the pointer to remove.
201 @Returns: the pointer which was removed.
204 <!-- ##### FUNCTION g_ptr_array_remove_range ##### -->
206 Removes the given number of pointers starting at the given index from a
207 #GPtrArray. The following elements are moved to close the gap.
208 If @array has a non-%NULL #GDestroyNotify function it is called for
209 the removed elements.
212 @array: a @GPtrArray.
213 @index_: the index of the first pointer to remove.
214 @length: the number of pointers to remove.
218 <!-- ##### FUNCTION g_ptr_array_sort ##### -->
220 Sorts the array, using @compare_func which should be a qsort()-style comparison
221 function (returns less than zero for first arg is less than second arg,
222 zero for equal, greater than zero if irst arg is greater than second arg).
225 If two array elements compare equal, their order in the sorted array is
229 The comparison function for g_ptr_array_sort() doesn't take the pointers
230 from the array as arguments, it takes pointers to the pointers in the array.
233 @array: a #GPtrArray.
234 @compare_func: comparison function.
237 <!-- ##### FUNCTION g_ptr_array_sort_with_data ##### -->
239 Like g_ptr_array_sort(), but the comparison function has an extra user data
243 The comparison function for g_ptr_array_sort_with_data() doesn't take the
244 pointers from the array as arguments, it takes pointers to the pointers in
248 @array: a #GPtrArray.
249 @compare_func: comparison function.
250 @user_data: data to pass to @compare_func.
253 <!-- ##### FUNCTION g_ptr_array_set_size ##### -->
255 Sets the size of the array. When making the array larger, newly-added
256 elements will be set to %NULL. When making it smaller, if @array has a
257 non-%NULL #GDestroyNotify function then it will be called for the
262 @array: a #GPtrArray.
263 @length: the new length of the pointer array.
266 <!-- ##### MACRO g_ptr_array_index ##### -->
268 Returns the pointer at the given index of the pointer array.
271 @array: a #GPtrArray.
272 @index_: the index of the pointer to return.
273 @Returns: the pointer at the given index.
276 <!-- ##### FUNCTION g_ptr_array_free ##### -->
278 Frees the memory allocated for the #GPtrArray.
279 If @free_seg is %TRUE it frees the memory block holding the elements
280 as well. Pass %FALSE if you want to free the #GPtrArray wrapper but preserve
281 the underlying array for use elsewhere. If the reference count of @array
282 is greater than one, the #GPtrArray wrapper is preserved but the size of
283 @array will be set to zero.
287 If array contents point to dynamically-allocated memory, they should
288 be freed separately if @free_seg is %TRUE and no #GDestroyNotify
289 function has been set for @array.
293 @array: a #GPtrArray.
294 @free_seg: if %TRUE the actual pointer array is freed as well.
295 @Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
296 The pointer array should be freed using g_free().
299 <!-- ##### FUNCTION g_ptr_array_foreach ##### -->