/src/wrappers/glib/library/data_types/glib_byte_arrays.e

  1indexing
  2	copyright: "(C) 2005 Paolo Redaelli "
  3	license: "LGPL v2 or later"
  4	date: "$Date:$"
  5	revision: "$REvision:$"
  6
  7class GLIB_BYTE_ARRAYS
  8	-- Prev 	Up 	Home 	GLib Reference Manual 	Next
  9-- Top  |  Description
 10-- Byte Arrays
 11
 12-- Byte Arrays %G —%@ arrays of bytes, which grow automatically as elements are added.
 13	
 14-- Synopsis
 15
 16-- #include <glib.h>
 17
 18
 19--             GByteArray;
 20-- GByteArray* g_byte_array_new                (void);
 21-- GByteArray* g_byte_array_sized_new          (guint reserved_size);
 22-- GByteArray* g_byte_array_append             (GByteArray *array,
 23--                                              const guint8 *data,
 24--                                              guint len);
 25-- GByteArray* g_byte_array_prepend            (GByteArray *array,
 26--                                              const guint8 *data,
 27--                                              guint len);
 28-- GByteArray* g_byte_array_remove_index       (GByteArray *array,
 29--                                              guint index_);
 30-- GByteArray* g_byte_array_remove_index_fast  (GByteArray *array,
 31--                                              guint index_);
 32-- GByteArray* g_byte_array_remove_range       (GByteArray *array,
 33--                                              guint index_,
 34--                                              guint length);
 35-- void        g_byte_array_sort               (GByteArray *array,
 36--                                              GCompareFunc compare_func);
 37-- void        g_byte_array_sort_with_data     (GByteArray *array,
 38--                                              GCompareDataFunc compare_func,
 39--                                              gpointer user_data);
 40-- GByteArray* g_byte_array_set_size           (GByteArray *array,
 41--                                              guint length);
 42-- guint8*     g_byte_array_free               (GByteArray *array,
 43--                                              gboolean free_segment);
 44
 45-- Description
 46
 47-- GByteArray is based on GArray, to provide arrays of bytes which grow automatically as elements are added.
 48
 49-- To create a new GByteArray use g_byte_array_new().
 50
 51-- To add elements to a GByteArray, use g_byte_array_append(), and g_byte_array_prepend().
 52
 53-- To set the size of a GByteArray, use g_byte_array_set_size().
 54
 55-- To free a GByteArray, use g_byte_array_free().
 56
 57-- Example 6. Using a GByteArray
 58
 59--   GByteArray *gbarray;
 60--   gint i;
 61
 62--   gbarray = g_byte_array_new ();
 63--   for (i = 0; i < 10000; i++)
 64--     g_byte_array_append (gbarray, (guint8*) "abcd", 4);
 65
 66--   for (i = 0; i < 10000; i++)
 67--     {
 68--       g_assert (gbarray->data[4*i] == 'a');
 69--       g_assert (gbarray->data[4*i+1] == 'b');
 70--       g_assert (gbarray->data[4*i+2] == 'c');
 71--       g_assert (gbarray->data[4*i+3] == 'd');
 72--     }
 73
 74--   g_byte_array_free (gbarray, TRUE);
 75
 76-- Details
 77-- GByteArray
 78
 79-- typedef struct {
 80--   guint8 *data;
 81--   guint	  len;
 82-- } GByteArray;
 83
 84-- The GByteArray struct allows access to the public fields of a GByteArray.
 85-- guint8 *data; 	a pointer to the element data. The data may be moved as elements are added to the GByteArray.
 86-- guint len; 	the number of elements in the GByteArray.
 87-- g_byte_array_new ()
 88
 89-- GByteArray* g_byte_array_new                (void);
 90
 91-- Creates a new GByteArray.
 92-- Returns : 	the new GByteArray.
 93-- g_byte_array_sized_new ()
 94
 95-- GByteArray* g_byte_array_sized_new          (guint reserved_size);
 96
 97-- 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.
 98-- reserved_size : 	number of bytes preallocated.
 99-- Returns : 	the new GByteArray.
100-- g_byte_array_append ()
101
102-- GByteArray* g_byte_array_append             (GByteArray *array,
103--                                              const guint8 *data,
104--                                              guint len);
105
106-- Adds the given bytes to the end of the GByteArray. The array will grow in size automatically if necessary.
107-- array : 	a GByteArray.
108-- data : 	the byte data to be added.
109-- len : 	the number of bytes to add.
110-- Returns : 	the GByteArray.
111-- g_byte_array_prepend ()
112
113-- GByteArray* g_byte_array_prepend            (GByteArray *array,
114--                                              const guint8 *data,
115--                                              guint len);
116
117-- Adds the given data to the start of the GByteArray. The array will grow in size automatically if necessary.
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-- g_byte_array_remove_index ()
123
124-- GByteArray* g_byte_array_remove_index       (GByteArray *array,
125--                                              guint index_);
126
127-- Removes the byte at the given index from a GByteArray. The following bytes are moved down one place.
128-- array : 	a GByteArray.
129-- index_ : 	the index of the byte to remove.
130-- Returns : 	the GByteArray.
131-- g_byte_array_remove_index_fast ()
132
133-- GByteArray* g_byte_array_remove_index_fast  (GByteArray *array,
134--                                              guint index_);
135
136-- 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().
137-- array : 	a GByteArray.
138-- index_ : 	the index of the byte to remove.
139-- Returns : 	the GByteArray.
140-- g_byte_array_remove_range ()
141
142-- GByteArray* g_byte_array_remove_range       (GByteArray *array,
143--                                              guint index_,
144--                                              guint length);
145
146-- Removes the given number of bytes starting at the given index from a GByteArray. The following elements are moved to close the gap.
147-- array : 	a GByteArray.
148-- index_ : 	the index of the first byte to remove.
149-- length : 	the number of bytes to remove.
150-- Returns : 	the GByteArray.
151
152-- Since 2.4
153-- g_byte_array_sort ()
154
155-- void        g_byte_array_sort               (GByteArray *array,
156--                                              GCompareFunc compare_func);
157
158-- Sorts a byte array, using compare_func which should be a qsort()-style comparison function (returns -1 for first arg is less than second arg, 0 for equal, 1 if first arg is greater than second arg).
159-- array : 	a GByteArray.
160-- compare_func : 	comparison function.
161-- g_byte_array_sort_with_data ()
162
163-- void        g_byte_array_sort_with_data     (GByteArray *array,
164--                                              GCompareDataFunc compare_func,
165--                                              gpointer user_data);
166
167-- Like g_byte_array_sort(), but the comparison function takes a user data argument.
168-- array : 	a GByteArray.
169-- compare_func : 	comparison function.
170-- user_data : 	data to pass to compare_func.
171-- g_byte_array_set_size ()
172
173-- GByteArray* g_byte_array_set_size           (GByteArray *array,
174--                                              guint length);
175
176-- Sets the size of the GByteArray, expanding it if necessary.
177-- array : 	a GByteArray.
178-- length : 	the new size of the GByteArray.
179-- Returns : 	the GByteArray.
180-- g_byte_array_free ()
181
182-- guint8*     g_byte_array_free               (GByteArray *array,
183--                                              gboolean free_segment);
184
185-- Frees the memory allocated by the GByteArray. If free_segment is TRUE it frees the actual byte data.
186-- array : 	a GByteArray.
187-- free_segment : 	if TRUE the actual byte data is freed as well.
188-- Returns : 	the element data if free_segment is FALSE, otherwise NULL
189end