[project @ 2001-04-05 09:10:35 by simonmar]

Add notes on parallel list comprehensions from Jeff Lewis.

diff --git a/ghc/docs/users_guide/5-00-notes.sgml b/ghc/docs/users_guide/5-00-notes.sgml
index b1377c3..11bc59f 100644 (file)
--- a/ghc/docs/users_guide/5-00-notes.sgml
+++ b/ghc/docs/users_guide/5-00-notes.sgml
@@ -50,7 +50,8 @@
         been removed.</para>
       </listitem>
       <listitem>
-       <para>Parallel list comprehensions added.</para>
+       <para>Parallel list comprehensions added.  See <xref
+       linkend="parallel-list-comprehensions">.</para>
       </listitem>
       <listitem>
        <para>Profiling: please use 
@@ -118,14 +119,28 @@
        linkend="sec-MVars">).</para>
       </listitem>
       <listitem>
-       <para>The <literal>Integer</literal> type now has an instance
-        of <literal>Bits</literal> (<xref linkend="sec-Bits">).</para>
+       <para>The <literal>Int</literal> and
+        <literal>Integer</literal> types now have instances of
+        <literal>Bits</literal> (<xref linkend="sec-Bits">).</para>
       </listitem>
       <listitem>
        <para>Package <literal>hssource</literal> has been added.  It
        contains a Haskell 98 abstract syntax, parser, lexer and pretty
        printer.  No documentation yet.</para>
       </listitem>
+      <listitem>
+       <para>The methods <literal>fromInt</literal> and
+       <literal>toInt</literal>, which used to be in class
+       <literal>Num</literal> but exported from module
+       <literal>Int</literal>, are no longer in class
+       <literal>Num</literal>.  They're still available from module
+       <literal>Int</literal>, however.</para> 
+
+       <para>In most cases, there should be no benefit from using
+       <literal>fromInt</literal> instead of
+       <literal>fromIntegral</literal>, which is specialised for all
+       integral types.</para>
+      </listitem>
     </itemizedlist>
   </sect2>
 

diff --git a/ghc/docs/users_guide/glasgow_exts.sgml b/ghc/docs/users_guide/glasgow_exts.sgml
index b0b36ba..bea9fcd 100644 (file)
--- a/ghc/docs/users_guide/glasgow_exts.sgml
+++ b/ghc/docs/users_guide/glasgow_exts.sgml
@@ -96,6 +96,15 @@ Executive summary of our extensions:
     </varlistentry>
 
     <varlistentry>
+      <term>Parallel list comprehensions</term>
+      <listitem>
+       <para>An extension to the list comprehension syntax to support
+       <literal>zipWith</literal>-like functionality.  See <xref
+       linkend="parallel-list-comprehensions">.</para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
       <term>Foreign calling:</term>
       <listitem>
        <para>Just what it sounds like.  We provide
@@ -533,6 +542,56 @@ qualifier list has just one element, a boolean expression.
 </para>
 </sect1>
 
+  <sect1 id="parallel-list-comprehensions">
+    <title>Parallel List Comprehensions</title>
+    <indexterm><primary>list comprehensions</primary><secondary>parallel</secondary>
+    </indexterm>
+    <indexterm><primary>parallel list comprehensions</primary>
+    </indexterm>
+
+    <para>Parallel list comprehensions are a natural extension to list
+    comprehensions.  List comprehensions can be thought of as a nice
+    syntax for writing maps and filters.  Parallel comprehensions
+    extend this to include the zipWith family.</para>
+
+    <para>A parallel list comprehension has multiple independent
+    branches of qualifier lists, each separated by a `|' symbol.  For
+    example, the following zips together two lists:</para>
+
+<programlisting>
+   [ (x, y) | x <- xs | y <- ys ] 
+</programlisting>
+
+    <para>The behavior of parallel list comprehensions follows that of
+    zip, in that the resulting list will have the same length as the
+    shortest branch.</para>
+
+    <para>We can define parallel list comprehensions by translation to
+    regular comprehensions.  Here's the basic idea:</para>
+
+    <para>Given a parallel comprehension of the form: </para>
+
+<programlisting>
+   [ e | p1 <- e11, p2 <- e12, ... 
+       | q1 <- e21, q2 <- e22, ... 
+       ... 
+   ] 
+</programlisting>
+
+    <para>This will be translated to: </para>
+
+<programlisting>
+   [ e | ((p1,p2), (q1,q2), ...) <- zipN [(p1,p2) | p1 <- e11, p2 <- e12, ...] 
+                                         [(q1,q2) | q1 <- e21, q2 <- e22, ...] 
+                                         ... 
+   ] 
+</programlisting>
+
+    <para>where `zipN' is the appropriate zip for the given number of
+    branches.</para>
+
+  </sect1>
+
   <sect1 id="sec-ffi">
     <title>The foreign interface</title>