6a089ee432dccd46b36c3359be4e5fe0fc82e61b
[ghc.git] / libraries / base / 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 GHC.Base        Classes: Eq, Ord, Functor, Monad
20                 Types:   list, (), Int, Bool, Ordering, Char, String
21
22 Data.Tuple      Types: tuples, plus instances for GHC.Base classes
23
24 GHC.Show        Class: Show, plus instances for GHC.Base/GHC.Tup types
25
26 GHC.Enum        Class: Enum,  plus instances for GHC.Base/GHC.Tup types
27
28 Data.Maybe      Type: Maybe, plus instances for GHC.Base classes
29
30 GHC.List        List functions
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 GHC.ST  The ST monad, instances and a few helper functions
47
48 Ix              Classes: Ix, plus instances for Int, Bool, Char, Integer, Ordering, tuples
49
50 GHC.Arr         Types: Array, MutableArray, MutableVar
51
52                 Arrays are used by a function in GHC.Float
53
54 GHC.Float       Classes: Floating, RealFloat
55                 Types:   Float, Double, plus instances of all classes so far
56
57                 This module contains everything to do with floating point.
58                 It is a big module (900 lines)
59                 With a bit of luck, many modules can be compiled without ever reading GHC.Float.hi
60
61
62 Other Prelude modules are much easier with fewer complex dependencies.
63
64 \begin{code}
65 {-# LANGUAGE Unsafe #-}
66 {-# LANGUAGE CPP
67            , NoImplicitPrelude
68            , BangPatterns
69            , ExplicitForAll
70            , MagicHash
71            , UnboxedTuples
72            , ExistentialQuantification
73            , RankNTypes
74   #-}
75 -- -fno-warn-orphans is needed for things like:
76 -- Orphan rule: "x# -# x#" ALWAYS forall x# :: Int# -# x# x# = 0
77 {-# OPTIONS_GHC -fno-warn-orphans #-}
78 {-# OPTIONS_HADDOCK hide #-}
79
80 -----------------------------------------------------------------------------
81 -- |
82 -- Module      :  GHC.Base
83 -- Copyright   :  (c) The University of Glasgow, 1992-2002
84 -- License     :  see libraries/base/LICENSE
85 --
86 -- Maintainer  :  cvs-ghc@haskell.org
87 -- Stability   :  internal
88 -- Portability :  non-portable (GHC extensions)
89 --
90 -- Basic data types and classes.
91 --
92 -----------------------------------------------------------------------------
93
94 #include "MachDeps.h"
95
96 module GHC.Base
97         (
98         module GHC.Base,
99         module GHC.Classes,
100         module GHC.CString,
101         module GHC.Magic,
102         module GHC.Types,
103         module GHC.Prim,        -- Re-export GHC.Prim and [boot] GHC.Err,
104                                 -- to avoid lots of people having to
105         module GHC.Err          -- import it explicitly
106   )
107         where
108
109 import GHC.Types
110 import GHC.Classes
111 import GHC.CString
112 import GHC.Magic
113 import GHC.Prim
114 import GHC.Err
115 import {-# SOURCE #-} GHC.IO (failIO)
116
117 import GHC.Tuple ()     -- Note [Depend on GHC.Tuple]
118 import GHC.Integer ()   -- Note [Depend on GHC.Integer]
119
120 infixr 9  .
121 infixr 5  ++
122 infixl 4  <$
123 infixl 1  >>, >>=
124 infixr 0  $
125
126 default ()              -- Double isn't available yet
127 \end{code}
128
129 Note [Depend on GHC.Integer]
130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
131 The Integer type is special because TidyPgm uses
132 GHC.Integer.Type.mkInteger to construct Integer literal values
133 Currently it reads the interface file whether or not the current
134 module *has* any Integer literals, so it's important that
135 GHC.Integer.Type (in patckage integer-gmp or integer-simple) is
136 compiled before any other module.  (There's a hack in GHC to disable
137 this for packages ghc-prim, integer-gmp, integer-simple, which aren't
138 allowed to contain any Integer literals.)
139
140 Likewise we implicitly need Integer when deriving things like Eq
141 instances.
142
143 The danger is that if the build system doesn't know about the dependency
144 on Integer, it'll compile some base module before GHC.Integer.Type, 
145 resulting in:
146   Failed to load interface for ‘GHC.Integer.Type’
147     There are files missing in the ‘integer-gmp’ package,
148
149 Bottom line: we make GHC.Base depend on GHC.Integer; and everything
150 else either depends on GHC.Base, or does not have NoImplicitPrelude
151 (and hence depends on Prelude).
152
153 Note [Depend on GHC.Tuple]
154 ~~~~~~~~~~~~~~~~~~~~~~~~~~
155 Similarly, tuple syntax (or ()) creates an implicit dependency on
156 GHC.Tuple, so we use the same rule as for Integer --- see Note [Depend on
157 GHC.Integer] --- to explain this to the build system.  We make GHC.Base
158 depend on GHC.Tuple, and everything else depends on GHC.Base or Prelude.
159
160 %*********************************************************
161 %*                                                      *
162 \subsection{DEBUGGING STUFF}
163 %*  (for use when compiling GHC.Base itself doesn't work)
164 %*                                                      *
165 %*********************************************************
166
167 \begin{code}
168 {-
169 data  Bool  =  False | True
170 data Ordering = LT | EQ | GT
171 data Char = C# Char#
172 type  String = [Char]
173 data Int = I# Int#
174 data  ()  =  ()
175 data [] a = MkNil
176
177 not True = False
178 (&&) True True = True
179 otherwise = True
180
181 build = error "urk"
182 foldr = error "urk"
183 -}
184 \end{code}
185
186
187 %*********************************************************
188 %*                                                      *
189 \subsection{Monadic classes @Functor@, @Monad@ }
190 %*                                                      *
191 %*********************************************************
192
193 \begin{code}
194 {- | The 'Functor' class is used for types that can be mapped over.
195 Instances of 'Functor' should satisfy the following laws:
196
197 > fmap id  ==  id
198 > fmap (f . g)  ==  fmap f . fmap g
199
200 The instances of 'Functor' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
201 satisfy these laws.
202 -}
203
204 class  Functor f  where
205     fmap        :: (a -> b) -> f a -> f b
206
207     -- | Replace all locations in the input with the same value.
208     -- The default definition is @'fmap' . 'const'@, but this may be
209     -- overridden with a more efficient version.
210     (<$)        :: a -> f b -> f a
211     (<$)        =  fmap . const
212
213 {- | The 'Monad' class defines the basic operations over a /monad/,
214 a concept from a branch of mathematics known as /category theory/.
215 From the perspective of a Haskell programmer, however, it is best to
216 think of a monad as an /abstract datatype/ of actions.
217 Haskell's @do@ expressions provide a convenient syntax for writing
218 monadic expressions.
219
220 Minimal complete definition: '>>=' and 'return'.
221
222 Instances of 'Monad' should satisfy the following laws:
223
224 > return a >>= k  ==  k a
225 > m >>= return  ==  m
226 > m >>= (\x -> k x >>= h)  ==  (m >>= k) >>= h
227
228 Instances of both 'Monad' and 'Functor' should additionally satisfy the law:
229
230 > fmap f xs  ==  xs >>= return . f
231
232 The instances of 'Monad' for lists, 'Data.Maybe.Maybe' and 'System.IO.IO'
233 defined in the "Prelude" satisfy these laws.
234 -}
235
236 class  Monad m  where
237     -- | Sequentially compose two actions, passing any value produced
238     -- by the first as an argument to the second.
239     (>>=)       :: forall a b. m a -> (a -> m b) -> m b
240     -- | Sequentially compose two actions, discarding any value produced
241     -- by the first, like sequencing operators (such as the semicolon)
242     -- in imperative languages.
243     (>>)        :: forall a b. m a -> m b -> m b
244         -- Explicit for-alls so that we know what order to
245         -- give type arguments when desugaring
246
247     -- | Inject a value into the monadic type.
248     return      :: a -> m a
249     -- | Fail with a message.  This operation is not part of the
250     -- mathematical definition of a monad, but is invoked on pattern-match
251     -- failure in a @do@ expression.
252     fail        :: String -> m a
253
254     {-# INLINE (>>) #-}
255     m >> k      = m >>= \_ -> k
256     fail s      = error s
257
258 instance Functor ((->) r) where
259     fmap = (.)
260
261 instance Monad ((->) r) where
262     return = const
263     f >>= k = \ r -> k (f r) r
264
265 instance Functor ((,) a) where
266     fmap f (x,y) = (x, f y)
267 \end{code}
268
269
270 %*********************************************************
271 %*                                                      *
272 \subsection{The list type}
273 %*                                                      *
274 %*********************************************************
275
276 \begin{code}
277 instance Functor [] where
278     fmap = map
279
280 instance  Monad []  where
281     m >>= k             = foldr ((++) . k) [] m
282     m >> k              = foldr ((++) . (\ _ -> k)) [] m
283     return x            = [x]
284     fail _              = []
285 \end{code}
286
287 A few list functions that appear here because they are used here.
288 The rest of the prelude list functions are in GHC.List.
289
290 ----------------------------------------------
291 --      foldr/build/augment
292 ----------------------------------------------
293
294 \begin{code}
295 -- | 'foldr', applied to a binary operator, a starting value (typically
296 -- the right-identity of the operator), and a list, reduces the list
297 -- using the binary operator, from right to left:
298 --
299 -- > foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
300
301 foldr            :: (a -> b -> b) -> b -> [a] -> b
302 -- foldr _ z []     =  z
303 -- foldr f z (x:xs) =  f x (foldr f z xs)
304 {-# INLINE [0] foldr #-}
305 -- Inline only in the final stage, after the foldr/cons rule has had a chance
306 -- Also note that we inline it when it has *two* parameters, which are the
307 -- ones we are keen about specialising!
308 foldr k z = go
309           where
310             go []     = z
311             go (y:ys) = y `k` go ys
312
313 -- | A list producer that can be fused with 'foldr'.
314 -- This function is merely
315 --
316 -- >    build g = g (:) []
317 --
318 -- but GHC's simplifier will transform an expression of the form
319 -- @'foldr' k z ('build' g)@, which may arise after inlining, to @g k z@,
320 -- which avoids producing an intermediate list.
321
322 build   :: forall a. (forall b. (a -> b -> b) -> b -> b) -> [a]
323 {-# INLINE [1] build #-}
324         -- The INLINE is important, even though build is tiny,
325         -- because it prevents [] getting inlined in the version that
326         -- appears in the interface file.  If [] *is* inlined, it
327         -- won't match with [] appearing in rules in an importing module.
328         --
329         -- The "1" says to inline in phase 1
330
331 build g = g (:) []
332
333 -- | A list producer that can be fused with 'foldr'.
334 -- This function is merely
335 --
336 -- >    augment g xs = g (:) xs
337 --
338 -- but GHC's simplifier will transform an expression of the form
339 -- @'foldr' k z ('augment' g xs)@, which may arise after inlining, to
340 -- @g k ('foldr' k z xs)@, which avoids producing an intermediate list.
341
342 augment :: forall a. (forall b. (a->b->b) -> b -> b) -> [a] -> [a]
343 {-# INLINE [1] augment #-}
344 augment g xs = g (:) xs
345
346 {-# RULES
347 "fold/build"    forall k z (g::forall b. (a->b->b) -> b -> b) .
348                 foldr k z (build g) = g k z
349
350 "foldr/augment" forall k z xs (g::forall b. (a->b->b) -> b -> b) .
351                 foldr k z (augment g xs) = g k (foldr k z xs)
352
353 "foldr/id"                        foldr (:) [] = \x  -> x
354 "foldr/app"     [1] forall ys. foldr (:) ys = \xs -> xs ++ ys
355         -- Only activate this from phase 1, because that's
356         -- when we disable the rule that expands (++) into foldr
357
358 -- The foldr/cons rule looks nice, but it can give disastrously
359 -- bloated code when commpiling
360 --      array (a,b) [(1,2), (2,2), (3,2), ...very long list... ]
361 -- i.e. when there are very very long literal lists
362 -- So I've disabled it for now. We could have special cases
363 -- for short lists, I suppose.
364 -- "foldr/cons" forall k z x xs. foldr k z (x:xs) = k x (foldr k z xs)
365
366 "foldr/single"  forall k z x. foldr k z [x] = k x z
367 "foldr/nil"     forall k z.   foldr k z []  = z
368
369 "augment/build" forall (g::forall b. (a->b->b) -> b -> b)
370                        (h::forall b. (a->b->b) -> b -> b) .
371                        augment g (build h) = build (\c n -> g c (h c n))
372 "augment/nil"   forall (g::forall b. (a->b->b) -> b -> b) .
373                         augment g [] = build g
374  #-}
375
376 -- This rule is true, but not (I think) useful:
377 --      augment g (augment h t) = augment (\cn -> g c (h c n)) t
378 \end{code}
379
380
381 ----------------------------------------------
382 --              map
383 ----------------------------------------------
384
385 \begin{code}
386 -- | 'map' @f xs@ is the list obtained by applying @f@ to each element
387 -- of @xs@, i.e.,
388 --
389 -- > map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
390 -- > map f [x1, x2, ...] == [f x1, f x2, ...]
391
392 map :: (a -> b) -> [a] -> [b]
393 {-# NOINLINE [1] map #-}    -- We want the RULE to fire first.
394                             -- It's recursive, so won't inline anyway,
395                             -- but saying so is more explicit
396 map _ []     = []
397 map f (x:xs) = f x : map f xs
398
399 -- Note eta expanded
400 mapFB ::  (elt -> lst -> lst) -> (a -> elt) -> a -> lst -> lst
401 {-# INLINE [0] mapFB #-}
402 mapFB c f = \x ys -> c (f x) ys
403
404 -- The rules for map work like this.
405 --
406 -- Up to (but not including) phase 1, we use the "map" rule to
407 -- rewrite all saturated applications of map with its build/fold
408 -- form, hoping for fusion to happen.
409 -- In phase 1 and 0, we switch off that rule, inline build, and
410 -- switch on the "mapList" rule, which rewrites the foldr/mapFB
411 -- thing back into plain map.
412 --
413 -- It's important that these two rules aren't both active at once
414 -- (along with build's unfolding) else we'd get an infinite loop
415 -- in the rules.  Hence the activation control below.
416 --
417 -- The "mapFB" rule optimises compositions of map.
418 --
419 -- This same pattern is followed by many other functions:
420 -- e.g. append, filter, iterate, repeat, etc.
421
422 {-# RULES
423 "map"       [~1] forall f xs.   map f xs                = build (\c n -> foldr (mapFB c f) n xs)
424 "mapList"   [1]  forall f.      foldr (mapFB (:) f) []  = map f
425 "mapFB"     forall c f g.       mapFB (mapFB c f) g     = mapFB c (f.g)
426   #-}
427
428 -- There's also a rule for Map and Data.Coerce. See "Safe Coercions",
429 -- section 6.4:
430 --
431 --   http://research.microsoft.com/en-us/um/people/simonpj/papers/ext-f/coercible.pdf
432
433 {-# RULES "map/coerce" [1] map coerce = coerce #-}
434
435 \end{code}
436
437
438 ----------------------------------------------
439 --              append
440 ----------------------------------------------
441 \begin{code}
442 -- | Append two lists, i.e.,
443 --
444 -- > [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
445 -- > [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
446 --
447 -- If the first list is not finite, the result is the first list.
448
449 (++) :: [a] -> [a] -> [a]
450 {-# NOINLINE [1] (++) #-}    -- We want the RULE to fire first.
451                              -- It's recursive, so won't inline anyway,
452                              -- but saying so is more explicit
453 (++) []     ys = ys
454 (++) (x:xs) ys = x : xs ++ ys
455
456 {-# RULES
457 "++"    [~1] forall xs ys. xs ++ ys = augment (\c n -> foldr c n xs) ys
458   #-}
459
460 \end{code}
461
462
463 %*********************************************************
464 %*                                                      *
465 \subsection{Type @Bool@}
466 %*                                                      *
467 %*********************************************************
468
469 \begin{code}
470 -- |'otherwise' is defined as the value 'True'.  It helps to make
471 -- guards more readable.  eg.
472 --
473 -- >  f x | x < 0     = ...
474 -- >      | otherwise = ...
475 otherwise               :: Bool
476 otherwise               =  True
477 \end{code}
478
479 %*********************************************************
480 %*                                                      *
481 \subsection{Type @Char@ and @String@}
482 %*                                                      *
483 %*********************************************************
484
485 \begin{code}
486 -- | A 'String' is a list of characters.  String constants in Haskell are values
487 -- of type 'String'.
488 --
489 type String = [Char]
490
491 unsafeChr :: Int -> Char
492 unsafeChr (I# i#) = C# (chr# i#)
493
494 -- | The 'Prelude.fromEnum' method restricted to the type 'Data.Char.Char'.
495 ord :: Char -> Int
496 ord (C# c#) = I# (ord# c#)
497 \end{code}
498
499 String equality is used when desugaring pattern-matches against strings.
500
501 \begin{code}
502 eqString :: String -> String -> Bool
503 eqString []       []       = True
504 eqString (c1:cs1) (c2:cs2) = c1 == c2 && cs1 `eqString` cs2
505 eqString _        _        = False
506
507 {-# RULES "eqString" (==) = eqString #-}
508 -- eqString also has a BuiltInRule in PrelRules.lhs:
509 --      eqString (unpackCString# (Lit s1)) (unpackCString# (Lit s2) = s1==s2
510 \end{code}
511
512
513 %*********************************************************
514 %*                                                      *
515 \subsection{Type @Int@}
516 %*                                                      *
517 %*********************************************************
518
519 \begin{code}
520 maxInt, minInt :: Int
521
522 {- Seems clumsy. Should perhaps put minInt and MaxInt directly into MachDeps.h -}
523 #if WORD_SIZE_IN_BITS == 31
524 minInt  = I# (-0x40000000#)
525 maxInt  = I# 0x3FFFFFFF#
526 #elif WORD_SIZE_IN_BITS == 32
527 minInt  = I# (-0x80000000#)
528 maxInt  = I# 0x7FFFFFFF#
529 #else
530 minInt  = I# (-0x8000000000000000#)
531 maxInt  = I# 0x7FFFFFFFFFFFFFFF#
532 #endif
533 \end{code}
534
535
536 %*********************************************************
537 %*                                                      *
538 \subsection{The function type}
539 %*                                                      *
540 %*********************************************************
541
542 \begin{code}
543 -- | Identity function.
544 id                      :: a -> a
545 id x                    =  x
546
547 -- Assertion function.  This simply ignores its boolean argument.
548 -- The compiler may rewrite it to @('assertError' line)@.
549
550 -- | If the first argument evaluates to 'True', then the result is the
551 -- second argument.  Otherwise an 'AssertionFailed' exception is raised,
552 -- containing a 'String' with the source file and line number of the
553 -- call to 'assert'.
554 --
555 -- Assertions can normally be turned on or off with a compiler flag
556 -- (for GHC, assertions are normally on unless optimisation is turned on
557 -- with @-O@ or the @-fignore-asserts@
558 -- option is given).  When assertions are turned off, the first
559 -- argument to 'assert' is ignored, and the second argument is
560 -- returned as the result.
561
562 --      SLPJ: in 5.04 etc 'assert' is in GHC.Prim,
563 --      but from Template Haskell onwards it's simply
564 --      defined here in Base.lhs
565 assert :: Bool -> a -> a
566 assert _pred r = r
567
568 breakpoint :: a -> a
569 breakpoint r = r
570
571 breakpointCond :: Bool -> a -> a
572 breakpointCond _ r = r
573
574 data Opaque = forall a. O a
575
576 -- | Constant function.
577 const                   :: a -> b -> a
578 const x _               =  x
579
580 -- | Function composition.
581 {-# INLINE (.) #-}
582 -- Make sure it has TWO args only on the left, so that it inlines
583 -- when applied to two functions, even if there is no final argument
584 (.)    :: (b -> c) -> (a -> b) -> a -> c
585 (.) f g = \x -> f (g x)
586
587 -- | @'flip' f@ takes its (first) two arguments in the reverse order of @f@.
588 flip                    :: (a -> b -> c) -> b -> a -> c
589 flip f x y              =  f y x
590
591 -- | Application operator.  This operator is redundant, since ordinary
592 -- application @(f x)@ means the same as @(f '$' x)@. However, '$' has
593 -- low, right-associative binding precedence, so it sometimes allows
594 -- parentheses to be omitted; for example:
595 --
596 -- >     f $ g $ h x  =  f (g (h x))
597 --
598 -- It is also useful in higher-order situations, such as @'map' ('$' 0) xs@,
599 -- or @'Data.List.zipWith' ('$') fs xs@.
600 {-# INLINE ($) #-}
601 ($)                     :: (a -> b) -> a -> b
602 f $ x                   =  f x
603
604 -- | @'until' p f@ yields the result of applying @f@ until @p@ holds.
605 until                   :: (a -> Bool) -> (a -> a) -> a -> a
606 until p f = go
607   where
608     go x | p x          = x
609          | otherwise    = go (f x)
610
611 -- | 'asTypeOf' is a type-restricted version of 'const'.  It is usually
612 -- used as an infix operator, and its typing forces its first argument
613 -- (which is usually overloaded) to have the same type as the second.
614 asTypeOf                :: a -> a -> a
615 asTypeOf                =  const
616 \end{code}
617
618 %*********************************************************
619 %*                                                      *
620 \subsection{@Functor@ and @Monad@ instances for @IO@}
621 %*                                                      *
622 %*********************************************************
623
624 \begin{code}
625 instance  Functor IO where
626    fmap f x = x >>= (return . f)
627
628 instance  Monad IO  where
629     {-# INLINE return #-}
630     {-# INLINE (>>)   #-}
631     {-# INLINE (>>=)  #-}
632     m >> k    = m >>= \ _ -> k
633     return    = returnIO
634     (>>=)     = bindIO
635     fail s    = failIO s
636
637 returnIO :: a -> IO a
638 returnIO x = IO $ \ s -> (# s, x #)
639
640 bindIO :: IO a -> (a -> IO b) -> IO b
641 bindIO (IO m) k = IO $ \ s -> case m s of (# new_s, a #) -> unIO (k a) new_s
642
643 thenIO :: IO a -> IO b -> IO b
644 thenIO (IO m) k = IO $ \ s -> case m s of (# new_s, _ #) -> unIO k new_s
645
646 unIO :: IO a -> (State# RealWorld -> (# State# RealWorld, a #))
647 unIO (IO a) = a
648 \end{code}
649
650 %*********************************************************
651 %*                                                      *
652 \subsection{@getTag@}
653 %*                                                      *
654 %*********************************************************
655
656 Returns the 'tag' of a constructor application; this function is used
657 by the deriving code for Eq, Ord and Enum.
658
659 The primitive dataToTag# requires an evaluated constructor application
660 as its argument, so we provide getTag as a wrapper that performs the
661 evaluation before calling dataToTag#.  We could have dataToTag#
662 evaluate its argument, but we prefer to do it this way because (a)
663 dataToTag# can be an inline primop if it doesn't need to do any
664 evaluation, and (b) we want to expose the evaluation to the
665 simplifier, because it might be possible to eliminate the evaluation
666 in the case when the argument is already known to be evaluated.
667
668 \begin{code}
669 {-# INLINE getTag #-}
670 getTag :: a -> Int#
671 getTag x = x `seq` dataToTag# x
672 \end{code}
673
674 %*********************************************************
675 %*                                                      *
676 \subsection{Numeric primops}
677 %*                                                      *
678 %*********************************************************
679
680 Definitions of the boxed PrimOps; these will be
681 used in the case of partial applications, etc.
682
683 \begin{code}
684 {-# INLINE quotInt #-}
685 {-# INLINE remInt #-}
686
687 quotInt, remInt, divInt, modInt :: Int -> Int -> Int
688 (I# x) `quotInt`  (I# y) = I# (x `quotInt#` y)
689 (I# x) `remInt`   (I# y) = I# (x `remInt#`  y)
690 (I# x) `divInt`   (I# y) = I# (x `divInt#`  y)
691 (I# x) `modInt`   (I# y) = I# (x `modInt#`  y)
692
693 quotRemInt :: Int -> Int -> (Int, Int)
694 (I# x) `quotRemInt` (I# y) = case x `quotRemInt#` y of
695                              (# q, r #) ->
696                                  (I# q, I# r)
697
698 divModInt :: Int -> Int -> (Int, Int)
699 (I# x) `divModInt` (I# y) = case x `divModInt#` y of
700                             (# q, r #) -> (I# q, I# r)
701
702 divModInt# :: Int# -> Int# -> (# Int#, Int# #)
703 x# `divModInt#` y#
704  | isTrue# (x# ># 0#) && isTrue# (y# <# 0#) =
705                                     case (x# -# 1#) `quotRemInt#` y# of
706                                       (# q, r #) -> (# q -# 1#, r +# y# +# 1# #)
707  | isTrue# (x# <# 0#) && isTrue# (y# ># 0#) =
708                                     case (x# +# 1#) `quotRemInt#` y# of
709                                       (# q, r #) -> (# q -# 1#, r +# y# -# 1# #)
710  | otherwise                                =
711                                     x# `quotRemInt#` y#
712
713 -- Wrappers for the shift operations.  The uncheckedShift# family are
714 -- undefined when the amount being shifted by is greater than the size
715 -- in bits of Int#, so these wrappers perform a check and return
716 -- either zero or -1 appropriately.
717 --
718 -- Note that these wrappers still produce undefined results when the
719 -- second argument (the shift amount) is negative.
720
721 -- | Shift the argument left by the specified number of bits
722 -- (which must be non-negative).
723 shiftL# :: Word# -> Int# -> Word#
724 a `shiftL#` b   | isTrue# (b >=# WORD_SIZE_IN_BITS#) = 0##
725                 | otherwise                          = a `uncheckedShiftL#` b
726
727 -- | Shift the argument right by the specified number of bits
728 -- (which must be non-negative).
729 -- The "RL" means "right, logical" (as opposed to RA for arithmetic)
730 -- (although an arithmetic right shift wouldn't make sense for Word#)
731 shiftRL# :: Word# -> Int# -> Word#
732 a `shiftRL#` b  | isTrue# (b >=# WORD_SIZE_IN_BITS#) = 0##
733                 | otherwise                          = a `uncheckedShiftRL#` b
734
735 -- | Shift the argument left by the specified number of bits
736 -- (which must be non-negative).
737 iShiftL# :: Int# -> Int# -> Int#
738 a `iShiftL#` b  | isTrue# (b >=# WORD_SIZE_IN_BITS#) = 0#
739                 | otherwise                          = a `uncheckedIShiftL#` b
740
741 -- | Shift the argument right (signed) by the specified number of bits
742 -- (which must be non-negative).
743 -- The "RA" means "right, arithmetic" (as opposed to RL for logical)
744 iShiftRA# :: Int# -> Int# -> Int#
745 a `iShiftRA#` b | isTrue# (b >=# WORD_SIZE_IN_BITS#) = if isTrue# (a <# 0#)
746                                                           then (-1#)
747                                                           else 0#
748                 | otherwise                          = a `uncheckedIShiftRA#` b
749
750 -- | Shift the argument right (unsigned) by the specified number of bits
751 -- (which must be non-negative).
752 -- The "RL" means "right, logical" (as opposed to RA for arithmetic)
753 iShiftRL# :: Int# -> Int# -> Int#
754 a `iShiftRL#` b | isTrue# (b >=# WORD_SIZE_IN_BITS#) = 0#
755                 | otherwise                          = a `uncheckedIShiftRL#` b
756
757 -- Rules for C strings (the functions themselves are now in GHC.CString)
758 {-# RULES
759 "unpack"       [~1] forall a   . unpackCString# a             = build (unpackFoldrCString# a)
760 "unpack-list"  [1]  forall a   . unpackFoldrCString# a (:) [] = unpackCString# a
761 "unpack-append"     forall a n . unpackFoldrCString# a (:) n  = unpackAppendCString# a n
762
763 -- There's a built-in rule (in PrelRules.lhs) for
764 --      unpackFoldr "foo" c (unpackFoldr "baz" c n)  =  unpackFoldr "foobaz" c n
765
766   #-}
767 \end{code}
768
769
770 #ifdef __HADDOCK__
771 \begin{code}
772 -- | A special argument for the 'Control.Monad.ST.ST' type constructor,
773 -- indexing a state embedded in the 'Prelude.IO' monad by
774 -- 'Control.Monad.ST.stToIO'.
775 data RealWorld
776 \end{code}
777 #endif