[m-rev.] for review: document MR_word_to_float and MR_float_to_word in ref. manual

[Julien Fischer]

Branches: main, 10.04

Mention MR_word_to_float and MR_float_to_word in the user's guide.

doc/reference_manual.texi:
 	Add a paragraph about MR_word_to_float() and MR_float_to_word().

 	Provide an example of their use in conjunction with the list access
 	macros.

Julien.

Index: reference_manual.texi
===================================================================
RCS file: /home/mercury/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.443
diff -u -r1.443 reference_manual.texi
--- reference_manual.texi	7 May 2010 03:12:24 -0000	1.443
+++ reference_manual.texi	6 Jul 2010 07:34:40 -0000
@@ -6915,6 +6915,25 @@
  Note that the use of these macros is subject to some caveats
  (@pxref{Memory management for C}).

+The implementation provides the macro @samp{MR_word_to_float} for converting a
+value of type @samp{MR_Word} to one of type @samp{MR_Float}, and the macro
+ at samp{MR_float_to_word} for converting a value of type @samp{MR_Float} to one
+of type @samp{MR_Word}.
+These macros must be used to perform these conversions since for some Mercury
+implementations @samp{sizeof(MR_Float)} is greater than @samp{sizeof(MR_Word)}.
+
+The following fragment of C code illustrates the correct way to extract the
+head of a Mercury list of floats.
+
+ at example
+MR_Float f;
+f = MR_word_to_float(MR_list_head(list));
+ at end example
+
+Omitting the call to @samp{MR_word_to_float} in the above example would yield
+incorrect results for implementations where @samp{sizeof(MR_Float)} is greater
+than @samp{sizeof(MR_Word)}.
+
  @node IL and C# data passing conventions
  @subsection IL and C# data passing conventions



--------------------------------------------------------------------------
mercury-reviews mailing list
Post messages to:       mercury-reviews at csse.unimelb.edu.au
Administrative Queries: owner-mercury-reviews at csse.unimelb.edu.au
Subscriptions:          mercury-reviews-request at csse.unimelb.edu.au
--------------------------------------------------------------------------