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