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

# Byte Arrays

## Name

Byte Arrays -- arrays of bytes, which grow automatically as elements are added.

## Synopsis

    #include <glib.h>

    struct      GByteArray;
    GByteArray* g_byte_array_new                (void);
    GByteArray* g_byte_array_sized_new          (guint reserved_size);
    GByteArray* g_byte_array_append             (GByteArray *array,
                                                 const guint8 *data,
                                                 guint len);
    GByteArray* g_byte_array_prepend            (GByteArray *array,
                                                 const guint8 *data,
                                                 guint len);
    GByteArray* g_byte_array_remove_index       (GByteArray *array,
                                                 guint index);
    GByteArray* g_byte_array_remove_index_fast  (GByteArray *array,
                                                 guint index);
    void        g_byte_array_sort               (GByteArray *array,
                                                 GCompareFunc compare_func);
    void        g_byte_array_sort_with_data     (GByteArray *array,
                                                 GCompareDataFunc compare_func,
                                                 gpointer user_data);
    GByteArray* g_byte_array_set_size           (GByteArray *array,
                                                 guint length);
    guint8*     g_byte_array_free               (GByteArray *array,
                                                 gboolean free_segment);

## Description

GByteArray is based on GArray, to provide arrays of bytes which grow automatically as elements are added.

To create a new GByteArray use g_byte_array_new().

To add elements to a GByteArray, use g_byte_array_append(), and g_byte_array_prepend().

To set the size of a GByteArray, use g_byte_array_set_size().

To free a GByteArray, use g_byte_array_free().

Example 1. Using a GByteArray.

      GByteArray *gbarray;
      gint i;

      gbarray = g_byte_array_new ();
      for (i = 0; i < 10000; i++)
        g_byte_array_append (gbarray, (guint8*) "abcd", 4);

      for (i = 0; i < 10000; i++)
        {
          g_assert (gbarray->data[4*i] == 'a');
          g_assert (gbarray->data[4*i+1] == 'b');
          g_assert (gbarray->data[4*i+2] == 'c');
          g_assert (gbarray->data[4*i+3] == 'd');
        }

      g_byte_array_free (gbarray, TRUE);

## Details

### struct GByteArray

    struct GByteArray
    {
      guint8 *data;
      guint	  len;
    };

The GByteArray struct allows access to the public fields of a GByteArray.

guint8 *`data` | a pointer to the element data. The data may be moved as elements are added to the GByteArray.
guint `len` | the number of elements in the GByteArray.

### g_byte_array_new ()

    GByteArray* g_byte_array_new                (void);

Creates a new GByteArray.

Returns : | the new GByteArray.

### g_byte_array_sized_new ()

    GByteArray* g_byte_array_sized_new          (guint reserved_size);

Creates a new GByteArray with `reserved_size` bytes preallocated. This avoids frequent reallocation, if you are going to add many bytes to the array. Note however that the size of the array is still 0.

`reserved_size` : | number of bytes preallocated.
Returns : | the new GByteArray.

### g_byte_array_append ()

    GByteArray* g_byte_array_append             (GByteArray *array,
                                                 const guint8 *data,
                                                 guint len);

Adds the given bytes to the end of the GByteArray. The array will grow in size automatically if necessary.

`array` : | a GByteArray.
`data` : | the byte data to be added.
`len` : | the number of bytes to add.
Returns : | the GByteArray.

### g_byte_array_prepend ()

    GByteArray* g_byte_array_prepend            (GByteArray *array,
                                                 const guint8 *data,
                                                 guint len);

Adds the given data to the start of the GByteArray. The array will grow in size automatically if necessary.

`array` : | a GByteArray.
`data` : | the byte data to be added.
`len` : | the number of bytes to add.
Returns : | the GByteArray.

### g_byte_array_remove_index ()

    GByteArray* g_byte_array_remove_index       (GByteArray *array,
                                                 guint index);

Removes the byte at the given index from a GByteArray. The following bytes are moved down one place.

`array` : | a GByteArray.
`index` : | the index of the byte to remove.
Returns : | the GByteArray.

### g_byte_array_remove_index_fast ()

    GByteArray* g_byte_array_remove_index_fast  (GByteArray *array,
                                                 guint index);

Removes the byte at the given index from a GByteArray. The last element in the array is used to fill in the space, so this function does not preserve the order of the GByteArray. But it is faster than g_byte_array_remove_index().

`array` : | a GByteArray.
`index` : | the index of the byte to remove.
Returns : | the GByteArray.

### g_byte_array_sort ()

    void        g_byte_array_sort               (GByteArray *array,
                                                 GCompareFunc compare_func);

Sorts a byte array, 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).

`array` : | a GByteArray.
`compare_func` : | comparison function.

### g_byte_array_sort_with_data ()

    void        g_byte_array_sort_with_data     (GByteArray *array,
                                                 GCompareDataFunc compare_func,
                                                 gpointer user_data);

Like g_byte_array_sort(), but the comparison function takes a user data argument.

`array` : | a GByteArray.
`compare_func` : | comparison function.
`user_data` : | data to pass to `compare_func`.

### g_byte_array_set_size ()

    GByteArray* g_byte_array_set_size           (GByteArray *array,
                                                 guint length);

Sets the size of the GByteArray, expanding it if necessary.

`array` : | a GByteArray.
`length` : | the new size of the GByteArray.
Returns : | the GByteArray.

### g_byte_array_free ()

    guint8*     g_byte_array_free               (GByteArray *array,
                                                 gboolean free_segment);

Frees the memory allocated by the GByteArray. If `free_segment` is `TRUE` it frees the actual byte data.

`array` : | a GByteArray.
`free_segment` : | if `TRUE` the actual byte data is freed as well.
Returns : |

<<< Previous Page | Home | Up | Next Page >>>
Pointer Arrays | Balanced Binary Trees