docs/reference/glib/tmpl/arrays_pointer.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Pointer Arrays
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 arrays of pointers to any type of data, which grow automatically as new
   6 elements are added
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 Pointer Arrays are similar to Arrays but are used only for storing pointers.
  11 </para>
  12 <note>
  13 <para>
  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.
  19 </para>
  20 </note>
  21 <para>
  22 To create a pointer array, use g_ptr_array_new().
  23 </para>
  24 <para>
  25 To add elements to a pointer array, use g_ptr_array_add().
  26 </para>
  27 <para>
  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().
  30 </para>
  31 <para>
  32 To access an element of a pointer array, use g_ptr_array_index().
  33 </para>
  34 <para>
  35 To set the size of a pointer array, use g_ptr_array_set_size().
  36 </para>
  37 <para>
  38 To 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 &percnt;p instead of &percnt;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>
  68 Contains 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>
  76 Creates a new #GPtrArray with a reference count of 1.
  77 </para>
  78
  79 @Returns: the new #GPtrArray.
  80
  81
  82 <!-- ##### FUNCTION g_ptr_array_sized_new ##### -->
  83 <para>
  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.
  88 </para>
  89
  90 @reserved_size: number of pointers preallocated.
  91 @Returns: the new #GPtrArray.
  92
  93
  94 <!-- ##### FUNCTION g_ptr_array_new_with_free_func ##### -->
  95 <para>
  96
  97 </para>
  98
  99 @element_free_func:
 100 @Returns:
 101
 102
 103 <!-- ##### FUNCTION g_ptr_array_set_free_func ##### -->
 104 <para>
 105
 106 </para>
 107
 108 @array:
 109 @element_free_func:
 110
 111
 112 <!-- ##### FUNCTION g_ptr_array_ref ##### -->
 113 <para>
 114
 115 </para>
 116
 117 @array:
 118 @Returns:
 119
 120
 121 <!-- ##### FUNCTION g_ptr_array_unref ##### -->
 122 <para>
 123
 124 </para>
 125
 126 @array:
 127
 128
 129 <!-- ##### FUNCTION g_ptr_array_add ##### -->
 130 <para>
 131 Adds a pointer to the end of the pointer array.
 132 The array will grow in size automatically if necessary.
 133 </para>
 134
 135 @array: a #GPtrArray.
 136 @data: the pointer to add.
 137
 138
 139 <!-- ##### FUNCTION g_ptr_array_remove ##### -->
 140 <para>
 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
 144 the removed element.
 145 </para>
 146 <para>
 147 It returns %TRUE if the pointer was removed, or %FALSE if the pointer
 148 was not found.
 149 </para>
 150
 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
 154 in the array.
 155
 156
 157 <!-- ##### FUNCTION g_ptr_array_remove_index ##### -->
 158 <para>
 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
 162 the removed element.
 163 </para>
 164
 165 @array: a #GPtrArray.
 166 @index_: the index of the pointer to remove.
 167 @Returns: the pointer which was removed.
 168
 169
 170 <!-- ##### FUNCTION g_ptr_array_remove_fast ##### -->
 171 <para>
 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
 177 the removed element.
 178 </para>
 179 <para>
 180 It returns %TRUE if the pointer was removed, or %FALSE if the pointer
 181 was not found.
 182 </para>
 183
 184 @array: a #GPtrArray.
 185 @data: the pointer to remove.
 186 @Returns: %TRUE if the pointer was found in the array.
 187
 188
 189 <!-- ##### FUNCTION g_ptr_array_remove_index_fast ##### -->
 190 <para>
 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
 196 the removed element.
 197 </para>
 198
 199 @array: a #GPtrArray.
 200 @index_: the index of the pointer to remove.
 201 @Returns: the pointer which was removed.
 202
 203
 204 <!-- ##### FUNCTION g_ptr_array_remove_range ##### -->
 205 <para>
 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.
 210 </para>
 211
 212 @array: a @GPtrArray.
 213 @index_: the index of the first pointer to remove.
 214 @length: the number of pointers to remove.
 215 @Since: 2.4
 216
 217
 218 <!-- ##### FUNCTION g_ptr_array_sort ##### -->
 219 <para>
 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).
 223 </para>
 224 <para>
 225 If two array elements compare equal, their order in the sorted array is
 226 undefined.
 227 </para>
 228 <note><para>
 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.
 231 </para></note>
 232
 233 @array: a #GPtrArray.
 234 @compare_func: comparison function.
 235
 236
 237 <!-- ##### FUNCTION g_ptr_array_sort_with_data ##### -->
 238 <para>
 239 Like g_ptr_array_sort(), but the comparison function has an extra user data
 240 argument.
 241 </para>
 242 <note><para>
 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
 245 the array.
 246 </para></note>
 247
 248 @array: a #GPtrArray.
 249 @compare_func: comparison function.
 250 @user_data: data to pass to @compare_func.
 251
 252
 253 <!-- ##### FUNCTION g_ptr_array_set_size ##### -->
 254 <para>
 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
 258 removed elements.
 259
 260 </para>
 261
 262 @array: a #GPtrArray.
 263 @length: the new length of the pointer array.
 264
 265
 266 <!-- ##### MACRO g_ptr_array_index ##### -->
 267 <para>
 268 Returns the pointer at the given index of the pointer array.
 269 </para>
 270
 271 @array: a #GPtrArray.
 272 @index_: the index of the pointer to return.
 273 @Returns: the pointer at the given index.
 274
 275
 276 <!-- ##### FUNCTION g_ptr_array_free ##### -->
 277 <para>
 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.
 284 </para>
 285 <note>
 286 <para>
 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.
 290 </para>
 291 </note>
 292
 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().
 297
 298
 299 <!-- ##### FUNCTION g_ptr_array_foreach ##### -->
 300 <para>
 301
 302 </para>
 303
 304 @array:
 305 @func:
 306 @user_data:
 307
 308