g_byte_array_new ()

GByteArray *
g_byte_array_new (void);

Creates a new GByteArray with a reference count of 1.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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]

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]

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.

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.

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

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.

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.

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.

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 .

Since: 2.32

g_bytes_ref ()

GBytes *
g_bytes_ref (GBytes *bytes);

Increase the reference count on bytes .

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.

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.

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.

Since: 2.32

struct GByteArray

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

Contains the public fields of a 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