common-lisp:standard-object, common-lisp:t

None

The g-variant-dict structure is a mutable interface to g-variant dictionaries.

It can be used for doing a sequence of dictionary lookups in an efficient way on an existing g-variant 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.

The g-variant-dict structure can only be used with "a(sv)" dictionaries.

It is possible to use g-variant-dict structures allocated on the stack or on the heap. When using a stack-allocated g-variant-dict structure, you begin with a call to the g-variant-dict-init function and free the resources with a call to the g-variant-dict-clear function.

Heap-allocated g-variant-dict structures follows normal refcounting rules: you allocate it with the g-variant-dict-new function and use the g-variant-dict-ref and g-variant-dict-unref functions.

The g-variant-dict-end function is used to convert the g-variant-dict structure back into a g-variant dictionary type. When used with stack-allocated instances, this also implicitly frees all associated memory, but for heap-allocated instances, you must still call the g-variant-dict-unref function afterwards.

You will typically want to use a heap-allocated g-variant-dict structure 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 g-variant instance.

Using a stack-allocated gvariant-dict instance:

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 a heap-allocated g-variant-dict instance:

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;
}