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

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

Initial release

File size: 10.2 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.VariantDict;
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 * #GVariantDict is a mutable interface to #GVariant dictionaries.
33 *
34 * It can be used for doing a sequence of dictionary lookups in an
35 * efficient way on an existing #GVariant dictionary or it can be used
36 * to construct new dictionaries with a hashtable-like interface.  It
37 * can also be used for taking existing dictionaries and modifying them
38 * in order to create new ones.
39 *
40 * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT
41 * dictionaries.
42 *
43 * It is possible to use #GVariantDict allocated on the stack or on the
44 * heap.  When using a stack-allocated #GVariantDict, you begin with a
45 * call to g_variant_dict_init() and free the resources with a call to
46 * g_variant_dict_clear().
47 *
48 * Heap-allocated #GVariantDict follows normal refcounting rules: you
49 * allocate it with g_variant_dict_new() and use g_variant_dict_ref()
50 * and g_variant_dict_unref().
51 *
52 * g_variant_dict_end() is used to convert the #GVariantDict back into a
53 * dictionary-type #GVariant.  When used with stack-allocated instances,
54 * this also implicitly frees all associated memory, but for
55 * heap-allocated instances, you must still call g_variant_dict_unref()
56 * afterwards.
57 *
58 * You will typically want to use a heap-allocated #GVariantDict when
59 * you expose it as part of an API.  For most other uses, the
60 * stack-allocated form will be more convenient.
61 *
62 * Consider the following two examples that do the same thing in each
63 * style: take an existing dictionary and look up the "count" uint32
64 * key, adding 1 to it if it is found, or returning an error if the
65 * key is not found.  Each returns the new dictionary as a floating
66 * #GVariant.
67 *
68 * ## Using a stack-allocated GVariantDict
69 *
70 * |[<!-- language="C" -->
71 * GVariant *
72 * add_to_count (GVariant  *orig,
73 * GError   **error)
74 * {
75 * GVariantDict dict;
76 * guint32 count;
77 *
78 * g_variant_dict_init (&dict, orig);
79 * if (!g_variant_dict_lookup (&dict, "count", "u", &count))
80 * {
81 * g_set_error (...);
82 * g_variant_dict_clear (&dict);
83 * return NULL;
84 * }
85 *
86 * g_variant_dict_insert (&dict, "count", "u", count + 1);
87 *
88 * return g_variant_dict_end (&dict);
89 * }
90 * ]|
91 *
92 * ## Using heap-allocated GVariantDict
93 *
94 * |[<!-- language="C" -->
95 * GVariant *
96 * add_to_count (GVariant  *orig,
97 * GError   **error)
98 * {
99 * GVariantDict *dict;
100 * GVariant *result;
101 * guint32 count;
102 *
103 * dict = g_variant_dict_new (orig);
104 *
105 * if (g_variant_dict_lookup (dict, "count", "u", &count))
106 * {
107 * g_variant_dict_insert (dict, "count", "u", count + 1);
108 * result = g_variant_dict_end (dict);
109 * }
110 * else
111 * {
112 * g_set_error (...);
113 * result = NULL;
114 * }
115 *
116 * g_variant_dict_unref (dict);
117 *
118 * return result;
119 * }
120 * ]|
121 *
122 * Since: 2.40
123 */
124public class VariantDict
125{
126        /** the main Gtk struct */
127        protected GVariantDict* gVariantDict;
128        protected bool ownedRef;
129
130        /** Get the main Gtk struct */
131        public GVariantDict* getVariantDictStruct()
132        {
133                return gVariantDict;
134        }
135
136        /** the main Gtk struct as a void* */
137        protected void* getStruct()
138        {
139                return cast(void*)gVariantDict;
140        }
141
142        /**
143         * Sets our main struct and passes it to the parent class.
144         */
145        public this (GVariantDict* gVariantDict, bool ownedRef = false)
146        {
147                this.gVariantDict = gVariantDict;
148                this.ownedRef = ownedRef;
149        }
150
151
152        /**
153         * Allocates and initialises a new #GVariantDict.
154         *
155         * You should call g_variant_dict_unref() on the return value when it
156         * is no longer needed.  The memory will not be automatically freed by
157         * any other call.
158         *
159         * In some cases it may be easier to place a #GVariantDict directly on
160         * the stack of the calling function and initialise it with
161         * g_variant_dict_init().  This is particularly useful when you are
162         * using #GVariantDict to construct a #GVariant.
163         *
164         * Params:
165         *     fromAsv = the #GVariant with which to initialise the
166         *         dictionary
167         *
168         * Returns: a #GVariantDict
169         *
170         * Since: 2.40
171         *
172         * Throws: ConstructionException GTK+ fails to create the object.
173         */
174        public this(Variant fromAsv)
175        {
176                auto p = g_variant_dict_new((fromAsv is null) ? null : fromAsv.getVariantStruct());
177               
178                if(p is null)
179                {
180                        throw new ConstructionException("null returned by new");
181                }
182               
183                this(cast(GVariantDict*) p);
184        }
185
186        /**
187         * Releases all memory associated with a #GVariantDict without freeing
188         * the #GVariantDict structure itself.
189         *
190         * It typically only makes sense to do this on a stack-allocated
191         * #GVariantDict if you want to abort building the value part-way
192         * through.  This function need not be called if you call
193         * g_variant_dict_end() and it also doesn't need to be called on dicts
194         * allocated with g_variant_dict_new (see g_variant_dict_unref() for
195         * that).
196         *
197         * It is valid to call this function on either an initialised
198         * #GVariantDict or one that was previously cleared by an earlier call
199         * to g_variant_dict_clear() but it is not valid to call this function
200         * on uninitialised memory.
201         *
202         * Since: 2.40
203         */
204        public void clear()
205        {
206                g_variant_dict_clear(gVariantDict);
207        }
208
209        /**
210         * Checks if @key exists in @dict.
211         *
212         * Params:
213         *     key = the key to lookup in the dictionary
214         *
215         * Returns: %TRUE if @key is in @dict
216         *
217         * Since: 2.40
218         */
219        public bool contains(string key)
220        {
221                return g_variant_dict_contains(gVariantDict, Str.toStringz(key)) != 0;
222        }
223
224        /**
225         * Returns the current value of @dict as a #GVariant of type
226         * %G_VARIANT_TYPE_VARDICT, clearing it in the process.
227         *
228         * It is not permissible to use @dict in any way after this call except
229         * for reference counting operations (in the case of a heap-allocated
230         * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in
231         * the case of stack-allocated).
232         *
233         * Returns: a new, floating, #GVariant
234         *
235         * Since: 2.40
236         */
237        public Variant end()
238        {
239                auto p = g_variant_dict_end(gVariantDict);
240               
241                if(p is null)
242                {
243                        return null;
244                }
245               
246                return new Variant(cast(GVariant*) p);
247        }
248
249        /**
250         * Initialises a #GVariantDict structure.
251         *
252         * If @from_asv is given, it is used to initialise the dictionary.
253         *
254         * This function completely ignores the previous contents of @dict.  On
255         * one hand this means that it is valid to pass in completely
256         * uninitialised memory.  On the other hand, this means that if you are
257         * initialising over top of an existing #GVariantDict you need to first
258         * call g_variant_dict_clear() in order to avoid leaking memory.
259         *
260         * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a
261         * #GVariantDict that was initialised with this function.  If you ever
262         * pass a reference to a #GVariantDict outside of the control of your
263         * own code then you should assume that the person receiving that
264         * reference may try to use reference counting; you should use
265         * g_variant_dict_new() instead of this function.
266         *
267         * Params:
268         *     fromAsv = the initial value for @dict
269         *
270         * Since: 2.40
271         */
272        public void init(Variant fromAsv)
273        {
274                g_variant_dict_init(gVariantDict, (fromAsv is null) ? null : fromAsv.getVariantStruct());
275        }
276
277        /**
278         * Inserts (or replaces) a key in a #GVariantDict.
279         *
280         * @value is consumed if it is floating.
281         *
282         * Params:
283         *     key = the key to insert a value for
284         *     value = the value to insert
285         *
286         * Since: 2.40
287         */
288        public void insertValue(string key, Variant value)
289        {
290                g_variant_dict_insert_value(gVariantDict, Str.toStringz(key), (value is null) ? null : value.getVariantStruct());
291        }
292
293        /**
294         * Looks up a value in a #GVariantDict.
295         *
296         * If @key is not found in @dictionary, %NULL is returned.
297         *
298         * The @expected_type string specifies what type of value is expected.
299         * If the value associated with @key has a different type then %NULL is
300         * returned.
301         *
302         * If the key is found and the value has the correct type, it is
303         * returned.  If @expected_type was specified then any non-%NULL return
304         * value will have this type.
305         *
306         * Params:
307         *     key = the key to lookup in the dictionary
308         *     expectedType = a #GVariantType, or %NULL
309         *
310         * Returns: the value of the dictionary key, or %NULL
311         *
312         * Since: 2.40
313         */
314        public Variant lookupValue(string key, VariantType expectedType)
315        {
316                auto p = g_variant_dict_lookup_value(gVariantDict, Str.toStringz(key), (expectedType is null) ? null : expectedType.getVariantTypeStruct());
317               
318                if(p is null)
319                {
320                        return null;
321                }
322               
323                return new Variant(cast(GVariant*) p, true);
324        }
325
326        /**
327         * Increases the reference count on @dict.
328         *
329         * Don't call this on stack-allocated #GVariantDict instances or bad
330         * things will happen.
331         *
332         * Returns: a new reference to @dict
333         *
334         * Since: 2.40
335         */
336        public VariantDict doref()
337        {
338                auto p = g_variant_dict_ref(gVariantDict);
339               
340                if(p is null)
341                {
342                        return null;
343                }
344               
345                return new VariantDict(cast(GVariantDict*) p, true);
346        }
347
348        /**
349         * Removes a key and its associated value from a #GVariantDict.
350         *
351         * Params:
352         *     key = the key to remove
353         *
354         * Returns: %TRUE if the key was found and removed
355         *
356         * Since: 2.40
357         */
358        public bool remove(string key)
359        {
360                return g_variant_dict_remove(gVariantDict, Str.toStringz(key)) != 0;
361        }
362
363        /**
364         * Decreases the reference count on @dict.
365         *
366         * In the event that there are no more references, releases all memory
367         * associated with the #GVariantDict.
368         *
369         * Don't call this on stack-allocated #GVariantDict instances or bad
370         * things will happen.
371         *
372         * Since: 2.40
373         */
374        public void unref()
375        {
376                g_variant_dict_unref(gVariantDict);
377        }
378}
Note: See TracBrowser for help on using the repository browser.