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 <!-- ##### SECTION Stability_Level ##### -->
  53
  54
  55 <!-- ##### STRUCT GByteArray ##### -->
  56 <para>
  57 The <structname>GByteArray</structname> struct allows access to the public fields of a <structname>GByteArray</structname>.
  58 </para>
  59
  60 @data: a pointer to the element data. The data may be moved as elements are
  61 added to the #GByteArray.
  62 @len: the number of elements in the #GByteArray.
  63
  64 <!-- ##### FUNCTION g_byte_array_new ##### -->
  65 <para>
  66 Creates a new #GByteArray with a reference count of 1.
  67 </para>
  68
  69 @Returns: the new #GByteArray.
  70
  71
  72 <!-- ##### FUNCTION g_byte_array_sized_new ##### -->
  73 <para>
  74 Creates a new #GByteArray with @reserved_size bytes preallocated. This
  75 avoids frequent reallocation, if you are going to add many bytes to
  76 the array. Note however that the size of the array is still 0.
  77 </para>
  78
  79 @reserved_size: number of bytes preallocated.
  80 @Returns: the new #GByteArray.
  81
  82
  83 <!-- ##### FUNCTION g_byte_array_ref ##### -->
  84 <para>
  85
  86 </para>
  87
  88 @array:
  89 @Returns:
  90
  91
  92 <!-- ##### FUNCTION g_byte_array_unref ##### -->
  93 <para>
  94
  95 </para>
  96
  97 @array:
  98
  99
 100 <!-- ##### FUNCTION g_byte_array_append ##### -->
 101 <para>
 102 Adds the given bytes to the end of the #GByteArray.
 103 The array will grow in size automatically if necessary.
 104 </para>
 105
 106 @array: a #GByteArray.
 107 @data: the byte data to be added.
 108 @len: the number of bytes to add.
 109 @Returns: the #GByteArray.
 110
 111
 112 <!-- ##### FUNCTION g_byte_array_prepend ##### -->
 113 <para>
 114 Adds the given data to the start of the #GByteArray.
 115 The array will grow in size automatically if necessary.
 116 </para>
 117
 118 @array: a #GByteArray.
 119 @data: the byte data to be added.
 120 @len: the number of bytes to add.
 121 @Returns: the #GByteArray.
 122
 123
 124 <!-- ##### FUNCTION g_byte_array_remove_index ##### -->
 125 <para>
 126 Removes the byte at the given index from a #GByteArray.
 127 The following bytes are moved down one place.
 128 </para>
 129
 130 @array: a #GByteArray.
 131 @index_: the index of the byte to remove.
 132 @Returns: the #GByteArray.
 133
 134
 135 <!-- ##### FUNCTION g_byte_array_remove_index_fast ##### -->
 136 <para>
 137 Removes the byte at the given index from a #GByteArray.
 138 The last element in the array is used to fill in the space, so this function
 139 does not preserve the order of the #GByteArray. But it is faster than
 140 g_byte_array_remove_index().
 141 </para>
 142
 143 @array: a #GByteArray.
 144 @index_: the index of the byte to remove.
 145 @Returns: the #GByteArray.
 146
 147
 148 <!-- ##### FUNCTION g_byte_array_remove_range ##### -->
 149 <para>
 150 Removes the given number of bytes starting at the given index from a
 151 #GByteArray.  The following elements are moved to close the gap.
 152 </para>
 153
 154 @array: a @GByteArray.
 155 @index_: the index of the first byte to remove.
 156 @length: the number of bytes to remove.
 157 @Returns: the #GByteArray.
 158 @Since: 2.4
 159
 160
 161 <!-- ##### FUNCTION g_byte_array_sort ##### -->
 162 <para>
 163 Sorts a byte array, using @compare_func which should be a qsort()-style
 164 comparison function (returns less than zero for first arg is less than second
 165 arg, zero for equal, greater than zero if first arg is greater than second
 166 arg).
 167 </para>
 168 <para>
 169 If two array elements compare equal, their order in the sorted array is
 170 undefined.
 171 </para>
 172
 173 @array: a #GByteArray.
 174 @compare_func: comparison function.
 175
 176
 177 <!-- ##### FUNCTION g_byte_array_sort_with_data ##### -->
 178 <para>
 179 Like g_byte_array_sort(), but the comparison function takes an extra user data
 180 argument.
 181 </para>
 182
 183 @array: a #GByteArray.
 184 @compare_func: comparison function.
 185 @user_data: data to pass to @compare_func.
 186
 187
 188 <!-- ##### FUNCTION g_byte_array_set_size ##### -->
 189 <para>
 190 Sets the size of the #GByteArray, expanding it if necessary.
 191 </para>
 192
 193 @array: a #GByteArray.
 194 @length: the new size of the #GByteArray.
 195 @Returns: the #GByteArray.
 196
 197
 198 <!-- ##### FUNCTION g_byte_array_free ##### -->
 199 <para>
 200 Frees the memory allocated by the #GByteArray.
 201 If @free_segment is %TRUE it frees the actual byte data. If the reference
 202 count of @array is greater than one, the #GByteArray wrapper is preserved but
 203 the size of @array will be set to zero.
 204 </para>
 205
 206 @array: a #GByteArray.
 207 @free_segment: if %TRUE the actual byte data is freed as well.
 208 @Returns: the element data if @free_segment is %FALSE, otherwise %NULL.
 209         The element data should be freed using g_free().
 210
 211