GLib.VariantIter.loop

### Method

# GLib VariantIterloop

since: 2.24

#### Declaration [src]

    gboolean
    g_variant_iter_loop (
      GVariantIter* iter,
      const gchar* format_string,
      ...
    )

#### Description [src]

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 `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).

`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.

Available since: 2.24

This method is not directly available to language bindings.

#### Parameters

`format_string`

  Type: `const gchar*`

  A GVariant format string.

  The data is owned by the caller of the method.
  The value is a NUL terminated UTF-8 string.

`...`

  Type: ``

  The arguments to unpack the value into.

#### Return value

Type: `gboolean`

`TRUE` if a value was unpacked, or `FALSE` if there was no value.