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