GI.GLib.Structs.VariantBuilder

A utility type for constructing container-type GVariant instances.

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

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

Exported types

newtype VariantBuilder

Memory-managed wrapper type.

Constructors

VariantBuilder (ManagedPtr VariantBuilder)

Instances

Eq VariantBuilder

Defined in GI.GLib.Structs.VariantBuilder

Methods

(==) :: VariantBuilder -> VariantBuilder -> Bool

(/=) :: VariantBuilder -> VariantBuilder -> Bool

GBoxed VariantBuilder

Defined in GI.GLib.Structs.VariantBuilder

ManagedPtrNewtype VariantBuilder

Defined in GI.GLib.Structs.VariantBuilder

Methods

toManagedPtr :: VariantBuilder -> ManagedPtr VariantBuilder

TypedObject VariantBuilder

Defined in GI.GLib.Structs.VariantBuilder

Methods

glibType :: IO GType

HasParentTypes VariantBuilder

Defined in GI.GLib.Structs.VariantBuilder

IsGValue (Maybe VariantBuilder)

Convert VariantBuilder to and from GValue. See toGValue and fromGValue.

Defined in GI.GLib.Structs.VariantBuilder

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe VariantBuilder -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe VariantBuilder)

type ParentTypes VariantBuilder

Defined in GI.GLib.Structs.VariantBuilder

type ParentTypes VariantBuilder = '[] :: [Type]

Methods

Click to display all available methods, including inherited ones

Methods

addValue, close, end, open, ref, unref.

Getters

None.

Setters

None.

addValue

variantBuilderAddValue

Arguments

:: (HasCallStack, MonadIO m)

=> VariantBuilder

builder: a VariantBuilder

-> GVariant

value: a GVariant

-> m ()

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 variantRefSink), the builder instance takes ownership of value.

Since: 2.24

close

variantBuilderClose

Arguments

:: (HasCallStack, MonadIO m)

=> VariantBuilder

builder: a VariantBuilder

-> m ()

Closes the subcontainer inside the given builder that was opened by the most recent call to variantBuilderOpen.

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

Since: 2.24

end

variantBuilderEnd

Arguments

:: (HasCallStack, MonadIO m)

=> VariantBuilder

builder: a VariantBuilder

-> m GVariant

Returns: a new, floating, GVariant

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 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 variantBuilderEnd.

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.

Since: 2.24

new

variantBuilderNew

Arguments

:: (HasCallStack, MonadIO m)

=> VariantType

type: a container type

-> m VariantBuilder

Returns: a VariantBuilder

Allocates and initialises a new VariantBuilder.

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

Since: 2.24

open

variantBuilderOpen

Arguments

:: (HasCallStack, MonadIO m)

=> VariantBuilder

builder: a VariantBuilder

-> VariantType

type: the VariantType of the container

-> m ()

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

C code

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

Since: 2.24

ref

variantBuilderRef

Arguments

:: (HasCallStack, MonadIO m)

=> VariantBuilder

builder: a VariantBuilder allocated by variantBuilderNew

-> m VariantBuilder

Returns: a new reference to builder

Increases the reference count on builder.

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

Since: 2.24

unref

variantBuilderUnref

Arguments

:: (HasCallStack, MonadIO m)

=> VariantBuilder

builder: a VariantBuilder allocated by variantBuilderNew

-> m ()

Decreases the reference count on builder.

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

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

Since: 2.24