docs/reference/glib/html/glib-Type-Conversion-Macros.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Type Conversion Macros</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-fundamentals.html" title="GLib Fundamentals">
   9 <link rel="prev" href="glib-Standard-Macros.html" title="Standard Macros">
  10 <link rel="next" href="glib-Byte-Order-Macros.html" title="Byte Order Macros">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-Standard-Macros.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-fundamentals.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <td><a accesskey="n" href="glib-Byte-Order-Macros.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-Type-Conversion-Macros.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Type-Conversion-Macros.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-Type-Conversion-Macros"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-Type-Conversion-Macros.top_of_page"></a>Type Conversion Macros</span></h2>
  34 <p>Type Conversion Macros — portably storing integers in pointer variables</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="glib-Type-Conversion-Macros.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;glib.h&gt;
  42
  43 #define             <a class="link" href="glib-Type-Conversion-Macros.html#GINT-TO-POINTER:CAPS" title="GINT_TO_POINTER()">GINT_TO_POINTER</a>                     (i)
  44 #define             <a class="link" href="glib-Type-Conversion-Macros.html#GPOINTER-TO-INT:CAPS" title="GPOINTER_TO_INT()">GPOINTER_TO_INT</a>                     (p)
  45
  46 #define             <a class="link" href="glib-Type-Conversion-Macros.html#GUINT-TO-POINTER:CAPS" title="GUINT_TO_POINTER()">GUINT_TO_POINTER</a>                    (u)
  47 #define             <a class="link" href="glib-Type-Conversion-Macros.html#GPOINTER-TO-UINT:CAPS" title="GPOINTER_TO_UINT()">GPOINTER_TO_UINT</a>                    (p)
  48 #define             <a class="link" href="glib-Type-Conversion-Macros.html#GSIZE-TO-POINTER:CAPS" title="GSIZE_TO_POINTER()">GSIZE_TO_POINTER</a>                    (s)
  49 #define             <a class="link" href="glib-Type-Conversion-Macros.html#GPOINTER-TO-SIZE:CAPS" title="GPOINTER_TO_SIZE()">GPOINTER_TO_SIZE</a>                    (p)
  50 </pre>
  51 </div>
  52 <div class="refsect1">
  53 <a name="glib-Type-Conversion-Macros.description"></a><h2>Description</h2>
  54 <p>
  55 Many times GLib, GTK+, and other libraries allow you to pass "user
  56 data" to a callback, in the form of a void pointer. From time to time
  57 you want to pass an integer instead of a pointer. You could allocate
  58 an integer, with something like:
  59 </p>
  60 <div class="informalexample"><pre class="programlisting">
  61   int *ip = g_new (int, 1);
  62   *ip = 42;
  63 </pre></div>
  64 <p>
  65 But this is inconvenient, and it's annoying to have to free the
  66 memory at some later time.
  67 </p>
  68 <p>
  69 Pointers are always at least 32 bits in size (on all platforms GLib
  70 intends to support). Thus you can store at least 32-bit integer values
  71 in a pointer value. Naively, you might try this, but it's incorrect:
  72 </p>
  73 <div class="informalexample"><pre class="programlisting">
  74   gpointer p;
  75   int i;
  76   p = (void*) 42;
  77   i = (int) p;
  78 </pre></div>
  79 <p>
  80 Again, that example was <span class="emphasis"><em>not</em></span> correct, don't copy it.
  81 The problem is that on some systems you need to do this:
  82 </p>
  83 <div class="informalexample"><pre class="programlisting">
  84   gpointer p;
  85   int i;
  86   p = (void*) (long) 42;
  87   i = (int) (long) p;
  88 </pre></div>
  89 <p>
  90 The GLib macros <a class="link" href="glib-Type-Conversion-Macros.html#GPOINTER-TO-INT:CAPS" title="GPOINTER_TO_INT()"><code class="function">GPOINTER_TO_INT()</code></a>, <a class="link" href="glib-Type-Conversion-Macros.html#GINT-TO-POINTER:CAPS" title="GINT_TO_POINTER()"><code class="function">GINT_TO_POINTER()</code></a>, etc. take care
  91 to do the right thing on the every platform.
  92 </p>
  93 <p>
  94 </p>
  95 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
  96 <h3 class="title">Warning</h3>
  97 <p>You may not store pointers in integers. This is not
  98 portable in any way, shape or form. These macros <span class="emphasis"><em>only</em></span>
  99 allow storing integers in pointers, and only preserve 32 bits of the
 100 integer; values outside the range of a 32-bit integer will be mangled.
 101 </p>
 102 </div>
 103 <p>
 104 </p>
 105 </div>
 106 <div class="refsect1">
 107 <a name="glib-Type-Conversion-Macros.details"></a><h2>Details</h2>
 108 <div class="refsect2">
 109 <a name="GINT-TO-POINTER:CAPS"></a><h3>GINT_TO_POINTER()</h3>
 110 <pre class="programlisting">#define GINT_TO_POINTER(i) ((gpointer) (glong) (i))
 111 </pre>
 112 <p>
 113 Stuffs an integer into a pointer type.
 114 </p>
 115 <p>
 116 Remember, you may not store pointers in integers. This is not portable
 117 in any way, shape or form. These macros <span class="emphasis"><em>only</em></span> allow
 118 storing integers in pointers, and only preserve 32 bits of the
 119 integer; values outside the range of a 32-bit integer will be mangled.
 120 </p>
 121 <div class="variablelist"><table border="0">
 122 <col align="left" valign="top">
 123 <tbody><tr>
 124 <td><p><span class="term"><em class="parameter"><code>i</code></em> :</span></p></td>
 125 <td>integer to stuff into a pointer</td>
 126 </tr></tbody>
 127 </table></div>
 128 </div>
 129 <hr>
 130 <div class="refsect2">
 131 <a name="GPOINTER-TO-INT:CAPS"></a><h3>GPOINTER_TO_INT()</h3>
 132 <pre class="programlisting">#define GPOINTER_TO_INT(p) ((gint)  (glong) (p))
 133 </pre>
 134 <p>
 135 Extracts an integer from a pointer. The integer must have
 136 been stored in the pointer with <a class="link" href="glib-Type-Conversion-Macros.html#GINT-TO-POINTER:CAPS" title="GINT_TO_POINTER()"><code class="function">GINT_TO_POINTER()</code></a>.
 137 </p>
 138 <p>
 139 Remember, you may not store pointers in integers. This is not portable
 140 in any way, shape or form. These macros <span class="emphasis"><em>only</em></span> allow
 141 storing integers in pointers, and only preserve 32 bits of the
 142 integer; values outside the range of a 32-bit integer will be mangled.
 143 </p>
 144 <div class="variablelist"><table border="0">
 145 <col align="left" valign="top">
 146 <tbody><tr>
 147 <td><p><span class="term"><em class="parameter"><code>p</code></em> :</span></p></td>
 148 <td>pointer containing an integer</td>
 149 </tr></tbody>
 150 </table></div>
 151 </div>
 152 <hr>
 153 <div class="refsect2">
 154 <a name="GUINT-TO-POINTER:CAPS"></a><h3>GUINT_TO_POINTER()</h3>
 155 <pre class="programlisting">#define GUINT_TO_POINTER(u) ((gpointer) (gulong) (u))
 156 </pre>
 157 <p>
 158 Stuffs an unsigned integer into a pointer type.
 159 </p>
 160 <div class="variablelist"><table border="0">
 161 <col align="left" valign="top">
 162 <tbody><tr>
 163 <td><p><span class="term"><em class="parameter"><code>u</code></em> :</span></p></td>
 164 <td>unsigned integer to stuff into the pointer</td>
 165 </tr></tbody>
 166 </table></div>
 167 </div>
 168 <hr>
 169 <div class="refsect2">
 170 <a name="GPOINTER-TO-UINT:CAPS"></a><h3>GPOINTER_TO_UINT()</h3>
 171 <pre class="programlisting">#define GPOINTER_TO_UINT(p) ((guint) (gulong) (p))
 172 </pre>
 173 <p>
 174 Extracts an unsigned integer from a pointer. The integer must have
 175 been stored in the pointer with <a class="link" href="glib-Type-Conversion-Macros.html#GUINT-TO-POINTER:CAPS" title="GUINT_TO_POINTER()"><code class="function">GUINT_TO_POINTER()</code></a>.
 176 </p>
 177 <div class="variablelist"><table border="0">
 178 <col align="left" valign="top">
 179 <tbody><tr>
 180 <td><p><span class="term"><em class="parameter"><code>p</code></em> :</span></p></td>
 181 <td>pointer to extract an unsigned integer from</td>
 182 </tr></tbody>
 183 </table></div>
 184 </div>
 185 <hr>
 186 <div class="refsect2">
 187 <a name="GSIZE-TO-POINTER:CAPS"></a><h3>GSIZE_TO_POINTER()</h3>
 188 <pre class="programlisting">#define GSIZE_TO_POINTER(s) ((gpointer) (gsize) (s))
 189 </pre>
 190 <p>
 191 Stuffs a <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> into a pointer type.
 192 </p>
 193 <div class="variablelist"><table border="0">
 194 <col align="left" valign="top">
 195 <tbody><tr>
 196 <td><p><span class="term"><em class="parameter"><code>s</code></em> :</span></p></td>
 197 <td>
 198 <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> to stuff into the pointer</td>
 199 </tr></tbody>
 200 </table></div>
 201 </div>
 202 <hr>
 203 <div class="refsect2">
 204 <a name="GPOINTER-TO-SIZE:CAPS"></a><h3>GPOINTER_TO_SIZE()</h3>
 205 <pre class="programlisting">#define GPOINTER_TO_SIZE(p) ((gsize) (p))
 206 </pre>
 207 <p>
 208 Extracts a <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> from a pointer. The <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> must have
 209 been stored in the pointer with <a class="link" href="glib-Type-Conversion-Macros.html#GSIZE-TO-POINTER:CAPS" title="GSIZE_TO_POINTER()"><code class="function">GSIZE_TO_POINTER()</code></a>.
 210 </p>
 211 <div class="variablelist"><table border="0">
 212 <col align="left" valign="top">
 213 <tbody><tr>
 214 <td><p><span class="term"><em class="parameter"><code>p</code></em> :</span></p></td>
 215 <td>pointer to extract a <a class="link" href="glib-Basic-Types.html#gsize" title="gsize"><span class="type">gsize</span></a> from</td>
 216 </tr></tbody>
 217 </table></div>
 218 </div>
 219 </div>
 220 </div>
 221 <div class="footer">
 222 <hr>
 223           Generated by GTK-Doc V1.18</div>
 224 </body>
 225 </html>