[project @ 1998-01-30 17:29:12 by sof]

New sections on naming conventions and NumExts

diff --git a/ghc/docs/libraries/libs.sgml b/ghc/docs/libraries/libs.sgml
index d5c132d..7c41ea6 100644 (file)
--- a/ghc/docs/libraries/libs.sgml
+++ b/ghc/docs/libraries/libs.sgml
@@ -10,7 +10,7 @@
 <title>The Hugs-GHC Extension Libraries
 <author>Alastair Reid <tt/reid-alastair@cs.yale.edu/ 
         Simon Marlow <tt/simonm@dcs.gla.ac.uk/
 <title>The Hugs-GHC Extension Libraries
 <author>Alastair Reid <tt/reid-alastair@cs.yale.edu/ 
         Simon Marlow <tt/simonm@dcs.gla.ac.uk/

-<date>v0.8, 14 December 1997
+<date>v0.8, 28 January 1998

 <abstract>
 Hugs and GHC provide a common set of libraries to aid portability.
 This document specifies the interfaces to these libraries and documents
 <abstract>
 Hugs and GHC provide a common set of libraries to aid portability.
 This document specifies the interfaces to these libraries and documents

@@ -20,6 +20,55 @@ as Standard Haskell Libraries sometime soon.
 
 <toc>
 
 
 <toc>
 

+<sect> <idx/Naming conventions/ 
+<label id="sec:Naming conventions">
+<p>
+
+The set of interfaces specified in this document try to adhere to the
+following naming conventions: 
+
+<itemize>
+<item>
+Actions that create a new values have the prefix <tt/new/ followed by
+the name of the type of object they're creating, e.g., <tt/newIORef/,
+<tt/newChan/ etc.
+<item>
+Operations that read a value from a mutable object are prefixed with
+<tt/read/, and operations that update the contents have the prefix
+<tt/write/, e.g., <tt/readChan/, <tt/readIOArray/.
+
+Notes: 
+<itemize>
+<item>
+This differs from the convention used to name the operations for
+reading and writing to a file <tt/Handle/, where <tt/get/ and <tt/put/
+are used instead.
+<item>
+Operations provided by various concurrency abstractions, e.g., <tt/MVar/,
+<tt/CVar/ , also deviate from this naming scheme. This is perhaps
+defensible, since the read and write operations have additional
+behaviour, e.g., <tt/takeMVar/ tries to read the current value
+of an <tt/MVar/, locking it if it succeeds.
+</itemize>
+<item>
+Conversions operators have the form <tt/AToB/ where <tt/A/ and <tt/B/
+are the types we're converting between.
+<item>
+Operations that lazily read values from a mutable object/handle, have
+the form <tt/getXContents/, e.g., <tt/Channel.getChanContents/ and
+<tt/IO.hGetContents/. (OK, so the latter isn't called
+<tt/getHandleContents/, but you hopefully get the picture.)
+</itemize>
+
+<sect> <idx/LazyST/ <p>
+
+This library provides support for both <em/lazy/ and <em/strict/ state
+threads, as described in the PLDI '94 paper by John Launchbury and
+Simon Peyton Jones <cite id="LazyStateThreads">.  In addition to the
+monad <tt/ST/, it also provides mutable variables <tt/STRef/ and
+mutable arrays <tt/STArray/.  As the name suggests, the monad <tt/ST/
+instance is <em/lazy/.
+=======

 <sect> <idx/ST/ 
 <label id="sec:ST">
 <p>
 <sect> <idx/ST/ 
 <label id="sec:ST">
 <p>

@@ -307,12 +356,12 @@ The types supported are as follows:
 
 <tabular ca="ll">
 type    | number of bits @
 
 <tabular ca="ll">
 type    | number of bits @

-<hline> 
+<!-- <hline>  -->

 Word8    | 8  @
 Word16   | 16 @
 Word32   | 32 @
 Word64   | 64 @
 Word8    | 8  @
 Word16   | 16 @
 Word32   | 32 @
 Word64   | 64 @

-<hline> 
+<!-- <hline>  -->

 </tabular>
 
 For each type <it/W/ above, we provide the following functions and
 </tabular>
 
 For each type <it/W/ above, we provide the following functions and

@@ -402,12 +451,12 @@ supported are as follows:
 
 <tabular ca="ll">
 type    | number of bits @ 
 
 <tabular ca="ll">
 type    | number of bits @ 

-<hline> 
+<!-- <hline>  -->

 Int8    | 8  @
 Int16   | 16 @
 Int32   | 32 @
 Int64   | 64 @
 Int8    | 8  @
 Int16   | 16 @
 Int32   | 32 @
 Int64   | 64 @

-<hline> 
+<!-- <hline>  -->

 </tabular>
 
 For each type <it/I/ above, we provide the following instances.
 </tabular>
 
 For each type <it/I/ above, we provide the following instances.

@@ -512,8 +561,40 @@ Hugs provides <tt/Addr/ and <tt/nullAddr/ but does not provide any of
 the index, read or write functions.  They can be implemented using 
 GreenCard if required.
 
 the index, read or write functions.  They can be implemented using 
 GreenCard if required.
 

-<sect> <idx/ForeignObj/
-<label id="sec:ForeignObj">
+<sect> <idx/NumExts/
+<label id="sec:NumExts">
+<p>
+
+The <tt/NumExts/ interface collect together various numeric
+operations that have proven to be commonly useful 
+
+<tscreen> <verb>
+-- Going between Doubles and Floats:
+doubleToFloat :: Double -> Float
+floatToDouble :: Float  -> Double
+
+showHex       :: Integral a => a -> ShowS
+showOct       :: Integral a => a -> ShowS
+</verb> </tscreen>
+
+Notes: 
+<itemize>
+<item>
+    If <tt/doubleToFloat/ is applied to a <tt/Double/ that is within
+    the representable range for <tt/Float/, the result may be the next
+    higher or lower representable <tt/Float/ value. If the <tt/Double/
+    is out of range, the result is undefined.
+<item>
+    No loss of precision occurs in the other direction with
+    <tt/floatToDouble/, the floating value remains unchanged.
+<item>
+    <tt/showOct/ and <tt/showHex/ will prefix <tt/0o/ and <tt/0x/
+    respectively. Like <tt/Numeric.showInt/, these show functions
+    work on positive numbers only.
+</itemize>
+
+<sect> <idx/Foreign/
+<label id="sec:Foreign">

 <p>
 
 This module is provided by GHC but not by Hugs.
 <p>
 
 This module is provided by GHC but not by Hugs.