Documentation fixes.

[platform/upstream/glib.git] / docs / reference / glib / tmpl / type_conversion.sgml

diff --git a/docs/reference/glib/tmpl/type_conversion.sgml b/docs/reference/glib/tmpl/type_conversion.sgml
index 45138be..41527e5 100644 (file)
--- a/docs/reference/glib/tmpl/type_conversion.sgml
+++ b/docs/reference/glib/tmpl/type_conversion.sgml
@@ -2,37 +2,52 @@
 Type Conversion Macros
 
 <!-- ##### SECTION Short_Description ##### -->
-a portable method for storing #gint &amp; #guint values in #gpointer variables.
+
+portably storing integers in pointer variables.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-These macros provide a portable method of storing #gint and #guint values in
-#gpointer variables.
+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>
-Many of the GLib data types are based on storing #gpointer values,
-e.g. #GHashTable, #GList, #GSList, #GTree, and #GNode.
-By using the type conversion macros described below you can store #gint and
-#guint values inside a #gpointer. So you can, for example, create
-a hash table of #gint values, or a linked list of #guint values.
+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 GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. do the right thing
+on the current platform.
 </para>
 <para>
-The type conversion macros are necessary because the size of a #gpointer can
-vary across different platforms. So the type conversion has to be done
-carefully.
-</para>
+<warning>
 <para>
-Note that the reverse operation, storing #gpointer values in
-integer variables, is not supported, since an integer is not guaranteed to
-be large enough to store #gpointer values across all platforms.
+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>
-<para>
-To convert an integer value, a #gint, to a #gpointer, use #GINT_TO_POINTER.
-To convert it back to a #gint, use #GPOINTER_TO_INT.
-</para>
-<para>
-To convert an unsigned integer, a #guint, to a #gpointer, use
-#GUINT_TO_POINTER. To convert it back to a #guint, use #GPOINTER_TO_UINT.
+</warning>
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -42,37 +57,64 @@ To convert an unsigned integer, a #guint, to a #gpointer, use
 
 <!-- ##### MACRO GINT_TO_POINTER ##### -->
 <para>
-Converts a #gint to a #gpointer.
+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>
 
-@i: a #gint value.
-@Returns: the value converted to a #gpointer.
+@i: integer to stuff into a pointer.
 
 
 <!-- ##### MACRO GPOINTER_TO_INT ##### -->
 <para>
-Converts a #gpointer to a #gint.
+Extracts an integer from a pointer. The integer must have
+been stored in the pointer with GINT_TO_POINTER().
+</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>
 
-@p: a #gpointer value.
-@Returns: the value converted to a #gint.
+@p: pointer containing an integer.
 
 
 <!-- ##### MACRO GUINT_TO_POINTER ##### -->
 <para>
-Converts a #guint to a #gpointer.
+Stuffs an unsigned integer into a pointer type.
 </para>
 
-@u: a #guint value.
-@Returns: the value converted to a #gpointer.
+@u: unsigned integer to stuff into the pointer.
 
 
 <!-- ##### MACRO GPOINTER_TO_UINT ##### -->
 <para>
-Converts a #gpointer to a #guint.
+Extracts an unsigned integer from a pointer. The integer must have
+been stored in the pointer with GUINT_TO_POINTER().
+</para>
+
+@p: pointer to extract an unsigned integer from.
+
+
+<!-- ##### MACRO GSIZE_TO_POINTER ##### -->
+<para>
+Stuffs a #gsize into a pointer type.
+</para>
+
+@s: #gsize to stuff into the pointer.
+
+
+<!-- ##### MACRO GPOINTER_TO_SIZE ##### -->
+<para>
+Extracts a #gsize from a pointer. The #gsize must have
+been stored in the pointer with GSIZE_TO_POINTER().
 </para>
 
-@p: a #gpointer value.
-@Returns: the value converted to a #guint.
+@p: pointer to extract a #gsize from.