Package org.gnome.glib

Class VariantBuilder

java.lang.Object

org.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 builder.
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 @Nullable Type	getType()	Get the GType of the VariantBuilder class
void	init(VariantType type)	Initialises a GVariantBuilder structure.
void	initStatic(VariantType type)	Initialises a GVariantBuilder structure.
void	open(VariantType type)	Opens a subcontainer inside the given builder. When done adding items to the subcontainer, g_variant_builder_close() must be called.
@org.jspecify.annotations.Nullable long @Nullable []	readX()	Read the value of the field x.
VariantBuilder	ref()	Increases the reference count on builder.
void	unref()	Decreases the reference count on builder.
void	writeX(@org.jspecify.annotations.Nullable long @Nullable [] x, Arena _arena)	Write a value in the field x.

Methods inherited from class org.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_static().

Parameters:

type - a container type

Since:

2.24

Method Details

getType

public static @Nullable 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 @org.jspecify.annotations.Nullable long @Nullable [] readX()

Read the value of the field x.

Returns:

The value of the field x

writeX

public void writeX(@org.jspecify.annotations.Nullable long @Nullable [] x,
 Arena _arena)

Write a value in the field x.

Parameters:

x - The new value for the field x

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_static (&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

Since:

2.24

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_static (&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

Since:

2.26

addValue

public void addValue(Variant 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 this VariantBuilder instance takes ownership of value.

Parameters:

value - a GVariant

Since:

2.24

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.

Since:

2.24

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

Since:

2.24

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

Since:

2.24

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.

If using a static type such as one of the G_VARIANT_TYPE_* constants or a G_VARIANT_TYPE ("(ii)") macro, it is more performant to use g_variant_builder_init_static() rather than g_variant_builder_init().

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

Since:

2.24

initStatic

public void initStatic(VariantType type)

Initialises a GVariantBuilder structure.

This function works exactly like g_variant_builder_init() but does not make a copy of type. Therefore, type must remain valid for the lifetime of builder. This is always true of type constants like G_VARIANT_TYPE_* or G_VARIANT_TYPE ("(ii)").

Parameters:

type - a container type

Since:

2.84

open

public void open(VariantType 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);
 

Parameters:

type - the GVariantType of the container

Since:

2.24

ref

public VariantBuilder ref()

Increases the reference count on builder.

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

Returns:

a new reference to this VariantBuilder

Since:

2.24

unref

public void unref()

Decreases the reference count on builder.

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.

Since:

2.24