<!-- ##### SECTION Title ##### --> Arrays <!-- ##### SECTION Short_Description ##### --> arrays of arbitrary elements which grow automatically as elements are added. <!-- ##### SECTION Long_Description ##### --> <para> Arrays are similar to standard C arrays, except that they grow automatically as elements are added. </para> <para> Array elements can be of any size (though all elements of one array are the same size), and the array can be automatically cleared to '0's and zero-terminated. </para> <para> To create a new array use g_array_new(). </para> <para> To add elements to an array, use g_array_append_val(), g_array_append_vals(), g_array_prepend_val(), and g_array_prepend_vals(). </para> <para> To access an element of an array, use g_array_index(). </para> <para> To set the size of an array, use g_array_set_size(). </para> <para> To free an array, use g_array_free(). </para> <example> <title>Using a <structname>GArray</structname> to store <type>gint</type> values</title> <programlisting> GArray *garray; gint i; /* We create a new array to store gint values. We don't want it zero-terminated or cleared to 0's. */ garray = g_array_new (FALSE, FALSE, sizeof (gint)); for (i = 0; i < 10000; i++) g_array_append_val (garray, i); for (i = 0; i < 10000; i++) if (g_array_index (garray, gint, i) != i) g_print ("ERROR: got %d instead of %d\n", g_array_index (garray, gint, i), i); g_array_free (garray, TRUE); </programlisting></example> <!-- ##### SECTION See_Also ##### --> <para> </para> <!-- ##### STRUCT GArray ##### --> <para> Contains the public fields of an <link linkend="glib-arrays">Array</link>. </para> @data: a pointer to the element data. The data may be moved as elements are added to the #GArray. @len: the number of elements in the #GArray. <!-- ##### FUNCTION g_array_new ##### --> <para> Creates a new #GArray. </para> @zero_terminated: %TRUE if the array should have an extra element at the end which is set to 0. @clear_: %TRUE if #GArray elements should be automatically cleared to 0 when they are allocated. @element_size: the size of each element in bytes. @Returns: the new #GArray. <!-- ##### FUNCTION g_array_sized_new ##### --> <para> Creates a new #GArray with @reserved_size elements preallocated. This avoids frequent reallocation, if you are going to add many elements to the array. Note however that the size of the array is still 0. </para> @zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared. @clear_: %TRUE if all bits in the array should be cleared to 0 on allocation. @element_size: size of each element in the array. @reserved_size: number of elements preallocated. @Returns: the new #GArray. <!-- ##### MACRO g_array_append_val ##### --> <para> Adds the value on to the end of the array. The array will grow in size automatically if necessary. </para> <note> <para> g_array_append_val() is a macro which uses a reference to the value parameter @v. This means that you cannot use it with literal values such as "27". You must use variables. </para> </note> @a: a #GArray. @v: the value to append to the #GArray. @Returns: the #GArray. <!-- ##### FUNCTION g_array_append_vals ##### --> <para> Adds @len elements onto the end of the array. </para> @array: a #GArray. @data: a pointer to the elements to append to the end of the array. @len: the number of elements to append. @Returns: the #GArray. <!-- ##### MACRO g_array_prepend_val ##### --> <para> Adds the value on to the start of the array. The array will grow in size automatically if necessary. </para> <para> This operation is slower than g_array_append_val() since the existing elements in the array have to be moved to make space for the new element. </para> <note> <para> g_array_prepend_val() is a macro which uses a reference to the value parameter @v. This means that you cannot use it with literal values such as "27". You must use variables. </para> </note> @a: a #GArray. @v: the value to prepend to the #GArray. @Returns: the #GArray. <!-- ##### FUNCTION g_array_prepend_vals ##### --> <para> Adds @len elements onto the start of the array. </para> <para> This operation is slower than g_array_append_vals() since the existing elements in the array have to be moved to make space for the new elements. </para> @array: a #GArray. @data: a pointer to the elements to prepend to the start of the array. @len: the number of elements to prepend. @Returns: the #GArray. <!-- ##### MACRO g_array_insert_val ##### --> <para> Inserts an element into an array at the given index. </para> <note> <para> g_array_insert_val() is a macro which uses a reference to the value parameter @v. This means that you cannot use it with literal values such as "27". You must use variables. </para> </note> @a: a #GArray. @i: the index to place the element at. @v: the value to insert into the array. @Returns: the #GArray. <!-- ##### FUNCTION g_array_insert_vals ##### --> <para> Inserts @len elements into a #GArray at the given index. </para> @array: a #GArray. @index_: the index to place the elements at. @data: a pointer to the elements to insert. @len: the number of elements to insert. @Returns: the #GArray. <!-- ##### FUNCTION g_array_remove_index ##### --> <para> Removes the element at the given index from a #GArray. The following elements are moved down one place. </para> @array: a #GArray. @index_: the index of the element to remove. @Returns: the #GArray. <!-- ##### FUNCTION g_array_remove_index_fast ##### --> <para> Removes the element at the given index from a #GArray. The last element in the array is used to fill in the space, so this function does not preserve the order of the #GArray. But it is faster than g_array_remove_index(). </para> @array: a @GArray. @index_: the index of the element to remove. @Returns: the #GArray. <!-- ##### FUNCTION g_array_remove_range ##### --> <para> Removes the given number of elements starting at the given index from a #GArray. The following elements are moved to close the gap. </para> @array: a @GArray. @index_: the index of the first element to remove. @length: the number of elements to remove. @Returns: the #GArray. @Since: 2.4 <!-- ##### FUNCTION g_array_sort ##### --> <para> Sorts a #GArray using @compare_func which should be a qsort()-style comparison function (returns -1 for first arg is less than second arg, 0 for equal, 1 if first arg is greater than second arg). </para> @array: a #GArray. @compare_func: comparison function. <!-- ##### FUNCTION g_array_sort_with_data ##### --> <para> Like g_array_sort(), but the comparison function receives a user data argument. </para> @array: a #GArray. @compare_func: comparison function. @user_data: data to pass to @compare_func. <!-- ##### MACRO g_array_index ##### --> <para> Returns the element of a #GArray at the given index. The return value is cast to the given type. <example> <title>Getting a pointer to an element in a <structname>GArray</structname></title> <programlisting> EDayViewEvent *event; /* This gets a pointer to the 3rd element in the array of EDayViewEvent structs. */ event = &g_array_index (events, EDayViewEvent, 3); </programlisting> </example> </para> @a: a #GArray. @t: the type of the elements. @i: the index of the element to return. @Returns: the element of the #GArray at the index given by @i. <!-- ##### FUNCTION g_array_set_size ##### --> <para> Sets the size of the array, expanding it if necessary. If the array was created with @clear_ set to %TRUE, the new elements are set to 0. </para> @array: a #GArray. @length: the new size of the #GArray. @Returns: the #GArray. <!-- ##### FUNCTION g_array_free ##### --> <para> Frees the memory allocated for the #GArray. If @free_segment is %TRUE it frees the actual element data as well. </para> @array: a #GArray. @free_segment: if %TRUE the actual element data is freed as well. @Returns: the element data if @free_segment is %FALSE, otherwise %NULL