Varargs Value Collection

## Varargs Value Collection Varargs Value Collection — Converting varargs to generic values |

## Synopsis

    #include <glib-object.h>
    #include <gobject/gvaluecollector.h>

    union               GTypeCValue;
    #define             G_VALUE_COLLECT_INIT                (value,
                                                             _value_type,
                                                             var_args,
                                                             flags,
                                                             __error)
    #define             G_VALUE_COLLECT                     (value,
                                                             var_args,
                                                             flags,
                                                             __error)
    #define             G_VALUE_COLLECT_SKIP                (_value_type,
                                                             var_args)
    #define             G_VALUE_LCOPY                       (value,
                                                             var_args,
                                                             flags,
                                                             __error)
    #define             G_VALUE_COLLECT_FORMAT_MAX_LENGTH

## Description

The macros in this section provide the varargs parsing support needed in variadic GObject functions such as `g_object_new()` or `g_object_set()`. They currently support the collection of integral types, floating point types and pointers.

## Details

### union GTypeCValue

    union _GTypeCValue
    {
      gint     v_int;
      glong    v_long;
      gint64   v_int64;
      gdouble  v_double;
      gpointer v_pointer;
    };

A union holding one collected value.

gint `v_int`; | the field for holding integer values
glong `v_long`; | the field for holding long integer values
gint64 `v_int64`; | the field for holding 64 bit integer values
gdouble `v_double`; | the field for holding floating point values
gpointer `v_pointer`; | the field for holding pointers

### G_VALUE_COLLECT_INIT()

    #define             G_VALUE_COLLECT_INIT(value, _value_type, var_args, flags, __error)

Collects a variable argument value from a va_list. We have to implement the varargs collection as a macro, because on some systems va_list variables cannot be passed by reference.

`value` : | a GValue return location. `value` must contain only 0 bytes.
`_value_type` : | the GType to use for `value`.
`var_args` : | the va_list variable; it may be evaluated multiple times
`flags` : | flags which are passed on to the `collect_value()` function of the GTypeValueTable of `value`.
`__error` : | a gchar** variable that will be modified to hold a `g_new()` allocated error messages if something fails

Since 2.24

### G_VALUE_COLLECT()

    #define             G_VALUE_COLLECT(value, var_args, flags, __error)

Collects a variable argument value from a va_list. We have to implement the varargs collection as a macro, because on some systems va_list variables cannot be passed by reference.

Note: If you are creating the `value` argument just before calling this macro, you should use the G_VALUE_COLLECT_INIT variant and pass the unitialized GValue. That variant is faster than G_VALUE_COLLECT.

`value` : | a GValue return location. `value` is supposed to be initialized according to the value type to be collected
`var_args` : | the va_list variable; it may be evaluated multiple times
`flags` : | flags which are passed on to the `collect_value()` function of the GTypeValueTable of `value`.
`__error` : | a gchar** variable that will be modified to hold a `g_new()` allocated error messages if something fails

### G_VALUE_COLLECT_SKIP()

    #define             G_VALUE_COLLECT_SKIP(_value_type, var_args)

### G_VALUE_LCOPY()

    #define             G_VALUE_LCOPY(value, var_args, flags, __error)

Collects a value's variable argument locations from a va_list. Usage is analogous to `G_VALUE_COLLECT()`.

`value` : | a GValue return location. `value` is supposed to be initialized according to the value type to be collected
`var_args` : | the va_list variable; it may be evaluated multiple times
`flags` : | flags which are passed on to the `lcopy_value()` function of the GTypeValueTable of `value`.
`__error` : | a gchar** variable that will be modified to hold a `g_new()` allocated error messages if something fails

### G_VALUE_COLLECT_FORMAT_MAX_LENGTH

    #define G_VALUE_COLLECT_FORMAT_MAX_LENGTH (8)

The maximal number of GTypeCValues which can be collected for a single GValue.