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, see <http://www.gnu.org/licenses/>.
27 #include "gvaluecollector.h"
28 #include "gbsearcharray.h"
29 #include "gtype-private.h"
33 * SECTION:generic_values
34 * @short_description: A polymorphic type that can hold values of any
36 * @see_also: The fundamental types which all support #GValue
37 * operations and thus can be used as a type initializer for
38 * g_value_init() are defined by a separate interface. See the
39 * [standard values API][gobject-Standard-Parameter-and-Value-Types]
41 * @title: Generic values
43 * The #GValue structure is basically a variable container that consists
44 * of a type identifier and a specific value of that type.
45 * The type identifier within a #GValue structure always determines the
46 * type of the associated value.
47 * To create a undefined #GValue structure, simply create a zero-filled
48 * #GValue structure. To initialize the #GValue, use the g_value_init()
49 * function. A #GValue cannot be used until it is initialized.
50 * The basic type operations (such as freeing and copying) are determined
51 * by the #GTypeValueTable associated with the type ID stored in the #GValue.
52 * Other #GValue operations (such as converting values between types) are
53 * provided by this interface.
55 * The code in the example program below demonstrates #GValue's
58 * |[<!-- language="C" -->
59 * #include <glib-object.h>
62 * int2string (const GValue *src_value,
65 * if (g_value_get_int (src_value) == 42)
66 * g_value_set_static_string (dest_value, "An important number");
68 * g_value_set_static_string (dest_value, "What's that?");
75 * // GValues must be initialized
76 * GValue a = G_VALUE_INIT;
77 * GValue b = G_VALUE_INIT;
78 * const gchar *message;
80 * // The GValue starts empty
81 * g_assert (!G_VALUE_HOLDS_STRING (&a));
83 * // Put a string in it
84 * g_value_init (&a, G_TYPE_STRING);
85 * g_assert (G_VALUE_HOLDS_STRING (&a));
86 * g_value_set_static_string (&a, "Hello, world!");
87 * g_printf ("%s\n", g_value_get_string (&a));
89 * // Reset it to its pristine state
92 * // It can then be reused for another type
93 * g_value_init (&a, G_TYPE_INT);
94 * g_value_set_int (&a, 42);
96 * // Attempt to transform it into a GValue of type STRING
97 * g_value_init (&b, G_TYPE_STRING);
99 * // An INT is transformable to a STRING
100 * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
102 * g_value_transform (&a, &b);
103 * g_printf ("%s\n", g_value_get_string (&b));
105 * // Attempt to transform it again using a custom transform function
106 * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
107 * g_value_transform (&a, &b);
108 * g_printf ("%s\n", g_value_get_string (&b));
115 /* --- typedefs & structures --- */
119 GValueTransform func
;
123 /* --- prototypes --- */
124 static gint
transform_entries_cmp (gconstpointer bsearch_node1
,
125 gconstpointer bsearch_node2
);
128 /* --- variables --- */
129 static GBSearchArray
*transform_array
= NULL
;
130 static GBSearchConfig transform_bconfig
= {
131 sizeof (TransformEntry
),
132 transform_entries_cmp
,
133 G_BSEARCH_ARRAY_ALIGN_POWER2
,
137 /* --- functions --- */
139 _g_value_c_init (void)
141 transform_array
= g_bsearch_array_create (&transform_bconfig
);
144 static inline void /* keep this function in sync with gvaluecollector.h and gboxed.c */
145 value_meminit (GValue
*value
,
148 value
->g_type
= value_type
;
149 memset (value
->data
, 0, sizeof (value
->data
));
154 * @value: A zero-filled (uninitialized) #GValue structure.
155 * @g_type: Type the #GValue should hold values of.
157 * Initializes @value with the default value of @type.
159 * Returns: (transfer none): the #GValue structure that has been passed in
162 g_value_init (GValue
*value
,
165 /* g_return_val_if_fail (G_TYPE_IS_VALUE (g_type), NULL); be more elaborate below */
166 g_return_val_if_fail (value
!= NULL
, NULL
);
167 /* g_return_val_if_fail (G_VALUE_TYPE (value) == 0, NULL); be more elaborate below */
169 if (G_TYPE_IS_VALUE (g_type
) && G_VALUE_TYPE (value
) == 0)
171 GTypeValueTable
*value_table
= g_type_value_table_peek (g_type
);
174 value_meminit (value
, g_type
);
175 value_table
->value_init (value
);
177 else if (G_VALUE_TYPE (value
))
178 g_warning ("%s: cannot initialize GValue with type '%s', the value has already been initialized as '%s'",
180 g_type_name (g_type
),
181 g_type_name (G_VALUE_TYPE (value
)));
182 else /* !G_TYPE_IS_VALUE (g_type) */
183 g_warning ("%s: cannot initialize GValue with type '%s', %s",
185 g_type_name (g_type
),
186 g_type_value_table_peek (g_type
) ?
187 "this type is abstract with regards to GValue use, use a more specific (derived) type" :
188 "this type has no GTypeValueTable implementation");
194 * @src_value: An initialized #GValue structure.
195 * @dest_value: An initialized #GValue structure of the same type as @src_value.
197 * Copies the value of @src_value into @dest_value.
200 g_value_copy (const GValue
*src_value
,
203 g_return_if_fail (G_IS_VALUE (src_value
));
204 g_return_if_fail (G_IS_VALUE (dest_value
));
205 g_return_if_fail (g_value_type_compatible (G_VALUE_TYPE (src_value
), G_VALUE_TYPE (dest_value
)));
207 if (src_value
!= dest_value
)
209 GType dest_type
= G_VALUE_TYPE (dest_value
);
210 GTypeValueTable
*value_table
= g_type_value_table_peek (dest_type
);
212 /* make sure dest_value's value is free()d */
213 if (value_table
->value_free
)
214 value_table
->value_free (dest_value
);
217 value_meminit (dest_value
, dest_type
);
218 value_table
->value_copy (src_value
, dest_value
);
224 * @value: An initialized #GValue structure.
226 * Clears the current value in @value and resets it to the default value
227 * (as if the value had just been initialized).
229 * Returns: the #GValue structure that has been passed in
232 g_value_reset (GValue
*value
)
234 GTypeValueTable
*value_table
;
237 g_return_val_if_fail (G_IS_VALUE (value
), NULL
);
239 g_type
= G_VALUE_TYPE (value
);
240 value_table
= g_type_value_table_peek (g_type
);
242 /* make sure value's value is free()d */
243 if (value_table
->value_free
)
244 value_table
->value_free (value
);
247 value_meminit (value
, g_type
);
248 value_table
->value_init (value
);
255 * @value: An initialized #GValue structure.
257 * Clears the current value in @value and "unsets" the type,
258 * this releases all resources associated with this GValue.
259 * An unset value is the same as an uninitialized (zero-filled)
263 g_value_unset (GValue
*value
)
265 GTypeValueTable
*value_table
;
267 g_return_if_fail (G_IS_VALUE (value
));
269 value_table
= g_type_value_table_peek (G_VALUE_TYPE (value
));
271 if (value_table
->value_free
)
272 value_table
->value_free (value
);
273 memset (value
, 0, sizeof (*value
));
277 * g_value_fits_pointer:
278 * @value: An initialized #GValue structure.
280 * Determines if @value will fit inside the size of a pointer value.
281 * This is an internal function introduced mainly for C marshallers.
283 * Returns: %TRUE if @value will fit inside a pointer value.
286 g_value_fits_pointer (const GValue
*value
)
288 GTypeValueTable
*value_table
;
290 g_return_val_if_fail (G_IS_VALUE (value
), FALSE
);
292 value_table
= g_type_value_table_peek (G_VALUE_TYPE (value
));
294 return value_table
->value_peek_pointer
!= NULL
;
298 * g_value_peek_pointer:
299 * @value: An initialized #GValue structure
301 * Returns the value contents as pointer. This function asserts that
302 * g_value_fits_pointer() returned %TRUE for the passed in value.
303 * This is an internal function introduced mainly for C marshallers.
305 * Returns: (transfer none): the value contents as pointer
308 g_value_peek_pointer (const GValue
*value
)
310 GTypeValueTable
*value_table
;
312 g_return_val_if_fail (G_IS_VALUE (value
), NULL
);
314 value_table
= g_type_value_table_peek (G_VALUE_TYPE (value
));
315 if (!value_table
->value_peek_pointer
)
317 g_return_val_if_fail (g_value_fits_pointer (value
) == TRUE
, NULL
);
321 return value_table
->value_peek_pointer (value
);
325 * g_value_set_instance:
326 * @value: An initialized #GValue structure.
327 * @instance: (allow-none): the instance
329 * Sets @value from an instantiatable type via the
330 * value_table's collect_value() function.
333 g_value_set_instance (GValue
*value
,
337 GTypeValueTable
*value_table
;
341 g_return_if_fail (G_IS_VALUE (value
));
344 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance
));
345 g_return_if_fail (g_value_type_compatible (G_TYPE_FROM_INSTANCE (instance
), G_VALUE_TYPE (value
)));
348 g_type
= G_VALUE_TYPE (value
);
349 value_table
= g_type_value_table_peek (g_type
);
351 g_return_if_fail (strcmp (value_table
->collect_format
, "p") == 0);
353 memset (&cvalue
, 0, sizeof (cvalue
));
354 cvalue
.v_pointer
= instance
;
356 /* make sure value's value is free()d */
357 if (value_table
->value_free
)
358 value_table
->value_free (value
);
360 /* setup and collect */
361 value_meminit (value
, g_type
);
362 error_msg
= value_table
->collect_value (value
, 1, &cvalue
, 0);
365 g_warning ("%s: %s", G_STRLOC
, error_msg
);
368 /* we purposely leak the value here, it might not be
369 * in a sane state if an error condition occoured
371 value_meminit (value
, g_type
);
372 value_table
->value_init (value
);
377 * g_value_init_from_instance:
378 * @value: An uninitialized #GValue structure.
379 * @instance: the instance
381 * Initializes and sets @value from an instantiatable type via the
382 * value_table's collect_value() function.
384 * Note: The @value will be initialised with the exact type of
385 * @instance. If you wish to set the @value's type to a different GType
386 * (such as a parent class GType), you need to manually call
387 * g_value_init() and g_value_set_instance().
392 g_value_init_from_instance (GValue
*value
,
395 g_return_if_fail (value
!= NULL
&& G_VALUE_TYPE(value
) == 0);
397 if (G_IS_OBJECT (instance
))
400 * If G_IS_OBJECT() succeeds we know:
401 * * that instance is present and valid
402 * * that it is a GObject, and therefore we can directly
403 * use the collect implementation (g_object_ref) */
404 value_meminit (value
, G_TYPE_FROM_INSTANCE (instance
));
405 value
->data
[0].v_pointer
= g_object_ref (instance
);
410 GTypeValueTable
*value_table
;
414 g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance
));
416 g_type
= G_TYPE_FROM_INSTANCE (instance
);
417 value_table
= g_type_value_table_peek (g_type
);
418 g_return_if_fail (strcmp (value_table
->collect_format
, "p") == 0);
420 memset (&cvalue
, 0, sizeof (cvalue
));
421 cvalue
.v_pointer
= instance
;
423 /* setup and collect */
424 value_meminit (value
, g_type
);
425 value_table
->value_init (value
);
426 error_msg
= value_table
->collect_value (value
, 1, &cvalue
, 0);
429 g_warning ("%s: %s", G_STRLOC
, error_msg
);
432 /* we purposely leak the value here, it might not be
433 * in a sane state if an error condition occoured
435 value_meminit (value
, g_type
);
436 value_table
->value_init (value
);
441 static GValueTransform
442 transform_func_lookup (GType src_type
,
445 TransformEntry entry
;
447 entry
.src_type
= src_type
;
450 entry
.dest_type
= dest_type
;
455 e
= g_bsearch_array_lookup (transform_array
, &transform_bconfig
, &entry
);
458 /* need to check that there hasn't been a change in value handling */
459 if (g_type_value_table_peek (entry
.dest_type
) == g_type_value_table_peek (dest_type
) &&
460 g_type_value_table_peek (entry
.src_type
) == g_type_value_table_peek (src_type
))
463 entry
.dest_type
= g_type_parent (entry
.dest_type
);
465 while (entry
.dest_type
);
467 entry
.src_type
= g_type_parent (entry
.src_type
);
469 while (entry
.src_type
);
475 transform_entries_cmp (gconstpointer bsearch_node1
,
476 gconstpointer bsearch_node2
)
478 const TransformEntry
*e1
= bsearch_node1
;
479 const TransformEntry
*e2
= bsearch_node2
;
480 gint cmp
= G_BSEARCH_ARRAY_CMP (e1
->src_type
, e2
->src_type
);
485 return G_BSEARCH_ARRAY_CMP (e1
->dest_type
, e2
->dest_type
);
489 * g_value_register_transform_func: (skip)
490 * @src_type: Source type.
491 * @dest_type: Target type.
492 * @transform_func: a function which transforms values of type @src_type
493 * into value of type @dest_type
495 * Registers a value transformation function for use in g_value_transform().
496 * A previously registered transformation function for @src_type and @dest_type
500 g_value_register_transform_func (GType src_type
,
502 GValueTransform transform_func
)
504 TransformEntry entry
;
506 /* these checks won't pass for dynamic types.
507 * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (src_type));
508 * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (dest_type));
510 g_return_if_fail (transform_func
!= NULL
);
512 entry
.src_type
= src_type
;
513 entry
.dest_type
= dest_type
;
515 #if 0 /* let transform function replacement be a valid operation */
516 if (g_bsearch_array_lookup (transform_array
, &transform_bconfig
, &entry
))
517 g_warning ("reregistering value transformation function (%p) for '%s' to '%s'",
519 g_type_name (src_type
),
520 g_type_name (dest_type
));
523 entry
.func
= transform_func
;
524 transform_array
= g_bsearch_array_replace (transform_array
, &transform_bconfig
, &entry
);
528 * g_value_type_transformable:
529 * @src_type: Source type.
530 * @dest_type: Target type.
532 * Check whether g_value_transform() is able to transform values
533 * of type @src_type into values of type @dest_type. Note that for
534 * the types to be transformable, they must be compatible and a
535 * transform function must be registered.
537 * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
540 g_value_type_transformable (GType src_type
,
543 g_return_val_if_fail (G_TYPE_IS_VALUE (src_type
), FALSE
);
544 g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type
), FALSE
);
546 return (g_value_type_compatible (src_type
, dest_type
) ||
547 transform_func_lookup (src_type
, dest_type
) != NULL
);
551 * g_value_type_compatible:
552 * @src_type: source type to be copied.
553 * @dest_type: destination type for copying.
555 * Returns whether a #GValue of type @src_type can be copied into
556 * a #GValue of type @dest_type.
558 * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
561 g_value_type_compatible (GType src_type
,
564 g_return_val_if_fail (G_TYPE_IS_VALUE (src_type
), FALSE
);
565 g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type
), FALSE
);
567 return (g_type_is_a (src_type
, dest_type
) &&
568 g_type_value_table_peek (dest_type
) == g_type_value_table_peek (src_type
));
573 * @src_value: Source value.
574 * @dest_value: Target value.
576 * Tries to cast the contents of @src_value into a type appropriate
577 * to store in @dest_value, e.g. to transform a %G_TYPE_INT value
578 * into a %G_TYPE_FLOAT value. Performing transformations between
579 * value types might incur precision lossage. Especially
580 * transformations into strings might reveal seemingly arbitrary
581 * results and shouldn't be relied upon for production code (such
582 * as rcfile value or object property serialization).
584 * Returns: Whether a transformation rule was found and could be applied.
585 * Upon failing transformations, @dest_value is left untouched.
588 g_value_transform (const GValue
*src_value
,
593 g_return_val_if_fail (G_IS_VALUE (src_value
), FALSE
);
594 g_return_val_if_fail (G_IS_VALUE (dest_value
), FALSE
);
596 dest_type
= G_VALUE_TYPE (dest_value
);
597 if (g_value_type_compatible (G_VALUE_TYPE (src_value
), dest_type
))
599 g_value_copy (src_value
, dest_value
);
605 GValueTransform transform
= transform_func_lookup (G_VALUE_TYPE (src_value
), dest_type
);
609 g_value_unset (dest_value
);
611 /* setup and transform */
612 value_meminit (dest_value
, dest_type
);
613 transform (src_value
, dest_value
);