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