Imported Upstream version 2.73.3

[platform/upstream/glib.git] / gobject / gvaluecollector.h

diff --git a/gobject/gvaluecollector.h b/gobject/gvaluecollector.h
index 177aa3d..7e7ae02 100644 (file)
--- a/gobject/gvaluecollector.h
+++ b/gobject/gvaluecollector.h
@@ -1,6 +1,8 @@
 /* GObject - GLib Type, Object, Parameter and Signal Library
  * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.
  *
+ * SPDX-License-Identifier: LGPL-2.1-or-later
+ *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
  * License as published by the Free Software Foundation; either
@@ -23,6 +25,7 @@
  * 
  * 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.
  */
@@ -79,21 +82,45 @@ union _GTypeCValue
  * @__error: a #gchar** variable that will be modified to hold a g_new()
  *  allocated error messages if something fails
  * 
- * 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.
+ * 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.
  *
  * Since: 2.24
  */
-#define G_VALUE_COLLECT_INIT(value, _value_type, var_args, flags, __error)             \
+#define G_VALUE_COLLECT_INIT(value, _value_type, var_args, flags, __error) \
+  G_STMT_START { \
+    GTypeValueTable *g_vci_vtab; \
+    G_VALUE_COLLECT_INIT2(value, g_vci_vtab, _value_type, var_args, flags, __error); \
+} G_STMT_END
+
+/**
+ * G_VALUE_COLLECT_INIT2:
+ * @value: a #GValue return location. @value must contain only 0 bytes.
+ * @g_vci_vtab: a #GTypeValueTable pointer that will be set to the value table
+ *   for @_value_type
+ * @_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
+ *
+ * A variant of G_VALUE_COLLECT_INIT() that provides the #GTypeValueTable
+ * to the caller.
+ *
+ * Since: 2.74
+ */
+#define G_VALUE_COLLECT_INIT2(value, g_vci_vtab, _value_type, var_args, flags, __error)                \
 G_STMT_START {                                                                         \
   GValue *g_vci_val = (value);                                                         \
   guint g_vci_flags = (flags);                                                         \
-  GTypeValueTable *g_vci_vtab = g_type_value_table_peek (_value_type);                 \
-  const gchar *g_vci_collect_format = g_vci_vtab->collect_format;                                      \
+  const gchar *g_vci_collect_format; \
   GTypeCValue g_vci_cvalues[G_VALUE_COLLECT_FORMAT_MAX_LENGTH] = { { 0, }, };          \
   guint g_vci_n_values = 0;                                                                    \
-                                                                                        \
+  g_vci_vtab = g_type_value_table_peek (_value_type);                  \
+  g_vci_collect_format = g_vci_vtab->collect_format;                                   \
   g_vci_val->g_type = _value_type;             /* value_meminit() from gvalue.c */             \
   while (*g_vci_collect_format)                                                                \
     {                                                                                  \
@@ -136,13 +163,14 @@ G_STMT_START {                                                                            \
  * @__error: a #gchar** variable that will be modified to hold a g_new()
  *  allocated error messages if something fails
  *
- * 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.
+ * 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.
+ * you should use the G_VALUE_COLLECT_INIT() variant and pass the uninitialized
+ * #GValue. That variant is faster than G_VALUE_COLLECT().
  */
 #define G_VALUE_COLLECT(value, var_args, flags, __error) G_STMT_START {                        \
   GValue *g_vc_value = (value);                                                                \
@@ -203,7 +231,8 @@ G_STMT_START {                                                                              \
  * @__error: a #gchar** variable that will be modified to hold a g_new()
  *  allocated error message if something fails
  *
- * Stores a value’s value into one or more argument locations from a va_list.
+ * Stores a value’s value into one or more argument locations from a `va_list`.
+ *
  * This is the inverse of G_VALUE_COLLECT().
  */
 #define G_VALUE_LCOPY(value, var_args, flags, __error)                                 \