:right-sidebar: True VariantDict =================================================================== .. currentmodule:: gi.repository.GLib .. versionadded:: 2.40 .. class:: VariantDict(**kwargs) :no-contents-entry: :obj:`~gi.repository.GLib.VariantDict` is a mutable interface to :obj:`~gi.repository.GLib.Variant` dictionaries. It can be used for doing a sequence of dictionary lookups in an efficient way on an existing :obj:`~gi.repository.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. :obj:`~gi.repository.GLib.VariantDict` can only be used with %G_VARIANT_TYPE_VARDICT dictionaries. It is possible to use :obj:`~gi.repository.GLib.VariantDict` allocated on the stack or on the heap. When using a stack-allocated :obj:`~gi.repository.GLib.VariantDict`\, you begin with a call to :func:`~gi.repository.GLib.VariantDict.init` and free the resources with a call to :func:`~gi.repository.GLib.VariantDict.clear`. Heap-allocated :obj:`~gi.repository.GLib.VariantDict` follows normal refcounting rules: you allocate it with :func:`~gi.repository.GLib.VariantDict.new` and use :func:`~gi.repository.GLib.VariantDict.ref` and :func:`~gi.repository.GLib.VariantDict.unref`. :func:`~gi.repository.GLib.VariantDict.end` is used to convert the :obj:`~gi.repository.GLib.VariantDict` back into a dictionary-type :obj:`~gi.repository.GLib.Variant`\. When used with stack-allocated instances, this also implicitly frees all associated memory, but for heap-allocated instances, you must still call :func:`~gi.repository.GLib.VariantDict.unref` afterwards. You will typically want to use a heap-allocated :obj:`~gi.repository.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 :obj:`~gi.repository.GLib.Variant`\. Using a stack-allocated GVariantDict -------------------------------------------------------------------------------- .. code-block:: C :dedent: 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 -------------------------------------------------------------------------------- .. code-block:: C :dedent: 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; } Constructors ------------ .. rst-class:: interim-class .. class:: VariantDict :no-index: .. classmethod:: new(from_asv: ~gi.repository.GLib.Variant | None = None) -> ~gi.repository.GLib.VariantDict Allocates and initialises a new :obj:`~gi.repository.GLib.VariantDict`\. You should call :func:`~gi.repository.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 :obj:`~gi.repository.GLib.VariantDict` directly on the stack of the calling function and initialise it with :func:`~gi.repository.GLib.VariantDict.init`. This is particularly useful when you are using :obj:`~gi.repository.GLib.VariantDict` to construct a :obj:`~gi.repository.GLib.Variant`\. .. versionadded:: 2.40 :param from_asv: the :obj:`~gi.repository.GLib.Variant` with which to initialise the dictionary Methods ------- .. rst-class:: interim-class .. class:: VariantDict :no-index: .. method:: clear() -> None Releases all memory associated with a :obj:`~gi.repository.GLib.VariantDict` without freeing the :obj:`~gi.repository.GLib.VariantDict` structure itself. It typically only makes sense to do this on a stack-allocated :obj:`~gi.repository.GLib.VariantDict` if you want to abort building the value part-way through. This function need not be called if you call :func:`~gi.repository.GLib.VariantDict.end` and it also doesn't need to be called on dicts allocated with g_variant_dict_new (see :func:`~gi.repository.GLib.VariantDict.unref` for that). It is valid to call this function on either an initialised :obj:`~gi.repository.GLib.VariantDict` or one that was previously cleared by an earlier call to :func:`~gi.repository.GLib.VariantDict.clear` but it is not valid to call this function on uninitialised memory. .. versionadded:: 2.40 .. method:: contains(key: str) -> bool Checks if ``key`` exists in ``dict``\. .. versionadded:: 2.40 :param key: the key to look up in the dictionary .. method:: end() -> ~gi.repository.GLib.Variant Returns the current value of ``dict`` as a :obj:`~gi.repository.GLib.Variant` 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 :obj:`~gi.repository.GLib.VariantDict`\) or by reinitialising it with :func:`~gi.repository.GLib.VariantDict.init` (in the case of stack-allocated). .. versionadded:: 2.40 .. method:: insert_value(key: str, value: ~gi.repository.GLib.Variant) -> None Inserts (or replaces) a key in a :obj:`~gi.repository.GLib.VariantDict`\. ``value`` is consumed if it is floating. .. versionadded:: 2.40 :param key: the key to insert a value for :param value: the value to insert .. method:: lookup_value(key: str, expected_type: ~gi.repository.GLib.VariantType | None = None) -> ~gi.repository.GLib.Variant | None Looks up a value in a :obj:`~gi.repository.GLib.VariantDict`\. If ``key`` is not found in ``dictionary``\, :const:`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 :const:`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-:const:`None` return value will have this type. .. versionadded:: 2.40 :param key: the key to look up in the dictionary :param expected_type: a :obj:`~gi.repository.GLib.VariantType`\, or :const:`None` .. method:: remove(key: str) -> bool Removes a key and its associated value from a :obj:`~gi.repository.GLib.VariantDict`\. .. versionadded:: 2.40 :param key: the key to remove :return: 0 if the file was successfully removed, -1 if an error occurred