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.ListG; 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 #GList struct is used for each element in a doubly-linked list. 36 */ 37 public class ListG 38 { 39 /** the main Gtk struct */ 40 protected GList* gList; 41 protected bool ownedRef; 42 43 /** Get the main Gtk struct */ 44 public GList* getListGStruct(bool transferOwnership = false) 45 { 46 if (transferOwnership) 47 ownedRef = false; 48 return gList; 49 } 50 51 /** the main Gtk struct as a void* */ 52 protected void* getStruct() 53 { 54 return cast(void*)gList; 55 } 56 57 /** 58 * Sets our main struct and passes it to the parent class. 59 */ 60 public this (GList* gList, bool ownedRef = false) 61 { 62 this.gList = gList; 63 this.ownedRef = ownedRef; 64 } 65 66 /** */ 67 @property void* data() 68 { 69 return gList.data; 70 } 71 72 /** 73 * get the next element 74 * Returns: the next element, or NULL if there are no more elements. 75 */ 76 @property ListG next() 77 { 78 if ( gList.next is null ) 79 { 80 return null; 81 } 82 83 return new ListG(gList.next); 84 } 85 86 /** 87 * get the previous element 88 * Returns: the previous element, or NULL if there are no more elements. 89 */ 90 @property ListG previous() 91 { 92 if ( gList.prev is null ) 93 { 94 return null; 95 } 96 97 return new ListG(gList.prev); 98 } 99 100 /** 101 * Turn the list into a D array of the desiered type. 102 * Type T wraps should match the type of the data. 103 */ 104 public T[] toArray(T, TC = getCType!T)() 105 if ( is(T == class) ) 106 { 107 T[] arr = new T[length()]; 108 ListG list = this; 109 size_t count; 110 111 while(list !is null && count < arr.length) 112 { 113 arr[count] = ObjectG.getDObject!(T)(cast(TC)list.data); 114 list = list.next(); 115 count++; 116 } 117 118 return arr; 119 } 120 121 /** Ditto */ 122 public T[] toArray(T)() 123 if ( is ( T == string ) ) 124 { 125 T[] arr = new T[length()]; 126 ListG list = this; 127 size_t count; 128 129 while(list !is null && count < arr.length) 130 { 131 arr[count] = Str.toString(cast(char*)list.data); 132 list = list.next(); 133 count++; 134 } 135 136 return arr; 137 } 138 139 private template getCType(T) 140 { 141 static if ( is(T == class) ) 142 alias getCType = typeof(T.tupleof[0]); 143 else 144 alias getCType = void*; 145 } 146 147 unittest 148 { 149 import gobject.Value; 150 151 auto list = new ListG(null); 152 list = list.append(new Value(0).getValueStruct()); 153 list = list.append(new Value(1).getValueStruct()); 154 auto arr = list.toArray!Value(); 155 156 assert(arr[0].getInt() == 0); 157 assert(arr[1].getInt() == 1); 158 159 list = new ListG(null); 160 list = list.append(cast(void*)"test\0".ptr); 161 list = list.append(cast(void*)"test2\0".ptr); 162 163 assert(["test", "test2"] == list.toArray!string()); 164 } 165 166 /** 167 */ 168 169 /** 170 * Allocates space for one #GList element. It is called by 171 * g_list_append(), g_list_prepend(), g_list_insert() and 172 * g_list_insert_sorted() and so is rarely used on its own. 173 * 174 * Returns: a pointer to the newly-allocated #GList element 175 */ 176 public static ListG alloc() 177 { 178 auto p = g_list_alloc(); 179 180 if(p is null) 181 { 182 return null; 183 } 184 185 return new ListG(cast(GList*) p); 186 } 187 188 /** 189 * Adds a new element on to the end of the list. 190 * 191 * Note that the return value is the new start of the list, 192 * if @list was empty; make sure you store the new value. 193 * 194 * g_list_append() has to traverse the entire list to find the end, 195 * which is inefficient when adding multiple elements. A common idiom 196 * to avoid the inefficiency is to use g_list_prepend() and reverse 197 * the list with g_list_reverse() when all elements have been added. 198 * 199 * |[<!-- language="C" --> 200 * // Notice that these are initialized to the empty list. 201 * GList *string_list = NULL, *number_list = NULL; 202 * 203 * // This is a list of strings. 204 * string_list = g_list_append (string_list, "first"); 205 * string_list = g_list_append (string_list, "second"); 206 * 207 * // This is a list of integers. 208 * number_list = g_list_append (number_list, GINT_TO_POINTER (27)); 209 * number_list = g_list_append (number_list, GINT_TO_POINTER (14)); 210 * ]| 211 * 212 * Params: 213 * data = the data for the new element 214 * 215 * Returns: either @list or the new start of the #GList if @list was %NULL 216 */ 217 public ListG append(void* data) 218 { 219 auto p = g_list_append(gList, data); 220 221 if(p is null) 222 { 223 return null; 224 } 225 226 return new ListG(cast(GList*) p); 227 } 228 229 /** 230 * Adds the second #GList onto the end of the first #GList. 231 * Note that the elements of the second #GList are not copied. 232 * They are used directly. 233 * 234 * This function is for example used to move an element in the list. 235 * The following example moves an element to the top of the list: 236 * |[<!-- language="C" --> 237 * list = g_list_remove_link (list, llink); 238 * list = g_list_concat (llink, list); 239 * ]| 240 * 241 * Params: 242 * list2 = the #GList to add to the end of the first #GList, 243 * this must point to the top of the list 244 * 245 * Returns: the start of the new #GList, which equals @list1 if not %NULL 246 */ 247 public ListG concat(ListG list2) 248 { 249 auto p = g_list_concat(gList, (list2 is null) ? null : list2.getListGStruct()); 250 251 if(p is null) 252 { 253 return null; 254 } 255 256 return new ListG(cast(GList*) p); 257 } 258 259 /** 260 * Copies a #GList. 261 * 262 * Note that this is a "shallow" copy. If the list elements 263 * consist of pointers to data, the pointers are copied but 264 * the actual data is not. See g_list_copy_deep() if you need 265 * to copy the data as well. 266 * 267 * Returns: the start of the new list that holds the same data as @list 268 */ 269 public ListG copy() 270 { 271 auto p = g_list_copy(gList); 272 273 if(p is null) 274 { 275 return null; 276 } 277 278 return new ListG(cast(GList*) p); 279 } 280 281 /** 282 * Makes a full (deep) copy of a #GList. 283 * 284 * In contrast with g_list_copy(), this function uses @func to make 285 * a copy of each list element, in addition to copying the list 286 * container itself. 287 * 288 * @func, as a #GCopyFunc, takes two arguments, the data to be copied 289 * and a @user_data pointer. On common processor architectures, it's safe to 290 * pass %NULL as @user_data if the copy function takes only one argument. You 291 * may get compiler warnings from this though if compiling with GCC’s 292 * `-Wcast-function-type` warning. 293 * 294 * For instance, if @list holds a list of GObjects, you can do: 295 * |[<!-- language="C" --> 296 * another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL); 297 * ]| 298 * 299 * And, to entirely free the new list, you could do: 300 * |[<!-- language="C" --> 301 * g_list_free_full (another_list, g_object_unref); 302 * ]| 303 * 304 * Params: 305 * func = a copy function used to copy every element in the list 306 * userData = user data passed to the copy function @func, or %NULL 307 * 308 * Returns: the start of the new list that holds a full copy of @list, 309 * use g_list_free_full() to free it 310 * 311 * Since: 2.34 312 */ 313 public ListG copyDeep(GCopyFunc func, void* userData) 314 { 315 auto p = g_list_copy_deep(gList, func, userData); 316 317 if(p is null) 318 { 319 return null; 320 } 321 322 return new ListG(cast(GList*) p); 323 } 324 325 /** 326 * Removes the node link_ from the list and frees it. 327 * Compare this to g_list_remove_link() which removes the node 328 * without freeing it. 329 * 330 * Params: 331 * link = node to delete from @list 332 * 333 * Returns: the (possibly changed) start of the #GList 334 */ 335 public ListG deleteLink(ListG link) 336 { 337 auto p = g_list_delete_link(gList, (link is null) ? null : link.getListGStruct()); 338 339 if(p is null) 340 { 341 return null; 342 } 343 344 return new ListG(cast(GList*) p); 345 } 346 347 /** 348 * Finds the element in a #GList which contains the given data. 349 * 350 * Params: 351 * data = the element data to find 352 * 353 * Returns: the found #GList element, or %NULL if it is not found 354 */ 355 public ListG find(void* data) 356 { 357 auto p = g_list_find(gList, data); 358 359 if(p is null) 360 { 361 return null; 362 } 363 364 return new ListG(cast(GList*) p); 365 } 366 367 /** 368 * Finds an element in a #GList, using a supplied function to 369 * find the desired element. It iterates over the list, calling 370 * the given function which should return 0 when the desired 371 * element is found. The function takes two #gconstpointer arguments, 372 * the #GList element's data as the first argument and the 373 * given user data. 374 * 375 * Params: 376 * data = user data passed to the function 377 * func = the function to call for each element. 378 * It should return 0 when the desired element is found 379 * 380 * Returns: the found #GList element, or %NULL if it is not found 381 */ 382 public ListG findCustom(void* data, GCompareFunc func) 383 { 384 auto p = g_list_find_custom(gList, data, func); 385 386 if(p is null) 387 { 388 return null; 389 } 390 391 return new ListG(cast(GList*) p); 392 } 393 394 /** 395 * Gets the first element in a #GList. 396 * 397 * Returns: the first element in the #GList, 398 * or %NULL if the #GList has no elements 399 */ 400 public ListG first() 401 { 402 auto p = g_list_first(gList); 403 404 if(p is null) 405 { 406 return null; 407 } 408 409 return new ListG(cast(GList*) p); 410 } 411 412 alias foreac = foreach_; 413 /** 414 * Calls a function for each element of a #GList. 415 * 416 * It is safe for @func to remove the element from @list, but it must 417 * not modify any part of the list after that element. 418 * 419 * Params: 420 * func = the function to call with each element's data 421 * userData = user data to pass to the function 422 */ 423 public void foreach_(GFunc func, void* userData) 424 { 425 g_list_foreach(gList, func, userData); 426 } 427 428 /** 429 * Frees all of the memory used by a #GList. 430 * The freed elements are returned to the slice allocator. 431 * 432 * If list elements contain dynamically-allocated memory, you should 433 * either use g_list_free_full() or free them manually first. 434 */ 435 public void free() 436 { 437 g_list_free(gList); 438 } 439 440 /** 441 * Frees one #GList element, but does not update links from the next and 442 * previous elements in the list, so you should not call this function on an 443 * element that is currently part of a list. 444 * 445 * It is usually used after g_list_remove_link(). 446 */ 447 public void free1() 448 { 449 g_list_free_1(gList); 450 } 451 452 /** 453 * Convenience method, which frees all the memory used by a #GList, 454 * and calls @free_func on every element's data. 455 * 456 * @free_func must not modify the list (eg, by removing the freed 457 * element from it). 458 * 459 * Params: 460 * freeFunc = the function to be called to free each element's data 461 * 462 * Since: 2.28 463 */ 464 public void freeFull(GDestroyNotify freeFunc) 465 { 466 g_list_free_full(gList, freeFunc); 467 } 468 469 /** 470 * Gets the position of the element containing 471 * the given data (starting from 0). 472 * 473 * Params: 474 * data = the data to find 475 * 476 * Returns: the index of the element containing the data, 477 * or -1 if the data is not found 478 */ 479 public int index(void* data) 480 { 481 return g_list_index(gList, data); 482 } 483 484 /** 485 * Inserts a new element into the list at the given position. 486 * 487 * Params: 488 * data = the data for the new element 489 * position = the position to insert the element. If this is 490 * negative, or is larger than the number of elements in the 491 * list, the new element is added on to the end of the list. 492 * 493 * Returns: the (possibly changed) start of the #GList 494 */ 495 public ListG insert(void* data, int position) 496 { 497 auto p = g_list_insert(gList, data, position); 498 499 if(p is null) 500 { 501 return null; 502 } 503 504 return new ListG(cast(GList*) p); 505 } 506 507 /** 508 * Inserts a new element into the list before the given position. 509 * 510 * Params: 511 * sibling = the list element before which the new element 512 * is inserted or %NULL to insert at the end of the list 513 * data = the data for the new element 514 * 515 * Returns: the (possibly changed) start of the #GList 516 */ 517 public ListG insertBefore(ListG sibling, void* data) 518 { 519 auto p = g_list_insert_before(gList, (sibling is null) ? null : sibling.getListGStruct(), data); 520 521 if(p is null) 522 { 523 return null; 524 } 525 526 return new ListG(cast(GList*) p); 527 } 528 529 /** 530 * Inserts a new element into the list, using the given comparison 531 * function to determine its position. 532 * 533 * If you are adding many new elements to a list, and the number of 534 * new elements is much larger than the length of the list, use 535 * g_list_prepend() to add the new items and sort the list afterwards 536 * with g_list_sort(). 537 * 538 * Params: 539 * data = the data for the new element 540 * func = the function to compare elements in the list. It should 541 * return a number > 0 if the first parameter comes after the 542 * second parameter in the sort order. 543 * 544 * Returns: the (possibly changed) start of the #GList 545 */ 546 public ListG insertSorted(void* data, GCompareFunc func) 547 { 548 auto p = g_list_insert_sorted(gList, data, func); 549 550 if(p is null) 551 { 552 return null; 553 } 554 555 return new ListG(cast(GList*) p); 556 } 557 558 /** 559 * Inserts a new element into the list, using the given comparison 560 * function to determine its position. 561 * 562 * If you are adding many new elements to a list, and the number of 563 * new elements is much larger than the length of the list, use 564 * g_list_prepend() to add the new items and sort the list afterwards 565 * with g_list_sort(). 566 * 567 * Params: 568 * data = the data for the new element 569 * func = the function to compare elements in the list. It should 570 * return a number > 0 if the first parameter comes after the 571 * second parameter in the sort order. 572 * userData = user data to pass to comparison function 573 * 574 * Returns: the (possibly changed) start of the #GList 575 * 576 * Since: 2.10 577 */ 578 public ListG insertSortedWithData(void* data, GCompareDataFunc func, void* userData) 579 { 580 auto p = g_list_insert_sorted_with_data(gList, data, func, userData); 581 582 if(p is null) 583 { 584 return null; 585 } 586 587 return new ListG(cast(GList*) p); 588 } 589 590 /** 591 * Gets the last element in a #GList. 592 * 593 * Returns: the last element in the #GList, 594 * or %NULL if the #GList has no elements 595 */ 596 public ListG last() 597 { 598 auto p = g_list_last(gList); 599 600 if(p is null) 601 { 602 return null; 603 } 604 605 return new ListG(cast(GList*) p); 606 } 607 608 /** 609 * Gets the number of elements in a #GList. 610 * 611 * This function iterates over the whole list to count its elements. 612 * Use a #GQueue instead of a GList if you regularly need the number 613 * of items. To check whether the list is non-empty, it is faster to check 614 * @list against %NULL. 615 * 616 * Returns: the number of elements in the #GList 617 */ 618 public uint length() 619 { 620 return g_list_length(gList); 621 } 622 623 /** 624 * Gets the element at the given position in a #GList. 625 * 626 * This iterates over the list until it reaches the @n-th position. If you 627 * intend to iterate over every element, it is better to use a for-loop as 628 * described in the #GList introduction. 629 * 630 * Params: 631 * n = the position of the element, counting from 0 632 * 633 * Returns: the element, or %NULL if the position is off 634 * the end of the #GList 635 */ 636 public ListG nth(uint n) 637 { 638 auto p = g_list_nth(gList, n); 639 640 if(p is null) 641 { 642 return null; 643 } 644 645 return new ListG(cast(GList*) p); 646 } 647 648 /** 649 * Gets the data of the element at the given position. 650 * 651 * This iterates over the list until it reaches the @n-th position. If you 652 * intend to iterate over every element, it is better to use a for-loop as 653 * described in the #GList introduction. 654 * 655 * Params: 656 * n = the position of the element 657 * 658 * Returns: the element's data, or %NULL if the position 659 * is off the end of the #GList 660 */ 661 public void* nthData(uint n) 662 { 663 return g_list_nth_data(gList, n); 664 } 665 666 /** 667 * Gets the element @n places before @list. 668 * 669 * Params: 670 * n = the position of the element, counting from 0 671 * 672 * Returns: the element, or %NULL if the position is 673 * off the end of the #GList 674 */ 675 public ListG nthPrev(uint n) 676 { 677 auto p = g_list_nth_prev(gList, n); 678 679 if(p is null) 680 { 681 return null; 682 } 683 684 return new ListG(cast(GList*) p); 685 } 686 687 /** 688 * Gets the position of the given element 689 * in the #GList (starting from 0). 690 * 691 * Params: 692 * llink = an element in the #GList 693 * 694 * Returns: the position of the element in the #GList, 695 * or -1 if the element is not found 696 */ 697 public int position(ListG llink) 698 { 699 return g_list_position(gList, (llink is null) ? null : llink.getListGStruct()); 700 } 701 702 /** 703 * Prepends a new element on to the start of the list. 704 * 705 * Note that the return value is the new start of the list, 706 * which will have changed, so make sure you store the new value. 707 * 708 * |[<!-- language="C" --> 709 * // Notice that it is initialized to the empty list. 710 * GList *list = NULL; 711 * 712 * list = g_list_prepend (list, "last"); 713 * list = g_list_prepend (list, "first"); 714 * ]| 715 * 716 * Do not use this function to prepend a new element to a different 717 * element than the start of the list. Use g_list_insert_before() instead. 718 * 719 * Params: 720 * data = the data for the new element 721 * 722 * Returns: a pointer to the newly prepended element, which is the new 723 * start of the #GList 724 */ 725 public ListG prepend(void* data) 726 { 727 auto p = g_list_prepend(gList, data); 728 729 if(p is null) 730 { 731 return null; 732 } 733 734 return new ListG(cast(GList*) p); 735 } 736 737 /** 738 * Removes an element from a #GList. 739 * If two elements contain the same data, only the first is removed. 740 * If none of the elements contain the data, the #GList is unchanged. 741 * 742 * Params: 743 * data = the data of the element to remove 744 * 745 * Returns: the (possibly changed) start of the #GList 746 */ 747 public ListG remove(void* data) 748 { 749 auto p = g_list_remove(gList, data); 750 751 if(p is null) 752 { 753 return null; 754 } 755 756 return new ListG(cast(GList*) p); 757 } 758 759 /** 760 * Removes all list nodes with data equal to @data. 761 * Returns the new head of the list. Contrast with 762 * g_list_remove() which removes only the first node 763 * matching the given data. 764 * 765 * Params: 766 * data = data to remove 767 * 768 * Returns: the (possibly changed) start of the #GList 769 */ 770 public ListG removeAll(void* data) 771 { 772 auto p = g_list_remove_all(gList, data); 773 774 if(p is null) 775 { 776 return null; 777 } 778 779 return new ListG(cast(GList*) p); 780 } 781 782 /** 783 * Removes an element from a #GList, without freeing the element. 784 * The removed element's prev and next links are set to %NULL, so 785 * that it becomes a self-contained list with one element. 786 * 787 * This function is for example used to move an element in the list 788 * (see the example for g_list_concat()) or to remove an element in 789 * the list before freeing its data: 790 * |[<!-- language="C" --> 791 * list = g_list_remove_link (list, llink); 792 * free_some_data_that_may_access_the_list_again (llink->data); 793 * g_list_free (llink); 794 * ]| 795 * 796 * Params: 797 * llink = an element in the #GList 798 * 799 * Returns: the (possibly changed) start of the #GList 800 */ 801 public ListG removeLink(ListG llink) 802 { 803 auto p = g_list_remove_link(gList, (llink is null) ? null : llink.getListGStruct()); 804 805 if(p is null) 806 { 807 return null; 808 } 809 810 return new ListG(cast(GList*) p); 811 } 812 813 /** 814 * Reverses a #GList. 815 * It simply switches the next and prev pointers of each element. 816 * 817 * Returns: the start of the reversed #GList 818 */ 819 public ListG reverse() 820 { 821 auto p = g_list_reverse(gList); 822 823 if(p is null) 824 { 825 return null; 826 } 827 828 return new ListG(cast(GList*) p); 829 } 830 831 /** 832 * Sorts a #GList using the given comparison function. The algorithm 833 * used is a stable sort. 834 * 835 * Params: 836 * compareFunc = the comparison function used to sort the #GList. 837 * This function is passed the data from 2 elements of the #GList 838 * and should return 0 if they are equal, a negative value if the 839 * first element comes before the second, or a positive value if 840 * the first element comes after the second. 841 * 842 * Returns: the (possibly changed) start of the #GList 843 */ 844 public ListG sort(GCompareFunc compareFunc) 845 { 846 auto p = g_list_sort(gList, compareFunc); 847 848 if(p is null) 849 { 850 return null; 851 } 852 853 return new ListG(cast(GList*) p); 854 } 855 856 /** 857 * Like g_list_sort(), but the comparison function accepts 858 * a user data argument. 859 * 860 * Params: 861 * compareFunc = comparison function 862 * userData = user data to pass to comparison function 863 * 864 * Returns: the (possibly changed) start of the #GList 865 */ 866 public ListG sortWithData(GCompareDataFunc compareFunc, void* userData) 867 { 868 auto p = g_list_sort_with_data(gList, compareFunc, userData); 869 870 if(p is null) 871 { 872 return null; 873 } 874 875 return new ListG(cast(GList*) p); 876 } 877 }