GLib.VariantDict

Fields

None

Methods

class	new (from_asv)
	clear ()
	contains (key)
	end ()
	insert_value (key, value)
	lookup_value (key, expected_type)
	ref ()
	remove (key)
	unref ()

Details

class GLib.VariantDict

GLib.VariantDict is a mutable interface to GLib.Variant dictionaries.

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

GLib.VariantDict can only be used with %G_VARIANT_TYPE_VARDICT dictionaries.

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

Heap-allocated GLib.VariantDict follows normal refcounting rules: you allocate it with GLib.VariantDict.new() and use GLib.VariantDict.ref() and GLib.VariantDict.unref().

GLib.VariantDict.end() is used to convert the GLib.VariantDict back into a dictionary-type GLib.Variant. When used with stack-allocated instances, this also implicitly frees all associated memory, but for heap-allocated instances, you must still call GLib.VariantDict.unref() afterwards.

You will typically want to use a heap-allocated GLib.VariantDict 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 GLib.Variant.

Using a stack-allocated GLib.VariantDict

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 GLib.VariantDict

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

New in version 2.40.

classmethod new(from_asv)

Parameters:from_asv (GLib.Variant or None) – the GLib.Variant with which to initialise the dictionary Returns:a GLib.VariantDict Return type:GLib.VariantDict

Allocates and initialises a new GLib.VariantDict.

You should call GLib.VariantDict.unref() on the return value when it is no longer needed. The memory will not be automatically freed by any other call.

In some cases it may be easier to place a GLib.VariantDict directly on the stack of the calling function and initialise it with g_variant_dict_init(). This is particularly useful when you are using GLib.VariantDict to construct a GLib.Variant.

New in version 2.40.

clear()

Releases all memory associated with a GLib.VariantDict without freeing the GLib.VariantDict structure itself.

It typically only makes sense to do this on a stack-allocated GLib.VariantDict if you want to abort building the value part-way through. This function need not be called if you call GLib.VariantDict.end() and it also doesn’t need to be called on dicts allocated with GLib.VariantDict.new (see GLib.VariantDict.unref() for that).

It is valid to call this function on either an initialised GLib.VariantDict or one that was previously cleared by an earlier call to GLib.VariantDict.clear() but it is not valid to call this function on uninitialised memory.

New in version 2.40.

contains(key)

Parameters:key (str) – the key to look up in the dictionary Returns:True if key is in self Return type:bool

Checks if key exists in self.

New in version 2.40.

end()

Returns:a new, floating, GLib.Variant Return type:GLib.Variant

Returns the current value of self as a GLib.Variant of type %G_VARIANT_TYPE_VARDICT, clearing it in the process.

It is not permissible to use self in any way after this call except for reference counting operations (in the case of a heap-allocated GLib.VariantDict) or by reinitialising it with g_variant_dict_init() (in the case of stack-allocated).

New in version 2.40.

insert_value(key, value)

Parameters:

• key (str) – the key to insert a value for
• value (GLib.Variant) – the value to insert

Inserts (or replaces) a key in a GLib.VariantDict.

value is consumed if it is floating.

New in version 2.40.

lookup_value(key, expected_type)

Parameters:

• key (str) – the key to look up in the dictionary
• expected_type (GLib.VariantType or None) – a GLib.VariantType, or None

Returns:

the value of the dictionary key, or None

Return type:

GLib.Variant

Looks up a value in a GLib.VariantDict.

If key is not found in dictionary, None is returned.

The expected_type string specifies what type of value is expected. If the value associated with key has a different type then None 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-None return value will have this type.

New in version 2.40.

ref()

Returns:a new reference to self Return type:GLib.VariantDict

Increases the reference count on self.

Don’t call this on stack-allocated GLib.VariantDict instances or bad things will happen.

New in version 2.40.

remove(key)

Parameters:key (str) – the key to remove Returns:True if the key was found and removed Return type:bool

Removes a key and its associated value from a GLib.VariantDict.

New in version 2.40.

unref()

Decreases the reference count on self.

In the event that there are no more references, releases all memory associated with the GLib.VariantDict.

Don’t call this on stack-allocated GLib.VariantDict instances or bad things will happen.

New in version 2.40.