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 -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 )
85 import {-# SOURCE #-} PrelNum ( addr2Integer )
86 -- Otherwise the system import of addr2Integer looks for PrelNum.hi
92 infix 4 ==, /=, <, <=, >=, >
98 default () -- Double isn't available yet
102 %*********************************************************
104 \subsection{DEBUGGING STUFF}
105 %* (for use when compiling PrelBase itself doesn't work)
107 %*********************************************************
111 data Bool = False | True
112 data Ordering = LT | EQ | GT
120 (&&) True True = True
126 unpackCString# :: Addr# -> [Char]
127 unpackFoldrCString# :: Addr# -> (Char -> a -> a) -> a -> a
128 unpackAppendCString# :: Addr# -> [Char] -> [Char]
129 unpackNBytes# :: Addr# -> Int# -> [Char]
130 unpackNBytes# a b = error "urk"
131 unpackCString# a = error "urk"
132 unpackFoldrCString# a = error "urk"
133 unpackAppendCString# a = error "urk"
138 %*********************************************************
140 \subsection{Standard classes @Eq@, @Ord@}
142 %*********************************************************
146 (==), (/=) :: a -> a -> Bool
148 -- x /= y = not (x == y)
149 -- x == y = not (x /= y)
151 (/=) x y = not ((==) x y)
154 class (Eq a) => Ord a where
155 compare :: a -> a -> Ordering
156 (<), (<=), (>=), (>):: a -> a -> Bool
157 max, min :: a -> a -> a
159 -- An instance of Ord should define either compare or <=
160 -- Using compare can be more efficient for complex types.
163 | x <= y = LT -- NB: must be '<=' not '<' to validate the
164 -- above claim about the minimal things that can
165 -- be defined for an instance of Ord
168 x <= y = case compare x y of { GT -> False; _other -> True }
169 x < y = case compare x y of { LT -> True; _other -> False }
170 x >= y = case compare x y of { LT -> False; _other -> True }
171 x > y = case compare x y of { GT -> True; _other -> False }
173 -- These two default methods use '>' rather than compare
174 -- because the latter is often more expensive
175 max x y = if x > y then x else y
176 min x y = if x > y then y else x
179 %*********************************************************
181 \subsection{Monadic classes @Functor@, @Monad@ }
183 %*********************************************************
186 class Functor f where
187 fmap :: (a -> b) -> f a -> f b
190 (>>=) :: m a -> (a -> m b) -> m b
191 (>>) :: m a -> m b -> m b
193 fail :: String -> m a
195 m >> k = m >>= \_ -> k
201 %*********************************************************
203 \subsection{The list type}
205 %*********************************************************
208 data [] a = [] | a : [a] -- do explicitly: deriving (Eq, Ord)
209 -- to avoid weird names like con2tag_[]#
212 instance (Eq a) => Eq [a] where
214 {-# SPECIALISE instance Eq [Char] #-}
217 (x:xs) == (y:ys) = x == y && xs == ys
220 xs /= ys = if (xs == ys) then False else True
222 instance (Ord a) => Ord [a] where
224 {-# SPECIALISE instance Ord [Char] #-}
226 a < b = case compare a b of { LT -> True; EQ -> False; GT -> False }
227 a <= b = case compare a b of { LT -> True; EQ -> True; GT -> False }
228 a >= b = case compare a b of { LT -> False; EQ -> True; GT -> True }
229 a > b = case compare a b of { LT -> False; EQ -> False; GT -> True }
232 compare (_:_) [] = GT
233 compare [] (_:_) = LT
234 compare (x:xs) (y:ys) = case compare x y of
239 instance Functor [] where
242 instance Monad [] where
243 m >>= k = foldr ((++) . k) [] m
244 m >> k = foldr ((++) . (\ _ -> k)) [] m
249 A few list functions that appear here because they are used here.
250 The rest of the prelude list functions are in PrelList.
252 ----------------------------------------------
253 -- foldr/build/augment
254 ----------------------------------------------
257 foldr :: (a -> b -> b) -> b -> [a] -> b
259 -- foldr f z (x:xs) = f x (foldr f z xs)
264 go (x:xs) = x `k` go xs
266 build :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
267 {-# INLINE 2 build #-}
268 -- The INLINE is important, even though build is tiny,
269 -- because it prevents [] getting inlined in the version that
270 -- appears in the interface file. If [] *is* inlined, it
271 -- won't match with [] appearing in rules in an importing module.
273 -- The "2" says to inline in phase 2
277 augment :: forall a. (forall b. (a->b->b) -> b -> b) -> [a] -> [a]
278 {-# INLINE 2 augment #-}
279 augment g xs = g (:) xs
282 "fold/build" forall k z (g::forall b. (a->b->b) -> b -> b) .
283 foldr k z (build g) = g k z
285 "foldr/augment" forall k z xs (g::forall b. (a->b->b) -> b -> b) .
286 foldr k z (augment g xs) = g k (foldr k z xs)
288 "foldr/id" foldr (:) [] = \x->x
289 "foldr/app" forall xs ys. foldr (:) ys xs = append xs ys
291 "foldr/cons" forall k z x xs. foldr k z (x:xs) = k x (foldr k z xs)
292 "foldr/nil" forall k z. foldr k z [] = z
294 "augment/build" forall (g::forall b. (a->b->b) -> b -> b)
295 (h::forall b. (a->b->b) -> b -> b) .
296 augment g (build h) = build (\c n -> g c (h c n))
297 "augment/nil" forall (g::forall b. (a->b->b) -> b -> b) .
298 augment g [] = build g
301 -- This rule is true, but not (I think) useful:
302 -- augment g (augment h t) = augment (\cn -> g c (h c n)) t
306 ----------------------------------------------
308 ----------------------------------------------
311 map :: (a -> b) -> [a] -> [b]
315 mapFB c f x ys = c (f x) ys
317 mapList :: (a -> b) -> [a] -> [b]
319 mapList f (x:xs) = f x : mapList f xs
322 "map" forall f xs. map f xs = build (\c n -> foldr (mapFB c f) n xs)
323 "mapFB" forall c f g. mapFB (mapFB c f) g = mapFB c (f.g)
324 "mapList" forall f. foldr (mapFB (:) f) [] = mapList f
329 ----------------------------------------------
331 ----------------------------------------------
333 (++) :: [a] -> [a] -> [a]
337 "++" forall xs ys. (++) xs ys = augment (\c n -> foldr c n xs) ys
340 append :: [a] -> [a] -> [a]
342 append (x:xs) ys = x : append xs ys
346 %*********************************************************
348 \subsection{Type @Bool@}
350 %*********************************************************
353 data Bool = False | True deriving (Eq, Ord)
354 -- Read in PrelRead, Show in PrelShow
358 (&&), (||) :: Bool -> Bool -> Bool
373 %*********************************************************
375 \subsection{The @()@ type}
377 %*********************************************************
379 The Unit type is here because virtually any program needs it (whereas
380 some programs may get away without consulting PrelTup). Furthermore,
381 the renamer currently *always* asks for () to be in scope, so that
382 ccalls can use () as their default type; so when compiling PrelBase we
383 need (). (We could arrange suck in () only if -fglasgow-exts, but putting
384 it here seems more direct.)
393 instance Ord () where
404 %*********************************************************
406 \subsection{Type @Ordering@}
408 %*********************************************************
411 data Ordering = LT | EQ | GT deriving (Eq, Ord)
412 -- Read in PrelRead, Show in PrelShow
416 %*********************************************************
418 \subsection{Type @Char@ and @String@}
420 %*********************************************************
427 -- We don't use deriving for Eq and Ord, because for Ord the derived
428 -- instance defines only compare, which takes two primops. Then
429 -- '>' uses compare, and therefore takes two primops instead of one.
431 instance Eq Char where
432 (C# c1) == (C# c2) = c1 `eqChar#` c2
433 (C# c1) /= (C# c2) = c1 `neChar#` c2
435 instance Ord Char where
436 (C# c1) > (C# c2) = c1 `gtChar#` c2
437 (C# c1) >= (C# c2) = c1 `geChar#` c2
438 (C# c1) <= (C# c2) = c1 `leChar#` c2
439 (C# c1) < (C# c2) = c1 `ltChar#` c2
442 chr (I# i) | i >=# 0# && i <=# 255# = C# (chr# i)
443 | otherwise = error ("Prelude.chr: bad argument")
445 unsafeChr :: Int -> Char
446 unsafeChr (I# i) = C# (chr# i)
449 ord (C# c) = I# (ord# c)
453 %*********************************************************
455 \subsection{Type @Int@}
457 %*********************************************************
462 zeroInt, oneInt, twoInt, maxInt, minInt :: Int
466 minInt = I# (-2147483648#) -- GHC <= 2.09 had this at -2147483647
467 maxInt = I# 2147483647#
469 instance Eq Int where
470 (==) x y = x `eqInt` y
471 (/=) x y = x `neInt` y
473 instance Ord Int where
474 compare x y = compareInt x y
481 compareInt :: Int -> Int -> Ordering
482 (I# x) `compareInt` (I# y) | x <# y = LT
488 %*********************************************************
490 \subsection{The function type}
492 %*********************************************************
503 -- function composition
505 (.) :: (b -> c) -> (a -> b) -> a -> c
508 -- flip f takes its (first) two arguments in the reverse order of f.
509 flip :: (a -> b -> c) -> b -> a -> c
512 -- right-associating infix application operator (useful in continuation-
514 ($) :: (a -> b) -> a -> b
517 -- until p f yields the result of applying f until p holds.
518 until :: (a -> Bool) -> (a -> a) -> a -> a
519 until p f x | p x = x
520 | otherwise = until p f (f x)
522 -- asTypeOf is a type-restricted version of const. It is usually used
523 -- as an infix operator, and its typing forces its first argument
524 -- (which is usually overloaded) to have the same type as the second.
525 asTypeOf :: a -> a -> a
529 %*********************************************************
531 \subsection{CCallable instances}
533 %*********************************************************
535 Defined here to avoid orphans
538 instance CCallable Char
539 instance CReturnable Char
541 instance CCallable Int
542 instance CReturnable Int
544 instance CReturnable () -- Why, exactly?
548 %*********************************************************
550 \subsection{Numeric primops}
552 %*********************************************************
554 Definitions of the boxed PrimOps; these will be
555 used in the case of partial applications, etc.
564 {-# INLINE plusInt #-}
565 {-# INLINE minusInt #-}
566 {-# INLINE timesInt #-}
567 {-# INLINE quotInt #-}
568 {-# INLINE remInt #-}
569 {-# INLINE negateInt #-}
571 plusInt, minusInt, timesInt, quotInt, remInt, gcdInt :: Int -> Int -> Int
572 plusInt (I# x) (I# y) = I# (x +# y)
573 minusInt(I# x) (I# y) = I# (x -# y)
574 timesInt(I# x) (I# y) = I# (x *# y)
575 quotInt (I# x) (I# y) = I# (quotInt# x y)
576 remInt (I# x) (I# y) = I# (remInt# x y)
577 gcdInt (I# a) (I# b) = I# (gcdInt# a b)
579 negateInt :: Int -> Int
580 negateInt (I# x) = I# (negateInt# x)
582 divInt, modInt :: Int -> Int -> Int
584 | x > zeroInt && y < zeroInt = quotInt ((x `minusInt` y) `minusInt` oneInt) y
585 | x < zeroInt && y > zeroInt = quotInt ((x `minusInt` y) `plusInt` oneInt) y
586 | otherwise = quotInt x y
589 | x > zeroInt && y < zeroInt ||
590 x < zeroInt && y > zeroInt = if r/=zeroInt then r `plusInt` y else zeroInt
595 gtInt, geInt, eqInt, neInt, ltInt, leInt :: Int -> Int -> Bool
596 gtInt (I# x) (I# y) = x ># y
597 geInt (I# x) (I# y) = x >=# y
598 eqInt (I# x) (I# y) = x ==# y
599 neInt (I# x) (I# y) = x /=# y
600 ltInt (I# x) (I# y) = x <# y
601 leInt (I# x) (I# y) = x <=# y
605 %********************************************************
607 \subsection{Unpacking C strings}
609 %********************************************************
611 This code is needed for virtually all programs, since it's used for
612 unpacking the strings of error messages.
615 unpackCString# :: Addr# -> [Char]
616 unpackCString# a = unpackCStringList# a
618 unpackCStringList# :: Addr# -> [Char]
619 unpackCStringList# addr
623 | ch `eqChar#` '\0'# = []
624 | otherwise = C# ch : unpack (nh +# 1#)
626 ch = indexCharOffAddr# addr nh
628 unpackAppendCString# :: Addr# -> [Char] -> [Char]
629 unpackAppendCString# addr rest
633 | ch `eqChar#` '\0'# = rest
634 | otherwise = C# ch : unpack (nh +# 1#)
636 ch = indexCharOffAddr# addr nh
638 unpackFoldrCString# :: Addr# -> (Char -> a -> a) -> a -> a
639 unpackFoldrCString# addr f z
643 | ch `eqChar#` '\0'# = z
644 | otherwise = C# ch `f` unpack (nh +# 1#)
646 ch = indexCharOffAddr# addr nh
648 unpackNBytes# :: Addr# -> Int# -> [Char]
649 -- This one is called by the compiler to unpack literal
650 -- strings with NULs in them; rare. It's strict!
651 -- We don't try to do list deforestation for this one
653 unpackNBytes# _addr 0# = []
654 unpackNBytes# addr len# = unpack [] (len# -# 1#)
659 case indexCharOffAddr# addr i# of
660 ch -> unpack (C# ch : acc) (i# -# 1#)
663 "unpack" forall a . unpackCString# a = build (unpackFoldrCString# a)
664 "unpack-list" forall a . unpackFoldrCString# a (:) [] = unpackCStringList# a
665 "unpack-append" forall a n . unpackFoldrCString# a (:) n = unpackAppendCString# a n
667 -- There's a built-in rule (in PrelRules.lhs) for
668 -- unpackFoldr "foo" c (unpackFoldr "baz" c n) = unpackFoldr "foobaz" c n