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

  1indexing
  2	description: "The GList provides a standard doubly-linked list data %
  3   %structure. See also G_LIST_TRAVERSABLE."
  4	copyright: "2008 Raphael Mack"
  5	license: "LGPL v2 or later"
  6	date: "$Date:$"
  7	revision: "$Revision:$"
  8
  9deferred class G_LIST [ITEM->WRAPPER]
 10
 11   -- TODO: add test for all COLLECTION features (modify the version 
 12   -- from SE testsuite?)
 13   
 14	-- Some GLib-using libraries requires that some instances of
 15	-- GList shall be modified only by the library, making it
 16	-- effectively freezed for the developer. In those cases
 17	-- G_LIST_TRAVERSABLE shall be used in place of G_LIST.  If the
 18	-- library allows its clients to change the lists it returns it
 19	-- will return a G_LIST.
 20  
 21
 22inherit
 23	G_LIST_TRAVERSABLE[ITEM]
 24		undefine
 25			out_in_tagged_out_memory,
 26			fill_tagged_out_memory
 27		end
 28	COLLECTION[ITEM]
 29		undefine
 30			swap,
 31			has,
 32			fast_has,
 33			clear_all,
 34			append_collection
 35	  end
 36feature
 37	put (an_item: like first; i: INTEGER) is
 38         --
 39      do
 40         glist_struct_set_data (g_list_nth(handle,i.to_natural_32), an_item.handle)
 41      end
 42   
 43	swap (i,j: INTEGER) is
 44         -- exchange two elements
 45      local
 46         ith,jth,tmp: POINTER
 47		 in,jn: NATURAL_32
 48      do
 49		 in := i.to_natural_32; jn := j.to_natural_32
 50         ith := g_list_nth_data (handle,in)
 51         jth := g_list_nth_data (handle,jn)
 52
 53         tmp := glist_struct_get_data(ith)
 54         glist_struct_set_data (ith, glist_struct_get_data(jth))
 55         glist_struct_set_data (jth, tmp)
 56      end
 57
 58	set_all_with (v: like first) is
 59			--
 60		local
 61         ith:POINTER
 62		do
 63			from ith:=handle
 64			until ith.is_null
 65			loop
 66				glist_struct_set_data (ith, v.handle)
 67				ith := glist_struct_get_next (ith)
 68			end
 69		end
 70
 71	clear_all is do not_yet_implemented end
 72
 73	add_first (element: like first) is
 74			-- 
 75		do
 76			handle := g_list_prepend (handle, element.handle)
 77		end
 78
 79	add_last (element: like first) is
 80         -- Note that add_last has to traverse the entire list to find
 81         -- the end, which is inefficient when adding multiple
 82         -- elements. A common idiom to avoid the inefficiency is to
 83         -- prepend the elements and reverse the list when all
 84         -- elements have been added.
 85      do
 86         handle := g_list_append (handle, element.handle)
 87		end
 88
 89	add (element: like first; an_index: INTEGER) is
 90		do
 91			handle := g_list_insert (handle, element.handle, an_index)
 92		end
 93	
 94	append_collection (other: COLLECTION[ITEM]) is
 95		do
 96			other.do_all(agent add_last)
 97		end
 98
 99	force (element: like first; an_index: INTEGER) is
100      do
101         not_yet_implemented
102         -- TODO
103      end
104
105	remove_first is
106		require not is_empty
107		do
108			handle:=g_list_delete_link (handle, handle)
109		end
110
111	remove (an_index: INTEGER) is
112		require 
113			not is_empty
114			valid_index(an_index)
115		do
116			handle:=g_list_delete_link (handle, g_list_nth_data (handle, an_index.to_natural_32))
117		end
118
119	remove_head (n: INTEGER) is
120		require 
121			n < count	
122		do
123			-- Ohh, how long I longed to write it *THIS* way! Thanks Adrian! Paolo 2010-05-30
124			n.times(agent remove_first)
125		end
126
127	remove_tail (n: INTEGER) is
128		require 
129			n < count 
130		do
131			-- Ohh, how long I longed to write it *THIS* way! Thanks Adrian! Paolo 2010-05-30
132			n.times(agent remove_last)
133		end
134
135	remove_last is
136		require 
137			not is_empty
138		do
139			handle:=g_list_delete_link (handle,g_list_last (handle))
140		end
141
142	clear_count, clear_count_and_capacity is
143			-- Discard all items (is_empty is True after that call). Frees
144			-- all of the memory used by a GList. The freed elements are
145			-- added to the GAllocator free list.
146		do
147			g_list_free (handle)
148			handle := default_pointer
149		end
150
151	replace_all (old_value, new_value: like first) is
152		do
153			not_yet_implemented -- TODO
154		end
155
156	fast_replace_all (old_value, new_value: like first) is
157		do
158			not_yet_implemented -- TODO
159		end
160
161	reverse is
162		local old_handle: POINTER
163		do
164			old_handle := handle
165			handle:=g_list_reverse (old_handle)
166		end
167
168	append (an_item: like first) is
169			-- Adds `an_item' on to the end of the list.
170		do
171			handle:=g_list_append (handle, an_item.handle)
172
173			-- Note: The return value is the new start of the list, which may have changed, so make sure you store the new value.
174			
175			-- Note: g_list_append() has to traverse the entire list to
176			-- find the end, which is inefficient when adding multiple
177			-- elements. A common idiom to avoid the inefficiency is to
178			-- prepend the elements and reverse the list when all
179			-- elements have been added.
180
181			--   /* Notice that these are initialized to the empty list. */
182			--   GList *list = NULL, *number_list = NULL;
183			
184			--   /* This is a list of strings. */
185			--   list = g_list_append (list, "first");
186			--   list = g_list_append (list, "second");
187			
188			--   /* This is a list of integers. */
189			--   number_list = g_list_append (number_list, GINT_TO_POINTER (27));
190			--   number_list = g_list_append (number_list, GINT_TO_POINTER (14));
191		end
192
193	prepend  (an_item: like first) is
194			-- Adds a new element on to the start of the list.
195		require valid_item: an_item/=Void
196		do
197			handle := g_list_prepend (handle,an_item.handle)
198			-- Note: The return value is the new start of the list, which
199			-- may have changed, so make sure you store the new value.
200
201			-- /* Notice that it is initialized to the empty list. */
202			-- GList *list = NULL; list = g_list_prepend (list,
203			-- "last"); list = g_list_prepend (list, "first");
204		end
205
206
207-- g_list_insert ()
208
209-- GList*     g_list_insert                  (GList *list, gpointer data, gint position);
210
211-- Inserts a new element into the list at the given position.
212-- list : 	a GList.
213-- data : 	the data for the new element.
214-- 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.
215-- Returns : 	the new start of the GList.
216-- g_list_insert_before ()
217
218-- GList*     g_list_insert_before           (GList *slist, GList *sibling, gpointer data);
219
220-- Inserts a node before sibling containing data. Returns the new head of the list.
221-- slist : 	a GList.
222-- sibling : 	node to insert data before.
223-- data : 	data to put in the newly-inserted node.
224-- Returns : 	new head of the list.
225-- g_list_insert_sorted ()
226
227-- GList*     g_list_insert_sorted           (GList *list, gpointer data, GCompareFunc func);
228
229-- Inserts a new element into the list, using the given comparison function to determine its position.
230-- list : 	a GList.
231-- data : 	the data for the new element.
232-- 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.
233-- Returns : 	the new start of the GList.
234-- g_list_remove ()
235
236-- GList*     g_list_remove                  (GList *list, gconstpointer data);
237
238-- Removes an element from a GList. If two elements contain the same data, only the first is removed. If none of the elements contain the data, the GList is unchanged.
239-- list : 	a GList.
240-- data : 	the data of the element to remove.
241-- Returns : 	the new start of the GList.
242-- g_list_remove_link ()
243
244-- GList*     g_list_remove_link             (GList *list, GList *link_);
245
246-- Removes an element from a GList, 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.
247-- list : 	a GList.
248-- link_ : 	an element in the GList.
249-- Returns : 	the new start of the GList, without the element.
250-- g_list_delete_link ()
251
252-- GList*     g_list_delete_link             (GList *list, GList *link_);
253
254-- Deletes a node of list. Returns the new list head.
255-- list : 	a GList.
256-- link_ : 	node to delete.
257-- Returns : 	new head of list.
258-- g_list_remove_all ()
259
260-- GList*     g_list_remove_all              (GList *list, gconstpointer data);
261
262-- Removes all list nodes with data equal to data. Returns the new head of the list. Contrast with g_list_remove() which removes only the first node matching the given data.
263-- list : 	a GList.
264-- data : 	data to remove.
265-- Returns : 	new head of list.
266
267
268end