![]() |
![]() |
![]() |
![]() |
<GVariantDict>
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.
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); }
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; }
(define-values () (variant-dict:clear self))
Releases all memory associated with a GVariantDict without freeing the GVariantDict structure itself.
It typically only makes sense to do this on a stack-allocated
GVariantDict if you want to abort building the value part-way
through. This function need not be called if you call
g_variant_dict_end()
and it also doesn't need to be called on dicts
allocated with g_variant_dict_new (see g_variant_dict_unref()
for
that).
It is valid to call this function on either an initialised
GVariantDict or one that was previously cleared by an earlier call
to g_variant_dict_clear()
but it is not valid to call this function
on uninitialised memory.
(define-values (%return) (variant-dict:end self))
Returns the current value of dict
as a GVariant of type
G_VARIANT_TYPE_VARDICT
, clearing it in the process.
It is not permissible to use dict
in any way after this call except
for reference counting operations (in the case of a heap-allocated
GVariantDict) or by reinitialising it with g_variant_dict_init()
(in
the case of stack-allocated).
(define-values () (variant-dict:insert-value self key value))
Inserts (or replaces) a key in a GVariantDict.
value
is consumed if it is floating.
(define-values (%return) (variant-dict:lookup-value self key expected-type))
Looks up a value in a GVariantDict.
If key
is not found in dictionary
, NULL
is returned.
The expected_type
string specifies what type of value is expected.
If the value associated with key
has a different type then NULL
is
returned.
If the key is found and the value has the correct type, it is
returned. If expected_type
was specified then any non-NULL
return
value will have this type.
(define-values (%return) (variant-dict:ref self))
Increases the reference count on dict
.
Don't call this on stack-allocated GVariantDict instances or bad things will happen.
(define-values (%return) (variant-dict:remove? self key))
Removes a key and its associated value from a GVariantDict.