1<!-- ##### SECTION Title ##### --> 2Pointer Arrays 3 4<!-- ##### SECTION Short_Description ##### --> 5arrays of pointers to any type of data, which grow automatically as new 6elements are added 7 8<!-- ##### SECTION Long_Description ##### --> 9<para> 10Pointer Arrays are similar to Arrays but are used only for storing pointers. 11</para> 12<note> 13<para> 14If you remove elements from the array, elements at the end of the array 15are moved into the space previously occupied by the removed element. 16This means that you should not rely on the index of particular elements 17remaining the same. You should also be careful when deleting elements while 18iterating over the array. 19</para> 20</note> 21<para> 22To create a pointer array, use g_ptr_array_new(). 23</para> 24<para> 25To add elements to a pointer array, use g_ptr_array_add(). 26</para> 27<para> 28To remove elements from a pointer array, use g_ptr_array_remove(), 29g_ptr_array_remove_index() or g_ptr_array_remove_index_fast(). 30</para> 31<para> 32To access an element of a pointer array, use g_ptr_array_index(). 33</para> 34<para> 35To set the size of a pointer array, use g_ptr_array_set_size(). 36</para> 37<para> 38To free a pointer array, use g_ptr_array_free(). 39</para> 40<example> 41<title>Using a <structname>GPtrArray</structname></title> 42<programlisting> 43 GPtrArray *gparray; 44 gchar *string1 = "one", *string2 = "two", *string3 = "three"; 45 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); 50 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); 54 55 g_ptr_array_free (gparray, TRUE); 56</programlisting></example> 57 58<!-- ##### SECTION See_Also ##### --> 59<para> 60 61</para> 62 63<!-- ##### SECTION Stability_Level ##### --> 64 65 66<!-- ##### STRUCT GPtrArray ##### --> 67<para> 68Contains the public fields of a pointer array. 69</para> 70 71@pdata: points to the array of pointers, which may be moved when the array grows. 72@len: number of pointers in the array. 73 74<!-- ##### FUNCTION g_ptr_array_new ##### --> 75<para> 76Creates a new #GPtrArray. 77</para> 78 79@Returns: the new #GPtrArray. 80 81 82<!-- ##### FUNCTION g_ptr_array_sized_new ##### --> 83<para> 84Creates a new #GPtrArray with @reserved_size pointers 85preallocated. This avoids frequent reallocation, if you are going to 86add many pointers to the array. Note however that the size of the 87array is still 0. 88</para> 89 90@reserved_size: number of pointers preallocated. 91@Returns: the new #GPtrArray. 92 93 94<!-- ##### FUNCTION g_ptr_array_add ##### --> 95<para> 96Adds a pointer to the end of the pointer array. 97The array will grow in size automatically if necessary. 98</para> 99 100@array: a #GPtrArray. 101@data: the pointer to add. 102 103 104<!-- ##### FUNCTION g_ptr_array_remove ##### --> 105<para> 106Removes the first occurrence of the given pointer from the pointer array. 107The following elements are moved down one place. 108</para> 109<para> 110It returns %TRUE if the pointer was removed, or %FALSE if the pointer 111was not found. 112</para> 113 114@array: a #GPtrArray. 115@data: the pointer to remove. 116@Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found 117in the array. 118 119 120<!-- ##### FUNCTION g_ptr_array_remove_index ##### --> 121<para> 122Removes the pointer at the given index from the pointer array. 123The following elements are moved down one place. 124</para> 125 126@array: a #GPtrArray. 127@index_: the index of the pointer to remove. 128@Returns: the pointer which was removed. 129 130 131<!-- ##### FUNCTION g_ptr_array_remove_fast ##### --> 132<para> 133Removes the first occurrence of the given pointer from the pointer array. 134The last element in the array is used to fill in the space, so this function 135does not preserve the order of the array. But it is faster than 136g_ptr_array_remove(). 137</para> 138<para> 139It returns %TRUE if the pointer was removed, or %FALSE if the pointer 140was not found. 141</para> 142 143@array: a #GPtrArray. 144@data: the pointer to remove. 145@Returns: %TRUE if the pointer was found in the array. 146 147 148<!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### --> 149<para> 150Removes the pointer at the given index from the pointer array. 151The last element in the array is used to fill in the space, so this function 152does not preserve the order of the array. But it is faster than 153g_ptr_array_remove_index(). 154</para> 155 156@array: a #GPtrArray. 157@index_: the index of the pointer to remove. 158@Returns: the pointer which was removed. 159 160 161<!-- ##### FUNCTION g_ptr_array_remove_range ##### --> 162<para> 163Removes the given number of pointers starting at the given index from a 164#GPtrArray. The following elements are moved to close the gap. 165</para> 166 167@array: a @GPtrArray. 168@index_: the index of the first pointer to remove. 169@length: the number of pointers to remove. 170@Since: 2.4 171 172 173<!-- ##### FUNCTION g_ptr_array_sort ##### --> 174<para> 175Sorts the array, using @compare_func which should be a qsort()-style comparison 176function (returns less than zero for first arg is less than second arg, 177zero for equal, greater than zero if irst arg is greater than second arg). 178</para> 179<para> 180If two array elements compare equal, their order in the sorted array is 181undefined. 182</para> 183<note><para> 184The comparison function for g_ptr_array_sort() doesn't take the pointers 185from the array as arguments, it takes pointers to the pointers in the array. 186</para></note> 187 188@array: a #GPtrArray. 189@compare_func: comparison function. 190 191 192<!-- ##### FUNCTION g_ptr_array_sort_with_data ##### --> 193<para> 194Like g_ptr_array_sort(), but the comparison function has an extra user data 195argument. 196</para> 197<note><para> 198The comparison function for g_ptr_array_sort_with_data() doesn't take the 199pointers from the array as arguments, it takes pointers to the pointers in 200the array. 201</para></note> 202 203@array: a #GPtrArray. 204@compare_func: comparison function. 205@user_data: data to pass to @compare_func. 206 207 208<!-- ##### FUNCTION g_ptr_array_set_size ##### --> 209<para> 210Sets the size of the array, expanding it if necessary. 211New elements are set to %NULL. 212</para> 213 214@array: a #GPtrArray. 215@length: the new length of the pointer array. 216 217 218<!-- ##### MACRO g_ptr_array_index ##### --> 219<para> 220Returns the pointer at the given index of the pointer array. 221</para> 222 223@array: a #GPtrArray. 224@index_: the index of the pointer to return. 225@Returns: the pointer at the given index. 226 227 228<!-- ##### FUNCTION g_ptr_array_free ##### --> 229<para> 230Frees the memory allocated for the #GPtrArray. 231If @free_segment is %TRUE it frees the memory block holding the elements 232as well. Pass %FALSE if you want to free the #GPtrArray wrapper but preserve 233the underlying array for use elsewhere. 234</para> 235<note> 236<para> 237If array contents point to dynamically-allocated memory, they should be freed 238separately. 239</para> 240</note> 241 242@array: a #GPtrArray. 243@free_seg: if %TRUE the actual pointer array is freed as well. 244@Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. 245 The pointer array should be freed using g_free(). 246 247 248<!-- ##### FUNCTION g_ptr_array_foreach ##### --> 249<para> 250 251</para> 252 253@array: 254@func: 255@user_data: 256 257 258