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