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

New sections on naming conventions and NumExts

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/
-<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
@@ -20,6 +20,55 @@ as Standard Haskell Libraries sometime soon.
 
 <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>
@@ -307,12 +356,12 @@ The types supported are as follows:
 
 <tabular ca="ll">
 type    | number of bits @
-<hline> 
+<!-- <hline>  -->
 Word8    | 8  @
 Word16   | 16 @
 Word32   | 32 @
 Word64   | 64 @
-<hline> 
+<!-- <hline>  -->
 </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 @ 
-<hline> 
+<!-- <hline>  -->
 Int8    | 8  @
 Int16   | 16 @
 Int32   | 32 @
 Int64   | 64 @
-<hline> 
+<!-- <hline>  -->
 </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.
 
-<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.