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