Byte Arrays: GLib Reference Manual

## Byte Arrays Byte Arrays — arrays of bytes |

## Functions

GByteArray * | g_byte_array_new ()
guint8 * | g_byte_array_steal ()
GByteArray * | g_byte_array_new_take ()
GByteArray * | g_byte_array_sized_new ()
GByteArray * | g_byte_array_ref ()
void | g_byte_array_unref ()
GByteArray * | g_byte_array_append ()
GByteArray * | g_byte_array_prepend ()
GByteArray * | g_byte_array_remove_index ()
GByteArray * | g_byte_array_remove_index_fast ()
GByteArray * | g_byte_array_remove_range ()
void | g_byte_array_sort ()
void | g_byte_array_sort_with_data ()
GByteArray * | g_byte_array_set_size ()
guint8 * | g_byte_array_free ()
GBytes * | g_byte_array_free_to_bytes ()
GBytes * | g_bytes_new ()
GBytes * | g_bytes_new_take ()
GBytes * | g_bytes_new_static ()
GBytes * | g_bytes_new_with_free_func ()
GBytes * | g_bytes_new_from_bytes ()
gconstpointer | g_bytes_get_data ()
gconstpointer | g_bytes_get_region ()
gsize | g_bytes_get_size ()
guint | g_bytes_hash ()
gboolean | g_bytes_equal ()
gint | g_bytes_compare ()
GBytes * | g_bytes_ref ()
void | g_bytes_unref ()
gpointer | g_bytes_unref_to_data ()
GByteArray * | g_bytes_unref_to_array ()

## Types and Values

struct | GByteArray
| GBytes

## Includes

    #include <gmodule.h>

## 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()`.

An example for 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.

## Functions

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

    guint8 *
    g_byte_array_steal (GByteArray *array,
                        gsize *len);

Frees the data in the array and resets the size to zero, while the underlying array is preserved for use elsewhere and returned to the caller.

#### Parameters

array | a GByteArray. |
len | pointer to retrieve the number of elements of the original array. | [optional][out]

#### Returns

the element data, which should be freed using `g_free()`.

[transfer full]

Since: 2.64

### g_byte_array_new_take ()

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

Creates a byte array containing the `data` . After this call, `data` belongs to the GByteArray and may no longer be modified by the caller. The memory of `data` has to be dynamically allocated and will eventually be freed with `g_free()`.

Do not use it if `len` is greater than `G_MAXUINT`. GByteArray stores the length of its data in guint, which may be shorter than gsize.

#### Parameters

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.

#### Parameters

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 thread-safe and may be called from any thread.

#### Parameters

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 thread-safe and may be called from any thread.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

array | a GByteArray. | [transfer full]

#### Returns

a new immutable GBytes representing same byte data that was in the array.

[transfer full]

Since: 2.32

### g_bytes_new ()

    GBytes *
    g_bytes_new (gconstpointer data,
                 gsize size);

Creates a new GBytes from `data` .

`data` is copied. If `size` is 0, `data` may be `NULL`.

#### Parameters

data | the data to be used for the bytes. | [transfer none][array length=size][element-type guint8][nullable]
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 GBytes and may no longer be modified by the caller. The memory of `data` has to be dynamically allocated and will eventually be freed with `g_free()`.

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

`data` may be `NULL` if `size` is 0.

#### Parameters

data | the data to be used for the bytes. | [transfer full][array length=size][element-type guint8][nullable]
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). It may be `NULL` if `size` is 0.

[skip]

#### Parameters

data | the data to be used for the bytes. | [transfer full][array length=size][element-type guint8][nullable]
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` may be `NULL` if `size` is 0.

[skip]

#### Parameters

data | the data to be used for the bytes. | [array length=size][element-type guint8][nullable]
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.

Since 2.56, if `offset` is 0 and `length` matches the size of `bytes` , then `bytes` will be returned with the reference count incremented by 1. If `bytes` is a slice of another GBytes, then the resulting GBytes will reference the same GBytes instead of `bytes` . This allows consumers to simplify the usage of GBytes when asynchronously writing to streams.

#### Parameters

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.

`NULL` may be returned if `size` is 0. This is not guaranteed, as the GBytes may represent an empty string with `data` non-`NULL` and `size` as 0. `NULL` will not be returned if `size` is non-zero.

#### Parameters

bytes | a GBytes |
size | location to return size of byte data. | [out][optional]

#### Returns

a pointer to the byte data, or `NULL`.

[transfer none][array length=size][element-type guint8][nullable]

Since: 2.32

### g_bytes_get_region ()

    gconstpointer
    g_bytes_get_region (GBytes *bytes,
                        gsize element_size,
                        gsize offset,
                        gsize n_elements);

Gets a pointer to a region in `bytes` .

The region starts at `offset` many bytes from the start of the data and contains `n_elements` many elements of `element_size` size.

`n_elements` may be zero, but `element_size` must always be non-zero. Ideally, `element_size` is a static constant (eg: sizeof a struct).

This function does careful bounds checking (including checking for arithmetic overflows) and returns a non-`NULL` pointer if the specified region lies entirely within the `bytes` . If the region is in some way out of range, or if an overflow has occurred, then `NULL` is returned.

Note: it is possible to have a valid zero-size region. In this case, the returned pointer will be equal to the base pointer of the data of `bytes` , plus `offset` . This will be non-`NULL` except for the case where `bytes` itself was a zero-sized region. Since it is unlikely that you will be using this function to check for a zero-sized region in a zero-sized `bytes` , `NULL` effectively always means "error".

#### Parameters

bytes | a GBytes |
element_size | a non-zero element size |
offset | an offset to the start of the region within the `bytes` |
n_elements | the number of elements in the region |

#### Returns

the requested region, or `NULL` in case of an error.

[nullable]

Since: 2.70

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

#### Parameters

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_hash_func` parameter, when using non-`NULL` GBytes pointers as keys in a GHashTable.

#### Parameters

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.

#### Parameters

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 lexicographical order.

If `bytes1` and `bytes2` have different length but the shorter one is a prefix of the longer one then the shorter one is considered to be less than the longer one. Otherwise the first byte where both differ is used for comparison. If `bytes1` has a smaller value at that position it is considered less, otherwise greater than `bytes2` .

#### Parameters

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 `bytes1` is less than `bytes2` , a positive value if `bytes1` is greater than `bytes2` , and zero if `bytes1` is equal to `bytes2`

Since: 2.32

### g_bytes_ref ()

    GBytes *
    g_bytes_ref (GBytes *bytes);

Increase the reference count on `bytes` .

#### Parameters

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. If `bytes` is `NULL`, it will return immediately.

#### Parameters

bytes | a GBytes. | [nullable]

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.

#### Parameters

bytes | a GBytes. | [transfer full]
size | location to place the length of the returned data. | [out]

#### Returns

(transfer full) (array length=size) (element-type guint8) (not nullable): a pointer to the same byte data, which should be freed with `g_free()`

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.

Do not use it if `bytes` contains more than `G_MAXUINT` bytes. GByteArray stores the length of its data in guint, which may be shorter than gsize, that `bytes` is using.

#### Parameters

bytes | a GBytes. | [transfer full]

#### Returns

a new mutable GByteArray containing the same byte data.

[transfer full]

Since: 2.32

## Types and Values

### struct GByteArray

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

Contains the public fields of a GByteArray.

#### Members

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 |

### GBytes

    typedef struct _GBytes GBytes;

A simple refcounted data type representing an immutable sequence of zero or more bytes 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