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

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

Initial release

File size: 8.4 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.VariantBuilder;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.ConstructionException;
26private import glib.Str;
27private import glib.Variant;
28private import glib.VariantType;
29
30
31/**
32 * A utility type for constructing container-type #GVariant instances.
33 *
34 * This is an opaque structure and may only be accessed using the
35 * following functions.
36 *
37 * #GVariantBuilder is not threadsafe in any way.  Do not attempt to
38 * access it from more than one thread.
39 */
40public class VariantBuilder
41{
42        /** the main Gtk struct */
43        protected GVariantBuilder* gVariantBuilder;
44        protected bool ownedRef;
45
46        /** Get the main Gtk struct */
47        public GVariantBuilder* getVariantBuilderStruct()
48        {
49                return gVariantBuilder;
50        }
51
52        /** the main Gtk struct as a void* */
53        protected void* getStruct()
54        {
55                return cast(void*)gVariantBuilder;
56        }
57
58        /**
59         * Sets our main struct and passes it to the parent class.
60         */
61        public this (GVariantBuilder* gVariantBuilder, bool ownedRef = false)
62        {
63                this.gVariantBuilder = gVariantBuilder;
64                this.ownedRef = ownedRef;
65        }
66
67
68        /**
69         * Allocates and initialises a new #GVariantBuilder.
70         *
71         * You should call g_variant_builder_unref() on the return value when it
72         * is no longer needed.  The memory will not be automatically freed by
73         * any other call.
74         *
75         * In most cases it is easier to place a #GVariantBuilder directly on
76         * the stack of the calling function and initialise it with
77         * g_variant_builder_init().
78         *
79         * Params:
80         *     type = a container type
81         *
82         * Returns: a #GVariantBuilder
83         *
84         * Since: 2.24
85         *
86         * Throws: ConstructionException GTK+ fails to create the object.
87         */
88        public this(VariantType type)
89        {
90                auto p = g_variant_builder_new((type is null) ? null : type.getVariantTypeStruct());
91               
92                if(p is null)
93                {
94                        throw new ConstructionException("null returned by new");
95                }
96               
97                this(cast(GVariantBuilder*) p);
98        }
99
100        /**
101         * Adds @value to @builder.
102         *
103         * It is an error to call this function in any way that would create an
104         * inconsistent value to be constructed.  Some examples of this are
105         * putting different types of items into an array, putting the wrong
106         * types or number of items in a tuple, putting more than one value into
107         * a variant, etc.
108         *
109         * If @value is a floating reference (see g_variant_ref_sink()),
110         * the @builder instance takes ownership of @value.
111         *
112         * Params:
113         *     value = a #GVariant
114         *
115         * Since: 2.24
116         */
117        public void addValue(Variant value)
118        {
119                g_variant_builder_add_value(gVariantBuilder, (value is null) ? null : value.getVariantStruct());
120        }
121
122        /**
123         * Releases all memory associated with a #GVariantBuilder without
124         * freeing the #GVariantBuilder structure itself.
125         *
126         * It typically only makes sense to do this on a stack-allocated
127         * #GVariantBuilder if you want to abort building the value part-way
128         * through.  This function need not be called if you call
129         * g_variant_builder_end() and it also doesn't need to be called on
130         * builders allocated with g_variant_builder_new (see
131         * g_variant_builder_unref() for that).
132         *
133         * This function leaves the #GVariantBuilder structure set to all-zeros.
134         * It is valid to call this function on either an initialised
135         * #GVariantBuilder or one that is set to all-zeros but it is not valid
136         * to call this function on uninitialised memory.
137         *
138         * Since: 2.24
139         */
140        public void clear()
141        {
142                g_variant_builder_clear(gVariantBuilder);
143        }
144
145        /**
146         * Closes the subcontainer inside the given @builder that was opened by
147         * the most recent call to g_variant_builder_open().
148         *
149         * It is an error to call this function in any way that would create an
150         * inconsistent value to be constructed (ie: too few values added to the
151         * subcontainer).
152         *
153         * Since: 2.24
154         */
155        public void close()
156        {
157                g_variant_builder_close(gVariantBuilder);
158        }
159
160        /**
161         * Ends the builder process and returns the constructed value.
162         *
163         * It is not permissible to use @builder in any way after this call
164         * except for reference counting operations (in the case of a
165         * heap-allocated #GVariantBuilder) or by reinitialising it with
166         * g_variant_builder_init() (in the case of stack-allocated).
167         *
168         * It is an error to call this function in any way that would create an
169         * inconsistent value to be constructed (ie: insufficient number of
170         * items added to a container with a specific number of children
171         * required).  It is also an error to call this function if the builder
172         * was created with an indefinite array or maybe type and no children
173         * have been added; in this case it is impossible to infer the type of
174         * the empty array.
175         *
176         * Returns: a new, floating, #GVariant
177         *
178         * Since: 2.24
179         */
180        public Variant end()
181        {
182                auto p = g_variant_builder_end(gVariantBuilder);
183               
184                if(p is null)
185                {
186                        return null;
187                }
188               
189                return new Variant(cast(GVariant*) p);
190        }
191
192        /**
193         * Initialises a #GVariantBuilder structure.
194         *
195         * @type must be non-%NULL.  It specifies the type of container to
196         * construct.  It can be an indefinite type such as
197         * %G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)".
198         * Maybe, array, tuple, dictionary entry and variant-typed values may be
199         * constructed.
200         *
201         * After the builder is initialised, values are added using
202         * g_variant_builder_add_value() or g_variant_builder_add().
203         *
204         * After all the child values are added, g_variant_builder_end() frees
205         * the memory associated with the builder and returns the #GVariant that
206         * was created.
207         *
208         * This function completely ignores the previous contents of @builder.
209         * On one hand this means that it is valid to pass in completely
210         * uninitialised memory.  On the other hand, this means that if you are
211         * initialising over top of an existing #GVariantBuilder you need to
212         * first call g_variant_builder_clear() in order to avoid leaking
213         * memory.
214         *
215         * You must not call g_variant_builder_ref() or
216         * g_variant_builder_unref() on a #GVariantBuilder that was initialised
217         * with this function.  If you ever pass a reference to a
218         * #GVariantBuilder outside of the control of your own code then you
219         * should assume that the person receiving that reference may try to use
220         * reference counting; you should use g_variant_builder_new() instead of
221         * this function.
222         *
223         * Params:
224         *     type = a container type
225         *
226         * Since: 2.24
227         */
228        public void init(VariantType type)
229        {
230                g_variant_builder_init(gVariantBuilder, (type is null) ? null : type.getVariantTypeStruct());
231        }
232
233        /**
234         * Opens a subcontainer inside the given @builder.  When done adding
235         * items to the subcontainer, g_variant_builder_close() must be called.
236         *
237         * It is an error to call this function in any way that would cause an
238         * inconsistent value to be constructed (ie: adding too many values or
239         * a value of an incorrect type).
240         *
241         * Params:
242         *     type = a #GVariantType
243         *
244         * Since: 2.24
245         */
246        public void open(VariantType type)
247        {
248                g_variant_builder_open(gVariantBuilder, (type is null) ? null : type.getVariantTypeStruct());
249        }
250
251        /**
252         * Increases the reference count on @builder.
253         *
254         * Don't call this on stack-allocated #GVariantBuilder instances or bad
255         * things will happen.
256         *
257         * Returns: a new reference to @builder
258         *
259         * Since: 2.24
260         */
261        public VariantBuilder doref()
262        {
263                auto p = g_variant_builder_ref(gVariantBuilder);
264               
265                if(p is null)
266                {
267                        return null;
268                }
269               
270                return new VariantBuilder(cast(GVariantBuilder*) p, true);
271        }
272
273        /**
274         * Decreases the reference count on @builder.
275         *
276         * In the event that there are no more references, releases all memory
277         * associated with the #GVariantBuilder.
278         *
279         * Don't call this on stack-allocated #GVariantBuilder instances or bad
280         * things will happen.
281         *
282         * Since: 2.24
283         */
284        public void unref()
285        {
286                g_variant_builder_unref(gVariantBuilder);
287        }
288}
Note: See TracBrowser for help on using the repository browser.