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

  1indexing
  2	description: "The GSList provides a standard singly-linked list data structure. See also G_SLIST, G_LIST"
  3	copyright: "(C) 2006, 2008 Paolo Redaelli, Raphael Mack"
  4	license: "LGPL v2 or later"
  5	date: "$Date: 2008-11-30 00:48:25 +0100 (dom, 30 nov 2008) $"
  6	revision: "$Revision: 1101 $"
  7
  8deferred class G_SLIST_TRAVERSABLE [ITEM->WRAPPER]
  9	-- A singly-linked list data structure.
 10	
 11	-- To add elements, use `add_last', `append', `add_first', `prepend',
 12	-- `add' and (TODO `insert_sorted').
 13
 14	-- To remove elements, use `remove', `remove_first' and `remove_last'.
 15
 16	-- To find elements in the list use `last', (TODO: `next'), 
 17	-- `item', `fast_has' (PS: `has' calls `fast_has' in turn), `first_index_of'.
 18
 19	-- To find the index of an element use TODO: g_slist_position() and
 20	-- g_slist_index().
 21	
 22	-- TODO: To call a function for each element in the list use
 23	-- g_slist_foreach().
 24	
 25	-- To free the entire list, use g_slist_free().
 26
 27inherit
 28	WRAPPER
 29   
 30   TRAVERSABLE[ITEM]
 31      undefine
 32         copy
 33      redefine
 34         is_equal
 35      end
 36   
 37   WRAPPER_FACTORY[ITEM]
 38
 39insert
 40	GSLIST_EXTERNALS 
 41		undefine
 42			fill_tagged_out_memory
 43		end
 44	GSLIST_STRUCT
 45
 46feature
 47	-- At C level a NULL pointer is considered to be the empty list so
 48	-- you simply set a GSList* to NULL.
 49
 50	-- Note that most of the low-level C GSList functions expect to be
 51	-- passed a pointer to the first element in the list. The functions
 52	-- which insert elements return the new start of the list, which
 53	-- may have changed.
 54
 55	make, make_empty is
 56		do
 57			handle := default_pointer
 58		end
 59
 60	first: ITEM is
 61		local p: POINTER -- Item Pointer
 62		do
 63			p:=gslist_struct_get_data (handle)
 64			if p.is_not_null then Result := wrapper(p) end
 65		end
 66
 67	last: like first is
 68		local
 69         p: POINTER -- Item Pointer
 70		do
 71			p := gslist_struct_get_data (g_slist_last (handle))
 72			if p.is_not_null then
 73            Result := wrapper(p)
 74         end
 75		end
 76
 77	item (i: INTEGER): like first is
 78		local p: POINTER -- Item Pointer
 79		do
 80			p:=g_slist_nth_data (handle, i.to_natural_32)
 81			if p.is_not_null then Result:=wrapper(p) end
 82		end
 83
 84	has (x: like first): BOOLEAN is
 85			-- Look for x using is_equal for comparison. Note: current
 86			-- implementation is just a copy of `fast_has'; try using
 87			-- `fast_has' whenever possible since an implementation of
 88			-- `has' that really uses `is_equal' will be quite slow.
 89		do
 90			Result:=fast_has(x)
 91		end
 92	
 93	fast_has (x: like first): BOOLEAN is
 94			-- Look for x using basic = for comparison.
 95		do
 96			if (g_slist_find(handle,x.handle).is_not_null)
 97			then Result:=True
 98			else check Result=False end
 99			end
100		end
101	
102	first_index_of (element: like first): INTEGER is
103			-- Give the an_index of the first occurrence of element using
104			-- is_equal for comparison. Answer upper + 1 when element is
105			-- not inside.
106		do
107			Result:=g_slist_index(handle,element.handle)
108		end
109
110	an_index_of (element: like first;  start_index: INTEGER ): INTEGER is
111		do
112			Result:= g_slist_index(g_slist_nth(handle,start_index.to_natural_32),element.handle)
113		end
114
115	reverse_index_of (element: like first; start_index: INTEGER): INTEGER is do not_yet_implemented end
116
117	fast_first_index_of (element: like first): INTEGER is
118			-- Give the an_index of the first occurrence of element using
119			-- basic = for comparison. Answer upper + 1 when element is
120			-- not inside.
121		do
122			not_yet_implemented -- TODO
123		end
124
125	fast_index_of (element: like first; start_index: INTEGER): INTEGER is do not_yet_implemented end
126
127	fast_reverse_index_of (element: like first; start_index: INTEGER): INTEGER  is
128			-- Using basic = comparison, gives the an_index of the first
129			-- occurrence of element at or before start_index. Search is
130			-- done in reverse direction, which means from the
131			-- start_index down to the lower an_index . Answer lower -1 when
132			-- the search fail.
133		do
134			not_yet_implemented -- TODO
135		end
136
137   
138	is_equal_map (other: like Current): BOOLEAN is
139			-- Do both collections have the same lower, upper, and items?
140		do
141			Result := is_equal(other)
142		end
143
144	is_equal (other: like Current): BOOLEAN is
145			-- Do both collections have the same lower, upper, and items?
146      local
147		  ci, oi: ITERATOR[ITEM]
148         i, j: INTEGER
149		do
150			if count = other.count and then
151				lower = other.lower then
152				check
153					upper = other.upper 
154					-- shall be implied by the previous two checks
155				end
156				from 
157					ci:=new_iterator; ci.start
158					oi:=new_iterator; oi.start
159				until not Result or else ci.is_off 
160				loop
161					Result := (ci.item = oi.item)
162					ci.next; oi.next
163				end
164			end
165		end
166
167	all_default: BOOLEAN is
168			--	Do all items have their type s default value? Note: for
169			--	non Void items, the test is performed with the is_default
170			--	predicate.
171		do
172			not_yet_implemented -- TODO
173		end
174
175	copy (other: like Current) is
176		do
177			not_yet_implemented -- TODO
178		end
179
180	occurrences (element: like first): INTEGER is
181			-- Number of occurrences of element using is_equal for comparison.
182		do
183			not_yet_implemented -- TODO
184		end
185
186	fast_occurrences (element: like first): INTEGER is 
187		do
188			not_yet_implemented -- TODO
189		end
190	
191	
192	lower: INTEGER is 0
193
194	upper: INTEGER is
195		do
196			Result:=count-1
197		end
198	
199	count: INTEGER_32 is 
200		do
201			Result:=g_slist_length(handle).to_integer_32
202			--	ensure positive: Result >= 0 
203		end
204
205	is_empty: BOOLEAN is 
206		do
207			Result:= (handle.is_null)
208		end
209	
210
211	new_iterator: ITERATOR[ITEM] is 
212		do
213			create {ITERATOR_ON_G_SLIST[ITEM]} Result.make (Current)
214		end
215
216feature {} -- Memory management
217
218	dispose is
219		do
220			-- We override the default dispose routine; list nodes are not
221			-- allocated with malloc() so we should not use free()
222			g_slist_free (handle)
223			handle:= default_pointer
224		end
225
226	-- Glib's doc, useful for implementing unimplemented
227	
228-- typedef struct {
229--   gpointer data;
230--   GSList *next;
231-- } GSList;
232
233-- The GSList struct is used for each element in the singly-linked list.
234	-- gpointer data; 	holds the element's data, which can be a pointer to any kind of data, or any integer value using the Type Conversion Macros.
235	-- GSList *next; 	contains the link to the next element in the list.
236	-- g_slist_alloc ()
237
238-- GSList*     g_slist_alloc                   (void);
239
240-- Allocates space for one GSList element. It is called by the g_slist_append(), g_slist_prepend(), g_slist_insert() and g_slist_insert_sorted() functions and so is rarely used on its own.
241-- Returns : 	a pointer to the newly-allocated GSList element.
242
243
244-- g_slist_insert ()
245
246-- GSList*     g_slist_insert                  (GSList *list, gpointer data, gint position);
247
248-- Inserts a new element into the list at the given position.
249-- list : 	a GSList.
250-- data : 	the data for the new element.
251-- position : 	the position to insert the element. If this is negative, or is larger than the number of elements in the list, the new element is added on to the end of the list.
252-- Returns : 	the new start of the GSList.
253-- g_slist_insert_before ()
254
255-- GSList*     g_slist_insert_before           (GSList *slist, GSList *sibling, gpointer data);
256
257-- Inserts a node before sibling containing data. Returns the new head of the list.
258-- slist : 	a GSList.
259-- sibling : 	node to insert data before.
260-- data : 	data to put in the newly-inserted node.
261-- Returns : 	new head of the list.
262-- g_slist_insert_sorted ()
263
264-- GSList*     g_slist_insert_sorted           (GSList *list, gpointer data, GCompareFunc func);
265
266-- Inserts a new element into the list, using the given comparison function to determine its position.
267-- list : 	a GSList.
268-- data : 	the data for the new element.
269-- func : 	the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order.
270-- Returns : 	the new start of the GSList.
271-- g_slist_remove ()
272
273-- GSList*     g_slist_remove                  (GSList *list, gconstpointer data);
274
275-- Removes an element from a GSList. If two elements contain the same data, only the first is removed. If none of the elements contain the data, the GSList is unchanged.
276-- list : 	a GSList.
277-- data : 	the data of the element to remove.
278-- Returns : 	the new start of the GSList.
279-- g_slist_remove_link ()
280
281-- GSList*     g_slist_remove_link             (GSList *list, GSList *link_);
282
283-- Removes an element from a GSList, without freeing the element. The removed element's next link is set to NULL, so that it becomes a self-contained list with one element.
284-- list : 	a GSList.
285-- link_ : 	an element in the GSList.
286-- Returns : 	the new start of the GSList, without the element.
287-- g_slist_delete_link ()
288
289-- GSList*     g_slist_delete_link             (GSList *list, GSList *link_);
290
291-- Deletes a node of list. Returns the new list head.
292-- list : 	a GSList.
293-- link_ : 	node to delete.
294-- Returns : 	new head of list.
295-- g_slist_remove_all ()
296
297-- GSList*     g_slist_remove_all              (GSList *list, gconstpointer data);
298
299-- Removes all list nodes with data equal to data. Returns the new head of the list. Contrast with g_slist_remove() which removes only the first node matching the given data.
300-- list : 	a GSList.
301-- data : 	data to remove.
302-- Returns : 	new head of list.
303-- g_slist_free ()
304
305-- void        g_slist_free                    (GSList *list);
306
307-- Frees all of the memory used by a GSList. The freed elements are added to the GAllocator free list.
308-- list : 	a GSList.
309-- g_slist_free_1 ()
310
311-- void        g_slist_free_1                  (GSList *list);
312
313-- Frees one GSList element. It is usually used after g_slist_remove_link().
314-- list : 	a GSList element.
315-- g_slist_length ()
316
317-- guint       g_slist_length                  (GSList *list);
318
319-- Gets the number of elements in a GSList.
320-- list : 	a GSList.
321-- Returns : 	the number of elements in the GSList.
322-- g_slist_copy ()
323
324-- GSList*     g_slist_copy                    (GSList *list);
325
326-- Copies a GSList.
327
328-- Note that this is a "shallow" copy. If the list elements consist of pointers to data, the pointers are copied but the actual data isn't.
329-- list : 	a GSList.
330-- Returns : 	a copy of list.
331-- g_slist_reverse ()
332
333-- GSList*     g_slist_reverse                 (GSList *list);
334
335-- Reverses a GSList.
336-- list : 	a GSList.
337-- Returns : 	the start of the reversed GSList.
338-- g_slist_sort ()
339
340-- GSList*     g_slist_sort                    (GSList *list, GCompareFunc compare_func);
341
342-- Sorts a GSList using the given comparison function.
343-- list : 	a GSList.
344-- compare_func : 	the comparison function used to sort the GSList. This function is passed the data from 2 elements of the GSList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if the first element comes after the second.
345-- Returns : 	the start of the sorted GSList.
346-- g_slist_sort_with_data ()
347
348-- GSList*     g_slist_sort_with_data          (GSList *list, GCompareDataFunc compare_func, gpointer user_data);
349
350-- Like g_slist_sort(), but the sort function accepts a user data argument.
351-- list : 	a GSList
352-- compare_func : 	comparison function.
353-- user_data : 	data to pass to comparison function.
354-- Returns : 	new head of the list.
355-- g_slist_concat ()
356
357-- GSList*     g_slist_concat                  (GSList *list1, GSList *list2);
358
359-- Adds the second GSList onto the end of the first GSList. Note that the elements of the second GSList are not copied. They are used directly.
360-- list1 : 	a GSList.
361-- list2 : 	the GSList to add to the end of the first GSList.
362-- Returns : 	the start of the new GSList.
363-- g_slist_foreach ()
364
365-- void        g_slist_foreach                 (GSList *list, GFunc func, gpointer user_data);
366
367-- Calls a function for each element of a GSList.
368-- list : 	a GSList.
369-- func : 	the function to call with each element's data.
370-- user_data : 	user data to pass to the function.
371-- g_slist_last ()
372
373-- GSList*     g_slist_last                    (GSList *list);
374
375-- Gets the last element in a GSList.
376-- list : 	a GSList.
377-- Returns : 	the last element in the GSList, or NULL if the GSList has no elements.
378-- g_slist_next()
379
380-- #define     g_slist_next(slist)
381
382-- A convenience macro to gets the next element in a GSList.
383-- slist : 	an element in a GSList.
384-- Returns : 	the next element, or NULL if there are no more elements.
385-- g_slist_nth ()
386
387-- GSList*     g_slist_nth                     (GSList *list, guint n);
388
389-- Gets the element at the given position in a GSList.
390-- list : 	a GSList.
391-- n : 	the position of the element, counting from 0.
392-- Returns : 	the element, or NULL if the position is off the end of the GSList.
393-- g_slist_nth_data ()
394
395-- gpointer    g_slist_nth_data                (GSList *list, guint n);
396
397-- Gets the data of the element at the given position.
398-- list : 	a GSList.
399-- n : 	the position of the element.
400-- Returns : 	the element's data, or NULL if the position is off the end of the GSList.
401-- g_slist_find ()
402
403-- GSList*     g_slist_find                    (GSList *list, gconstpointer data);
404
405-- Finds the element in a GSList which contains the given data.
406-- list : 	a GSList.
407-- data : 	the element data to find.
408-- Returns : 	the found GSList element, or NULL if it is not found.
409-- g_slist_find_custom ()
410
411-- GSList*     g_slist_find_custom             (GSList *list, gconstpointer data, GCompareFunc func);
412
413-- Finds an element in a GSList, using a supplied function to find the desired element. It iterates over the list, calling the given function which should return 0 when the desired element is found. The function takes two gconstpointer arguments, the GSList element's data as the first argument and the given user data.
414-- list : 	a GSList.
415-- data : 	user data passed to the function.
416-- func : 	the function to call for each element. It should return 0 when the desired element is found.
417-- Returns : 	the found GSList element, or NULL if it is not found.
418-- g_slist_position ()
419
420-- gint        g_slist_position                (GSList *list, GSList *llink);
421
422-- Gets the position of the given element in the GSList (starting from 0).
423-- list : 	a GSList.
424-- llink : 	an element in the GSList.
425-- Returns : 	the position of the element in the GSList, or -1 if the element is not found.
426-- g_slist_index ()
427
428-- gint        g_slist_index                   (GSList *list, gconstpointer data);
429
430-- Gets the position of the element containing the given data (starting from 0).
431-- list : 	a GSList.
432-- data : 	the data to find.
433-- Returns : 	the an_index of the element containing the data, or -1 if the data is not found.
434-- g_slist_push_allocator ()
435
436-- void        g_slist_push_allocator          (GAllocator *allocator);
437
438-- Sets the allocator to use to allocate GSList elements. Use g_slist_pop_allocator() to restore the previous allocator.
439
440-- Note that this function is not available if GLib has been compiled with --disable-mem-pools
441-- allocator : 	the GAllocator to use when allocating GSList elements.
442-- g_slist_pop_allocator ()
443
444-- void        g_slist_pop_allocator           (void);
445
446-- Restores the previous GAllocator, used when allocating GSList elements.
447
448-- Note that this function is not available if GLib has been compiled with --disable-mem-pools
449
450	manifest_put (an_index: INTEGER; element: like item) is
451		do
452			not_yet_implemented 
453		end
454
455end
456
457
458