docs/reference/glib/tmpl/arrays.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Arrays
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 arrays of arbitrary elements which grow automatically as elements are added.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Arrays are similar to standard C arrays, except that they grow automatically
  10 as elements are added.
  11 </para>
  12 <para>
  13 Array elements can be of any size (though all elements of one array are the
  14 same size), and the array can be automatically cleared to '0's and
  15 zero-terminated.
  16 </para>
  17 <para>
  18 To create a new array use g_array_new().
  19 </para>
  20 <para>
  21 To add elements to an array, use g_array_append_val(), g_array_append_vals(),
  22 g_array_prepend_val(), and g_array_prepend_vals().
  23 </para>
  24 <para>
  25 To access an element of an array, use g_array_index().
  26 </para>
  27 <para>
  28 To set the size of an array, use g_array_set_size().
  29 </para>
  30 <para>
  31 To free an array, use g_array_free().
  32 </para>
  33 <example>
  34 <title>Using a <structname>GArray</structname> to store gint values.</title>
  35 <programlisting>
  36   GArray *garray;
  37   gint i;
  38
  39   /* We create a new array to store gint values.
  40      We don't want it zero-terminated or cleared to 0's. */
  41   garray = g_array_new (FALSE, FALSE, sizeof (gint));
  42   for (i = 0; i &lt; 10000; i++)
  43     g_array_append_val (garray, i);
  44
  45   for (i = 0; i &lt; 10000; i++)
  46     if (g_array_index (garray, gint, i) != i)
  47       g_print ("ERROR: got %d instead of %d\n",
  48                g_array_index (garray, gint, i), i);
  49
  50   g_array_free (garray, TRUE);
  51 </programlisting></example>
  52
  53 <!-- ##### SECTION See_Also ##### -->
  54 <para>
  55
  56 </para>
  57
  58 <!-- ##### STRUCT GArray ##### -->
  59 <para>
  60 Contains the public fields of an <link linkend="glib-arrays">Array</link>.
  61 </para>
  62
  63 @data: a pointer to the element data. The data may be moved as elements are
  64 added to the #GArray.
  65 @len: the number of elements in the #GArray.
  66
  67 <!-- ##### FUNCTION g_array_new ##### -->
  68 <para>
  69 Creates a new #GArray.
  70 </para>
  71
  72 @zero_terminated: %TRUE if the array should have an extra element at the end
  73 which is set to 0.
  74 @clear_: %TRUE if #GArray elements should be automatically cleared to 0
  75 when they are allocated.
  76 @element_size: the size of each element in bytes.
  77 @Returns: the new #GArray.
  78
  79
  80 <!-- ##### FUNCTION g_array_sized_new ##### -->
  81 <para>
  82 Creates a new #GArray with @reserved_size elements
  83 preallocated. This avoids frequent reallocation, if you are going to
  84 add many elements to the array. Note however that the size of the
  85 array is still 0.
  86 </para>
  87
  88 @zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared.
  89 @clear_: %TRUE if all bits in the array should be cleared to 0 on allocation.
  90 @element_size: size of each element in the array.
  91 @reserved_size: number of elements preallocated.
  92 @Returns: the new #GArray.
  93
  94
  95 <!-- ##### MACRO g_array_append_val ##### -->
  96 <para>
  97 Adds the value on to the end of the array.
  98 The array will grow in size automatically if necessary.
  99 </para>
 100 <note>
 101 <para>
 102 g_array_append_val() is a macro which uses a reference to the value
 103 parameter @v. This means that you cannot use it with literal values
 104 such as "27". You must use variables.
 105 </para>
 106 </note>
 107
 108 @a: a #GArray.
 109 @v: the value to append to the #GArray.
 110 @Returns: the #GArray.
 111
 112
 113 <!-- ##### FUNCTION g_array_append_vals ##### -->
 114 <para>
 115 Adds @len elements onto the end of the array.
 116 </para>
 117
 118 @array: a #GArray.
 119 @data: a pointer to the elements to append to the end of the array.
 120 @len: the number of elements to append.
 121 @Returns: the #GArray.
 122
 123
 124 <!-- ##### MACRO g_array_prepend_val ##### -->
 125 <para>
 126 Adds the value on to the start of the array.
 127 The array will grow in size automatically if necessary.
 128 </para>
 129 <para>
 130 This operation is slower than g_array_append_val() since the existing elements
 131 in the array have to be moved to make space for the new element.
 132 </para>
 133 <note>
 134 <para>
 135 g_array_prepend_val() is a macro which uses a reference to the value
 136 parameter @v. This means that you cannot use it with literal values
 137 such as "27". You must use variables.
 138 </para>
 139 </note>
 140
 141 @a: a #GArray.
 142 @v: the value to prepend to the #GArray.
 143 @Returns: the #GArray.
 144
 145
 146 <!-- ##### FUNCTION g_array_prepend_vals ##### -->
 147 <para>
 148 Adds @len elements onto the start of the array.
 149 </para>
 150 <para>
 151 This operation is slower than g_array_append_vals() since the existing elements
 152 in the array have to be moved to make space for the new elements.
 153 </para>
 154
 155 @array: a #GArray.
 156 @data: a pointer to the elements to prepend to the start of the array.
 157 @len: the number of elements to prepend.
 158 @Returns: the #GArray.
 159
 160
 161 <!-- ##### MACRO g_array_insert_val ##### -->
 162 <para>
 163 Inserts an element into an array at the given index.
 164 </para>
 165 <note>
 166 <para>
 167 g_array_insert_val() is a macro which uses a reference to the value
 168 parameter @v. This means that you cannot use it with literal values
 169 such as "27". You must use variables.
 170 </para>
 171 </note>
 172
 173 @a: a #GArray.
 174 @i: the index to place the element at.
 175 @v: the value to insert into the array.
 176 @Returns: the #GArray.
 177
 178
 179 <!-- ##### FUNCTION g_array_insert_vals ##### -->
 180 <para>
 181 Inserts @len elements into a #GArray at the given index.
 182 </para>
 183
 184 @array: a #GArray.
 185 @index_: the index to place the elements at.
 186 @data: a pointer to the elements to insert.
 187 @len: the number of elements to insert.
 188 @Returns: the #GArray.
 189
 190
 191 <!-- ##### FUNCTION g_array_remove_index ##### -->
 192 <para>
 193 Removes the element at the given index from a #GArray.
 194 The following elements are moved down one place.
 195 </para>
 196
 197 @array: a #GArray.
 198 @index_: the index of the element to remove.
 199 @Returns: the #GArray.
 200
 201
 202 <!-- ##### FUNCTION g_array_remove_index_fast ##### -->
 203 <para>
 204 Removes the element at the given index from a #GArray.
 205 The last element in the array is used to fill in the space, so this function
 206 does not preserve the order of the #GArray. But it is faster than
 207 g_array_remove_index().
 208 </para>
 209
 210 @array: a @GArray.
 211 @index_: the index of the element to remove.
 212 @Returns: the #GArray.
 213
 214
 215 <!-- ##### FUNCTION g_array_sort ##### -->
 216 <para>
 217 Sorts a #GArray using @compare_func which should be a <function>qsort()</function>-style comparison
 218 function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
 219 first arg is greater than second arg).
 220 </para>
 221
 222 @array: a #GArray.
 223 @compare_func: comparison function.
 224
 225
 226 <!-- ##### FUNCTION g_array_sort_with_data ##### -->
 227 <para>
 228 Like g_array_sort(), but the comparison function receives a user data
 229 argument.
 230 </para>
 231
 232 @array: a #GArray.
 233 @compare_func: comparison function.
 234 @user_data: data to pass to @compare_func.
 235
 236
 237 <!-- ##### MACRO g_array_index ##### -->
 238 <para>
 239 Returns the element of a #GArray at the given index.
 240 The return value is cast to the given type.
 241
 242 <example>
 243 <title>Getting a pointer to an element in a <structname>GArray</structname>.</title>
 244 <programlisting>
 245   EDayViewEvent *event;
 246
 247   /* This gets a pointer to the 3rd element in the array of EDayViewEvent
 248      structs. */
 249   event = &amp;g_array_index (events, EDayViewEvent, 3);
 250 </programlisting>
 251 </example>
 252 </para>
 253
 254 @a: a #GArray.
 255 @t: the type of the elements.
 256 @i: the index of the element to return.
 257 @Returns: the element of the #GArray at the index given by @i.
 258
 259
 260 <!-- ##### FUNCTION g_array_set_size ##### -->
 261 <para>
 262 Sets the size of the array, expanding it if necessary.
 263 If the array was created with @clear_ set to %TRUE, the new elements are set to 0.
 264 </para>
 265
 266 @array: a #GArray.
 267 @length: the new size of the #GArray.
 268 @Returns: the #GArray.
 269
 270
 271 <!-- ##### FUNCTION g_array_free ##### -->
 272 <para>
 273 Frees the memory allocated for the #GArray.
 274 If @free_segment is %TRUE it frees the actual element data as well.
 275 </para>
 276
 277 @array: a #GArray.
 278 @free_segment: if %TRUE the actual element data is freed as well.
 279 @Returns:
 280
 281