X-Git-Url: http://git.megacz.com/?a=blobdiff_plain;f=GHC%2FBase.lhs;h=e07e2109ff4e3a72d9e1e8f49032f300c0aad119;hb=819adca5f17b40ee129e4a30edf685f817febbf9;hp=988c94e46fda18645dea2c0df53b28929f31034e;hpb=9f9c1ba962b98906e1a750b16138344bc62a6fd3;p=ghc-base.git diff --git a/GHC/Base.lhs b/GHC/Base.lhs index 988c94e..e07e210 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,6 +81,7 @@ Other Prelude modules are much easier with fewer complex dependencies. #include "MachDeps.h" +-- #hide module GHC.Base ( module GHC.Base, @@ -163,14 +162,22 @@ class Eq a where 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 @@ -225,8 +232,10 @@ satisfy these laws. -} class Monad m where - (>>=) :: m a -> (a -> m b) -> m b - (>>) :: m a -> m b -> m b + (>>=) :: forall a b. m a -> (a -> m b) -> m b + (>>) :: forall a b. m a -> m b -> m b + -- Explicit for-alls so that we know what order to + -- give type arguments when desugaring return :: a -> m a fail :: String -> m a @@ -295,6 +304,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, @@ -306,6 +324,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 @@ -583,10 +610,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# @@ -634,7 +660,7 @@ compareInt# x# y# %********************************************************* \begin{code} --- identity function +-- | Identity function. id :: a -> a id x = x @@ -646,40 +672,59 @@ id x = x lazy :: a -> a lazy 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 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 --- constant function +-- | 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 @@ -687,25 +732,6 @@ asTypeOf = const %********************************************************* %* * -\subsection{CCallable instances} -%* * -%********************************************************* - -Defined here to avoid orphans - -\begin{code} -instance CCallable Char -instance CReturnable Char - -instance CCallable Int -instance CReturnable Int - -instance CReturnable () -- Why, exactly? -\end{code} - - -%********************************************************* -%* * \subsection{Generics} %* * %********************************************************* @@ -869,22 +895,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