[m-rev.] for review: document Java methods for manipulating Mercury lists

[Ian MacLarty]

doc/reference_manual.texi:
    Document how Mercury lists can be manipulated in Java code.

    Also document that one should use the equals method to
    compare bool and comparison_result values in Java code.

Index: doc/reference_manual.texi
===================================================================
RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
retrieving revision 1.436
diff -u -r1.436 reference_manual.texi
--- doc/reference_manual.texi	10 Dec 2009 19:40:57 -0000	1.436
+++ doc/reference_manual.texi	12 Jan 2010 05:53:19 -0000
@@ -6973,13 +6973,15 @@
 For the Mercury standard library type @samp{bool.bool}, there is a
 corresponding Java type, @code{bool.Bool_0}.  Java code can refer to the
 boolean data constructors @samp{yes} and @samp{no}, as @code{bool.YES}
-and @code{bool.NO} respectively.
+and @code{bool.NO} respectively (use the @samp{equals} method to
+test for equality between @samp{bool.bool} values).
 
 For the Mercury standard library type @samp{builtin.comparison_result}, there
 is a corresponding Java type, @code{builtin.Comparison_result_0}.  Java code
 can refer to the data constructors of this type, @samp{(<)}, @samp{(=)} and
 @samp{(>)}, as @code{builtin.COMPARE_LESS}, @code{builtin.COMPARE_EQUAL}
-and @code{builtin.COMPARE_GREATER} respectively.
+and @code{builtin.COMPARE_GREATER} respectively (use the @samp{equals} method
+to test for equality between @samp{builtin.comparison_result} values).
 
 Mercury variables of a type for which there is a Java @samp{pragma
 foreign_type} declaration (@pxref{Using foreign types from Mercury}) will be
@@ -6999,6 +7001,35 @@
 The first character of the type name will have its case inverted,
 and the name may be mangled to satisfy Java lexical rules.
 
+Mercury lists can be manipulated by Java code using the following static
+methods in the @samp{jmercury.list} package.
+
+ at example
+public static boolean is_empty(List_1 lst); /* test if a list is empty */
+public static Object det_head(List_1 lst); /* get the head of a non-empty list */
+public static List_1 det_tail(List_1 lst); /* get the tail of a non-empty list */
+public static List_1 empty_list(); /* create an empty list */
+public static List_1 cons(Object H, List_1 T); /* construct a list with the given head and tail */
+ at end example
+
+A @code{ListIterator} wrapper class that implements the
+ at code{Iterable} and @code{Iterator} interfaces is also provided
+in the @samp{jmercury.list} package.
+
+ at example
+public static class ListIterator<E>
+    implements java.lang.Iterable<E>, java.util.Iterator<E>
+ at end example
+
+This allows Java for-each syntax to be used with Mercury lists.
+
+ at example
+/* Print all the strings in a Mercury list merc_list. */
+for (String str : new jmercury.list.ListIterator<String>(merc_list)) @{
+    System.out.println(str);
+@}
+ at end example
+
 Java code generated by the Mercury compiler is placed in the @samp{jmercury}
 package.  Mercury module qualifiers are converted into a Java class name by
 concatenating the components with double underscore separators (@samp{__}).
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------