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 }