2 % (c) The GRAP/AQUA Project, Glasgow University, 1992-1996
4 \section[PrelBase]{Module @PrelBase@}
7 The overall structure of the GHC Prelude is a bit tricky.
9 a) We want to avoid "orphan modules", i.e. ones with instance
10 decls that don't belong either to a tycon or a class
11 defined in the same module
13 b) We want to avoid giant modules
15 So the rough structure is as follows, in (linearised) dependency order
18 PrelGHC Has no implementation. It defines built-in things, and
19 by importing it you bring them into scope.
20 The source file is PrelGHC.hi-boot, which is just
21 copied to make PrelGHC.hi
23 Classes: CCallable, CReturnable
25 PrelBase Classes: Eq, Ord, Functor, Monad
26 Types: list, (), Int, Bool, Ordering, Char, String
28 PrelTup Types: tuples, plus instances for PrelBase classes
30 PrelShow Class: Show, plus instances for PrelBase/PrelTup types
32 PrelEnum Class: Enum, plus instances for PrelBase/PrelTup types
34 PrelMaybe Type: Maybe, plus instances for PrelBase classes
36 PrelNum Class: Num, plus instances for Int
37 Type: Integer, plus instances for all classes so far (Eq, Ord, Num, Show)
39 Integer is needed here because it is mentioned in the signature
40 of 'fromInteger' in class Num
42 PrelReal Classes: Real, Integral, Fractional, RealFrac
43 plus instances for Int, Integer
44 Types: Ratio, Rational
45 plus intances for classes so far
47 Rational is needed here because it is mentioned in the signature
48 of 'toRational' in class Real
50 Ix Classes: Ix, plus instances for Int, Bool, Char, Integer, Ordering, tuples
52 PrelArr Types: Array, MutableArray, MutableVar
54 Does *not* contain any ByteArray stuff (see PrelByteArr)
55 Arrays are used by a function in PrelFloat
57 PrelFloat Classes: Floating, RealFloat
58 Types: Float, Double, plus instances of all classes so far
60 This module contains everything to do with floating point.
61 It is a big module (900 lines)
62 With a bit of luck, many modules can be compiled without ever reading PrelFloat.hi
64 PrelByteArr Types: ByteArray, MutableByteArray
66 We want this one to be after PrelFloat, because it defines arrays
70 Other Prelude modules are much easier with fewer complex dependencies.
74 {-# OPTIONS -fcompiling-prelude -fno-implicit-prelude #-}
79 module PrelGHC -- Re-export PrelGHC, to avoid lots of people
80 -- having to import it explicitly
84 import {-# SOURCE #-} PrelErr ( error )
89 infix 4 ==, /=, <, <=, >=, >
95 default () -- Double isn't available yet
99 %*********************************************************
101 \subsection{DEBUGGING STUFF}
102 %* (for use when compiling PrelBase itself doesn't work)
104 %*********************************************************
108 data Bool = False | True
109 data Ordering = LT | EQ | GT
117 (&&) True True = True
123 unpackCString# :: Addr# -> [Char]
124 unpackFoldrCString# :: Addr# -> (Char -> a -> a) -> a -> a
125 unpackAppendCString# :: Addr# -> [Char] -> [Char]
126 unpackNBytes# :: Addr# -> Int# -> [Char]
127 unpackNBytes# a b = error "urk"
128 unpackCString# a = error "urk"
129 unpackFoldrCString# a = error "urk"
130 unpackAppendCString# a = error "urk"
135 %*********************************************************
137 \subsection{Standard classes @Eq@, @Ord@}
139 %*********************************************************
143 (==), (/=) :: a -> a -> Bool
145 -- x /= y = not (x == y)
146 -- x == y = not (x /= y)
148 (/=) x y = not ((==) x y)
151 class (Eq a) => Ord a where
152 compare :: a -> a -> Ordering
153 (<), (<=), (>=), (>):: a -> a -> Bool
154 max, min :: a -> a -> a
156 -- An instance of Ord should define either compare or <=
157 -- Using compare can be more efficient for complex types.
160 | x <= y = LT -- NB: must be '<=' not '<' to validate the
161 -- above claim about the minimal things that can
162 -- be defined for an instance of Ord
165 x <= y = case compare x y of { GT -> False; _other -> True }
166 x < y = case compare x y of { LT -> True; _other -> False }
167 x >= y = case compare x y of { LT -> False; _other -> True }
168 x > y = case compare x y of { GT -> True; _other -> False }
170 -- These two default methods use '>' rather than compare
171 -- because the latter is often more expensive
172 max x y = if x > y then x else y
173 min x y = if x > y then y else x
176 %*********************************************************
178 \subsection{Monadic classes @Functor@, @Monad@ }
180 %*********************************************************
183 class Functor f where
184 fmap :: (a -> b) -> f a -> f b
187 (>>=) :: m a -> (a -> m b) -> m b
188 (>>) :: m a -> m b -> m b
190 fail :: String -> m a
192 m >> k = m >>= \_ -> k
198 %*********************************************************
200 \subsection{The list type}
202 %*********************************************************
205 data [] a = [] | a : [a] -- do explicitly: deriving (Eq, Ord)
206 -- to avoid weird names like con2tag_[]#
209 instance (Eq a) => Eq [a] where
211 {-# SPECIALISE instance Eq [Char] #-}
214 (x:xs) == (y:ys) = x == y && xs == ys
217 xs /= ys = if (xs == ys) then False else True
219 instance (Ord a) => Ord [a] where
221 {-# SPECIALISE instance Ord [Char] #-}
223 a < b = case compare a b of { LT -> True; EQ -> False; GT -> False }
224 a <= b = case compare a b of { LT -> True; EQ -> True; GT -> False }
225 a >= b = case compare a b of { LT -> False; EQ -> True; GT -> True }
226 a > b = case compare a b of { LT -> False; EQ -> False; GT -> True }
229 compare (_:_) [] = GT
230 compare [] (_:_) = LT
231 compare (x:xs) (y:ys) = case compare x y of
236 instance Functor [] where
239 instance Monad [] where
240 m >>= k = foldr ((++) . k) [] m
241 m >> k = foldr ((++) . (\ _ -> k)) [] m
246 A few list functions that appear here because they are used here.
247 The rest of the prelude list functions are in PrelList.
249 ----------------------------------------------
250 -- foldr/build/augment
251 ----------------------------------------------
254 foldr :: (a -> b -> b) -> b -> [a] -> b
256 -- foldr f z (x:xs) = f x (foldr f z xs)
261 go (x:xs) = x `k` go xs
263 build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
264 {-# INLINE 2 build #-}
265 -- The INLINE is important, even though build is tiny,
266 -- because it prevents [] getting inlined in the version that
267 -- appears in the interface file. If [] *is* inlined, it
268 -- won't match with [] appearing in rules in an importing module.
270 -- The "2" says to inline in phase 2
274 augment :: forall a. (forall b. (a->b->b) -> b -> b) -> [a] -> [a]
275 {-# INLINE 2 augment #-}
276 augment g xs = g (:) xs
279 "fold/build" forall k z (g::forall b. (a->b->b) -> b -> b) .
280 foldr k z (build g) = g k z
282 "foldr/augment" forall k z xs (g::forall b. (a->b->b) -> b -> b) .
283 foldr k z (augment g xs) = g k (foldr k z xs)
285 "foldr/id" foldr (:) [] = \x->x
286 "foldr/app" forall xs ys. foldr (:) ys xs = append xs ys
288 "foldr/cons" forall k z x xs. foldr k z (x:xs) = k x (foldr k z xs)
289 "foldr/nil" forall k z. foldr k z [] = z
291 "augment/build" forall (g::forall b. (a->b->b) -> b -> b)
292 (h::forall b. (a->b->b) -> b -> b) .
293 augment g (build h) = build (\c n -> g c (h c n))
294 "augment/nil" forall (g::forall b. (a->b->b) -> b -> b) .
295 augment g [] = build g
298 -- This rule is true, but not (I think) useful:
299 -- augment g (augment h t) = augment (\cn -> g c (h c n)) t
303 ----------------------------------------------
305 ----------------------------------------------
308 map :: (a -> b) -> [a] -> [b]
312 mapFB c f x ys = c (f x) ys
314 mapList :: (a -> b) -> [a] -> [b]
316 mapList f (x:xs) = f x : mapList f xs
319 "map" forall f xs. map f xs = build (\c n -> foldr (mapFB c f) n xs)
320 "mapFB" forall c f g. mapFB (mapFB c f) g = mapFB c (f.g)
321 "mapList" forall f. foldr (mapFB (:) f) [] = mapList f
326 ----------------------------------------------
328 ----------------------------------------------
330 (++) :: [a] -> [a] -> [a]
334 "++" forall xs ys. (++) xs ys = augment (\c n -> foldr c n xs) ys
337 append :: [a] -> [a] -> [a]
339 append (x:xs) ys = x : append xs ys
343 %*********************************************************
345 \subsection{Type @Bool@}
347 %*********************************************************
350 data Bool = False | True deriving (Eq, Ord)
351 -- Read in PrelRead, Show in PrelShow
355 (&&), (||) :: Bool -> Bool -> Bool
370 %*********************************************************
372 \subsection{The @()@ type}
374 %*********************************************************
376 The Unit type is here because virtually any program needs it (whereas
377 some programs may get away without consulting PrelTup). Furthermore,
378 the renamer currently *always* asks for () to be in scope, so that
379 ccalls can use () as their default type; so when compiling PrelBase we
380 need (). (We could arrange suck in () only if -fglasgow-exts, but putting
381 it here seems more direct.)
390 instance Ord () where
401 %*********************************************************
403 \subsection{Type @Ordering@}
405 %*********************************************************
408 data Ordering = LT | EQ | GT deriving (Eq, Ord)
409 -- Read in PrelRead, Show in PrelShow
413 %*********************************************************
415 \subsection{Type @Char@ and @String@}
417 %*********************************************************
424 -- We don't use deriving for Eq and Ord, because for Ord the derived
425 -- instance defines only compare, which takes two primops. Then
426 -- '>' uses compare, and therefore takes two primops instead of one.
428 instance Eq Char where
429 (C# c1) == (C# c2) = c1 `eqChar#` c2
430 (C# c1) /= (C# c2) = c1 `neChar#` c2
432 instance Ord Char where
433 (C# c1) > (C# c2) = c1 `gtChar#` c2
434 (C# c1) >= (C# c2) = c1 `geChar#` c2
435 (C# c1) <= (C# c2) = c1 `leChar#` c2
436 (C# c1) < (C# c2) = c1 `ltChar#` c2
439 chr (I# i) | i >=# 0# && i <=# 255# = C# (chr# i)
440 | otherwise = error ("Prelude.chr: bad argument")
442 unsafeChr :: Int -> Char
443 unsafeChr (I# i) = C# (chr# i)
446 ord (C# c) = I# (ord# c)
450 %*********************************************************
452 \subsection{Type @Int@}
454 %*********************************************************
459 zeroInt, oneInt, twoInt, maxInt, minInt :: Int
463 minInt = I# (-2147483648#) -- GHC <= 2.09 had this at -2147483647
464 maxInt = I# 2147483647#
466 instance Eq Int where
467 (==) x y = x `eqInt` y
468 (/=) x y = x `neInt` y
470 instance Ord Int where
471 compare x y = compareInt x y
478 compareInt :: Int -> Int -> Ordering
479 (I# x) `compareInt` (I# y) | x <# y = LT
485 %*********************************************************
487 \subsection{The function type}
489 %*********************************************************
500 -- function composition
502 (.) :: (b -> c) -> (a -> b) -> a -> c
505 -- flip f takes its (first) two arguments in the reverse order of f.
506 flip :: (a -> b -> c) -> b -> a -> c
509 -- right-associating infix application operator (useful in continuation-
511 ($) :: (a -> b) -> a -> b
514 -- until p f yields the result of applying f until p holds.
515 until :: (a -> Bool) -> (a -> a) -> a -> a
516 until p f x | p x = x
517 | otherwise = until p f (f x)
519 -- asTypeOf is a type-restricted version of const. It is usually used
520 -- as an infix operator, and its typing forces its first argument
521 -- (which is usually overloaded) to have the same type as the second.
522 asTypeOf :: a -> a -> a
526 %*********************************************************
528 \subsection{CCallable instances}
530 %*********************************************************
532 Defined here to avoid orphans
535 instance CCallable Char
536 instance CReturnable Char
538 instance CCallable Int
539 instance CReturnable Int
541 instance CReturnable () -- Why, exactly?
545 %*********************************************************
547 \subsection{Numeric primops}
549 %*********************************************************
551 Definitions of the boxed PrimOps; these will be
552 used in the case of partial applications, etc.
561 {-# INLINE plusInt #-}
562 {-# INLINE minusInt #-}
563 {-# INLINE timesInt #-}
564 {-# INLINE quotInt #-}
565 {-# INLINE remInt #-}
566 {-# INLINE negateInt #-}
568 plusInt, minusInt, timesInt, quotInt, remInt, gcdInt :: Int -> Int -> Int
569 plusInt (I# x) (I# y) = I# (x +# y)
570 minusInt(I# x) (I# y) = I# (x -# y)
571 timesInt(I# x) (I# y) = I# (x *# y)
572 quotInt (I# x) (I# y) = I# (quotInt# x y)
573 remInt (I# x) (I# y) = I# (remInt# x y)
574 gcdInt (I# a) (I# b) = I# (gcdInt# a b)
576 negateInt :: Int -> Int
577 negateInt (I# x) = I# (negateInt# x)
579 divInt, modInt :: Int -> Int -> Int
581 | x > zeroInt && y < zeroInt = quotInt ((x `minusInt` y) `minusInt` oneInt) y
582 | x < zeroInt && y > zeroInt = quotInt ((x `minusInt` y) `plusInt` oneInt) y
583 | otherwise = quotInt x y
586 | x > zeroInt && y < zeroInt ||
587 x < zeroInt && y > zeroInt = if r/=zeroInt then r `plusInt` y else zeroInt
592 gtInt, geInt, eqInt, neInt, ltInt, leInt :: Int -> Int -> Bool
593 gtInt (I# x) (I# y) = x ># y
594 geInt (I# x) (I# y) = x >=# y
595 eqInt (I# x) (I# y) = x ==# y
596 neInt (I# x) (I# y) = x /=# y
597 ltInt (I# x) (I# y) = x <# y
598 leInt (I# x) (I# y) = x <=# y
602 %********************************************************
604 \subsection{Unpacking C strings}
606 %********************************************************
608 This code is needed for virtually all programs, since it's used for
609 unpacking the strings of error messages.
612 unpackCString# :: Addr# -> [Char]
613 unpackCString# a = unpackCStringList# a
615 unpackCStringList# :: Addr# -> [Char]
616 unpackCStringList# addr
620 | ch `eqChar#` '\0'# = []
621 | otherwise = C# ch : unpack (nh +# 1#)
623 ch = indexCharOffAddr# addr nh
625 unpackAppendCString# :: Addr# -> [Char] -> [Char]
626 unpackAppendCString# addr rest
630 | ch `eqChar#` '\0'# = rest
631 | otherwise = C# ch : unpack (nh +# 1#)
633 ch = indexCharOffAddr# addr nh
635 unpackFoldrCString# :: Addr# -> (Char -> a -> a) -> a -> a
636 unpackFoldrCString# addr f z
640 | ch `eqChar#` '\0'# = z
641 | otherwise = C# ch `f` unpack (nh +# 1#)
643 ch = indexCharOffAddr# addr nh
645 unpackNBytes# :: Addr# -> Int# -> [Char]
646 -- This one is called by the compiler to unpack literal
647 -- strings with NULs in them; rare. It's strict!
648 -- We don't try to do list deforestation for this one
650 unpackNBytes# _addr 0# = []
651 unpackNBytes# addr len# = unpack [] (len# -# 1#)
656 case indexCharOffAddr# addr i# of
657 ch -> unpack (C# ch : acc) (i# -# 1#)
660 "unpack" forall a . unpackCString# a = build (unpackFoldrCString# a)
661 "unpack-list" forall a . unpackFoldrCString# a (:) [] = unpackCStringList# a
662 "unpack-append" forall a n . unpackFoldrCString# a (:) n = unpackAppendCString# a n
664 -- There's a built-in rule (in PrelRules.lhs) for
665 -- unpackFoldr "foo" c (unpackFoldr "baz" c n) = unpackFoldr "foobaz" c n