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 GByteArray.</title>
  28 <programlisting>
  29   GByteArray *gbarray;
  30   gint i;
  31
  32   gbarray = g_byte_array_new ();
  33   for (i = 0; i < 10000; i++)
  34     g_byte_array_append (gbarray, (guint8*) "abcd", 4);
  35
  36   for (i = 0; i < 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 #GByteArray struct allows access to the public fields of a #GByteArray.
  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
  72 </para>
  73
  74 @reserved_size:
  75 @Returns:
  76
  77
  78 <!-- ##### FUNCTION g_byte_array_append ##### -->
  79 <para>
  80 Adds the given bytes to the end of the #GByteArray.
  81 The array will grow in size automatically if necessary.
  82 </para>
  83
  84 @array: a #GByteArray.
  85 @data: the byte data to be added.
  86 @len: the number of bytes to add.
  87 @Returns: the #GByteArray.
  88
  89
  90 <!-- ##### FUNCTION g_byte_array_prepend ##### -->
  91 <para>
  92 Adds the given data to the start of the #GByteArray.
  93 The array will grow in size automatically if necessary.
  94 </para>
  95
  96 @array: a #GByteArray.
  97 @data: the byte data to be added.
  98 @len: the number of bytes to add.
  99 @Returns: the #GByteArray.
 100
 101
 102 <!-- ##### FUNCTION g_byte_array_remove_index ##### -->
 103 <para>
 104 Removes the byte at the given index from a #GByteArray.
 105 The following bytes are moved down one place.
 106 </para>
 107
 108 @array: a #GByteArray.
 109 @index: the index of the byte to remove.
 110 @Returns: the #GByteArray.
 111
 112
 113 <!-- ##### FUNCTION g_byte_array_remove_index_fast ##### -->
 114 <para>
 115 Removes the byte at the given index from a #GByteArray.
 116 The last element in the array is used to fill in the space, so this function
 117 does not preserve the order of the #GByteArray. But it is faster than
 118 g_byte_array_remove_index().
 119 </para>
 120
 121 @array: a #GByteArray.
 122 @index: the index of the byte to remove.
 123 @Returns: the #GByteArray.
 124
 125
 126 <!-- ##### FUNCTION g_byte_array_sort ##### -->
 127 <para>
 128
 129 </para>
 130
 131 @array:
 132 @compare_func:
 133
 134
 135 <!-- ##### FUNCTION g_byte_array_sort_with_data ##### -->
 136 <para>
 137
 138 </para>
 139
 140 @array:
 141 @compare_func:
 142 @user_data:
 143
 144
 145 <!-- ##### FUNCTION g_byte_array_set_size ##### -->
 146 <para>
 147 Sets the size of the #GByteArray, expanding it if necessary.
 148 </para>
 149
 150 @array: a #GByteArray.
 151 @length: the new size of the #GByteArray.
 152 @Returns: the #GByteArray.
 153
 154
 155 <!-- ##### FUNCTION g_byte_array_free ##### -->
 156 <para>
 157 Frees the memory allocated by the #GByteArray.
 158 If free_segment is TRUE it frees the actual byte data.
 159 </para>
 160
 161 @array: a #GByteArray.
 162 @free_segment: if TRUE the actual byte data is freed as well.
 163 @Returns:
 164
 165