1<!-- ##### SECTION Title ##### --> 2Byte Arrays 3 4<!-- ##### SECTION Short_Description ##### --> 5arrays 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 10automatically as elements are added. 11</para> 12<para> 13To create a new #GByteArray use g_byte_array_new(). 14</para> 15<para> 16To add elements to a #GByteArray, use g_byte_array_append(), and 17g_byte_array_prepend(). 18</para> 19<para> 20To set the size of a #GByteArray, use g_byte_array_set_size(). 21</para> 22<para> 23To 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 < 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<!-- ##### SECTION Stability_Level ##### --> 53 54 55<!-- ##### STRUCT GByteArray ##### --> 56<para> 57The <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 61added to the #GByteArray. 62@len: the number of elements in the #GByteArray. 63 64<!-- ##### FUNCTION g_byte_array_new ##### --> 65<para> 66Creates a new #GByteArray. 67</para> 68 69@Returns: the new #GByteArray. 70 71 72<!-- ##### FUNCTION g_byte_array_sized_new ##### --> 73<para> 74Creates a new #GByteArray with @reserved_size bytes preallocated. This 75avoids frequent reallocation, if you are going to add many bytes to 76the 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_append ##### --> 84<para> 85Adds the given bytes to the end of the #GByteArray. 86The array will grow in size automatically if necessary. 87</para> 88 89@array: a #GByteArray. 90@data: the byte data to be added. 91@len: the number of bytes to add. 92@Returns: the #GByteArray. 93 94 95<!-- ##### FUNCTION g_byte_array_prepend ##### --> 96<para> 97Adds the given data to the start of the #GByteArray. 98The array will grow in size automatically if necessary. 99</para> 100 101@array: a #GByteArray. 102@data: the byte data to be added. 103@len: the number of bytes to add. 104@Returns: the #GByteArray. 105 106 107<!-- ##### FUNCTION g_byte_array_remove_index ##### --> 108<para> 109Removes the byte at the given index from a #GByteArray. 110The following bytes are moved down one place. 111</para> 112 113@array: a #GByteArray. 114@index_: the index of the byte to remove. 115@Returns: the #GByteArray. 116 117 118<!-- ##### FUNCTION g_byte_array_remove_index_fast ##### --> 119<para> 120Removes the byte at the given index from a #GByteArray. 121The last element in the array is used to fill in the space, so this function 122does not preserve the order of the #GByteArray. But it is faster than 123g_byte_array_remove_index(). 124</para> 125 126@array: a #GByteArray. 127@index_: the index of the byte to remove. 128@Returns: the #GByteArray. 129 130 131<!-- ##### FUNCTION g_byte_array_remove_range ##### --> 132<para> 133Removes the given number of bytes starting at the given index from a 134#GByteArray. The following elements are moved to close the gap. 135</para> 136 137@array: a @GByteArray. 138@index_: the index of the first byte to remove. 139@length: the number of bytes to remove. 140@Returns: the #GByteArray. 141@Since: 2.4 142 143 144<!-- ##### FUNCTION g_byte_array_sort ##### --> 145<para> 146Sorts a byte array, using @compare_func which should be a qsort()-style 147comparison function (returns less than zero for first arg is less than second 148arg, zero for equal, greater than zero if first arg is greater than second 149arg). 150</para> 151<para> 152If two array elements compare equal, their order in the sorted array is 153undefined. 154</para> 155 156@array: a #GByteArray. 157@compare_func: comparison function. 158 159 160<!-- ##### FUNCTION g_byte_array_sort_with_data ##### --> 161<para> 162Like g_byte_array_sort(), but the comparison function takes an extra user data 163argument. 164</para> 165 166@array: a #GByteArray. 167@compare_func: comparison function. 168@user_data: data to pass to @compare_func. 169 170 171<!-- ##### FUNCTION g_byte_array_set_size ##### --> 172<para> 173Sets the size of the #GByteArray, expanding it if necessary. 174</para> 175 176@array: a #GByteArray. 177@length: the new size of the #GByteArray. 178@Returns: the #GByteArray. 179 180 181<!-- ##### FUNCTION g_byte_array_free ##### --> 182<para> 183Frees the memory allocated by the #GByteArray. 184If @free_segment is %TRUE it frees the actual byte data. 185</para> 186 187@array: a #GByteArray. 188@free_segment: if %TRUE the actual byte data is freed as well. 189@Returns: the element data if @free_segment is %FALSE, otherwise %NULL. 190 The element data should be freed using g_free(). 191 192 193