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 the value contents as pointer. This function asserts that
 302  * g_value_fits_pointer() returned %TRUE for the passed in value.
 303  * This is an internal function introduced mainly for C marshallers.
 304  *
 305  * Returns: (transfer none): the value contents as pointer
 306  */
 307 gpointer
 308 g_value_peek_pointer (const GValue *value)
 309 {
 310   GTypeValueTable *value_table;
 311
 312   g_return_val_if_fail (G_IS_VALUE (value), NULL);
 313
 314   value_table = g_type_value_table_peek (G_VALUE_TYPE (value));
 315   if (!value_table->value_peek_pointer)
 316     {
 317       g_return_val_if_fail (g_value_fits_pointer (value) == TRUE, NULL);
 318       return NULL;
 319     }
 320
 321   return value_table->value_peek_pointer (value);
 322 }
 323
 324 /**
 325  * g_value_set_instance:
 326  * @value: An initialized #GValue structure.
 327  * @instance: (allow-none): the instance
 328  *
 329  * Sets @value from an instantiatable type via the
 330  * value_table's collect_value() function.
 331  */
 332 void
 333 g_value_set_instance (GValue  *value,
 334                       gpointer instance)
 335 {
 336   GType g_type;
 337   GTypeValueTable *value_table;
 338   GTypeCValue cvalue;
 339   gchar *error_msg;
 340
 341   g_return_if_fail (G_IS_VALUE (value));
 342   if (instance)
 343     {
 344       g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
 345       g_return_if_fail (g_value_type_compatible (G_TYPE_FROM_INSTANCE (instance), G_VALUE_TYPE (value)));
 346     }
 347
 348   g_type = G_VALUE_TYPE (value);
 349   value_table = g_type_value_table_peek (g_type);
 350
 351   g_return_if_fail (strcmp (value_table->collect_format, "p") == 0);
 352
 353   memset (&cvalue, 0, sizeof (cvalue));
 354   cvalue.v_pointer = instance;
 355
 356   /* make sure value's value is free()d */
 357   if (value_table->value_free)
 358     value_table->value_free (value);
 359
 360   /* setup and collect */
 361   value_meminit (value, g_type);
 362   error_msg = value_table->collect_value (value, 1, &cvalue, 0);
 363   if (error_msg)
 364     {
 365       g_warning ("%s: %s", G_STRLOC, error_msg);
 366       g_free (error_msg);
 367
 368       /* we purposely leak the value here, it might not be
 369        * in a sane state if an error condition occoured
 370        */
 371       value_meminit (value, g_type);
 372       value_table->value_init (value);
 373     }
 374 }
 375
 376 /**
 377  * g_value_init_from_instance:
 378  * @value: An uninitialized #GValue structure.
 379  * @instance: the instance
 380  *
 381  * Initializes and sets @value from an instantiatable type via the
 382  * value_table's collect_value() function.
 383  *
 384  * Note: The @value will be initialised with the exact type of
 385  * @instance.  If you wish to set the @value's type to a different GType
 386  * (such as a parent class GType), you need to manually call
 387  * g_value_init() and g_value_set_instance().
 388  *
 389  * Since: 2.42
 390  */
 391 void
 392 g_value_init_from_instance (GValue  *value,
 393                             gpointer instance)
 394 {
 395   g_return_if_fail (value != NULL && G_VALUE_TYPE(value) == 0);
 396
 397   if (G_IS_OBJECT (instance))
 398     {
 399       /* Fast-path.
 400        * If G_IS_OBJECT() succeeds we know:
 401        * * that instance is present and valid
 402        * * that it is a GObject, and therefore we can directly
 403        *   use the collect implementation (g_object_ref) */
 404       value_meminit (value, G_TYPE_FROM_INSTANCE (instance));
 405       value->data[0].v_pointer = g_object_ref (instance);
 406     }
 407   else
 408     {
 409       GType g_type;
 410       GTypeValueTable *value_table;
 411       GTypeCValue cvalue;
 412       gchar *error_msg;
 413
 414       g_return_if_fail (G_TYPE_CHECK_INSTANCE (instance));
 415
 416       g_type = G_TYPE_FROM_INSTANCE (instance);
 417       value_table = g_type_value_table_peek (g_type);
 418       g_return_if_fail (strcmp (value_table->collect_format, "p") == 0);
 419
 420       memset (&cvalue, 0, sizeof (cvalue));
 421       cvalue.v_pointer = instance;
 422
 423       /* setup and collect */
 424       value_meminit (value, g_type);
 425       value_table->value_init (value);
 426       error_msg = value_table->collect_value (value, 1, &cvalue, 0);
 427       if (error_msg)
 428         {
 429           g_warning ("%s: %s", G_STRLOC, error_msg);
 430           g_free (error_msg);
 431
 432           /* we purposely leak the value here, it might not be
 433            * in a sane state if an error condition occoured
 434            */
 435           value_meminit (value, g_type);
 436           value_table->value_init (value);
 437         }
 438     }
 439 }
 440
 441 static GValueTransform
 442 transform_func_lookup (GType src_type,
 443                        GType dest_type)
 444 {
 445   TransformEntry entry;
 446
 447   entry.src_type = src_type;
 448   do
 449     {
 450       entry.dest_type = dest_type;
 451       do
 452         {
 453           TransformEntry *e;
 454
 455           e = g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry);
 456           if (e)
 457             {
 458               /* need to check that there hasn't been a change in value handling */
 459               if (g_type_value_table_peek (entry.dest_type) == g_type_value_table_peek (dest_type) &&
 460                   g_type_value_table_peek (entry.src_type) == g_type_value_table_peek (src_type))
 461                 return e->func;
 462             }
 463           entry.dest_type = g_type_parent (entry.dest_type);
 464         }
 465       while (entry.dest_type);
 466
 467       entry.src_type = g_type_parent (entry.src_type);
 468     }
 469   while (entry.src_type);
 470
 471   return NULL;
 472 }
 473
 474 static gint
 475 transform_entries_cmp (gconstpointer bsearch_node1,
 476                        gconstpointer bsearch_node2)
 477 {
 478   const TransformEntry *e1 = bsearch_node1;
 479   const TransformEntry *e2 = bsearch_node2;
 480   gint cmp = G_BSEARCH_ARRAY_CMP (e1->src_type, e2->src_type);
 481
 482   if (cmp)
 483     return cmp;
 484   else
 485     return G_BSEARCH_ARRAY_CMP (e1->dest_type, e2->dest_type);
 486 }
 487
 488 /**
 489  * g_value_register_transform_func: (skip)
 490  * @src_type: Source type.
 491  * @dest_type: Target type.
 492  * @transform_func: a function which transforms values of type @src_type
 493  *  into value of type @dest_type
 494  *
 495  * Registers a value transformation function for use in g_value_transform().
 496  * A previously registered transformation function for @src_type and @dest_type
 497  * will be replaced.
 498  */
 499 void
 500 g_value_register_transform_func (GType           src_type,
 501                                  GType           dest_type,
 502                                  GValueTransform transform_func)
 503 {
 504   TransformEntry entry;
 505
 506   /* these checks won't pass for dynamic types.
 507    * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (src_type));
 508    * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (dest_type));
 509    */
 510   g_return_if_fail (transform_func != NULL);
 511
 512   entry.src_type = src_type;
 513   entry.dest_type = dest_type;
 514
 515 #if 0 /* let transform function replacement be a valid operation */
 516   if (g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry))
 517     g_warning ("reregistering value transformation function (%p) for '%s' to '%s'",
 518                transform_func,
 519                g_type_name (src_type),
 520                g_type_name (dest_type));
 521 #endif
 522
 523   entry.func = transform_func;
 524   transform_array = g_bsearch_array_replace (transform_array, &transform_bconfig, &entry);
 525 }
 526
 527 /**
 528  * g_value_type_transformable:
 529  * @src_type: Source type.
 530  * @dest_type: Target type.
 531  *
 532  * Check whether g_value_transform() is able to transform values
 533  * of type @src_type into values of type @dest_type. Note that for
 534  * the types to be transformable, they must be compatible and a
 535  * transform function must be registered.
 536  *
 537  * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
 538  */
 539 gboolean
 540 g_value_type_transformable (GType src_type,
 541                             GType dest_type)
 542 {
 543   g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
 544   g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
 545
 546   return (g_value_type_compatible (src_type, dest_type) ||
 547           transform_func_lookup (src_type, dest_type) != NULL);
 548 }
 549
 550 /**
 551  * g_value_type_compatible:
 552  * @src_type: source type to be copied.
 553  * @dest_type: destination type for copying.
 554  *
 555  * Returns whether a #GValue of type @src_type can be copied into
 556  * a #GValue of type @dest_type.
 557  *
 558  * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
 559  */
 560 gboolean
 561 g_value_type_compatible (GType src_type,
 562                          GType dest_type)
 563 {
 564   g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
 565   g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
 566
 567   return (g_type_is_a (src_type, dest_type) &&
 568           g_type_value_table_peek (dest_type) == g_type_value_table_peek (src_type));
 569 }
 570
 571 /**
 572  * g_value_transform:
 573  * @src_value: Source value.
 574  * @dest_value: Target value.
 575  *
 576  * Tries to cast the contents of @src_value into a type appropriate
 577  * to store in @dest_value, e.g. to transform a %G_TYPE_INT value
 578  * into a %G_TYPE_FLOAT value. Performing transformations between
 579  * value types might incur precision lossage. Especially
 580  * transformations into strings might reveal seemingly arbitrary
 581  * results and shouldn't be relied upon for production code (such
 582  * as rcfile value or object property serialization).
 583  *
 584  * Returns: Whether a transformation rule was found and could be applied.
 585  *  Upon failing transformations, @dest_value is left untouched.
 586  */
 587 gboolean
 588 g_value_transform (const GValue *src_value,
 589                    GValue       *dest_value)
 590 {
 591   GType dest_type;
 592
 593   g_return_val_if_fail (G_IS_VALUE (src_value), FALSE);
 594   g_return_val_if_fail (G_IS_VALUE (dest_value), FALSE);
 595
 596   dest_type = G_VALUE_TYPE (dest_value);
 597   if (g_value_type_compatible (G_VALUE_TYPE (src_value), dest_type))
 598     {
 599       g_value_copy (src_value, dest_value);
 600
 601       return TRUE;
 602     }
 603   else
 604     {
 605       GValueTransform transform = transform_func_lookup (G_VALUE_TYPE (src_value), dest_type);
 606
 607       if (transform)
 608         {
 609           g_value_unset (dest_value);
 610
 611           /* setup and transform */
 612           value_meminit (dest_value, dest_type);
 613           transform (src_value, dest_value);
 614
 615           return TRUE;
 616         }
 617     }
 618   return FALSE;
 619 }