diff --git a/docs/reference/gobject/gobject.toml.in b/docs/reference/gobject/gobject.toml.in index ddd44c8bd..de39bc489 100644 --- a/docs/reference/gobject/gobject.toml.in +++ b/docs/reference/gobject/gobject.toml.in @@ -50,6 +50,7 @@ content_files = [ "boxed.md", "enum-types.md", "gvalue.md", + "value-collection.md", ] content_images = [ "images/glue.png", diff --git a/docs/reference/gobject/meson.build b/docs/reference/gobject/meson.build index 7a39440dd..945e16a35 100644 --- a/docs/reference/gobject/meson.build +++ b/docs/reference/gobject/meson.build @@ -74,6 +74,7 @@ expand_content_files = [ 'tutorial.md', 'types.md', 'signals.md', + 'value-collection.md', ] gobject_toml = configure_file(input: 'gobject.toml.in', output: 'gobject.toml', configuration: toml_conf) diff --git a/docs/reference/gobject/value-collection.md b/docs/reference/gobject/value-collection.md new file mode 100644 index 000000000..f04070382 --- /dev/null +++ b/docs/reference/gobject/value-collection.md @@ -0,0 +1,56 @@ +Title: Value Collection +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 2005 Matthias Clasen + +# Value Collection + +GLib provides a set of macros for the varargs parsing support needed +in variadic GObject functions such as [ctor@GObject.Object.new] or +[method@GObject.Object.set] + +They currently support the collection of integral types, floating point +types and pointers. + +## Macros + +`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. + + Since: 2.24 + +`G_VALUE_COLLECT_INIT2(value, g_vci_vtab, _value_type, var_args, flags, __error)` + +: A variant of `G_VALUE_COLLECT_INIT` that provides the [struct@GObject.TypeValueTable] + to the caller. + + Since: 2.74 + +`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 uninitialized + `GValue`. That variant is faster than `G_VALUE_COLLECT`. + +`G_VALUE_COLLECT_SKIP(_value_type, var_args)` + +: Skip an argument of type `_value_type` from `var_args`. + +`G_VALUE_LCOPY(value, var_args, flags, __error)` + +: Stores a value’s value into one or more argument locations from a `va_list`. + + This is the inverse of G_VALUE_COLLECT(). + +`G_VALUE_COLLECT_FORMAT_MAX_LENGTH` + +: The maximal number of [type@GObject.TypeCValue]s which can be collected for a + single `GValue`. diff --git a/gobject/gvaluecollector.h b/gobject/gvaluecollector.h index 7e7ae021b..35608b107 100644 --- a/gobject/gvaluecollector.h +++ b/gobject/gvaluecollector.h @@ -18,17 +18,7 @@ * * gvaluecollector.h: GValue varargs stubs */ -/** - * SECTION:value_collection - * @Short_description: Converting varargs to generic values - * @Title: Varargs Value Collection - * - * 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. - */ + #ifndef __G_VALUE_COLLECTOR_H__ #define __G_VALUE_COLLECTOR_H__