<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [

<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="gobject-Generic-values">
<refmeta>
<refentrytitle role="top_of_page" id="gobject-Generic-values.top_of_page">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>

<refsect1 id="gobject-Generic-values.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-VALUE-HOLDS:CAPS">G_VALUE_HOLDS</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-VALUE-TYPE:CAPS">G_VALUE_TYPE</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-VALUE-TYPE-NAME:CAPS">G_VALUE_TYPE_NAME</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-TYPE-IS-VALUE:CAPS">G_TYPE_IS_VALUE</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-TYPE-IS-VALUE-ABSTRACT:CAPS">G_TYPE_IS_VALUE_ABSTRACT</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-IS-VALUE:CAPS">G_IS_VALUE</link><phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GValue"><returnvalue>GValue</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-value-init">g_value_init</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-copy">g_value_copy</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GValue"><returnvalue>GValue</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-value-reset">g_value_reset</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-unset">g_value_unset</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-init-from-instance">g_value_init_from_instance</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-set-instance">g_value_set_instance</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-fits-pointer">g_value_fits_pointer</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-peek-pointer">g_value_peek_pointer</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-type-compatible">g_value_type_compatible</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-type-transformable">g_value_type_transformable</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-transform">g_value_transform</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><phrase role="c_punctuation">(</phrase><link linkend="GValueTransform">*GValueTransform</link><phrase role="c_punctuation">)</phrase>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-value-register-transform-func">g_value_register_transform_func</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="g-strdup-value-contents">g_strdup_value_contents</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<anchor id="GValue"/><refsect1 id="gobject-Generic-values.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-VALUE-INIT:CAPS">G_VALUE_INIT</link></entry></row>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GValue-struct">GValue</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-TYPE-VALUE:CAPS">G_TYPE_VALUE</link></entry></row>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-TYPE-VALUE-ARRAY:CAPS">G_TYPE_VALUE_ARRAY</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="gobject-Generic-values.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GBoxed">GBoxed</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GValue
</screen>
</refsect1>

<refsect1 id="gobject-Generic-values.includes"><title>Includes</title><synopsis>#include &lt;glib-object.h&gt;
</synopsis></refsect1>

<refsect1 id="gobject-Generic-values.description" role="desc">
<title role="desc.title">Description</title>
<para>The <link linkend="GValue"><type>GValue</type></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"><type>GValue</type></link> structure always determines the
type of the associated value.
To create an undefined <link linkend="GValue"><type>GValue</type></link> structure, simply create a zero-filled
<link linkend="GValue"><type>GValue</type></link> structure. To initialize the <link linkend="GValue"><type>GValue</type></link>, use the <link linkend="g-value-init"><function>g_value_init()</function></link>
function. A <link linkend="GValue"><type>GValue</type></link> cannot be used until it is initialized.
The basic type operations (such as freeing and copying) are determined
by the <link linkend="GTypeValueTable"><type>GTypeValueTable</type></link> associated with the type ID stored in the <link linkend="GValue"><type>GValue</type></link>.
Other <link linkend="GValue"><type>GValue</type></link> operations (such as converting values between types) are
provided by this interface.</para>
<para>The code in the example program below demonstrates <link linkend="GValue"><type>GValue</type></link>'s
features.</para>
<informalexample><programlisting role="example"><![CDATA[
#include <glib-object.h>

static void
int2string (const GValue *src_value,
            GValue       *dest_value)
{
  if (g_value_get_int (src_value) == 42)
    g_value_set_static_string (dest_value, "An important number");
  else
    g_value_set_static_string (dest_value, "What's that?");
}

int
main (int   argc,
      char *argv[])
{
  // GValues must be initialized
  GValue a = G_VALUE_INIT;
  GValue b = G_VALUE_INIT;
  const gchar *message;

  // The GValue starts empty
  g_assert (!G_VALUE_HOLDS_STRING (&a));

  // Put a string in it
  g_value_init (&a, G_TYPE_STRING);
  g_assert (G_VALUE_HOLDS_STRING (&a));
  g_value_set_static_string (&a, "Hello, world!");
  g_printf ("%s\n", g_value_get_string (&a));

  // Reset it to its pristine state
  g_value_unset (&a);

  // It can then be reused for another type
  g_value_init (&a, G_TYPE_INT);
  g_value_set_int (&a, 42);

  // Attempt to transform it into a GValue of type STRING
  g_value_init (&b, G_TYPE_STRING);

  // An INT is transformable to a STRING
  g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));

  g_value_transform (&a, &b);
  g_printf ("%s\n", g_value_get_string (&b));

  // Attempt to transform it again using a custom transform function
  g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
  g_value_transform (&a, &b);
  g_printf ("%s\n", g_value_get_string (&b));
  return 0;
}
]]></programlisting></informalexample>
<para></para>

</refsect1>
<refsect1 id="gobject-Generic-values.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="G-VALUE-HOLDS:CAPS" role="macro">
<title>G_VALUE_HOLDS()</title>
<indexterm zone="G-VALUE-HOLDS:CAPS"><primary sortas="VALUE_HOLDS">G_VALUE_HOLDS</primary></indexterm>
<programlisting language="C">#define G_VALUE_HOLDS(value,type)&#160;(G_TYPE_CHECK_VALUE_TYPE ((value), (type)))
</programlisting>
<para>Checks 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"><literal>NULL</literal></link> and issue a
warning if the check fails.</para>
<refsect3 id="G-VALUE-HOLDS.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>A <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>type</para></entry>
<entry role="parameter_description"><para>A <link linkend="GType"><type>GType</type></link> value.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="G-VALUE-HOLDS.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>value</parameter>
holds the <parameter>type</parameter>
.</para>
</refsect3></refsect2>
<refsect2 id="G-VALUE-TYPE:CAPS" role="macro">
<title>G_VALUE_TYPE()</title>
<indexterm zone="G-VALUE-TYPE:CAPS"><primary sortas="VALUE_TYPE">G_VALUE_TYPE</primary></indexterm>
<programlisting language="C">#define&#160;G_VALUE_TYPE(value)		(((GValue*) (value))-&gt;g_type)
</programlisting>
<para>Get the type identifier of <parameter>value</parameter>
.</para>
<refsect3 id="G-VALUE-TYPE.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>A <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="G-VALUE-TYPE.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GType"><type>GType</type></link>.</para>
</refsect3></refsect2>
<refsect2 id="G-VALUE-TYPE-NAME:CAPS" role="macro">
<title>G_VALUE_TYPE_NAME()</title>
<indexterm zone="G-VALUE-TYPE-NAME:CAPS"><primary sortas="VALUE_TYPE_NAME">G_VALUE_TYPE_NAME</primary></indexterm>
<programlisting language="C">#define&#160;G_VALUE_TYPE_NAME(value)&#160;(g_type_name (G_VALUE_TYPE (value)))
</programlisting>
<para>Gets the type name of <parameter>value</parameter>
.</para>
<refsect3 id="G-VALUE-TYPE-NAME.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>A <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="G-VALUE-TYPE-NAME.returns" role="returns">
<title>Returns</title>
<para> the type name.</para>
</refsect3></refsect2>
<refsect2 id="G-TYPE-IS-VALUE:CAPS" role="macro">
<title>G_TYPE_IS_VALUE()</title>
<indexterm zone="G-TYPE-IS-VALUE:CAPS"><primary sortas="TYPE_IS_VALUE">G_TYPE_IS_VALUE</primary></indexterm>
<programlisting language="C">#define&#160;G_TYPE_IS_VALUE(type)		(g_type_check_is_value_type (type))
</programlisting>
<para>Checks whether the passed in type ID can be used for <link linkend="g-value-init"><function>g_value_init()</function></link>.
That is, this macro checks whether this type provides an implementation
of the <link linkend="GTypeValueTable"><type>GTypeValueTable</type></link> functions required for a type to create a <link linkend="GValue"><type>GValue</type></link> of.</para>
<refsect3 id="G-TYPE-IS-VALUE.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>type</para></entry>
<entry role="parameter_description"><para>A <link linkend="GType"><type>GType</type></link> value.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="G-TYPE-IS-VALUE.returns" role="returns">
<title>Returns</title>
<para> Whether <parameter>type</parameter>
is suitable as a <link linkend="GValue"><type>GValue</type></link> type.</para>
</refsect3></refsect2>
<refsect2 id="G-TYPE-IS-VALUE-ABSTRACT:CAPS" role="macro">
<title>G_TYPE_IS_VALUE_ABSTRACT()</title>
<indexterm zone="G-TYPE-IS-VALUE-ABSTRACT:CAPS"><primary sortas="TYPE_IS_VALUE_ABSTRACT">G_TYPE_IS_VALUE_ABSTRACT</primary></indexterm>
<programlisting language="C">#define G_TYPE_IS_VALUE_ABSTRACT(type)          (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
</programlisting>
<para>Checks if <parameter>type</parameter>
 is an abstract value type.  An abstract value type introduces
a value table, but can't be used for <link linkend="g-value-init"><function>g_value_init()</function></link> and is normally used as
an abstract base type for derived value types.</para>
<refsect3 id="G-TYPE-IS-VALUE-ABSTRACT.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>type</para></entry>
<entry role="parameter_description"><para>A <link linkend="GType"><type>GType</type></link> value</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="G-TYPE-IS-VALUE-ABSTRACT.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success</para>
</refsect3></refsect2>
<refsect2 id="G-IS-VALUE:CAPS" role="macro">
<title>G_IS_VALUE()</title>
<indexterm zone="G-IS-VALUE:CAPS"><primary sortas="IS_VALUE">G_IS_VALUE</primary></indexterm>
<programlisting language="C">#define&#160;G_IS_VALUE(value)		(G_TYPE_CHECK_VALUE (value))
</programlisting>
<para>Checks if <parameter>value</parameter>
 is a valid and initialized <link linkend="GValue"><type>GValue</type></link> structure.</para>
<refsect3 id="G-IS-VALUE.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>A <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="G-IS-VALUE.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success.</para>
</refsect3></refsect2>
<refsect2 id="g-value-init" role="function">
<title>g_value_init&#160;()</title>
<indexterm zone="g-value-init"><primary sortas="value_init">g_value_init</primary></indexterm>
<programlisting language="C"><link linkend="GValue"><returnvalue>GValue</returnvalue></link>&#160;*
g_value_init (<parameter><link linkend="GValue"><type>GValue</type></link> *value</parameter>,
              <parameter><link linkend="GType"><type>GType</type></link> g_type</parameter>);</programlisting>
<para>Initializes <parameter>value</parameter>
 with the default value of <parameter>type</parameter>
.</para>
<refsect3 id="g-value-init.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>A zero-filled (uninitialized) <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>g_type</para></entry>
<entry role="parameter_description"><para>Type the <link linkend="GValue"><type>GValue</type></link> should hold values of.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-value-init.returns" role="returns">
<title>Returns</title>
<para>the <link linkend="GValue"><type>GValue</type></link> structure that has been passed in. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-value-copy" role="function">
<title>g_value_copy&#160;()</title>
<indexterm zone="g-value-copy"><primary sortas="value_copy">g_value_copy</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_value_copy (<parameter>const <link linkend="GValue"><type>GValue</type></link> *src_value</parameter>,
              <parameter><link linkend="GValue"><type>GValue</type></link> *dest_value</parameter>);</programlisting>
<para>Copies the value of <parameter>src_value</parameter>
 into <parameter>dest_value</parameter>
.</para>
<refsect3 id="g-value-copy.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>src_value</para></entry>
<entry role="parameter_description"><para>An initialized <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dest_value</para></entry>
<entry role="parameter_description"><para>An initialized <link linkend="GValue"><type>GValue</type></link> structure of the same type as <parameter>src_value</parameter>
.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-value-reset" role="function">
<title>g_value_reset&#160;()</title>
<indexterm zone="g-value-reset"><primary sortas="value_reset">g_value_reset</primary></indexterm>
<programlisting language="C"><link linkend="GValue"><returnvalue>GValue</returnvalue></link>&#160;*
g_value_reset (<parameter><link linkend="GValue"><type>GValue</type></link> *value</parameter>);</programlisting>
<para>Clears the current value in <parameter>value</parameter>
 and resets it to the default value
(as if the value had just been initialized).</para>
<refsect3 id="g-value-reset.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>An initialized <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-value-reset.returns" role="returns">
<title>Returns</title>
<para> the <link linkend="GValue"><type>GValue</type></link> structure that has been passed in</para>
</refsect3></refsect2>
<refsect2 id="g-value-unset" role="function">
<title>g_value_unset&#160;()</title>
<indexterm zone="g-value-unset"><primary sortas="value_unset">g_value_unset</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_value_unset (<parameter><link linkend="GValue"><type>GValue</type></link> *value</parameter>);</programlisting>
<para>Clears the current value in <parameter>value</parameter>
 (if any) and "unsets" the type,
this releases all resources associated with this GValue. An unset
value is the same as an uninitialized (zero-filled) <link linkend="GValue"><type>GValue</type></link>
structure.</para>
<refsect3 id="g-value-unset.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>An initialized <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-value-init-from-instance" role="function" condition="since:2.42">
<title>g_value_init_from_instance&#160;()</title>
<indexterm zone="g-value-init-from-instance" role="2.42"><primary sortas="value_init_from_instance">g_value_init_from_instance</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_value_init_from_instance (<parameter><link linkend="GValue"><type>GValue</type></link> *value</parameter>,
                            <parameter><link linkend="gpointer"><type>gpointer</type></link> instance</parameter>);</programlisting>
<para>Initializes and sets <parameter>value</parameter>
 from an instantiatable type via the
value_table's <link linkend="collect-value"><function>collect_value()</function></link> function.</para>
<para>Note: The <parameter>value</parameter>
 will be initialised with the exact type of
<parameter>instance</parameter>
.  If you wish to set the <parameter>value</parameter>
's type to a different GType
(such as a parent class GType), you need to manually call
<link linkend="g-value-init"><function>g_value_init()</function></link> and <link linkend="g-value-set-instance"><function>g_value_set_instance()</function></link>.</para>
<refsect3 id="g-value-init-from-instance.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>An uninitialized <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>instance</para></entry>
<entry role="parameter_description"><para>the instance. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>type</acronym> GObject.TypeInstance]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.42">2.42</link></para></refsect2>
<refsect2 id="g-value-set-instance" role="function">
<title>g_value_set_instance&#160;()</title>
<indexterm zone="g-value-set-instance"><primary sortas="value_set_instance">g_value_set_instance</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_value_set_instance (<parameter><link linkend="GValue"><type>GValue</type></link> *value</parameter>,
                      <parameter><link linkend="gpointer"><type>gpointer</type></link> instance</parameter>);</programlisting>
<para>Sets <parameter>value</parameter>
 from an instantiatable type via the
value_table's <link linkend="collect-value"><function>collect_value()</function></link> function.</para>
<refsect3 id="g-value-set-instance.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>An initialized <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>instance</para></entry>
<entry role="parameter_description"><para>the instance. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-value-fits-pointer" role="function">
<title>g_value_fits_pointer&#160;()</title>
<indexterm zone="g-value-fits-pointer"><primary sortas="value_fits_pointer">g_value_fits_pointer</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_value_fits_pointer (<parameter>const <link linkend="GValue"><type>GValue</type></link> *value</parameter>);</programlisting>
<para>Determines if <parameter>value</parameter>
 will fit inside the size of a pointer value.
This is an internal function introduced mainly for C marshallers.</para>
<refsect3 id="g-value-fits-pointer.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>An initialized <link linkend="GValue"><type>GValue</type></link> structure.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-value-fits-pointer.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>value</parameter>
will fit inside a pointer value.</para>
</refsect3></refsect2>
<refsect2 id="g-value-peek-pointer" role="function">
<title>g_value_peek_pointer&#160;()</title>
<indexterm zone="g-value-peek-pointer"><primary sortas="value_peek_pointer">g_value_peek_pointer</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
g_value_peek_pointer (<parameter>const <link linkend="GValue"><type>GValue</type></link> *value</parameter>);</programlisting>
<para>Returns the value contents as pointer. This function asserts that
<link linkend="g-value-fits-pointer"><function>g_value_fits_pointer()</function></link> returned <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> for the passed in value.
This is an internal function introduced mainly for C marshallers.</para>
<refsect3 id="g-value-peek-pointer.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para>An initialized <link linkend="GValue"><type>GValue</type></link> structure</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-value-peek-pointer.returns" role="returns">
<title>Returns</title>
<para>the value contents as pointer. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="g-value-type-compatible" role="function">
<title>g_value_type_compatible&#160;()</title>
<indexterm zone="g-value-type-compatible"><primary sortas="value_type_compatible">g_value_type_compatible</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_value_type_compatible (<parameter><link linkend="GType"><type>GType</type></link> src_type</parameter>,
                         <parameter><link linkend="GType"><type>GType</type></link> dest_type</parameter>);</programlisting>
<para>Returns whether a <link linkend="GValue"><type>GValue</type></link> of type <parameter>src_type</parameter>
 can be copied into
a <link linkend="GValue"><type>GValue</type></link> of type <parameter>dest_type</parameter>
.</para>
<refsect3 id="g-value-type-compatible.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>src_type</para></entry>
<entry role="parameter_description"><para>source type to be copied.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dest_type</para></entry>
<entry role="parameter_description"><para>destination type for copying.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-value-type-compatible.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <link linkend="g-value-copy"><function>g_value_copy()</function></link> is possible with <parameter>src_type</parameter>
and <parameter>dest_type</parameter>
.</para>
</refsect3></refsect2>
<refsect2 id="g-value-type-transformable" role="function">
<title>g_value_type_transformable&#160;()</title>
<indexterm zone="g-value-type-transformable"><primary sortas="value_type_transformable">g_value_type_transformable</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_value_type_transformable (<parameter><link linkend="GType"><type>GType</type></link> src_type</parameter>,
                            <parameter><link linkend="GType"><type>GType</type></link> dest_type</parameter>);</programlisting>
<para>Check whether <link linkend="g-value-transform"><function>g_value_transform()</function></link> is able to transform values
of type <parameter>src_type</parameter>
 into values of type <parameter>dest_type</parameter>
. Note that for
the types to be transformable, they must be compatible or a
transformation function must be registered.</para>
<refsect3 id="g-value-type-transformable.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>src_type</para></entry>
<entry role="parameter_description"><para>Source type.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dest_type</para></entry>
<entry role="parameter_description"><para>Target type.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-value-type-transformable.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the transformation is possible, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise.</para>
</refsect3></refsect2>
<refsect2 id="g-value-transform" role="function">
<title>g_value_transform&#160;()</title>
<indexterm zone="g-value-transform"><primary sortas="value_transform">g_value_transform</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_value_transform (<parameter>const <link linkend="GValue"><type>GValue</type></link> *src_value</parameter>,
                   <parameter><link linkend="GValue"><type>GValue</type></link> *dest_value</parameter>);</programlisting>
<para>Tries to cast the contents of <parameter>src_value</parameter>
 into a type appropriate
to store in <parameter>dest_value</parameter>
, e.g. to transform a <link linkend="G-TYPE-INT:CAPS"><literal>G_TYPE_INT</literal></link> value
into a <link linkend="G-TYPE-FLOAT:CAPS"><literal>G_TYPE_FLOAT</literal></link> 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>
<refsect3 id="g-value-transform.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>src_value</para></entry>
<entry role="parameter_description"><para>Source value.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dest_value</para></entry>
<entry role="parameter_description"><para>Target value.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-value-transform.returns" role="returns">
<title>Returns</title>
<para> Whether a transformation rule was found and could be applied.
Upon failing transformations, <parameter>dest_value</parameter>
is left untouched.</para>
</refsect3></refsect2>
<refsect2 id="GValueTransform" role="function">
<title>GValueTransform&#160;()</title>
<indexterm zone="GValueTransform"><primary sortas="ValueTransform">GValueTransform</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
<phrase role="c_punctuation">(</phrase>*GValueTransform<phrase role="c_punctuation">)</phrase> (<parameter>const <link linkend="GValue"><type>GValue</type></link> *src_value</parameter>,
                    <parameter><link linkend="GValue"><type>GValue</type></link> *dest_value</parameter>);</programlisting>
<para>The type of value transformation functions which can be registered with
<link linkend="g-value-register-transform-func"><function>g_value_register_transform_func()</function></link>.</para>
<para><parameter>dest_value</parameter>
 will be initialized to the correct destination type.</para>
<refsect3 id="GValueTransform.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>src_value</para></entry>
<entry role="parameter_description"><para>Source value.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dest_value</para></entry>
<entry role="parameter_description"><para>Target value.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-value-register-transform-func" role="function">
<title>g_value_register_transform_func&#160;()</title>
<indexterm zone="g-value-register-transform-func"><primary sortas="value_register_transform_func">g_value_register_transform_func</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_value_register_transform_func (<parameter><link linkend="GType"><type>GType</type></link> src_type</parameter>,
                                 <parameter><link linkend="GType"><type>GType</type></link> dest_type</parameter>,
                                 <parameter><link linkend="GValueTransform"><type>GValueTransform</type></link> transform_func</parameter>);</programlisting>
<para>Registers a value transformation function for use in <link linkend="g-value-transform"><function>g_value_transform()</function></link>.
A previously registered transformation function for <parameter>src_type</parameter>
 and <parameter>dest_type</parameter>

will be replaced.</para>

<para><emphasis role="annotation">[<acronym>skip</acronym>]</emphasis></para><refsect3 id="g-value-register-transform-func.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>src_type</para></entry>
<entry role="parameter_description"><para>Source type.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>dest_type</para></entry>
<entry role="parameter_description"><para>Target type.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>transform_func</para></entry>
<entry role="parameter_description"><para>a function which transforms values of type <parameter>src_type</parameter>
into value of type <parameter>dest_type</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="g-strdup-value-contents" role="function">
<title>g_strdup_value_contents&#160;()</title>
<indexterm zone="g-strdup-value-contents"><primary sortas="strdup_value_contents">g_strdup_value_contents</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
g_strdup_value_contents (<parameter>const <link linkend="GValue"><type>GValue</type></link> *value</parameter>);</programlisting>
<para>Return a newly allocated string, which describes the contents of a
<link linkend="GValue"><type>GValue</type></link>.  The main purpose of this function is to describe <link linkend="GValue"><type>GValue</type></link>
contents for debugging output, the way in which the contents are
described may change between different GLib versions.</para>
<refsect3 id="g-strdup-value-contents.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>value</para></entry>
<entry role="parameter_description"><para><link linkend="GValue"><type>GValue</type></link> which contents are to be described.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-strdup-value-contents.returns" role="returns">
<title>Returns</title>
<para> Newly allocated string.</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="gobject-Generic-values.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="G-VALUE-INIT:CAPS" role="macro" condition="since:2.30">
<title>G_VALUE_INIT</title>
<indexterm zone="G-VALUE-INIT:CAPS" role="2.30"><primary sortas="VALUE_INIT">G_VALUE_INIT</primary></indexterm>
<programlisting language="C">#define G_VALUE_INIT  { 0, { { 0 } } }
</programlisting>
<para>A <link linkend="GValue"><type>GValue</type></link> must be initialized before it can be used. This macro can
be used as initializer instead of an explicit <literal>{ 0 }</literal> when declaring
a variable, but it cannot be assigned to a variable.</para>
<informalexample><programlisting role="example"><![CDATA[
  GValue value = G_VALUE_INIT;
]]></programlisting></informalexample>
<para></para>
<para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="GValue-struct" role="struct">
<title>GValue</title>
<indexterm zone="GValue-struct"><primary sortas="Value">GValue</primary></indexterm>
<programlisting language="C">typedef struct {
} GValue;
</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"><type>GTypeValueTable</type></link> structure, or implementations of
the g_value_*() API. That is, code portions which implement new fundamental
types.
<link linkend="GValue"><type>GValue</type></link> users cannot make any assumptions about how data is stored
within the 2 element <parameter>data</parameter>
 union, and the <parameter>g_type</parameter>
 member should
only be accessed through the <link linkend="G-VALUE-TYPE:CAPS"><function>G_VALUE_TYPE()</function></link> macro.</para>
</refsect2>
<refsect2 id="G-TYPE-VALUE:CAPS" role="macro">
<title>G_TYPE_VALUE</title>
<indexterm zone="G-TYPE-VALUE:CAPS"><primary sortas="TYPE_VALUE">G_TYPE_VALUE</primary></indexterm>
<programlisting language="C">#define G_TYPE_VALUE (g_value_get_type ())
</programlisting>
<para>The type ID of the "GValue" type which is a boxed type,
used to pass around pointers to GValues.</para>
</refsect2>
<refsect2 id="G-TYPE-VALUE-ARRAY:CAPS" role="macro" condition="deprecated:2.32: Use #GArray instead of #GValueArray">
<title>G_TYPE_VALUE_ARRAY</title>
<indexterm zone="G-TYPE-VALUE-ARRAY:CAPS" role="deprecated"><primary sortas="TYPE_VALUE_ARRAY">G_TYPE_VALUE_ARRAY</primary></indexterm>
<programlisting language="C">#define G_TYPE_VALUE_ARRAY (g_value_array_get_type ()) GLIB_DEPRECATED_MACRO_IN_2_32_FOR(G_TYPE_ARRAY)
</programlisting>
<warning><para><literal>G_TYPE_VALUE_ARRAY</literal> has been deprecated since version 2.32 and should not be used in newly-written code.</para> <para>Use <link linkend="GArray"><type>GArray</type></link> instead of <link linkend="GValueArray"><type>GValueArray</type></link></para>
</warning>
<para>The type ID of the "GValueArray" type which is a boxed type,
used to pass around pointers to GValueArrays.</para>
</refsect2>

</refsect1>
<refsect1 id="gobject-Generic-values.see-also">
<title>See Also</title>
<para>The fundamental types which all support <link linkend="GValue"><type>GValue</type></link>
operations and thus can be used as a type initializer for
<link linkend="g-value-init"><function>g_value_init()</function></link> are defined by a separate interface.  See the
<link linkend="gobject-Standard-Parameter-and-Value-Types">standard values API</link>
for details</para>

</refsect1>

</refentry>
