generic_values.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="gobject-Generic-values">
<refmeta>
<refentrytitle>Generic Values</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GOBJECT Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Generic Values</refname><refpurpose>A polymorphic type that can hold values of any other type.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gobject.h&gt;


#define     <link linkend="G-VALUE-HOLDS-CAPS">G_VALUE_HOLDS</link>                   (value,type)
#define     <link linkend="G-VALUE-TYPE-CAPS">G_VALUE_TYPE</link>                    (value)
#define     <link linkend="G-VALUE-TYPE-NAME-CAPS">G_VALUE_TYPE_NAME</link>               (value)
#define     <link linkend="G-TYPE-IS-VALUE-CAPS">G_TYPE_IS_VALUE</link>                 (type)
#define     <link linkend="G-TYPE-IS-VALUE-ABSTRACT-CAPS">G_TYPE_IS_VALUE_ABSTRACT</link>        (type)
#define     <link linkend="G-IS-VALUE-CAPS">G_IS_VALUE</link>                      (value)
struct      <link linkend="GValue">GValue</link>;
#define     <link linkend="G-TYPE-VALUE-CAPS">G_TYPE_VALUE</link>
#define     <link linkend="G-TYPE-VALUE-ARRAY-CAPS">G_TYPE_VALUE_ARRAY</link>
<link linkend="GValue">GValue</link>*     <link linkend="g-value-init">g_value_init</link>                    (<link linkend="GValue">GValue</link> *value,
                                             <link linkend="GType">GType</link> g_type);
void        <link linkend="g-value-copy">g_value_copy</link>                    (const <link linkend="GValue">GValue</link> *src_value,
                                             <link linkend="GValue">GValue</link> *dest_value);
<link linkend="GValue">GValue</link>*     <link linkend="g-value-reset">g_value_reset</link>                   (<link linkend="GValue">GValue</link> *value);
void        <link linkend="g-value-unset">g_value_unset</link>                   (<link linkend="GValue">GValue</link> *value);
<link linkend="gboolean">gboolean</link>    <link linkend="g-value-fits-pointer">g_value_fits_pointer</link>            (const <link linkend="GValue">GValue</link> *value);
<link linkend="gpointer">gpointer</link>    <link linkend="g-value-peek-pointer">g_value_peek_pointer</link>            (const <link linkend="GValue">GValue</link> *value);
<link linkend="gboolean">gboolean</link>    <link linkend="g-value-type-compatible">g_value_type_compatible</link>         (<link linkend="GType">GType</link> src_type,
                                             <link linkend="GType">GType</link> dest_type);
<link linkend="gboolean">gboolean</link>    <link linkend="g-value-type-transformable">g_value_type_transformable</link>      (<link linkend="GType">GType</link> src_type,
                                             <link linkend="GType">GType</link> dest_type);
<link linkend="gboolean">gboolean</link>    <link linkend="g-value-transform">g_value_transform</link>               (const <link linkend="GValue">GValue</link> *src_value,
                                             <link linkend="GValue">GValue</link> *dest_value);
void        (<link linkend="GValueTransform">*GValueTransform</link>)              (const <link linkend="GValue">GValue</link> *src_value,
                                             <link linkend="GValue">GValue</link> *dest_value);
void        <link linkend="g-value-register-transform-func">g_value_register_transform_func</link> (<link linkend="GType">GType</link> src_type,
                                             <link linkend="GType">GType</link> dest_type,
                                             <link linkend="GValueTransform">GValueTransform</link> transform_func);
<link linkend="gchar">gchar</link>*      <link linkend="g-strdup-value-contents">g_strdup_value_contents</link>         (const <link linkend="GValue">GValue</link> *value);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The <link linkend="GValue">GValue</link> structure is basically a variable container that consists
of a type identifier and a specific value of that type.
The type identifier within a <link linkend="GValue">GValue</link> structure always determines the
type of the associated value.
To create a undefined <link linkend="GValue">GValue</link> structure, simply create a zero-filled
<link linkend="GValue">GValue</link> structure. To initialize the <link linkend="GValue">GValue</link>, use the <link linkend="g-value-init">g_value_init</link>()
function. A <link linkend="GValue">GValue</link> cannot be used until it is initialized.
The basic type operations (such as freeing and copying) are determined
by the <link linkend="GTypeValueTable">GTypeValueTable</link> associated with the type ID stored in the <link linkend="GValue">GValue</link>.
Other <link linkend="GValue">GValue</link> operations (such as converting values between types) are
provided by this interface.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="G-VALUE-HOLDS-CAPS">G_VALUE_HOLDS()</title>
<programlisting>#define G_VALUE_HOLDS(value,type)	(G_TYPE_CHECK_VALUE_TYPE ((value), (type)))
</programlisting>
<para>
Returns <link linkend="TRUE-CAPS">TRUE</link> if <parameter>value</parameter> holds (or contains) a value of <parameter>type</parameter>.
This macro will also check for <parameter>value</parameter> != <link linkend="NULL-CAPS">NULL</link> and issue a
warning if the check fails.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>
</entry></row>
<row><entry align="right"><parameter>type</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-VALUE-TYPE-CAPS">G_VALUE_TYPE()</title>
<programlisting>#define	G_VALUE_TYPE(value)		(((GValue*) (value))-&gt;g_type)
</programlisting>
<para>
Returns the type identifier of <parameter>value</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>A <link linkend="GValue">GValue</link> structure.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-VALUE-TYPE-NAME-CAPS">G_VALUE_TYPE_NAME()</title>
<programlisting>#define	G_VALUE_TYPE_NAME(value)	(g_type_name (G_VALUE_TYPE (value)))
</programlisting>
<para>
Returns the type name of <parameter>value</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>A <link linkend="GValue">GValue</link> structure.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-TYPE-IS-VALUE-CAPS">G_TYPE_IS_VALUE()</title>
<programlisting>#define	G_TYPE_IS_VALUE(type)		(g_type_check_is_value_type (type))
</programlisting>
<para>
Return whether the passed in type ID can be used for <link linkend="g-value-init">g_value_init</link>().
That is, this macro checks whether this type provides an implementation
of the <link linkend="GTypeValueTable">GTypeValueTable</link> functions required for a type to create a <link linkend="GValue">GValue</link> of.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>type</parameter>&nbsp;:</entry>
<entry>	  A <link linkend="GType">GType</link> value.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>Whether <parameter>type</parameter> is suitable as a <link linkend="GValue">GValue</link> type.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-TYPE-IS-VALUE-ABSTRACT-CAPS">G_TYPE_IS_VALUE_ABSTRACT()</title>
<programlisting>#define G_TYPE_IS_VALUE_ABSTRACT(type)          (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
</programlisting>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>type</parameter>&nbsp;:</entry>
<entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-IS-VALUE-CAPS">G_IS_VALUE()</title>
<programlisting>#define	G_IS_VALUE(value)		(G_TYPE_CHECK_VALUE (value))
</programlisting>
<para>
Returns <link linkend="TRUE-CAPS">TRUE</link> if <parameter>value</parameter> is a valid and initialized <link linkend="GValue">GValue</link> structure.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>A <link linkend="GValue">GValue</link> structure.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GValue">struct GValue</title>
<programlisting>struct GValue
{
  /*&lt; private &gt;*/
  GType		g_type;

  /* public for GTypeValueTable methods */
  union {
    gint	v_int;
    guint	v_uint;
    glong	v_long;
    gulong	v_ulong;
    gint64      v_int64;
    guint64     v_uint64;
    gfloat	v_float;
    gdouble	v_double;
    gpointer	v_pointer;
  } data[2];
};
</programlisting>
<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 <link linkend="GTypeValueTable">GTypeValueTable</link> structure, or implementations of
the g_value_*() API. That is, code portions which implement new fundamental
types.
<link linkend="GValue">GValue</link> users can not make any assumptions about how data is stored
within the 2 element <link linkend="GValue">GValue</link>.data[] union, and the g_type member should
only be accessed through the <link linkend="G-VALUE-TYPE-CAPS">G_VALUE_TYPE</link>() macro.
</para></refsect2>
<refsect2>
<title><anchor id="G-TYPE-VALUE-CAPS">G_TYPE_VALUE</title>
<programlisting>#define	G_TYPE_VALUE		(g_value_get_type ())
</programlisting>
<para>
Returns the type ID of the "GValue" type which is a boxed type,
used to pass around pointers to GValues.
</para></refsect2>
<refsect2>
<title><anchor id="G-TYPE-VALUE-ARRAY-CAPS">G_TYPE_VALUE_ARRAY</title>
<programlisting>#define	G_TYPE_VALUE_ARRAY	(g_value_array_get_type ())
</programlisting>
<para>
Returns the type ID of the "GValueArray" type which is a boxed type,
used to pass around pointers to GValueArrays.
</para></refsect2>
<refsect2>
<title><anchor id="g-value-init">g_value_init ()</title>
<programlisting><link linkend="GValue">GValue</link>*     g_value_init                    (<link linkend="GValue">GValue</link> *value,
                                             <link linkend="GType">GType</link> g_type);</programlisting>
<para>
Initializes <parameter>value</parameter> with the default value of <parameter>type</parameter>.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>value</parameter>&nbsp;:</entry>
<entry>		A zero-filled (uninitialized) <link linkend="GValue">GValue</link> structure.
</entry></row>
<row><entry align="right"><parameter>g_type</parameter>&nbsp;:</entry>
<entry>	Type the <link linkend="GValue">GValue</link> should hold values of.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>


</entry></row>
</tbody></tgroup></informaltable></refsect2>