Class VariantDict

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.glib.VariantDict

All Implemented Interfaces:

Proxy

@Generated("org.javagi.JavaGI")
public class VariantDict
extends ProxyInstance

GVariantDict is a mutable interface to GVariant dictionaries.

It can be used for doing a sequence of dictionary lookups in an efficient way on an existing GVariant dictionary or it can be used to construct new dictionaries with a hashtable-like interface. It can also be used for taking existing dictionaries and modifying them in order to create new ones.

GVariantDict can only be used with G_VARIANT_TYPE_VARDICT dictionaries.

It is possible to use GVariantDict allocated on the stack or on the heap. When using a stack-allocated GVariantDict, you begin with a call to g_variant_dict_init() and free the resources with a call to g_variant_dict_clear().

Heap-allocated GVariantDict follows normal refcounting rules: you allocate it with g_variant_dict_new() and use g_variant_dict_ref() and g_variant_dict_unref().

g_variant_dict_end() is used to convert the GVariantDict back into a dictionary-type GVariant. When used with stack-allocated instances, this also implicitly frees all associated memory, but for heap-allocated instances, you must still call g_variant_dict_unref() afterwards.

You will typically want to use a heap-allocated GVariantDict when you expose it as part of an API. For most other uses, the stack-allocated form will be more convenient.

Consider the following two examples that do the same thing in each style: take an existing dictionary and look up the "count" uint32 key, adding 1 to it if it is found, or returning an error if the key is not found. Each returns the new dictionary as a floating GVariant.

Using a stack-allocated GVariantDict

  GVariant *
  add_to_count (GVariant  *orig,
                GError   **error)
  {
    GVariantDict dict;
    guint32 count;

    g_variant_dict_init (&dict, orig);
    if (!g_variant_dict_lookup (&dict, "count", "u", &count))
      {
        g_set_error (...);
        g_variant_dict_clear (&dict);
        return NULL;
      }

    g_variant_dict_insert (&dict, "count", "u", count + 1);

    return g_variant_dict_end (&dict);
  }

Using heap-allocated GVariantDict

  GVariant *
  add_to_count (GVariant  *orig,
                GError   **error)
  {
    GVariantDict *dict;
    GVariant *result;
    guint32 count;

    dict = g_variant_dict_new (orig);

    if (g_variant_dict_lookup (dict, "count", "u", &count))
      {
        g_variant_dict_insert (dict, "count", "u", count + 1);
        result = g_variant_dict_end (dict);
      }
    else
      {
        g_set_error (...);
        result = NULL;
      }

    g_variant_dict_unref (dict);

    return result;
  }

Since:

2.40

Constructor Summary

Constructors

Constructor	Description
VariantDict(MemorySegment address)	Create a VariantDict proxy instance for the provided memory address.
VariantDict(@Nullable Variant fromAsv)	Allocates and initialises a new GVariantDict.

Method Summary

Modifier and Type	Method	Description
void	clear()	Releases all memory associated with a GVariantDict without freeing the GVariantDict structure itself.
boolean	contains(String key)	Checks if key exists in dict.
Variant	end()	Returns the current value of this VariantDict as a GVariant of type G_VARIANT_TYPE_VARDICT, clearing it in the process.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static @Nullable Type	getType()	Get the GType of the VariantDict class.
void	init(@Nullable Variant fromAsv)	Initialises a GVariantDict structure.
void	insert(String key, String formatString, Object... varargs)	Inserts a value into a GVariantDict.
void	insertValue(String key, Variant value)	Inserts (or replaces) a key in a GVariantDict.
boolean	lookup(String key, String formatString, Object... varargs)	Looks up a value in a GVariantDict.
@Nullable Variant	lookupValue(String key, @Nullable VariantType expectedType)	Looks up a value in a GVariantDict.
@Nullable long @Nullable []	readX()	Read the value of the field x.
VariantDict	ref()	Increases the reference count on dict.
boolean	remove(String key)	Removes a key and its associated value from a GVariantDict.
void	unref()	Decreases the reference count on dict.
void	writeX(@Nullable long @Nullable [] x, Arena _arena)	Write a value in the field x.

Methods inherited from class ProxyInstance

equals, handle, hashCode

Methods inherited from class Object

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

Constructor Details

VariantDict

public VariantDict(MemorySegment address)

Create a VariantDict proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

VariantDict

public VariantDict(@Nullable Variant fromAsv)

Allocates and initialises a new GVariantDict.

You should call g_variant_dict_unref() on the return value when it is no longer needed. The memory will not be automatically freed by any other call.

In some cases it may be easier to place a GVariantDict directly on the stack of the calling function and initialise it with g_variant_dict_init(). This is particularly useful when you are using GVariantDict to construct a GVariant.

Parameters:

fromAsv - the GVariant with which to initialise the dictionary

Since:

2.40

Method Details

getType

public static @Nullable Type getType()

Get the GType of the VariantDict class.

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readX

public @Nullable long @Nullable [] readX()

Read the value of the field x.

Returns:

The value of the field x

writeX

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

Write a value in the field x.

Parameters:

x - The new value for the field x

clear

public void clear()

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

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

It is valid to call this function on either an initialised GVariantDict or one that was previously cleared by an earlier call to g_variant_dict_clear() but it is not valid to call this function on uninitialised memory.

Since:

2.40

contains

public boolean contains(String key)

Checks if key exists in dict.

Parameters:

key - the key to look up in the dictionary

Returns:

true if key is in this VariantDict

Since:

2.40

end

public Variant end()

Returns the current value of this VariantDict as a GVariant of type G_VARIANT_TYPE_VARDICT, clearing it in the process.

It is not permissible to use this VariantDict in any way after this call except for reference counting operations (in the case of a heap-allocated GVariantDict) or by reinitialising it with g_variant_dict_init() (in the case of stack-allocated).

Returns:

a new, floating, GVariant

Since:

2.40

init

public void init(@Nullable Variant fromAsv)

Initialises a GVariantDict structure.

If fromAsv is given, it is used to initialise the dictionary.

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

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

Parameters:

fromAsv - the initial value for this VariantDict

Since:

2.40

insert

public void insert(String key,
 String formatString,
 Object... varargs)

Inserts a value into a GVariantDict.

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

Parameters:

key - the key to insert a value for

formatString - a GVariant varargs format string

varargs - arguments, as per formatString

Since:

2.40

insertValue

public void insertValue(String key,
 Variant value)

Inserts (or replaces) a key in a GVariantDict.

value is consumed if it is floating.

Parameters:

key - the key to insert a value for

value - the value to insert

Since:

2.40

lookup

public boolean lookup(String key,
 String formatString,
 Object... varargs)

Looks up a value in a GVariantDict.

This function is a wrapper around g_variant_dict_lookup_value() and g_variant_get(). In the case that null would have been returned, this function returns false and does not modify the values of the arguments passed in to .... Otherwise, it unpacks the returned value and returns true.

formatString determines the C types that are used for unpacking the values and also determines if the values are copied or borrowed, see the section on GVariant format strings.

Parameters:

key - the key to look up in the dictionary

formatString - a GVariant format string

varargs - the arguments to unpack the value into

Returns:

true if a value was unpacked

Since:

2.40

lookupValue

public @Nullable Variant lookupValue(String key,
 @Nullable VariantType expectedType)

Looks up a value in a GVariantDict.

If key is not found in dictionary, null is returned.

The expectedType string specifies what type of value is expected. If the value associated with key has a different type then null is returned.

If the key is found and the value has the correct type, it is returned. If expectedType was specified then any non-null return value will have this type.

Parameters:

key - the key to look up in the dictionary

expectedType - a GVariantType, or null

Returns:

the value of the dictionary key, or null

Since:

2.40

ref

public VariantDict ref()

Increases the reference count on dict.

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

Returns:

a new reference to this VariantDict

Since:

2.40

remove

public boolean remove(String key)

Removes a key and its associated value from a GVariantDict.

Parameters:

key - the key to remove

Returns:

true if the key was found and removed

Since:

2.40

unref

public void unref()

Decreases the reference count on dict.

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

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

Since:

2.40