* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
* FIXME: MT-safety
*/
+#include "config.h"
+
#include <string.h>
#include "gvalue.h"
#include "gvaluecollector.h"
#include "gbsearcharray.h"
+#include "gtype-private.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][gobject-Standard-Parameter-and-Value-Types]
+ * 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.
+ *
+ * |[<!-- language="C" -->
+ * #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 be initialized */
+ * GValue a = G_VALUE_INIT;
+ * GValue b = G_VALUE_INIT;
+ * const gchar *message;
+ *
+ * /* 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 --- */
/* --- variables --- */
-static GBSearchArray transform_array = G_STATIC_BSEARCH_ARRAY_INIT (sizeof (TransformEntry),
- transform_entries_cmp,
- 0);
+static GBSearchArray *transform_array = NULL;
+static GBSearchConfig transform_bconfig = {
+ sizeof (TransformEntry),
+ transform_entries_cmp,
+ G_BSEARCH_ARRAY_ALIGN_POWER2,
+};
/* --- functions --- */
+void
+_g_value_c_init (void)
+{
+ transform_array = g_bsearch_array_create (&transform_bconfig);
+}
+
static inline void /* keep this function in sync with gvaluecollector.h and gboxed.c */
value_meminit (GValue *value,
GType value_type)
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: (transfer none): the #GValue structure that has been passed in
+ */
GValue*
g_value_init (GValue *value,
GType g_type)
value_table->value_init (value);
}
else if (G_VALUE_TYPE (value))
- g_warning ("%s: cannot initialize GValue with type `%s', the value has already been initialized as `%s'",
+ g_warning ("%s: cannot initialize GValue with type '%s', the value has already been initialized as '%s'",
G_STRLOC,
g_type_name (g_type),
g_type_name (G_VALUE_TYPE (value)));
else /* !G_TYPE_IS_VALUE (g_type) */
- g_warning ("%s: cannot initialize GValue with type `%s', %s",
+ g_warning ("%s: cannot initialize GValue with type '%s', %s",
G_STRLOC,
g_type_name (g_type),
g_type_value_table_peek (g_type) ?
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)
}
}
+/**
+ * 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)
{
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)
{
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)
{
return value_table->value_peek_pointer != NULL;
}
+/**
+ * g_value_peek_pointer:
+ * @value: An initialized #GValue structure.
+ *
+ * Returns: (transfer none): 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.
+ */
gpointer
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_return_val_if_fail (g_value_fits_pointer (value) == TRUE, NULL);
+ {
+ 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: (allow-none): 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)
{
TransformEntry *e;
- e = g_bsearch_array_lookup (&transform_array, &entry);
+ e = g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry);
if (e)
{
/* need to check that there hasn't been a change in value handling */
return G_BSEARCH_ARRAY_CMP (e1->dest_type, e2->dest_type);
}
+/**
+ * g_value_register_transform_func: (skip)
+ * @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,
{
TransformEntry entry;
- g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (src_type));
- g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (dest_type));
+ /* these checks won't pass for dynamic types.
+ * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (src_type));
+ * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (dest_type));
+ */
g_return_if_fail (transform_func != NULL);
- if (transform_func_lookup (src_type, dest_type))
- g_warning ("reregistering value transformation function (%p) for `%s' to `%s'",
+ entry.src_type = src_type;
+ entry.dest_type = dest_type;
+
+#if 0 /* let transform function replacement be a valid operation */
+ if (g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry))
+ g_warning ("reregistering value transformation function (%p) for '%s' to '%s'",
transform_func,
g_type_name (src_type),
g_type_name (dest_type));
- entry.src_type = src_type;
- entry.dest_type = dest_type;
+#endif
+
entry.func = transform_func;
- g_bsearch_array_insert (&transform_array, &entry, TRUE);
+ 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. Note that for
+ * the types to be transformable, they must be compatible and a
+ * transform function must be registered.
+ *
+ * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
+ */
gboolean
g_value_type_transformable (GType src_type,
GType dest_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)
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)