1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module glib.ListSG; 26 27 private import glib.Str; 28 private import glib.c.functions; 29 public import glib.c.types; 30 private import gobject.ObjectG; 31 public import gtkc.glibtypes; 32 33 34 /** 35 * The #GSList struct is used for each element in the singly-linked 36 * list. 37 */ 38 public class ListSG 39 { 40 /** the main Gtk struct */ 41 protected GSList* gSList; 42 protected bool ownedRef; 43 44 /** Get the main Gtk struct */ 45 public GSList* getListSGStruct(bool transferOwnership = false) 46 { 47 if (transferOwnership) 48 ownedRef = false; 49 return gSList; 50 } 51 52 /** the main Gtk struct as a void* */ 53 protected void* getStruct() 54 { 55 return cast(void*)gSList; 56 } 57 58 /** 59 * Sets our main struct and passes it to the parent class. 60 */ 61 public this (GSList* gSList, bool ownedRef = false) 62 { 63 this.gSList = gSList; 64 this.ownedRef = ownedRef; 65 } 66 67 /** */ 68 @property void* data() 69 { 70 return gSList.data; 71 } 72 73 /** 74 * get the next element 75 * Returns: the next element, or NULL if there are no more elements. 76 */ 77 @property ListSG next() 78 { 79 if ( gSList.next is null ) 80 { 81 return null; 82 } 83 84 return new ListSG(gSList.next); 85 } 86 87 /** 88 * Turn the list into a D array of the desiered type. 89 * Type T wraps should match the type of the data. 90 */ 91 public T[] toArray(T, TC = getCType!T)() 92 if ( is(T == class) ) 93 { 94 T[] arr = new T[length()]; 95 ListSG list = this; 96 size_t count; 97 98 while(list !is null && count < arr.length) 99 { 100 arr[count] = ObjectG.getDObject!(T)(cast(TC)list.data); 101 list = list.next(); 102 count++; 103 } 104 105 return arr; 106 } 107 108 /** Ditto */ 109 public T[] toArray(T)() 110 if ( is ( T == string ) ) 111 { 112 T[] arr = new T[length()]; 113 ListSG list = this; 114 size_t count; 115 116 while(list !is null && count < arr.length) 117 { 118 arr[count] = Str.toString(cast(char*)list.data); 119 list = list.next(); 120 count++; 121 } 122 123 return arr; 124 } 125 126 private template getCType(T) 127 { 128 static if ( is(T == class) ) 129 alias getCType = typeof(T.tupleof[0]); 130 else 131 alias getCType = void*; 132 } 133 134 unittest 135 { 136 import gobject.Value; 137 138 auto list = new ListSG(null); 139 list = list.append(new Value(0).getValueStruct()); 140 list = list.append(new Value(1).getValueStruct()); 141 auto arr = list.toArray!Value(); 142 143 assert(arr[0].getInt() == 0); 144 assert(arr[1].getInt() == 1); 145 146 list = new ListSG(null); 147 list = list.append(cast(void*)"test\0".ptr); 148 list = list.append(cast(void*)"test2\0".ptr); 149 150 assert(["test", "test2"] == list.toArray!string()); 151 } 152 153 /** 154 */ 155 156 /** 157 * Allocates space for one #GSList element. It is called by the 158 * g_slist_append(), g_slist_prepend(), g_slist_insert() and 159 * g_slist_insert_sorted() functions and so is rarely used on its own. 160 * 161 * Returns: a pointer to the newly-allocated #GSList element. 162 */ 163 public static ListSG alloc() 164 { 165 auto p = g_slist_alloc(); 166 167 if(p is null) 168 { 169 return null; 170 } 171 172 return new ListSG(cast(GSList*) p); 173 } 174 175 /** 176 * Adds a new element on to the end of the list. 177 * 178 * The return value is the new start of the list, which may 179 * have changed, so make sure you store the new value. 180 * 181 * Note that g_slist_append() has to traverse the entire list 182 * to find the end, which is inefficient when adding multiple 183 * elements. A common idiom to avoid the inefficiency is to prepend 184 * the elements and reverse the list when all elements have been added. 185 * 186 * |[<!-- language="C" --> 187 * // Notice that these are initialized to the empty list. 188 * GSList *list = NULL, *number_list = NULL; 189 * 190 * // This is a list of strings. 191 * list = g_slist_append (list, "first"); 192 * list = g_slist_append (list, "second"); 193 * 194 * // This is a list of integers. 195 * number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); 196 * number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); 197 * ]| 198 * 199 * Params: 200 * data = the data for the new element 201 * 202 * Returns: the new start of the #GSList 203 */ 204 public ListSG append(void* data) 205 { 206 auto p = g_slist_append(gSList, data); 207 208 if(p is null) 209 { 210 return null; 211 } 212 213 return new ListSG(cast(GSList*) p); 214 } 215 216 /** 217 * Adds the second #GSList onto the end of the first #GSList. 218 * Note that the elements of the second #GSList are not copied. 219 * They are used directly. 220 * 221 * Params: 222 * list2 = the #GSList to add to the end of the first #GSList 223 * 224 * Returns: the start of the new #GSList 225 */ 226 public ListSG concat(ListSG list2) 227 { 228 auto p = g_slist_concat(gSList, (list2 is null) ? null : list2.getListSGStruct()); 229 230 if(p is null) 231 { 232 return null; 233 } 234 235 return new ListSG(cast(GSList*) p); 236 } 237 238 /** 239 * Copies a #GSList. 240 * 241 * Note that this is a "shallow" copy. If the list elements 242 * consist of pointers to data, the pointers are copied but 243 * the actual data isn't. See g_slist_copy_deep() if you need 244 * to copy the data as well. 245 * 246 * Returns: a copy of @list 247 */ 248 public ListSG copy() 249 { 250 auto p = g_slist_copy(gSList); 251 252 if(p is null) 253 { 254 return null; 255 } 256 257 return new ListSG(cast(GSList*) p); 258 } 259 260 /** 261 * Makes a full (deep) copy of a #GSList. 262 * 263 * In contrast with g_slist_copy(), this function uses @func to make a copy of 264 * each list element, in addition to copying the list container itself. 265 * 266 * @func, as a #GCopyFunc, takes two arguments, the data to be copied and a user 267 * pointer. It's safe to pass #NULL as user_data, if the copy function takes only 268 * one argument. 269 * 270 * For instance, if @list holds a list of GObjects, you can do: 271 * |[<!-- language="C" --> 272 * another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL); 273 * ]| 274 * 275 * And, to entirely free the new list, you could do: 276 * |[<!-- language="C" --> 277 * g_slist_free_full (another_list, g_object_unref); 278 * ]| 279 * 280 * Params: 281 * func = a copy function used to copy every element in the list 282 * userData = user data passed to the copy function @func, or #NULL 283 * 284 * Returns: a full copy of @list, use #g_slist_free_full to free it 285 * 286 * Since: 2.34 287 */ 288 public ListSG copyDeep(GCopyFunc func, void* userData) 289 { 290 auto p = g_slist_copy_deep(gSList, func, userData); 291 292 if(p is null) 293 { 294 return null; 295 } 296 297 return new ListSG(cast(GSList*) p); 298 } 299 300 /** 301 * Removes the node link_ from the list and frees it. 302 * Compare this to g_slist_remove_link() which removes the node 303 * without freeing it. 304 * 305 * Removing arbitrary nodes from a singly-linked list requires time 306 * that is proportional to the length of the list (ie. O(n)). If you 307 * find yourself using g_slist_delete_link() frequently, you should 308 * consider a different data structure, such as the doubly-linked 309 * #GList. 310 * 311 * Params: 312 * link = node to delete 313 * 314 * Returns: the new head of @list 315 */ 316 public ListSG deleteLink(ListSG link) 317 { 318 auto p = g_slist_delete_link(gSList, (link is null) ? null : link.getListSGStruct()); 319 320 if(p is null) 321 { 322 return null; 323 } 324 325 return new ListSG(cast(GSList*) p); 326 } 327 328 /** 329 * Finds the element in a #GSList which 330 * contains the given data. 331 * 332 * Params: 333 * data = the element data to find 334 * 335 * Returns: the found #GSList element, 336 * or %NULL if it is not found 337 */ 338 public ListSG find(void* data) 339 { 340 auto p = g_slist_find(gSList, data); 341 342 if(p is null) 343 { 344 return null; 345 } 346 347 return new ListSG(cast(GSList*) p); 348 } 349 350 /** 351 * Finds an element in a #GSList, using a supplied function to 352 * find the desired element. It iterates over the list, calling 353 * the given function which should return 0 when the desired 354 * element is found. The function takes two #gconstpointer arguments, 355 * the #GSList element's data as the first argument and the 356 * given user data. 357 * 358 * Params: 359 * data = user data passed to the function 360 * func = the function to call for each element. 361 * It should return 0 when the desired element is found 362 * 363 * Returns: the found #GSList element, or %NULL if it is not found 364 */ 365 public ListSG findCustom(void* data, GCompareFunc func) 366 { 367 auto p = g_slist_find_custom(gSList, data, func); 368 369 if(p is null) 370 { 371 return null; 372 } 373 374 return new ListSG(cast(GSList*) p); 375 } 376 377 alias foreac = foreach_; 378 /** 379 * Calls a function for each element of a #GSList. 380 * 381 * It is safe for @func to remove the element from @list, but it must 382 * not modify any part of the list after that element. 383 * 384 * Params: 385 * func = the function to call with each element's data 386 * userData = user data to pass to the function 387 */ 388 public void foreach_(GFunc func, void* userData) 389 { 390 g_slist_foreach(gSList, func, userData); 391 } 392 393 /** 394 * Frees all of the memory used by a #GSList. 395 * The freed elements are returned to the slice allocator. 396 * 397 * If list elements contain dynamically-allocated memory, 398 * you should either use g_slist_free_full() or free them manually 399 * first. 400 */ 401 public void free() 402 { 403 g_slist_free(gSList); 404 } 405 406 /** 407 * Frees one #GSList element. 408 * It is usually used after g_slist_remove_link(). 409 */ 410 public void free1() 411 { 412 g_slist_free_1(gSList); 413 } 414 415 /** 416 * Convenience method, which frees all the memory used by a #GSList, and 417 * calls the specified destroy function on every element's data. 418 * 419 * @free_func must not modify the list (eg, by removing the freed 420 * element from it). 421 * 422 * Params: 423 * freeFunc = the function to be called to free each element's data 424 * 425 * Since: 2.28 426 */ 427 public void freeFull(GDestroyNotify freeFunc) 428 { 429 g_slist_free_full(gSList, freeFunc); 430 } 431 432 /** 433 * Gets the position of the element containing 434 * the given data (starting from 0). 435 * 436 * Params: 437 * data = the data to find 438 * 439 * Returns: the index of the element containing the data, 440 * or -1 if the data is not found 441 */ 442 public int index(void* data) 443 { 444 return g_slist_index(gSList, data); 445 } 446 447 /** 448 * Inserts a new element into the list at the given position. 449 * 450 * Params: 451 * data = the data for the new element 452 * position = the position to insert the element. 453 * If this is negative, or is larger than the number 454 * of elements in the list, the new element is added on 455 * to the end of the list. 456 * 457 * Returns: the new start of the #GSList 458 */ 459 public ListSG insert(void* data, int position) 460 { 461 auto p = g_slist_insert(gSList, data, position); 462 463 if(p is null) 464 { 465 return null; 466 } 467 468 return new ListSG(cast(GSList*) p); 469 } 470 471 /** 472 * Inserts a node before @sibling containing @data. 473 * 474 * Params: 475 * sibling = node to insert @data before 476 * data = data to put in the newly-inserted node 477 * 478 * Returns: the new head of the list. 479 */ 480 public ListSG insertBefore(ListSG sibling, void* data) 481 { 482 auto p = g_slist_insert_before(gSList, (sibling is null) ? null : sibling.getListSGStruct(), data); 483 484 if(p is null) 485 { 486 return null; 487 } 488 489 return new ListSG(cast(GSList*) p); 490 } 491 492 /** 493 * Inserts a new element into the list, using the given 494 * comparison function to determine its position. 495 * 496 * Params: 497 * data = the data for the new element 498 * func = the function to compare elements in the list. 499 * It should return a number > 0 if the first parameter 500 * comes after the second parameter in the sort order. 501 * 502 * Returns: the new start of the #GSList 503 */ 504 public ListSG insertSorted(void* data, GCompareFunc func) 505 { 506 auto p = g_slist_insert_sorted(gSList, data, func); 507 508 if(p is null) 509 { 510 return null; 511 } 512 513 return new ListSG(cast(GSList*) p); 514 } 515 516 /** 517 * Inserts a new element into the list, using the given 518 * comparison function to determine its position. 519 * 520 * Params: 521 * data = the data for the new element 522 * func = the function to compare elements in the list. 523 * It should return a number > 0 if the first parameter 524 * comes after the second parameter in the sort order. 525 * userData = data to pass to comparison function 526 * 527 * Returns: the new start of the #GSList 528 * 529 * Since: 2.10 530 */ 531 public ListSG insertSortedWithData(void* data, GCompareDataFunc func, void* userData) 532 { 533 auto p = g_slist_insert_sorted_with_data(gSList, data, func, userData); 534 535 if(p is null) 536 { 537 return null; 538 } 539 540 return new ListSG(cast(GSList*) p); 541 } 542 543 /** 544 * Gets the last element in a #GSList. 545 * 546 * This function iterates over the whole list. 547 * 548 * Returns: the last element in the #GSList, 549 * or %NULL if the #GSList has no elements 550 */ 551 public ListSG last() 552 { 553 auto p = g_slist_last(gSList); 554 555 if(p is null) 556 { 557 return null; 558 } 559 560 return new ListSG(cast(GSList*) p); 561 } 562 563 /** 564 * Gets the number of elements in a #GSList. 565 * 566 * This function iterates over the whole list to 567 * count its elements. To check whether the list is non-empty, it is faster to 568 * check @list against %NULL. 569 * 570 * Returns: the number of elements in the #GSList 571 */ 572 public uint length() 573 { 574 return g_slist_length(gSList); 575 } 576 577 /** 578 * Gets the element at the given position in a #GSList. 579 * 580 * Params: 581 * n = the position of the element, counting from 0 582 * 583 * Returns: the element, or %NULL if the position is off 584 * the end of the #GSList 585 */ 586 public ListSG nth(uint n) 587 { 588 auto p = g_slist_nth(gSList, n); 589 590 if(p is null) 591 { 592 return null; 593 } 594 595 return new ListSG(cast(GSList*) p); 596 } 597 598 /** 599 * Gets the data of the element at the given position. 600 * 601 * Params: 602 * n = the position of the element 603 * 604 * Returns: the element's data, or %NULL if the position 605 * is off the end of the #GSList 606 */ 607 public void* nthData(uint n) 608 { 609 return g_slist_nth_data(gSList, n); 610 } 611 612 /** 613 * Gets the position of the given element 614 * in the #GSList (starting from 0). 615 * 616 * Params: 617 * llink = an element in the #GSList 618 * 619 * Returns: the position of the element in the #GSList, 620 * or -1 if the element is not found 621 */ 622 public int position(ListSG llink) 623 { 624 return g_slist_position(gSList, (llink is null) ? null : llink.getListSGStruct()); 625 } 626 627 /** 628 * Adds a new element on to the start of the list. 629 * 630 * The return value is the new start of the list, which 631 * may have changed, so make sure you store the new value. 632 * 633 * |[<!-- language="C" --> 634 * // Notice that it is initialized to the empty list. 635 * GSList *list = NULL; 636 * list = g_slist_prepend (list, "last"); 637 * list = g_slist_prepend (list, "first"); 638 * ]| 639 * 640 * Params: 641 * data = the data for the new element 642 * 643 * Returns: the new start of the #GSList 644 */ 645 public ListSG prepend(void* data) 646 { 647 auto p = g_slist_prepend(gSList, data); 648 649 if(p is null) 650 { 651 return null; 652 } 653 654 return new ListSG(cast(GSList*) p); 655 } 656 657 /** 658 * Removes an element from a #GSList. 659 * If two elements contain the same data, only the first is removed. 660 * If none of the elements contain the data, the #GSList is unchanged. 661 * 662 * Params: 663 * data = the data of the element to remove 664 * 665 * Returns: the new start of the #GSList 666 */ 667 public ListSG remove(void* data) 668 { 669 auto p = g_slist_remove(gSList, data); 670 671 if(p is null) 672 { 673 return null; 674 } 675 676 return new ListSG(cast(GSList*) p); 677 } 678 679 /** 680 * Removes all list nodes with data equal to @data. 681 * Returns the new head of the list. Contrast with 682 * g_slist_remove() which removes only the first node 683 * matching the given data. 684 * 685 * Params: 686 * data = data to remove 687 * 688 * Returns: new head of @list 689 */ 690 public ListSG removeAll(void* data) 691 { 692 auto p = g_slist_remove_all(gSList, data); 693 694 if(p is null) 695 { 696 return null; 697 } 698 699 return new ListSG(cast(GSList*) p); 700 } 701 702 /** 703 * Removes an element from a #GSList, without 704 * freeing the element. The removed element's next 705 * link is set to %NULL, so that it becomes a 706 * self-contained list with one element. 707 * 708 * Removing arbitrary nodes from a singly-linked list 709 * requires time that is proportional to the length of the list 710 * (ie. O(n)). If you find yourself using g_slist_remove_link() 711 * frequently, you should consider a different data structure, 712 * such as the doubly-linked #GList. 713 * 714 * Params: 715 * link = an element in the #GSList 716 * 717 * Returns: the new start of the #GSList, without the element 718 */ 719 public ListSG removeLink(ListSG link) 720 { 721 auto p = g_slist_remove_link(gSList, (link is null) ? null : link.getListSGStruct()); 722 723 if(p is null) 724 { 725 return null; 726 } 727 728 return new ListSG(cast(GSList*) p); 729 } 730 731 /** 732 * Reverses a #GSList. 733 * 734 * Returns: the start of the reversed #GSList 735 */ 736 public ListSG reverse() 737 { 738 auto p = g_slist_reverse(gSList); 739 740 if(p is null) 741 { 742 return null; 743 } 744 745 return new ListSG(cast(GSList*) p); 746 } 747 748 /** 749 * Sorts a #GSList using the given comparison function. The algorithm 750 * used is a stable sort. 751 * 752 * Params: 753 * compareFunc = the comparison function used to sort the #GSList. 754 * This function is passed the data from 2 elements of the #GSList 755 * and should return 0 if they are equal, a negative value if the 756 * first element comes before the second, or a positive value if 757 * the first element comes after the second. 758 * 759 * Returns: the start of the sorted #GSList 760 */ 761 public ListSG sort(GCompareFunc compareFunc) 762 { 763 auto p = g_slist_sort(gSList, compareFunc); 764 765 if(p is null) 766 { 767 return null; 768 } 769 770 return new ListSG(cast(GSList*) p); 771 } 772 773 /** 774 * Like g_slist_sort(), but the sort function accepts a user data argument. 775 * 776 * Params: 777 * compareFunc = comparison function 778 * userData = data to pass to comparison function 779 * 780 * Returns: new head of the list 781 */ 782 public ListSG sortWithData(GCompareDataFunc compareFunc, void* userData) 783 { 784 auto p = g_slist_sort_with_data(gSList, compareFunc, userData); 785 786 if(p is null) 787 { 788 return null; 789 } 790 791 return new ListSG(cast(GSList*) p); 792 } 793 }