2008-06-21 Stefan Kost <ensonic@users.sf.net>
+ * docs/reference/gobject/tmpl/generic_values.sgml:
+ * gobject/gboxed.h:
+ * gobject/gtype.h:
+ * gobject/gvalue.c:
+ * gobject/gvalue.h:
+ * gobject/gvaluetypes.c:
+ Migrating docs.
+
+2008-06-21 Stefan Kost <ensonic@users.sf.net>
+
* gobject/genums.h:
Fix documentation for return values.
+++ /dev/null
-<!-- ##### 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 <link
-linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values
-API</link> 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: A #GValue structure.
-@type: A #GType value.
-
-
-<!-- ##### 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 @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_set_instance ##### -->
-<para>
-Sets @value from an instantiatable type via the
-value_table's collect_value() function.
-</para>
-
-@value: An initialized #GValue structure.
-@instance: the instance
-
-
-<!-- ##### 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 appropriate
-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 incur 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.
-
-
* The #GType for #GClosure.
*/
#define G_TYPE_CLOSURE (g_closure_get_type ())
+/**
+ * G_TYPE_VALUE:
+ *
+ * The type ID of the "GValue" type which is a boxed type,
+ * used to pass around pointers to GValues.
+ */
#define G_TYPE_VALUE (g_value_get_type ())
+/**
+ * G_TYPE_VALUE_ARRAY:
+ *
+ * The type ID of the "GValueArray" type which is a boxed type,
+ * used to pass around pointers to GValueArrays.
+ */
#define G_TYPE_VALUE_ARRAY (g_value_array_get_type ())
/**
* G_TYPE_DATE:
#define G_TYPE_IS_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))
#define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))
#define G_TYPE_IS_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))
+/**
+ * G_TYPE_IS_VALUE_ABSTRACT:
+ * @type: A #GType value.
+ *
+ * Checks 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.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
#define G_TYPE_IS_VALUE_TYPE(type) (g_type_check_is_value_type (type))
#define G_TYPE_HAS_VALUE_TABLE(type) (g_type_value_table_peek (type) != NULL)
* Free Software Foundation, Inc., 59 Temple Place, Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:Generic Values
+ * @Short_description: A polymorphic type that can hold values of any other type
+ * @See_also: 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 <link
+ * linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values
+ * API</link> for details.
+ *
+ * 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.
+ */
/*
* FIXME: MT-safety
memset (value->data, 0, sizeof (value->data));
}
+/**
+ * g_value_init:
+ * @value: A zero-filled (uninitialized) #GValue structure.
+ * @g_type: Type the #GValue should hold values of.
+ *
+ * Initializes @value with the default value of @type.
+ *
+ * Returns: the #GValue structure that has been passed in
+ */
GValue*
g_value_init (GValue *value,
GType g_type)
return value;
}
+/**
+ * g_value_copy:
+ * @src_value: An initialized #GValue structure.
+ * @dest_value: An initialized #GValue structure of the same type as @src_value.
+ *
+ * Copies the value of @src_value into @dest_value.
+ */
void
g_value_copy (const GValue *src_value,
GValue *dest_value)
}
}
+/**
+ * g_value_reset:
+ * @value: An initialized #GValue structure.
+ *
+ * Clears the current value in @value and resets it to the default value
+ * (as if the value had just been initialized).
+ *
+ * Returns: the #GValue structure that has been passed in
+ */
GValue*
g_value_reset (GValue *value)
{
return value;
}
+/**
+ * g_value_unset:
+ * @value: An initialized #GValue structure.
+ *
+ * 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.
+ */
void
g_value_unset (GValue *value)
{
memset (value, 0, sizeof (*value));
}
+/**
+ * g_value_fits_pointer:
+ * @value: An initialized #GValue structure.
+ *
+ * Determines if @value will fit inside the size of a pointer value.
+ * This is an internal function introduced mainly for C marshallers.
+ *
+ * Returns: %TRUE if @value will fit inside a pointer value.
+ */
gboolean
g_value_fits_pointer (const GValue *value)
{
return value_table->value_peek_pointer != NULL;
}
+/**
+ * g_value_peek_pointer:
+ * @value: An initialized #GValue structure.
+ *
+ * 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.
+ *
+ * Returns: %TRUE if @value will fit inside a pointer value.
+ */
gpointer
g_value_peek_pointer (const GValue *value)
{
return value_table->value_peek_pointer (value);
}
+/**
+ * g_value_set_instance:
+ * @value: An initialized #GValue structure.
+ * @instance: the instance
+ *
+ * Sets @value from an instantiatable type via the
+ * value_table's collect_value() function.
+ */
void
g_value_set_instance (GValue *value,
gpointer instance)
return G_BSEARCH_ARRAY_CMP (e1->dest_type, e2->dest_type);
}
+/**
+ * g_value_register_transform_func:
+ * @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
+ *
+ * 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.
+ */
void
g_value_register_transform_func (GType src_type,
GType dest_type,
transform_array = g_bsearch_array_replace (transform_array, &transform_bconfig, &entry);
}
+/**
+ * g_value_type_transformable:
+ * @src_type: Source type.
+ * @dest_type: Target type.
+ *
+ * Check whether g_value_transform() is able to transform values
+ * of type @src_type into values of type @dest_type.
+ *
+ * Returns: %TRUE if the transformation is possible, %FALSE otherwise.
+ */
gboolean
g_value_type_transformable (GType src_type,
GType dest_type)
transform_func_lookup (src_type, dest_type) != NULL);
}
+/**
+ * g_value_type_compatible:
+ * @src_type: source type to be copied.
+ * @dest_type: destination type for copying.
+ *
+ * Returns whether a #GValue of type @src_type can be copied into
+ * a #GValue of type @dest_type.
+ *
+ * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type.
+ */
gboolean
g_value_type_compatible (GType src_type,
GType dest_type)
g_type_value_table_peek (dest_type) == g_type_value_table_peek (src_type));
}
+/**
+ * g_value_transform:
+ * @src_value: Source value.
+ * @dest_value: Target value.
+ *
+ * Tries to cast the contents of @src_value into a type appropriate
+ * 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 incur 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).
+ *
+ * Returns: Whether a transformation rule was found and could be applied.
+ * Upon failing transformations, @dest_value is left untouched.
+ */
gboolean
g_value_transform (const GValue *src_value,
GValue *dest_value)
G_BEGIN_DECLS
/* --- type macros --- */
+/**
+ * G_TYPE_IS_VALUE:
+ * @type: A #GType value.
+ *
+ * Checks 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.
+ *
+ * Returns: Whether @type is suitable as a #GValue type.
+ */
#define G_TYPE_IS_VALUE(type) (g_type_check_is_value_type (type))
+/**
+ * G_IS_VALUE:
+ * @value: A #GValue structure.
+ *
+ * Checks if @value is a valid and initialized #GValue structure.
+ *
+ * Returns: %TRUE on success.
+ */
#define G_IS_VALUE(value) (G_TYPE_CHECK_VALUE (value))
+/**
+ * G_VALUE_TYPE:
+ * @value: A #GValue structure.
+ *
+ * Get the type identifier of @value.
+ *
+ * Returns: the #GType.
+ */
#define G_VALUE_TYPE(value) (((GValue*) (value))->g_type)
+/**
+ * G_VALUE_TYPE_NAME:
+ * @value: A #GValue structure.
+ *
+ * Gets the the type name of @value.
+ *
+ * Returns: the type name.
+ */
#define G_VALUE_TYPE_NAME(value) (g_type_name (G_VALUE_TYPE (value)))
+/**
+ * G_VALUE_HOLDS:
+ * @value: A #GValue structure.
+ * @type: A #GType value.
+ *
+ * Checks 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.
+ *
+ * Returns: %TRUE if @value holds the @type.
+ */
#define G_VALUE_HOLDS(value,type) (G_TYPE_CHECK_VALUE_TYPE ((value), (type)))
/* --- typedefs & structures --- */
+/**
+ * GValueTransform:
+ * @src_value: Source value.
+ * @dest_value: Target value.
+ *
+ * The type of value transformation functions which can be registered with
+ * g_value_register_transform_func().
+ */
typedef void (*GValueTransform) (const GValue *src_value,
GValue *dest_value);
+/**
+ * GValue:
+ *
+ * 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 @data union, and the @g_type member should
+ * only be accessed through the G_VALUE_TYPE() macro.
+ */
struct _GValue
{
/*< private >*/
return value->data[0].v_long;
}
-
+/**
+ * g_strdup_value_contents:
+ * @value: #GValue which contents are to be described.
+ *
+ * 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.
+ *
+ * Returns: Newly allocated string.
+ */
gchar*
g_strdup_value_contents (const GValue *value)
{
projects / platform / upstream / glib.git / commitdiff