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