Description

Gnome::Glib::VariantDict 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.

Gnome::Glib::VariantDict can only be used with G_VARIANT_TYPE_VARDICT dictionaries.

end() is used to convert the Gnome::Glib::VariantDict back into a dictionary-type Gnome::Glib::Variant. You must call clear-object() afterwards.

Example

my Gnome::Glib::VariantDict $vd .= new(
  :variant(
    Gnome::Glib::Variant.new(:parse(Q:q/{ 'width': <350>, 'height': <200>}/))
  )
);

$vd.insert-value( 'depth', Gnome::Glib::Variant.new(:parse('-40')));
say $vd.lookup-value( 'width', 'i').get-int32;  # 350
$vd.remove('width');

my Gnome::Glib::Variant $v .= new(:native-object($vd.end));
$vd.clear-object;
say 'dict: ' ~ $v.print(False); # dict: {'height': <200>, 'vd01': <-40>}

See Also

• Variants

• Variant types

• Gnome::Glib::VariantType

• Variant format strings

• Variant text format

Synopsis

Declaration

unit class Gnome::Glib::VariantDict;
also is Gnome::N::TopLevelClassSupport;

Methods

new

default no options

:variant

clear

Releases all memory associated with a Gnome::Glib::VariantDict without freeing the Gnome::Glib::VariantDict structure itself. It typically only makes sense to do this on a stack-allocated Gnome::Glib::VariantDict 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 clear-object() for that). It is valid to call this function on either an initialised Gnome::Glib::VariantDict 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.

method clear ( )

contains

Checks if $key exists in dict.

Returns: True if $key is in dict

method contains ( Str $key --> Bool )

• Str $key; the key to lookup in the dictionary

end

Returns the current value of dict as a Gnome::Glib::VariantDict of type G_VARIANT_TYPE_VARDICT, clearing it in the process. It is not permissible to use dict in any way after this call except for clear-object(), clear()

Returns: a new Gnome::Glib::Variant of type G_VARIANT_TYPE_VARDICT.

method end ( --> N-GObject )

init

Initialises a Gnome::Glib::VariantDict structure. If from_asv 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 Gnome::Glib::VariantDict 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 Gnome::Glib::VariantDict that was initialised with this function. If you ever pass a reference to a Gnome::Glib::VariantDict 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.

method init ( N-GObject $from_asv )

• N-GObject $from_asv; (nullable): the initial value for dict

insert

Inserts a value into a Gnome::Glib::VariantDict.

method insert ( Str $key, Str $string )

• Str $key; the key to insert a value for

• Str $string; a Gnome::Glib::VariantDict varargs string

insert-value

Inserts (or replaces) a key in a Gnome::Glib::VariantDict. value is consumed if it is floating.

method insert-value ( Str $key, N-GObject $value )

• Str $key; the key to insert a value for

• N-GObject $value; the value to insert

lookup

Looks up a value in a Gnome::Glib::VariantDict. This function is a wrapper around g_variant_dict_lookup_value() and g_variant_get(). In the case that Any would have been returned, this function returns 0. Otherwise, it unpacks the returned value and returns 1. format_string 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][gvariant-format-strings-pointers].

Returns: True if a value was unpacked

method lookup ( Str $key, Str $format_string --> Bool )

• Str $key; the key to lookup in the dictionary

• Str $string; a GVariant string @...: the arguments to unpack the value into

lookup-value

Looks up a value in a Gnome::Glib::VariantDict. If $key is not found in dictionary, an invalid Gnome::Glib::Variant is returned. The $expected_type string specifies what type of value is expected. If the value associated with $key has a different type then an invalid Gnome::Glib::Variant is returned. If the key is found and the value has the correct type, it is returned. If $expected_type was specified then any valid return value will have this type.

Returns: the value of the dictionary key, or undefined

method lookup-value (
  Str $key, N-GObject $expected_type --> Gnome::Glib::Variant
)

• Str $key; the key to lookup in the dictionary

• N-GObject $expected_type; a GVariantType, or undefined

remove

Removes a key and its associated value from a Gnome::Glib::VariantDict.

Returns: True if the key was found and removed

method remove ( Str $key --> Bool )

• Str $key; the key to remove

ref

Increases the reference count. Don't call this on stack-allocated Gnome::Glib::VariantDict instances or bad things will happen.

Returns: a new reference

method ref ( --> N-GObject )

unref

Decreases the reference count. In the event that there are no more references, releases all memory associated with the Gnome::Glib::VariantDict. Don't call this on stack-allocated Gnome::Glib::VariantDict instances or bad things will happen.

method unref ( )

new

Allocates and initialises a new Gnome::Glib::VariantDict. You should call clear-object() 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 Gnome::Glib::VariantDict directly on the stack of the calling function and initialise it with g_variant_dict_init(). This is particularly useful when you are using Gnome::Glib::VariantDict to construct a Gnome::Glib::VariantDict.

Returns: a Gnome::Glib::VariantDict

method new ( N-GObject $from_asv --> N-GObject )

• N-GObject from_asv; the GVariant with which to initialise the dictionary.