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