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 static GValueTransform
 377 transform_func_lookup (GType src_type,
 378                        GType dest_type)
 379 {
 380   TransformEntry entry;
 381
 382   entry.src_type = src_type;
 383   do
 384     {
 385       entry.dest_type = dest_type;
 386       do
 387         {
 388           TransformEntry *e;
 389
 390           e = g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry);
 391           if (e)
 392             {
 393               /* need to check that there hasn't been a change in value handling */
 394               if (g_type_value_table_peek (entry.dest_type) == g_type_value_table_peek (dest_type) &&
 395                   g_type_value_table_peek (entry.src_type) == g_type_value_table_peek (src_type))
 396                 return e->func;
 397             }
 398           entry.dest_type = g_type_parent (entry.dest_type);
 399         }
 400       while (entry.dest_type);
 401
 402       entry.src_type = g_type_parent (entry.src_type);
 403     }
 404   while (entry.src_type);
 405
 406   return NULL;
 407 }
 408
 409 static gint
 410 transform_entries_cmp (gconstpointer bsearch_node1,
 411                        gconstpointer bsearch_node2)
 412 {
 413   const TransformEntry *e1 = bsearch_node1;
 414   const TransformEntry *e2 = bsearch_node2;
 415   gint cmp = G_BSEARCH_ARRAY_CMP (e1->src_type, e2->src_type);
 416
 417   if (cmp)
 418     return cmp;
 419   else
 420     return G_BSEARCH_ARRAY_CMP (e1->dest_type, e2->dest_type);
 421 }
 422
 423 /**
 424  * g_value_register_transform_func: (skip)
 425  * @src_type: Source type.
 426  * @dest_type: Target type.
 427  * @transform_func: a function which transforms values of type @src_type
 428  *  into value of type @dest_type
 429  *
 430  * Registers a value transformation function for use in g_value_transform().
 431  * A previously registered transformation function for @src_type and @dest_type
 432  * will be replaced.
 433  */
 434 void
 435 g_value_register_transform_func (GType           src_type,
 436                                  GType           dest_type,
 437                                  GValueTransform transform_func)
 438 {
 439   TransformEntry entry;
 440
 441   /* these checks won't pass for dynamic types.
 442    * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (src_type));
 443    * g_return_if_fail (G_TYPE_HAS_VALUE_TABLE (dest_type));
 444    */
 445   g_return_if_fail (transform_func != NULL);
 446
 447   entry.src_type = src_type;
 448   entry.dest_type = dest_type;
 449
 450 #if 0 /* let transform function replacement be a valid operation */
 451   if (g_bsearch_array_lookup (transform_array, &transform_bconfig, &entry))
 452     g_warning ("reregistering value transformation function (%p) for '%s' to '%s'",
 453                transform_func,
 454                g_type_name (src_type),
 455                g_type_name (dest_type));
 456 #endif
 457
 458   entry.func = transform_func;
 459   transform_array = g_bsearch_array_replace (transform_array, &transform_bconfig, &entry);
 460 }
 461
 462 /**
 463  * g_value_type_transformable:
 464  * @src_type: Source type.
 465  * @dest_type: Target type.
 466  *
 467  * Check whether g_value_transform() is able to transform values
 468  * of type @src_type into values of type @dest_type. Note that for
 469  * the types to be transformable, they must be compatible and a
 470  * transform function must be registered.
 471  *
 472  * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
 473  */
 474 gboolean
 475 g_value_type_transformable (GType src_type,
 476                             GType dest_type)
 477 {
 478   g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
 479   g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
 480
 481   return (g_value_type_compatible (src_type, dest_type) ||
 482           transform_func_lookup (src_type, dest_type) != NULL);
 483 }
 484
 485 /**
 486  * g_value_type_compatible:
 487  * @src_type: source type to be copied.
 488  * @dest_type: destination type for copying.
 489  *
 490  * Returns whether a #GValue of type @src_type can be copied into
 491  * a #GValue of type @dest_type.
 492  *
 493  * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
 494  */
 495 gboolean
 496 g_value_type_compatible (GType src_type,
 497                          GType dest_type)
 498 {
 499   g_return_val_if_fail (G_TYPE_IS_VALUE (src_type), FALSE);
 500   g_return_val_if_fail (G_TYPE_IS_VALUE (dest_type), FALSE);
 501
 502   return (g_type_is_a (src_type, dest_type) &&
 503           g_type_value_table_peek (dest_type) == g_type_value_table_peek (src_type));
 504 }
 505
 506 /**
 507  * g_value_transform:
 508  * @src_value: Source value.
 509  * @dest_value: Target value.
 510  *
 511  * Tries to cast the contents of @src_value into a type appropriate
 512  * to store in @dest_value, e.g. to transform a %G_TYPE_INT value
 513  * into a %G_TYPE_FLOAT value. Performing transformations between
 514  * value types might incur precision lossage. Especially
 515  * transformations into strings might reveal seemingly arbitrary
 516  * results and shouldn't be relied upon for production code (such
 517  * as rcfile value or object property serialization).
 518  *
 519  * Returns: Whether a transformation rule was found and could be applied.
 520  *  Upon failing transformations, @dest_value is left untouched.
 521  */
 522 gboolean
 523 g_value_transform (const GValue *src_value,
 524                    GValue       *dest_value)
 525 {
 526   GType dest_type;
 527
 528   g_return_val_if_fail (G_IS_VALUE (src_value), FALSE);
 529   g_return_val_if_fail (G_IS_VALUE (dest_value), FALSE);
 530
 531   dest_type = G_VALUE_TYPE (dest_value);
 532   if (g_value_type_compatible (G_VALUE_TYPE (src_value), dest_type))
 533     {
 534       g_value_copy (src_value, dest_value);
 535
 536       return TRUE;
 537     }
 538   else
 539     {
 540       GValueTransform transform = transform_func_lookup (G_VALUE_TYPE (src_value), dest_type);
 541
 542       if (transform)
 543         {
 544           g_value_unset (dest_value);
 545
 546           /* setup and transform */
 547           value_meminit (dest_value, dest_type);
 548           transform (src_value, dest_value);
 549
 550           return TRUE;
 551         }
 552     }
 553   return FALSE;
 554 }