1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
6 Portably storing integers in pointer variables.
8 <!-- ##### SECTION Long_Description ##### -->
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:
15 int *ip = g_new (int, 1);
18 But this is inconvenient, and it's annoying to have to free the
19 memory at some later time.
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:
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:
36 p = (void*) (long) 42;
39 So GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. do the right thing
40 on the current platform.
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.
53 <!-- ##### SECTION See_Also ##### -->
58 <!-- ##### MACRO GINT_TO_POINTER ##### -->
60 Stuffs an integer into a pointer type.
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.
69 @i: integer to stuff into a pointer.
72 <!-- ##### MACRO GPOINTER_TO_INT ##### -->
74 Extracts an integer from a pointer. The integer must have
75 been stored in the pointer with GINT_TO_POINTER().
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.
84 @p: pointer containing an integer.
87 <!-- ##### MACRO GUINT_TO_POINTER ##### -->
89 Stuffs an unsigned integer into a pointer type.
92 @u: unsigned integer to stuff into the pointer.
95 <!-- ##### MACRO GPOINTER_TO_UINT ##### -->
97 Extracts an unsigned integer from a pointer. The integer must have
98 been stored in the pointer with GUINT_TO_POINTER().
101 @p: pointer to extract an unsigned integer from.
104 <!-- ##### MACRO GSIZE_TO_POINTER ##### -->
106 Stuffs a #gsize into a pointer type.
109 @s: #gsize to stuff into the pointer.
112 <!-- ##### MACRO GPOINTER_TO_SIZE ##### -->
114 Extracts a #gsize from a pointer. The #gsize must have
115 been stored in the pointer with GSIZE_TO_POINTER().
118 @p: pointer to extract a #gsize from.