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