source: appstream-generator/build/girepo/glib/ListG.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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