1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17 * Boston, MA 02111-1307, USA.
29 #include "gvaluecollector.h"
30 #include "gbsearcharray.h"
34 * SECTION:generic_values
35 * @short_description: A polymorphic type that can hold values of any
37 * @see_also: The fundamental types which all support #GValue
38 * operations and thus can be used as a type initializer for
39 * g_value_init() are defined by a separate interface. See the <link
40 * linkend="gobject-Standard-Parameter-and-Value-Types">Standard
41 * Values API</link> for details.
42 * @title: Generic values
44 * The #GValue structure is basically a variable container that consists
45 * of a type identifier and a specific value of that type.
46 * The type identifier within a #GValue structure always determines the
47 * type of the associated value.
48 * To create a undefined #GValue structure, simply create a zero-filled
49 * #GValue structure. To initialize the #GValue, use the g_value_init()
50 * function. A #GValue cannot be used until it is initialized.
51 * The basic type operations (such as freeing and copying) are determined
52 * by the #GTypeValueTable associated with the type ID stored in the #GValue.
53 * Other #GValue operations (such as converting values between types) are
54 * provided by this interface.
56 * The code in the example program below demonstrates #GValue's
60 * #include <glib-object.h>
63 * int2string (const GValue *src_value,
66 * if (g_value_get_int (src_value) == 42)
67 * g_value_set_static_string (dest_value, "An important number");
69 * g_value_set_static_string (dest_value, "What's that?");
76 * /* GValues must start zero-filled */
79 * const gchar *message;
83 * /* The GValue starts empty */
84 * g_assert (!G_VALUE_HOLDS_STRING (&a));
86 * /* Put a string in it */
87 * g_value_init (&a, G_TYPE_STRING);
88 * g_assert (G_VALUE_HOLDS_STRING (&a));
89 * g_value_set_static_string (&a, "Hello, world!");
90 * g_printf ("%s\n", g_value_get_string (&a));
92 * /* Reset it to its pristine state */
93 * g_value_unset (&a);
95 * /* It can then be reused for another type */
96 * g_value_init (&a, G_TYPE_INT);
97 * g_value_set_int (&a, 42);
99 * /* Attempt to transform it into a GValue of type STRING */
100 * g_value_init (&b, G_TYPE_STRING);
102 * /* An INT is transformable to a STRING */
103 * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
105 * g_value_transform (&a, &b);
106 * g_printf ("%s\n", g_value_get_string (&b));
108 * /* Attempt to transform it again using a custom transform function */
109 * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
110 * g_value_transform (&a, &b);
111 * g_printf ("%s\n", g_value_get_string (&b));
118 /* --- typedefs & structures --- */
122 GValueTransform func;
126 /* --- prototypes --- */
127 static gint transform_entries_cmp (gconstpointer bsearch_node1,
128 gconstpointer bsearch_node2);
131 /* --- variables --- */
132 static GBSearchArray *transform_array = NULL;
133 static GBSearchConfig transform_bconfig = {
134 sizeof (TransformEntry),
135 transform_entries_cmp,
136 G_BSEARCH_ARRAY_ALIGN_POWER2,
140 /* --- functions --- */
142 _g_value_c_init (void)
144 transform_array = g_bsearch_array_create (&transform_bconfig);
147 static inline void /* keep this function in sync with gvaluecollector.h and gboxed.c */
148 value_meminit (GValue *value,
151 value->g_type = value_type;
152 memset (value->data, 0, sizeof (value->data));
157 * @value: A zero-filled (uninitialized) #GValue structure.
158 * @g_type: Type the #GValue should hold values of.
160 * Initializes @value with the default value of @type.
162 * Returns: (transfer none): the #GValue structure that has been passed in
165 g_value_init (GValue *value,
168 /* g_return_val_if_fail (G_TYPE_IS_VALUE (g_type), NULL); be more elaborate below */
169 g_return_val_if_fail (value != NULL, NULL);
170 /* g_return_val_if_fail (G_VALUE_TYPE (value) == 0, NULL); be more elaborate below */
172 if (G_TYPE_IS_VALUE (g_type) && G_VALUE_TYPE (value) == 0)
174 GTypeValueTable *value_table = g_type_value_table_peek (g_type);
177 value_meminit (value, g_type);
178 value_table->value_init (value);
180 else if (G_VALUE_TYPE (value))
181 g_warning ("%s: cannot initialize GValue with type `%s', the value has already been initialized as `%s'",
183 g_type_name (g_type),
184 g_type_name (G_VALUE_TYPE (value)));
185 else /* !G_TYPE_IS_VALUE (g_type) */
186 g_warning ("%s: cannot initialize GValue with type `%s', %s",
188 g_type_name (g_type),
189 g_type_value_table_peek (g_type) ?
190 "this type is abstract with regards to GValue use, use a more specific (derived) type" :
191 "this type has no GTypeValueTable implementation");
197 * @src_value: An initialized #GValue structure.
198 * @dest_value: An initialized #GValue structure of the same type as @src_value.
200 * Copies the value of @src_value into @dest_value.
203 g_value_copy (const GValue *src_value,
206 g_return_if_fail (G_IS_VALUE (src_value));
207 g_return_if_fail (G_IS_VALUE (dest_value));
208 g_return_if_fail (g_value_type_compatible (G_VALUE_TYPE (src_value), G_VALUE_TYPE (dest_value)));
210 if (src_value != dest_value)
212 GType dest_type = G_VALUE_TYPE (dest_value);
213 GTypeValueTable *value_table = g_type_value_table_peek (dest_type);
215 /* make sure dest_value's value is free()d */
216 if (value_table->value_free)
217 value_table->value_free (dest_value);
220 value_meminit (dest_value, dest_type);
221 value_table->value_copy (src_value, dest_value);
227 * @value: An initialized #GValue structure.
229 * Clears the current value in @value and resets it to the default value
230 * (as if the value had just been initialized).
232 * Returns: the #GValue structure that has been passed in
235 g_value_reset (GValue *value)
237 GTypeValueTable *value_table;
240 g_return_val_if_fail (G_IS_VALUE (value), NULL);
242 g_type = G_VALUE_TYPE (value);
243 value_table = g_type_value_table_peek (g_type);
245 /* make sure value's value is free()d */
246 if (value_table->value_free)
247 value_table->value_free (value);
250 value_meminit (value, g_type);
251 value_table->value_init (value);
258 * @value: An initialized #GValue structure.
260 * Clears the current value in @value and "unsets" the type,
261 * this releases all resources associated with this GValue.
262 * An unset value is the same as an uninitialized (zero-filled)
266 g_value_unset (GValue *value)
268 GTypeValueTable *value_table;
270 g_return_if_fail (G_IS_VALUE (value));
272 value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
274 if (value_table->value_free)
275 value_table->value_free (value);
276 memset (value, 0, sizeof (*value));
280 * g_value_fits_pointer:
281 * @value: An initialized #GValue structure.
283 * Determines if @value will fit inside the size of a pointer value.
284 * This is an internal function introduced mainly for C marshallers.
286 * Returns: %TRUE if @value will fit inside a pointer value.
289 g_value_fits_pointer (const GValue *value)
291 GTypeValueTable *value_table;
293 g_return_val_if_fail (G_IS_VALUE (value), FALSE);
295 value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
297 return value_table->value_peek_pointer != NULL;
301 * g_value_peek_pointer:
302 * @value: An initialized #GValue structure.
304 * Returns: (transfer none): the value contents as pointer. This
305 * function asserts that g_value_fits_pointer() returned %TRUE for the
306 * passed in value. This is an internal function introduced mainly
310 g_value_peek_pointer (const GValue *value)
312 GTypeValueTable *value_table;
314 g_return_val_if_fail (G_IS_VALUE (value), NULL);
316 value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
317 if (!value_table->value_peek_pointer)
319 g_return_val_if_fail (g_value_fits_pointer (value) == TRUE, NULL);
323 return value_table->value_peek_pointer (value);
327 * g_value_set_instance:
328 * @value: An initialized #GValue structure.
329 * @instance: the instance
331 * Sets @value from an instantiatable type via the
332 * value_table's collect_value() function.
335 g_value_set_instance (GValue *value,
339 GTypeValueTable *value_table;
343 g_return_if_fail (G_IS_VALUE (value));
346 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
347 g_return_if_fail (g_value_type_compatible (G_TYPE_FROM_INSTANCE (instance), G_VALUE_TYPE (value)));
350 g_type = G_VALUE_TYPE (value);
351 value_table = g_type_value_table_peek (g_type);
353 g_return_if_fail (strcmp (value_table->collect_format, "p") == 0);
355 memset (&cvalue, 0, sizeof (cvalue));
356 cvalue.v_pointer = instance;
358 /* make sure value's value is free()d */
359 if (value_table->value_free)
360 value_table->value_free (value);
362 /* setup and collect */
363 value_meminit (value, g_type);
364 error_msg = value_table->collect_value (value, 1, &cvalue, 0);
367 g_warning ("%s: %s", G_STRLOC, error_msg);
370 /* we purposely leak the value here, it might not be
371 * in a sane state if an error condition occoured
373 value_meminit (value, g_type);
374 value_table->value_init (value);
378 static GValueTransform
379 transform_func_lookup (GType src_type,
382 TransformEntry entry;
384 entry.src_type = src_type;
387 entry.dest_type = dest_type;
392 e = g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry);
395 /* need to check that there hasn't been a change in value handling */
396 if (g_type_value_table_peek (entry.dest_type) == g_type_value_table_peek (dest_type) &&
397 g_type_value_table_peek (entry.src_type) == g_type_value_table_peek (src_type))
400 entry.dest_type = g_type_parent (entry.dest_type);
402 while (entry.dest_type);
404 entry.src_type = g_type_parent (entry.src_type);
406 while (entry.src_type);
412 transform_entries_cmp (gconstpointer bsearch_node1,
413 gconstpointer bsearch_node2)
415 const TransformEntry *e1 = bsearch_node1;
416 const TransformEntry *e2 = bsearch_node2;
417 gint cmp = G_BSEARCH_ARRAY_CMP (e1->src_type, e2->src_type);
422 return G_BSEARCH_ARRAY_CMP (e1->dest_type, e2->dest_type);
426 * g_value_register_transform_func: (skip)
427 * @src_type: Source type.
428 * @dest_type: Target type.
429 * @transform_func: a function which transforms values of type @src_type
430 * into value of type @dest_type
432 * Registers a value transformation function for use in g_value_transform().
433 * A previously registered transformation function for @src_type and @dest_type
437 g_value_register_transform_func (GType src_type,
439 GValueTransform transform_func)
441 TransformEntry entry;
443 /* these checks won't pass for dynamic types.
444 * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (src_type));
445 * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (dest_type));
447 g_return_if_fail (transform_func != NULL);
449 entry.src_type = src_type;
450 entry.dest_type = dest_type;
452 #if 0 /* let transform function replacement be a valid operation */
453 if (g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry))
454 g_warning ("reregistering value transformation function (%p) for `%s' to `%s'",
456 g_type_name (src_type),
457 g_type_name (dest_type));
460 entry.func = transform_func;
461 transform_array = g_bsearch_array_replace (transform_array, &transform_bconfig, &entry);
465 * g_value_type_transformable:
466 * @src_type: Source type.
467 * @dest_type: Target type.
469 * Check whether g_value_transform() is able to transform values
470 * of type @src_type into values of type @dest_type.
472 * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
475 g_value_type_transformable (GType src_type,
478 g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
479 g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
481 return (g_value_type_compatible (src_type, dest_type) ||
482 transform_func_lookup (src_type, dest_type) != NULL);
486 * g_value_type_compatible:
487 * @src_type: source type to be copied.
488 * @dest_type: destination type for copying.
490 * Returns whether a #GValue of type @src_type can be copied into
491 * a #GValue of type @dest_type.
493 * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
496 g_value_type_compatible (GType src_type,
499 g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
500 g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
502 return (g_type_is_a (src_type, dest_type) &&
503 g_type_value_table_peek (dest_type) == g_type_value_table_peek (src_type));
508 * @src_value: Source value.
509 * @dest_value: Target value.
511 * Tries to cast the contents of @src_value into a type appropriate
512 * to store in @dest_value, e.g. to transform a %G_TYPE_INT value
513 * into a %G_TYPE_FLOAT value. Performing transformations between
514 * value types might incur precision lossage. Especially
515 * transformations into strings might reveal seemingly arbitrary
516 * results and shouldn't be relied upon for production code (such
517 * as rcfile value or object property serialization).
519 * Returns: Whether a transformation rule was found and could be applied.
520 * Upon failing transformations, @dest_value is left untouched.
523 g_value_transform (const GValue *src_value,
528 g_return_val_if_fail (G_IS_VALUE (src_value), FALSE);
529 g_return_val_if_fail (G_IS_VALUE (dest_value), FALSE);
531 dest_type = G_VALUE_TYPE (dest_value);
532 if (g_value_type_compatible (G_VALUE_TYPE (src_value), dest_type))
534 g_value_copy (src_value, dest_value);
540 GValueTransform transform = transform_func_lookup (G_VALUE_TYPE (src_value), dest_type);
544 g_value_unset (dest_value);
546 /* setup and transform */
547 value_meminit (dest_value, dest_type);
548 transform (src_value, dest_value);