Byte Arrays

Byte Arrays — arrays of bytes

Functions

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

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

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