[project @ 2003-09-05 17:36:40 by ross]
[packages/old-time.git] / GHC / Base.lhs
1 \section[GHC.Base]{Module @GHC.Base@}
2
3 The overall structure of the GHC Prelude is a bit tricky.
4
5   a) We want to avoid "orphan modules", i.e. ones with instance
6         decls that don't belong either to a tycon or a class
7         defined in the same module
8
9   b) We want to avoid giant modules
10
11 So the rough structure is as follows, in (linearised) dependency order
12
13
14 GHC.Prim                Has no implementation.  It defines built-in things, and
15                 by importing it you bring them into scope.
16                 The source file is GHC.Prim.hi-boot, which is just
17                 copied to make GHC.Prim.hi
18
19                 Classes: CCallable, CReturnable
20
21 GHC.Base        Classes: Eq, Ord, Functor, Monad
22                 Types:   list, (), Int, Bool, Ordering, Char, String
23
24 Data.Tup        Types: tuples, plus instances for GHC.Base classes
25
26 GHC.Show        Class: Show, plus instances for GHC.Base/GHC.Tup types
27
28 GHC.Enum        Class: Enum,  plus instances for GHC.Base/GHC.Tup types
29
30 Data.Maybe      Type: Maybe, plus instances for GHC.Base classes
31
32 GHC.Num         Class: Num, plus instances for Int
33                 Type:  Integer, plus instances for all classes so far (Eq, Ord, Num, Show)
34
35                 Integer is needed here because it is mentioned in the signature
36                 of 'fromInteger' in class Num
37
38 GHC.Real        Classes: Real, Integral, Fractional, RealFrac
39                          plus instances for Int, Integer
40                 Types:  Ratio, Rational
41                         plus intances for classes so far
42
43                 Rational is needed here because it is mentioned in the signature
44                 of 'toRational' in class Real
45
46 Ix              Classes: Ix, plus instances for Int, Bool, Char, Integer, Ordering, tuples
47
48 GHC.Arr         Types: Array, MutableArray, MutableVar
49
50                 Does *not* contain any ByteArray stuff (see GHC.ByteArr)
51                 Arrays are used by a function in GHC.Float
52
53 GHC.Float       Classes: Floating, RealFloat
54                 Types:   Float, Double, plus instances of all classes so far
55
56                 This module contains everything to do with floating point.
57                 It is a big module (900 lines)
58                 With a bit of luck, many modules can be compiled without ever reading GHC.Float.hi
59
60 GHC.ByteArr     Types: ByteArray, MutableByteArray
61                 
62                 We want this one to be after GHC.Float, because it defines arrays
63                 of unboxed floats.
64
65
66 Other Prelude modules are much easier with fewer complex dependencies.
67
68 \begin{code}
69 {-# OPTIONS -fno-implicit-prelude #-}
70 -----------------------------------------------------------------------------
71 -- |
72 -- Module      :  GHC.Base
73 -- Copyright   :  (c) The University of Glasgow, 1992-2002
74 -- License     :  see libraries/base/LICENSE
75 -- 
76 -- Maintainer  :  cvs-ghc@haskell.org
77 -- Stability   :  internal
78 -- Portability :  non-portable (GHC extensions)
79 --
80 -- Basic data types and classes.
81 -- 
82 -----------------------------------------------------------------------------
83
84 #include "MachDeps.h"
85
86 module GHC.Base
87         (
88         module GHC.Base,
89         module GHC.Prim,        -- Re-export GHC.Prim and GHC.Err, to avoid lots
90         module GHC.Err          -- of people having to import it explicitly
91   ) 
92         where
93
94 import GHC.Prim
95 import {-# SOURCE #-} GHC.Err
96
97 infixr 9  .
98 infixr 5  ++, :
99 infix  4  ==, /=, <, <=, >=, >
100 infixr 3  &&
101 infixr 2  ||
102 infixl 1  >>, >>=
103 infixr 0  $
104
105 default ()              -- Double isn't available yet
106 \end{code}
107
108
109 %*********************************************************
110 %*                                                      *
111 \subsection{DEBUGGING STUFF}
112 %*  (for use when compiling GHC.Base itself doesn't work)
113 %*                                                      *
114 %*********************************************************
115
116 \begin{code}
117 {-
118 data  Bool  =  False | True
119 data Ordering = LT | EQ | GT 
120 data Char = C# Char#
121 type  String = [Char]
122 data Int = I# Int#
123 data  ()  =  ()
124 data [] a = MkNil
125
126 not True = False
127 (&&) True True = True
128 otherwise = True
129
130 build = error "urk"
131 foldr = error "urk"
132
133 unpackCString# :: Addr# -> [Char]
134 unpackFoldrCString# :: Addr# -> (Char  -> a -> a) -> a -> a 
135 unpackAppendCString# :: Addr# -> [Char] -> [Char]
136 unpackCStringUtf8# :: Addr# -> [Char]
137 unpackCString# a = error "urk"
138 unpackFoldrCString# a = error "urk"
139 unpackAppendCString# a = error "urk"
140 unpackCStringUtf8# a = error "urk"
141 -}
142 \end{code}
143
144
145 %*********************************************************
146 %*                                                      *
147 \subsection{Standard classes @Eq@, @Ord@}
148 %*                                                      *
149 %*********************************************************
150
151 \begin{code}
152
153 -- | The 'Eq' class defines equality ('==') and inequality ('/=').
154 -- All the basic datatypes exported by the "Prelude" are instances of 'Eq',
155 -- and 'Eq' may be derived for any datatype whose constituents are also
156 -- instances of 'Eq'.
157 --
158 -- Minimal complete definition: either '==' or '/='.
159 --
160 class  Eq a  where
161     (==), (/=)           :: a -> a -> Bool
162
163     x /= y               = not (x == y)
164     x == y               = not (x /= y)
165
166 class  (Eq a) => Ord a  where
167     compare              :: a -> a -> Ordering
168     (<), (<=), (>), (>=) :: a -> a -> Bool
169     max, min             :: a -> a -> a
170
171     -- An instance of Ord should define either 'compare' or '<='.
172     -- Using 'compare' can be more efficient for complex types.
173
174     compare x y
175         | x == y    = EQ
176         | x <= y    = LT        -- NB: must be '<=' not '<' to validate the
177                                 -- above claim about the minimal things that
178                                 -- can be defined for an instance of Ord
179         | otherwise = GT
180
181     x <  y = case compare x y of { LT -> True;  _other -> False }
182     x <= y = case compare x y of { GT -> False; _other -> True }
183     x >  y = case compare x y of { GT -> True;  _other -> False }
184     x >= y = case compare x y of { LT -> False; _other -> True }
185
186         -- These two default methods use '<=' rather than 'compare'
187         -- because the latter is often more expensive
188     max x y = if x <= y then y else x
189     min x y = if x <= y then x else y
190 \end{code}
191
192 %*********************************************************
193 %*                                                      *
194 \subsection{Monadic classes @Functor@, @Monad@ }
195 %*                                                      *
196 %*********************************************************
197
198 \begin{code}
199 {- | The 'Functor' class is used for types that can be mapped over.
200 Instances of 'Functor' should satisfy the following laws:
201
202 > fmap id  ==  id
203 > fmap (f . g)  ==  fmap f . fmap g
204
205 The instances of 'Functor' for lists, 'Maybe' and 'IO' defined in the "Prelude"
206 satisfy these laws.
207 -}
208
209 class  Functor f  where
210     fmap        :: (a -> b) -> f a -> f b
211
212 {- | The 'Monad' class defines the basic operations over a /monad/.
213 Instances of 'Monad' should satisfy the following laws:
214
215 > return a >>= k  ==  k a
216 > m >>= return  ==  m
217 > m >>= (\x -> k x >>= h)  ==  (m >>= k) >>= h
218
219 Instances of both 'Monad' and 'Functor' should additionally satisfy the law:
220
221 > fmap f xs  ==  xs >>= return . f
222
223 The instances of 'Monad' for lists, 'Maybe' and 'IO' defined in the "Prelude"
224 satisfy these laws.
225 -}
226
227 class  Monad m  where
228     (>>=)       :: m a -> (a -> m b) -> m b
229     (>>)        :: m a -> m b -> m b
230     return      :: a -> m a
231     fail        :: String -> m a
232
233     m >> k      = m >>= \_ -> k
234     fail s      = error s
235 \end{code}
236
237
238 %*********************************************************
239 %*                                                      *
240 \subsection{The list type}
241 %*                                                      *
242 %*********************************************************
243
244 \begin{code}
245 data [] a = [] | a : [a]  -- do explicitly: deriving (Eq, Ord)
246                           -- to avoid weird names like con2tag_[]#
247
248
249 instance (Eq a) => Eq [a] where
250     {-# SPECIALISE instance Eq [Char] #-}
251     []     == []     = True
252     (x:xs) == (y:ys) = x == y && xs == ys
253     _xs    == _ys    = False
254
255 instance (Ord a) => Ord [a] where
256     {-# SPECIALISE instance Ord [Char] #-}
257     compare []     []     = EQ
258     compare []     (_:_)  = LT
259     compare (_:_)  []     = GT
260     compare (x:xs) (y:ys) = case compare x y of
261                                 EQ    -> compare xs ys
262                                 other -> other
263
264 instance Functor [] where
265     fmap = map
266
267 instance  Monad []  where
268     m >>= k             = foldr ((++) . k) [] m
269     m >> k              = foldr ((++) . (\ _ -> k)) [] m
270     return x            = [x]
271     fail _              = []
272 \end{code}
273
274 A few list functions that appear here because they are used here.
275 The rest of the prelude list functions are in GHC.List.
276
277 ----------------------------------------------
278 --      foldr/build/augment
279 ----------------------------------------------
280   
281 \begin{code}
282 -- | 'foldr', applied to a binary operator, a starting value (typically
283 -- the right-identity of the operator), and a list, reduces the list
284 -- using the binary operator, from right to left:
285 --
286 -- > foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
287
288 foldr            :: (a -> b -> b) -> b -> [a] -> b
289 -- foldr _ z []     =  z
290 -- foldr f z (x:xs) =  f x (foldr f z xs)
291 {-# INLINE [0] foldr #-}
292 -- Inline only in the final stage, after the foldr/cons rule has had a chance
293 foldr k z xs = go xs
294              where
295                go []     = z
296                go (y:ys) = y `k` go ys
297
298 build   :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
299 {-# INLINE [1] build #-}
300         -- The INLINE is important, even though build is tiny,
301         -- because it prevents [] getting inlined in the version that
302         -- appears in the interface file.  If [] *is* inlined, it
303         -- won't match with [] appearing in rules in an importing module.
304         --
305         -- The "1" says to inline in phase 1
306
307 build g = g (:) []
308
309 augment :: forall a. (forall b. (a->b->b) -> b -> b) -> [a] -> [a]
310 {-# INLINE [1] augment #-}
311 augment g xs = g (:) xs
312
313 {-# RULES
314 "fold/build"    forall k z (g::forall b. (a->b->b) -> b -> b) . 
315                 foldr k z (build g) = g k z
316
317 "foldr/augment" forall k z xs (g::forall b. (a->b->b) -> b -> b) . 
318                 foldr k z (augment g xs) = g k (foldr k z xs)
319
320 "foldr/id"                        foldr (:) [] = \x->x
321 "foldr/app"     [1] forall xs ys. foldr (:) ys xs = xs ++ ys
322         -- Only activate this from phase 1, because that's
323         -- when we disable the rule that expands (++) into foldr
324
325 -- The foldr/cons rule looks nice, but it can give disastrously
326 -- bloated code when commpiling
327 --      array (a,b) [(1,2), (2,2), (3,2), ...very long list... ]
328 -- i.e. when there are very very long literal lists
329 -- So I've disabled it for now. We could have special cases
330 -- for short lists, I suppose.
331 -- "foldr/cons" forall k z x xs. foldr k z (x:xs) = k x (foldr k z xs)
332
333 "foldr/single"  forall k z x. foldr k z [x] = k x z
334 "foldr/nil"     forall k z.   foldr k z []  = z 
335
336 "augment/build" forall (g::forall b. (a->b->b) -> b -> b)
337                        (h::forall b. (a->b->b) -> b -> b) .
338                        augment g (build h) = build (\c n -> g c (h c n))
339 "augment/nil"   forall (g::forall b. (a->b->b) -> b -> b) .
340                         augment g [] = build g
341  #-}
342
343 -- This rule is true, but not (I think) useful:
344 --      augment g (augment h t) = augment (\cn -> g c (h c n)) t
345 \end{code}
346
347
348 ----------------------------------------------
349 --              map     
350 ----------------------------------------------
351
352 \begin{code}
353 -- | 'map' @f xs@ is the list obtained by applying @f@ to each element
354 -- of @xs@, i.e.,
355 --
356 -- > map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
357 -- > map f [x1, x2, ...] == [f x1, f x2, ...]
358
359 map :: (a -> b) -> [a] -> [b]
360 map _ []     = []
361 map f (x:xs) = f x : map f xs
362
363 -- Note eta expanded
364 mapFB ::  (elt -> lst -> lst) -> (a -> elt) -> a -> lst -> lst
365 {-# INLINE [0] mapFB #-}
366 mapFB c f x ys = c (f x) ys
367
368 -- The rules for map work like this.
369 -- 
370 -- Up to (but not including) phase 1, we use the "map" rule to
371 -- rewrite all saturated applications of map with its build/fold 
372 -- form, hoping for fusion to happen.
373 -- In phase 1 and 0, we switch off that rule, inline build, and
374 -- switch on the "mapList" rule, which rewrites the foldr/mapFB
375 -- thing back into plain map.  
376 --
377 -- It's important that these two rules aren't both active at once 
378 -- (along with build's unfolding) else we'd get an infinite loop 
379 -- in the rules.  Hence the activation control below.
380 --
381 -- The "mapFB" rule optimises compositions of map.
382 --
383 -- This same pattern is followed by many other functions: 
384 -- e.g. append, filter, iterate, repeat, etc.
385
386 {-# RULES
387 "map"       [~1] forall f xs.   map f xs                = build (\c n -> foldr (mapFB c f) n xs)
388 "mapList"   [1]  forall f.      foldr (mapFB (:) f) []  = map f
389 "mapFB"     forall c f g.       mapFB (mapFB c f) g     = mapFB c (f.g) 
390   #-}
391 \end{code}
392
393
394 ----------------------------------------------
395 --              append  
396 ----------------------------------------------
397 \begin{code}
398 -- | Append two lists, i.e.,
399 --
400 -- > [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
401 -- > [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
402 --
403 -- If the first list is not finite, the result is the first list.
404
405 (++) :: [a] -> [a] -> [a]
406 (++) []     ys = ys
407 (++) (x:xs) ys = x : xs ++ ys
408
409 {-# RULES
410 "++"    [~1] forall xs ys. xs ++ ys = augment (\c n -> foldr c n xs) ys
411   #-}
412
413 \end{code}
414
415
416 %*********************************************************
417 %*                                                      *
418 \subsection{Type @Bool@}
419 %*                                                      *
420 %*********************************************************
421
422 \begin{code}
423 -- |The 'Bool' type is an enumeration.  It is defined with 'False'
424 -- first so that the corresponding 'Prelude.Enum' instance will give
425 -- 'Prelude.fromEnum' 'False' the value zero, and
426 -- 'Prelude.fromEnum' 'True' the value 1.
427 data  Bool  =  False | True  deriving (Eq, Ord)
428         -- Read in GHC.Read, Show in GHC.Show
429
430 -- Boolean functions
431
432 -- | Boolean \"and\"
433 (&&)                    :: Bool -> Bool -> Bool
434 True  && x              =  x
435 False && _              =  False
436
437 -- | Boolean \"or\"
438 (||)                    :: Bool -> Bool -> Bool
439 True  || _              =  True
440 False || x              =  x
441
442 -- | Boolean \"not\"
443 not                     :: Bool -> Bool
444 not True                =  False
445 not False               =  True
446
447 -- |'otherwise' is defined as the value 'True'.  It helps to make
448 -- guards more readable.  eg.
449 --
450 -- >  f x | x < 0     = ...
451 -- >      | otherwise = ...
452 otherwise               :: Bool
453 otherwise               =  True
454 \end{code}
455
456
457 %*********************************************************
458 %*                                                      *
459 \subsection{The @()@ type}
460 %*                                                      *
461 %*********************************************************
462
463 The Unit type is here because virtually any program needs it (whereas
464 some programs may get away without consulting GHC.Tup).  Furthermore,
465 the renamer currently *always* asks for () to be in scope, so that
466 ccalls can use () as their default type; so when compiling GHC.Base we
467 need ().  (We could arrange suck in () only if -fglasgow-exts, but putting
468 it here seems more direct.)
469
470 \begin{code}
471 -- | The unit datatype @()@ has one non-undefined member, the nullary
472 -- constructor @()@.
473 data () = ()
474
475 instance Eq () where
476     () == () = True
477     () /= () = False
478
479 instance Ord () where
480     () <= () = True
481     () <  () = False
482     () >= () = True
483     () >  () = False
484     max () () = ()
485     min () () = ()
486     compare () () = EQ
487 \end{code}
488
489
490 %*********************************************************
491 %*                                                      *
492 \subsection{Type @Ordering@}
493 %*                                                      *
494 %*********************************************************
495
496 \begin{code}
497 -- | Represents an ordering relationship between two values: less
498 -- than, equal to, or greater than.  An 'Ordering' is returned by
499 -- 'compare'.
500 data Ordering = LT | EQ | GT deriving (Eq, Ord)
501         -- Read in GHC.Read, Show in GHC.Show
502 \end{code}
503
504
505 %*********************************************************
506 %*                                                      *
507 \subsection{Type @Char@ and @String@}
508 %*                                                      *
509 %*********************************************************
510
511 \begin{code}
512 -- | A 'String' is a list of characters.  String constants in Haskell are values
513 -- of type 'String'.
514 --
515 type String = [Char]
516
517 {-| The character type 'Char' is an enumeration whose values represent
518 Unicode (or equivalently ISO 10646) characters.
519 This set extends the ISO 8859-1 (Latin-1) character set
520 (the first 256 charachers), which is itself an extension of the ASCII
521 character set (the first 128 characters).
522 A character literal in Haskell has type 'Char'.
523
524 To convert a 'Char' to or from the corresponding 'Int' value defined
525 by Unicode, use 'Prelude.toEnum' and 'Prelude.fromEnum' from the
526 'Prelude.Enum' class respectively (or equivalently 'ord' and 'chr').
527 -}
528 data Char = C# Char#
529
530 -- We don't use deriving for Eq and Ord, because for Ord the derived
531 -- instance defines only compare, which takes two primops.  Then
532 -- '>' uses compare, and therefore takes two primops instead of one.
533
534 instance Eq Char where
535     (C# c1) == (C# c2) = c1 `eqChar#` c2
536     (C# c1) /= (C# c2) = c1 `neChar#` c2
537
538 instance Ord Char where
539     (C# c1) >  (C# c2) = c1 `gtChar#` c2
540     (C# c1) >= (C# c2) = c1 `geChar#` c2
541     (C# c1) <= (C# c2) = c1 `leChar#` c2
542     (C# c1) <  (C# c2) = c1 `ltChar#` c2
543
544 {-# RULES
545 "x# `eqChar#` x#" forall x#. x# `eqChar#` x# = True
546 "x# `neChar#` x#" forall x#. x# `neChar#` x# = False
547 "x# `gtChar#` x#" forall x#. x# `gtChar#` x# = False
548 "x# `geChar#` x#" forall x#. x# `geChar#` x# = True
549 "x# `leChar#` x#" forall x#. x# `leChar#` x# = True
550 "x# `ltChar#` x#" forall x#. x# `ltChar#` x# = False
551   #-}
552
553 -- | The 'Prelude.toEnum' method restricted to the type 'Data.Char.Char'.
554 chr :: Int -> Char
555 chr (I# i#) | int2Word# i# `leWord#` int2Word# 0x10FFFF# = C# (chr# i#)
556             | otherwise                                  = error "Prelude.chr: bad argument"
557
558 unsafeChr :: Int -> Char
559 unsafeChr (I# i#) = C# (chr# i#)
560
561 -- | The 'Prelude.fromEnum' method restricted to the type 'Data.Char.Char'.
562 ord :: Char -> Int
563 ord (C# c#) = I# (ord# c#)
564 \end{code}
565
566 String equality is used when desugaring pattern-matches against strings.
567
568 \begin{code}
569 eqString :: String -> String -> Bool
570 eqString []       []       = True
571 eqString (c1:cs1) (c2:cs2) = c1 == c2 && cs1 `eqString` cs2
572 eqString cs1      cs2      = False
573
574 {-# RULES "eqString" (==) = eqString #-}
575 \end{code}
576
577
578 %*********************************************************
579 %*                                                      *
580 \subsection{Type @Int@}
581 %*                                                      *
582 %*********************************************************
583
584 \begin{code}
585 data Int = I# Int#
586 -- ^A fixed-precision integer type with at least the range @[-2^29
587 -- .. 2^29-1]@.  The exact range for a given implementation can be
588 -- determined by using 'minBound' and 'maxBound' from the 'Bounded'
589 -- class.
590
591 zeroInt, oneInt, twoInt, maxInt, minInt :: Int
592 zeroInt = I# 0#
593 oneInt  = I# 1#
594 twoInt  = I# 2#
595
596 {- Seems clumsy. Should perhaps put minInt and MaxInt directly into MachDeps.h -}
597 #if WORD_SIZE_IN_BITS == 31
598 minInt  = I# (-0x40000000#)
599 maxInt  = I# 0x3FFFFFFF#
600 #elif WORD_SIZE_IN_BITS == 32
601 minInt  = I# (-0x80000000#)
602 maxInt  = I# 0x7FFFFFFF#
603 #else 
604 minInt  = I# (-0x8000000000000000#)
605 maxInt  = I# 0x7FFFFFFFFFFFFFFF#
606 #endif
607
608 instance Eq Int where
609     (==) = eqInt
610     (/=) = neInt
611
612 instance Ord Int where
613     compare = compareInt
614     (<)     = ltInt
615     (<=)    = leInt
616     (>=)    = geInt
617     (>)     = gtInt
618
619 compareInt :: Int -> Int -> Ordering
620 (I# x#) `compareInt` (I# y#) = compareInt# x# y#
621
622 compareInt# :: Int# -> Int# -> Ordering
623 compareInt# x# y#
624     | x# <#  y# = LT
625     | x# ==# y# = EQ
626     | otherwise = GT
627 \end{code}
628
629
630 %*********************************************************
631 %*                                                      *
632 \subsection{The function type}
633 %*                                                      *
634 %*********************************************************
635
636 \begin{code}
637 -- identity function
638 id                      :: a -> a
639 id x                    =  x
640
641 -- lazy function; this is just the same as id, but its unfolding
642 -- and strictness are over-ridden by the definition in MkId.lhs
643 -- That way, it does not get inlined, and the strictness analyser
644 -- sees it as lazy.  Then the worker/wrapper phase inlines it.
645 -- Result: happiness
646 lazy :: a -> a
647 lazy x = x
648
649 -- Assertion function. This simply ignores its boolean argument.
650 -- The compiler may rewrite it to (assertError line)
651 --      SLPJ: in 5.04 etc 'assert' is in GHC.Prim,
652 --      but from Template Haskell onwards it's simply
653 --      defined here in Base.lhs
654 assert :: Bool -> a -> a
655 assert pred r = r
656  
657 -- constant function
658 const                   :: a -> b -> a
659 const x _               =  x
660
661 -- function composition
662 {-# INLINE (.) #-}
663 (.)       :: (b -> c) -> (a -> b) -> a -> c
664 (.) f g x = f (g x)
665
666 -- flip f  takes its (first) two arguments in the reverse order of f.
667 flip                    :: (a -> b -> c) -> b -> a -> c
668 flip f x y              =  f y x
669
670 -- right-associating infix application operator (useful in continuation-
671 -- passing style)
672 {-# INLINE ($) #-}
673 ($)                     :: (a -> b) -> a -> b
674 f $ x                   =  f x
675
676 -- until p f  yields the result of applying f until p holds.
677 until                   :: (a -> Bool) -> (a -> a) -> a -> a
678 until p f x | p x       =  x
679             | otherwise =  until p f (f x)
680
681 -- asTypeOf is a type-restricted version of const.  It is usually used
682 -- as an infix operator, and its typing forces its first argument
683 -- (which is usually overloaded) to have the same type as the second.
684 asTypeOf                :: a -> a -> a
685 asTypeOf                =  const
686 \end{code}
687
688 %*********************************************************
689 %*                                                      *
690 \subsection{CCallable instances}
691 %*                                                      *
692 %*********************************************************
693
694 Defined here to avoid orphans
695
696 \begin{code}
697 instance CCallable Char
698 instance CReturnable Char
699
700 instance CCallable   Int
701 instance CReturnable Int
702
703 instance CReturnable () -- Why, exactly?
704 \end{code}
705
706
707 %*********************************************************
708 %*                                                      *
709 \subsection{Generics}
710 %*                                                      *
711 %*********************************************************
712
713 \begin{code}
714 data Unit = Unit
715 #ifndef __HADDOCK__
716 data (:+:) a b = Inl a | Inr b
717 data (:*:) a b = a :*: b
718 #endif
719 \end{code}
720
721 %*********************************************************
722 %*                                                      *
723 \subsection{@getTag@}
724 %*                                                      *
725 %*********************************************************
726
727 Returns the 'tag' of a constructor application; this function is used
728 by the deriving code for Eq, Ord and Enum.
729
730 The primitive dataToTag# requires an evaluated constructor application
731 as its argument, so we provide getTag as a wrapper that performs the
732 evaluation before calling dataToTag#.  We could have dataToTag#
733 evaluate its argument, but we prefer to do it this way because (a)
734 dataToTag# can be an inline primop if it doesn't need to do any
735 evaluation, and (b) we want to expose the evaluation to the
736 simplifier, because it might be possible to eliminate the evaluation
737 in the case when the argument is already known to be evaluated.
738
739 \begin{code}
740 {-# INLINE getTag #-}
741 getTag :: a -> Int#
742 getTag x = x `seq` dataToTag# x
743 \end{code}
744
745 %*********************************************************
746 %*                                                      *
747 \subsection{Numeric primops}
748 %*                                                      *
749 %*********************************************************
750
751 \begin{code}
752 divInt# :: Int# -> Int# -> Int#
753 x# `divInt#` y#
754         -- Be careful NOT to overflow if we do any additional arithmetic
755         -- on the arguments...  the following  previous version of this
756         -- code has problems with overflow:
757 --    | (x# ># 0#) && (y# <# 0#) = ((x# -# y#) -# 1#) `quotInt#` y#
758 --    | (x# <# 0#) && (y# ># 0#) = ((x# -# y#) +# 1#) `quotInt#` y#
759     | (x# ># 0#) && (y# <# 0#) = ((x# -# 1#) `quotInt#` y#) -# 1#
760     | (x# <# 0#) && (y# ># 0#) = ((x# +# 1#) `quotInt#` y#) -# 1#
761     | otherwise                = x# `quotInt#` y#
762
763 modInt# :: Int# -> Int# -> Int#
764 x# `modInt#` y#
765     | (x# ># 0#) && (y# <# 0#) ||
766       (x# <# 0#) && (y# ># 0#)    = if r# /=# 0# then r# +# y# else 0#
767     | otherwise                   = r#
768     where
769     r# = x# `remInt#` y#
770 \end{code}
771
772 Definitions of the boxed PrimOps; these will be
773 used in the case of partial applications, etc.
774
775 \begin{code}
776 {-# INLINE eqInt #-}
777 {-# INLINE neInt #-}
778 {-# INLINE gtInt #-}
779 {-# INLINE geInt #-}
780 {-# INLINE ltInt #-}
781 {-# INLINE leInt #-}
782 {-# INLINE plusInt #-}
783 {-# INLINE minusInt #-}
784 {-# INLINE timesInt #-}
785 {-# INLINE quotInt #-}
786 {-# INLINE remInt #-}
787 {-# INLINE negateInt #-}
788
789 plusInt, minusInt, timesInt, quotInt, remInt, divInt, modInt, gcdInt :: Int -> Int -> Int
790 (I# x) `plusInt`  (I# y) = I# (x +# y)
791 (I# x) `minusInt` (I# y) = I# (x -# y)
792 (I# x) `timesInt` (I# y) = I# (x *# y)
793 (I# x) `quotInt`  (I# y) = I# (x `quotInt#` y)
794 (I# x) `remInt`   (I# y) = I# (x `remInt#`  y)
795 (I# x) `divInt`   (I# y) = I# (x `divInt#`  y)
796 (I# x) `modInt`   (I# y) = I# (x `modInt#`  y)
797
798 {-# RULES
799 "x# +# 0#" forall x#. x# +# 0# = x#
800 "0# +# x#" forall x#. 0# +# x# = x#
801 "x# -# 0#" forall x#. x# -# 0# = x#
802 "x# -# x#" forall x#. x# -# x# = 0#
803 "x# *# 0#" forall x#. x# *# 0# = 0#
804 "0# *# x#" forall x#. 0# *# x# = 0#
805 "x# *# 1#" forall x#. x# *# 1# = x#
806 "1# *# x#" forall x#. 1# *# x# = x#
807   #-}
808
809 gcdInt (I# a) (I# b) = g a b
810    where g 0# 0# = error "GHC.Base.gcdInt: gcd 0 0 is undefined"
811          g 0# _  = I# absB
812          g _  0# = I# absA
813          g _  _  = I# (gcdInt# absA absB)
814
815          absInt x = if x <# 0# then negateInt# x else x
816
817          absA     = absInt a
818          absB     = absInt b
819
820 negateInt :: Int -> Int
821 negateInt (I# x) = I# (negateInt# x)
822
823 gtInt, geInt, eqInt, neInt, ltInt, leInt :: Int -> Int -> Bool
824 (I# x) `gtInt` (I# y) = x >#  y
825 (I# x) `geInt` (I# y) = x >=# y
826 (I# x) `eqInt` (I# y) = x ==# y
827 (I# x) `neInt` (I# y) = x /=# y
828 (I# x) `ltInt` (I# y) = x <#  y
829 (I# x) `leInt` (I# y) = x <=# y
830
831 {-# RULES
832 "x# ># x#"  forall x#. x# >#  x# = False
833 "x# >=# x#" forall x#. x# >=# x# = True
834 "x# ==# x#" forall x#. x# ==# x# = True
835 "x# /=# x#" forall x#. x# /=# x# = False
836 "x# <# x#"  forall x#. x# <#  x# = False
837 "x# <=# x#" forall x#. x# <=# x# = True
838   #-}
839
840 {-# RULES
841 "plusFloat x 0.0"   forall x#. plusFloat#  x#   0.0# = x#
842 "plusFloat 0.0 x"   forall x#. plusFloat#  0.0# x#   = x#
843 "minusFloat x 0.0"  forall x#. minusFloat# x#   0.0# = x#
844 "minusFloat x x"    forall x#. minusFloat# x#   x#   = 0.0#
845 "timesFloat x 0.0"  forall x#. timesFloat# x#   0.0# = 0.0#
846 "timesFloat0.0 x"   forall x#. timesFloat# 0.0# x#   = 0.0#
847 "timesFloat x 1.0"  forall x#. timesFloat# x#   1.0# = x#
848 "timesFloat 1.0 x"  forall x#. timesFloat# 1.0# x#   = x#
849 "divideFloat x 1.0" forall x#. divideFloat# x#  1.0# = x#
850   #-}
851
852 {-# RULES
853 "plusDouble x 0.0"   forall x#. (+##) x#    0.0## = x#
854 "plusDouble 0.0 x"   forall x#. (+##) 0.0## x#    = x#
855 "minusDouble x 0.0"  forall x#. (-##) x#    0.0## = x#
856 "minusDouble x x"    forall x#. (-##) x#    x#    = 0.0##
857 "timesDouble x 0.0"  forall x#. (*##) x#    0.0## = 0.0##
858 "timesDouble 0.0 x"  forall x#. (*##) 0.0## x#    = 0.0##
859 "timesDouble x 1.0"  forall x#. (*##) x#    1.0## = x#
860 "timesDouble 1.0 x"  forall x#. (*##) 1.0## x#    = x#
861 "divideDouble x 1.0" forall x#. (/##) x#    1.0## = x#
862   #-}
863
864 -- Wrappers for the shift operations.  The uncheckedShift# family are
865 -- undefined when the amount being shifted by is greater than the size
866 -- in bits of Int#, so these wrappers perform a check and return
867 -- either zero or -1 appropriately.
868 --
869 -- Note that these wrappers still produce undefined results when the
870 -- second argument (the shift amount) is negative.
871
872 shiftL#, shiftRL# :: Word# -> Int# -> Word#
873
874 a `shiftL#` b   | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
875                 | otherwise                = a `uncheckedShiftL#` b
876
877 a `shiftRL#` b  | b >=# WORD_SIZE_IN_BITS# = int2Word# 0#
878                 | otherwise                = a `uncheckedShiftRL#` b
879
880 iShiftL#, iShiftRA#, iShiftRL# :: Int# -> Int# -> Int#
881
882 a `iShiftL#` b  | b >=# WORD_SIZE_IN_BITS# = 0#
883                 | otherwise                = a `uncheckedIShiftL#` b
884
885 a `iShiftRA#` b | b >=# WORD_SIZE_IN_BITS# = if a <# 0# then (-1#) else 0#
886                 | otherwise                = a `uncheckedIShiftRA#` b
887
888 a `iShiftRL#` b | b >=# WORD_SIZE_IN_BITS# = 0#
889                 | otherwise                = a `uncheckedIShiftRL#` b
890
891 #if WORD_SIZE_IN_BITS == 32
892 {-# RULES
893 "narrow32Int#"  forall x#. narrow32Int#   x# = x#
894 "narrow32Word#" forall x#. narrow32Word#   x# = x#
895    #-}
896 #endif
897
898 {-# RULES
899 "int2Word2Int"  forall x#. int2Word# (word2Int# x#) = x#
900 "word2Int2Word" forall x#. word2Int# (int2Word# x#) = x#
901   #-}
902 \end{code}
903
904
905 %********************************************************
906 %*                                                      *
907 \subsection{Unpacking C strings}
908 %*                                                      *
909 %********************************************************
910
911 This code is needed for virtually all programs, since it's used for
912 unpacking the strings of error messages.
913
914 \begin{code}
915 unpackCString# :: Addr# -> [Char]
916 {-# NOINLINE [1] unpackCString# #-}
917 unpackCString# addr 
918   = unpack 0#
919   where
920     unpack nh
921       | ch `eqChar#` '\0'# = []
922       | otherwise          = C# ch : unpack (nh +# 1#)
923       where
924         ch = indexCharOffAddr# addr nh
925
926 unpackAppendCString# :: Addr# -> [Char] -> [Char]
927 unpackAppendCString# addr rest
928   = unpack 0#
929   where
930     unpack nh
931       | ch `eqChar#` '\0'# = rest
932       | otherwise          = C# ch : unpack (nh +# 1#)
933       where
934         ch = indexCharOffAddr# addr nh
935
936 unpackFoldrCString# :: Addr# -> (Char  -> a -> a) -> a -> a 
937 {-# NOINLINE [0] unpackFoldrCString# #-}
938 -- Don't inline till right at the end;
939 -- usually the unpack-list rule turns it into unpackCStringList
940 unpackFoldrCString# addr f z 
941   = unpack 0#
942   where
943     unpack nh
944       | ch `eqChar#` '\0'# = z
945       | otherwise          = C# ch `f` unpack (nh +# 1#)
946       where
947         ch = indexCharOffAddr# addr nh
948
949 unpackCStringUtf8# :: Addr# -> [Char]
950 unpackCStringUtf8# addr 
951   = unpack 0#
952   where
953     unpack nh
954       | ch `eqChar#` '\0'#   = []
955       | ch `leChar#` '\x7F'# = C# ch : unpack (nh +# 1#)
956       | ch `leChar#` '\xDF'# =
957           C# (chr# (((ord# ch                                  -# 0xC0#) `uncheckedIShiftL#`  6#) +#
958                      (ord# (indexCharOffAddr# addr (nh +# 1#)) -# 0x80#))) :
959           unpack (nh +# 2#)
960       | ch `leChar#` '\xEF'# =
961           C# (chr# (((ord# ch                                  -# 0xE0#) `uncheckedIShiftL#` 12#) +#
962                     ((ord# (indexCharOffAddr# addr (nh +# 1#)) -# 0x80#) `uncheckedIShiftL#`  6#) +#
963                      (ord# (indexCharOffAddr# addr (nh +# 2#)) -# 0x80#))) :
964           unpack (nh +# 3#)
965       | otherwise            =
966           C# (chr# (((ord# ch                                  -# 0xF0#) `uncheckedIShiftL#` 18#) +#
967                     ((ord# (indexCharOffAddr# addr (nh +# 1#)) -# 0x80#) `uncheckedIShiftL#` 12#) +#
968                     ((ord# (indexCharOffAddr# addr (nh +# 2#)) -# 0x80#) `uncheckedIShiftL#`  6#) +#
969                      (ord# (indexCharOffAddr# addr (nh +# 3#)) -# 0x80#))) :
970           unpack (nh +# 4#)
971       where
972         ch = indexCharOffAddr# addr nh
973
974 unpackNBytes# :: Addr# -> Int# -> [Char]
975 unpackNBytes# _addr 0#   = []
976 unpackNBytes#  addr len# = unpack [] (len# -# 1#)
977     where
978      unpack acc i#
979       | i# <# 0#  = acc
980       | otherwise = 
981          case indexCharOffAddr# addr i# of
982             ch -> unpack (C# ch : acc) (i# -# 1#)
983
984 {-# RULES
985 "unpack"       [~1] forall a   . unpackCString# a                  = build (unpackFoldrCString# a)
986 "unpack-list"  [1]  forall a   . unpackFoldrCString# a (:) [] = unpackCString# a
987 "unpack-append"     forall a n . unpackFoldrCString# a (:) n  = unpackAppendCString# a n
988
989 -- There's a built-in rule (in PrelRules.lhs) for
990 --      unpackFoldr "foo" c (unpackFoldr "baz" c n)  =  unpackFoldr "foobaz" c n
991
992   #-}
993 \end{code}
994
995 #ifdef __HADDOCK__
996 \begin{code}
997 -- | A placeholder argument for the 'Control.Monad.ST.ST' type constructor,
998 -- to mark a state embedded in the 'Prelude.IO' monad by
999 -- 'Control.Monad.ST.stToIO'.
1000 data RealWorld
1001 \end{code}
1002 #endif