<refentry id="glib-Type-Conversion-Macros">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Type-Conversion-Macros.top_of_page">Type Conversion Macros</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Type Conversion Macros</refname>
<refpurpose>portably storing integers in pointer variables</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Type-Conversion-Macros.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

#define             <link linkend="GINT-TO-POINTER--CAPS">GINT_TO_POINTER</link>                     (i)
#define             <link linkend="GPOINTER-TO-INT--CAPS">GPOINTER_TO_INT</link>                     (p)

#define             <link linkend="GUINT-TO-POINTER--CAPS">GUINT_TO_POINTER</link>                    (u)
#define             <link linkend="GPOINTER-TO-UINT--CAPS">GPOINTER_TO_UINT</link>                    (p)
#define             <link linkend="GSIZE-TO-POINTER--CAPS">GSIZE_TO_POINTER</link>                    (s)
#define             <link linkend="GPOINTER-TO-SIZE--CAPS">GPOINTER_TO_SIZE</link>                    (p)
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Type-Conversion-Macros.description" role="desc">
<title role="desc.title">Description</title>
<para>
Many times GLib, GTK+, and other libraries allow you to pass "user
data" to a callback, in the form of a void pointer. From time to time
you want to pass an integer instead of a pointer. You could allocate
an integer, with something like:
<informalexample><programlisting>
 int *ip = g_new (int, 1);
 *ip = 42;
</programlisting></informalexample>
But this is inconvenient, and it's annoying to have to free the
memory at some later time.
</para>
<para>
Pointers are always at least 32 bits in size (on all platforms GLib
intends to support). Thus you can store at least 32-bit integer values
in a pointer value. Naively, you might try this, but it's incorrect:
<informalexample><programlisting>
 gpointer p;
 int i;
 p = (void*) 42;
 i = (int) p;
</programlisting></informalexample>
Again, that example was <emphasis>not</emphasis> correct, don't copy it.
The problem is that on some systems you need to do this:
<informalexample><programlisting>
 gpointer p;
 int i;
 p = (void*) (long) 42;
 i = (int) (long) p;
</programlisting></informalexample>
So <link linkend="GPOINTER-TO-INT--CAPS"><function>GPOINTER_TO_INT()</function></link>, <link linkend="GINT-TO-POINTER--CAPS"><function>GINT_TO_POINTER()</function></link>, etc. do the right thing
on the current platform.
</para>
<para>
<warning>
<para>
YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE IN ANY
WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
storing integers in pointers, and only preserve 32 bits of the
integer; values outside the range of a 32-bit integer will be mangled.
</para>
</warning>
</para>
</refsect1>

<refsect1 id="glib-Type-Conversion-Macros.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GINT-TO-POINTER--CAPS" role="macro">
<title>GINT_TO_POINTER()</title>
<indexterm zone="GINT-TO-POINTER--CAPS"><primary sortas="INT_TO_POINTER">GINT_TO_POINTER</primary></indexterm><programlisting>#define GINT_TO_POINTER(i)	((gpointer) (glong) (i))
</programlisting>
<para>
Stuffs an integer into a pointer type.
</para>
<para>
Remember, YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE
IN ANY WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
storing integers in pointers, and only preserve 32 bits of the
integer; values outside the range of a 32-bit integer will be mangled.
</para><variablelist role="params">
<varlistentry><term><parameter>i</parameter>&#160;:</term>
<listitem><simpara>integer to stuff into a pointer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GPOINTER-TO-INT--CAPS" role="macro">
<title>GPOINTER_TO_INT()</title>
<indexterm zone="GPOINTER-TO-INT--CAPS"><primary sortas="POINTER_TO_INT">GPOINTER_TO_INT</primary></indexterm><programlisting>#define GPOINTER_TO_INT(p)	((gint)  (glong) (p))
</programlisting>
<para>
Extracts an integer from a pointer. The integer must have
been stored in the pointer with <link linkend="GINT-TO-POINTER--CAPS"><function>GINT_TO_POINTER()</function></link>.
</para>
<para>
Remember, YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE
IN ANY WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
storing integers in pointers, and only preserve 32 bits of the
integer; values outside the range of a 32-bit integer will be mangled.
</para><variablelist role="params">
<varlistentry><term><parameter>p</parameter>&#160;:</term>
<listitem><simpara>pointer containing an integer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GUINT-TO-POINTER--CAPS" role="macro">
<title>GUINT_TO_POINTER()</title>
<indexterm zone="GUINT-TO-POINTER--CAPS"><primary sortas="UINT_TO_POINTER">GUINT_TO_POINTER</primary></indexterm><programlisting>#define GUINT_TO_POINTER(u)	((gpointer) (gulong) (u))
</programlisting>
<para>
Stuffs an unsigned integer into a pointer type.
</para><variablelist role="params">
<varlistentry><term><parameter>u</parameter>&#160;:</term>
<listitem><simpara>unsigned integer to stuff into the pointer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GPOINTER-TO-UINT--CAPS" role="macro">
<title>GPOINTER_TO_UINT()</title>
<indexterm zone="GPOINTER-TO-UINT--CAPS"><primary sortas="POINTER_TO_UINT">GPOINTER_TO_UINT</primary></indexterm><programlisting>#define GPOINTER_TO_UINT(p)	((guint) (gulong) (p))
</programlisting>
<para>
Extracts an unsigned integer from a pointer. The integer must have
been stored in the pointer with <link linkend="GUINT-TO-POINTER--CAPS"><function>GUINT_TO_POINTER()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>p</parameter>&#160;:</term>
<listitem><simpara>pointer to extract an unsigned integer from.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GSIZE-TO-POINTER--CAPS" role="macro">
<title>GSIZE_TO_POINTER()</title>
<indexterm zone="GSIZE-TO-POINTER--CAPS"><primary sortas="SIZE_TO_POINTER">GSIZE_TO_POINTER</primary></indexterm><programlisting>#define GSIZE_TO_POINTER(s)	((gpointer) (gsize) (s))
</programlisting>
<para>
Stuffs a <link linkend="gsize"><type>gsize</type></link> into a pointer type.
</para><variablelist role="params">
<varlistentry><term><parameter>s</parameter>&#160;:</term>
<listitem><simpara>#gsize to stuff into the pointer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="GPOINTER-TO-SIZE--CAPS" role="macro">
<title>GPOINTER_TO_SIZE()</title>
<indexterm zone="GPOINTER-TO-SIZE--CAPS"><primary sortas="POINTER_TO_SIZE">GPOINTER_TO_SIZE</primary></indexterm><programlisting>#define GPOINTER_TO_SIZE(p)	((gsize) (p))
</programlisting>
<para>
Extracts a <link linkend="gsize"><type>gsize</type></link> from a pointer. The <link linkend="gsize"><type>gsize</type></link> must have
been stored in the pointer with <link linkend="GSIZE-TO-POINTER--CAPS"><function>GSIZE_TO_POINTER()</function></link>.
</para><variablelist role="params">
<varlistentry><term><parameter>p</parameter>&#160;:</term>
<listitem><simpara>pointer to extract a <link linkend="gsize"><type>gsize</type></link> from.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
