docs/reference/glib/tmpl/arrays_byte.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Byte Arrays
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 arrays of bytes, which grow automatically as elements are added.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 #GByteArray is based on #GArray, to provide arrays of bytes which grow
  10 automatically as elements are added.
  11 </para>
  12 <para>
  13 To create a new #GByteArray use g_byte_array_new().
  14 </para>
  15 <para>
  16 To add elements to a #GByteArray, use g_byte_array_append(), and
  17 g_byte_array_prepend().
  18 </para>
  19 <para>
  20 To set the size of a #GByteArray, use g_byte_array_set_size().
  21 </para>
  22 <para>
  23 To free a #GByteArray, use g_byte_array_free().
  24 </para>
  25
  26 <example>
  27 <title>Using a <structname>GByteArray</structname>.</title>
  28 <programlisting>
  29   GByteArray *gbarray;
  30   gint i;
  31
  32   gbarray = g_byte_array_new (<!-- -->);
  33   for (i = 0; i &lt; 10000; i++)
  34     g_byte_array_append (gbarray, (guint8*) "abcd", 4);
  35
  36   for (i = 0; i &lt; 10000; i++)
  37     {
  38       g_assert (gbarray->data[4*i] == 'a');
  39       g_assert (gbarray->data[4*i+1] == 'b');
  40       g_assert (gbarray->data[4*i+2] == 'c');
  41       g_assert (gbarray->data[4*i+3] == 'd');
  42     }
  43
  44   g_byte_array_free (gbarray, TRUE);
  45 </programlisting></example>
  46
  47 <!-- ##### SECTION See_Also ##### -->
  48 <para>
  49
  50 </para>
  51
  52 <!-- ##### STRUCT GByteArray ##### -->
  53 <para>
  54 The <structname>GByteArray</structname> struct allows access to the public fields of a <structname>GByteArray</structname>.
  55 </para>
  56
  57 @data: a pointer to the element data. The data may be moved as elements are
  58 added to the #GByteArray.
  59 @len: the number of elements in the #GByteArray.
  60
  61 <!-- ##### FUNCTION g_byte_array_new ##### -->
  62 <para>
  63 Creates a new #GByteArray.
  64 </para>
  65
  66 @Returns: the new #GByteArray.
  67
  68
  69 <!-- ##### FUNCTION g_byte_array_sized_new ##### -->
  70 <para>
  71 Creates a new #GByteArray with @reserved_size bytes preallocated. This
  72 avoids frequent reallocation, if you are going to add many bytes to
  73 the array. Note however that the size of the array is still 0.
  74 </para>
  75
  76 @reserved_size: number of bytes preallocated.
  77 @Returns: the new #GByteArray.
  78
  79
  80 <!-- ##### FUNCTION g_byte_array_append ##### -->
  81 <para>
  82 Adds the given bytes to the end of the #GByteArray.
  83 The array will grow in size automatically if necessary.
  84 </para>
  85
  86 @array: a #GByteArray.
  87 @data: the byte data to be added.
  88 @len: the number of bytes to add.
  89 @Returns: the #GByteArray.
  90
  91
  92 <!-- ##### FUNCTION g_byte_array_prepend ##### -->
  93 <para>
  94 Adds the given data to the start of the #GByteArray.
  95 The array will grow in size automatically if necessary.
  96 </para>
  97
  98 @array: a #GByteArray.
  99 @data: the byte data to be added.
 100 @len: the number of bytes to add.
 101 @Returns: the #GByteArray.
 102
 103
 104 <!-- ##### FUNCTION g_byte_array_remove_index ##### -->
 105 <para>
 106 Removes the byte at the given index from a #GByteArray.
 107 The following bytes are moved down one place.
 108 </para>
 109
 110 @array: a #GByteArray.
 111 @index: the index of the byte to remove.
 112 @Returns: the #GByteArray.
 113
 114
 115 <!-- ##### FUNCTION g_byte_array_remove_index_fast ##### -->
 116 <para>
 117 Removes the byte at the given index from a #GByteArray.
 118 The last element in the array is used to fill in the space, so this function
 119 does not preserve the order of the #GByteArray. But it is faster than
 120 g_byte_array_remove_index().
 121 </para>
 122
 123 @array: a #GByteArray.
 124 @index: the index of the byte to remove.
 125 @Returns: the #GByteArray.
 126
 127
 128 <!-- ##### FUNCTION g_byte_array_sort ##### -->
 129 <para>
 130 Sorts a byte array, using @compare_func which should be a <function>qsort()</function>-style
 131 comparison function (returns -1 for first arg is less than second arg, 0 for
 132 equal, 1 if first arg is greater than second arg).
 133 </para>
 134
 135 @array: a #GByteArray.
 136 @compare_func: comparison function.
 137
 138
 139 <!-- ##### FUNCTION g_byte_array_sort_with_data ##### -->
 140 <para>
 141 Like g_byte_array_sort(), but the comparison function takes a user data argument.
 142 </para>
 143
 144 @array: a #GByteArray.
 145 @compare_func: comparison function.
 146 @user_data: data to pass to @compare_func.
 147
 148
 149 <!-- ##### FUNCTION g_byte_array_set_size ##### -->
 150 <para>
 151 Sets the size of the #GByteArray, expanding it if necessary.
 152 </para>
 153
 154 @array: a #GByteArray.
 155 @length: the new size of the #GByteArray.
 156 @Returns: the #GByteArray.
 157
 158
 159 <!-- ##### FUNCTION g_byte_array_free ##### -->
 160 <para>
 161 Frees the memory allocated by the #GByteArray.
 162 If @free_segment is %TRUE it frees the actual byte data.
 163 </para>
 164
 165 @array: a #GByteArray.
 166 @free_segment: if %TRUE the actual byte data is freed as well.
 167 @Returns:
 168
 169