Byte Arrays

## Byte Arrays Byte Arrays — arrays of bytes |

## Synopsis

    #include <glib.h>

    struct              GByteArray;
    GByteArray *        g_byte_array_new                    (void);
    GByteArray *        g_byte_array_new_take               (guint8 *data,
                                                             gsize len);
    GByteArray *        g_byte_array_sized_new              (guint reserved_size);
    GByteArray *        g_byte_array_ref                    (GByteArray *array);
    void                g_byte_array_unref                  (GByteArray *array);
    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_remove_range           (GByteArray *array,
                                                             guint index_,
                                                             guint length);
    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);
    GBytes *            g_byte_array_free_to_bytes          (GByteArray *array);

                        GBytes;
    GBytes *            g_bytes_new                         (gconstpointer data,
                                                             gsize size);
    GBytes *            g_bytes_new_take                    (gpointer data,
                                                             gsize size);
    GBytes *            g_bytes_new_static                  (gconstpointer data,
                                                             gsize size);
    GBytes *            g_bytes_new_with_free_func          (gconstpointer data,
                                                             gsize size,
                                                             GDestroyNotify free_func,
                                                             gpointer user_data);
    GBytes *            g_bytes_new_from_bytes              (GBytes *bytes,
                                                             gsize offset,
                                                             gsize length);
    gconstpointer       g_bytes_get_data                    (GBytes *bytes,
                                                             gsize *size);
    gsize               g_bytes_get_size                    (GBytes *bytes);
    guint               g_bytes_hash                        (gconstpointer bytes);
    gboolean            g_bytes_equal                       (gconstpointer bytes1,
                                                             gconstpointer bytes2);
    gint                g_bytes_compare                     (gconstpointer bytes1,
                                                             gconstpointer bytes2);
    GBytes *            g_bytes_ref                         (GBytes *bytes);
    void                g_bytes_unref                       (GBytes *bytes);
    gpointer            g_bytes_unref_to_data               (GBytes *bytes,
                                                             gsize *size);
    GByteArray *        g_bytes_unref_to_array              (GBytes *bytes);

## Description

GByteArray is a mutable array of bytes 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 16. Using a GByteArray

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    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);

See GBytes if you are interested in an immutable object representing a sequence of bytes.

## 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 with a reference count of 1.

Returns : | the new GByteArray. [transfer full]

### g_byte_array_new_take ()

    GByteArray *        g_byte_array_new_take               (guint8 *data,
                                                             gsize len);

Create byte array containing the data. The data will be owned by the array and will be freed with `g_free()`, i.e. it could be allocated using `g_strdup()`.

`data` : | byte data for the array. [transfer full][array length=len]
`len` : | length of `data`
Returns : | a new GByteArray. [transfer full]

Since 2.32

### 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_ref ()

    GByteArray *        g_byte_array_ref                    (GByteArray *array);

Atomically increments the reference count of `array` by one. This function is MT-safe and may be called from any thread.

`array` : | A GByteArray.
Returns : | The passed in GByteArray.

Since 2.22

### g_byte_array_unref ()

    void                g_byte_array_unref                  (GByteArray *array);

Atomically decrements the reference count of `array` by one. If the reference count drops to 0, all memory allocated by the array is released. This function is MT-safe and may be called from any thread.

`array` : | A GByteArray.

Since 2.22

### 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_remove_range ()

    GByteArray *        g_byte_array_remove_range           (GByteArray *array,
                                                             guint index_,
                                                             guint length);

Removes the given number of bytes starting at the given index from a GByteArray. The following elements are moved to close the gap.

`array` : | a `GByteArray`.
`index_` : | the index of the first byte to remove.
`length` : | the number of bytes to remove.
Returns : | the GByteArray.

Since 2.4

### 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 less than zero for first arg is less than second arg, zero for equal, greater than zero if first arg is greater than second arg).

If two array elements compare equal, their order in the sorted array is undefined. If you want equal elements to keep their order (i.e. you want a stable sort) you can write a comparison function that, if two elements would otherwise compare equal, compares them by their addresses.

`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 an extra 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. If the reference count of `array` is greater than one, the GByteArray wrapper is preserved but the size of `array` will be set to zero.

`array` : | a GByteArray.
`free_segment` : | if `TRUE` the actual byte data is freed as well.
Returns : | the element data if `free_segment` is `FALSE`, otherwise `NULL`. The element data should be freed using `g_free()`.

### g_byte_array_free_to_bytes ()

    GBytes *            g_byte_array_free_to_bytes          (GByteArray *array);

Transfers the data from the GByteArray into a new immutable GBytes.

The GByteArray is freed unless the reference count of `array` is greater than one, the GByteArray wrapper is preserved but the size of `array` will be set to zero.

This is identical to using `g_bytes_new_take()` and `g_byte_array_free()` together.

`array` : | a GByteArray. [transfer full]
Returns : | a new immutable GBytes representing same byte data that was in the array. [transfer full]

Since 2.32

### GBytes

    typedef struct _GBytes GBytes;

A simple refcounted data type representing an immutable byte sequence from an unspecified origin.

The purpose of a GBytes is to keep the memory region that it holds alive for as long as anyone holds a reference to the bytes. When the last reference count is dropped, the memory is released. Multiple unrelated callers can use byte data in the GBytes without coordinating their activities, resting assured that the byte data will not change or move while they hold a reference.

A GBytes can come from many different origins that may have different procedures for freeing the memory region. Examples are memory from `g_malloc()`, from memory slices, from a GMappedFile or memory from other allocators.

GBytes work well as keys in GHashTable. Use `g_bytes_equal()` and `g_bytes_hash()` as parameters to `g_hash_table_new()` or `g_hash_table_new_full()`. GBytes can also be used as keys in a GTree by passing the `g_bytes_compare()` function to `g_tree_new()`.

The data pointed to by this bytes must not be modified. For a mutable array of bytes see GByteArray. Use `g_bytes_unref_to_array()` to create a mutable array for a GBytes sequence. To create an immutable GBytes from a mutable GByteArray, use the `g_byte_array_free_to_bytes()` function.

Since 2.32

### g_bytes_new ()

    GBytes *            g_bytes_new                         (gconstpointer data,
                                                             gsize size);

Creates a new GBytes from `data`.

`data` is copied.

`data` : | the data to be used for the bytes. [transfer none][array length=size][element-type guint8]
`size` : | the size of `data`
Returns : | a new GBytes. [transfer full]

Since 2.32

### g_bytes_new_take ()

    GBytes *            g_bytes_new_take                    (gpointer data,
                                                             gsize size);

Creates a new GBytes from `data`.

After this call, `data` belongs to the bytes and may no longer be modified by the caller. `g_free()` will be called on `data` when the bytes is no longer in use. Because of this `data` must have been created by a call to `g_malloc()`, `g_malloc0()` or `g_realloc()` or by one of the many functions that wrap these calls (such as `g_new()`, `g_strdup()`, etc).

For creating GBytes with memory from other allocators, see `g_bytes_new_with_free_func()`.

`data` : | the data to be used for the bytes. [transfer full][array length=size][element-type guint8]
`size` : | the size of `data`
Returns : | a new GBytes. [transfer full]

Since 2.32

### g_bytes_new_static ()

    GBytes *            g_bytes_new_static                  (gconstpointer data,
                                                             gsize size);

Creates a new GBytes from static data.

`data` must be static (ie: never modified or freed).

`data` : | the data to be used for the bytes. [transfer full][array length=size][element-type guint8]
`size` : | the size of `data`
Returns : | a new GBytes. [transfer full]

Since 2.32

### g_bytes_new_with_free_func ()

    GBytes *            g_bytes_new_with_free_func          (gconstpointer data,
                                                             gsize size,
                                                             GDestroyNotify free_func,
                                                             gpointer user_data);

Creates a GBytes from `data`.

When the last reference is dropped, `free_func` will be called with the `user_data` argument.

`data` must not be modified after this call is made until `free_func` has been called to indicate that the bytes is no longer in use.

`data` : | the data to be used for the bytes. [array length=size]
`size` : | the size of `data`
`free_func` : | the function to call to release the data
`user_data` : | data to pass to `free_func`
Returns : | a new GBytes. [transfer full]

Since 2.32

### g_bytes_new_from_bytes ()

    GBytes *            g_bytes_new_from_bytes              (GBytes *bytes,
                                                             gsize offset,
                                                             gsize length);

Creates a GBytes which is a subsection of another GBytes. The `offset` + `length` may not be longer than the size of `bytes`.

A reference to `bytes` will be held by the newly created GBytes until the byte data is no longer needed.

`bytes` : | a GBytes
`offset` : | offset which subsection starts at
`length` : | length of subsection
Returns : | a new GBytes. [transfer full]

Since 2.32

### g_bytes_get_data ()

    gconstpointer       g_bytes_get_data                    (GBytes *bytes,
                                                             gsize *size);

Get the byte data in the GBytes. This data should not be modified.

This function will always return the same pointer for a given GBytes.

`bytes` : | a GBytes
`size` : | location to return size of byte data. [out][allow-none]
Returns : | a pointer to the byte data. [transfer none][array length=size][type guint8]

Since 2.32

### g_bytes_get_size ()

    gsize               g_bytes_get_size                    (GBytes *bytes);

Get the size of the byte data in the GBytes.

This function will always return the same value for a given GBytes.

`bytes` : | a GBytes
Returns : | the size

Since 2.32

### g_bytes_hash ()

    guint               g_bytes_hash                        (gconstpointer bytes);

Creates an integer hash code for the byte data in the GBytes.

This function can be passed to `g_hash_table_new()` as the `key_equal_func` parameter, when using non-`NULL` GBytes pointers as keys in a GHashTable.

`bytes` : | a pointer to a GBytes key. [type GLib.Bytes]
Returns : | a hash value corresponding to the key.

Since 2.32

### g_bytes_equal ()

    gboolean            g_bytes_equal                       (gconstpointer bytes1,
                                                             gconstpointer bytes2);

Compares the two GBytes values being pointed to and returns `TRUE` if they are equal.

This function can be passed to `g_hash_table_new()` as the `key_equal_func` parameter, when using non-`NULL` GBytes pointers as keys in a GHashTable.

`bytes1` : | a pointer to a GBytes. [type GLib.Bytes]
`bytes2` : | a pointer to a GBytes to compare with `bytes1`. [type GLib.Bytes]
Returns : | `TRUE` if the two keys match.

Since 2.32

### g_bytes_compare ()

    gint                g_bytes_compare                     (gconstpointer bytes1,
                                                             gconstpointer bytes2);

Compares the two GBytes values.

This function can be used to sort GBytes instances in lexographical order.

`bytes1` : | a pointer to a GBytes. [type GLib.Bytes]
`bytes2` : | a pointer to a GBytes to compare with `bytes1`. [type GLib.Bytes]
Returns : | a negative value if bytes2 is lesser, a positive value if bytes2 is greater, and zero if bytes2 is equal to bytes1

Since 2.32

### g_bytes_ref ()

    GBytes *            g_bytes_ref                         (GBytes *bytes);

Increase the reference count on `bytes`.

`bytes` : | a GBytes
Returns : | the GBytes

Since 2.32

### g_bytes_unref ()

    void                g_bytes_unref                       (GBytes *bytes);

Releases a reference on `bytes`. This may result in the bytes being freed.

`bytes` : | a GBytes. [allow-none]

Since 2.32

### g_bytes_unref_to_data ()

    gpointer            g_bytes_unref_to_data               (GBytes *bytes,
                                                             gsize *size);

Unreferences the bytes, and returns a pointer the same byte data contents.

As an optimization, the byte data is returned without copying if this was the last reference to bytes and bytes was created with `g_bytes_new()`, `g_bytes_new_take()` or `g_byte_array_free_to_bytes()`. In all other cases the data is copied.

`bytes` : | a GBytes. [transfer full]
`size` : | location to place the length of the returned data
Returns : | a pointer to the same byte data, which should be freed with `g_free()`. [transfer full]

Since 2.32

### g_bytes_unref_to_array ()

    GByteArray *        g_bytes_unref_to_array              (GBytes *bytes);

Unreferences the bytes, and returns a new mutable GByteArray containing the same byte data.

As an optimization, the byte data is transferred to the array without copying if this was the last reference to bytes and bytes was created with `g_bytes_new()`, `g_bytes_new_take()` or `g_byte_array_free_to_bytes()`. In all other cases the data is copied.

`bytes` : | a GBytes. [transfer full]
Returns : | a new mutable GByteArray containing the same byte data. [transfer full]

Since 2.32