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