| <!-- ##### 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> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### 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 |
| |
| |