Commit 2b8edf23 authored by Philip Withnall's avatar Philip Withnall

gvariant: Document the need to cast varargs when constructing GVariants

Slightly expand on the documentation about casting varargs when
constructing GVariants, and link to it from all the functions where it’s
a necessary consideration.

Add an example of passing flags to a ‘t’ type variable (guint64).
Assuming the flags enum does not have many members, the flag variable
will be 32 bits wide, and needs an explicit cast to be passed into
g_variant_new() as a 64-bit value.

https://bugzilla.gnome.org/show_bug.cgi?id=712837
parent 3f3d2976
......@@ -466,6 +466,7 @@
</tgroup>
</informaltable>
<anchor id='gvariant-varargs'/>
<para>
Note that in C, small integer types in variable argument lists are promoted up to <link
linkend='gint'><type>int</type></link> or <link linkend='guint'><type>unsigned int</type></link> as appropriate, and
......
......@@ -2428,6 +2428,10 @@ g_variant_parse (const GVariantType *type,
* #GVariant pointer will be returned unmodified, without adding any
* additional references.
*
* Note that the arguments in @app must be of the correct width for their types
* specified in @format when collected into the #va_list. See
* the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
*
* In order to behave correctly in all cases it is necessary for the
* calling function to g_variant_ref_sink() the return result before
* returning control to the user that originally provided the pointer.
......@@ -2481,6 +2485,10 @@ g_variant_new_parsed_va (const gchar *format,
* that case, the same arguments are collected from the argument list as
* g_variant_new() would have collected.
*
* Note that the arguments must be of the correct width for their types
* specified in @format. This can be achieved by casting them. See
* the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
*
* Consider this simple example:
* |[<!-- language="C" -->
* g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
......@@ -2530,6 +2538,10 @@ g_variant_new_parsed (const gchar *format,
* calling g_variant_new_parsed() followed by
* g_variant_builder_add_value().
*
* Note that the arguments must be of the correct width for their types
* specified in @format_string. This can be achieved by casting them. See
* the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
*
* This function might be used as follows:
*
* |[<!-- language="C" -->
......
......@@ -5168,6 +5168,21 @@ g_variant_valist_get (const gchar **str,
* 'r'; in essence, a new #GVariant must always be constructed by this
* function (and not merely passed through it unmodified).
*
* Note that the arguments must be of the correct width for their types
* specified in @format_string. This can be achieved by casting them. See
* the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
*
* <programlisting>
* MyFlags some_flags = FLAG_ONE | FLAG_TWO;
* const gchar *some_strings[] = { "a", "b", "c", NULL };
* GVariant *new_variant;
*
* new_variant = g_variant_new ("(t^as)",
* /<!-- -->* This cast is required. *<!-- -->/
* (guint64) some_flags,
* some_strings);
* </programlisting>
*
* Returns: a new floating #GVariant instance
*
* Since: 2.24
......@@ -5214,6 +5229,10 @@ g_variant_new (const gchar *format_string,
* @format_string, are collected from this #va_list and the list is left
* pointing to the argument following the last.
*
* Note that the arguments in @app must be of the correct width for their types
* specified in @format_string when collected into the #va_list. See
* the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
*
* These two generalisations allow mixing of multiple calls to
* g_variant_new_va() and g_variant_get_va() within a single actual
* varargs call by the user.
......@@ -5365,6 +5384,10 @@ g_variant_get_va (GVariant *value,
* This call is a convenience wrapper that is exactly equivalent to
* calling g_variant_new() followed by g_variant_builder_add_value().
*
* Note that the arguments must be of the correct width for their types
* specified in @format_string. This can be achieved by casting them. See
* the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
*
* This function might be used as follows:
*
* |[<!-- language="C" -->
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment