[project @ 2002-07-02 10:34:52 by simonmar]

[ghc-base.git] / GHC / Base.lhs

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index b19e83a..3945397 100644 (file)
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -368,21 +368,34 @@ mapFB c f x ys = c (f x) ys
 %*********************************************************
 
 \begin{code}
+-- |The 'Bool' type is an enumeration.  It is defined with 'False'
+-- first so that the corresponding 'Enum' instance will give @'fromEnum'
+-- False@ the value zero, and @'fromEnum' True@ the value 1.
 data  Bool  =  False | True  deriving (Eq, Ord)
        -- Read in GHC.Read, Show in GHC.Show
 
 -- Boolean functions
 
-(&&), (||)             :: Bool -> Bool -> Bool
+-- | Boolean \"and\"
+(&&)                   :: Bool -> Bool -> Bool
 True  && x             =  x
 False && _             =  False
+
+-- | Boolean \"or\"
+(||)                   :: Bool -> Bool -> Bool
 True  || _             =  True
 False || x             =  x
 
+-- | Boolean \"not\"
 not                    :: Bool -> Bool
 not True               =  False
 not False              =  True
 
+-- |'otherwise' is defined as the value 'True'; it helps to make
+-- guards more readable.  eg.
+--
+-- >  f x | x \< 0     = ...
+-- >      | otherwise = ...
 otherwise              :: Bool
 otherwise              =  True
 \end{code}
@@ -496,6 +509,10 @@ eqString cs1      cs2         = False
 
 \begin{code}
 data Int = I# Int#
+-- ^A fixed-precision integer type with at least the range @[-2^29
+-- .. 2^29-1]@.  The exact range for a given implementation can be
+-- determined by using 'minBound' and 'maxBound' from the 'Bounded'
+-- class.
 
 zeroInt, oneInt, twoInt, maxInt, minInt :: Int
 zeroInt = I# 0#
@@ -547,6 +564,14 @@ compareInt# x# y#
 id                     :: a -> a
 id x                   =  x
 
+-- lazy function; this is just the same as id, but its unfolding
+-- and strictness are over-ridden by the definition in MkId.lhs
+-- That way, it does not get inlined, and the strictness analyser
+-- sees it as lazy.  Then the worker/wrapper phase inlines it.
+-- Result: happiness
+lazy :: a -> a
+lazy x = x
+
 -- constant function
 const                  :: a -> b -> a
 const x _              =  x
@@ -619,11 +644,18 @@ data (:*:) a b = a :*: b
 %*********************************************************
 
 \begin{code}
-divInt#, modInt# :: Int# -> Int# -> Int#
+divInt# :: Int# -> Int# -> Int#
 x# `divInt#` y#
-    | (x# ># 0#) && (y# <# 0#) = ((x# -# y#) -# 1#) `quotInt#` y#
-    | (x# <# 0#) && (y# ># 0#) = ((x# -# y#) +# 1#) `quotInt#` y#
+       -- careful NOT to overflow if we do any additional arithmetic
+       -- on the arguments...  the following  previous version of this
+       -- code has problems with overflow:
+--    | (x# ># 0#) && (y# <# 0#) = ((x# -# y#) -# 1#) `quotInt#` y#
+--    | (x# <# 0#) && (y# ># 0#) = ((x# -# y#) +# 1#) `quotInt#` y#
+    | (x# ># 0#) && (y# <# 0#) = (x# -# 1#) `quotInt#` y# -# 1#
+    | (x# <# 0#) && (y# ># 0#) = (x# +# 1#) `quotInt#` y# -# 1#
     | otherwise                = x# `quotInt#` y#
+
+modInt# :: Int# -> Int# -> Int#
 x# `modInt#` y#
     | (x# ># 0#) && (y# <# 0#) ||
       (x# <# 0#) && (y# ># 0#)    = if r# /=# 0# then r# +# y# else 0#
@@ -777,10 +809,7 @@ unpacking the strings of error messages.
 \begin{code}
 unpackCString# :: Addr# -> [Char]
 {-# NOINLINE [1] unpackCString# #-}
-unpackCString# a = unpackCStringList# a
-
-unpackCStringList# :: Addr# -> [Char]
-unpackCStringList# addr 
+unpackCString# addr 
   = unpack 0#
   where
     unpack nh
@@ -849,10 +878,10 @@ unpackNBytes#  addr len# = unpack [] (len# -# 1#)
 
 {-# RULES
 "unpack"       [~1] forall a   . unpackCString# a                 = build (unpackFoldrCString# a)
-"unpack-list"  [1]  forall a   . unpackFoldrCString# a (:) [] = unpackCStringList# a
+"unpack-list"  [1]  forall a   . unpackFoldrCString# a (:) [] = unpackCString# a
 "unpack-append"     forall a n . unpackFoldrCString# a (:) n  = unpackAppendCString# a n
 
--- There's a built-in rule (in GHC.Rules.lhs) for
+-- There's a built-in rule (in PrelRules.lhs) for
 --     unpackFoldr "foo" c (unpackFoldr "baz" c n)  =  unpackFoldr "foobaz" c n
 
   #-}