<!-- ##### 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 GArray to store gint values.</title>
<programlisting>
  GArray *garray;
  gint i;

  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>


<!-- ##### STRUCT GArray ##### -->
<para>
Contains the public fields of an <link linkend="glib-arrays">Array</link>.
The <structfield>data</structfield> field points to the element data.
It may change as elements are added to the array.
The <structfield>len</structfield> field contains the number of elements
in the array.
</para>

<!-- ##### 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.

<!-- ##### 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_index ##### -->
<para>
Returns the element of a #GArray at the given index.
The return value is cast to the given type.
FIXME: need more info on how it works with structures.
</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.

