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

Gnome::Glib::N-VariantIter

Description

Gnome::Glib::N-VariantIter is an opaque data structure and can only be accessed using the following functions.

#------------------------------------------------------------------------------- #--[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! )

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

Methods

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

copy

Creates a new heap-allocated Gnome::Glib::N-VariantIter to iterate over the container that was being iterated over by $iter. Iteration begins on the new iterator from the current position of the old iterator but the two copies are independent past that point.

Use .free() to free the return value when you no longer need it.

A reference is taken to the container that $iter is iterating over and will be related only when .free() is called.

method copy (--> N-Object )

Return value; a new heap-allocated Gnome::Glib::N-VariantIter.

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

free

Frees a heap-allocated Gnome::Glib::N-VariantIter. Only call this function on iterators that were returned by .new-variantiter() or .copy().

method free ( )

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

init

Initialises (without allocating) a Gnome::Glib::N-VariantIter. $iter may be completely uninitialised prior to this call; its old value is ignored.

The iterator remains valid for as long as $value exists, and need not be freed in any way.

method init ( N-Object $value --> Int )

• $value; a container Gnome::Glib::N-Variant

Return value; the number of items in $value.

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

loop This function is not yet available

Gets the next item in the container and unpacks it into the variable argument list according to $format-string, returning True.

If no more items remain then False is returned.

On the first call to this function, the pointers appearing on the variable argument list are assumed to point at uninitialised memory. On the second and later calls, it is assumed that the same pointers will be given and that they will point to the memory as set by the previous call to this function. This allows the previous values to be freed, as appropriate.

This function is intended to be used with a while loop as demonstrated in the following example. This function can only be used when iterating over an array. It is only valid to call this function with a string constant for the format string and the same string constant must be used each time. Mixing calls to this function and .next() or .next-value() on the same iterator causes undefined behavior.

If you break out of a such a while loop using .loop() then you must free or unreference all the unpacked values as you would with g_variant_get(). Failure to do so will cause a memory leak.

Here is an example for memory management with .loop():

For most cases you should use .next().

This function is really only useful when unpacking into Gnome::Glib::N-Variant or Gnome::Glib::N-VariantIter in order to allow you to skip the call to g_variant_unref() or .free().

For example, if you are only looping over simple integer and string types, .next() is definitely preferred. For string types, use the '&' prefix to avoid allocating any memory at all (and thereby avoiding the need to free anything as well). $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 loop ( Str $format-string, … --> Bool )

• $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, or False if there was no value.

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

n-children

Queries the number of child items in the container that we are iterating over. This is the total number of items -- not the number of items remaining.

This function might be useful for preallocation of arrays.

method n-children (--> Int )

Return value; the number of children in the container.

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

next This function is not yet available

Gets the next item in the container and unpacks it into the variable argument list according to $format-string, returning True.

If no more items remain then False is returned.

All of the pointers given on the variable arguments list of this function are assumed to point at uninitialised memory. It is the responsibility of the caller to free all of the values returned by the unpacking process.

Here is an example for memory management with .next():

For a solution that is likely to be more convenient to C programmers when dealing with loops, see .loop(). $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 next ( Str $format-string, … --> Bool )

• $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, or False if there as no value.

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

next-value

Gets the next item in the container. If no more items remain then undefined is returned.

Use g_variant_unref() to drop your reference on the return value when you no longer need it.

Here is an example for iterating with .next-value():

method next-value (--> N-Object )

Return value; a Gnome::Glib::N-Variant, or undefined.