Arrays

GLib Reference Manual
<<< Previous Page	Home	Up	Next Page >>>

Description

Arrays are similar to standard C arrays, except that they grow automatically as elements are added.

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.

To create a new array use g_array_new().

To add elements to an array, use g_array_append_val(), g_array_append_vals(), g_array_prepend_val(), and g_array_prepend_vals().

To access an element of an array, use g_array_index().

To set the size of an array, use g_array_set_size().

To free an array, use g_array_free().

Example 1. Using a GArray to store gint values.

  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);

Details

struct GArray

struct GArray
{
  gchar *data;
  guint len;
};

Contains the public fields of an Array. The data field points to the element data. It may change as elements are added to the array. The len field contains the number of elements in the array.

g_array_new ()

GArray*     g_array_new                     (gboolean zero_terminated,
                                             gboolean clear,
                                             guint element_size);

Creates a new GArray.

`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.

g_array_append_val()

#define     g_array_append_val(a,v)

Adds the value on to the end of the array. The array will grow in size automatically if necessary.

Note: 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.

`a` :	a GArray.
`v` :	the value to append to the GArray.
Returns :	the GArray.

g_array_append_vals ()

GArray*     g_array_append_vals             (GArray *array,
                                             gconstpointer data,
                                             guint len);

Adds len elements onto the end of the array.

`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.

g_array_prepend_val()

#define     g_array_prepend_val(a,v)

Adds the value on to the start of the array. The array will grow in size automatically if necessary.

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.

Note: 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.

`a` :	a GArray.
`v` :	the value to prepend to the GArray.
Returns :	the GArray.

g_array_prepend_vals ()

GArray*     g_array_prepend_vals            (GArray *array,
                                             gconstpointer data,
                                             guint len);

Adds len elements onto the start of the array.

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.

`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.

g_array_insert_val()

#define     g_array_insert_val(a,i,v)

`a` :
`i` :
`v` :

g_array_insert_vals ()

GArray*     g_array_insert_vals             (GArray *array,
                                             guint index,
                                             gconstpointer data,
                                             guint len);

`array` :
`index` :
`data` :
`len` :
Returns :

g_array_remove_index ()

GArray*     g_array_remove_index            (GArray *array,
                                             guint index);

`array` :
`index` :
Returns :

g_array_remove_index_fast ()

GArray*     g_array_remove_index_fast       (GArray *array,
                                             guint index);

`array` :
`index` :
Returns :

g_array_index()

#define     g_array_index(a,t,i)

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.

`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`.

g_array_set_size ()

GArray*     g_array_set_size                (GArray *array,
                                             guint length);

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.

`array` :	a GArray.
`length` :	the new size of the GArray.
Returns :	the GArray.

g_array_free ()

void        g_array_free                    (GArray *array,
                                             gboolean free_segment);

Frees the memory allocated for the GArray. If free_segment is TRUE it frees the actual element data as well.

`array` :	a GArray.
`free_segment` :	if TRUE the actual element data is freed as well.