/src/wrappers/glib/partially-implemented/g_array.e
Specman e | 415 lines | 199 code | 71 blank | 145 comment | 0 complexity | 9aa398fe919b05ea13a2fd73b096eaad MD5 | raw file
1indexing 2 description: "Arrays of arbitrary elements which grow automatically as elements are added." 3 copyright: "(C) 2005 Paolo Redaelli " 4 license: "LGPL v2 or later" 5 date: "$Date:$" 6 revision: "$REvision:$" 7 8 -- Description: G_ARRAYS are similar to standard C arrays, 9 -- except that they grow automatically as elements are added. 10 11 -- Array elements can be of any size (though all elements of 12 -- one array are the same size), and the array can be 13 -- automatically cleared to '0's and zero-terminated. 14 15 -- To create a new array use g_array_new(). 16 17 -- To add elements to an array, use g_array_append_val(), 18 -- g_array_append_vals(), g_array_prepend_val(), and 19 -- g_array_prepend_vals(). 20 21 -- To access an element of an array, use g_array_index(). 22 23 -- To set the size of an array, use g_array_set_size(). 24 25 -- To free an array, use g_array_free(). 26 27 -- Example 3. Using a GArray to store gint values 28 29 -- GArray *garray; 30 -- gint i; 31 32 -- /* We create a new array to store gint values. 33 -- We don't want it zero-terminated or cleared to 0's. */ 34 -- garray = g_array_new (FALSE, FALSE, sizeof (gint)); 35 -- for (i = 0; i < 10000; i++) 36 -- g_array_append_val (garray, i); 37 38 -- for (i = 0; i < 10000; i++) 39 -- if (g_array_index (garray, gint, i) != i) 40 -- g_print ("ERROR: got %d instead of %d\n", 41 -- g_array_index (garray, gint, i), i); 42 43 -- g_array_free (garray, TRUE); 44 45 46class G_ARRAY [ITEM->C_STRUCT] 47 48inherit C_STRUCT 49 -- TODO: make it a proper heir of ARRAY, FAST_ARRAY or 50 -- ARRAYED_COLLECTION 51 52insert WRAPPER_FACTORY [ITEM] 53 54creation make, empty, from_external_pointer 55 56feature {} -- Creation 57 58 make (zero_terminated, cleared: BOOLEAN) is 59 -- Creates a new G_ARRAY. `zero_terminated' is True when the 60 -- array should have an extra element at the end which is set 61 -- to 0. `cleared' is True if elements should be 62 -- automatically cleared to 0 when they are allocated. 63 local element_size: INTEGER 64 do 65 -- element_size is the size of each element in bytes. 66 from_external_pointer 67 (g_array_new (zero_terminated.to_integer, 68 cleared.to_integer, 69 element_size)) 70 end 71 72 with_capacity (a_capacity: INTEGER) is 73 -- Creates a new GArray with `a_capacity' elements 74 -- preallocated. This avoids frequent reallocation, if you 75 -- are going to add many elements to the array. Note however 76 -- that the size of the array is still 0. Note: (low level 77 -- details) the array will be zero terminated, i.e. il will 78 -- have an extra element at the end with all bits 79 -- cleared. The allocated memory will be not cleared. 80 require positive_capacity: 81 -- a_capacity > 0 82 local element_size: INTEGER 83 do 84 from_external_pointer 85 (g_array_sized_new (1, -- zero_terminated, 86 0, -- clear_, 87 element_size, 88 a_capacity)) 89 end 90 91feature 92 append (an_item: like first) is 93 -- Adds the value on to the end of the array. The array will 94 -- grow in size automatically if necessary. 95 require item_not_void: an_item /= Void 96 do 97 g_array_append_val(handle,a_value.handle) 98 -- Note: g_array_append_val() is a macro which uses a 99 -- reference to the value parameter v. This means that you cannot use 100 -- it with literal values such as "27". You must use variables. 101 end 102 103 append_values (some_items: ARRAY[ITEM]) is 104 -- Adds `some_elements' onto the end of the array. 105 require 106 items_not_void: some_items /= Void 107 items_not_empty: not some_items.is_empty 108 local ptr: POINTER 109 do 110 ptr:=g_array_append_vals (handle, some_items.to_external, some_items.count) 111 check 112 -- g_array_prepend_vals should return the pointer to the GArray 113 ptr = handle 114 end 115 end 116 117 prepend (an_item: like first) is 118 -- Adds `an_item' on to the start of the array. The array 119 -- will grow in size automatically if necessary. 120 121 -- This operation is slower than `append' since the existing 122 -- elements in the array have to be moved to make space for 123 -- the new element. 124 require item_not_void: an_item /= Void 125 do 126 g_array_prepend_val (handle,an_item.handle) 127 -- Note: g_array_prepend_val() is a macro which uses a 128 -- reference to the value parameter v. This means that you 129 -- cannot use it with literal values such as "27". You must 130 -- use variables. 131 end 132 133 prepend_values (some_items: ARRAY[ITEM]) is 134 -- Adds `some_items' onto the start of the array. 135 136 -- This operation is slower than `append_values' since the 137 -- existing elements in the array have to be moved to make 138 -- space for the new elements. 139 require 140 items_not_void: some_items /= Void 141 items_not_empty: not some_items.is_empty 142 local ptr: POINTER 143 do 144 ptr:=g_array_prepend_vals (handle, some_items.to_external, some_items.count) 145 check 146 -- g_array_prepend_vals should return the pointer to the GArray 147 ptr = handle 148 end 149 end 150 151 insert_value (an_item: ITEM; an_index: INTEGER) is 152 -- Inserts `an_item' into Current array at `an_index'. 153 require 154 item_not_void: an_item /= Void 155 valid_index: is_valid_index (an_index) 156 local ptr: POINTER 157 do 158 ptr:=g_array_insert_val (handle, an_index, an_item.handle) 159 check 160 ptr_is_c_garray: ptr = handle 161 end 162 -- Note: g_array_insert_val() is a macro which uses a 163 -- reference to the value parameter v. This means that you 164 -- cannot use it with literal values such as "27". You must 165 -- use variables. 166 ensure -- TODO: value_put 167 end 168 169 insert_values (some_values: ARRAY[ITEM]; an_index: INTEGER) is 170 -- Inserts `some_values' into Current GArray at `an_index'. 171 require 172 values_not_void: some_values /= Void 173 values_not_empty: not some_values.is_empty 174 local ptr: POINTER 175 do 176 ptr:=g_array_insert_vals(handle, an_index, 177 some_values.to_external, 178 some_values.count) 179 check 180 ptr_is_c_garray: ptr = handle 181 end 182 end 183 184 remove_index (an_index: INTEGER) is 185 -- Removes the element at `an_index' from Current GArray. The 186 -- following elements are moved down one place. 187 require valid_index: is_valid_index (an_index) 188 local ptr: POINTER 189 do 190 ptr:=g_array_remove_index(handle,an_index) 191 check 192 ptr_is_c_garray: ptr = handle 193 end 194 ensure count_decreased: count = old count - 1 195 end 196 197 remove_index_fast (an_index: INTEGER) is 198 -- Removes the element at `an_index' from Current GArray. The 199 -- last element in the array is used to fill in the space, so 200 -- this function does not preserve the order of the 201 -- GArray. But it is faster than `remove_index'. 202 require valid_index: is_valid_index (an_index) 203 local ptr: POINTER 204 do 205 ptr:=g_array_remove_index_fast(handle,an_index) 206 check 207 ptr_is_c_garray: ptr = handle 208 end 209 ensure 210 count_decreased: count = old count - 1 211 last_moved_to_an_index: old last = item(an_index) 212 end 213 214 remove_range (an_index, a_number: INTEGER) is 215 -- Removes `a_number' elements starting at `an_index' from a 216 -- GArray. The following elements are moved to close the gap. 217 require 218 valid_index: is_valid_index (an_index) 219 valid_range: is_valid_index (an_index+a_lenght-1) 220 local ptr: POINTER 221 do 222 ptr:=g_array_remove_range(handle,an_index,a_lenght) 223 check 224 ptr_is_c_garray: ptr = handle 225 end 226 ensure 227 count_decreased: count = old count - a_number 228 end 229 230 -- TODO: sort () 231 232 -- void g_array_sort (GArray *array, GCompareFunc compare_func); 233 234 -- Sorts a GArray using compare_func which should be a 235 -- qsort()-style comparison function (returns -1 for first arg is 236 -- less than second arg, 0 for equal, 1 if first arg is greater 237 -- than second arg). array : a GArray. compare_func : comparison 238 -- function. g_array_sort_with_data () 239 240 -- void g_array_sort_with_data (GArray *array, GCompareDataFunc 241 -- compare_func, gpointer user_data); 242 243 -- Like g_array_sort(), but the comparison function receives a user 244 -- data argument. array : a GArray. compare_func : comparison 245 -- function. user_data : data to pass to compare_func. 246 247 item (an_index: INTEGER): ITEM is 248 -- the element of Current GArray at `an_index'. 249 250 -- Example 4. Getting a pointer to an element in a GArray 251 252 -- EDayViewEvent *event; /* This gets a pointer to the 3rd 253 -- element in the array of EDayViewEvent structs. */ event = 254 -- &g_array_index (events, EDayViewEvent, 3); 255 local ptr: POINTER 256 do 257 ptr := g_array_index(handle,an_index) 258 -- The return value is cast to the given type. 259 ensure implemented: False 260 end 261 262 set_size (a_length: INTEGER) is 263 -- Sets the size of the array, expanding it if necessary. If the array 264 -- was created with `cleared' set to True, the new elements are 265 -- set to Void. 266 require positive_length: a_length >= 0 267 local ptr: POINTER 268 do 269 ptr:=g_array_set_size(handle,a_length) 270 end 271 272 dispose is 273 local p: POINTER 274 do 275 -- g_array_free frees the memory allocated for the GArray. If 276 -- free_segment is TRUE it frees the memory block holding the 277 -- elements as well. Pass FALSE if you want to free the 278 -- GArray wrapper but preserve the underlying array for use 279 -- elsewhere. free_segment : if TRUE the actual element data 280 -- is freed as well. 281 p:=g_array_free (handle, 282 0 -- free_segment=False, i.e. do not 283 -- free the actual data 284 ) 285 unstore_eiffel_wrapper 286 handle:=default_pointer 287 end 288 289feature {} -- External calls 290 struct_size: INTEGER is 291 external "C inline use <glib.h>" 292 alias "sizeof(GArray)" 293 end 294 295 g_array_new (zero_terminated_bool, clear_bool, an_element_size: INTEGER): POINTER is 296 -- GArray* g_array_new (gboolean zero_terminated, gboolean 297 -- clear_, guint element_size); 298 299 -- TODO: an_element_size should be NATURAL 300 external "C use <glib.h>" 301 end 302 303 g_array_sized_new (zero_terminated_bool, clear_bool, an_element_size, a_reserverd_size: INTEGER): POINTER is 304 -- GArray* g_array_sized_new (gboolean zero_terminated, gboolean clear_, guint element_size, guint reserved_size); 305 306 -- TODO: an_element_size should be NATURAL 307 -- TODO: a_reserved_size should be NATURAL 308 external "C use <glib.h>" 309 end 310 311 g_array_append_val (a,v: POINTER) is 312 -- #define g_array_append_val (a,v) 313 external "C macro use <glib.h>" 314 end 315 316 g_array_append_vals (an_array, some_data: INTEGER; a_len: INTEGER): POINTER is 317 -- GArray* g_array_append_vals (GArray *array, gconstpointer 318 -- data, guint len); 319 320 -- TODO: a_len should be NATURAL 321 external "C use <glib.h>" 322 end 323 324 g_array_prepend_val (a,v: POINTER) is 325 -- #define g_array_prepend_val (a,v) 326 external "C macro use <glib.h>" 327 end 328 329 g_array_prepend_vals (an_array, some_data: POINTER; a_len: INTEGER): POINTER is 330 -- GArray* g_array_prepend_vals (GArray *array, gconstpointer 331 -- data, guint len); 332 333 -- TODO: a_len should be NATURAL 334 external "C use <glib.h>" 335 end 336 337 g_array_insert_val (an_array: POINTER; an_index: INTEGER; a_value: POINTER) is 338 -- #define g_array_insert_val (a,i,v) 339 external "C macro use <glib.h>" 340 end 341 342 g_array_insert_vals (an_array: POINTER; guint_index: INTEGER; some_data: POINTER; guint_len: INTEGER): POINTER is 343 -- GArray* g_array_insert_vals (GArray *array, guint index_, 344 -- gconstpointer data, guint len); 345 346 -- TODO: guint_index and guint_len should be NATURALs 347 external "C use <glib.h>" 348 end 349 350 g_array_remove_index (an_array: POINTER; guint_index: INTEGER): POINTER is 351 -- GArray* g_array_remove_index (GArray *array, guint 352 -- index_); 353 354 -- TODO: guint_index should be NATURAL 355 external "C use <glib.h>" 356 end 357 358 g_array_remove_index_fast (an_array: POINTER; guint_index: INTEGER): POINTER is 359 -- GArray* g_array_remove_index_fast (GArray *array, guint 360 -- index_); 361 362 -- TODO: guint_index should be NATURAL 363 364 external "C use <glib.h>" 365 end 366 367 g_array_remove_range (an_array: POINTER; guint_index, guint_length: INTEGER): POINTER is 368 -- GArray* g_array_remove_range (GArray *array, guint index_, 369 -- guint length); 370 371 -- TODO: guint_index and guint_len should be NATURALs 372 external "C use <glib.h>" 373 end 374 375 g_array_sort (an_array, a_compare_func: POINTER) is 376 -- void g_array_sort (GArray *array, GCompareFunc compare_func); 377 external "C use <glib.h>" 378 end 379 380 g_array_sort_with_data (an_array, a_compare_func, some_data: POINTER) is 381 -- void g_array_sort_with_data (GArray *array, 382 -- GCompareDataFunc compare_func, gpointer user_data); 383 external "C use <glib.h>" 384 end 385 386 g_array_index (an_array: POINTER; an_index: INTEGER): POINTER is 387 -- #define g_array_index (a,t,i) 388 external "C macro use <glib.h>" 389 alias "g_array_index ($an_array, (void *), $an_index)" 390 end 391 392 g_array_set_size (an_array: POINTER; a_length): POINTER is 393 -- GArray* g_array_set_size (GArray *array, guint length); 394 395 -- TODO: a_length should be NATURAL 396 external "C use <glib.h>" 397 end 398 399 g_array_free (an_array: POINTER; free_segment_bool: INTEGER): POINTER is 400 -- gchar* g_array_free (GArray *array, gboolean free_segment); 401 external "C use <glib.h>" 402 end 403 404feature {} -- Struct access 405-- GArray 406 407-- typedef struct { 408-- gchar *data; 409-- guint len; 410-- } GArray; 411 412-- Contains the public fields of an Array. 413-- gchar *data; a pointer to the element data. The data may be moved as elements are added to the GArray. 414-- guint len; the number of elements in the GArray. 415end