docs/reference/glib/tmpl/type_conversion.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Type Conversion Macros
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6 portably storing integers in pointer variables.
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9 <para>
  10 Many times GLib, GTK+, and other libraries allow you to pass "user
  11 data" to a callback, in the form of a void pointer. From time to time
  12 you want to pass an integer instead of a pointer. You could allocate
  13 an integer, with something like:
  14 <informalexample><programlisting>
  15  int *ip = g_new (int, 1);
  16  *ip = 42;
  17 </programlisting></informalexample>
  18 But this is inconvenient, and it's annoying to have to free the
  19 memory at some later time.
  20 </para>
  21 <para>
  22 Pointers are always at least 32 bits in size (on all platforms GLib
  23 intends to support). Thus you can store at least 32-bit integer values
  24 in a pointer value. Naively, you might try this, but it's incorrect:
  25 <informalexample><programlisting>
  26  gpointer p;
  27  int i;
  28  p = (void*) 42;
  29  i = (int) p;
  30 </programlisting></informalexample>
  31 Again, that example was <emphasis>not</emphasis> correct, don't copy it.
  32 The problem is that on some systems you need to do this:
  33 <informalexample><programlisting>
  34  gpointer p;
  35  int i;
  36  p = (void*) (long) 42;
  37  i = (int) (long) p;
  38 </programlisting></informalexample>
  39 So GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. do the right thing
  40 on the current platform.
  41 </para>
  42 <para>
  43 <warning>
  44 <para>
  45 YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE IN ANY
  46 WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
  47 storing integers in pointers, and only preserve 32 bits of the
  48 integer; values outside the range of a 32-bit integer will be mangled.
  49 </para>
  50 </warning>
  51 </para>
  52
  53 <!-- ##### SECTION See_Also ##### -->
  54 <para>
  55
  56 </para>
  57
  58 <!-- ##### MACRO GINT_TO_POINTER ##### -->
  59 <para>
  60 Stuffs an integer into a pointer type.
  61 </para>
  62 <para>
  63 Remember, YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE
  64 IN ANY WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
  65 storing integers in pointers, and only preserve 32 bits of the
  66 integer; values outside the range of a 32-bit integer will be mangled.
  67 </para>
  68
  69 @i: integer to stuff into a pointer.
  70
  71
  72 <!-- ##### MACRO GPOINTER_TO_INT ##### -->
  73 <para>
  74 Extracts an integer from a pointer. The integer must have
  75 been stored in the pointer with GINT_TO_POINTER().
  76 </para>
  77 <para>
  78 Remember, YOU MAY NOT STORE POINTERS IN INTEGERS. THIS IS NOT PORTABLE
  79 IN ANY WAY SHAPE OR FORM. These macros <emphasis>ONLY</emphasis> allow
  80 storing integers in pointers, and only preserve 32 bits of the
  81 integer; values outside the range of a 32-bit integer will be mangled.
  82 </para>
  83
  84 @p: pointer containing an integer.
  85
  86
  87 <!-- ##### MACRO GUINT_TO_POINTER ##### -->
  88 <para>
  89 Stuffs an unsigned integer into a pointer type.
  90 </para>
  91
  92 @u: unsigned integer to stuff into the pointer.
  93
  94
  95 <!-- ##### MACRO GPOINTER_TO_UINT ##### -->
  96 <para>
  97 Extracts an unsigned integer from a pointer. The integer must have
  98 been stored in the pointer with GUINT_TO_POINTER().
  99 </para>
 100
 101 @p: pointer to extract an unsigned integer from.
 102
 103
 104 <!-- ##### MACRO GSIZE_TO_POINTER ##### -->
 105 <para>
 106 Stuffs a #gsize into a pointer type.
 107 </para>
 108
 109 @s: #gsize to stuff into the pointer.
 110
 111
 112 <!-- ##### MACRO GPOINTER_TO_SIZE ##### -->
 113 <para>
 114 Extracts a #gsize from a pointer. The #gsize must have
 115 been stored in the pointer with GSIZE_TO_POINTER().
 116 </para>
 117
 118 @p: pointer to extract a #gsize from.
 119
 120