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