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

Gnome::Glib::N-VariantDict

Description

Gnome::Glib::N-VariantDict is a mutable interface to Gnome::Glib::N-Variant dictionaries.

It can be used for doing a sequence of dictionary lookups in an efficient way on an existing Gnome::Glib::N-Variant 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::N-VariantDict can only be used with G_VARIANT_TYPE_VARDICT dictionaries.

It is possible to use Gnome::Glib::N-VariantDict allocated on the stack or on the heap. When using a stack-allocated Gnome::Glib::N-VariantDict, you begin with a call to .init() and free the resources with a call to .clear().

Heap-allocated Gnome::Glib::N-VariantDict follows normal refcounting rules: you allocate it with .new-variantdict() and use .ref() and .unref().

.end() is used to convert the Gnome::Glib::N-VariantDict back into a dictionary-type Gnome::Glib::N-Variant. When used with stack-allocated instances, this also implicitly frees all associated memory, but for heap-allocated instances, you must still call .unref() afterwards.

You will typically want to use a heap-allocated Gnome::Glib::N-VariantDict 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 Gnome::Glib::N-Variant.

Using a stack-allocated GVariantDict

Using heap-allocated GVariantDict

#------------------------------------------------------------------------------- #--[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-variantdict

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

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 some cases it may be easier to place a Gnome::Glib::N-VariantDict directly on the stack of the calling function and initialise it with .init(). This is particularly useful when you are using Gnome::Glib::N-VariantDict to construct a Gnome::Glib::N-Variant.

method new-variantdict ( N-Object $from-asv --> Gnome::Glib::VariantDict \)

• $from-asv; the Gnome::Glib::N-Variant with which to initialise the dictionary

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

Methods

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

clear

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

It typically only makes sense to do this on a stack-allocated Gnome::Glib::N-VariantDict 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 dicts allocated with g_variant_dict_new (see .unref() for that).

It is valid to call this function on either an initialised Gnome::Glib::N-VariantDict or one that was previously cleared by an earlier call to .clear() but it is not valid to call this function on uninitialised memory.

method clear ( )

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

contains

Checks if $key exists in $dict.

method contains ( Str $key --> Bool )

• $key; the key to look up in the dictionary.

Return value; True if $key is in $dict.

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

end

Returns the current value of $dict as a Gnome::Glib::N-Variant 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 reference counting operations (in the case of a heap-allocated Gnome::Glib::N-VariantDict) or by reinitialising it with .init() (in the case of stack-allocated).

method end (--> N-Object )

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

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

init

Initialises a Gnome::Glib::N-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::N-VariantDict you need to first call .clear() in order to avoid leaking memory.

You must not call .ref() or .unref() on a Gnome::Glib::N-VariantDict that was initialised with this function. If you ever pass a reference to a Gnome::Glib::N-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 .new-variantdict() instead of this function.

method init ( N-Object $from-asv )

• $from-asv; the initial value for $dict

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

insert This function is not yet available

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

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

method insert ( Str $key, Str $format-string, … )

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

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

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

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

insert-value

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

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

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

• $value; the value to insert

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

lookup This function is not yet available

Looks up a value in a Gnome::Glib::N-VariantDict.

This function is a wrapper around .lookup-value() and g_variant_get(). In the case that undefined would have been returned, this function returns False. Otherwise, it unpacks the returned value and returns True. $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.

method lookup ( Str $key, Str $format-string, … --> Bool )

• $key; the key to look up in the dictionary.

• $format-string; a GVariant format string.

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

Return value; True if a value was unpacked.

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

lookup-value

Looks up a value in a Gnome::Glib::N-VariantDict.

If $key is not found in $dictionary, undefined is returned.

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

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

method lookup-value ( Str $key, N-Object $expected-type --> N-Object )

• $key; the key to look up in the dictionary.

• $expected-type; a Gnome::Glib::N-VariantType, or undefined

Return value; the value of the dictionary key, or undefined.

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

ref

Increases the reference count on $dict.

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

method ref (--> N-Object )

Return value; a new reference to $dict.

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

remove

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

method remove ( Str $key --> Bool )

• $key; the key to remove.

Return value; True if the key was found and removed.

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

unref

Decreases the reference count on $dict.

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

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

method unref ( )