| <!-- ##### SECTION Title ##### --> |
| Byte Arrays |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| arrays of bytes, which grow automatically as elements are added |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| #GByteArray is based on #GArray, to provide arrays of bytes which grow |
| automatically as elements are added. |
| </para> |
| <para> |
| To create a new #GByteArray use g_byte_array_new(). |
| </para> |
| <para> |
| To add elements to a #GByteArray, use g_byte_array_append(), and |
| g_byte_array_prepend(). |
| </para> |
| <para> |
| To set the size of a #GByteArray, use g_byte_array_set_size(). |
| </para> |
| <para> |
| To free a #GByteArray, use g_byte_array_free(). |
| </para> |
| |
| <example> |
| <title>Using a <structname>GByteArray</structname></title> |
| <programlisting> |
| 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); |
| </programlisting></example> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### STRUCT GByteArray ##### --> |
| <para> |
| The <structname>GByteArray</structname> struct allows access to the public fields of a <structname>GByteArray</structname>. |
| </para> |
| |
| @data: a pointer to the element data. The data may be moved as elements are |
| added to the #GByteArray. |
| @len: the number of elements in the #GByteArray. |
| |
| <!-- ##### FUNCTION g_byte_array_new ##### --> |
| <para> |
| Creates a new #GByteArray. |
| </para> |
| |
| @Returns: the new #GByteArray. |
| |
| |
| <!-- ##### FUNCTION g_byte_array_sized_new ##### --> |
| <para> |
| 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. |
| </para> |
| |
| @reserved_size: number of bytes preallocated. |
| @Returns: the new #GByteArray. |
| |
| |
| <!-- ##### FUNCTION g_byte_array_append ##### --> |
| <para> |
| Adds the given bytes to the end of the #GByteArray. |
| The array will grow in size automatically if necessary. |
| </para> |
| |
| @array: a #GByteArray. |
| @data: the byte data to be added. |
| @len: the number of bytes to add. |
| @Returns: the #GByteArray. |
| |
| |
| <!-- ##### FUNCTION g_byte_array_prepend ##### --> |
| <para> |
| Adds the given data to the start of the #GByteArray. |
| The array will grow in size automatically if necessary. |
| </para> |
| |
| @array: a #GByteArray. |
| @data: the byte data to be added. |
| @len: the number of bytes to add. |
| @Returns: the #GByteArray. |
| |
| |
| <!-- ##### FUNCTION g_byte_array_remove_index ##### --> |
| <para> |
| Removes the byte at the given index from a #GByteArray. |
| The following bytes are moved down one place. |
| </para> |
| |
| @array: a #GByteArray. |
| @index_: the index of the byte to remove. |
| @Returns: the #GByteArray. |
| |
| |
| <!-- ##### FUNCTION g_byte_array_remove_index_fast ##### --> |
| <para> |
| 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(). |
| </para> |
| |
| @array: a #GByteArray. |
| @index_: the index of the byte to remove. |
| @Returns: the #GByteArray. |
| |
| |
| <!-- ##### FUNCTION g_byte_array_remove_range ##### --> |
| <para> |
| Removes the given number of bytes starting at the given index from a |
| #GByteArray. The following elements are moved to close the gap. |
| </para> |
| |
| @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 |
| |
| |
| <!-- ##### FUNCTION g_byte_array_sort ##### --> |
| <para> |
| 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). |
| </para> |
| <para> |
| If two array elements compare equal, their order in the sorted array is |
| undefined. |
| </para> |
| |
| @array: a #GByteArray. |
| @compare_func: comparison function. |
| |
| |
| <!-- ##### FUNCTION g_byte_array_sort_with_data ##### --> |
| <para> |
| Like g_byte_array_sort(), but the comparison function takes an extra user data |
| argument. |
| </para> |
| |
| @array: a #GByteArray. |
| @compare_func: comparison function. |
| @user_data: data to pass to @compare_func. |
| |
| |
| <!-- ##### FUNCTION g_byte_array_set_size ##### --> |
| <para> |
| Sets the size of the #GByteArray, expanding it if necessary. |
| </para> |
| |
| @array: a #GByteArray. |
| @length: the new size of the #GByteArray. |
| @Returns: the #GByteArray. |
| |
| |
| <!-- ##### FUNCTION g_byte_array_free ##### --> |
| <para> |
| Frees the memory allocated by the #GByteArray. |
| If @free_segment is %TRUE it frees the actual byte data. |
| </para> |
| |
| @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(). |
| |
| |