/src/wrappers/glib/library/data_types/g_slist_traversable.e
Specman e | 458 lines | 145 code | 108 blank | 205 comment | 7 complexity | 39d68193e998ae4d0e099cf48a618845 MD5 | raw file
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