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. It's safe to pass %NULL as user_data, 290 * if the copy function takes only one argument. 291 * 292 * For instance, if @list holds a list of GObjects, you can do: 293 * |[<!-- language="C" --> 294 * another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL); 295 * ]| 296 * 297 * And, to entirely free the new list, you could do: 298 * |[<!-- language="C" --> 299 * g_list_free_full (another_list, g_object_unref); 300 * ]| 301 * 302 * Params: 303 * func = a copy function used to copy every element in the list 304 * userData = user data passed to the copy function @func, or %NULL 305 * 306 * Returns: the start of the new list that holds a full copy of @list, 307 * use g_list_free_full() to free it 308 * 309 * Since: 2.34 310 */ 311 public ListG copyDeep(GCopyFunc func, void* userData) 312 { 313 auto p = g_list_copy_deep(gList, func, userData); 314 315 if(p is null) 316 { 317 return null; 318 } 319 320 return new ListG(cast(GList*) p); 321 } 322 323 /** 324 * Removes the node link_ from the list and frees it. 325 * Compare this to g_list_remove_link() which removes the node 326 * without freeing it. 327 * 328 * Params: 329 * link = node to delete from @list 330 * 331 * Returns: the (possibly changed) start of the #GList 332 */ 333 public ListG deleteLink(ListG link) 334 { 335 auto p = g_list_delete_link(gList, (link is null) ? null : link.getListGStruct()); 336 337 if(p is null) 338 { 339 return null; 340 } 341 342 return new ListG(cast(GList*) p); 343 } 344 345 /** 346 * Finds the element in a #GList which contains the given data. 347 * 348 * Params: 349 * data = the element data to find 350 * 351 * Returns: the found #GList element, or %NULL if it is not found 352 */ 353 public ListG find(void* data) 354 { 355 auto p = g_list_find(gList, data); 356 357 if(p is null) 358 { 359 return null; 360 } 361 362 return new ListG(cast(GList*) p); 363 } 364 365 /** 366 * Finds an element in a #GList, using a supplied function to 367 * find the desired element. It iterates over the list, calling 368 * the given function which should return 0 when the desired 369 * element is found. The function takes two #gconstpointer arguments, 370 * the #GList element's data as the first argument and the 371 * given user data. 372 * 373 * Params: 374 * data = user data passed to the function 375 * func = the function to call for each element. 376 * It should return 0 when the desired element is found 377 * 378 * Returns: the found #GList element, or %NULL if it is not found 379 */ 380 public ListG findCustom(void* data, GCompareFunc func) 381 { 382 auto p = g_list_find_custom(gList, data, func); 383 384 if(p is null) 385 { 386 return null; 387 } 388 389 return new ListG(cast(GList*) p); 390 } 391 392 /** 393 * Gets the first element in a #GList. 394 * 395 * Returns: the first element in the #GList, 396 * or %NULL if the #GList has no elements 397 */ 398 public ListG first() 399 { 400 auto p = g_list_first(gList); 401 402 if(p is null) 403 { 404 return null; 405 } 406 407 return new ListG(cast(GList*) p); 408 } 409 410 alias foreac = foreach_; 411 /** 412 * Calls a function for each element of a #GList. 413 * 414 * It is safe for @func to remove the element from @list, but it must 415 * not modify any part of the list after that element. 416 * 417 * Params: 418 * func = the function to call with each element's data 419 * userData = user data to pass to the function 420 */ 421 public void foreach_(GFunc func, void* userData) 422 { 423 g_list_foreach(gList, func, userData); 424 } 425 426 /** 427 * Frees all of the memory used by a #GList. 428 * The freed elements are returned to the slice allocator. 429 * 430 * If list elements contain dynamically-allocated memory, you should 431 * either use g_list_free_full() or free them manually first. 432 */ 433 public void free() 434 { 435 g_list_free(gList); 436 } 437 438 /** 439 * Frees one #GList element, but does not update links from the next and 440 * previous elements in the list, so you should not call this function on an 441 * element that is currently part of a list. 442 * 443 * It is usually used after g_list_remove_link(). 444 */ 445 public void free1() 446 { 447 g_list_free_1(gList); 448 } 449 450 /** 451 * Convenience method, which frees all the memory used by a #GList, 452 * and calls @free_func on every element's data. 453 * 454 * @free_func must not modify the list (eg, by removing the freed 455 * element from it). 456 * 457 * Params: 458 * freeFunc = the function to be called to free each element's data 459 * 460 * Since: 2.28 461 */ 462 public void freeFull(GDestroyNotify freeFunc) 463 { 464 g_list_free_full(gList, freeFunc); 465 } 466 467 /** 468 * Gets the position of the element containing 469 * the given data (starting from 0). 470 * 471 * Params: 472 * data = the data to find 473 * 474 * Returns: the index of the element containing the data, 475 * or -1 if the data is not found 476 */ 477 public int index(void* data) 478 { 479 return g_list_index(gList, data); 480 } 481 482 /** 483 * Inserts a new element into the list at the given position. 484 * 485 * Params: 486 * data = the data for the new element 487 * position = the position to insert the element. If this is 488 * negative, or is larger than the number of elements in the 489 * list, the new element is added on to the end of the list. 490 * 491 * Returns: the (possibly changed) start of the #GList 492 */ 493 public ListG insert(void* data, int position) 494 { 495 auto p = g_list_insert(gList, data, position); 496 497 if(p is null) 498 { 499 return null; 500 } 501 502 return new ListG(cast(GList*) p); 503 } 504 505 /** 506 * Inserts a new element into the list before the given position. 507 * 508 * Params: 509 * sibling = the list element before which the new element 510 * is inserted or %NULL to insert at the end of the list 511 * data = the data for the new element 512 * 513 * Returns: the (possibly changed) start of the #GList 514 */ 515 public ListG insertBefore(ListG sibling, void* data) 516 { 517 auto p = g_list_insert_before(gList, (sibling is null) ? null : sibling.getListGStruct(), data); 518 519 if(p is null) 520 { 521 return null; 522 } 523 524 return new ListG(cast(GList*) p); 525 } 526 527 /** 528 * Inserts a new element into the list, using the given comparison 529 * function to determine its position. 530 * 531 * If you are adding many new elements to a list, and the number of 532 * new elements is much larger than the length of the list, use 533 * g_list_prepend() to add the new items and sort the list afterwards 534 * with g_list_sort(). 535 * 536 * Params: 537 * data = the data for the new element 538 * func = the function to compare elements in the list. It should 539 * return a number > 0 if the first parameter comes after the 540 * second parameter in the sort order. 541 * 542 * Returns: the (possibly changed) start of the #GList 543 */ 544 public ListG insertSorted(void* data, GCompareFunc func) 545 { 546 auto p = g_list_insert_sorted(gList, data, func); 547 548 if(p is null) 549 { 550 return null; 551 } 552 553 return new ListG(cast(GList*) p); 554 } 555 556 /** 557 * Inserts a new element into the list, using the given comparison 558 * function to determine its position. 559 * 560 * If you are adding many new elements to a list, and the number of 561 * new elements is much larger than the length of the list, use 562 * g_list_prepend() to add the new items and sort the list afterwards 563 * with g_list_sort(). 564 * 565 * Params: 566 * data = the data for the new element 567 * func = the function to compare elements in the list. It should 568 * return a number > 0 if the first parameter comes after the 569 * second parameter in the sort order. 570 * userData = user data to pass to comparison function 571 * 572 * Returns: the (possibly changed) start of the #GList 573 * 574 * Since: 2.10 575 */ 576 public ListG insertSortedWithData(void* data, GCompareDataFunc func, void* userData) 577 { 578 auto p = g_list_insert_sorted_with_data(gList, data, func, userData); 579 580 if(p is null) 581 { 582 return null; 583 } 584 585 return new ListG(cast(GList*) p); 586 } 587 588 /** 589 * Gets the last element in a #GList. 590 * 591 * Returns: the last element in the #GList, 592 * or %NULL if the #GList has no elements 593 */ 594 public ListG last() 595 { 596 auto p = g_list_last(gList); 597 598 if(p is null) 599 { 600 return null; 601 } 602 603 return new ListG(cast(GList*) p); 604 } 605 606 /** 607 * Gets the number of elements in a #GList. 608 * 609 * This function iterates over the whole list to count its elements. 610 * Use a #GQueue instead of a GList if you regularly need the number 611 * of items. To check whether the list is non-empty, it is faster to check 612 * @list against %NULL. 613 * 614 * Returns: the number of elements in the #GList 615 */ 616 public uint length() 617 { 618 return g_list_length(gList); 619 } 620 621 /** 622 * Gets the element at the given position in a #GList. 623 * 624 * This iterates over the list until it reaches the @n-th position. If you 625 * intend to iterate over every element, it is better to use a for-loop as 626 * described in the #GList introduction. 627 * 628 * Params: 629 * n = the position of the element, counting from 0 630 * 631 * Returns: the element, or %NULL if the position is off 632 * the end of the #GList 633 */ 634 public ListG nth(uint n) 635 { 636 auto p = g_list_nth(gList, n); 637 638 if(p is null) 639 { 640 return null; 641 } 642 643 return new ListG(cast(GList*) p); 644 } 645 646 /** 647 * Gets the data of the element at the given position. 648 * 649 * This iterates over the list until it reaches the @n-th position. If you 650 * intend to iterate over every element, it is better to use a for-loop as 651 * described in the #GList introduction. 652 * 653 * Params: 654 * n = the position of the element 655 * 656 * Returns: the element's data, or %NULL if the position 657 * is off the end of the #GList 658 */ 659 public void* nthData(uint n) 660 { 661 return g_list_nth_data(gList, n); 662 } 663 664 /** 665 * Gets the element @n places before @list. 666 * 667 * Params: 668 * n = the position of the element, counting from 0 669 * 670 * Returns: the element, or %NULL if the position is 671 * off the end of the #GList 672 */ 673 public ListG nthPrev(uint n) 674 { 675 auto p = g_list_nth_prev(gList, n); 676 677 if(p is null) 678 { 679 return null; 680 } 681 682 return new ListG(cast(GList*) p); 683 } 684 685 /** 686 * Gets the position of the given element 687 * in the #GList (starting from 0). 688 * 689 * Params: 690 * llink = an element in the #GList 691 * 692 * Returns: the position of the element in the #GList, 693 * or -1 if the element is not found 694 */ 695 public int position(ListG llink) 696 { 697 return g_list_position(gList, (llink is null) ? null : llink.getListGStruct()); 698 } 699 700 /** 701 * Prepends a new element on to the start of the list. 702 * 703 * Note that the return value is the new start of the list, 704 * which will have changed, so make sure you store the new value. 705 * 706 * |[<!-- language="C" --> 707 * // Notice that it is initialized to the empty list. 708 * GList *list = NULL; 709 * 710 * list = g_list_prepend (list, "last"); 711 * list = g_list_prepend (list, "first"); 712 * ]| 713 * 714 * Do not use this function to prepend a new element to a different 715 * element than the start of the list. Use g_list_insert_before() instead. 716 * 717 * Params: 718 * data = the data for the new element 719 * 720 * Returns: a pointer to the newly prepended element, which is the new 721 * start of the #GList 722 */ 723 public ListG prepend(void* data) 724 { 725 auto p = g_list_prepend(gList, data); 726 727 if(p is null) 728 { 729 return null; 730 } 731 732 return new ListG(cast(GList*) p); 733 } 734 735 /** 736 * Removes an element from a #GList. 737 * If two elements contain the same data, only the first is removed. 738 * If none of the elements contain the data, the #GList is unchanged. 739 * 740 * Params: 741 * data = the data of the element to remove 742 * 743 * Returns: the (possibly changed) start of the #GList 744 */ 745 public ListG remove(void* data) 746 { 747 auto p = g_list_remove(gList, data); 748 749 if(p is null) 750 { 751 return null; 752 } 753 754 return new ListG(cast(GList*) p); 755 } 756 757 /** 758 * Removes all list nodes with data equal to @data. 759 * Returns the new head of the list. Contrast with 760 * g_list_remove() which removes only the first node 761 * matching the given data. 762 * 763 * Params: 764 * data = data to remove 765 * 766 * Returns: the (possibly changed) start of the #GList 767 */ 768 public ListG removeAll(void* data) 769 { 770 auto p = g_list_remove_all(gList, data); 771 772 if(p is null) 773 { 774 return null; 775 } 776 777 return new ListG(cast(GList*) p); 778 } 779 780 /** 781 * Removes an element from a #GList, without freeing the element. 782 * The removed element's prev and next links are set to %NULL, so 783 * that it becomes a self-contained list with one element. 784 * 785 * This function is for example used to move an element in the list 786 * (see the example for g_list_concat()) or to remove an element in 787 * the list before freeing its data: 788 * |[<!-- language="C" --> 789 * list = g_list_remove_link (list, llink); 790 * free_some_data_that_may_access_the_list_again (llink->data); 791 * g_list_free (llink); 792 * ]| 793 * 794 * Params: 795 * llink = an element in the #GList 796 * 797 * Returns: the (possibly changed) start of the #GList 798 */ 799 public ListG removeLink(ListG llink) 800 { 801 auto p = g_list_remove_link(gList, (llink is null) ? null : llink.getListGStruct()); 802 803 if(p is null) 804 { 805 return null; 806 } 807 808 return new ListG(cast(GList*) p); 809 } 810 811 /** 812 * Reverses a #GList. 813 * It simply switches the next and prev pointers of each element. 814 * 815 * Returns: the start of the reversed #GList 816 */ 817 public ListG reverse() 818 { 819 auto p = g_list_reverse(gList); 820 821 if(p is null) 822 { 823 return null; 824 } 825 826 return new ListG(cast(GList*) p); 827 } 828 829 /** 830 * Sorts a #GList using the given comparison function. The algorithm 831 * used is a stable sort. 832 * 833 * Params: 834 * compareFunc = the comparison function used to sort the #GList. 835 * This function is passed the data from 2 elements of the #GList 836 * and should return 0 if they are equal, a negative value if the 837 * first element comes before the second, or a positive value if 838 * the first element comes after the second. 839 * 840 * Returns: the (possibly changed) start of the #GList 841 */ 842 public ListG sort(GCompareFunc compareFunc) 843 { 844 auto p = g_list_sort(gList, compareFunc); 845 846 if(p is null) 847 { 848 return null; 849 } 850 851 return new ListG(cast(GList*) p); 852 } 853 854 /** 855 * Like g_list_sort(), but the comparison function accepts 856 * a user data argument. 857 * 858 * Params: 859 * compareFunc = comparison function 860 * userData = user data to pass to comparison function 861 * 862 * Returns: the (possibly changed) start of the #GList 863 */ 864 public ListG sortWithData(GCompareDataFunc compareFunc, void* userData) 865 { 866 auto p = g_list_sort_with_data(gList, compareFunc, userData); 867 868 if(p is null) 869 { 870 return null; 871 } 872 873 return new ListG(cast(GList*) p); 874 } 875 }