| <!-- ##### SECTION Title ##### --> |
| Generic Values |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| A polymorphic type that can hold values of any other type |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| The #GValue structure is basically a variable container that consists |
| of a type identifier and a specific value of that type. |
| The type identifier within a #GValue structure always determines the |
| type of the associated value. |
| To create a undefined #GValue structure, simply create a zero-filled |
| #GValue structure. To initialize the #GValue, use the g_value_init() |
| function. A #GValue cannot be used until it is initialized. |
| The basic type operations (such as freeing and copying) are determined |
| by the #GTypeValueTable associated with the type ID stored in the #GValue. |
| Other #GValue operations (such as converting values between types) are |
| provided by this interface. |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| The fundamental types which all support #GValue operations and thus |
| can be used as a type initializer for g_value_init() are defined by |
| a separate interface. See the Standard Values API for details. |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### MACRO G_VALUE_HOLDS ##### --> |
| <para> |
| Returns #TRUE if @value holds (or contains) a value of @type. |
| This macro will also check for @value != #NULL and issue a |
| warning if the check fails. |
| </para> |
| |
| @value: |
| @type: |
| |
| |
| <!-- ##### MACRO G_VALUE_TYPE ##### --> |
| <para> |
| Returns the type identifier of @value. |
| </para> |
| |
| @value: A #GValue structure. |
| |
| |
| <!-- ##### MACRO G_VALUE_TYPE_NAME ##### --> |
| <para> |
| Returns the type name of @value. |
| </para> |
| |
| @value: A #GValue structure. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_VALUE ##### --> |
| <para> |
| Return whether the passed in type ID can be used for g_value_init(). |
| That is, this macro checks whether this type provides an implementation |
| of the #GTypeValueTable functions required for a type to create a #GValue of. |
| </para> |
| |
| @type: A #GType value. |
| @Returns: Whether @type is suitable as a #GValue type. |
| |
| |
| <!-- ##### MACRO G_TYPE_IS_VALUE_ABSTRACT ##### --> |
| <para> |
| Returns %TRUE if @type is an abstract value type. An abstract value type |
| introduces a value table, but can't be used for g_value_init() and is normally |
| used as an abstract base type for derived value types. |
| </para> |
| |
| @type: A #GType value. |
| |
| |
| <!-- ##### MACRO G_IS_VALUE ##### --> |
| <para> |
| Returns #TRUE if @value is a valid and initialized #GValue structure. |
| </para> |
| |
| @value: A #GValue structure. |
| |
| |
| <!-- ##### STRUCT GValue ##### --> |
| <para> |
| An opaque structure used to hold different types of values. |
| The data within the structure has protected scope: it is accessible only |
| to functions within a #GTypeValueTable structure, or implementations of |
| the g_value_*() API. That is, code portions which implement new fundamental |
| types. |
| #GValue users can not make any assumptions about how data is stored |
| within the 2 element #GValue.data[] union, and the g_type member should |
| only be accessed through the G_VALUE_TYPE() macro. |
| </para> |
| |
| |
| <!-- ##### MACRO G_TYPE_VALUE ##### --> |
| <para> |
| Returns the type ID of the "GValue" type which is a boxed type, |
| used to pass around pointers to GValues. |
| </para> |
| |
| |
| |
| <!-- ##### MACRO G_TYPE_VALUE_ARRAY ##### --> |
| <para> |
| Returns the type ID of the "GValueArray" type which is a boxed type, |
| used to pass around pointers to GValueArrays. |
| </para> |
| |
| |
| |
| <!-- ##### FUNCTION g_value_init ##### --> |
| <para> |
| Initializes @value with the default value of @type. |
| </para> |
| |
| @value: A zero-filled (uninitialized) #GValue structure. |
| @g_type: Type the #GValue should hold values of. |
| @Returns: the #GValue structure that has been passed in |
| |
| |
| <!-- ##### FUNCTION g_value_copy ##### --> |
| <para> |
| Copies the value of @src_value into @dest_value. |
| </para> |
| |
| @src_value: An initialized #GValue structure. |
| @dest_value: An initialized #GValue structure of the same type as @src_value. |
| |
| |
| <!-- ##### FUNCTION g_value_reset ##### --> |
| <para> |
| Clears the current value in @value and resets it to the default value |
| (as if the value had just been initialized). |
| </para> |
| |
| @value: An initialized #GValue structure. |
| @Returns: the #GValue structure that has been passed in |
| |
| |
| <!-- ##### FUNCTION g_value_unset ##### --> |
| <para> |
| Clears the current value in @value and "unsets" the type, |
| this releases all resources associated with this GValue. |
| An unset value is the same as an uninitialized (zero-filled) |
| #GValue structure. |
| </para> |
| |
| @value: An initialized #GValue structure. |
| |
| |
| <!-- ##### FUNCTION g_value_fits_pointer ##### --> |
| <para> |
| Determines if @value will fit inside the size of a pointer value. |
| This is an internal function introduced mainly for C marshallers. |
| </para> |
| |
| @value: An initialized #GValue structure. |
| @Returns: #TRUE if @value will fit inside a pointer value. |
| |
| |
| <!-- ##### FUNCTION g_value_peek_pointer ##### --> |
| <para> |
| Return the value contents as pointer. This function asserts that |
| g_value_fits_pointer() returned #TRUE for the passed in value. |
| This is an internal function introduced mainly for C marshallers. |
| </para> |
| |
| @value: An initialized #GValue structure. |
| @Returns: #TRUE if @value will fit inside a pointer value. |
| |
| |
| <!-- ##### FUNCTION g_value_type_compatible ##### --> |
| <para> |
| Returns whether a #GValue of type @src_type can be copied into |
| a #GValue of type @dest_type. |
| </para> |
| |
| @src_type: source type to be copied. |
| @dest_type: destination type for copying. |
| @Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. |
| |
| |
| <!-- ##### FUNCTION g_value_type_transformable ##### --> |
| <para> |
| Check whether g_value_transform() is able to transform values |
| of type @src_type into values of type @dest_type. |
| </para> |
| |
| @src_type: Source type. |
| @dest_type: Target type. |
| @Returns: %TRUE if the transformation is possible, %FALSE otherwise. |
| |
| |
| <!-- ##### FUNCTION g_value_transform ##### --> |
| <para> |
| Tries to cast the contents of @src_value into a type apropriate |
| to store in @dest_value, e.g. to transform a %G_TYPE_INT value |
| into a %G_TYPE_FLOAT value. Performing transformations between |
| value types might incour precision lossage. Especially |
| transformations into strings might reveal seemingly arbitrary |
| results and shouldn't be relied upon for production code (such |
| as rcfile value or object property serialization). |
| </para> |
| |
| @src_value: Source value. |
| @dest_value: Target value. |
| @Returns: Whether a transformation rule was found and could be applied. |
| Upon failing transformations, @dest_value is left untouched. |
| |
| |
| <!-- ##### USER_FUNCTION GValueTransform ##### --> |
| <para> |
| The type of value transformation functions which can be registered with |
| g_value_register_transform_func(). |
| </para> |
| |
| @src_value: Source value. |
| @dest_value: Target value. |
| |
| |
| <!-- ##### FUNCTION g_value_register_transform_func ##### --> |
| <para> |
| Registers a value transformation function for use in g_value_transform(). |
| A previously registered transformation function for @src_type and @dest_type |
| will be replaced. |
| </para> |
| |
| @src_type: Source type. |
| @dest_type: Target type. |
| @transform_func: a function which transforms values of type @src_type |
| into value of type @dest_type |
| |
| |
| <!-- ##### FUNCTION g_strdup_value_contents ##### --> |
| <para> |
| Return a newly allocated string, which describes the contents of a #GValue. |
| The main purpose of this function is to describe #GValue contents for debugging |
| output, the way in which the contents are described may change between different |
| GLib versions. |
| </para> |
| |
| @value: #GValue which contents are to be described. |
| @Returns: Newly allocated string. |
| |
| |