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. 383 * It is usually used after g_list_remove_link(). 384 */ 385 public void free1() 386 { 387 g_list_free_1(gList); 388 } 389 390 /** 391 * Convenience method, which frees all the memory used by a #GList, 392 * and calls @free_func on every element's data. 393 * 394 * Params: 395 * freeFunc = the function to be called to free each element's data 396 * 397 * Since: 2.28 398 */ 399 public void freeFull(GDestroyNotify freeFunc) 400 { 401 g_list_free_full(gList, freeFunc); 402 } 403 404 /** 405 * Gets the position of the element containing 406 * the given data (starting from 0). 407 * 408 * Params: 409 * data = the data to find 410 * 411 * Return: the index of the element containing the data, 412 * or -1 if the data is not found 413 */ 414 public int index(void* data) 415 { 416 return g_list_index(gList, data); 417 } 418 419 /** 420 * Inserts a new element into the list at the given position. 421 * 422 * Params: 423 * data = the data for the new element 424 * position = the position to insert the element. If this is 425 * negative, or is larger than the number of elements in the 426 * list, the new element is added on to the end of the list. 427 * 428 * Return: the (possibly changed) start of the #GList 429 */ 430 public ListG insert(void* data, int position) 431 { 432 auto p = g_list_insert(gList, data, position); 433 434 if(p is null) 435 { 436 return null; 437 } 438 439 return new ListG(cast(GList*) p); 440 } 441 442 /** 443 * Inserts a new element into the list before the given position. 444 * 445 * Params: 446 * sibling = the list element before which the new element 447 * is inserted or %NULL to insert at the end of the list 448 * data = the data for the new element 449 * 450 * Return: the (possibly changed) start of the #GList 451 */ 452 public ListG insertBefore(ListG sibling, void* data) 453 { 454 auto p = g_list_insert_before(gList, (sibling is null) ? null : sibling.getListGStruct(), data); 455 456 if(p is null) 457 { 458 return null; 459 } 460 461 return new ListG(cast(GList*) p); 462 } 463 464 /** 465 * Inserts a new element into the list, using the given comparison 466 * function to determine its position. 467 * 468 * If you are adding many new elements to a list, and the number of 469 * new elements is much larger than the length of the list, use 470 * g_list_prepend() to add the new items and sort the list afterwards 471 * with g_list_sort(). 472 * 473 * Params: 474 * data = the data for the new element 475 * func = the function to compare elements in the list. It should 476 * return a number > 0 if the first parameter comes after the 477 * second parameter in the sort order. 478 * 479 * Return: the (possibly changed) start of the #GList 480 */ 481 public ListG insertSorted(void* data, GCompareFunc func) 482 { 483 auto p = g_list_insert_sorted(gList, data, func); 484 485 if(p is null) 486 { 487 return null; 488 } 489 490 return new ListG(cast(GList*) p); 491 } 492 493 /** 494 * Inserts a new element into the list, using the given comparison 495 * function to determine its position. 496 * 497 * If you are adding many new elements to a list, and the number of 498 * new elements is much larger than the length of the list, use 499 * g_list_prepend() to add the new items and sort the list afterwards 500 * with g_list_sort(). 501 * 502 * Params: 503 * data = the data for the new element 504 * func = the function to compare elements in the list. It should 505 * return a number > 0 if the first parameter comes after the 506 * second parameter in the sort order. 507 * userData = user data to pass to comparison function 508 * 509 * Return: the (possibly changed) start of the #GList 510 * 511 * Since: 2.10 512 */ 513 public ListG insertSortedWithData(void* data, GCompareDataFunc func, void* userData) 514 { 515 auto p = g_list_insert_sorted_with_data(gList, data, func, userData); 516 517 if(p is null) 518 { 519 return null; 520 } 521 522 return new ListG(cast(GList*) p); 523 } 524 525 /** 526 * Gets the last element in a #GList. 527 * 528 * Return: the last element in the #GList, 529 * or %NULL if the #GList has no elements 530 */ 531 public ListG last() 532 { 533 auto p = g_list_last(gList); 534 535 if(p is null) 536 { 537 return null; 538 } 539 540 return new ListG(cast(GList*) p); 541 } 542 543 /** 544 * Gets the number of elements in a #GList. 545 * 546 * This function iterates over the whole list to count its elements. 547 * Use a #GQueue instead of a GList if you regularly need the number 548 * of items. 549 * 550 * Return: the number of elements in the #GList 551 */ 552 public uint length() 553 { 554 return g_list_length(gList); 555 } 556 557 /** 558 * Gets the element at the given position in a #GList. 559 * 560 * Params: 561 * n = the position of the element, counting from 0 562 * 563 * Return: the element, or %NULL if the position is off 564 * the end of the #GList 565 */ 566 public ListG nth(uint n) 567 { 568 auto p = g_list_nth(gList, n); 569 570 if(p is null) 571 { 572 return null; 573 } 574 575 return new ListG(cast(GList*) p); 576 } 577 578 /** 579 * Gets the data of the element at the given position. 580 * 581 * Params: 582 * n = the position of the element 583 * 584 * Return: the element's data, or %NULL if the position 585 * is off the end of the #GList 586 */ 587 public void* nthData(uint n) 588 { 589 return g_list_nth_data(gList, n); 590 } 591 592 /** 593 * Gets the element @n places before @list. 594 * 595 * Params: 596 * n = the position of the element, counting from 0 597 * 598 * Return: the element, or %NULL if the position is 599 * off the end of the #GList 600 */ 601 public ListG nthPrev(uint n) 602 { 603 auto p = g_list_nth_prev(gList, n); 604 605 if(p is null) 606 { 607 return null; 608 } 609 610 return new ListG(cast(GList*) p); 611 } 612 613 /** 614 * Gets the position of the given element 615 * in the #GList (starting from 0). 616 * 617 * Params: 618 * llink = an element in the #GList 619 * 620 * Return: the position of the element in the #GList, 621 * or -1 if the element is not found 622 */ 623 public int position(ListG llink) 624 { 625 return g_list_position(gList, (llink is null) ? null : llink.getListGStruct()); 626 } 627 628 /** 629 * Prepends a new element on to the start of the list. 630 * 631 * Note that the return value is the new start of the list, 632 * which will have changed, so make sure you store the new value. 633 * 634 * |[<!-- language="C" --> 635 * // Notice that it is initialized to the empty list. 636 * GList *list = NULL; 637 * 638 * list = g_list_prepend (list, "last"); 639 * list = g_list_prepend (list, "first"); 640 * ]| 641 * 642 * Do not use this function to prepend a new element to a different 643 * element than the start of the list. Use g_list_insert_before() instead. 644 * 645 * Params: 646 * data = the data for the new element 647 * 648 * Return: a pointer to the newly prepended element, which is the new 649 * start of the #GList 650 */ 651 public ListG prepend(void* data) 652 { 653 auto p = g_list_prepend(gList, data); 654 655 if(p is null) 656 { 657 return null; 658 } 659 660 return new ListG(cast(GList*) p); 661 } 662 663 /** 664 * Removes an element from a #GList. 665 * If two elements contain the same data, only the first is removed. 666 * If none of the elements contain the data, the #GList is unchanged. 667 * 668 * Params: 669 * data = the data of the element to remove 670 * 671 * Return: the (possibly changed) start of the #GList 672 */ 673 public ListG remove(void* data) 674 { 675 auto p = g_list_remove(gList, data); 676 677 if(p is null) 678 { 679 return null; 680 } 681 682 return new ListG(cast(GList*) p); 683 } 684 685 /** 686 * Removes all list nodes with data equal to @data. 687 * Returns the new head of the list. Contrast with 688 * g_list_remove() which removes only the first node 689 * matching the given data. 690 * 691 * Params: 692 * data = data to remove 693 * 694 * Return: the (possibly changed) start of the #GList 695 */ 696 public ListG removeAll(void* data) 697 { 698 auto p = g_list_remove_all(gList, data); 699 700 if(p is null) 701 { 702 return null; 703 } 704 705 return new ListG(cast(GList*) p); 706 } 707 708 /** 709 * Removes an element from a #GList, without freeing the element. 710 * The removed element's prev and next links are set to %NULL, so 711 * that it becomes a self-contained list with one element. 712 * 713 * This function is for example used to move an element in the list 714 * (see the example for g_list_concat()) or to remove an element in 715 * the list before freeing its data: 716 * |[<!-- language="C" --> 717 * list = g_list_remove_link (list, llink); 718 * free_some_data_that_may_access_the_list_again (llink->data); 719 * g_list_free (llink); 720 * ]| 721 * 722 * Params: 723 * llink = an element in the #GList 724 * 725 * Return: the (possibly changed) start of the #GList 726 */ 727 public ListG removeLink(ListG llink) 728 { 729 auto p = g_list_remove_link(gList, (llink is null) ? null : llink.getListGStruct()); 730 731 if(p is null) 732 { 733 return null; 734 } 735 736 return new ListG(cast(GList*) p); 737 } 738 739 /** 740 * Reverses a #GList. 741 * It simply switches the next and prev pointers of each element. 742 * 743 * Return: the start of the reversed #GList 744 */ 745 public ListG reverse() 746 { 747 auto p = g_list_reverse(gList); 748 749 if(p is null) 750 { 751 return null; 752 } 753 754 return new ListG(cast(GList*) p); 755 } 756 757 /** 758 * Sorts a #GList using the given comparison function. The algorithm 759 * used is a stable sort. 760 * 761 * Params: 762 * compareFunc = the comparison function used to sort the #GList. 763 * This function is passed the data from 2 elements of the #GList 764 * and should return 0 if they are equal, a negative value if the 765 * first element comes before the second, or a positive value if 766 * the first element comes after the second. 767 * 768 * Return: the (possibly changed) start of the #GList 769 */ 770 public ListG sort(GCompareFunc compareFunc) 771 { 772 auto p = g_list_sort(gList, compareFunc); 773 774 if(p is null) 775 { 776 return null; 777 } 778 779 return new ListG(cast(GList*) p); 780 } 781 782 /** 783 * Like g_list_sort(), but the comparison function accepts 784 * a user data argument. 785 * 786 * Params: 787 * compareFunc = comparison function 788 * userData = user data to pass to comparison function 789 * 790 * Return: the (possibly changed) start of the #GList 791 */ 792 public ListG sortWithData(GCompareDataFunc compareFunc, void* userData) 793 { 794 auto p = g_list_sort_with_data(gList, compareFunc, userData); 795 796 if(p is null) 797 { 798 return null; 799 } 800 801 return new ListG(cast(GList*) p); 802 } 803 }