Class VariantIter

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.glib.VariantIter
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class VariantIter extends ProxyInstance
GVariantIter is an opaque data structure and can only be accessed using the following functions.

  • Constructor Summary

    Constructors
    Constructor
    Description
    VariantIter()
    Allocate a new VariantIter.
    VariantIter(long[] x)
    Allocate a new VariantIter with the fields set to the provided values.
    VariantIter(long[] x, Arena arena)
    Allocate a new VariantIter with the fields set to the provided values.
    VariantIter(Arena arena)
    Allocate a new VariantIter.
    VariantIter(MemorySegment address)
    Create a VariantIter proxy instance for the provided memory address.

  • Method Summary

    Modifier and Type
    Method
    Description
    VariantIter
    copy()
    Creates a new heap-allocated GVariantIter 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.
    void
    free()
    Frees a heap-allocated GVariantIter.
    static MemoryLayout
    getMemoryLayout()
    The memory layout of the native struct.
    long
    init(Variant value)
    Initialises (without allocating) a GVariantIter.
    boolean
    loop(String formatString, Object... varargs)
    Gets the next item in the container and unpacks it into the variable argument list according to formatString, returning true.
    long
    nChildren()
    Queries the number of child items in the container that we are iterating over.
    boolean
    next(String formatString, Object... varargs)
    Gets the next item in the container and unpacks it into the variable argument list according to formatString, returning true.
    @Nullable Variant
    nextValue()
    Gets the next item in the container.
    @Nullable long @Nullable []
    readX()
    Read the value of the field x.
    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

    • VariantIter

      public VariantIter(MemorySegment address)
      Create a VariantIter proxy instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • VariantIter

      public VariantIter(Arena arena)
      Allocate a new VariantIter.
      Parameters:
      arena - to control the memory allocation scope

    • VariantIter

      public VariantIter()
      Allocate a new VariantIter. The memory is allocated with Arena.ofAuto().

    • VariantIter

      public VariantIter(long[] x, Arena arena)
      Allocate a new VariantIter with the fields set to the provided values.
      Parameters:
      x - value for the field x
      arena - to control the memory allocation scope

    • VariantIter

      public VariantIter(long[] x)
      Allocate a new VariantIter with the fields set to the provided values. The memory is allocated with Arena.ofAuto().
      Parameters:
      x - value for the field x

  • Method Details

    • 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

    • copy

      public VariantIter copy()

      Creates a new heap-allocated GVariantIter 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 g_variant_iter_free() to free the return value when you no longer need it.

      A reference is taken to the container that this VariantIter is iterating over and will be related only when g_variant_iter_free() is called.

      Returns:
      a new heap-allocated GVariantIter
      Since:
      2.24

    • free

      public void free()
      Frees a heap-allocated GVariantIter. Only call this function on iterators that were returned by g_variant_iter_new() or g_variant_iter_copy().
      Since:
      2.24

    • init

      public long init(Variant value)

      Initialises (without allocating) a GVariantIter. this VariantIter 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.

      Parameters:
      value - a container GVariant
      Returns:
      the number of items in value
      Since:
      2.24

    • loop

      public boolean loop(String formatString, Object... varargs)

      Gets the next item in the container and unpacks it into the variable argument list according to formatString, 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 g_variant_iter_next() or g_variant_iter_next_value() on the same iterator causes undefined behavior.

      If you break out of a such a while loop using g_variant_iter_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 g_variant_iter_loop():

        // Iterates a dictionary of type 'a{sv}'
  void
  iterate_dictionary (GVariant *dictionary)
  {
    GVariantIter iter;
    GVariant *value;
    gchar *key;

    g_variant_iter_init (&iter, dictionary);
    while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
      {
        g_print ("Item '%s' has type '%s'\\n", key,
                 g_variant_get_type_string (value));

        // no need to free 'key' and 'value' here
        // unless breaking out of this loop
      }
  }

      For most cases you should use g_variant_iter_next().

      This function is really only useful when unpacking into GVariant or GVariantIter in order to allow you to skip the call to g_variant_unref() or g_variant_iter_free().

      For example, if you are only looping over simple integer and string types, g_variant_iter_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).

      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:
      formatString - a GVariant format string
      varargs - the arguments to unpack the value into
      Returns:
      true if a value was unpacked, or false if there was no value
      Since:
      2.24

    • nChildren

      public long nChildren()

      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.

      Returns:
      the number of children in the container
      Since:
      2.24

    • next

      public boolean next(String formatString, Object... varargs)

      Gets the next item in the container and unpacks it into the variable argument list according to formatString, 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 g_variant_iter_next():

        // Iterates a dictionary of type 'a{sv}'
  void
  iterate_dictionary (GVariant *dictionary)
  {
    GVariantIter iter;
    GVariant *value;
    gchar *key;

    g_variant_iter_init (&iter, dictionary);
    while (g_variant_iter_next (&iter, "{sv}", &key, &value))
      {
        g_print ("Item '%s' has type '%s'\\n", key,
                 g_variant_get_type_string (value));

        // must free data for ourselves
        g_variant_unref (value);
        g_free (key);
      }
  }

      For a solution that is likely to be more convenient to C programmers when dealing with loops, see g_variant_iter_loop().

      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:
      formatString - a GVariant format string
      varargs - the arguments to unpack the value into
      Returns:
      true if a value was unpacked, or false if there as no value
      Since:
      2.24

    • nextValue

      public @Nullable Variant nextValue()

      Gets the next item in the container. If no more items remain then null 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 g_variant_iter_next_value():

        // recursively iterate a container
  void
  iterate_container_recursive (GVariant *container)
  {
    GVariantIter iter;
    GVariant *child;

    g_variant_iter_init (&iter, container);
    while ((child = g_variant_iter_next_value (&iter)))
      {
        g_print ("type '%s'\\n", g_variant_get_type_string (child));

        if (g_variant_is_container (child))
          iterate_container_recursive (child);

        g_variant_unref (child);
      }
  }
      Returns:
      a GVariant, or null
      Since:
      2.24