Add explicit `{-# LANGUAGE CPP, PackageImports #-}` pragmas
[packages/haskell2010.git] / Prelude.hs
1 {-# LANGUAGE BangPatterns, CPP, NoImplicitPrelude, PackageImports #-}
2 #if __GLASGOW_HASKELL__ >= 701
3 {-# LANGUAGE Trustworthy #-}
4 #endif
5
6 -- |
7 -- The Haskell 2010 Prelude: a standard module imported by default
8 -- into all Haskell modules. For more documentation, see the Haskell 2010
9 -- Report <http://www.haskell.org/onlinereport/>.
10 module Prelude (
11
12 -- * Standard types, classes and related functions
13
14 -- ** Basic data types
15 Bool(False, True),
16 (&&), (||), not, otherwise,
17
18 Maybe(Nothing, Just),
19 maybe,
20
21 Either(Left, Right),
22 either,
23
24 Ordering(LT, EQ, GT),
25 Char, String,
26
27 -- *** Tuples
28 fst, snd, curry, uncurry,
29
30 #ifdef __HUGS__
31 (:), -- Not legal Haskell 98
32 #endif
33
34 -- ** Basic type classes
35 Eq((==), (/=)),
36 Ord(compare, (<), (<=), (>=), (>), max, min),
37 Enum(succ, pred, toEnum, fromEnum, enumFrom, enumFromThen,
38 enumFromTo, enumFromThenTo),
39 Bounded(minBound, maxBound),
40
41 -- ** Numbers
42
43 -- *** Numeric types
44 Int, Integer, Float, Double,
45 Rational,
46
47 -- *** Numeric type classes
48 Num((+), (-), (*), negate, abs, signum, fromInteger),
49 Real(toRational),
50 Integral(quot, rem, div, mod, quotRem, divMod, toInteger),
51 Fractional((/), recip, fromRational),
52 Floating(pi, exp, log, sqrt, (**), logBase, sin, cos, tan,
53 asin, acos, atan, sinh, cosh, tanh, asinh, acosh, atanh),
54 RealFrac(properFraction, truncate, round, ceiling, floor),
55 RealFloat(floatRadix, floatDigits, floatRange, decodeFloat,
56 encodeFloat, exponent, significand, scaleFloat, isNaN,
57 isInfinite, isDenormalized, isIEEE, isNegativeZero, atan2),
58
59 -- *** Numeric functions
60 subtract, even, odd, gcd, lcm, (^), (^^),
61 fromIntegral, realToFrac,
62
63 -- ** Monads and functors
64 Monad((>>=), (>>), return, fail),
65 Functor(fmap),
66 mapM, mapM_, sequence, sequence_, (=<<),
67
68 -- ** Miscellaneous functions
69 id, const, (.), flip, ($), until,
70 asTypeOf, error, undefined,
71 seq, ($!),
72
73 -- * List operations
74 map, (++), filter,
75 head, last, tail, init, null, length, (!!),
76 reverse,
77 -- ** Reducing lists (folds)
78 foldl, foldl1, foldr, foldr1,
79 -- *** Special folds
80 and, or, any, all,
81 sum, product,
82 concat, concatMap,
83 maximum, minimum,
84 -- ** Building lists
85 -- *** Scans
86 scanl, scanl1, scanr, scanr1,
87 -- *** Infinite lists
88 iterate, repeat, replicate, cycle,
89 -- ** Sublists
90 take, drop, splitAt, takeWhile, dropWhile, span, break,
91 -- ** Searching lists
92 elem, notElem, lookup,
93 -- ** Zipping and unzipping lists
94 zip, zip3, zipWith, zipWith3, unzip, unzip3,
95 -- ** Functions on strings
96 lines, words, unlines, unwords,
97
98 -- * Converting to and from @String@
99 -- ** Converting to @String@
100 ShowS,
101 Show(showsPrec, showList, show),
102 shows,
103 showChar, showString, showParen,
104 -- ** Converting from @String@
105 ReadS,
106 Read(readsPrec, readList),
107 reads, readParen, read, lex,
108
109 -- * Basic Input and output
110 IO,
111 -- ** Simple I\/O operations
112 -- All I/O functions defined here are character oriented. The
113 -- treatment of the newline character will vary on different systems.
114 -- For example, two characters of input, return and linefeed, may
115 -- read as a single newline character. These functions cannot be
116 -- used portably for binary I/O.
117 -- *** Output functions
118 putChar,
119 putStr, putStrLn, print,
120 -- *** Input functions
121 getChar,
122 getLine, getContents, interact,
123 -- *** Files
124 FilePath,
125 readFile, writeFile, appendFile, readIO, readLn,
126 -- ** Exception handling in the I\/O monad
127 IOError, ioError, userError, catch
128
129 ) where
130
131 #ifndef __HUGS__
132 import qualified "base" Control.Exception.Base as New (catch)
133 import "base" Control.Monad
134 import "base" System.IO
135 import "base" System.IO.Error (IOError, ioError, userError)
136 import "base" Data.List hiding ( splitAt )
137 import "base" Data.Either
138 import "base" Data.Maybe
139 import "base" Data.Tuple
140 #endif
141
142 #ifdef __GLASGOW_HASKELL__
143 import GHC.Base
144 -- import GHC.IO
145 -- import GHC.IO.Exception
146 import Text.Read
147 import GHC.Enum
148 import GHC.Num
149 import GHC.Real hiding ( gcd )
150 import qualified GHC.Real ( gcd )
151 import GHC.Float
152 import GHC.Show
153 #endif
154
155 #ifdef __HUGS__
156 import Hugs.Prelude
157 #endif
158
159 #ifndef __HUGS__
160 infixr 0 $!
161 #endif
162
163 -- -----------------------------------------------------------------------------
164 -- Miscellaneous functions
165
166 -- | Strict (call-by-value) application, defined in terms of 'seq'.
167 ($!) :: (a -> b) -> a -> b
168 #ifdef __GLASGOW_HASKELL__
169 f $! x = let !vx = x in f vx -- see #2273
170 #elif !defined(__HUGS__)
171 f $! x = x `seq` f x
172 #endif
173
174 #ifdef __HADDOCK__
175 -- | The value of @'seq' a b@ is bottom if @a@ is bottom, and otherwise
176 -- equal to @b@. 'seq' is usually introduced to improve performance by
177 -- avoiding unneeded laziness.
178 seq :: a -> b -> b
179 seq _ y = y
180 #endif
181
182 -- | The 'catch' function establishes a handler that receives any
183 -- 'IOError' raised in the action protected by 'catch'.
184 -- An 'IOError' is caught by
185 -- the most recent handler established by one of the exception handling
186 -- functions. These handlers are
187 -- not selective: all 'IOError's are caught. Exception propagation
188 -- must be explicitly provided in a handler by re-raising any unwanted
189 -- exceptions. For example, in
190 --
191 -- > f = catch g (\e -> if IO.isEOFError e then return [] else ioError e)
192 --
193 -- the function @f@ returns @[]@ when an end-of-file exception
194 -- (cf. 'System.IO.Error.isEOFError') occurs in @g@; otherwise, the
195 -- exception is propagated to the next outer handler.
196 --
197 -- When an exception propagates outside the main program, the Haskell
198 -- system prints the associated 'IOError' value and exits the program.
199 --
200 -- Non-I\/O exceptions are not caught by this variant; to catch all
201 -- exceptions, use 'Control.Exception.catch' from "Control.Exception".
202 catch :: IO a -> (IOError -> IO a) -> IO a
203 catch = New.catch
204
205 #ifdef __GLASGOW_HASKELL__
206 -- | @'gcd' x y@ is the greatest (positive) integer that divides both @x@
207 -- and @y@; for example @'gcd' (-3) 6@ = @3@, @'gcd' (-3) (-6)@ = @3@,
208 -- @'gcd' 0 4@ = @4@. @'gcd' 0 0@ raises a runtime error.
209 gcd :: (Integral a) => a -> a -> a
210 gcd 0 0 = error "Prelude.gcd: gcd 0 0 is undefined"
211 gcd x y = GHC.Real.gcd x y
212 #endif
213
214 #ifndef __HUGS__
215 -- The GHC's version of 'splitAt' is too strict in 'n' compared to
216 -- Haskell98/2010 version. Ticket #1182.
217
218 -- | 'splitAt' @n xs@ returns a tuple where first element is @xs@ prefix of
219 -- length @n@ and second element is the remainder of the list:
220 --
221 -- > splitAt 6 "Hello World!" == ("Hello ","World!")
222 -- > splitAt 3 [1,2,3,4,5] == ([1,2,3],[4,5])
223 -- > splitAt 1 [1,2,3] == ([1],[2,3])
224 -- > splitAt 3 [1,2,3] == ([1,2,3],[])
225 -- > splitAt 4 [1,2,3] == ([1,2,3],[])
226 -- > splitAt 0 [1,2,3] == ([],[1,2,3])
227 -- > splitAt (-1) [1,2,3] == ([],[1,2,3])
228 --
229 -- It is equivalent to @('take' n xs, 'drop' n xs)@.
230 -- 'splitAt' is an instance of the more general 'Data.List.genericSplitAt',
231 -- in which @n@ may be of any integral type.
232 splitAt :: Int -> [a] -> ([a],[a])
233 splitAt n xs = (take n xs, drop n xs)
234 #endif