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