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