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