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_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);
GByteArray* g_byte_array_set_size           (GByteArray *array,
                                             guint length);
void        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 *dataa pointer to the element data. The data may be moved as elements are added to the GByteArray.
guint lenthe 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_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_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 ()

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