VariantDict

#GVariantDict is a mutable interface to #GVariant dictionaries.

It can be used for doing a sequence of dictionary lookups in an efficient way on an existing #GVariant dictionary or it can be used to construct new dictionaries with a hashtable-like interface. It can also be used for taking existing dictionaries and modifying them in order to create new ones.

#GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT dictionaries.

It is possible to use #GVariantDict allocated on the stack or on the heap. When using a stack-allocated #GVariantDict, you begin with a call to g_variant_dict_init() and free the resources with a call to g_variant_dict_clear().

Heap-allocated #GVariantDict follows normal refcounting rules: you allocate it with g_variant_dict_new() and use g_variant_dict_ref() and g_variant_dict_unref().

g_variant_dict_end() is used to convert the #GVariantDict back into a dictionary-type #GVariant. When used with stack-allocated instances, this also implicitly frees all associated memory, but for heap-allocated instances, you must still call g_variant_dict_unref() afterwards.

You will typically want to use a heap-allocated #GVariantDict when you expose it as part of an API. For most other uses, the stack-allocated form will be more convenient.

Consider the following two examples that do the same thing in each style: take an existing dictionary and look up the "count" uint32 key, adding 1 to it if it is found, or returning an error if the key is not found. Each returns the new dictionary as a floating #GVariant.

Using a stack-allocated GVariantDict

|[ GVariant * add_to_count (GVariant *orig, GError **error) { GVariantDict dict; guint32 count;

g_variant_dict_init (&dict, orig); if (!g_variant_dict_lookup (&dict, "count", "u", &count)) { g_set_error (...); g_variant_dict_clear (&dict); return NULL; }

g_variant_dict_insert (&dict, "count", "u", count + 1);

return g_variant_dict_end (&dict); } ]|

Using heap-allocated GVariantDict

|[ GVariant * add_to_count (GVariant *orig, GError **error) { GVariantDict *dict; GVariant *result; guint32 count;

dict = g_variant_dict_new (orig);

if (g_variant_dict_lookup (dict, "count", "u", &count)) { g_variant_dict_insert (dict, "count", "u", count + 1); result = g_variant_dict_end (dict); } else { g_set_error (...); result = NULL; }

g_variant_dict_unref (dict);

return result; } ]|

class VariantDict {

protected

GVariantDict* gVariantDict;

protected

bool ownedRef;

GVariantDict* getVariantDictStruct(bool transferOwnership);

void* getStruct();

this(GVariantDict* gVariantDict, bool ownedRef);

~this();

this(Variant fromAsv);

void clear();

bool contains(string key);

Variant end();

void init(Variant fromAsv);

void insertValue(string key, Variant value);

Variant lookupValue(string key, VariantType expectedType);

VariantDict doref();

bool remove(string key);

void unref();

}

Constructors

this this(GVariantDict* gVariantDict, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(Variant fromAsv): Allocates and initialises a new #GVariantDict.

Destructor

~this ~this(): Undocumented in source.

Members

Functions

clear void clear(): Releases all memory associated with a #GVariantDict without freeing the #GVariantDict structure itself.
contains bool contains(string key): Checks if @key exists in @dict.
doref VariantDict doref(): Increases the reference count on @dict.
end Variant end(): Returns the current value of @dict as a #GVariant of type %G_VARIANT_TYPE_VARDICT, clearing it in the process.
getStruct void* getStruct(): the main Gtk struct as a void*
getVariantDictStruct GVariantDict* getVariantDictStruct(bool transferOwnership): Get the main Gtk struct
init void init(Variant fromAsv): Initialises a #GVariantDict structure.
insertValue void insertValue(string key, Variant value): Inserts (or replaces) a key in a #GVariantDict.
lookupValue Variant lookupValue(string key, VariantType expectedType): Looks up a value in a #GVariantDict.
remove bool remove(string key): Removes a key and its associated value from a #GVariantDict.
unref void unref(): Decreases the reference count on @dict.

Variables

gVariantDict GVariantDict* gVariantDict;: the main Gtk struct
ownedRef bool ownedRef;: Undocumented in source.