docs/reference/gobject/tmpl/generic_values.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Generic Values
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A polymorphic type that can hold values of any other type.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GValue structure is basically a variable container that consists
  10 of a type identifier and a specific value of that type.
  11 The type identifier within a #GValue structure always determines the
  12 type of the associated value.
  13 To create a undefined #GValue structure, simply create a zero-filled
  14 #GValue structure. To intialize the #GValue, use the g_value_init()
  15 function. A #GValue cannot be used until it is initialized.
  16 The basic type operations (such as freeing and copying) are determined
  17 by the #GTypeValueTable associated with the type ID stored in the #GValue.
  18 Other #GValue operations (such as converting values between types) are
  19 provided by this interface.
  20 </para>
  21
  22 <!-- ##### SECTION See_Also ##### -->
  23 <para>
  24 The fundamental types which all support #GValue operations and thus
  25 can be used as a type initializer for g_value_init() are defined by
  26 a separate interface.  See the Standard Values API for details.
  27 </para>
  28
  29 <!-- ##### MACRO G_VALUE_HOLDS ##### -->
  30 <para>
  31 Returns #TRUE if @value holds (or contains) a value of @type.
  32 This macro will also check for @value != #NULL and issue a
  33 warning if the check fails.
  34 </para>
  35
  36 @value:
  37 @type:
  38
  39
  40 <!-- ##### MACRO G_VALUE_TYPE ##### -->
  41 <para>
  42 Returns the type identifier of @value.
  43 </para>
  44
  45 @value: A #GValue structure.
  46
  47
  48 <!-- ##### MACRO G_VALUE_TYPE_NAME ##### -->
  49 <para>
  50 Returns the type name of @value.
  51 </para>
  52
  53 @value: A #GValue structure.
  54
  55
  56 <!-- ##### MACRO G_TYPE_IS_VALUE ##### -->
  57 <para>
  58 Return whether the passed in type ID can be used for g_value_init().
  59 That is, this macro checks whether this type provides an implementation
  60 of the #GTypeValueTable functions required for a type to create a #GValue of.
  61 </para>
  62
  63 @type:    A #GType value.
  64 @Returns: Whether @type is suitable as a #GValue type.
  65
  66
  67 <!-- ##### MACRO G_IS_VALUE ##### -->
  68 <para>
  69 Returns #TRUE if @value is a valid and initialized #GValue structure.
  70 </para>
  71
  72 @value: A #GValue structure.
  73
  74
  75 <!-- ##### USER_FUNCTION GValueExchange ##### -->
  76 <para>
  77
  78 </para>
  79
  80 @value1:
  81 @value2:
  82
  83
  84 <!-- ##### STRUCT GValue ##### -->
  85 <para>
  86 A mostly opaque structure used to hold a #GValue object.  Mostly because
  87 the data within the structure has protected scope: it is accessible only
  88 to functions within a #GTypeValueTable structure, or implementations of
  89 the g_value_*() API.
  90 </para>
  91
  92
  93 <!-- ##### FUNCTION g_value_init ##### -->
  94 <para>
  95 Initializes @value with the default value of @type.
  96 </para>
  97
  98 @value:                 A zero-filled (uninitialized) #GValue structure.
  99 @g_type:        Type the #GValue should hold values of.
 100 @Returns:
 101
 102
 103 <!-- ##### FUNCTION g_value_copy ##### -->
 104 <para>
 105 Copies the value of @src_value into @dest_value.
 106 </para>
 107
 108 @src_value:     An initialized #GValue structure.
 109 @dest_value:    An initialized #GValue structure of the same type as @src_value.
 110
 111
 112 <!-- ##### FUNCTION g_value_reset ##### -->
 113 <para>
 114 Clears the current value in @value and resets it to the default value
 115 (as if the value had just been initialized).
 116 </para>
 117
 118 @value:         An initialized #GValue structure.
 119 @Returns:
 120
 121
 122 <!-- ##### FUNCTION g_value_unset ##### -->
 123 <para>
 124 Clears the current value in @value and "unsets" the type,
 125 this releases all resources associated with this GValue.
 126 An unset value is the same as an uninitialized (zero-filled)
 127 #GValue structure.
 128 </para>
 129
 130 @value:         An initialized #GValue structure.
 131
 132
 133 <!-- ##### FUNCTION g_value_fits_pointer ##### -->
 134 <para>
 135 Determines if @value will fit inside the size of a pointer value.
 136 This is an internal function introduced mainly for C marshallers.
 137 </para>
 138
 139 @value:                 An initialized #GValue structure.
 140 @Returns:       #TRUE if @value will fit inside a pointer value.
 141
 142
 143 <!-- ##### FUNCTION g_value_peek_pointer ##### -->
 144 <para>
 145 Return the value contents as pointer. This function asserts that
 146 g_value_fits_pointer() returned #TRUE for the passed in value.
 147 This is an internal function introduced mainly for C marshallers.
 148 </para>
 149
 150 @value:                 An initialized #GValue structure.
 151 @Returns:       #TRUE if @value will fit inside a pointer value.
 152
 153
 154 <!-- ##### STRUCT GTypeValueTable ##### -->
 155 <para>
 156 The #GTypeValueTable provides the functions required by the #GValue implementation,
 157 to serve as a container for values of a type.
 158 </para>
 159
 160 @value_init:            Default initialize @values contents by poking values
 161                         directly into the value-&gt;data array. The data array of
 162                         the #GValue passed into this function was zero-filled
 163                         with memset, so no care has to be taken to free any
 164                         old contents. E.g. for the implementation of a string
 165                         value that may never be NULL, the implementation might
 166                         look like:
 167 <msgtext><programlisting>
 168 {
 169   value-&gt;data[0].v_pointer = g_strdup ("");
 170 }
 171 </programlisting></msgtext>
 172 @value_free:            Free any old contents that might be left in the
 173                         data array of the passed in @value. No resources may
 174                         remain allocated through the #GValue contents after
 175                         this function returns. E.g. for our above string type:
 176 <msgtext><programlisting>
 177 {
 178   /* only free strings without a specific flag for static storage */
 179   if (!(value-&gt;data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
 180     g_free (value-&gt;data[0].v_pointer);
 181 }
 182 </programlisting></msgtext>
 183 @value_copy:            @dest_value is a #GValue with zero-filled data section
 184                         and @src_value is a properly setup #GValue of same or
 185                         derived type.
 186                         The purpose of this function is to copy the contents of
 187                         @src_value into @dest_value in a way, that even after
 188                         @src_value has been freed, the contents of @dest_value
 189                         remain valid. String type example:
 190 <msgtext><programlisting>
 191 {
 192   dest_value-&gt;data[0].v_pointer = g_strdup (src_value-&gt;data[0].v_pointer);
 193 }
 194 </programlisting></msgtext>
 195 @value_peek_pointer:    If the value contents fit into a pointer, such as objects
 196                         or strings, return this pointer, so the caller can peek at
 197                         the current contents. To extend on our above string example:
 198 <msgtext><programlisting>
 199 {
 200   return value-&gt;data[0].v_pointer;
 201 }
 202 </programlisting></msgtext>
 203 @collect_format:        A string format describing how to collect the contents of
 204                         this value, bit-by-bit. Each character in the format represents
 205                         an argument to be collected, the characters themselves indicate
 206                         the type of the argument. Currently supported arguments are:
 207 <msgtext><variablelist>
 208   <varlistentry><term></term><listitem><para>
 209         'i' - Integers. passed as collect_values[].v_int.
 210   </para></listitem></varlistentry>
 211   <varlistentry><term></term><listitem><para>
 212         'l' - Longs. passed as collect_values[].v_long.
 213   </para></listitem></varlistentry>
 214   <varlistentry><term></term><listitem><para>
 215         'd' - Doubles. passed as collect_values[].v_double.
 216   </para></listitem></varlistentry>
 217   <varlistentry><term></term><listitem><para>
 218         'p' - Pointers. passed as collect_values[].v_pointer.
 219   </para></listitem></varlistentry>
 220 </variablelist></msgtext>
 221                         It should be noted, that for variable argument list construction,
 222                         ANSI C promotes every type smaller than an integer to an int, and
 223                         floats to doubles. So for collection of short int or char, 'i'
 224                         needs to be used, and for collection of floats 'd'.
 225 @collect_value:         The collect_value() function is responsible for converting the
 226                         values collected from a variable argument list into contents
 227                         suitable for storage in a GValue. This function should setup
 228                         @value similar to value_init(), e.g. for a string value that
 229                         does not allow NULL pointers, it needs to either spew an error,
 230                         or do an implicit conversion by storing an empty string.
 231                         The @value passed in to this function has a zero-filled data
 232                         array, so just like for @value_init it is guarranteed to not
 233                         contain any old contents that might need freeing.
 234                         @n_collect_values is exactly the string length of @collect_format,
 235                         and @collect_values is an array of unions #GTypeCValue with
 236                         length @n_collect_values, containing the collected values
 237                         according to @collect_format.
 238                         @collect_flags is an argument provided as a hint by the caller,
 239                         which may contain the flag #G_VALUE_NOCOPY_CONTENTS indicating,
 240                         that the collected value contents may be considered "static"
 241                         for the duration of the #@value lifetime.
 242                         Thus an extra copy of the contents stored in @collect_values is
 243                         not required for assignment to @value.
 244                         For our above string example, we continue with:
 245 <msgtext><programlisting>
 246 {
 247   if (!collect_values[0].v_pointer)
 248     value->data[0].v_pointer = g_strdup ("");
 249   else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
 250     {
 251       value-&gt;data[0].v_pointer = collect_values[0].v_pointer;
 252       /* keep a flag for the value_free() implementation to not free this string */
 253       value-&gt;data[1].v_uint = G_VALUE_NOCOPY_CONTENTS;
 254     }
 255   else
 256     value-&gt;data[0].v_pointer = g_strdup (collect_values[0].v_pointer);
 257
 258   return NULL;
 259 }
 260 </programlisting></msgtext>
 261                         It should be noted, that it is generally a bad idea to follow the
 262                         #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to
 263                         reentrancy requirements and reference count assertions performed
 264                         by the GSignal code, reference counts should always be incremented
 265                         for reference counted contents stored in the value-&gt;data array.
 266                         To deviate from our string example for a moment, and taking a look
 267                         at an exemplary implementation for collect_value() of #GObject:
 268 <msgtext><programlisting>
 269 {
 270   if (collect_values[0].v_pointer)
 271     {
 272       GObject *object = G_OBJECT (collect_values[0].v_pointer);
 273
 274       /* never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types */
 275       value-&gt;data[0].v_pointer = g_object_ref (object);
 276       return NULL;
 277     }
 278   else
 279     return g_strdup_printf ("Object passed as invalid NULL pointer");
 280 }
 281 </programlisting></msgtext>
 282                         The reference count for valid objects is always incremented,
 283                         regardless of @collect_flags. For invalid objects, the example
 284                         returns a newly allocated string without altering @value.
 285                         Upon success, collect_value() needs to return NULL, if however
 286                         a malicious condition occoured, collect_value() may spew an
 287                         error by returning a newly allocated non-NULL string, giving
 288                         a suitable description of the error condition.
 289                         The calling code makes no assumptions about the @value
 290                         contents being valid upon error returns, @value
 291                         is simply thrown away without further freeing. As such, it is
 292                         a good idea to not allocate #GValue contents, prior to returning
 293                         an error, however, collect_values() is not obliged to return
 294                         a correctly setup @value for error returns, simply because
 295                         any non-NULL return is considered a fatal condition so further
 296                         program behaviour is undefined.
 297 @lcopy_format:          Format description of the arguments to collect for @lcopy_value,
 298                         analogous to @collect_format. Usually, @lcopy_format string consist
 299                         only of 'p's to provide lcopy_value() with pointers to storage locations.
 300 @lcopy_value:           This function is responsible for storing the @value contents into
 301                         arguments passed through a variable argument list which got
 302                         collected into @collect_values according to @lcopy_format.
 303                         @n_collect_values equals the string length of @lcopy_format,
 304                         and @collect_flags may contain #G_VALUE_NOCOPY_CONTENTS.
 305                         In contrast to collect_value(), lcopy_value() is obliged to
 306                         always properly support #G_VALUE_NOCOPY_CONTENTS.
 307                         Similar to collect_value() the function may prematurely abort
 308                         by returning a newly allocated string describing an error condition.
 309                         To complete the string example:
 310 <msgtext><programlisting>
 311 {
 312   gchar **string_p = collect_values[0].v_pointer;
 313
 314   if (!string_p)
 315     return g_strdup_printf ("string location passed as NULL");
 316
 317   if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
 318     *string_p = value-&gt;data[0].v_pointer;
 319   else
 320     *string_p = g_strdup (value-&gt;data[0].v_pointer);
 321
 322 }
 323 </programlisting></msgtext>
 324                         And an exemplary version of lcopy_value() for
 325                         reference-counted types:
 326 <msgtext><programlisting>
 327 {
 328   GObject **object_p = collect_values[0].v_pointer;
 329
 330   if (!object_p)
 331     return g_strdup_printf ("object location passed as NULL");
 332   if (!value-&gt;data[0].v_pointer)
 333     *object_p = NULL;
 334   else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /* always honour */
 335     *object_p = value-&gt;data[0].v_pointer;
 336   else
 337     *object_p = g_object_ref (value-&gt;data[0].v_pointer);
 338   return NULL;
 339 }
 340 </programlisting></msgtext>
 341