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 GArray 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 < 10000; i++)
  43     g_array_append_val (garray, i);
  44
  45   for (i = 0; i < 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
  83 </para>
  84
  85 @zero_terminated:
  86 @clear:
  87 @element_size:
  88 @reserved_size:
  89 @Returns:
  90
  91
  92 <!-- ##### MACRO g_array_append_val ##### -->
  93 <para>
  94 Adds the value on to the end of the array.
  95 The array will grow in size automatically if necessary.
  96 </para>
  97 <note>
  98 <para>
  99 g_array_append_val() is a macro which uses a reference to the value
 100 parameter @v. This means that you cannot use it with literal values
 101 such as "27". You must use variables.
 102 </para>
 103 </note>
 104
 105 @a: a #GArray.
 106 @v: the value to append to the #GArray.
 107 @Returns: the #GArray.
 108
 109
 110 <!-- ##### FUNCTION g_array_append_vals ##### -->
 111 <para>
 112 Adds @len elements onto the end of the array.
 113 </para>
 114
 115 @array: a #GArray.
 116 @data: a pointer to the elements to append to the end of the array.
 117 @len: the number of elements to append.
 118 @Returns: the #GArray.
 119
 120
 121 <!-- ##### MACRO g_array_prepend_val ##### -->
 122 <para>
 123 Adds the value on to the start of the array.
 124 The array will grow in size automatically if necessary.
 125 </para>
 126 <para>
 127 This operation is slower than g_array_append_val() since the existing elements
 128 in the array have to be moved to make space for the new element.
 129 </para>
 130 <note>
 131 <para>
 132 g_array_prepend_val() is a macro which uses a reference to the value
 133 parameter @v. This means that you cannot use it with literal values
 134 such as "27". You must use variables.
 135 </para>
 136 </note>
 137
 138 @a: a #GArray.
 139 @v: the value to prepend to the #GArray.
 140 @Returns: the #GArray.
 141
 142
 143 <!-- ##### FUNCTION g_array_prepend_vals ##### -->
 144 <para>
 145 Adds @len elements onto the start of the array.
 146 </para>
 147 <para>
 148 This operation is slower than g_array_append_vals() since the existing elements
 149 in the array have to be moved to make space for the new elements.
 150 </para>
 151
 152 @array: a #GArray.
 153 @data: a pointer to the elements to prepend to the start of the array.
 154 @len: the number of elements to prepend.
 155 @Returns: the #GArray.
 156
 157
 158 <!-- ##### MACRO g_array_insert_val ##### -->
 159 <para>
 160 Inserts an element into an array at the given index.
 161 </para>
 162 <note>
 163 <para>
 164 g_array_insert_val() is a macro which uses a reference to the value
 165 parameter @v. This means that you cannot use it with literal values
 166 such as "27". You must use variables.
 167 </para>
 168 </note>
 169
 170 @a: a #GArray.
 171 @i: the index to place the element at.
 172 @v: the value to insert into the array.
 173 @Returns: the #GArray.
 174
 175
 176 <!-- ##### FUNCTION g_array_insert_vals ##### -->
 177 <para>
 178 Inserts @len elements into a #GArray at the given index.
 179 </para>
 180
 181 @array: a #GArray.
 182 @index: the index to place the elements at.
 183 @data: a pointer to the elements to insert.
 184 @len: the number of elements to insert.
 185 @Returns: the #GArray.
 186
 187
 188 <!-- ##### FUNCTION g_array_remove_index ##### -->
 189 <para>
 190 Removes the element at the given index from a #GArray.
 191 The following elements are moved down one place.
 192 </para>
 193
 194 @array: a #GArray.
 195 @index: the index of the element to remove.
 196 @Returns: the #GArray.
 197
 198
 199 <!-- ##### FUNCTION g_array_remove_index_fast ##### -->
 200 <para>
 201 Removes the element at the given index from a #GArray.
 202 The last element in the array is used to fill in the space, so this function
 203 does not preserve the order of the #GArray. But it is faster than
 204 g_array_remove_index().
 205 </para>
 206
 207 @array: a @GArray.
 208 @index: the index of the element to remove.
 209 @Returns: the #GArray.
 210
 211
 212 <!-- ##### FUNCTION g_array_sort ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @array:
 218 @compare_func:
 219
 220
 221 <!-- ##### FUNCTION g_array_sort_with_data ##### -->
 222 <para>
 223
 224 </para>
 225
 226 @array:
 227 @compare_func:
 228 @user_data:
 229
 230
 231 <!-- ##### MACRO g_array_index ##### -->
 232 <para>
 233 Returns the element of a #GArray at the given index.
 234 The return value is cast to the given type.
 235
 236 <example>
 237 <title>Getting a pointer to an element in a GArray.</title>
 238 <programlisting>
 239   EDayViewEvent *event;
 240
 241   /* This gets a pointer to the 3rd element in the array of EDayViewEvent
 242      structs. */
 243   event = &amp;g_array_index (events, EDayViewEvent, 3);
 244 </programlisting>
 245 </example>
 246 </para>
 247
 248 @a: a #GArray.
 249 @t: the type of the elements.
 250 @i: the index of the element to return.
 251 @Returns: the element of the #GArray at the index given by @i.
 252
 253
 254 <!-- ##### FUNCTION g_array_set_size ##### -->
 255 <para>
 256 Sets the size of the array, expanding it if necessary.
 257 If the array was created with clear set to TRUE, the new elements are set to 0.
 258 </para>
 259
 260 @array: a #GArray.
 261 @length: the new size of the #GArray.
 262 @Returns: the #GArray.
 263
 264
 265 <!-- ##### FUNCTION g_array_free ##### -->
 266 <para>
 267 Frees the memory allocated for the #GArray.
 268 If free_segment is TRUE it frees the actual element data as well.
 269 </para>
 270
 271 @array: a #GArray.
 272 @free_segment: if TRUE the actual element data is freed as well.
 273 @Returns:
 274
 275