_GTypeValueTable Struct Reference

Detailed Description

GTypeValueTable: : Default initialize contents by poking values directly into the value->data array. The data array of the GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]| : Free any old contents that might be left in the data array of the passed in . No resources may remain allocated through the GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]| : is a GValue with zero-filled data section and is a properly setup GValue of same or derived type. The purpose of this function is to copy the contents of into in a way, that even after has been freed, the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]| : If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]| : A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><listitem>

'i' - Integers. passed as collect_values[].v_int.

</listitem></varlistentry> <varlistentry><listitem>

'l' - Longs. passed as collect_values[].v_long.

</listitem></varlistentry> <varlistentry><listitem>

'd' - Doubles. passed as collect_values[].v_double.

</listitem></varlistentry> <varlistentry><listitem>

'p' - Pointers. passed as collect_values[].v_pointer.

</listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i' needs to be used, and for collection of floats 'd'. : The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup similar to value_init(); e.g. for a string value that does not allow NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. is exactly the string length of , and is an array of unions GTypeCValue with length , containing the collected values according to . is an argument provided as a hint by the caller. It may contain the flag G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the lifetime. Thus an extra copy of the contents stored in is not required for assignment to . For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of . For invalid objects, the example returns a newly allocated string without altering . Upon success, collect_value() needs to return NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the contents being valid upon error returns, is simply thrown away without further freeing. As such, it is a good idea to not allocate GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup for error returns, simply because any non-NULL return is considered a fatal condition so further program behaviour is undefined. : Format description of the arguments to collect for , analogous to . Usually, string consists only of 'p's to provide lcopy_value() with pointers to storage locations. : This function is responsible for storing the contents into arguments passed through a variable argument list which got collected into according to . equals the string length of , and may contain G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]|

The GTypeValueTable provides the functions required by the GValue implementation, to serve as a container for values of a type.