glib-2.0/gobject/gvaluecollector.h

0001 /* GObject - GLib Type, Object, Parameter and Signal Library
0002  * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2.1 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General
0017  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
0018  *
0019  * gvaluecollector.h: GValue varargs stubs
0020  */
0021
0022 #ifndef __G_VALUE_COLLECTOR_H__
0023 #define __G_VALUE_COLLECTOR_H__
0024
0025 #include <glib-object.h>
0026
0027 G_BEGIN_DECLS
0028
0029 /* we may want to add aggregate types here some day, if requested
0030  * by users. the basic C types are covered already, everything
0031  * smaller than an int is promoted to an integer and floats are
0032  * always promoted to doubles for varargs call constructions.
0033  */
0034 enum    /*< skip >*/
0035 {
0036   G_VALUE_COLLECT_INT       = 'i',
0037   G_VALUE_COLLECT_LONG      = 'l',
0038   G_VALUE_COLLECT_INT64         = 'q',
0039   G_VALUE_COLLECT_DOUBLE    = 'd',
0040   G_VALUE_COLLECT_POINTER   = 'p'
0041 };
0042
0043
0044 /* vararg union holding actual values collected
0045  */
0046 /**
0047  * GTypeCValue:
0048  * @v_int: the field for holding integer values
0049  * @v_long: the field for holding long integer values
0050  * @v_int64: the field for holding 64 bit integer values
0051  * @v_double: the field for holding floating point values
0052  * @v_pointer: the field for holding pointers
0053  *
0054  * A union holding one collected value.
0055  */
0056 union _GTypeCValue
0057 {
0058   gint     v_int;
0059   glong    v_long;
0060   gint64   v_int64;
0061   gdouble  v_double;
0062   gpointer v_pointer;
0063 };
0064
0065 /**
0066  * G_VALUE_COLLECT_INIT:
0067  * @value: a #GValue return location. @value must contain only 0 bytes.
0068  * @_value_type: the #GType to use for @value.
0069  * @var_args: the va_list variable; it may be evaluated multiple times
0070  * @flags: flags which are passed on to the collect_value() function of
0071  *  the #GTypeValueTable of @value.
0072  * @__error: a #gchar** variable that will be modified to hold a g_new()
0073  *  allocated error messages if something fails
0074  *
0075  * Collects a variable argument value from a `va_list`.
0076  *
0077  * We have to implement the varargs collection as a macro, because on some
0078  * systems `va_list` variables cannot be passed by reference.
0079  *
0080  * Since: 2.24
0081  */
0082 #define G_VALUE_COLLECT_INIT(value, _value_type, var_args, flags, __error) \
0083   G_STMT_START { \
0084     GTypeValueTable *g_vci_vtab; \
0085     G_VALUE_COLLECT_INIT2(value, g_vci_vtab, _value_type, var_args, flags, __error); \
0086 } G_STMT_END
0087
0088 /**
0089  * G_VALUE_COLLECT_INIT2:
0090  * @value: a #GValue return location. @value must contain only 0 bytes.
0091  * @g_vci_vtab: a #GTypeValueTable pointer that will be set to the value table
0092  *   for @_value_type
0093  * @_value_type: the #GType to use for @value.
0094  * @var_args: the va_list variable; it may be evaluated multiple times
0095  * @flags: flags which are passed on to the collect_value() function of
0096  *  the #GTypeValueTable of @value.
0097  * @__error: a #gchar** variable that will be modified to hold a g_new()
0098  *  allocated error messages if something fails
0099  *
0100  * A variant of G_VALUE_COLLECT_INIT() that provides the #GTypeValueTable
0101  * to the caller.
0102  *
0103  * Since: 2.74
0104  */
0105 #define G_VALUE_COLLECT_INIT2(value, g_vci_vtab, _value_type, var_args, flags, __error)     \
0106 G_STMT_START {                                      \
0107   GValue *g_vci_val = (value);                              \
0108   guint g_vci_flags = (flags);                              \
0109   const gchar *g_vci_collect_format; \
0110   GTypeCValue g_vci_cvalues[G_VALUE_COLLECT_FORMAT_MAX_LENGTH] = { { 0, }, };       \
0111   guint g_vci_n_values = 0;                                 \
0112   g_vci_vtab = g_type_value_table_peek (_value_type);           \
0113   g_vci_collect_format = g_vci_vtab->collect_format;                    \
0114   g_vci_val->g_type = _value_type;      /* value_meminit() from gvalue.c */     \
0115   while (*g_vci_collect_format)                             \
0116     {                                           \
0117       GTypeCValue *g_vci_cvalue = g_vci_cvalues + g_vci_n_values++;                 \
0118                                                                                         \
0119       switch (*g_vci_collect_format++)                          \
0120     {                                       \
0121     case G_VALUE_COLLECT_INT:                           \
0122       g_vci_cvalue->v_int = va_arg ((var_args), gint);                  \
0123       break;                                    \
0124     case G_VALUE_COLLECT_LONG:                          \
0125       g_vci_cvalue->v_long = va_arg ((var_args), glong);                    \
0126       break;                                    \
0127     case G_VALUE_COLLECT_INT64:                         \
0128       g_vci_cvalue->v_int64 = va_arg ((var_args), gint64);              \
0129       break;                                    \
0130     case G_VALUE_COLLECT_DOUBLE:                            \
0131       g_vci_cvalue->v_double = va_arg ((var_args), gdouble);                \
0132       break;                                    \
0133     case G_VALUE_COLLECT_POINTER:                           \
0134       g_vci_cvalue->v_pointer = va_arg ((var_args), gpointer);              \
0135       break;                                    \
0136     default:                                    \
0137       g_assert_not_reached ();                          \
0138     }                                       \
0139     }                                           \
0140   *(__error) = g_vci_vtab->collect_value (g_vci_val,                        \
0141                        g_vci_n_values,                  \
0142                        g_vci_cvalues,                   \
0143                        g_vci_flags);                        \
0144 } G_STMT_END
0145
0146 /**
0147  * G_VALUE_COLLECT:
0148  * @value: a #GValue return location. @value is supposed to be initialized
0149  *  according to the value type to be collected
0150  * @var_args: the va_list variable; it may be evaluated multiple times
0151  * @flags: flags which are passed on to the collect_value() function of
0152  *  the #GTypeValueTable of @value.
0153  * @__error: a #gchar** variable that will be modified to hold a g_new()
0154  *  allocated error messages if something fails
0155  *
0156  * Collects a variable argument value from a `va_list`.
0157  *
0158  * We have to implement the varargs collection as a macro, because on some systems
0159  * `va_list` variables cannot be passed by reference.
0160  *
0161  * Note: If you are creating the @value argument just before calling this macro,
0162  * you should use the G_VALUE_COLLECT_INIT() variant and pass the uninitialized
0163  * #GValue. That variant is faster than G_VALUE_COLLECT().
0164  */
0165 #define G_VALUE_COLLECT(value, var_args, flags, __error) G_STMT_START {         \
0166   GValue *g_vc_value = (value);                             \
0167   GType g_vc_value_type = G_VALUE_TYPE (g_vc_value);                        \
0168   GTypeValueTable *g_vc_vtable = g_type_value_table_peek (g_vc_value_type);         \
0169                                             \
0170   if (g_vc_vtable->value_free)                              \
0171     g_vc_vtable->value_free (g_vc_value);                           \
0172   memset (g_vc_value->data, 0, sizeof (g_vc_value->data));                  \
0173                                             \
0174   G_VALUE_COLLECT_INIT(value, g_vc_value_type, var_args, flags, __error);           \
0175 } G_STMT_END
0176
0177 /**
0178  * G_VALUE_COLLECT_SKIP:
0179  * @_value_type: the #GType of the value to skip
0180  * @var_args: the va_list variable; it may be evaluated multiple times
0181  *
0182  * Skip an argument of type @_value_type from @var_args.
0183  */
0184 #define G_VALUE_COLLECT_SKIP(_value_type, var_args)                 \
0185 G_STMT_START {                                      \
0186   GTypeValueTable *g_vcs_vtable = g_type_value_table_peek (_value_type);            \
0187   const gchar *g_vcs_collect_format = g_vcs_vtable->collect_format;             \
0188                                                                                         \
0189   while (*g_vcs_collect_format)                             \
0190     {                                           \
0191       switch (*g_vcs_collect_format++)                          \
0192     {                                       \
0193     case G_VALUE_COLLECT_INT:                           \
0194       va_arg ((var_args), gint);                            \
0195       break;                                    \
0196     case G_VALUE_COLLECT_LONG:                          \
0197       va_arg ((var_args), glong);                           \
0198       break;                                    \
0199     case G_VALUE_COLLECT_INT64:                         \
0200       va_arg ((var_args), gint64);                          \
0201       break;                                    \
0202     case G_VALUE_COLLECT_DOUBLE:                            \
0203       va_arg ((var_args), gdouble);                         \
0204       break;                                    \
0205     case G_VALUE_COLLECT_POINTER:                           \
0206       va_arg ((var_args), gpointer);                        \
0207       break;                                    \
0208     default:                                    \
0209       g_assert_not_reached ();                          \
0210     }                                       \
0211     }                                           \
0212 } G_STMT_END
0213
0214 /**
0215  * G_VALUE_LCOPY:
0216  * @value: a #GValue to store into the @var_args; this must be initialized
0217  *  and set
0218  * @var_args: the va_list variable; it may be evaluated multiple times
0219  * @flags: flags which are passed on to the lcopy_value() function of
0220  *  the #GTypeValueTable of @value.
0221  * @__error: a #gchar** variable that will be modified to hold a g_new()
0222  *  allocated error message if something fails
0223  *
0224  * Stores a value’s value into one or more argument locations from a `va_list`.
0225  *
0226  * This is the inverse of G_VALUE_COLLECT().
0227  */
0228 #define G_VALUE_LCOPY(value, var_args, flags, __error)                  \
0229 G_STMT_START {                                      \
0230   const GValue *g_vl_value = (value);                           \
0231   guint g_vl_flags = (flags);                               \
0232   GType g_vl_value_type = G_VALUE_TYPE (g_vl_value);                        \
0233   GTypeValueTable *g_vl_vtable = g_type_value_table_peek (g_vl_value_type);         \
0234   const gchar *g_vl_lcopy_format = g_vl_vtable->lcopy_format;                   \
0235   GTypeCValue g_vl_cvalues[G_VALUE_COLLECT_FORMAT_MAX_LENGTH] = { { 0, }, };        \
0236   guint g_vl_n_values = 0;                                  \
0237                                                                                         \
0238   while (*g_vl_lcopy_format)                                \
0239     {                                           \
0240       GTypeCValue *g_vl_cvalue = g_vl_cvalues + g_vl_n_values++;                    \
0241                                                                                         \
0242       switch (*g_vl_lcopy_format++)                             \
0243     {                                       \
0244     case G_VALUE_COLLECT_INT:                           \
0245       g_vl_cvalue->v_int = va_arg ((var_args), gint);                   \
0246       break;                                    \
0247     case G_VALUE_COLLECT_LONG:                          \
0248       g_vl_cvalue->v_long = va_arg ((var_args), glong);                 \
0249       break;                                    \
0250     case G_VALUE_COLLECT_INT64:                         \
0251       g_vl_cvalue->v_int64 = va_arg ((var_args), gint64);               \
0252       break;                                    \
0253     case G_VALUE_COLLECT_DOUBLE:                            \
0254       g_vl_cvalue->v_double = va_arg ((var_args), gdouble);             \
0255       break;                                    \
0256     case G_VALUE_COLLECT_POINTER:                           \
0257       g_vl_cvalue->v_pointer = va_arg ((var_args), gpointer);               \
0258       break;                                    \
0259     default:                                    \
0260       g_assert_not_reached ();                          \
0261     }                                       \
0262     }                                           \
0263   *(__error) = g_vl_vtable->lcopy_value (g_vl_value,                        \
0264                      g_vl_n_values,                     \
0265                      g_vl_cvalues,                      \
0266                      g_vl_flags);                       \
0267 } G_STMT_END
0268
0269
0270 /**
0271  * G_VALUE_COLLECT_FORMAT_MAX_LENGTH:
0272  *
0273  * The maximal number of #GTypeCValues which can be collected for a
0274  * single #GValue.
0275  */
0276 #define G_VALUE_COLLECT_FORMAT_MAX_LENGTH   (8)
0277
0278 G_END_DECLS
0279
0280 #endif /* __G_VALUE_COLLECTOR_H__ */