* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
+
+/*
+ * FIXME: MT-safety
+ */
+
+#include "config.h"
+
+#include <string.h>
+
+#include "gvalue.h"
+#include "gvaluecollector.h"
+#include "gbsearcharray.h"
+#include "gobjectalias.h"
+
+
/**
- * SECTION:Generic Values
- * @Short_description: A polymorphic type that can hold values of any other type
- * @See_also: The fundamental types which all support #GValue operations and
- * thus can be used as a type initializer for g_value_init() are defined by
- * a separate interface. See the <link
- * linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values
- * API</link> for details.
- *
+ * SECTION:generic_values
+ * @short_description: A polymorphic type that can hold values of any
+ * other type
+ * @see_also: The fundamental types which all support #GValue
+ * operations and thus can be used as a type initializer for
+ * g_value_init() are defined by a separate interface. See the <link
+ * linkend="gobject-Standard-Parameter-and-Value-Types">Standard
+ * Values API</link> for details.
+ * @title: Generic values
+ *
* The #GValue structure is basically a variable container that consists
* of a type identifier and a specific value of that type.
* The type identifier within a #GValue structure always determines the
* 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;
+ * }
+ * ]|
*/
-/*
- * FIXME: MT-safety
- */
-
-#include <string.h>
-
-#include "gvalue.h"
-#include "gvaluecollector.h"
-#include "gbsearcharray.h"
-#include "gobjectalias.h"
-
/* --- typedefs & structures --- */
typedef struct {
static GBSearchConfig transform_bconfig = {
sizeof (TransformEntry),
transform_entries_cmp,
- 0,
+ G_BSEARCH_ARRAY_ALIGN_POWER2,
};
* g_value_init:
* @value: A zero-filled (uninitialized) #GValue structure.
* @g_type: Type the #GValue should hold values of.
- *
+ *
* Initializes @value with the default value of @type.
- *
+ *
* Returns: the #GValue structure that has been passed in
*/
GValue*
* g_value_copy:
* @src_value: An initialized #GValue structure.
* @dest_value: An initialized #GValue structure of the same type as @src_value.
- *
+ *
* Copies the value of @src_value into @dest_value.
*/
void
/**
* g_value_reset:
* @value: An initialized #GValue structure.
- *
+ *
* Clears the current value in @value and resets it to the default value
* (as if the value had just been initialized).
- *
+ *
* Returns: the #GValue structure that has been passed in
*/
GValue*
/**
* g_value_unset:
* @value: An initialized #GValue structure.
- *
+ *
* Clears the current value in @value and "unsets" the type,
* this releases all resources associated with this GValue.
* An unset value is the same as an uninitialized (zero-filled)
/**
* g_value_fits_pointer:
* @value: An initialized #GValue structure.
- *
+ *
* Determines if @value will fit inside the size of a pointer value.
* This is an internal function introduced mainly for C marshallers.
- *
+ *
* Returns: %TRUE if @value will fit inside a pointer value.
*/
gboolean
/**
* g_value_peek_pointer:
* @value: An initialized #GValue structure.
- *
+ *
* Return the value contents as pointer. This function asserts that
* g_value_fits_pointer() returned %TRUE for the passed in value.
* This is an internal function introduced mainly for C marshallers.
- *
+ *
* Returns: %TRUE if @value will fit inside a pointer value.
*/
gpointer
* g_value_set_instance:
* @value: An initialized #GValue structure.
* @instance: the instance
- *
- * Sets @value from an instantiatable type via the
+ *
+ * Sets @value from an instantiatable type via the
* value_table's collect_value() function.
*/
void
* @dest_type: Target type.
* @transform_func: a function which transforms values of type @src_type
* into value of type @dest_type
- *
+ *
* Registers a value transformation function for use in g_value_transform().
* A previously registered transformation function for @src_type and @dest_type
* will be replaced.
* g_value_type_transformable:
* @src_type: Source type.
* @dest_type: Target type.
- *
+ *
* Check whether g_value_transform() is able to transform values
* of type @src_type into values of type @dest_type.
- *
+ *
* Returns: %TRUE if the transformation is possible, %FALSE otherwise.
*/
gboolean
* g_value_type_compatible:
* @src_type: source type to be copied.
* @dest_type: destination type for copying.
- *
+ *
* Returns whether a #GValue of type @src_type can be copied into
* a #GValue of type @dest_type.
- *
+ *
* Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
*/
gboolean
* g_value_transform:
* @src_value: Source value.
* @dest_value: Target value.
- *
+ *
* Tries to cast the contents of @src_value into a type appropriate
* to store in @dest_value, e.g. to transform a %G_TYPE_INT value
* into a %G_TYPE_FLOAT value. Performing transformations between
* transformations into strings might reveal seemingly arbitrary
* results and shouldn't be relied upon for production code (such
* as rcfile value or object property serialization).
- *
+ *
* Returns: Whether a transformation rule was found and could be applied.
* Upon failing transformations, @dest_value is left untouched.
*/
projects / platform / upstream / glib.git / blobdiff