Make Control.Exception buildable by nhc98.

[haskell-directory.git] / GHC / Base.lhs

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index e3bc346..c590366 100644 (file)
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -16,12 +16,10 @@ GHC.Prim            Has no implementation.  It defines built-in things, and
                The source file is GHC.Prim.hi-boot, which is just
                copied to make GHC.Prim.hi
 
                The source file is GHC.Prim.hi-boot, which is just
                copied to make GHC.Prim.hi
 

-               Classes: CCallable, CReturnable
-

 GHC.Base       Classes: Eq, Ord, Functor, Monad
                Types:   list, (), Int, Bool, Ordering, Char, String
 
 GHC.Base       Classes: Eq, Ord, Functor, Monad
                Types:   list, (), Int, Bool, Ordering, Char, String
 

-Data.Tup       Types: tuples, plus instances for GHC.Base classes
+Data.Tuple     Types: tuples, plus instances for GHC.Base classes

 
 GHC.Show       Class: Show, plus instances for GHC.Base/GHC.Tup types
 
 
 GHC.Show       Class: Show, plus instances for GHC.Base/GHC.Tup types
 

@@ -29,6 +27,8 @@ GHC.Enum      Class: Enum,  plus instances for GHC.Base/GHC.Tup types
 
 Data.Maybe     Type: Maybe, plus instances for GHC.Base classes
 
 
 Data.Maybe     Type: Maybe, plus instances for GHC.Base classes
 

+GHC.List       List functions
+

 GHC.Num                Class: Num, plus instances for Int
                Type:  Integer, plus instances for all classes so far (Eq, Ord, Num, Show)
 
 GHC.Num                Class: Num, plus instances for Int
                Type:  Integer, plus instances for all classes so far (Eq, Ord, Num, Show)
 

@@ -43,11 +43,12 @@ GHC.Real    Classes: Real, Integral, Fractional, RealFrac
                Rational is needed here because it is mentioned in the signature
                of 'toRational' in class Real
 
                Rational is needed here because it is mentioned in the signature
                of 'toRational' in class Real
 

+GHC.ST The ST monad, instances and a few helper functions
+

 Ix             Classes: Ix, plus instances for Int, Bool, Char, Integer, Ordering, tuples
 
 GHC.Arr                Types: Array, MutableArray, MutableVar
 
 Ix             Classes: Ix, plus instances for Int, Bool, Char, Integer, Ordering, tuples
 
 GHC.Arr                Types: Array, MutableArray, MutableVar
 

-               Does *not* contain any ByteArray stuff (see GHC.ByteArr)

                Arrays are used by a function in GHC.Float
 
 GHC.Float      Classes: Floating, RealFloat
                Arrays are used by a function in GHC.Float
 
 GHC.Float      Classes: Floating, RealFloat

@@ -57,16 +58,11 @@ GHC.Float   Classes: Floating, RealFloat
                It is a big module (900 lines)
                With a bit of luck, many modules can be compiled without ever reading GHC.Float.hi
 
                It is a big module (900 lines)
                With a bit of luck, many modules can be compiled without ever reading GHC.Float.hi
 

-GHC.ByteArr    Types: ByteArray, MutableByteArray
-               
-               We want this one to be after GHC.Float, because it defines arrays
-               of unboxed floats.
-

 
 Other Prelude modules are much easier with fewer complex dependencies.
 
 \begin{code}
 
 Other Prelude modules are much easier with fewer complex dependencies.
 
 \begin{code}

-{-# OPTIONS -fno-implicit-prelude #-}
+{-# OPTIONS_GHC -fno-implicit-prelude #-}

 -----------------------------------------------------------------------------
 -- |
 -- Module      :  GHC.Base
 -----------------------------------------------------------------------------
 -- |
 -- Module      :  GHC.Base

@@ -83,6 +79,7 @@ Other Prelude modules are much easier with fewer complex dependencies.
 
 #include "MachDeps.h"
 
 
 #include "MachDeps.h"
 

+-- #hide

 module GHC.Base
        (
        module GHC.Base,
 module GHC.Base
        (
        module GHC.Base,

@@ -163,14 +160,22 @@ class  Eq a  where
     x /= y              = not (x == y)
     x == y              = not (x /= y)
 
     x /= y              = not (x == y)
     x == y              = not (x /= y)
 

+-- | The 'Ord' class is used for totally ordered datatypes.
+--
+-- Instances of 'Ord' can be derived for any user-defined
+-- datatype whose constituent types are in 'Ord'.  The declared order
+-- of the constructors in the data declaration determines the ordering
+-- in derived 'Ord' instances.  The 'Ordering' datatype allows a single
+-- comparison to determine the precise ordering of two objects.
+--
+-- Minimal complete definition: either 'compare' or '<='.
+-- Using 'compare' can be more efficient for complex types.
+--

 class  (Eq a) => Ord a  where
     compare             :: a -> a -> Ordering
     (<), (<=), (>), (>=) :: a -> a -> Bool
     max, min            :: a -> a -> a
 
 class  (Eq a) => Ord a  where
     compare             :: a -> a -> Ordering
     (<), (<=), (>), (>=) :: a -> a -> Bool
     max, min            :: a -> a -> a
 

-    -- An instance of Ord should define either 'compare' or '<='.
-    -- Using 'compare' can be more efficient for complex types.
-

     compare x y
        | x == y    = EQ
        | x <= y    = LT        -- NB: must be '<=' not '<' to validate the
     compare x y
        | x == y    = EQ
        | x <= y    = LT        -- NB: must be '<=' not '<' to validate the

@@ -196,13 +201,58 @@ class  (Eq a) => Ord a  where
 %*********************************************************
 
 \begin{code}
 %*********************************************************
 
 \begin{code}

+{- | The 'Functor' class is used for types that can be mapped over.
+Instances of 'Functor' should satisfy the following laws:
+
+> fmap id  ==  id
+> fmap (f . g)  ==  fmap f . fmap g
+
+The instances of 'Functor' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
+defined in the "Prelude" satisfy these laws.
+-}
+

 class  Functor f  where
     fmap        :: (a -> b) -> f a -> f b
 
 class  Functor f  where
     fmap        :: (a -> b) -> f a -> f b
 

+{- | The 'Monad' class defines the basic operations over a /monad/,
+a concept from a branch of mathematics known as /category theory/.
+From the perspective of a Haskell programmer, however, it is best to
+think of a monad as an /abstract datatype/ of actions.
+Haskell's @do@ expressions provide a convenient syntax for writing
+monadic expressions.
+
+Minimal complete definition: '>>=' and 'return'.
+
+Instances of 'Monad' should satisfy the following laws:
+
+> return a >>= k  ==  k a
+> m >>= return  ==  m
+> m >>= (\x -> k x >>= h)  ==  (m >>= k) >>= h
+
+Instances of both 'Monad' and 'Functor' should additionally satisfy the law:
+
+> fmap f xs  ==  xs >>= return . f
+
+The instances of 'Monad' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
+defined in the "Prelude" satisfy these laws.
+-}
+

 class  Monad m  where
 class  Monad m  where

-    (>>=)       :: m a -> (a -> m b) -> m b
-    (>>)        :: m a -> m b -> m b
+    -- | Sequentially compose two actions, passing any value produced
+    -- by the first as an argument to the second.
+    (>>=)       :: forall a b. m a -> (a -> m b) -> m b
+    -- | Sequentially compose two actions, discarding any value produced
+    -- by the first, like sequencing operators (such as the semicolon)
+    -- in imperative languages.
+    (>>)        :: forall a b. m a -> m b -> m b
+       -- Explicit for-alls so that we know what order to
+       -- give type arguments when desugaring
+
+    -- | Inject a value into the monadic type.

     return      :: a -> m a
     return      :: a -> m a

+    -- | Fail with a message.  This operation is not part of the
+    -- mathematical definition of a monad, but is invoked on pattern-match
+    -- failure in a @do@ expression.

     fail       :: String -> m a
 
     m >> k      = m >>= \_ -> k
     fail       :: String -> m a
 
     m >> k      = m >>= \_ -> k

@@ -254,6 +304,12 @@ The rest of the prelude list functions are in GHC.List.
 ----------------------------------------------
   
 \begin{code}
 ----------------------------------------------
   
 \begin{code}

+-- | 'foldr', applied to a binary operator, a starting value (typically
+-- the right-identity of the operator), and a list, reduces the list
+-- using the binary operator, from right to left:
+--
+-- > foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
+

 foldr            :: (a -> b -> b) -> b -> [a] -> b
 -- foldr _ z []     =  z
 -- foldr f z (x:xs) =  f x (foldr f z xs)
 foldr            :: (a -> b -> b) -> b -> [a] -> b
 -- foldr _ z []     =  z
 -- foldr f z (x:xs) =  f x (foldr f z xs)

@@ -264,6 +320,15 @@ foldr k z xs = go xs
               go []     = z
               go (y:ys) = y `k` go ys
 
               go []     = z
               go (y:ys) = y `k` go ys
 

+-- | A list producer that can be fused with 'foldr'.
+-- This function is merely
+--
+-- >   build g = g (:) []
+--
+-- but GHC's simplifier will transform an expression of the form
+-- @'foldr' k z ('build' g)@, which may arise after inlining, to @g k z@,
+-- which avoids producing an intermediate list.
+

 build  :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
 {-# INLINE [1] build #-}
        -- The INLINE is important, even though build is tiny,
 build  :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
 {-# INLINE [1] build #-}
        -- The INLINE is important, even though build is tiny,

@@ -275,6 +340,15 @@ build      :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
 
 build g = g (:) []
 
 
 build g = g (:) []
 

+-- | A list producer that can be fused with 'foldr'.
+-- This function is merely
+--
+-- >   augment g xs = g (:) xs
+--
+-- but GHC's simplifier will transform an expression of the form
+-- @'foldr' k z ('augment' g xs)@, which may arise after inlining, to
+-- @g k ('foldr' k z xs)@, which avoids producing an intermediate list.
+

 augment :: forall a. (forall b. (a->b->b) -> b -> b) -> [a] -> [a]
 {-# INLINE [1] augment #-}
 augment g xs = g (:) xs
 augment :: forall a. (forall b. (a->b->b) -> b -> b) -> [a] -> [a]
 {-# INLINE [1] augment #-}
 augment g xs = g (:) xs

@@ -286,8 +360,8 @@ augment g xs = g (:) xs
 "foldr/augment" forall k z xs (g::forall b. (a->b->b) -> b -> b) . 
                foldr k z (augment g xs) = g k (foldr k z xs)
 
 "foldr/augment" forall k z xs (g::forall b. (a->b->b) -> b -> b) . 
                foldr k z (augment g xs) = g k (foldr k z xs)
 

-"foldr/id"                       foldr (:) [] = \x->x
-"foldr/app"            [1] forall xs ys. foldr (:) ys xs = xs ++ ys
+"foldr/id"                       foldr (:) [] = \x  -> x
+"foldr/app"            [1] forall ys. foldr (:) ys = \xs -> xs ++ ys

        -- Only activate this from phase 1, because that's
        -- when we disable the rule that expands (++) into foldr
 
        -- Only activate this from phase 1, because that's
        -- when we disable the rule that expands (++) into foldr
 

@@ -319,6 +393,12 @@ augment g xs = g (:) xs
 ----------------------------------------------
 
 \begin{code}
 ----------------------------------------------
 
 \begin{code}

+-- | 'map' @f xs@ is the list obtained by applying @f@ to each element
+-- of @xs@, i.e.,
+--
+-- > map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
+-- > map f [x1, x2, ...] == [f x1, f x2, ...]
+

 map :: (a -> b) -> [a] -> [b]
 map _ []     = []
 map f (x:xs) = f x : map f xs
 map :: (a -> b) -> [a] -> [b]
 map _ []     = []
 map f (x:xs) = f x : map f xs

@@ -358,6 +438,13 @@ mapFB c f x ys = c (f x) ys
 --             append  
 ----------------------------------------------
 \begin{code}
 --             append  
 ----------------------------------------------
 \begin{code}

+-- | Append two lists, i.e.,
+--
+-- > [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
+-- > [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
+--
+-- If the first list is not finite, the result is the first list.
+

 (++) :: [a] -> [a] -> [a]
 (++) []     ys = ys
 (++) (x:xs) ys = x : xs ++ ys
 (++) :: [a] -> [a] -> [a]
 (++) []     ys = ys
 (++) (x:xs) ys = x : xs ++ ys

@@ -377,8 +464,9 @@ mapFB c f x ys = c (f x) ys
 
 \begin{code}
 -- |The 'Bool' type is an enumeration.  It is defined with 'False'
 
 \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.
+-- first so that the corresponding 'Prelude.Enum' instance will give
+-- 'Prelude.fromEnum' 'False' the value zero, and
+-- 'Prelude.fromEnum' 'True' the value 1.

 data  Bool  =  False | True  deriving (Eq, Ord)
        -- Read in GHC.Read, Show in GHC.Show
 
 data  Bool  =  False | True  deriving (Eq, Ord)
        -- Read in GHC.Read, Show in GHC.Show
 

@@ -399,16 +487,15 @@ not                       :: Bool -> Bool
 not True               =  False
 not False              =  True
 
 not True               =  False
 not False              =  True
 

--- |'otherwise' is defined as the value 'True'; it helps to make
+-- |'otherwise' is defined as the value 'True'.  It helps to make

 -- guards more readable.  eg.
 --
 -- guards more readable.  eg.
 --

--- >  f x | x \< 0     = ...
+-- >  f x | x < 0     = ...

 -- >      | otherwise = ...
 otherwise              :: Bool
 otherwise              =  True
 \end{code}
 
 -- >      | otherwise = ...
 otherwise              :: Bool
 otherwise              =  True
 \end{code}
 

-

 %*********************************************************
 %*                                                     *
 \subsection{The @()@ type}
 %*********************************************************
 %*                                                     *
 \subsection{The @()@ type}

@@ -470,11 +557,16 @@ data Ordering = LT | EQ | GT deriving (Eq, Ord)
 type String = [Char]
 
 {-| The character type 'Char' is an enumeration whose values represent
 type String = [Char]
 
 {-| The character type 'Char' is an enumeration whose values represent

-Unicode characters.  A character literal in Haskell has type 'Char'.
-
-To convert a 'Char' to or from an 'Int', use 'Prelude.toEnum' and
-'Prelude.fromEnum' from the 'Enum' class respectively (equivalently
-'ord' and 'chr' also do the trick).
+Unicode (or equivalently ISO\/IEC 10646) characters
+(see <http://www.unicode.org/> for details).
+This set extends the ISO 8859-1 (Latin-1) character set
+(the first 256 charachers), which is itself an extension of the ASCII
+character set (the first 128 characters).
+A character literal in Haskell has type 'Char'.
+
+To convert a 'Char' to or from the corresponding 'Int' value defined
+by Unicode, use 'Prelude.toEnum' and 'Prelude.fromEnum' from the
+'Prelude.Enum' class respectively (or equivalently 'ord' and 'chr').

 -}
 data Char = C# Char#
 
 -}
 data Char = C# Char#
 

@@ -501,6 +593,7 @@ instance Ord Char where
 "x# `ltChar#` x#" forall x#. x# `ltChar#` x# = False
   #-}
 
 "x# `ltChar#` x#" forall x#. x# `ltChar#` x# = False
   #-}
 

+-- | The 'Prelude.toEnum' method restricted to the type 'Data.Char.Char'.

 chr :: Int -> Char
 chr (I# i#) | int2Word# i# `leWord#` int2Word# 0x10FFFF# = C# (chr# i#)
             | otherwise                                  = error "Prelude.chr: bad argument"
 chr :: Int -> Char
 chr (I# i#) | int2Word# i# `leWord#` int2Word# 0x10FFFF# = C# (chr# i#)
             | otherwise                                  = error "Prelude.chr: bad argument"

@@ -508,6 +601,7 @@ chr (I# i#) | int2Word# i# `leWord#` int2Word# 0x10FFFF# = C# (chr# i#)
 unsafeChr :: Int -> Char
 unsafeChr (I# i#) = C# (chr# i#)
 
 unsafeChr :: Int -> Char
 unsafeChr (I# i#) = C# (chr# i#)
 

+-- | The 'Prelude.fromEnum' method restricted to the type 'Data.Char.Char'.

 ord :: Char -> Int
 ord (C# c#) = I# (ord# c#)
 \end{code}
 ord :: Char -> Int
 ord (C# c#) = I# (ord# c#)
 \end{code}

@@ -521,6 +615,8 @@ eqString (c1:cs1) (c2:cs2) = c1 == c2 && cs1 `eqString` cs2
 eqString cs1      cs2     = False
 
 {-# RULES "eqString" (==) = eqString #-}
 eqString cs1      cs2     = False
 
 {-# RULES "eqString" (==) = eqString #-}

+-- eqString also has a BuiltInRule in PrelRules.lhs:
+--     eqString (unpackCString# (Lit s1)) (unpackCString# (Lit s2) = s1==s2

 \end{code}
 
 
 \end{code}
 
 

@@ -532,10 +628,9 @@ eqString cs1      cs2         = False
 
 \begin{code}
 data Int = I# Int#
 
 \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.
+-- ^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
+-- 'Prelude.minBound' and 'Prelude.maxBound' from the 'Prelude.Bounded' class.

 
 zeroInt, oneInt, twoInt, maxInt, minInt :: Int
 zeroInt = I# 0#
 
 zeroInt, oneInt, twoInt, maxInt, minInt :: Int
 zeroInt = I# 0#

@@ -583,49 +678,99 @@ compareInt# x# y#
 %*********************************************************
 
 \begin{code}
 %*********************************************************
 
 \begin{code}

--- identity function
+-- | Identity function.

 id                     :: a -> a
 id x                   =  x
 
 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
+-- | The call '(lazy e)' means the same as 'e', but 'lazy' has a 
+-- magical strictness property: it is lazy in its first argument, 
+-- even though its semantics is strict.

 lazy :: a -> a
 lazy x = x
 lazy :: a -> a
 lazy x = x

+-- Implementation note: its strictness and unfolding are over-ridden
+-- by the definition in MkId.lhs; in both cases to nothing at all.
+-- That way, 'lazy' does not get inlined, and the strictness analyser
+-- sees it as lazy.  Then the worker/wrapper phase inlines it.
+-- Result: happiness
+
+
+-- | The call '(inline f)' reduces to 'f', but 'inline' has a BuiltInRule
+-- that tries to inline 'f' (if it has an unfolding) unconditionally
+-- The 'NOINLINE' pragma arranges that inline only gets inlined (and
+-- hence eliminated) late in compilation, after the rule has had
+-- a god chance to fire.
+inline :: a -> a
+{-# NOINLINE[0] inline #-}
+inline x = x

 
 

--- Assertion function. This simply ignores its boolean argument.
--- The compiler may rewrite it to (assertError line)
+-- Assertion function.  This simply ignores its boolean argument.
+-- The compiler may rewrite it to @('assertError' line)@.
+
+-- | If the first argument evaluates to 'True', then the result is the
+-- second argument.  Otherwise an 'AssertionFailed' exception is raised,
+-- containing a 'String' with the source file and line number of the
+-- call to 'assert'.
+--
+-- Assertions can normally be turned on or off with a compiler flag
+-- (for GHC, assertions are normally on unless optimisation is turned on 
+-- with @-O@ or the @-fignore-asserts@
+-- option is given).  When assertions are turned off, the first
+-- argument to 'assert' is ignored, and the second argument is
+-- returned as the result.
+
+--     SLPJ: in 5.04 etc 'assert' is in GHC.Prim,
+--     but from Template Haskell onwards it's simply
+--     defined here in Base.lhs

 assert :: Bool -> a -> a
 assert pred r = r
 assert :: Bool -> a -> a
 assert pred r = r

- 
--- constant function
+
+breakpoint :: a -> a
+breakpoint r = r
+
+breakpointCond :: Bool -> a -> a
+breakpointCond _ r = r
+
+data Unknown 
+data Unknown1 a
+data Unknown2 a b
+data Unknown3 a b c
+data Unknown4 a b c d
+
+data Opaque = forall a. O a
+
+-- | Constant function.

 const                  :: a -> b -> a
 const x _              =  x
 
 const                  :: a -> b -> a
 const x _              =  x
 

--- function composition
+-- | Function composition.

 {-# INLINE (.) #-}
 (.)      :: (b -> c) -> (a -> b) -> a -> c
 (.) f g        x = f (g x)
 
 {-# INLINE (.) #-}
 (.)      :: (b -> c) -> (a -> b) -> a -> c
 (.) f g        x = f (g x)
 

--- flip f  takes its (first) two arguments in the reverse order of f.
+-- | @'flip' f@ takes its (first) two arguments in the reverse order of @f@.

 flip                   :: (a -> b -> c) -> b -> a -> c
 flip f x y             =  f y x
 
 flip                   :: (a -> b -> c) -> b -> a -> c
 flip f x y             =  f y x
 

--- right-associating infix application operator (useful in continuation-
--- passing style)
+-- | Application operator.  This operator is redundant, since ordinary
+-- application @(f x)@ means the same as @(f '$' x)@. However, '$' has
+-- low, right-associative binding precedence, so it sometimes allows
+-- parentheses to be omitted; for example:
+--
+-- >     f $ g $ h x  =  f (g (h x))
+--
+-- It is also useful in higher-order situations, such as @'map' ('$' 0) xs@,
+-- or @'Data.List.zipWith' ('$') fs xs@.

 {-# INLINE ($) #-}
 ($)                    :: (a -> b) -> a -> b
 f $ x                  =  f x
 
 {-# INLINE ($) #-}
 ($)                    :: (a -> b) -> a -> b
 f $ x                  =  f x
 

--- until p f  yields the result of applying f until p holds.
+-- | @'until' p f@ yields the result of applying @f@ until @p@ holds.

 until                  :: (a -> Bool) -> (a -> a) -> a -> a
 until p f x | p x      =  x
            | otherwise =  until p f (f x)
 
 until                  :: (a -> Bool) -> (a -> a) -> a -> a
 until p f x | p x      =  x
            | otherwise =  until p f (f x)
 

--- asTypeOf is a type-restricted version of const.  It is usually used
--- as an infix operator, and its typing forces its first argument
+-- | 'asTypeOf' is a type-restricted version of 'const'.  It is usually
+-- used as an infix operator, and its typing forces its first argument

 -- (which is usually overloaded) to have the same type as the second.
 asTypeOf               :: a -> a -> a
 asTypeOf               =  const
 -- (which is usually overloaded) to have the same type as the second.
 asTypeOf               :: a -> a -> a
 asTypeOf               =  const

@@ -633,38 +778,42 @@ asTypeOf          =  const
 
 %*********************************************************
 %*                                                     *
 
 %*********************************************************
 %*                                                     *

-\subsection{CCallable instances}
+\subsection{Generics}

 %*                                                     *
 %*********************************************************
 
 %*                                                     *
 %*********************************************************
 

-Defined here to avoid orphans
-

 \begin{code}
 \begin{code}

-instance CCallable Char
-instance CReturnable Char
-
-instance CCallable   Int
-instance CReturnable Int
-
-instance CReturnable () -- Why, exactly?
+data Unit = Unit
+#ifndef __HADDOCK__
+data (:+:) a b = Inl a | Inr b
+data (:*:) a b = a :*: b
+#endif

 \end{code}
 
 \end{code}
 

-

 %*********************************************************
 %*                                                     *
 %*********************************************************
 %*                                                     *

-\subsection{Generics}
+\subsection{@getTag@}

 %*                                                     *
 %*********************************************************
 
 %*                                                     *
 %*********************************************************
 

+Returns the 'tag' of a constructor application; this function is used
+by the deriving code for Eq, Ord and Enum.
+
+The primitive dataToTag# requires an evaluated constructor application
+as its argument, so we provide getTag as a wrapper that performs the
+evaluation before calling dataToTag#.  We could have dataToTag#
+evaluate its argument, but we prefer to do it this way because (a)
+dataToTag# can be an inline primop if it doesn't need to do any
+evaluation, and (b) we want to expose the evaluation to the
+simplifier, because it might be possible to eliminate the evaluation
+in the case when the argument is already known to be evaluated.
+

 \begin{code}
 \begin{code}

-data Unit = Unit
-#ifndef __HADDOCK__
-data (:+:) a b = Inl a | Inr b
-data (:*:) a b = a :*: b
-#endif
+{-# INLINE getTag #-}
+getTag :: a -> Int#
+getTag x = x `seq` dataToTag# x

 \end{code}
 
 \end{code}
 

-

 %*********************************************************
 %*                                                     *
 \subsection{Numeric primops}
 %*********************************************************
 %*                                                     *
 \subsection{Numeric primops}

@@ -792,22 +941,33 @@ gtInt, geInt, eqInt, neInt, ltInt, leInt :: Int -> Int -> Bool
 -- Note that these wrappers still produce undefined results when the
 -- second argument (the shift amount) is negative.
 
 -- Note that these wrappers still produce undefined results when the
 -- second argument (the shift amount) is negative.
 

-shiftL#, shiftRL# :: Word# -> Int# -> Word#
-
+-- | Shift the argument left by the specified number of bits
+-- (which must be non-negative).
+shiftL# :: Word# -> Int# -> Word#

 a `shiftL#` b   | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
                | otherwise                = a `uncheckedShiftL#` b
 
 a `shiftL#` b   | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
                | otherwise                = a `uncheckedShiftL#` b
 

+-- | Shift the argument right by the specified number of bits
+-- (which must be non-negative).
+shiftRL# :: Word# -> Int# -> Word#

 a `shiftRL#` b  | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
                | otherwise                = a `uncheckedShiftRL#` b
 
 a `shiftRL#` b  | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
                | otherwise                = a `uncheckedShiftRL#` b
 

-iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
-
+-- | Shift the argument left by the specified number of bits
+-- (which must be non-negative).
+iShiftL# :: Int# -> Int# -> Int#

 a `iShiftL#` b  | b >=# WORD_SIZE_IN_BITS# = 0#
                | otherwise                = a `uncheckedIShiftL#` b
 
 a `iShiftL#` b  | b >=# WORD_SIZE_IN_BITS# = 0#
                | otherwise                = a `uncheckedIShiftL#` b
 

+-- | Shift the argument right (signed) by the specified number of bits
+-- (which must be non-negative).
+iShiftRA# :: Int# -> Int# -> Int#

 a `iShiftRA#` b | b >=# WORD_SIZE_IN_BITS# = if a <# 0# then (-1#) else 0#
                | otherwise                = a `uncheckedIShiftRA#` b
 
 a `iShiftRA#` b | b >=# WORD_SIZE_IN_BITS# = if a <# 0# then (-1#) else 0#
                | otherwise                = a `uncheckedIShiftRA#` b
 

+-- | Shift the argument right (unsigned) by the specified number of bits
+-- (which must be non-negative).
+iShiftRL# :: Int# -> Int# -> Int#

 a `iShiftRL#` b | b >=# WORD_SIZE_IN_BITS# = 0#
                | otherwise                = a `uncheckedIShiftRL#` b
 
 a `iShiftRL#` b | b >=# WORD_SIZE_IN_BITS# = 0#
                | otherwise                = a `uncheckedIShiftRL#` b
 

@@ -860,6 +1020,9 @@ unpackFoldrCString# :: Addr# -> (Char  -> a -> a) -> a -> a
 {-# NOINLINE [0] unpackFoldrCString# #-}
 -- Don't inline till right at the end;
 -- usually the unpack-list rule turns it into unpackCStringList
 {-# NOINLINE [0] unpackFoldrCString# #-}
 -- Don't inline till right at the end;
 -- usually the unpack-list rule turns it into unpackCStringList

+-- It also has a BuiltInRule in PrelRules.lhs:
+--     unpackFoldrCString# "foo" c (unpackFoldrCString# "baz" c n)
+--       =  unpackFoldrCString# "foobaz" c n

 unpackFoldrCString# addr f z 
   = unpack 0#
   where
 unpackFoldrCString# addr f z 
   = unpack 0#
   where

@@ -914,3 +1077,12 @@ unpackNBytes#  addr len# = unpack [] (len# -# 1#)
 
   #-}
 \end{code}
 
   #-}
 \end{code}

+
+#ifdef __HADDOCK__
+\begin{code}
+-- | A special argument for the 'Control.Monad.ST.ST' type constructor,
+-- indexing a state embedded in the 'Prelude.IO' monad by
+-- 'Control.Monad.ST.stToIO'.
+data RealWorld
+\end{code}
+#endif