#------------------------------------------------------------------------------- #--[Class Description]---------------------------------------------------------- #-------------------------------------------------------------------------------

Gnome::Glib::N-VariantBuilder

Description

A utility type for constructing container-type Gnome::Glib::N-Variant instances.

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

Gnome::Glib::N-VariantBuilder is not threadsafe in any way. Do not attempt to access it from more than one thread.

#------------------------------------------------------------------------------- #--[Class Initialization]------------------------------------------------------- #-------------------------------------------------------------------------------

Class initialization

new

:native-object

Create an object using a native object from elsewhere. See also Gnome::N::TopLevelSupportClass.

multi method new ( N-Object :$native-object! )

#-------------------------------------------------------------------------------

new-variantbuilder

Allocates and initialises a new Gnome::Glib::N-VariantBuilder.

You should call .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 Gnome::Glib::N-VariantBuilder directly on the stack of the calling function and initialise it with .init().

method new-variantbuilder ( N-Object $type --> Gnome::Glib::VariantBuilder \)

• $type; a container type

#------------------------------------------------------------------------------- #--[Methods]-------------------------------------------------------------------- #-------------------------------------------------------------------------------

Methods

#-------------------------------------------------------------------------------

add This function is not yet available

Adds to a Gnome::Glib::N-VariantBuilder.

This call is a convenience wrapper that is exactly equivalent to calling g_variant_new() followed by .add-value().

Note that the arguments must be of the correct width for their types specified in $format-string. This can be achieved by casting them. See the GVariant varargs documentation.

This function might be used as follows:

method add ( Str $format-string, … )

• $format-string; a Gnome::Glib::N-Variant varargs format string.

• …; …. Note that each argument must be specified as a type followed by its value!

#-------------------------------------------------------------------------------

add-parsed This function is not yet available

Adds to a Gnome::Glib::N-VariantBuilder.

This call is a convenience wrapper that is exactly equivalent to calling g_variant_new_parsed() followed by .add-value().

Note that the arguments must be of the correct width for their types specified in $format-string. This can be achieved by casting them. See the GVariant varargs documentation.

This function might be used as follows:

method add-parsed ( Str $format, … )

• $format; a text format Gnome::Glib::N-Variant.

• …; …. Note that each argument must be specified as a type followed by its value!

#-------------------------------------------------------------------------------

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

method add-value ( N-Object $value )

• $value; a Gnome::Glib::N-Variant

#-------------------------------------------------------------------------------

clear

Releases all memory associated with a Gnome::Glib::N-VariantBuilder without freeing the Gnome::Glib::N-VariantBuilder structure itself.

It typically only makes sense to do this on a stack-allocated Gnome::Glib::N-VariantBuilder if you want to abort building the value part-way through. This function need not be called if you call .end() and it also doesn't need to be called on builders allocated with .new-variantbuilder() (see .unref() for that).

This function leaves the Gnome::Glib::N-VariantBuilder structure set to all-zeros. It is valid to call this function on either an initialised Gnome::Glib::N-VariantBuilder or one that is set to all-zeros but it is not valid to call this function on uninitialised memory.

method clear ( )

#-------------------------------------------------------------------------------

close

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

method close ( )

#-------------------------------------------------------------------------------

end

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

method end (--> N-Object )

Return value; a new, floating, Gnome::Glib::N-Variant.

#-------------------------------------------------------------------------------

init

Initialises a Gnome::Glib::N-VariantBuilder structure. $type must be non-undefined. It specifies the type of container to construct. It can be an indefinite type such as G_VARIANT_TYPE_ARRAY or a definite type such as "as" or "(ii)". Maybe, array, tuple, dictionary entry and variant-typed values may be constructed.

After the builder is initialised, values are added using .add-value() or .add().

After all the child values are added, .end() frees the memory associated with the builder and returns the Gnome::Glib::N-Variant that was created.

This function completely ignores the previous contents of $builder. On one hand this means that it is valid to pass in completely uninitialised memory. On the other hand, this means that if you are initialising over top of an existing Gnome::Glib::N-VariantBuilder you need to first call .clear() in order to avoid leaking memory.

You must not call .ref() or .unref() on a Gnome::Glib::N-VariantBuilder that was initialised with this function. If you ever pass a reference to a Gnome::Glib::N-VariantBuilder outside of the control of your own code then you should assume that the person receiving that reference may try to use reference counting; you should use .new-variantbuilder() instead of this function.

method init ( N-Object $type )

• $type; a container type

#-------------------------------------------------------------------------------

open

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

method open ( N-Object $type )

• $type; the Gnome::Glib::N-VariantType of the container

#-------------------------------------------------------------------------------

ref

Increases the reference count on $builder.

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

method ref (--> N-Object )

Return value; a new reference to $builder.

#-------------------------------------------------------------------------------

unref

Decreases the reference count on $builder.

In the event that there are no more references, releases all memory associated with the Gnome::Glib::N-VariantBuilder.

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

method unref ( )