put 'unsafeCoerce' in a standard location

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

diff --git a/GHC/Base.lhs b/GHC/Base.lhs
index 7d310b7..c590366 100644 (file)
--- a/GHC/Base.lhs
+++ b/GHC/Base.lhs
@@ -19,7 +19,7 @@ GHC.Prim              Has no implementation.  It defines built-in things, and
 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
 

@@ -27,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)
 

@@ -41,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

@@ -55,11 +58,6 @@ 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.
 
 
 Other Prelude modules are much easier with fewer complex dependencies.
 

@@ -81,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,

@@ -208,14 +207,22 @@ Instances of 'Functor' should satisfy the following laws:
 > fmap id  ==  id
 > fmap (f . g)  ==  fmap f . fmap g
 
 > fmap id  ==  id
 > fmap (f . g)  ==  fmap f . fmap g
 

-The instances of 'Functor' for lists, 'Maybe' and 'IO' defined in the "Prelude"
-satisfy these laws.
+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/.
+{- | 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
 Instances of 'Monad' should satisfy the following laws:
 
 > return a >>= k  ==  k a

@@ -226,16 +233,26 @@ Instances of both 'Monad' and 'Functor' should additionally satisfy the law:
 
 > fmap f xs  ==  xs >>= return . f
 
 
 > fmap f xs  ==  xs >>= return . f
 

-The instances of 'Monad' for lists, 'Maybe' and 'IO' defined in the "Prelude"
-satisfy these laws.
+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

+    -- | 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
     (>>=)       :: 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
     (>>)        :: 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

@@ -343,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
 

@@ -479,7 +496,6 @@ otherwise           :: Bool
 otherwise              =  True
 \end{code}
 
 otherwise              =  True
 \end{code}
 

-

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

@@ -541,7 +557,8 @@ 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 (or equivalently ISO 10646) characters.
+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).
 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).

@@ -598,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}
 
 

@@ -663,23 +682,62 @@ compareInt# x# y#
 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.
+-- Assertion function.  This simply ignores its boolean argument.

 -- The compiler may rewrite it to @('assertError' line)@.
 
 -- 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
 --     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

- 
+
+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
 -- | Constant function.
 const                  :: a -> b -> a
 const x _              =  x

@@ -962,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