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 }