Gnome::Glib — N-VariantDict
#------------------------------------------------------------------------------- #--[Class Description]---------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
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
=end rakudoc
#------------------------------------------------------------------------------- #--[Class Initialization]------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
Class initialization
new
:native-object
Create an object using a native object from an object of the same type found elsewhere. See also Gnome::N::TopLevelSupportClass.
multi method new ( N-Object() :$native-object! )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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
=end rakudoc
#------------------------------------------------------------------------------- #--[Methods]-------------------------------------------------------------------- #-------------------------------------------------------------------------------
=begin rakudoc
Methods =end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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 ( )
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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 rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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!
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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.
=end rakudoc
#------------------------------------------------------------------------------- =begin rakudoc
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 ( )
=end rakudoc