X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gobject%2Fgvalue.c;h=9247d4c9b50fb2e53cc4f65184a89647ae7e3066;hb=0fc50fa5f7424d21ff43a79838fe76ff73ad869b;hp=680122f918f91bf1fdb58dc44aeaf78eca340180;hpb=465c7d1ead296b70b8d47ca333554a18f71da11d;p=platform%2Fupstream%2Fglib.git diff --git a/gobject/gvalue.c b/gobject/gvalue.c index 680122f..9247d4c 100644 --- a/gobject/gvalue.c +++ b/gobject/gvalue.c @@ -21,14 +21,100 @@ * FIXME: MT-safety */ +#include "config.h" + #include -#include "gobjectalias.h" #include "gvalue.h" #include "gvaluecollector.h" #include "gbsearcharray.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 Standard + * Values API 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 + * type of the associated value. + * To create a undefined #GValue structure, simply create a zero-filled + * #GValue structure. To initialize the #GValue, use the g_value_init() + * function. A #GValue cannot be used until it is initialized. + * The basic type operations (such as freeing and copying) are determined + * 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; + * } + * ]| + */ + + /* --- typedefs & structures --- */ typedef struct { GType src_type; @@ -47,7 +133,7 @@ static GBSearchArray *transform_array = NULL; static GBSearchConfig transform_bconfig = { sizeof (TransformEntry), transform_entries_cmp, - 0, + G_BSEARCH_ARRAY_ALIGN_POWER2, }; @@ -66,6 +152,15 @@ value_meminit (GValue *value, memset (value->data, 0, sizeof (value->data)); } +/** + * 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_init (GValue *value, GType g_type) @@ -97,6 +192,13 @@ g_value_init (GValue *value, return value; } +/** + * 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_copy (const GValue *src_value, GValue *dest_value) @@ -120,6 +222,15 @@ g_value_copy (const GValue *src_value, } } +/** + * 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_reset (GValue *value) { @@ -142,6 +253,15 @@ g_value_reset (GValue *value) return value; } +/** + * 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) + * #GValue structure. + */ void g_value_unset (GValue *value) { @@ -156,6 +276,15 @@ g_value_unset (GValue *value) memset (value, 0, sizeof (*value)); } +/** + * 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_fits_pointer (const GValue *value) { @@ -168,6 +297,16 @@ g_value_fits_pointer (const GValue *value) return value_table->value_peek_pointer != NULL; } +/** + * 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_peek_pointer (const GValue *value) { @@ -178,13 +317,21 @@ g_value_peek_pointer (const GValue *value) value_table = g_type_value_table_peek (G_VALUE_TYPE (value)); if (!value_table->value_peek_pointer) { - g_assert (g_value_fits_pointer (value) == TRUE); + g_return_val_if_fail (g_value_fits_pointer (value) == TRUE, NULL); return NULL; } return value_table->value_peek_pointer (value); } +/** + * g_value_set_instance: + * @value: An initialized #GValue structure. + * @instance: the instance + * + * Sets @value from an instantiatable type via the + * value_table's collect_value() function. + */ void g_value_set_instance (GValue *value, gpointer instance) @@ -276,6 +423,17 @@ transform_entries_cmp (gconstpointer bsearch_node1, return G_BSEARCH_ARRAY_CMP (e1->dest_type, e2->dest_type); } +/** + * g_value_register_transform_func: + * @src_type: Source type. + * @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. + */ void g_value_register_transform_func (GType src_type, GType dest_type, @@ -304,6 +462,16 @@ g_value_register_transform_func (GType src_type, transform_array = g_bsearch_array_replace (transform_array, &transform_bconfig, &entry); } +/** + * 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_transformable (GType src_type, GType dest_type) @@ -315,6 +483,16 @@ g_value_type_transformable (GType src_type, transform_func_lookup (src_type, dest_type) != NULL); } +/** + * 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_type_compatible (GType src_type, GType dest_type) @@ -326,6 +504,22 @@ g_value_type_compatible (GType src_type, g_type_value_table_peek (dest_type) == g_type_value_table_peek (src_type)); } +/** + * 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 + * value types might incur precision lossage. Especially + * 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. + */ gboolean g_value_transform (const GValue *src_value, GValue *dest_value)