/src/wrappers/glib/partially-implemented/g_array.e

  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