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  * Conversion parameters:
26  * inFile  = 
27  * outPack = glib
28  * outFile = VariantIter
29  * strct   = GVariantIter
30  * realStrct=
31  * ctorStrct=
32  * clss    = VariantIter
33  * interf  = 
34  * class Code: Yes
35  * interface Code: No
36  * template for:
37  * extend  = 
38  * implements:
39  * prefixes:
40  * 	- g_variant_iter_
41  * omit structs:
42  * omit prefixes:
43  * omit code:
44  * omit signals:
45  * imports:
46  * 	- glib.Str
47  * 	- glib.Variant
48  * 	- gtkc.paths
49  * 	- gtkc.Loader
50  * structWrap:
51  * 	- GVariant* -> Variant
52  * 	- GVariantIter* -> VariantIter
53  * module aliases:
54  * local aliases:
55  * overrides:
56  */
57 
58 module glib.VariantIter;
59 
60 public  import gtkc.glibtypes;
61 
62 private import gtkc.glib;
63 private import glib.ConstructionException;
64 
65 private import glib.Str;
66 private import glib.Variant;
67 private import gtkc.paths;
68 private import gtkc.Loader;
69 
70 
71 
72 /**
73  * GVariant is a variant datatype; it stores a value along with
74  * information about the type of that value. The range of possible
75  * values is determined by the type. The type system used by GVariant
76  * is GVariantType.
77  *
78  * GVariant instances always have a type and a value (which are given
79  * at construction time). The type and value of a GVariant instance
80  * can never change other than by the GVariant itself being
81  * destroyed. A GVariant cannot contain a pointer.
82  *
83  * GVariant is reference counted using g_variant_ref() and
84  * g_variant_unref(). GVariant also has floating reference counts --
85  * see g_variant_ref_sink().
86  *
87  * GVariant is completely threadsafe. A GVariant instance can be
88  * concurrently accessed in any way from any number of threads without
89  * problems.
90  *
91  * GVariant is heavily optimised for dealing with data in serialised
92  * form. It works particularly well with data located in memory-mapped
93  * files. It can perform nearly all deserialisation operations in a
94  * small constant time, usually touching only a single memory page.
95  * Serialised GVariant data can also be sent over the network.
96  *
97  * GVariant is largely compatible with D-Bus. Almost all types of
98  * GVariant instances can be sent over D-Bus. See GVariantType for
99  * exceptions. (However, GVariant's serialisation format is not the same
100  * as the serialisation format of a D-Bus message body: use GDBusMessage,
101  * in the gio library, for those.)
102  *
103  * For space-efficiency, the GVariant serialisation format does not
104  * automatically include the variant's type or endianness, which must
105  * either be implied from context (such as knowledge that a particular
106  * file format always contains a little-endian G_VARIANT_TYPE_VARIANT)
107  * or supplied out-of-band (for instance, a type and/or endianness
108  * indicator could be placed at the beginning of a file, network message
109  * or network stream).
110  *
111  * A GVariant's size is limited mainly by any lower level operating
112  * system constraints, such as the number of bits in gsize. For
113  * example, it is reasonable to have a 2GB file mapped into memory
114  * with GMappedFile, and call g_variant_new_from_data() on it.
115  *
116  * For convenience to C programmers, GVariant features powerful
117  * varargs-based value construction and destruction. This feature is
118  * designed to be embedded in other libraries.
119  *
120  * There is a Python-inspired text language for describing GVariant
121  * values. GVariant includes a printer for this language and a parser
122  * with type inferencing.
123  *
124  * Memory Use
125  *
126  *  GVariant tries to be quite efficient with respect to memory use.
127  *  This section gives a rough idea of how much memory is used by the
128  *  current implementation. The information here is subject to change
129  *  in the future.
130  *
131  *  The memory allocated by GVariant can be grouped into 4 broad
132  *  purposes: memory for serialised data, memory for the type
133  *  information cache, buffer management memory and memory for the
134  *  GVariant structure itself.
135  *
136  * Serialised Data Memory
137  *
138  *  This is the memory that is used for storing GVariant data in
139  *  serialised form. This is what would be sent over the network or
140  *  what would end up on disk.
141  *
142  *  The amount of memory required to store a boolean is 1 byte. 16,
143  *  32 and 64 bit integers and double precision floating point numbers
144  *  use their "natural" size. Strings (including object path and
145  *  signature strings) are stored with a nul terminator, and as such
146  *  use the length of the string plus 1 byte.
147  *
148  *  Maybe types use no space at all to represent the null value and
149  *  use the same amount of space (sometimes plus one byte) as the
150  *  equivalent non-maybe-typed value to represent the non-null case.
151  *
152  *  Arrays use the amount of space required to store each of their
153  *  members, concatenated. Additionally, if the items stored in an
154  *  array are not of a fixed-size (ie: strings, other arrays, etc)
155  *  then an additional framing offset is stored for each item. The
156  *  size of this offset is either 1, 2 or 4 bytes depending on the
157  *  overall size of the container. Additionally, extra padding bytes
158  *  are added as required for alignment of child values.
159  *
160  *  Tuples (including dictionary entries) use the amount of space
161  *  required to store each of their members, concatenated, plus one
162  *  framing offset (as per arrays) for each non-fixed-sized item in
163  *  the tuple, except for the last one. Additionally, extra padding
164  *  bytes are added as required for alignment of child values.
165  *
166  *  Variants use the same amount of space as the item inside of the
167  *  variant, plus 1 byte, plus the length of the type string for the
168  *  item inside the variant.
169  *
170  *  As an example, consider a dictionary mapping strings to variants.
171  *  In the case that the dictionary is empty, 0 bytes are required for
172  *  the serialisation.
173  *
174  *  If we add an item "width" that maps to the int32 value of 500 then
175  *  we will use 4 byte to store the int32 (so 6 for the variant
176  *  containing it) and 6 bytes for the string. The variant must be
177  *  aligned to 8 after the 6 bytes of the string, so that's 2 extra
178  *  bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
179  *  for the dictionary entry. An additional 1 byte is added to the
180  *  array as a framing offset making a total of 15 bytes.
181  *
182  *  If we add another entry, "title" that maps to a nullable string
183  *  that happens to have a value of null, then we use 0 bytes for the
184  *  null value (and 3 bytes for the variant to contain it along with
185  *  its type string) plus 6 bytes for the string. Again, we need 2
186  *  padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
187  *
188  *  We now require extra padding between the two items in the array.
189  *  After the 14 bytes of the first item, that's 2 bytes required. We
190  *  now require 2 framing offsets for an extra two bytes. 14 + 2 + 11
191  *  + 2 = 29 bytes to encode the entire two-item dictionary.
192  *
193  * Type Information Cache
194  *
195  *  For each GVariant type that currently exists in the program a type
196  *  information structure is kept in the type information cache. The
197  *  type information structure is required for rapid deserialisation.
198  *
199  *  Continuing with the above example, if a GVariant exists with the
200  *  type "a{sv}" then a type information struct will exist for
201  *  "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
202  *  will share the same type information. Additionally, all
203  *  single-digit types are stored in read-only static memory and do
204  *  not contribute to the writable memory footprint of a program using
205  *  GVariant.
206  *
207  *  Aside from the type information structures stored in read-only
208  *  memory, there are two forms of type information. One is used for
209  *  container types where there is a single element type: arrays and
210  *  maybe types. The other is used for container types where there
211  *  are multiple element types: tuples and dictionary entries.
212  *
213  *  Array type info structures are 6 * sizeof (void *), plus the
214  *  memory required to store the type string itself. This means that
215  *  on 32bit systems, the cache entry for "a{sv}" would require 30
216  *  bytes of memory (plus malloc overhead).
217  *
218  *  Tuple type info structures are 6 * sizeof (void *), plus 4 *
219  *  sizeof (void *) for each item in the tuple, plus the memory
220  *  required to store the type string itself. A 2-item tuple, for
221  *  example, would have a type information structure that consumed
222  *  writable memory in the size of 14 * sizeof (void *) (plus type
223  *  string) This means that on 32bit systems, the cache entry for
224  *  "{sv}" would require 61 bytes of memory (plus malloc overhead).
225  *
226  *  This means that in total, for our "a{sv}" example, 91 bytes of
227  *  type information would be allocated.
228  *
229  *  The type information cache, additionally, uses a GHashTable to
230  *  store and lookup the cached items and stores a pointer to this
231  *  hash table in static storage. The hash table is freed when there
232  *  are zero items in the type cache.
233  *
234  *  Although these sizes may seem large it is important to remember
235  *  that a program will probably only have a very small number of
236  *  different types of values in it and that only one type information
237  *  structure is required for many different values of the same type.
238  *
239  * Buffer Management Memory
240  *
241  *  GVariant uses an internal buffer management structure to deal
242  *  with the various different possible sources of serialised data
243  *  that it uses. The buffer is responsible for ensuring that the
244  *  correct call is made when the data is no longer in use by
245  *  GVariant. This may involve a g_free() or a g_slice_free() or
246  *  even g_mapped_file_unref().
247  *
248  *  One buffer management structure is used for each chunk of
249  *  serialised data. The size of the buffer management structure is 4
250  *  * (void *). On 32bit systems, that's 16 bytes.
251  *
252  * GVariant structure
253  *
254  *  The size of a GVariant structure is 6 * (void *). On 32 bit
255  *  systems, that's 24 bytes.
256  *
257  *  GVariant structures only exist if they are explicitly created
258  *  with API calls. For example, if a GVariant is constructed out of
259  *  serialised data for the example given above (with the dictionary)
260  *  then although there are 9 individual values that comprise the
261  *  entire dictionary (two keys, two values, two variants containing
262  *  the values, two dictionary entries, plus the dictionary itself),
263  *  only 1 GVariant instance exists -- the one referring to the
264  *  dictionary.
265  *
266  *  If calls are made to start accessing the other values then
267  *  GVariant instances will exist for those values only for as long
268  *  as they are in use (ie: until you call g_variant_unref()). The
269  *  type information is shared. The serialised data and the buffer
270  *  management structure for that serialised data is shared by the
271  *  child.
272  *
273  * Summary
274  *
275  *  To put the entire example together, for our dictionary mapping
276  *  strings to variants (with two entries, as given above), we are
277  *  using 91 bytes of memory for type information, 29 byes of memory
278  *  for the serialised data, 16 bytes for buffer management and 24
279  *  bytes for the GVariant instance, or a total of 160 bytes, plus
280  *  malloc overhead. If we were to use g_variant_get_child_value() to
281  *  access the two dictionary entries, we would use an additional 48
282  *  bytes. If we were to have other dictionaries of the same type, we
283  *  would use more memory for the serialised data and buffer
284  *  management for those dictionaries, but the type information would
285  *  be shared.
286  */
287 public class VariantIter
288 {
289 	
290 	/** the main Gtk struct */
291 	protected GVariantIter* gVariantIter;
292 	
293 	
294 	/** Get the main Gtk struct */
295 	public GVariantIter* getVariantIterStruct()
296 	{
297 		return gVariantIter;
298 	}
299 	
300 	
301 	/** the main Gtk struct as a void* */
302 	protected void* getStruct()
303 	{
304 		return cast(void*)gVariantIter;
305 	}
306 	
307 	/**
308 	 * Sets our main struct and passes it to the parent class
309 	 */
310 	public this (GVariantIter* gVariantIter)
311 	{
312 		this.gVariantIter = gVariantIter;
313 	}
314 	
315 	~this ()
316 	{
317 		if (  Linker.isLoaded(LIBRARY.GLIB) && gVariantIter !is null )
318 		{
319 			g_variant_iter_free(gVariantIter);
320 		}
321 	}
322 	
323 	/**
324 	 */
325 	
326 	/**
327 	 * Creates a new heap-allocated GVariantIter to iterate over the
328 	 * container that was being iterated over by iter. Iteration begins on
329 	 * the new iterator from the current position of the old iterator but
330 	 * the two copies are independent past that point.
331 	 * Use g_variant_iter_free() to free the return value when you no longer
332 	 * need it.
333 	 * A reference is taken to the container that iter is iterating over
334 	 * and will be releated only when g_variant_iter_free() is called.
335 	 * Since 2.24
336 	 * Returns: a new heap-allocated GVariantIter. [transfer full]
337 	 */
338 	public VariantIter copy()
339 	{
340 		// GVariantIter * g_variant_iter_copy (GVariantIter *iter);
341 		auto p = g_variant_iter_copy(gVariantIter);
342 		
343 		if(p is null)
344 		{
345 			return null;
346 		}
347 		
348 		return new VariantIter(cast(GVariantIter*) p);
349 	}
350 	
351 	/**
352 	 * Frees a heap-allocated GVariantIter. Only call this function on
353 	 * iterators that were returned by g_variant_iter_new() or
354 	 * g_variant_iter_copy().
355 	 * Since 2.24
356 	 */
357 	public void free()
358 	{
359 		// void g_variant_iter_free (GVariantIter *iter);
360 		g_variant_iter_free(gVariantIter);
361 	}
362 	
363 	/**
364 	 * Initialises (without allocating) a GVariantIter. iter may be
365 	 * completely uninitialised prior to this call; its old value is
366 	 * ignored.
367 	 * The iterator remains valid for as long as value exists, and need not
368 	 * be freed in any way.
369 	 * Since 2.24
370 	 * Params:
371 	 * value = a container GVariant
372 	 * Returns: the number of items in value
373 	 */
374 	public gsize init(Variant value)
375 	{
376 		// gsize g_variant_iter_init (GVariantIter *iter,  GVariant *value);
377 		return g_variant_iter_init(gVariantIter, (value is null) ? null : value.getVariantStruct());
378 	}
379 	
380 	/**
381 	 * Queries the number of child items in the container that we are
382 	 * iterating over. This is the total number of items -- not the number
383 	 * of items remaining.
384 	 * This function might be useful for preallocation of arrays.
385 	 * Since 2.24
386 	 * Returns: the number of children in the container
387 	 */
388 	public gsize nChildren()
389 	{
390 		// gsize g_variant_iter_n_children (GVariantIter *iter);
391 		return g_variant_iter_n_children(gVariantIter);
392 	}
393 	
394 	/**
395 	 * Creates a heap-allocated GVariantIter for iterating over the items
396 	 * in value.
397 	 * Use g_variant_iter_free() to free the return value when you no longer
398 	 * need it.
399 	 * A reference is taken to value and will be released only when
400 	 * g_variant_iter_free() is called.
401 	 * Since 2.24
402 	 * Params:
403 	 * value = a container GVariant
404 	 * Throws: ConstructionException GTK+ fails to create the object.
405 	 */
406 	public this (Variant value)
407 	{
408 		// GVariantIter * g_variant_iter_new (GVariant *value);
409 		auto p = g_variant_iter_new((value is null) ? null : value.getVariantStruct());
410 		if(p is null)
411 		{
412 			throw new ConstructionException("null returned by g_variant_iter_new((value is null) ? null : value.getVariantStruct())");
413 		}
414 		this(cast(GVariantIter*) p);
415 	}
416 	
417 	/**
418 	 * Gets the next item in the container. If no more items remain then
419 	 * NULL is returned.
420 	 * Use g_variant_unref() to drop your reference on the return value when
421 	 * you no longer need it.
422 	 * $(DDOC_COMMENT example)
423 	 * Since 2.24
424 	 * Returns: a GVariant, or NULL. [allow-none][transfer full]
425 	 */
426 	public Variant nextValue()
427 	{
428 		// GVariant * g_variant_iter_next_value (GVariantIter *iter);
429 		auto p = g_variant_iter_next_value(gVariantIter);
430 		
431 		if(p is null)
432 		{
433 			return null;
434 		}
435 		
436 		return new Variant(cast(GVariant*) p);
437 	}
438 }