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

See Also

GValueTable