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