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, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * FIXME: MT-safety
  20  */
  21
  22 #include "config.h"
  23
  24 #include <string.h>
  25
  26 #include "gvalue.h"
  27 #include "gvaluecollector.h"
  28 #include "gbsearcharray.h"
  29 #include "gtype-private.h"
  30
  31
  32 /**
  33  * SECTION:generic_values
  34  * @short_description: A polymorphic type that can hold values of any
  35  *     other type
  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]
  40  *     for details
  41  * @title: Generic values
  42  *
  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.
  54  *
  55  * The code in the example program below demonstrates #GValue's
  56  * features.
  57  *
  58  * |[<!-- language="C" -->
  59  * #include <glib-object.h>
  60  *
  61  * static void
  62  * int2string (const GValue *src_value,
  63  *             GValue       *dest_value)
  64  * {
  65  *   if (g_value_get_int (src_value) == 42)
  66  *     g_value_set_static_string (dest_value, "An important number");
  67  *   else
  68  *     g_value_set_static_string (dest_value, "What's that?");
  69  * }
  70  *
  71  * int
  72  * main (int   argc,
  73  *       char *argv[])
  74  * {
  75  *   // GValues must be initialized
  76  *   GValue a = G_VALUE_INIT;
  77  *   GValue b = G_VALUE_INIT;
  78  *   const gchar *message;
  79  *
  80  *   // The GValue starts empty
  81  *   g_assert (!G_VALUE_HOLDS_STRING (&a));
  82  *
  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));
  88  *
  89  *   // Reset it to its pristine state
  90  *   g_value_unset (&a);
  91  *
  92  *   // It can then be reused for another type
  93  *   g_value_init (&a, G_TYPE_INT);
  94  *   g_value_set_int (&a, 42);
  95  *
  96  *   // Attempt to transform it into a GValue of type STRING
  97  *   g_value_init (&b, G_TYPE_STRING);
  98  *
  99  *   // An INT is transformable to a STRING
 100  *   g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
 101  *
 102  *   g_value_transform (&a, &b);
 103  *   g_printf ("%s\n", g_value_get_string (&b));
 104  *
 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));
 109  *   return 0;
 110  * }
 111  * ]|
 112  */
 113
 114
 115 /* --- typedefs & structures --- */
 116 typedef struct {
 117   GType src_type;
 118   GType dest_type;
 119   GValueTransform func;
 120 } TransformEntry;
 121
 122
 123 /* --- prototypes --- */
 124 static gint     transform_entries_cmp   (gconstpointer bsearch_node1,
 125                                          gconstpointer bsearch_node2);
 126
 127
 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,
 134 };
 135
 136
 137 /* --- functions --- */
 138 void
 139 _g_value_c_init (void)
 140 {
 141   transform_array = g_bsearch_array_create (&transform_bconfig);
 142 }
 143
 144 static inline void              /* keep this function in sync with gvaluecollector.h and gboxed.c */
 145 value_meminit (GValue *value,
 146                GType   value_type)
 147 {
 148   value->g_type = value_type;
 149   memset (value->data, 0, sizeof (value->data));
 150 }
 151
 152 /**
 153  * g_value_init:
 154  * @value: A zero-filled (uninitialized) #GValue structure.
 155  * @g_type: Type the #GValue should hold values of.
 156  *
 157  * Initializes @value with the default value of @type.
 158  *
 159  * Returns: (transfer none): the #GValue structure that has been passed in
 160  */
 161 GValue*
 162 g_value_init (GValue *value,
 163               GType   g_type)
 164 {
 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 */
 168
 169   if (G_TYPE_IS_VALUE (g_type) && G_VALUE_TYPE (value) == 0)
 170     {
 171       GTypeValueTable *value_table = g_type_value_table_peek (g_type);
 172
 173       /* setup and init */
 174       value_meminit (value, g_type);
 175       value_table->value_init (value);
 176     }
 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'",
 179                G_STRLOC,
 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",
 184                G_STRLOC,
 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");
 189   return value;
 190 }
 191
 192 /**
 193  * g_value_copy:
 194  * @src_value: An initialized #GValue structure.
 195  * @dest_value: An initialized #GValue structure of the same type as @src_value.
 196  *
 197  * Copies the value of @src_value into @dest_value.
 198  */
 199 void
 200 g_value_copy (const GValue *src_value,
 201               GValue       *dest_value)
 202 {
 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)));
 206
 207   if (src_value != dest_value)
 208     {
 209       GType dest_type = G_VALUE_TYPE (dest_value);
 210       GTypeValueTable *value_table = g_type_value_table_peek (dest_type);
 211
 212       /* make sure dest_value's value is free()d */
 213       if (value_table->value_free)
 214         value_table->value_free (dest_value);
 215
 216       /* setup and copy */
 217       value_meminit (dest_value, dest_type);
 218       value_table->value_copy (src_value, dest_value);
 219     }
 220 }
 221
 222 /**
 223  * g_value_reset:
 224  * @value: An initialized #GValue structure.
 225  *
 226  * Clears the current value in @value and resets it to the default value
 227  * (as if the value had just been initialized).
 228  *
 229  * Returns: the #GValue structure that has been passed in
 230  */
 231 GValue*
 232 g_value_reset (GValue *value)
 233 {
 234   GTypeValueTable *value_table;
 235   GType g_type;
 236
 237   g_return_val_if_fail (G_IS_VALUE (value), NULL);
 238
 239   g_type = G_VALUE_TYPE (value);
 240   value_table = g_type_value_table_peek (g_type);
 241
 242   /* make sure value's value is free()d */
 243   if (value_table->value_free)
 244     value_table->value_free (value);
 245
 246   /* setup and init */
 247   value_meminit (value, g_type);
 248   value_table->value_init (value);
 249
 250   return value;
 251 }
 252
 253 /**
 254  * g_value_unset:
 255  * @value: An initialized #GValue structure.
 256  *
 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)
 260  * #GValue structure.
 261  */
 262 void
 263 g_value_unset (GValue *value)
 264 {
 265   GTypeValueTable *value_table;
 266
 267   g_return_if_fail (G_IS_VALUE (value));
 268
 269   value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
 270
 271   if (value_table->value_free)
 272     value_table->value_free (value);
 273   memset (value, 0, sizeof (*value));
 274 }
 275
 276 /**
 277  * g_value_fits_pointer:
 278  * @value: An initialized #GValue structure.
 279  *
 280  * Determines if @value will fit inside the size of a pointer value.
 281  * This is an internal function introduced mainly for C marshallers.
 282  *
 283  * Returns: %TRUE if @value will fit inside a pointer value.
 284  */
 285 gboolean
 286 g_value_fits_pointer (const GValue *value)
 287 {
 288   GTypeValueTable *value_table;
 289
 290   g_return_val_if_fail (G_IS_VALUE (value), FALSE);
 291
 292   value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
 293
 294   return value_table->value_peek_pointer != NULL;
 295 }
 296
 297 /**
 298  * g_value_peek_pointer:
 299  * @value: An initialized #GValue structure.
 300  *
 301  * Returns: (transfer none): the value contents as pointer. This
 302  * function asserts that g_value_fits_pointer() returned %TRUE for the
 303  * passed in value.  This is an internal function introduced mainly
 304  * for C marshallers.
 305  */
 306 gpointer
 307 g_value_peek_pointer (const GValue *value)
 308 {
 309   GTypeValueTable *value_table;
 310
 311   g_return_val_if_fail (G_IS_VALUE (value), NULL);
 312
 313   value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
 314   if (!value_table->value_peek_pointer)
 315     {
 316       g_return_val_if_fail (g_value_fits_pointer (value) == TRUE, NULL);
 317       return NULL;
 318     }
 319
 320   return value_table->value_peek_pointer (value);
 321 }
 322
 323 /**
 324  * g_value_set_instance:
 325  * @value: An initialized #GValue structure.
 326  * @instance: (allow-none): the instance
 327  *
 328  * Sets @value from an instantiatable type via the
 329  * value_table's collect_value() function.
 330  */
 331 void
 332 g_value_set_instance (GValue  *value,
 333                       gpointer instance)
 334 {
 335   GType g_type;
 336   GTypeValueTable *value_table;
 337   GTypeCValue cvalue;
 338   gchar *error_msg;
 339
 340   g_return_if_fail (G_IS_VALUE (value));
 341   if (instance)
 342     {
 343       g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
 344       g_return_if_fail (g_value_type_compatible (G_TYPE_FROM_INSTANCE (instance), G_VALUE_TYPE (value)));
 345     }
 346
 347   g_type = G_VALUE_TYPE (value);
 348   value_table = g_type_value_table_peek (g_type);
 349
 350   g_return_if_fail (strcmp (value_table->collect_format, "p") == 0);
 351
 352   memset (&cvalue, 0, sizeof (cvalue));
 353   cvalue.v_pointer = instance;
 354
 355   /* make sure value's value is free()d */
 356   if (value_table->value_free)
 357     value_table->value_free (value);
 358
 359   /* setup and collect */
 360   value_meminit (value, g_type);
 361   error_msg = value_table->collect_value (value, 1, &cvalue, 0);
 362   if (error_msg)
 363     {
 364       g_warning ("%s: %s", G_STRLOC, error_msg);
 365       g_free (error_msg);
 366
 367       /* we purposely leak the value here, it might not be
 368        * in a sane state if an error condition occoured
 369        */
 370       value_meminit (value, g_type);
 371       value_table->value_init (value);
 372     }
 373 }
 374
 375 static GValueTransform
 376 transform_func_lookup (GType src_type,
 377                        GType dest_type)
 378 {
 379   TransformEntry entry;
 380
 381   entry.src_type = src_type;
 382   do
 383     {
 384       entry.dest_type = dest_type;
 385       do
 386         {
 387           TransformEntry *e;
 388
 389           e = g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry);
 390           if (e)
 391             {
 392               /* need to check that there hasn't been a change in value handling */
 393               if (g_type_value_table_peek (entry.dest_type) == g_type_value_table_peek (dest_type) &&
 394                   g_type_value_table_peek (entry.src_type) == g_type_value_table_peek (src_type))
 395                 return e->func;
 396             }
 397           entry.dest_type = g_type_parent (entry.dest_type);
 398         }
 399       while (entry.dest_type);
 400
 401       entry.src_type = g_type_parent (entry.src_type);
 402     }
 403   while (entry.src_type);
 404
 405   return NULL;
 406 }
 407
 408 static gint
 409 transform_entries_cmp (gconstpointer bsearch_node1,
 410                        gconstpointer bsearch_node2)
 411 {
 412   const TransformEntry *e1 = bsearch_node1;
 413   const TransformEntry *e2 = bsearch_node2;
 414   gint cmp = G_BSEARCH_ARRAY_CMP (e1->src_type, e2->src_type);
 415
 416   if (cmp)
 417     return cmp;
 418   else
 419     return G_BSEARCH_ARRAY_CMP (e1->dest_type, e2->dest_type);
 420 }
 421
 422 /**
 423  * g_value_register_transform_func: (skip)
 424  * @src_type: Source type.
 425  * @dest_type: Target type.
 426  * @transform_func: a function which transforms values of type @src_type
 427  *  into value of type @dest_type
 428  *
 429  * Registers a value transformation function for use in g_value_transform().
 430  * A previously registered transformation function for @src_type and @dest_type
 431  * will be replaced.
 432  */
 433 void
 434 g_value_register_transform_func (GType           src_type,
 435                                  GType           dest_type,
 436                                  GValueTransform transform_func)
 437 {
 438   TransformEntry entry;
 439
 440   /* these checks won't pass for dynamic types.
 441    * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (src_type));
 442    * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (dest_type));
 443    */
 444   g_return_if_fail (transform_func != NULL);
 445
 446   entry.src_type = src_type;
 447   entry.dest_type = dest_type;
 448
 449 #if 0 /* let transform function replacement be a valid operation */
 450   if (g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry))
 451     g_warning ("reregistering value transformation function (%p) for '%s' to '%s'",
 452                transform_func,
 453                g_type_name (src_type),
 454                g_type_name (dest_type));
 455 #endif
 456
 457   entry.func = transform_func;
 458   transform_array = g_bsearch_array_replace (transform_array, &transform_bconfig, &entry);
 459 }
 460
 461 /**
 462  * g_value_type_transformable:
 463  * @src_type: Source type.
 464  * @dest_type: Target type.
 465  *
 466  * Check whether g_value_transform() is able to transform values
 467  * of type @src_type into values of type @dest_type. Note that for
 468  * the types to be transformable, they must be compatible and a
 469  * transform function must be registered.
 470  *
 471  * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
 472  */
 473 gboolean
 474 g_value_type_transformable (GType src_type,
 475                             GType dest_type)
 476 {
 477   g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
 478   g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
 479
 480   return (g_value_type_compatible (src_type, dest_type) ||
 481           transform_func_lookup (src_type, dest_type) != NULL);
 482 }
 483
 484 /**
 485  * g_value_type_compatible:
 486  * @src_type: source type to be copied.
 487  * @dest_type: destination type for copying.
 488  *
 489  * Returns whether a #GValue of type @src_type can be copied into
 490  * a #GValue of type @dest_type.
 491  *
 492  * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
 493  */
 494 gboolean
 495 g_value_type_compatible (GType src_type,
 496                          GType dest_type)
 497 {
 498   g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
 499   g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
 500
 501   return (g_type_is_a (src_type, dest_type) &&
 502           g_type_value_table_peek (dest_type) == g_type_value_table_peek (src_type));
 503 }
 504
 505 /**
 506  * g_value_transform:
 507  * @src_value: Source value.
 508  * @dest_value: Target value.
 509  *
 510  * Tries to cast the contents of @src_value into a type appropriate
 511  * to store in @dest_value, e.g. to transform a %G_TYPE_INT value
 512  * into a %G_TYPE_FLOAT value. Performing transformations between
 513  * value types might incur precision lossage. Especially
 514  * transformations into strings might reveal seemingly arbitrary
 515  * results and shouldn't be relied upon for production code (such
 516  * as rcfile value or object property serialization).
 517  *
 518  * Returns: Whether a transformation rule was found and could be applied.
 519  *  Upon failing transformations, @dest_value is left untouched.
 520  */
 521 gboolean
 522 g_value_transform (const GValue *src_value,
 523                    GValue       *dest_value)
 524 {
 525   GType dest_type;
 526
 527   g_return_val_if_fail (G_IS_VALUE (src_value), FALSE);
 528   g_return_val_if_fail (G_IS_VALUE (dest_value), FALSE);
 529
 530   dest_type = G_VALUE_TYPE (dest_value);
 531   if (g_value_type_compatible (G_VALUE_TYPE (src_value), dest_type))
 532     {
 533       g_value_copy (src_value, dest_value);
 534
 535       return TRUE;
 536     }
 537   else
 538     {
 539       GValueTransform transform = transform_func_lookup (G_VALUE_TYPE (src_value), dest_type);
 540
 541       if (transform)
 542         {
 543           g_value_unset (dest_value);
 544
 545           /* setup and transform */
 546           value_meminit (dest_value, dest_type);
 547           transform (src_value, dest_value);
 548
 549           return TRUE;
 550         }
 551     }
 552   return FALSE;
 553 }