X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=GHC%2FBase.lhs;h=cf3c5a3e099bb724b486dbf4b8d45044d666de66;hb=7a73aaf70fefb4b30c9159f5d15035f8e9c6e114;hp=39453973aea27452b0c525ec7f64504d2f78dfb7;hpb=1702d51a5974c23f8de861a0c01fc2925fed4477;p=haskell-directory.git diff --git a/GHC/Base.lhs b/GHC/Base.lhs index 3945397..cf3c5a3 100644 --- a/GHC/Base.lhs +++ b/GHC/Base.lhs @@ -16,8 +16,6 @@ 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 - Classes: CCallable, CReturnable - GHC.Base Classes: Eq, Ord, Functor, Monad Types: list, (), Int, Bool, Ordering, Char, String @@ -66,7 +64,7 @@ GHC.ByteArr Types: ByteArray, MutableByteArray Other Prelude modules are much easier with fewer complex dependencies. \begin{code} -{-# OPTIONS -fno-implicit-prelude #-} +{-# OPTIONS_GHC -fno-implicit-prelude #-} ----------------------------------------------------------------------------- -- | -- Module : GHC.Base @@ -83,10 +81,11 @@ Other Prelude modules are much easier with fewer complex dependencies. #include "MachDeps.h" +-- #hide module GHC.Base ( module GHC.Base, - module GHC.Prim, -- Re-export GHC.Prim and GHC.Err, to avoid lots + module GHC.Prim, -- Re-export GHC.Prim and GHC.Err, to avoid lots module GHC.Err -- of people having to import it explicitly ) where @@ -149,20 +148,36 @@ unpackCStringUtf8# a = error "urk" %********************************************************* \begin{code} + +-- | The 'Eq' class defines equality ('==') and inequality ('/='). +-- All the basic datatypes exported by the "Prelude" are instances of 'Eq', +-- and 'Eq' may be derived for any datatype whose constituents are also +-- instances of 'Eq'. +-- +-- Minimal complete definition: either '==' or '/='. +-- class Eq a where (==), (/=) :: a -> a -> Bool 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 - -- 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 @@ -188,13 +203,58 @@ class (Eq a) => Ord a where %********************************************************* \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 +{- | 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 - (>>=) :: 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 + -- | 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 @@ -246,6 +306,12 @@ The rest of the prelude list functions are in GHC.List. ---------------------------------------------- \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) @@ -256,6 +322,15 @@ foldr k z xs = go xs 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, @@ -267,6 +342,15 @@ build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a] 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 @@ -278,8 +362,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/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 @@ -311,6 +395,12 @@ augment g xs = g (:) xs ---------------------------------------------- \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 @@ -350,6 +440,13 @@ mapFB c f x ys = c (f x) ys -- 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 @@ -369,8 +466,9 @@ 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. +-- 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 @@ -391,10 +489,10 @@ not :: Bool -> Bool 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. -- --- > f x | x \< 0 = ... +-- > f x | x < 0 = ... -- > | otherwise = ... otherwise :: Bool otherwise = True @@ -415,6 +513,8 @@ need (). (We could arrange suck in () only if -fglasgow-exts, but putting it here seems more direct.) \begin{code} +-- | The unit datatype @()@ has one non-undefined member, the nullary +-- constructor @()@. data () = () instance Eq () where @@ -439,6 +539,9 @@ instance Ord () where %********************************************************* \begin{code} +-- | Represents an ordering relationship between two values: less +-- than, equal to, or greater than. An 'Ordering' is returned by +-- 'compare'. data Ordering = LT | EQ | GT deriving (Eq, Ord) -- Read in GHC.Read, Show in GHC.Show \end{code} @@ -451,8 +554,23 @@ data Ordering = LT | EQ | GT deriving (Eq, Ord) %********************************************************* \begin{code} +-- | A 'String' is a list of characters. String constants in Haskell are values +-- of type 'String'. +-- type String = [Char] +{-| The character type 'Char' is an enumeration whose values represent +Unicode (or equivalently ISO\/IEC 10646) characters +(see 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# -- We don't use deriving for Eq and Ord, because for Ord the derived @@ -478,6 +596,7 @@ instance Ord Char where "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" @@ -485,6 +604,7 @@ chr (I# i#) | int2Word# i# `leWord#` int2Word# 0x10FFFF# = 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} @@ -498,6 +618,8 @@ eqString (c1:cs1) (c2:cs2) = c1 == c2 && cs1 `eqString` cs2 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} @@ -509,10 +631,9 @@ 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. +-- ^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# @@ -560,44 +681,91 @@ compareInt# x# y# %********************************************************* \begin{code} --- identity function +-- | Identity function. 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 +-- 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 + --- constant function +-- | 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)@. + +-- | 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 + +breakpoint :: a -> a +breakpoint r = r + +breakpointCond :: Bool -> a -> a +breakpointCond _ r = r + +-- | Constant function. const :: a -> b -> a const x _ = x --- function composition +-- | Function composition. {-# 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 --- 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 --- 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) --- 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 @@ -605,38 +773,42 @@ asTypeOf = const %********************************************************* %* * -\subsection{CCallable instances} +\subsection{Generics} %* * %********************************************************* -Defined here to avoid orphans - \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} - %********************************************************* %* * -\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} -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} - %********************************************************* %* * \subsection{Numeric primops} @@ -646,13 +818,13 @@ data (:*:) a b = a :*: b \begin{code} divInt# :: Int# -> Int# -> Int# x# `divInt#` y# - -- careful NOT to overflow if we do any additional arithmetic + -- Be 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# + | (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# @@ -764,22 +936,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. -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 +-- | 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 -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 +-- | 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 +-- | 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 @@ -832,6 +1015,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 +-- 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 @@ -849,19 +1035,19 @@ unpackCStringUtf8# addr | ch `eqChar#` '\0'# = [] | ch `leChar#` '\x7F'# = C# ch : unpack (nh +# 1#) | ch `leChar#` '\xDF'# = - C# (chr# ((ord# ch -# 0xC0#) `uncheckedIShiftL#` 6# +# - (ord# (indexCharOffAddr# addr (nh +# 1#)) -# 0x80#))) : + C# (chr# (((ord# ch -# 0xC0#) `uncheckedIShiftL#` 6#) +# + (ord# (indexCharOffAddr# addr (nh +# 1#)) -# 0x80#))) : unpack (nh +# 2#) | ch `leChar#` '\xEF'# = - C# (chr# ((ord# ch -# 0xE0#) `uncheckedIShiftL#` 12# +# - (ord# (indexCharOffAddr# addr (nh +# 1#)) -# 0x80#) `uncheckedIShiftL#` 6# +# - (ord# (indexCharOffAddr# addr (nh +# 2#)) -# 0x80#))) : + C# (chr# (((ord# ch -# 0xE0#) `uncheckedIShiftL#` 12#) +# + ((ord# (indexCharOffAddr# addr (nh +# 1#)) -# 0x80#) `uncheckedIShiftL#` 6#) +# + (ord# (indexCharOffAddr# addr (nh +# 2#)) -# 0x80#))) : unpack (nh +# 3#) | otherwise = - C# (chr# ((ord# ch -# 0xF0#) `uncheckedIShiftL#` 18# +# - (ord# (indexCharOffAddr# addr (nh +# 1#)) -# 0x80#) `uncheckedIShiftL#` 12# +# - (ord# (indexCharOffAddr# addr (nh +# 2#)) -# 0x80#) `uncheckedIShiftL#` 6# +# - (ord# (indexCharOffAddr# addr (nh +# 3#)) -# 0x80#))) : + C# (chr# (((ord# ch -# 0xF0#) `uncheckedIShiftL#` 18#) +# + ((ord# (indexCharOffAddr# addr (nh +# 1#)) -# 0x80#) `uncheckedIShiftL#` 12#) +# + ((ord# (indexCharOffAddr# addr (nh +# 2#)) -# 0x80#) `uncheckedIShiftL#` 6#) +# + (ord# (indexCharOffAddr# addr (nh +# 3#)) -# 0x80#))) : unpack (nh +# 4#) where ch = indexCharOffAddr# addr nh @@ -886,3 +1072,12 @@ unpackNBytes# addr len# = unpack [] (len# -# 1#) #-} \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