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