GLib.VariantBuilder¶

Fields¶

None

Methods¶

class	`new` (type)
	`add_value` (value)
	`close` ()
	`end` ()
	`open` (type)
	`ref` ()
	`unref` ()

Details¶

class GLib.VariantBuilder¶

A utility type for constructing container-type GLib.Variant instances.

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

GLib.VariantBuilder is not threadsafe in any way. Do not attempt to access it from more than one thread.

classmethod new(type)[source]¶

Parameters:: type (GLib.VariantType) – a container type
Returns:: a GLib.VariantBuilder
Return type:: GLib.VariantBuilder

Allocates and initialises a new GLib.VariantBuilder.

You should call 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 GLib.VariantBuilder directly on the stack of the calling function and initialise it with g_variant_builder_init().

New in version 2.24.

add_value(value)[source]¶

Parameters:: value (GLib.Variant) – a GLib.Variant

Adds value to self.

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 GLib.Variant.ref_sink()), the self instance takes ownership of value.

New in version 2.24.

close()[source]¶

Closes the subcontainer inside the given self that was opened by the most recent call to 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).

New in version 2.24.

end()[source]¶

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

Ends the builder process and returns the constructed value.

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.VariantBuilder) or by reinitialising it with g_variant_builder_init() (in the case of stack-allocated). This means that for the stack-allocated builders there is no need to call g_variant_builder_clear() after the call to 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.

New in version 2.24.

open(type)[source]¶

Parameters:: type (GLib.VariantType) – the GLib.VariantType of the container

Opens a subcontainer inside the given self. When done adding items to the subcontainer, 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:

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

New in version 2.24.

ref()[source]¶

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

Increases the reference count on self.

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

New in version 2.24.

unref()[source]¶

Decreases the reference count on self.

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

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

New in version 2.24.