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