Package org.gnome.glib

Class VariantBuilder

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.glib.VariantBuilder

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class VariantBuilder
extends ProxyInstance

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.

Constructor Summary

Constructors

Constructor	Description
VariantBuilder(MemorySegment address)	Create a VariantBuilder proxy instance for the provided memory address.
VariantBuilder(VariantType type)	Allocates and initialises a new GVariantBuilder.

Method Summary

Modifier and Type	Method	Description
void	add(String formatString, Object... varargs)	Adds to a GVariantBuilder.
void	addParsed(String format, Object... varargs)	Adds to a GVariantBuilder.
void	addValue(Variant value)	Adds value to this VariantBuilder.
void	clear()	Releases all memory associated with a GVariantBuilder without freeing the GVariantBuilder structure itself.
void	close()	Closes the subcontainer inside the given this VariantBuilder that was opened by the most recent call to g_variant_builder_open().
Variant	end()	Ends the builder process and returns the constructed value.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static Type	getType()	Get the GType of the VariantBuilder class
void	init(VariantType type)	Initialises a GVariantBuilder structure.
void	open(VariantType type)	Opens a subcontainer inside the given this VariantBuilder.
long[]	readX()	Read the value of the field x.
VariantBuilder	ref()	Increases the reference count on this VariantBuilder.
void	unref()	Decreases the reference count on this VariantBuilder.
void	writeX(long[] x, Arena _arena)	Write a value in the field x.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

VariantBuilder

public VariantBuilder(MemorySegment address)

Create a VariantBuilder proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

VariantBuilder

public VariantBuilder(VariantType type)

Allocates and initialises a new GVariantBuilder.

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

Parameters:

type - a container type

Method Details

getType

public static Type getType()

Get the GType of the VariantBuilder class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readX

public long[] readX()

Read the value of the field x.

Returns:

The value of the field x

writeX

public void writeX(long[] x,
 Arena _arena)

Write a value in the field x.

Parameters:

x - The new value for the field x

_arena - to control the memory allocation scope

add

public void add(String formatString,
 Object... varargs)

Adds to a GVariantBuilder.

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

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

This function might be used as follows:

GVariant *
 make_pointless_dictionary (void)
 {
   GVariantBuilder builder;
   int i;

   g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
   for (i = 0; i < 16; i++)
     {
       gchar buf[3];

       sprintf (buf, "%d", i);
       g_variant_builder_add (&builder, "{is}", i, buf);
     }

   return g_variant_builder_end (&builder);
 }
 

Parameters:

formatString - a GVariant varargs format string

varargs - arguments, as per formatString

addParsed

public void addParsed(String format,
 Object... varargs)

Adds to a GVariantBuilder.

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

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

This function might be used as follows:

GVariant *
 make_pointless_dictionary (void)
 {
   GVariantBuilder builder;
   int i;

   g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
   g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600);
   g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo");
   g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}");
   return g_variant_builder_end (&builder);
 }
 

Parameters:

format - a text format GVariant

varargs - arguments as per format

addValue

public void addValue(Variant value)

Adds value to this VariantBuilder.

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 this VariantBuilder instance takes ownership of value.

Parameters:

value - a GVariant

clear

public void clear()

Releases all memory associated with a GVariantBuilder without freeing the GVariantBuilder structure itself.

It typically only makes sense to do this on a stack-allocated GVariantBuilder if you want to abort building the value part-way through. This function need not be called if you call g_variant_builder_end() and it also doesn't need to be called on builders allocated with g_variant_builder_new() (see g_variant_builder_unref() for that).

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

close

public void close()

Closes the subcontainer inside the given this VariantBuilder 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).

end

public Variant end()

Ends the builder process and returns the constructed value.

It is not permissible to use this VariantBuilder 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.

Returns:

a new, floating, GVariant

init

public void init(VariantType type)

Initialises a GVariantBuilder structure.

type must be non-null. 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 g_variant_builder_add_value() or g_variant_builder_add().

After all the child values are added, g_variant_builder_end() frees the memory associated with the builder and returns the GVariant that was created.

This function completely ignores the previous contents of this VariantBuilder. 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 GVariantBuilder you need to first call g_variant_builder_clear() in order to avoid leaking memory.

You must not call g_variant_builder_ref() or g_variant_builder_unref() on a GVariantBuilder that was initialised with this function. If you ever pass a reference to a GVariantBuilder 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 g_variant_builder_new() instead of this function.

Parameters:

type - a container type

open

public void open(VariantType type)

Opens a subcontainer inside the given this VariantBuilder. 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);
 

Parameters:

type - the GVariantType of the container

ref

public VariantBuilder ref()

Increases the reference count on this VariantBuilder.

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

Returns:

a new reference to this VariantBuilder

unref

public void unref()

Decreases the reference count on this VariantBuilder.

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

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