Bug 523939 – Example program for GValue

2008-08-22  Björn Lindqvist  <bjourne@gmail.com>

	Bug 523939 – Example program for GValue

	* gobject/gvalue.c: Add code example that demonstrates GValue's
	features.

svn path=/trunk/; revision=7387

ChangeLog

@@ -1,3 +1,10 @@
+2008-08-22  Björn Lindqvist  <bjourne@gmail.com>
+
+	Bug 523939 – Example program for GValue
+
+	* gobject/gvalue.c: Add code example that demonstrates GValue's
+	features.
+
 2008-08-21  Tor Lillqvist  <tml@novell.com>
 
 	* glib/giowin32.c: Minor comment improvements. Improve run-time

gobject/gvalue.c

@@ -53,6 +53,66 @@
  * by the #GTypeValueTable associated with the type ID stored in the #GValue.
  * Other #GValue operations (such as converting values between types) are
  * provided by this interface.
+ *
+ * The code in the example program below demonstrates #GValue's
+ * features.
+ *
+ * |[
+ * #include <glib-object.h>
+ *
+ * static void
+ * int2string (const GValue *src_value,
+ *             GValue       *dest_value)
+ * {
+ *   if (g_value_get_int (src_value) == 42)
+ *     g_value_set_static_string (dest_value, "An important number");
+ *   else
+ *     g_value_set_static_string (dest_value, "What's that?");
+ * }
+ *
+ * int
+ * main (int   argc,
+ *       char *argv[])
+ * {
+ *   /* GValues must start zero-filled */
+ *   GValue a = {0};
+ *   GValue b = {0};
+ *   const gchar *message;
+ *
+ *   g_type_init ();
+ *
+ *   /* The GValue starts empty */
+ *   g_assert (!G_VALUE_HOLDS_STRING (&a));
+ *
+ *   /* Put a string in it */
+ *   g_value_init (&a, G_TYPE_STRING);
+ *   g_assert (G_VALUE_HOLDS_STRING (&a));
+ *   g_value_set_static_string (&a, "Hello, world!");
+ *   g_printf ("%s\n", g_value_get_string (&a));
+ *
+ *   /* Reset it to its pristine state */
+ *   g_value_unset (&a);
+ *
+ *   /* It can then be reused for another type */
+ *   g_value_init (&a, G_TYPE_INT);
+ *   g_value_set_int (&a, 42);
+ *
+ *   /* Attempt to transform it into a GValue of type STRING */
+ *   g_value_init (&b, G_TYPE_STRING);
+ *
+ *   /* An INT is transformable to a STRING */
+ *   g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
+ *
+ *   g_value_transform (&a, &b);
+ *   g_printf ("%s\n", g_value_get_string (&b));
+ *
+ *   /* Attempt to transform it again using a custom transform function */
+ *   g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
+ *   g_value_transform (&a, &b);
+ *   g_printf ("%s\n", g_value_get_string (&b));
+ *   return 0;
+ * }
+ * ]|
  */