![]() |
![]() |
![]() |
![]() |
<GVariantBuilder>
A utility type for constructing container-type GVariant instances.
This is an opaque structure and may only be accessed using the following functions.
GVariantBuilder is not threadsafe in any way. Do not attempt to access it from more than one thread.
(define-values () (variant-builder:add-value self value))
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 g_variant_ref_sink()
),
the builder
instance takes ownership of value
.
(define-values () (variant-builder:close self))
Closes the subcontainer inside the given builder
that was opened by
the most recent call to g_variant_builder_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).
(define-values (%return) (variant-builder:end self))
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 GVariantBuilder) 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
g_variant_builder_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.
(define-values () (variant-builder:open self type))
Opens a subcontainer inside the given builder
. When done adding
items to the subcontainer, g_variant_builder_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);
(define-values (%return) (variant-builder:ref self))
Increases the reference count on builder
.
Don't call this on stack-allocated GVariantBuilder instances or bad things will happen.