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