:right-sidebar: True

VariantBuilder
===================================================================

.. currentmodule:: gi.repository.GLib





.. class:: VariantBuilder(**kwargs)
   :no-contents-entry:






A utility type for constructing container-type :obj:`~gi.repository.GLib.Variant` instances.

This is an opaque structure and may only be accessed using the
following functions.

:obj:`~gi.repository.GLib.VariantBuilder` is not threadsafe in any way.  Do not attempt to
access it from more than one thread.


Constructors
------------

.. rst-class:: interim-class

.. class:: VariantBuilder
   :no-index:


   .. classmethod:: new(type: ~gi.repository.GLib.VariantType) -> ~gi.repository.GLib.VariantBuilder

      Allocates and initialises a new :obj:`~gi.repository.GLib.VariantBuilder`\.

      You should call :func:`~gi.repository.GLib.VariantBuilder.unref` on the return value when it
      is no longer needed.  The memory will not be automatically freed by
      any other call.

      In most cases it is easier to place a :obj:`~gi.repository.GLib.VariantBuilder` directly on
      the stack of the calling function and initialise it with
      :func:`~gi.repository.GLib.VariantBuilder.init`.


      .. versionadded:: 2.24





      :param type: a container type








Methods
-------

.. rst-class:: interim-class

.. class:: VariantBuilder
   :no-index:


   .. method:: add_value(value: ~gi.repository.GLib.Variant) -> None

      Adds ``value`` to ``builder``\.

      It is an error to call this function in any way that would create an
      inconsistent value to be constructed.  Some examples of this are
      putting different types of items into an array, putting the wrong
      types or number of items in a tuple, putting more than one value into
      a variant, etc.

      If ``value`` is a floating reference (see :func:`~gi.repository.GLib.Variant.ref_sink`),
      the ``builder`` instance takes ownership of ``value``\.


      .. versionadded:: 2.24





      :param value: a :obj:`~gi.repository.GLib.Variant`




   .. method:: close() -> None

      Closes the subcontainer inside the given ``builder`` that was opened by
      the most recent call to :func:`~gi.repository.GLib.VariantBuilder.open`.

      It is an error to call this function in any way that would create an
      inconsistent value to be constructed (ie: too few values added to the
      subcontainer).


      .. versionadded:: 2.24






      :return: :const:`True` on success, :const:`False` if there was an error.



   .. method:: end() -> ~gi.repository.GLib.Variant

      Ends the builder process and returns the constructed value.

      It is not permissible to use ``builder`` in any way after this call
      except for reference counting operations (in the case of a
      heap-allocated :obj:`~gi.repository.GLib.VariantBuilder`\) or by reinitialising it with
      :func:`~gi.repository.GLib.VariantBuilder.init` (in the case of stack-allocated). This
      means that for the stack-allocated builders there is no need to
      call :func:`~gi.repository.GLib.VariantBuilder.clear` after the call to
      :func:`~gi.repository.GLib.VariantBuilder.end`.

      It is an error to call this function in any way that would create an
      inconsistent value to be constructed (ie: insufficient number of
      items added to a container with a specific number of children
      required).  It is also an error to call this function if the builder
      was created with an indefinite array or maybe type and no children
      have been added; in this case it is impossible to infer the type of
      the empty array.


      .. versionadded:: 2.24








   .. method:: open(type: ~gi.repository.GLib.VariantType) -> None

      Opens a subcontainer inside the given ``builder``\.  When done adding
      items to the subcontainer, :func:`~gi.repository.GLib.VariantBuilder.close` must be called. ``type``
      is the type of the container: so to build a tuple of several values, ``type``
      must include the tuple itself.

      It is an error to call this function in any way that would cause an
      inconsistent value to be constructed (ie: adding too many values or
      a value of an incorrect type).

      Example of building a nested variant:


      .. code-block:: C
          :dedent:

          GVariantBuilder builder;
          guint32 some_number = get_number ();
          g_autoptr (GHashTable) some_dict = get_dict ();
          GHashTableIter iter;
          const gchar *key;
          const GVariant *value;
          g_autoptr (GVariant) output = NULL;

          g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})"));
          g_variant_builder_add (&builder, "u", some_number);
          g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));

          g_hash_table_iter_init (&iter, some_dict);
          while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value))
            {
              g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}"));
              g_variant_builder_add (&builder, "s", key);
              g_variant_builder_add (&builder, "v", value);
              g_variant_builder_close (&builder);
            }

          g_variant_builder_close (&builder);

          output = g_variant_builder_end (&builder);


      .. versionadded:: 2.24





      :param type: the :obj:`~gi.repository.GLib.VariantType` of the container


      :return: a new file descriptor, or -1 if an error occurred.
             The return value can be used exactly like the return value
             from open().