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