gobject/gvalue.c

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 1997-1999, 2000-2001 Tim Janik and Red Hat, Inc.
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  */
  19 /**
  20  * SECTION:generic_values
  21  * @Short_description: A polymorphic type that can hold values of any other type
  22  * @See_also: The fundamental types which all support #GValue operations and
  23  * thus can be used as a type initializer for g_value_init() are defined by
  24  * a separate interface.  See the <link
  25  * linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values
  26  * API</link> for details.
  27  * @Title: Generic values
  28  *
  29  * The #GValue structure is basically a variable container that consists
  30  * of a type identifier and a specific value of that type.
  31  * The type identifier within a #GValue structure always determines the
  32  * type of the associated value.
  33  * To create a undefined #GValue structure, simply create a zero-filled
  34  * #GValue structure. To initialize the #GValue, use the g_value_init()
  35  * function. A #GValue cannot be used until it is initialized.
  36  * The basic type operations (such as freeing and copying) are determined
  37  * by the #GTypeValueTable associated with the type ID stored in the #GValue.
  38  * Other #GValue operations (such as converting values between types) are
  39  * provided by this interface.
  40  */
  41
  42 /*
  43  * FIXME: MT-safety
  44  */
  45
  46 #include <string.h>
  47
  48 #include "gvalue.h"
  49 #include "gvaluecollector.h"
  50 #include "gbsearcharray.h"
  51 #include "gobjectalias.h"
  52
  53
  54 /* --- typedefs & structures --- */
  55 typedef struct {
  56   GType src_type;
  57   GType dest_type;
  58   GValueTransform func;
  59 } TransformEntry;
  60
  61
  62 /* --- prototypes --- */
  63 static gint     transform_entries_cmp   (gconstpointer bsearch_node1,
  64                                          gconstpointer bsearch_node2);
  65
  66
  67 /* --- variables --- */
  68 static GBSearchArray *transform_array = NULL;
  69 static GBSearchConfig transform_bconfig = {
  70   sizeof (TransformEntry),
  71   transform_entries_cmp,
  72   0,
  73 };
  74
  75
  76 /* --- functions --- */
  77 void
  78 g_value_c_init (void)
  79 {
  80   transform_array = g_bsearch_array_create (&transform_bconfig);
  81 }
  82
  83 static inline void              /* keep this function in sync with gvaluecollector.h and gboxed.c */
  84 value_meminit (GValue *value,
  85                GType   value_type)
  86 {
  87   value->g_type = value_type;
  88   memset (value->data, 0, sizeof (value->data));
  89 }
  90
  91 /**
  92  * g_value_init:
  93  * @value: A zero-filled (uninitialized) #GValue structure.
  94  * @g_type: Type the #GValue should hold values of.
  95  *
  96  * Initializes @value with the default value of @type.
  97  *
  98  * Returns: the #GValue structure that has been passed in
  99  */
 100 GValue*
 101 g_value_init (GValue *value,
 102               GType   g_type)
 103 {
 104   /* g_return_val_if_fail (G_TYPE_IS_VALUE (g_type), NULL);     be more elaborate below */
 105   g_return_val_if_fail (value != NULL, NULL);
 106   /* g_return_val_if_fail (G_VALUE_TYPE (value) == 0, NULL);    be more elaborate below */
 107
 108   if (G_TYPE_IS_VALUE (g_type) && G_VALUE_TYPE (value) == 0)
 109     {
 110       GTypeValueTable *value_table = g_type_value_table_peek (g_type);
 111
 112       /* setup and init */
 113       value_meminit (value, g_type);
 114       value_table->value_init (value);
 115     }
 116   else if (G_VALUE_TYPE (value))
 117     g_warning ("%s: cannot initialize GValue with type `%s', the value has already been initialized as `%s'",
 118                G_STRLOC,
 119                g_type_name (g_type),
 120                g_type_name (G_VALUE_TYPE (value)));
 121   else /* !G_TYPE_IS_VALUE (g_type) */
 122     g_warning ("%s: cannot initialize GValue with type `%s', %s",
 123                G_STRLOC,
 124                g_type_name (g_type),
 125                g_type_value_table_peek (g_type) ?
 126                "this type is abstract with regards to GValue use, use a more specific (derived) type" :
 127                "this type has no GTypeValueTable implementation");
 128   return value;
 129 }
 130
 131 /**
 132  * g_value_copy:
 133  * @src_value: An initialized #GValue structure.
 134  * @dest_value: An initialized #GValue structure of the same type as @src_value.
 135  *
 136  * Copies the value of @src_value into @dest_value.
 137  */
 138 void
 139 g_value_copy (const GValue *src_value,
 140               GValue       *dest_value)
 141 {
 142   g_return_if_fail (G_IS_VALUE (src_value));
 143   g_return_if_fail (G_IS_VALUE (dest_value));
 144   g_return_if_fail (g_value_type_compatible (G_VALUE_TYPE (src_value), G_VALUE_TYPE (dest_value)));
 145
 146   if (src_value != dest_value)
 147     {
 148       GType dest_type = G_VALUE_TYPE (dest_value);
 149       GTypeValueTable *value_table = g_type_value_table_peek (dest_type);
 150
 151       /* make sure dest_value's value is free()d */
 152       if (value_table->value_free)
 153         value_table->value_free (dest_value);
 154
 155       /* setup and copy */
 156       value_meminit (dest_value, dest_type);
 157       value_table->value_copy (src_value, dest_value);
 158     }
 159 }
 160
 161 /**
 162  * g_value_reset:
 163  * @value: An initialized #GValue structure.
 164  *
 165  * Clears the current value in @value and resets it to the default value
 166  * (as if the value had just been initialized).
 167  *
 168  * Returns: the #GValue structure that has been passed in
 169  */
 170 GValue*
 171 g_value_reset (GValue *value)
 172 {
 173   GTypeValueTable *value_table;
 174   GType g_type;
 175
 176   g_return_val_if_fail (G_IS_VALUE (value), NULL);
 177
 178   g_type = G_VALUE_TYPE (value);
 179   value_table = g_type_value_table_peek (g_type);
 180
 181   /* make sure value's value is free()d */
 182   if (value_table->value_free)
 183     value_table->value_free (value);
 184
 185   /* setup and init */
 186   value_meminit (value, g_type);
 187   value_table->value_init (value);
 188
 189   return value;
 190 }
 191
 192 /**
 193  * g_value_unset:
 194  * @value: An initialized #GValue structure.
 195  *
 196  * Clears the current value in @value and "unsets" the type,
 197  * this releases all resources associated with this GValue.
 198  * An unset value is the same as an uninitialized (zero-filled)
 199  * #GValue structure.
 200  */
 201 void
 202 g_value_unset (GValue *value)
 203 {
 204   GTypeValueTable *value_table;
 205
 206   g_return_if_fail (G_IS_VALUE (value));
 207
 208   value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
 209
 210   if (value_table->value_free)
 211     value_table->value_free (value);
 212   memset (value, 0, sizeof (*value));
 213 }
 214
 215 /**
 216  * g_value_fits_pointer:
 217  * @value: An initialized #GValue structure.
 218  *
 219  * Determines if @value will fit inside the size of a pointer value.
 220  * This is an internal function introduced mainly for C marshallers.
 221  *
 222  * Returns: %TRUE if @value will fit inside a pointer value.
 223  */
 224 gboolean
 225 g_value_fits_pointer (const GValue *value)
 226 {
 227   GTypeValueTable *value_table;
 228
 229   g_return_val_if_fail (G_IS_VALUE (value), FALSE);
 230
 231   value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
 232
 233   return value_table->value_peek_pointer != NULL;
 234 }
 235
 236 /**
 237  * g_value_peek_pointer:
 238  * @value: An initialized #GValue structure.
 239  *
 240  * Return the value contents as pointer. This function asserts that
 241  * g_value_fits_pointer() returned %TRUE for the passed in value.
 242  * This is an internal function introduced mainly for C marshallers.
 243  *
 244  * Returns: %TRUE if @value will fit inside a pointer value.
 245  */
 246 gpointer
 247 g_value_peek_pointer (const GValue *value)
 248 {
 249   GTypeValueTable *value_table;
 250
 251   g_return_val_if_fail (G_IS_VALUE (value), NULL);
 252
 253   value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
 254   if (!value_table->value_peek_pointer)
 255     {
 256       g_return_val_if_fail (g_value_fits_pointer (value) == TRUE, NULL);
 257       return NULL;
 258     }
 259
 260   return value_table->value_peek_pointer (value);
 261 }
 262
 263 /**
 264  * g_value_set_instance:
 265  * @value: An initialized #GValue structure.
 266  * @instance: the instance
 267  *
 268  * Sets @value from an instantiatable type via the
 269  * value_table's collect_value() function.
 270  */
 271 void
 272 g_value_set_instance (GValue  *value,
 273                       gpointer instance)
 274 {
 275   GType g_type;
 276   GTypeValueTable *value_table;
 277   GTypeCValue cvalue;
 278   gchar *error_msg;
 279
 280   g_return_if_fail (G_IS_VALUE (value));
 281   if (instance)
 282     {
 283       g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
 284       g_return_if_fail (g_value_type_compatible (G_TYPE_FROM_INSTANCE (instance), G_VALUE_TYPE (value)));
 285     }
 286
 287   g_type = G_VALUE_TYPE (value);
 288   value_table = g_type_value_table_peek (g_type);
 289
 290   g_return_if_fail (strcmp (value_table->collect_format, "p") == 0);
 291
 292   memset (&cvalue, 0, sizeof (cvalue));
 293   cvalue.v_pointer = instance;
 294
 295   /* make sure value's value is free()d */
 296   if (value_table->value_free)
 297     value_table->value_free (value);
 298
 299   /* setup and collect */
 300   value_meminit (value, g_type);
 301   error_msg = value_table->collect_value (value, 1, &cvalue, 0);
 302   if (error_msg)
 303     {
 304       g_warning ("%s: %s", G_STRLOC, error_msg);
 305       g_free (error_msg);
 306
 307       /* we purposely leak the value here, it might not be
 308        * in a sane state if an error condition occoured
 309        */
 310       value_meminit (value, g_type);
 311       value_table->value_init (value);
 312     }
 313 }
 314
 315 static GValueTransform
 316 transform_func_lookup (GType src_type,
 317                        GType dest_type)
 318 {
 319   TransformEntry entry;
 320
 321   entry.src_type = src_type;
 322   do
 323     {
 324       entry.dest_type = dest_type;
 325       do
 326         {
 327           TransformEntry *e;
 328
 329           e = g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry);
 330           if (e)
 331             {
 332               /* need to check that there hasn't been a change in value handling */
 333               if (g_type_value_table_peek (entry.dest_type) == g_type_value_table_peek (dest_type) &&
 334                   g_type_value_table_peek (entry.src_type) == g_type_value_table_peek (src_type))
 335                 return e->func;
 336             }
 337           entry.dest_type = g_type_parent (entry.dest_type);
 338         }
 339       while (entry.dest_type);
 340
 341       entry.src_type = g_type_parent (entry.src_type);
 342     }
 343   while (entry.src_type);
 344
 345   return NULL;
 346 }
 347
 348 static gint
 349 transform_entries_cmp (gconstpointer bsearch_node1,
 350                        gconstpointer bsearch_node2)
 351 {
 352   const TransformEntry *e1 = bsearch_node1;
 353   const TransformEntry *e2 = bsearch_node2;
 354   gint cmp = G_BSEARCH_ARRAY_CMP (e1->src_type, e2->src_type);
 355
 356   if (cmp)
 357     return cmp;
 358   else
 359     return G_BSEARCH_ARRAY_CMP (e1->dest_type, e2->dest_type);
 360 }
 361
 362 /**
 363  * g_value_register_transform_func:
 364  * @src_type: Source type.
 365  * @dest_type: Target type.
 366  * @transform_func: a function which transforms values of type @src_type
 367  *  into value of type @dest_type
 368  *
 369  * Registers a value transformation function for use in g_value_transform().
 370  * A previously registered transformation function for @src_type and @dest_type
 371  * will be replaced.
 372  */
 373 void
 374 g_value_register_transform_func (GType           src_type,
 375                                  GType           dest_type,
 376                                  GValueTransform transform_func)
 377 {
 378   TransformEntry entry;
 379
 380   /* these checks won't pass for dynamic types.
 381    * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (src_type));
 382    * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (dest_type));
 383    */
 384   g_return_if_fail (transform_func != NULL);
 385
 386   entry.src_type = src_type;
 387   entry.dest_type = dest_type;
 388
 389 #if 0 /* let transform function replacement be a valid operation */
 390   if (g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry))
 391     g_warning ("reregistering value transformation function (%p) for `%s' to `%s'",
 392                transform_func,
 393                g_type_name (src_type),
 394                g_type_name (dest_type));
 395 #endif
 396
 397   entry.func = transform_func;
 398   transform_array = g_bsearch_array_replace (transform_array, &transform_bconfig, &entry);
 399 }
 400
 401 /**
 402  * g_value_type_transformable:
 403  * @src_type: Source type.
 404  * @dest_type: Target type.
 405  *
 406  * Check whether g_value_transform() is able to transform values
 407  * of type @src_type into values of type @dest_type.
 408  *
 409  * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
 410  */
 411 gboolean
 412 g_value_type_transformable (GType src_type,
 413                             GType dest_type)
 414 {
 415   g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
 416   g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
 417
 418   return (g_value_type_compatible (src_type, dest_type) ||
 419           transform_func_lookup (src_type, dest_type) != NULL);
 420 }
 421
 422 /**
 423  * g_value_type_compatible:
 424  * @src_type: source type to be copied.
 425  * @dest_type: destination type for copying.
 426  *
 427  * Returns whether a #GValue of type @src_type can be copied into
 428  * a #GValue of type @dest_type.
 429  *
 430  * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
 431  */
 432 gboolean
 433 g_value_type_compatible (GType src_type,
 434                          GType dest_type)
 435 {
 436   g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
 437   g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
 438
 439   return (g_type_is_a (src_type, dest_type) &&
 440           g_type_value_table_peek (dest_type) == g_type_value_table_peek (src_type));
 441 }
 442
 443 /**
 444  * g_value_transform:
 445  * @src_value: Source value.
 446  * @dest_value: Target value.
 447  *
 448  * Tries to cast the contents of @src_value into a type appropriate
 449  * to store in @dest_value, e.g. to transform a %G_TYPE_INT value
 450  * into a %G_TYPE_FLOAT value. Performing transformations between
 451  * value types might incur precision lossage. Especially
 452  * transformations into strings might reveal seemingly arbitrary
 453  * results and shouldn't be relied upon for production code (such
 454  * as rcfile value or object property serialization).
 455  *
 456  * Returns: Whether a transformation rule was found and could be applied.
 457  *  Upon failing transformations, @dest_value is left untouched.
 458  */
 459 gboolean
 460 g_value_transform (const GValue *src_value,
 461                    GValue       *dest_value)
 462 {
 463   GType dest_type;
 464
 465   g_return_val_if_fail (G_IS_VALUE (src_value), FALSE);
 466   g_return_val_if_fail (G_IS_VALUE (dest_value), FALSE);
 467
 468   dest_type = G_VALUE_TYPE (dest_value);
 469   if (g_value_type_compatible (G_VALUE_TYPE (src_value), dest_type))
 470     {
 471       g_value_copy (src_value, dest_value);
 472
 473       return TRUE;
 474     }
 475   else
 476     {
 477       GValueTransform transform = transform_func_lookup (G_VALUE_TYPE (src_value), dest_type);
 478
 479       if (transform)
 480         {
 481           g_value_unset (dest_value);
 482
 483           /* setup and transform */
 484           value_meminit (dest_value, dest_type);
 485           transform (src_value, dest_value);
 486
 487           return TRUE;
 488         }
 489     }
 490   return FALSE;
 491 }
 492
 493 #define __G_VALUE_C__
 494 #include "gobjectaliasdef.c"