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 special argument for the 'Control.Monad.ST.ST' type constructor,
 998 -- indexing a state embedded in the 'Prelude.IO' monad by
 999 -- 'Control.Monad.ST.stToIO'.
1000 data RealWorld
1001 \end{code}
1002 #endif