-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Compatibility with Haskell 2010 -- -- This package provides exactly the library modules defined by the -- Haskell 2010 standard. @package haskell2010 @version 1.1.0.1 -- | The Haskell 2010 Prelude: a standard module imported by default into -- all Haskell modules. For more documentation, see the Haskell 2010 -- Report <a>http://www.haskell.org/onlinereport/</a>. module Prelude data Bool :: * False :: Bool True :: Bool -- | Boolean "and" (&&) :: Bool -> Bool -> Bool -- | Boolean "or" (||) :: Bool -> Bool -> Bool -- | Boolean "not" not :: Bool -> Bool -- | <a>otherwise</a> is defined as the value <a>True</a>. It helps to make -- guards more readable. eg. -- -- <pre> -- f x | x < 0 = ... -- | otherwise = ... -- </pre> otherwise :: Bool -- | The <a>Maybe</a> type encapsulates an optional value. A value of type -- <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt> -- (represented as <tt><a>Just</a> a</tt>), or it is empty (represented -- as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with -- errors or exceptional cases without resorting to drastic measures such -- as <a>error</a>. -- -- The <a>Maybe</a> type is also a monad. It is a simple kind of error -- monad, where all errors are represented by <a>Nothing</a>. A richer -- error monad can be built using the <a>Either</a> type. data Maybe a :: * -> * Nothing :: Maybe a Just :: a -> Maybe a -- | The <a>maybe</a> function takes a default value, a function, and a -- <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the -- function returns the default value. Otherwise, it applies the function -- to the value inside the <a>Just</a> and returns the result. maybe :: b -> (a -> b) -> Maybe a -> b -- | The <a>Either</a> type represents values with two possibilities: a -- value of type <tt><a>Either</a> a b</tt> is either <tt><a>Left</a> -- a</tt> or <tt><a>Right</a> b</tt>. -- -- The <a>Either</a> type is sometimes used to represent a value which is -- either correct or an error; by convention, the <a>Left</a> constructor -- is used to hold an error value and the <a>Right</a> constructor is -- used to hold a correct value (mnemonic: "right" also means "correct"). data Either a b :: * -> * -> * Left :: a -> Either a b Right :: b -> Either a b -- | Case analysis for the <a>Either</a> type. If the value is -- <tt><a>Left</a> a</tt>, apply the first function to <tt>a</tt>; if it -- is <tt><a>Right</a> b</tt>, apply the second function to <tt>b</tt>. either :: (a -> c) -> (b -> c) -> Either a b -> c data Ordering :: * LT :: Ordering EQ :: Ordering GT :: Ordering -- | The character type <a>Char</a> is an enumeration whose values -- represent Unicode (or equivalently ISO/IEC 10646) characters (see -- <a>http://www.unicode.org/</a> for details). This set extends the ISO -- 8859-1 (Latin-1) character set (the first 256 characters), which is -- itself an extension of the ASCII character set (the first 128 -- characters). A character literal in Haskell has type <a>Char</a>. -- -- To convert a <a>Char</a> to or from the corresponding <a>Int</a> value -- defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the -- <a>Enum</a> class respectively (or equivalently <tt>ord</tt> and -- <tt>chr</tt>). data Char :: * -- | A <a>String</a> is a list of characters. String constants in Haskell -- are values of type <a>String</a>. type String = [Char] -- | Extract the first component of a pair. fst :: (a, b) -> a -- | Extract the second component of a pair. snd :: (a, b) -> b -- | <a>curry</a> converts an uncurried function to a curried function. curry :: ((a, b) -> c) -> a -> b -> c -- | <a>uncurry</a> converts a curried function to a function on pairs. uncurry :: (a -> b -> c) -> (a, b) -> c -- | The <a>Eq</a> class defines equality (<a>==</a>) and inequality -- (<a>/=</a>). All the basic datatypes exported by the <a>Prelude</a> -- are instances of <a>Eq</a>, and <a>Eq</a> may be derived for any -- datatype whose constituents are also instances of <a>Eq</a>. -- -- Minimal complete definition: either <a>==</a> or <a>/=</a>. class Eq a (==) :: Eq a => a -> a -> Bool (/=) :: Eq a => a -> a -> Bool -- | The <a>Ord</a> class is used for totally ordered datatypes. -- -- Instances of <a>Ord</a> can be derived for any user-defined datatype -- whose constituent types are in <a>Ord</a>. The declared order of the -- constructors in the data declaration determines the ordering in -- derived <a>Ord</a> instances. The <a>Ordering</a> datatype allows a -- single comparison to determine the precise ordering of two objects. -- -- Minimal complete definition: either <a>compare</a> or <a><=</a>. -- Using <a>compare</a> can be more efficient for complex types. class Eq a => Ord a compare :: Ord a => a -> a -> Ordering (<) :: Ord a => a -> a -> Bool (>=) :: Ord a => a -> a -> Bool (>) :: Ord a => a -> a -> Bool (<=) :: Ord a => a -> a -> Bool max :: Ord a => a -> a -> a min :: Ord a => a -> a -> a -- | Class <a>Enum</a> defines operations on sequentially ordered types. -- -- The <tt>enumFrom</tt>... methods are used in Haskell's translation of -- arithmetic sequences. -- -- Instances of <a>Enum</a> may be derived for any enumeration type -- (types whose constructors have no fields). The nullary constructors -- are assumed to be numbered left-to-right by <a>fromEnum</a> from -- <tt>0</tt> through <tt>n-1</tt>. See Chapter 10 of the <i>Haskell -- Report</i> for more details. -- -- For any type that is an instance of class <a>Bounded</a> as well as -- <a>Enum</a>, the following should hold: -- -- <ul> -- <li>The calls <tt><a>succ</a> <a>maxBound</a></tt> and <tt><a>pred</a> -- <a>minBound</a></tt> should result in a runtime error.</li> -- <li><a>fromEnum</a> and <a>toEnum</a> should give a runtime error if -- the result value is not representable in the result type. For example, -- <tt><a>toEnum</a> 7 :: <a>Bool</a></tt> is an error.</li> -- <li><a>enumFrom</a> and <a>enumFromThen</a> should be defined with an -- implicit bound, thus:</li> -- </ul> -- -- <pre> -- enumFrom x = enumFromTo x maxBound -- enumFromThen x y = enumFromThenTo x y bound -- where -- bound | fromEnum y >= fromEnum x = maxBound -- | otherwise = minBound -- </pre> class Enum a succ :: Enum a => a -> a pred :: Enum a => a -> a toEnum :: Enum a => Int -> a fromEnum :: Enum a => a -> Int enumFrom :: Enum a => a -> [a] enumFromThen :: Enum a => a -> a -> [a] enumFromTo :: Enum a => a -> a -> [a] enumFromThenTo :: Enum a => a -> a -> a -> [a] -- | The <a>Bounded</a> class is used to name the upper and lower limits of -- a type. <a>Ord</a> is not a superclass of <a>Bounded</a> since types -- that are not totally ordered may also have upper and lower bounds. -- -- The <a>Bounded</a> class may be derived for any enumeration type; -- <a>minBound</a> is the first constructor listed in the <tt>data</tt> -- declaration and <a>maxBound</a> is the last. <a>Bounded</a> may also -- be derived for single-constructor datatypes whose constituent types -- are in <a>Bounded</a>. class Bounded a minBound :: Bounded a => a maxBound :: Bounded a => a -- | A fixed-precision integer type with at least the range <tt>[-2^29 .. -- 2^29-1]</tt>. The exact range for a given implementation can be -- determined by using <a>minBound</a> and <a>maxBound</a> from the -- <a>Bounded</a> class. data Int :: * data Integer :: * -- | Single-precision floating point numbers. It is desirable that this -- type be at least equal in range and precision to the IEEE -- single-precision type. data Float :: * -- | Double-precision floating point numbers. It is desirable that this -- type be at least equal in range and precision to the IEEE -- double-precision type. data Double :: * -- | Arbitrary-precision rational numbers, represented as a ratio of two -- <a>Integer</a> values. A rational number may be constructed using the -- <a>%</a> operator. type Rational = Ratio Integer -- | Basic numeric class. -- -- Minimal complete definition: all except <a>negate</a> or <tt>(-)</tt> class Num a (+) :: Num a => a -> a -> a (*) :: Num a => a -> a -> a (-) :: Num a => a -> a -> a negate :: Num a => a -> a abs :: Num a => a -> a signum :: Num a => a -> a fromInteger :: Num a => Integer -> a class (Num a, Ord a) => Real a toRational :: Real a => a -> Rational -- | Integral numbers, supporting integer division. -- -- Minimal complete definition: <a>quotRem</a> and <a>toInteger</a> class (Real a, Enum a) => Integral a quot :: Integral a => a -> a -> a rem :: Integral a => a -> a -> a div :: Integral a => a -> a -> a mod :: Integral a => a -> a -> a quotRem :: Integral a => a -> a -> (a, a) divMod :: Integral a => a -> a -> (a, a) toInteger :: Integral a => a -> Integer -- | Fractional numbers, supporting real division. -- -- Minimal complete definition: <a>fromRational</a> and (<a>recip</a> or -- <tt>(<a>/</a>)</tt>) class Num a => Fractional a (/) :: Fractional a => a -> a -> a recip :: Fractional a => a -> a fromRational :: Fractional a => Rational -> a -- | Trigonometric and hyperbolic functions and related functions. -- -- Minimal complete definition: <a>pi</a>, <a>exp</a>, <a>log</a>, -- <a>sin</a>, <a>cos</a>, <a>sinh</a>, <a>cosh</a>, <a>asin</a>, -- <a>acos</a>, <a>atan</a>, <a>asinh</a>, <a>acosh</a> and <a>atanh</a> class Fractional a => Floating a pi :: Floating a => a exp :: Floating a => a -> a sqrt :: Floating a => a -> a log :: Floating a => a -> a (**) :: Floating a => a -> a -> a logBase :: Floating a => a -> a -> a sin :: Floating a => a -> a tan :: Floating a => a -> a cos :: Floating a => a -> a asin :: Floating a => a -> a atan :: Floating a => a -> a acos :: Floating a => a -> a sinh :: Floating a => a -> a tanh :: Floating a => a -> a cosh :: Floating a => a -> a asinh :: Floating a => a -> a atanh :: Floating a => a -> a acosh :: Floating a => a -> a -- | Extracting components of fractions. -- -- Minimal complete definition: <a>properFraction</a> class (Real a, Fractional a) => RealFrac a properFraction :: (RealFrac a, Integral b) => a -> (b, a) truncate :: (RealFrac a, Integral b) => a -> b round :: (RealFrac a, Integral b) => a -> b ceiling :: (RealFrac a, Integral b) => a -> b floor :: (RealFrac a, Integral b) => a -> b -- | Efficient, machine-independent access to the components of a -- floating-point number. -- -- Minimal complete definition: all except <a>exponent</a>, -- <a>significand</a>, <a>scaleFloat</a> and <a>atan2</a> class (RealFrac a, Floating a) => RealFloat a floatRadix :: RealFloat a => a -> Integer floatDigits :: RealFloat a => a -> Int floatRange :: RealFloat a => a -> (Int, Int) decodeFloat :: RealFloat a => a -> (Integer, Int) encodeFloat :: RealFloat a => Integer -> Int -> a exponent :: RealFloat a => a -> Int significand :: RealFloat a => a -> a scaleFloat :: RealFloat a => Int -> a -> a isNaN :: RealFloat a => a -> Bool isInfinite :: RealFloat a => a -> Bool isDenormalized :: RealFloat a => a -> Bool isNegativeZero :: RealFloat a => a -> Bool isIEEE :: RealFloat a => a -> Bool atan2 :: RealFloat a => a -> a -> a -- | the same as <tt><a>flip</a> (<a>-</a>)</tt>. -- -- Because <tt>-</tt> is treated specially in the Haskell grammar, -- <tt>(-</tt> <i>e</i><tt>)</tt> is not a section, but an application of -- prefix negation. However, <tt>(<a>subtract</a></tt> -- <i>exp</i><tt>)</tt> is equivalent to the disallowed section. subtract :: Num a => a -> a -> a even :: Integral a => a -> Bool odd :: Integral a => a -> Bool -- | <tt><a>gcd</a> x y</tt> is the greatest (positive) integer that -- divides both <tt>x</tt> and <tt>y</tt>; for example <tt><a>gcd</a> -- (-3) 6</tt> = <tt>3</tt>, <tt><a>gcd</a> (-3) (-6)</tt> = <tt>3</tt>, -- <tt><a>gcd</a> 0 4</tt> = <tt>4</tt>. <tt><a>gcd</a> 0 0</tt> raises a -- runtime error. gcd :: Integral a => a -> a -> a -- | <tt><a>lcm</a> x y</tt> is the smallest positive integer that both -- <tt>x</tt> and <tt>y</tt> divide. lcm :: Integral a => a -> a -> a -- | raise a number to a non-negative integral power (^) :: (Num a, Integral b) => a -> b -> a -- | raise a number to an integral power (^^) :: (Fractional a, Integral b) => a -> b -> a -- | general coercion from integral types fromIntegral :: (Integral a, Num b) => a -> b -- | general coercion to fractional types realToFrac :: (Real a, Fractional b) => a -> b -- | The <a>Monad</a> class defines the basic operations over a -- <i>monad</i>, a concept from a branch of mathematics known as -- <i>category theory</i>. From the perspective of a Haskell programmer, -- however, it is best to think of a monad as an <i>abstract datatype</i> -- of actions. Haskell's <tt>do</tt> expressions provide a convenient -- syntax for writing monadic expressions. -- -- Minimal complete definition: <a>>>=</a> and <a>return</a>. -- -- Instances of <a>Monad</a> should satisfy the following laws: -- -- <pre> -- return a >>= k == k a -- m >>= return == m -- m >>= (\x -> k x >>= h) == (m >>= k) >>= h -- </pre> -- -- Instances of both <a>Monad</a> and <a>Functor</a> should additionally -- satisfy the law: -- -- <pre> -- fmap f xs == xs >>= return . f -- </pre> -- -- The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a> -- defined in the <a>Prelude</a> satisfy these laws. class Monad (m :: * -> *) (>>=) :: Monad m => m a -> (a -> m b) -> m b (>>) :: Monad m => m a -> m b -> m b return :: Monad m => a -> m a fail :: Monad m => String -> m a -- | The <a>Functor</a> class is used for types that can be mapped over. -- Instances of <a>Functor</a> should satisfy the following laws: -- -- <pre> -- fmap id == id -- fmap (f . g) == fmap f . fmap g -- </pre> -- -- The instances of <a>Functor</a> for lists, <a>Maybe</a> and <a>IO</a> -- satisfy these laws. class Functor (f :: * -> *) fmap :: Functor f => (a -> b) -> f a -> f b -- | <tt><a>mapM</a> f</tt> is equivalent to <tt><a>sequence</a> . -- <a>map</a> f</tt>. mapM :: Monad m => (a -> m b) -> [a] -> m [b] -- | <tt><a>mapM_</a> f</tt> is equivalent to <tt><a>sequence_</a> . -- <a>map</a> f</tt>. mapM_ :: Monad m => (a -> m b) -> [a] -> m () -- | Evaluate each action in the sequence from left to right, and collect -- the results. sequence :: Monad m => [m a] -> m [a] -- | Evaluate each action in the sequence from left to right, and ignore -- the results. sequence_ :: Monad m => [m a] -> m () -- | Same as <a>>>=</a>, but with the arguments interchanged. (=<<) :: Monad m => (a -> m b) -> m a -> m b -- | Identity function. id :: a -> a -- | Constant function. const :: a -> b -> a -- | Function composition. (.) :: (b -> c) -> (a -> b) -> a -> c -- | <tt><a>flip</a> f</tt> takes its (first) two arguments in the reverse -- order of <tt>f</tt>. flip :: (a -> b -> c) -> b -> a -> c -- | Application operator. This operator is redundant, since ordinary -- application <tt>(f x)</tt> means the same as <tt>(f <a>$</a> x)</tt>. -- However, <a>$</a> has low, right-associative binding precedence, so it -- sometimes allows parentheses to be omitted; for example: -- -- <pre> -- f $ g $ h x = f (g (h x)) -- </pre> -- -- It is also useful in higher-order situations, such as <tt><a>map</a> -- (<a>$</a> 0) xs</tt>, or <tt><a>zipWith</a> (<a>$</a>) fs xs</tt>. ($) :: (a -> b) -> a -> b -- | <tt><a>until</a> p f</tt> yields the result of applying <tt>f</tt> -- until <tt>p</tt> holds. until :: (a -> Bool) -> (a -> a) -> a -> a -- | <a>asTypeOf</a> is a type-restricted version of <a>const</a>. It is -- usually used as an infix operator, and its typing forces its first -- argument (which is usually overloaded) to have the same type as the -- second. asTypeOf :: a -> a -> a -- | <a>error</a> stops execution and displays an error message. error :: [Char] -> a -- | A special case of <a>error</a>. It is expected that compilers will -- recognize this and insert error messages which are more appropriate to -- the context in which <a>undefined</a> appears. undefined :: a -- | Evaluates its first argument to head normal form, and then returns its -- second argument as the result. seq :: a -> b -> b -- | Strict (call-by-value) application, defined in terms of <a>seq</a>. ($!) :: (a -> b) -> a -> b -- | <a>map</a> <tt>f xs</tt> is the list obtained by applying <tt>f</tt> -- to each element of <tt>xs</tt>, i.e., -- -- <pre> -- map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn] -- map f [x1, x2, ...] == [f x1, f x2, ...] -- </pre> map :: (a -> b) -> [a] -> [b] -- | Append two lists, i.e., -- -- <pre> -- [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn] -- [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...] -- </pre> -- -- If the first list is not finite, the result is the first list. (++) :: [a] -> [a] -> [a] -- | <a>filter</a>, applied to a predicate and a list, returns the list of -- those elements that satisfy the predicate; i.e., -- -- <pre> -- filter p xs = [ x | x <- xs, p x] -- </pre> filter :: (a -> Bool) -> [a] -> [a] -- | Extract the first element of a list, which must be non-empty. head :: [a] -> a -- | Extract the last element of a list, which must be finite and -- non-empty. last :: [a] -> a -- | Extract the elements after the head of a list, which must be -- non-empty. tail :: [a] -> [a] -- | Return all the elements of a list except the last one. The list must -- be non-empty. init :: [a] -> [a] -- | Test whether a list is empty. null :: [a] -> Bool -- | <i>O(n)</i>. <a>length</a> returns the length of a finite list as an -- <a>Int</a>. It is an instance of the more general -- <a>genericLength</a>, the result type of which may be any kind of -- number. length :: [a] -> Int -- | List index (subscript) operator, starting from 0. It is an instance of -- the more general <a>genericIndex</a>, which takes an index of any -- integral type. (!!) :: [a] -> Int -> a -- | <a>reverse</a> <tt>xs</tt> returns the elements of <tt>xs</tt> in -- reverse order. <tt>xs</tt> must be finite. reverse :: [a] -> [a] -- | <a>foldl</a>, applied to a binary operator, a starting value -- (typically the left-identity of the operator), and a list, reduces the -- list using the binary operator, from left to right: -- -- <pre> -- foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn -- </pre> -- -- The list must be finite. foldl :: (a -> b -> a) -> a -> [b] -> a -- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value -- argument, and thus must be applied to non-empty lists. foldl1 :: (a -> a -> a) -> [a] -> a -- | <a>foldr</a>, applied to a binary operator, a starting value -- (typically the right-identity of the operator), and a list, reduces -- the list using the binary operator, from right to left: -- -- <pre> -- foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...) -- </pre> foldr :: (a -> b -> b) -> b -> [a] -> b -- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value -- argument, and thus must be applied to non-empty lists. foldr1 :: (a -> a -> a) -> [a] -> a -- | <a>and</a> returns the conjunction of a Boolean list. For the result -- to be <a>True</a>, the list must be finite; <a>False</a>, however, -- results from a <a>False</a> value at a finite index of a finite or -- infinite list. and :: [Bool] -> Bool -- | <a>or</a> returns the disjunction of a Boolean list. For the result to -- be <a>False</a>, the list must be finite; <a>True</a>, however, -- results from a <a>True</a> value at a finite index of a finite or -- infinite list. or :: [Bool] -> Bool -- | Applied to a predicate and a list, <a>any</a> determines if any -- element of the list satisfies the predicate. For the result to be -- <a>False</a>, the list must be finite; <a>True</a>, however, results -- from a <a>True</a> value for the predicate applied to an element at a -- finite index of a finite or infinite list. any :: (a -> Bool) -> [a] -> Bool -- | Applied to a predicate and a list, <a>all</a> determines if all -- elements of the list satisfy the predicate. For the result to be -- <a>True</a>, the list must be finite; <a>False</a>, however, results -- from a <a>False</a> value for the predicate applied to an element at a -- finite index of a finite or infinite list. all :: (a -> Bool) -> [a] -> Bool -- | The <a>sum</a> function computes the sum of a finite list of numbers. sum :: Num a => [a] -> a -- | The <a>product</a> function computes the product of a finite list of -- numbers. product :: Num a => [a] -> a -- | Concatenate a list of lists. concat :: [[a]] -> [a] -- | Map a function over a list and concatenate the results. concatMap :: (a -> [b]) -> [a] -> [b] -- | <a>maximum</a> returns the maximum value from a list, which must be -- non-empty, finite, and of an ordered type. It is a special case of -- <a>maximumBy</a>, which allows the programmer to supply their own -- comparison function. maximum :: Ord a => [a] -> a -- | <a>minimum</a> returns the minimum value from a list, which must be -- non-empty, finite, and of an ordered type. It is a special case of -- <a>minimumBy</a>, which allows the programmer to supply their own -- comparison function. minimum :: Ord a => [a] -> a -- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of -- successive reduced values from the left: -- -- <pre> -- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...] -- </pre> -- -- Note that -- -- <pre> -- last (scanl f z xs) == foldl f z xs. -- </pre> scanl :: (a -> b -> a) -> a -> [b] -> [a] -- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value -- argument: -- -- <pre> -- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...] -- </pre> scanl1 :: (a -> a -> a) -> [a] -> [a] -- | <a>scanr</a> is the right-to-left dual of <a>scanl</a>. Note that -- -- <pre> -- head (scanr f z xs) == foldr f z xs. -- </pre> scanr :: (a -> b -> b) -> b -> [a] -> [b] -- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value -- argument. scanr1 :: (a -> a -> a) -> [a] -> [a] -- | <a>iterate</a> <tt>f x</tt> returns an infinite list of repeated -- applications of <tt>f</tt> to <tt>x</tt>: -- -- <pre> -- iterate f x == [x, f x, f (f x), ...] -- </pre> iterate :: (a -> a) -> a -> [a] -- | <a>repeat</a> <tt>x</tt> is an infinite list, with <tt>x</tt> the -- value of every element. repeat :: a -> [a] -- | <a>replicate</a> <tt>n x</tt> is a list of length <tt>n</tt> with -- <tt>x</tt> the value of every element. It is an instance of the more -- general <a>genericReplicate</a>, in which <tt>n</tt> may be of any -- integral type. replicate :: Int -> a -> [a] -- | <a>cycle</a> ties a finite list into a circular one, or equivalently, -- the infinite repetition of the original list. It is the identity on -- infinite lists. cycle :: [a] -> [a] -- | <a>take</a> <tt>n</tt>, applied to a list <tt>xs</tt>, returns the -- prefix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt> itself if -- <tt>n > <a>length</a> xs</tt>: -- -- <pre> -- take 5 "Hello World!" == "Hello" -- take 3 [1,2,3,4,5] == [1,2,3] -- take 3 [1,2] == [1,2] -- take 3 [] == [] -- take (-1) [1,2] == [] -- take 0 [1,2] == [] -- </pre> -- -- It is an instance of the more general <a>genericTake</a>, in which -- <tt>n</tt> may be of any integral type. take :: Int -> [a] -> [a] -- | <a>drop</a> <tt>n xs</tt> returns the suffix of <tt>xs</tt> after the -- first <tt>n</tt> elements, or <tt>[]</tt> if <tt>n > <a>length</a> -- xs</tt>: -- -- <pre> -- drop 6 "Hello World!" == "World!" -- drop 3 [1,2,3,4,5] == [4,5] -- drop 3 [1,2] == [] -- drop 3 [] == [] -- drop (-1) [1,2] == [1,2] -- drop 0 [1,2] == [1,2] -- </pre> -- -- It is an instance of the more general <a>genericDrop</a>, in which -- <tt>n</tt> may be of any integral type. drop :: Int -> [a] -> [a] -- | <a>splitAt</a> <tt>n xs</tt> returns a tuple where first element is -- <tt>xs</tt> prefix of length <tt>n</tt> and second element is the -- remainder of the list: -- -- <pre> -- splitAt 6 "Hello World!" == ("Hello ","World!") -- splitAt 3 [1,2,3,4,5] == ([1,2,3],[4,5]) -- splitAt 1 [1,2,3] == ([1],[2,3]) -- splitAt 3 [1,2,3] == ([1,2,3],[]) -- splitAt 4 [1,2,3] == ([1,2,3],[]) -- splitAt 0 [1,2,3] == ([],[1,2,3]) -- splitAt (-1) [1,2,3] == ([],[1,2,3]) -- </pre> -- -- It is equivalent to <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>. -- <a>splitAt</a> is an instance of the more general -- <a>genericSplitAt</a>, in which <tt>n</tt> may be of any integral -- type. splitAt :: Int -> [a] -> ([a], [a]) -- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list -- <tt>xs</tt>, returns the longest prefix (possibly empty) of -- <tt>xs</tt> of elements that satisfy <tt>p</tt>: -- -- <pre> -- takeWhile (< 3) [1,2,3,4,1,2,3,4] == [1,2] -- takeWhile (< 9) [1,2,3] == [1,2,3] -- takeWhile (< 0) [1,2,3] == [] -- </pre> takeWhile :: (a -> Bool) -> [a] -> [a] -- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after -- <a>takeWhile</a> <tt>p xs</tt>: -- -- <pre> -- dropWhile (< 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3] -- dropWhile (< 9) [1,2,3] == [] -- dropWhile (< 0) [1,2,3] == [1,2,3] -- </pre> dropWhile :: (a -> Bool) -> [a] -> [a] -- | <a>span</a>, applied to a predicate <tt>p</tt> and a list <tt>xs</tt>, -- returns a tuple where first element is longest prefix (possibly empty) -- of <tt>xs</tt> of elements that satisfy <tt>p</tt> and second element -- is the remainder of the list: -- -- <pre> -- span (< 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4]) -- span (< 9) [1,2,3] == ([1,2,3],[]) -- span (< 0) [1,2,3] == ([],[1,2,3]) -- </pre> -- -- <a>span</a> <tt>p xs</tt> is equivalent to <tt>(<a>takeWhile</a> p xs, -- <a>dropWhile</a> p xs)</tt> span :: (a -> Bool) -> [a] -> ([a], [a]) -- | <a>break</a>, applied to a predicate <tt>p</tt> and a list -- <tt>xs</tt>, returns a tuple where first element is longest prefix -- (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i> -- <tt>p</tt> and second element is the remainder of the list: -- -- <pre> -- break (> 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4]) -- break (< 9) [1,2,3] == ([],[1,2,3]) -- break (> 9) [1,2,3] == ([1,2,3],[]) -- </pre> -- -- <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> . -- p)</tt>. break :: (a -> Bool) -> [a] -> ([a], [a]) -- | <a>elem</a> is the list membership predicate, usually written in infix -- form, e.g., <tt>x `elem` xs</tt>. For the result to be <a>False</a>, -- the list must be finite; <a>True</a>, however, results from an element -- equal to <tt>x</tt> found at a finite index of a finite or infinite -- list. elem :: Eq a => a -> [a] -> Bool -- | <a>notElem</a> is the negation of <a>elem</a>. notElem :: Eq a => a -> [a] -> Bool -- | <a>lookup</a> <tt>key assocs</tt> looks up a key in an association -- list. lookup :: Eq a => a -> [(a, b)] -> Maybe b -- | <a>zip</a> takes two lists and returns a list of corresponding pairs. -- If one input list is short, excess elements of the longer list are -- discarded. zip :: [a] -> [b] -> [(a, b)] -- | <a>zip3</a> takes three lists and returns a list of triples, analogous -- to <a>zip</a>. zip3 :: [a] -> [b] -> [c] -> [(a, b, c)] -- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function -- given as the first argument, instead of a tupling function. For -- example, <tt><a>zipWith</a> (+)</tt> is applied to two lists to -- produce the list of corresponding sums. zipWith :: (a -> b -> c) -> [a] -> [b] -> [c] -- | The <a>zipWith3</a> function takes a function which combines three -- elements, as well as three lists and returns a list of their -- point-wise combination, analogous to <a>zipWith</a>. zipWith3 :: (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d] -- | <a>unzip</a> transforms a list of pairs into a list of first -- components and a list of second components. unzip :: [(a, b)] -> ([a], [b]) -- | The <a>unzip3</a> function takes a list of triples and returns three -- lists, analogous to <a>unzip</a>. unzip3 :: [(a, b, c)] -> ([a], [b], [c]) -- | <a>lines</a> breaks a string up into a list of strings at newline -- characters. The resulting strings do not contain newlines. lines :: String -> [String] -- | <a>words</a> breaks a string up into a list of words, which were -- delimited by white space. words :: String -> [String] -- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins -- lines, after appending a terminating newline to each. unlines :: [String] -> String -- | <a>unwords</a> is an inverse operation to <a>words</a>. It joins words -- with separating spaces. unwords :: [String] -> String -- | The <tt>shows</tt> functions return a function that prepends the -- output <a>String</a> to an existing <a>String</a>. This allows -- constant-time concatenation of results using function composition. type ShowS = String -> String -- | Conversion of values to readable <a>String</a>s. -- -- Minimal complete definition: <a>showsPrec</a> or <a>show</a>. -- -- Derived instances of <a>Show</a> have the following properties, which -- are compatible with derived instances of <a>Read</a>: -- -- <ul> -- <li>The result of <a>show</a> is a syntactically correct Haskell -- expression containing only constants, given the fixity declarations in -- force at the point where the type is declared. It contains only the -- constructor names defined in the data type, parentheses, and spaces. -- When labelled constructor fields are used, braces, commas, field -- names, and equal signs are also used.</li> -- <li>If the constructor is defined to be an infix operator, then -- <a>showsPrec</a> will produce infix applications of the -- constructor.</li> -- <li>the representation will be enclosed in parentheses if the -- precedence of the top-level constructor in <tt>x</tt> is less than -- <tt>d</tt> (associativity is ignored). Thus, if <tt>d</tt> is -- <tt>0</tt> then the result is never surrounded in parentheses; if -- <tt>d</tt> is <tt>11</tt> it is always surrounded in parentheses, -- unless it is an atomic expression.</li> -- <li>If the constructor is defined using record syntax, then -- <a>show</a> will produce the record-syntax form, with the fields given -- in the same order as the original declaration.</li> -- </ul> -- -- For example, given the declarations -- -- <pre> -- infixr 5 :^: -- data Tree a = Leaf a | Tree a :^: Tree a -- </pre> -- -- the derived instance of <a>Show</a> is equivalent to -- -- <pre> -- instance (Show a) => Show (Tree a) where -- -- showsPrec d (Leaf m) = showParen (d > app_prec) $ -- showString "Leaf " . showsPrec (app_prec+1) m -- where app_prec = 10 -- -- showsPrec d (u :^: v) = showParen (d > up_prec) $ -- showsPrec (up_prec+1) u . -- showString " :^: " . -- showsPrec (up_prec+1) v -- where up_prec = 5 -- </pre> -- -- Note that right-associativity of <tt>:^:</tt> is ignored. For example, -- -- <ul> -- <li><tt><a>show</a> (Leaf 1 :^: Leaf 2 :^: Leaf 3)</tt> produces the -- string <tt>"Leaf 1 :^: (Leaf 2 :^: Leaf 3)"</tt>.</li> -- </ul> class Show a showsPrec :: Show a => Int -> a -> ShowS show :: Show a => a -> String showList :: Show a => [a] -> ShowS -- | equivalent to <a>showsPrec</a> with a precedence of 0. shows :: Show a => a -> ShowS -- | utility function converting a <a>Char</a> to a show function that -- simply prepends the character unchanged. showChar :: Char -> ShowS -- | utility function converting a <a>String</a> to a show function that -- simply prepends the string unchanged. showString :: String -> ShowS -- | utility function that surrounds the inner show function with -- parentheses when the <a>Bool</a> parameter is <a>True</a>. showParen :: Bool -> ShowS -> ShowS -- | A parser for a type <tt>a</tt>, represented as a function that takes a -- <a>String</a> and returns a list of possible parses as -- <tt>(a,<a>String</a>)</tt> pairs. -- -- Note that this kind of backtracking parser is very inefficient; -- reading a large structure may be quite slow (cf <a>ReadP</a>). type ReadS a = String -> [(a, String)] -- | Parsing of <a>String</a>s, producing values. -- -- Minimal complete definition: <a>readsPrec</a> (or, for GHC only, -- <a>readPrec</a>) -- -- Derived instances of <a>Read</a> make the following assumptions, which -- derived instances of <a>Show</a> obey: -- -- <ul> -- <li>If the constructor is defined to be an infix operator, then the -- derived <a>Read</a> instance will parse only infix applications of the -- constructor (not the prefix form).</li> -- <li>Associativity is not used to reduce the occurrence of parentheses, -- although precedence may be.</li> -- <li>If the constructor is defined using record syntax, the derived -- <a>Read</a> will parse only the record-syntax form, and furthermore, -- the fields must be given in the same order as the original -- declaration.</li> -- <li>The derived <a>Read</a> instance allows arbitrary Haskell -- whitespace between tokens of the input string. Extra parentheses are -- also allowed.</li> -- </ul> -- -- For example, given the declarations -- -- <pre> -- infixr 5 :^: -- data Tree a = Leaf a | Tree a :^: Tree a -- </pre> -- -- the derived instance of <a>Read</a> in Haskell 98 is equivalent to -- -- <pre> -- instance (Read a) => Read (Tree a) where -- -- readsPrec d r = readParen (d > app_prec) -- (\r -> [(Leaf m,t) | -- ("Leaf",s) <- lex r, -- (m,t) <- readsPrec (app_prec+1) s]) r -- -- ++ readParen (d > up_prec) -- (\r -> [(u:^:v,w) | -- (u,s) <- readsPrec (up_prec+1) r, -- (":^:",t) <- lex s, -- (v,w) <- readsPrec (up_prec+1) t]) r -- -- where app_prec = 10 -- up_prec = 5 -- </pre> -- -- Note that right-associativity of <tt>:^:</tt> is unused. -- -- The derived instance in GHC is equivalent to -- -- <pre> -- instance (Read a) => Read (Tree a) where -- -- readPrec = parens $ (prec app_prec $ do -- Ident "Leaf" <- lexP -- m <- step readPrec -- return (Leaf m)) -- -- +++ (prec up_prec $ do -- u <- step readPrec -- Symbol ":^:" <- lexP -- v <- step readPrec -- return (u :^: v)) -- -- where app_prec = 10 -- up_prec = 5 -- -- readListPrec = readListPrecDefault -- </pre> class Read a readsPrec :: Read a => Int -> ReadS a readList :: Read a => ReadS [a] -- | equivalent to <a>readsPrec</a> with a precedence of 0. reads :: Read a => ReadS a -- | <tt><a>readParen</a> <a>True</a> p</tt> parses what <tt>p</tt> parses, -- but surrounded with parentheses. -- -- <tt><a>readParen</a> <a>False</a> p</tt> parses what <tt>p</tt> -- parses, but optionally surrounded with parentheses. readParen :: Bool -> ReadS a -> ReadS a -- | The <a>read</a> function reads input from a string, which must be -- completely consumed by the input process. read :: Read a => String -> a -- | The <a>lex</a> function reads a single lexeme from the input, -- discarding initial white space, and returning the characters that -- constitute the lexeme. If the input string contains only white space, -- <a>lex</a> returns a single successful `lexeme' consisting of the -- empty string. (Thus <tt><a>lex</a> "" = [("","")]</tt>.) If there is -- no legal lexeme at the beginning of the input string, <a>lex</a> fails -- (i.e. returns <tt>[]</tt>). -- -- This lexer is not completely faithful to the Haskell lexical syntax in -- the following respects: -- -- <ul> -- <li>Qualified names are not handled properly</li> -- <li>Octal and hexadecimal numerics are not recognized as a single -- token</li> -- <li>Comments are not treated properly</li> -- </ul> lex :: ReadS String -- | A value of type <tt><a>IO</a> a</tt> is a computation which, when -- performed, does some I/O before returning a value of type <tt>a</tt>. -- -- There is really only one way to "perform" an I/O action: bind it to -- <tt>Main.main</tt> in your program. When your program is run, the I/O -- will be performed. It isn't possible to perform I/O from an arbitrary -- function, unless that function is itself in the <a>IO</a> monad and -- called at some point, directly or indirectly, from <tt>Main.main</tt>. -- -- <a>IO</a> is a monad, so <a>IO</a> actions can be combined using -- either the do-notation or the <tt>>></tt> and <tt>>>=</tt> -- operations from the <tt>Monad</tt> class. data IO a :: * -> * -- | Write a character to the standard output device (same as -- <a>hPutChar</a> <a>stdout</a>). putChar :: Char -> IO () -- | Write a string to the standard output device (same as <a>hPutStr</a> -- <a>stdout</a>). putStr :: String -> IO () -- | The same as <a>putStr</a>, but adds a newline character. putStrLn :: String -> IO () -- | The <a>print</a> function outputs a value of any printable type to the -- standard output device. Printable types are those that are instances -- of class <a>Show</a>; <a>print</a> converts values to strings for -- output using the <a>show</a> operation and adds a newline. -- -- For example, a program to print the first 20 integers and their powers -- of 2 could be written as: -- -- <pre> -- main = print ([(n, 2^n) | n <- [0..19]]) -- </pre> print :: Show a => a -> IO () -- | Read a character from the standard input device (same as -- <a>hGetChar</a> <a>stdin</a>). getChar :: IO Char -- | Read a line from the standard input device (same as <a>hGetLine</a> -- <a>stdin</a>). getLine :: IO String -- | The <a>getContents</a> operation returns all user input as a single -- string, which is read lazily as it is needed (same as -- <a>hGetContents</a> <a>stdin</a>). getContents :: IO String -- | The <a>interact</a> function takes a function of type -- <tt>String->String</tt> as its argument. The entire input from the -- standard input device is passed to this function as its argument, and -- the resulting string is output on the standard output device. interact :: (String -> String) -> IO () -- | File and directory names are values of type <a>String</a>, whose -- precise meaning is operating system dependent. Files can be opened, -- yielding a handle which can then be used to operate on the contents of -- that file. type FilePath = String -- | The <a>readFile</a> function reads a file and returns the contents of -- the file as a string. The file is read lazily, on demand, as with -- <a>getContents</a>. readFile :: FilePath -> IO String -- | The computation <a>writeFile</a> <tt>file str</tt> function writes the -- string <tt>str</tt>, to the file <tt>file</tt>. writeFile :: FilePath -> String -> IO () -- | The computation <a>appendFile</a> <tt>file str</tt> function appends -- the string <tt>str</tt>, to the file <tt>file</tt>. -- -- Note that <a>writeFile</a> and <a>appendFile</a> write a literal -- string to a file. To write a value of any printable type, as with -- <a>print</a>, use the <a>show</a> function to convert the value to a -- string first. -- -- <pre> -- main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]]) -- </pre> appendFile :: FilePath -> String -> IO () -- | The <a>readIO</a> function is similar to <a>read</a> except that it -- signals parse failure to the <a>IO</a> monad instead of terminating -- the program. readIO :: Read a => String -> IO a -- | The <a>readLn</a> function combines <a>getLine</a> and <a>readIO</a>. readLn :: Read a => IO a -- | The Haskell 98 type for exceptions in the <a>IO</a> monad. Any I/O -- operation may raise an <a>IOError</a> instead of returning a result. -- For a more general type of exception, including also those that arise -- in pure code, see <a>Control.Exception.Exception</a>. -- -- In Haskell 98, this is an opaque type. type IOError = IOException -- | Raise an <a>IOError</a> in the <a>IO</a> monad. ioError :: IOError -> IO a -- | Construct an <a>IOError</a> value with a string describing the error. -- The <a>fail</a> method of the <a>IO</a> instance of the <a>Monad</a> -- class raises a <a>userError</a>, thus: -- -- <pre> -- instance Monad IO where -- ... -- fail s = ioError (userError s) -- </pre> userError :: String -> IOError -- | The <a>catch</a> function establishes a handler that receives any -- <a>IOError</a> raised in the action protected by <a>catch</a>. An -- <a>IOError</a> is caught by the most recent handler established by one -- of the exception handling functions. These handlers are not selective: -- all <a>IOError</a>s are caught. Exception propagation must be -- explicitly provided in a handler by re-raising any unwanted -- exceptions. For example, in -- -- <pre> -- f = catch g (\e -> if IO.isEOFError e then return [] else ioError e) -- </pre> -- -- the function <tt>f</tt> returns <tt>[]</tt> when an end-of-file -- exception (cf. <a>isEOFError</a>) occurs in <tt>g</tt>; otherwise, the -- exception is propagated to the next outer handler. -- -- When an exception propagates outside the main program, the Haskell -- system prints the associated <a>IOError</a> value and exits the -- program. -- -- Non-I/O exceptions are not caught by this variant; to catch all -- exceptions, use <a>catch</a> from <a>Control.Exception</a>. catch :: IO a -> (IOError -> IO a) -> IO a module Foreign.StablePtr -- | A <i>stable pointer</i> is a reference to a Haskell expression that is -- guaranteed not to be affected by garbage collection, i.e., it will -- neither be deallocated nor will the value of the stable pointer itself -- change during garbage collection (ordinary references may be relocated -- during garbage collection). Consequently, stable pointers can be -- passed to foreign code, which can treat it as an opaque reference to a -- Haskell value. -- -- A value of type <tt>StablePtr a</tt> is a stable pointer to a Haskell -- expression of type <tt>a</tt>. data StablePtr a :: * -> * -- | Create a stable pointer referring to the given Haskell value. newStablePtr :: a -> IO (StablePtr a) -- | Obtain the Haskell value referenced by a stable pointer, i.e., the -- same value that was passed to the corresponding call to -- <tt>makeStablePtr</tt>. If the argument to <a>deRefStablePtr</a> has -- already been freed using <a>freeStablePtr</a>, the behaviour of -- <a>deRefStablePtr</a> is undefined. deRefStablePtr :: StablePtr a -> IO a -- | Dissolve the association between the stable pointer and the Haskell -- value. Afterwards, if the stable pointer is passed to -- <a>deRefStablePtr</a> or <a>freeStablePtr</a>, the behaviour is -- undefined. However, the stable pointer may still be passed to -- <a>castStablePtrToPtr</a>, but the <tt><a>Ptr</a> ()</tt> value -- returned by <a>castStablePtrToPtr</a>, in this case, is undefined (in -- particular, it may be <a>nullPtr</a>). Nevertheless, the call to -- <a>castStablePtrToPtr</a> is guaranteed not to diverge. freeStablePtr :: StablePtr a -> IO () -- | Coerce a stable pointer to an address. No guarantees are made about -- the resulting value, except that the original stable pointer can be -- recovered by <a>castPtrToStablePtr</a>. In particular, the address may -- not refer to an accessible memory location and any attempt to pass it -- to the member functions of the class <a>Storable</a> leads to -- undefined behaviour. castStablePtrToPtr :: StablePtr a -> Ptr () -- | The inverse of <a>castStablePtrToPtr</a>, i.e., we have the identity -- -- <pre> -- sp == castPtrToStablePtr (castStablePtrToPtr sp) -- </pre> -- -- for any stable pointer <tt>sp</tt> on which <a>freeStablePtr</a> has -- not been executed yet. Moreover, <a>castPtrToStablePtr</a> may only be -- applied to pointers that have been produced by -- <a>castStablePtrToPtr</a>. castPtrToStablePtr :: Ptr () -> StablePtr a module Data.Ix -- | The <a>Ix</a> class is used to map a contiguous subrange of values in -- a type onto integers. It is used primarily for array indexing (see the -- array package). -- -- The first argument <tt>(l,u)</tt> of each of these operations is a -- pair specifying the lower and upper bounds of a contiguous subrange of -- values. -- -- An implementation is entitled to assume the following laws about these -- operations: -- -- <ul> -- <li><tt><a>inRange</a> (l,u) i == <a>elem</a> i (<a>range</a> -- (l,u))</tt> <tt> </tt></li> -- <li><tt><a>range</a> (l,u) <a>!!</a> <a>index</a> (l,u) i == i</tt>, -- when <tt><a>inRange</a> (l,u) i</tt></li> -- <li><tt><a>map</a> (<a>index</a> (l,u)) (<a>range</a> (l,u))) == -- [0..<a>rangeSize</a> (l,u)-1]</tt> <tt> </tt></li> -- <li><tt><a>rangeSize</a> (l,u) == <a>length</a> (<a>range</a> -- (l,u))</tt> <tt> </tt></li> -- </ul> -- -- Minimal complete instance: <a>range</a>, <a>index</a> and -- <a>inRange</a>. class Ord a => Ix a range :: Ix a => (a, a) -> [a] index :: Ix a => (a, a) -> a -> Int inRange :: Ix a => (a, a) -> a -> Bool rangeSize :: Ix a => (a, a) -> Int module Data.Char -- | The character type <a>Char</a> is an enumeration whose values -- represent Unicode (or equivalently ISO/IEC 10646) characters (see -- <a>http://www.unicode.org/</a> for details). This set extends the ISO -- 8859-1 (Latin-1) character set (the first 256 characters), which is -- itself an extension of the ASCII character set (the first 128 -- characters). A character literal in Haskell has type <a>Char</a>. -- -- To convert a <a>Char</a> to or from the corresponding <a>Int</a> value -- defined by Unicode, use <a>toEnum</a> and <a>fromEnum</a> from the -- <a>Enum</a> class respectively (or equivalently <tt>ord</tt> and -- <tt>chr</tt>). data Char :: * -- | A <a>String</a> is a list of characters. String constants in Haskell -- are values of type <a>String</a>. type String = [Char] -- | Selects control characters, which are the non-printing characters of -- the Latin-1 subset of Unicode. isControl :: Char -> Bool -- | Returns <a>True</a> for any Unicode space character, and the control -- characters <tt>\t</tt>, <tt>\n</tt>, <tt>\r</tt>, <tt>\f</tt>, -- <tt>\v</tt>. isSpace :: Char -> Bool -- | Selects lower-case alphabetic Unicode characters (letters). isLower :: Char -> Bool -- | Selects upper-case or title-case alphabetic Unicode characters -- (letters). Title case is used by a small number of letter ligatures -- like the single-character form of <i>Lj</i>. isUpper :: Char -> Bool -- | Selects alphabetic Unicode characters (lower-case, upper-case and -- title-case letters, plus letters of caseless scripts and modifiers -- letters). This function is equivalent to <a>isLetter</a>. isAlpha :: Char -> Bool -- | Selects alphabetic or numeric digit Unicode characters. -- -- Note that numeric digits outside the ASCII range are selected by this -- function but not by <a>isDigit</a>. Such digits may be part of -- identifiers but are not used by the printer and reader to represent -- numbers. isAlphaNum :: Char -> Bool -- | Selects printable Unicode characters (letters, numbers, marks, -- punctuation, symbols and spaces). isPrint :: Char -> Bool -- | Selects ASCII digits, i.e. <tt>'0'</tt>..<tt>'9'</tt>. isDigit :: Char -> Bool -- | Selects ASCII octal digits, i.e. <tt>'0'</tt>..<tt>'7'</tt>. isOctDigit :: Char -> Bool -- | Selects ASCII hexadecimal digits, i.e. <tt>'0'</tt>..<tt>'9'</tt>, -- <tt>'a'</tt>..<tt>'f'</tt>, <tt>'A'</tt>..<tt>'F'</tt>. isHexDigit :: Char -> Bool -- | Selects alphabetic Unicode characters (lower-case, upper-case and -- title-case letters, plus letters of caseless scripts and modifiers -- letters). This function is equivalent to <a>isAlpha</a>. isLetter :: Char -> Bool -- | Selects Unicode mark characters, e.g. accents and the like, which -- combine with preceding letters. isMark :: Char -> Bool -- | Selects Unicode numeric characters, including digits from various -- scripts, Roman numerals, etc. isNumber :: Char -> Bool -- | Selects Unicode punctuation characters, including various kinds of -- connectors, brackets and quotes. isPunctuation :: Char -> Bool -- | Selects Unicode symbol characters, including mathematical and currency -- symbols. isSymbol :: Char -> Bool -- | Selects Unicode space and separator characters. isSeparator :: Char -> Bool -- | Selects the first 128 characters of the Unicode character set, -- corresponding to the ASCII character set. isAscii :: Char -> Bool -- | Selects the first 256 characters of the Unicode character set, -- corresponding to the ISO 8859-1 (Latin-1) character set. isLatin1 :: Char -> Bool -- | Selects ASCII upper-case letters, i.e. characters satisfying both -- <a>isAscii</a> and <a>isUpper</a>. isAsciiUpper :: Char -> Bool -- | Selects ASCII lower-case letters, i.e. characters satisfying both -- <a>isAscii</a> and <a>isLower</a>. isAsciiLower :: Char -> Bool -- | Unicode General Categories (column 2 of the UnicodeData table) in the -- order they are listed in the Unicode standard. data GeneralCategory :: * -- | Lu: Letter, Uppercase UppercaseLetter :: GeneralCategory -- | Ll: Letter, Lowercase LowercaseLetter :: GeneralCategory -- | Lt: Letter, Titlecase TitlecaseLetter :: GeneralCategory -- | Lm: Letter, Modifier ModifierLetter :: GeneralCategory -- | Lo: Letter, Other OtherLetter :: GeneralCategory -- | Mn: Mark, Non-Spacing NonSpacingMark :: GeneralCategory -- | Mc: Mark, Spacing Combining SpacingCombiningMark :: GeneralCategory -- | Me: Mark, Enclosing EnclosingMark :: GeneralCategory -- | Nd: Number, Decimal DecimalNumber :: GeneralCategory -- | Nl: Number, Letter LetterNumber :: GeneralCategory -- | No: Number, Other OtherNumber :: GeneralCategory -- | Pc: Punctuation, Connector ConnectorPunctuation :: GeneralCategory -- | Pd: Punctuation, Dash DashPunctuation :: GeneralCategory -- | Ps: Punctuation, Open OpenPunctuation :: GeneralCategory -- | Pe: Punctuation, Close ClosePunctuation :: GeneralCategory -- | Pi: Punctuation, Initial quote InitialQuote :: GeneralCategory -- | Pf: Punctuation, Final quote FinalQuote :: GeneralCategory -- | Po: Punctuation, Other OtherPunctuation :: GeneralCategory -- | Sm: Symbol, Math MathSymbol :: GeneralCategory -- | Sc: Symbol, Currency CurrencySymbol :: GeneralCategory -- | Sk: Symbol, Modifier ModifierSymbol :: GeneralCategory -- | So: Symbol, Other OtherSymbol :: GeneralCategory -- | Zs: Separator, Space Space :: GeneralCategory -- | Zl: Separator, Line LineSeparator :: GeneralCategory -- | Zp: Separator, Paragraph ParagraphSeparator :: GeneralCategory -- | Cc: Other, Control Control :: GeneralCategory -- | Cf: Other, Format Format :: GeneralCategory -- | Cs: Other, Surrogate Surrogate :: GeneralCategory -- | Co: Other, Private Use PrivateUse :: GeneralCategory -- | Cn: Other, Not Assigned NotAssigned :: GeneralCategory -- | The Unicode general category of the character. generalCategory :: Char -> GeneralCategory -- | Convert a letter to the corresponding upper-case letter, if any. Any -- other character is returned unchanged. toUpper :: Char -> Char -- | Convert a letter to the corresponding lower-case letter, if any. Any -- other character is returned unchanged. toLower :: Char -> Char -- | Convert a letter to the corresponding title-case or upper-case letter, -- if any. (Title case differs from upper case only for a small number of -- ligature letters.) Any other character is returned unchanged. toTitle :: Char -> Char -- | Convert a single digit <a>Char</a> to the corresponding <a>Int</a>. -- This function fails unless its argument satisfies <a>isHexDigit</a>, -- but recognises both upper and lower-case hexadecimal digits (i.e. -- <tt>'0'</tt>..<tt>'9'</tt>, <tt>'a'</tt>..<tt>'f'</tt>, -- <tt>'A'</tt>..<tt>'F'</tt>). digitToInt :: Char -> Int -- | Convert an <a>Int</a> in the range <tt>0</tt>..<tt>15</tt> to the -- corresponding single digit <a>Char</a>. This function fails on other -- inputs, and generates lower-case hexadecimal digits. intToDigit :: Int -> Char -- | The <a>fromEnum</a> method restricted to the type <a>Char</a>. ord :: Char -> Int -- | The <a>toEnum</a> method restricted to the type <a>Char</a>. chr :: Int -> Char -- | Convert a character to a string using only printable characters, using -- Haskell source-language escape conventions. For example: -- -- <pre> -- showLitChar '\n' s = "\\n" ++ s -- </pre> showLitChar :: Char -> ShowS -- | Read a string representation of a character, using Haskell -- source-language escape conventions. For example: -- -- <pre> -- lexLitChar "\\nHello" = [("\\n", "Hello")] -- </pre> lexLitChar :: ReadS String -- | Read a string representation of a character, using Haskell -- source-language escape conventions, and convert it to the character -- that it encodes. For example: -- -- <pre> -- readLitChar "\\nHello" = [('\n', "Hello")] -- </pre> readLitChar :: ReadS Char module Data.Int -- | A fixed-precision integer type with at least the range <tt>[-2^29 .. -- 2^29-1]</tt>. The exact range for a given implementation can be -- determined by using <a>minBound</a> and <a>maxBound</a> from the -- <a>Bounded</a> class. data Int :: * -- | 8-bit signed integer type data Int8 :: * -- | 16-bit signed integer type data Int16 :: * -- | 32-bit signed integer type data Int32 :: * -- | 64-bit signed integer type data Int64 :: * module Data.Ratio -- | Rational numbers, with numerator and denominator of some -- <a>Integral</a> type. data Ratio a :: * -> * -- | Arbitrary-precision rational numbers, represented as a ratio of two -- <a>Integer</a> values. A rational number may be constructed using the -- <a>%</a> operator. type Rational = Ratio Integer -- | Forms the ratio of two integral numbers. (%) :: Integral a => a -> a -> Ratio a -- | Extract the numerator of the ratio in reduced form: the numerator and -- denominator have no common factor and the denominator is positive. numerator :: Integral a => Ratio a -> a -- | Extract the denominator of the ratio in reduced form: the numerator -- and denominator have no common factor and the denominator is positive. denominator :: Integral a => Ratio a -> a -- | <a>approxRational</a>, applied to two real fractional numbers -- <tt>x</tt> and <tt>epsilon</tt>, returns the simplest rational number -- within <tt>epsilon</tt> of <tt>x</tt>. A rational number <tt>y</tt> is -- said to be <i>simpler</i> than another <tt>y'</tt> if -- -- <ul> -- <li><tt><a>abs</a> (<a>numerator</a> y) <= <a>abs</a> -- (<a>numerator</a> y')</tt>, and</li> -- <li><tt><a>denominator</a> y <= <a>denominator</a> y'</tt>.</li> -- </ul> -- -- Any real interval contains a unique simplest rational; in particular, -- note that <tt>0/1</tt> is the simplest rational of all. approxRational :: RealFrac a => a -> a -> Rational module Data.Word -- | A <a>Word</a> is an unsigned integral type, with the same size as -- <a>Int</a>. data Word :: * -- | 8-bit unsigned integer type data Word8 :: * -- | 16-bit unsigned integer type data Word16 :: * -- | 32-bit unsigned integer type data Word32 :: * -- | 64-bit unsigned integer type data Word64 :: * -- | The module <a>Foreign.Ptr</a> provides typed pointers to foreign -- entities. We distinguish two kinds of pointers: pointers to data and -- pointers to functions. It is understood that these two kinds of -- pointers may be represented differently as they may be references to -- data and text segments, respectively. module Foreign.Ptr -- | A value of type <tt><a>Ptr</a> a</tt> represents a pointer to an -- object, or an array of objects, which may be marshalled to or from -- Haskell values of type <tt>a</tt>. -- -- The type <tt>a</tt> will often be an instance of class <a>Storable</a> -- which provides the marshalling operations. However this is not -- essential, and you can provide your own operations to access the -- pointer. For example you might write small foreign functions to get or -- set the fields of a C <tt>struct</tt>. data Ptr a :: * -> * -- | The constant <a>nullPtr</a> contains a distinguished value of -- <a>Ptr</a> that is not associated with a valid memory location. nullPtr :: Ptr a -- | The <a>castPtr</a> function casts a pointer from one type to another. castPtr :: Ptr a -> Ptr b -- | Advances the given address by the given offset in bytes. plusPtr :: Ptr a -> Int -> Ptr b -- | Given an arbitrary address and an alignment constraint, -- <a>alignPtr</a> yields the next higher address that fulfills the -- alignment constraint. An alignment constraint <tt>x</tt> is fulfilled -- by any address divisible by <tt>x</tt>. This operation is idempotent. alignPtr :: Ptr a -> Int -> Ptr a -- | Computes the offset required to get from the second to the first -- argument. We have -- -- <pre> -- p2 == p1 `plusPtr` (p2 `minusPtr` p1) -- </pre> minusPtr :: Ptr a -> Ptr b -> Int -- | A value of type <tt><a>FunPtr</a> a</tt> is a pointer to a function -- callable from foreign code. The type <tt>a</tt> will normally be a -- <i>foreign type</i>, a function type with zero or more arguments where -- -- <ul> -- <li>the argument types are <i>marshallable foreign types</i>, i.e. -- <a>Char</a>, <a>Int</a>, <a>Double</a>, <a>Float</a>, <a>Bool</a>, -- <a>Int8</a>, <a>Int16</a>, <a>Int32</a>, <a>Int64</a>, <a>Word8</a>, -- <a>Word16</a>, <a>Word32</a>, <a>Word64</a>, <tt><a>Ptr</a> a</tt>, -- <tt><a>FunPtr</a> a</tt>, <tt><a>StablePtr</a> a</tt> or a renaming of -- any of these using <tt>newtype</tt>.</li> -- <li>the return type is either a marshallable foreign type or has the -- form <tt><a>IO</a> t</tt> where <tt>t</tt> is a marshallable foreign -- type or <tt>()</tt>.</li> -- </ul> -- -- A value of type <tt><a>FunPtr</a> a</tt> may be a pointer to a foreign -- function, either returned by another foreign function or imported with -- a a static address import like -- -- <pre> -- foreign import ccall "stdlib.h &free" -- p_free :: FunPtr (Ptr a -> IO ()) -- </pre> -- -- or a pointer to a Haskell function created using a <i>wrapper</i> stub -- declared to produce a <a>FunPtr</a> of the correct type. For example: -- -- <pre> -- type Compare = Int -> Int -> Bool -- foreign import ccall "wrapper" -- mkCompare :: Compare -> IO (FunPtr Compare) -- </pre> -- -- Calls to wrapper stubs like <tt>mkCompare</tt> allocate storage, which -- should be released with <a>freeHaskellFunPtr</a> when no longer -- required. -- -- To convert <a>FunPtr</a> values to corresponding Haskell functions, -- one can define a <i>dynamic</i> stub for the specific foreign type, -- e.g. -- -- <pre> -- type IntFunction = CInt -> IO () -- foreign import ccall "dynamic" -- mkFun :: FunPtr IntFunction -> IntFunction -- </pre> data FunPtr a :: * -> * -- | The constant <a>nullFunPtr</a> contains a distinguished value of -- <a>FunPtr</a> that is not associated with a valid memory location. nullFunPtr :: FunPtr a -- | Casts a <a>FunPtr</a> to a <a>FunPtr</a> of a different type. castFunPtr :: FunPtr a -> FunPtr b -- | Casts a <a>FunPtr</a> to a <a>Ptr</a>. -- -- <i>Note:</i> this is valid only on architectures where data and -- function pointers range over the same set of addresses, and should -- only be used for bindings to external libraries whose interface -- already relies on this assumption. castFunPtrToPtr :: FunPtr a -> Ptr b -- | Casts a <a>Ptr</a> to a <a>FunPtr</a>. -- -- <i>Note:</i> this is valid only on architectures where data and -- function pointers range over the same set of addresses, and should -- only be used for bindings to external libraries whose interface -- already relies on this assumption. castPtrToFunPtr :: Ptr a -> FunPtr b -- | Release the storage associated with the given <a>FunPtr</a>, which -- must have been obtained from a wrapper stub. This should be called -- whenever the return value from a foreign import wrapper function is no -- longer required; otherwise, the storage it uses will leak. freeHaskellFunPtr :: FunPtr a -> IO () -- | A signed integral type that can be losslessly converted to and from -- <tt>Ptr</tt>. This type is also compatible with the C99 type -- <tt>intptr_t</tt>, and can be marshalled to and from that type safely. data IntPtr :: * -- | casts a <tt>Ptr</tt> to an <tt>IntPtr</tt> ptrToIntPtr :: Ptr a -> IntPtr -- | casts an <tt>IntPtr</tt> to a <tt>Ptr</tt> intPtrToPtr :: IntPtr -> Ptr a -- | An unsigned integral type that can be losslessly converted to and from -- <tt>Ptr</tt>. This type is also compatible with the C99 type -- <tt>uintptr_t</tt>, and can be marshalled to and from that type -- safely. data WordPtr :: * -- | casts a <tt>Ptr</tt> to a <tt>WordPtr</tt> ptrToWordPtr :: Ptr a -> WordPtr -- | casts a <tt>WordPtr</tt> to a <tt>Ptr</tt> wordPtrToPtr :: WordPtr -> Ptr a module Data.Maybe -- | The <a>Maybe</a> type encapsulates an optional value. A value of type -- <tt><a>Maybe</a> a</tt> either contains a value of type <tt>a</tt> -- (represented as <tt><a>Just</a> a</tt>), or it is empty (represented -- as <a>Nothing</a>). Using <a>Maybe</a> is a good way to deal with -- errors or exceptional cases without resorting to drastic measures such -- as <a>error</a>. -- -- The <a>Maybe</a> type is also a monad. It is a simple kind of error -- monad, where all errors are represented by <a>Nothing</a>. A richer -- error monad can be built using the <a>Either</a> type. data Maybe a :: * -> * Nothing :: Maybe a Just :: a -> Maybe a -- | The <a>maybe</a> function takes a default value, a function, and a -- <a>Maybe</a> value. If the <a>Maybe</a> value is <a>Nothing</a>, the -- function returns the default value. Otherwise, it applies the function -- to the value inside the <a>Just</a> and returns the result. maybe :: b -> (a -> b) -> Maybe a -> b -- | The <a>isJust</a> function returns <a>True</a> iff its argument is of -- the form <tt>Just _</tt>. isJust :: Maybe a -> Bool -- | The <a>isNothing</a> function returns <a>True</a> iff its argument is -- <a>Nothing</a>. isNothing :: Maybe a -> Bool -- | The <a>fromJust</a> function extracts the element out of a <a>Just</a> -- and throws an error if its argument is <a>Nothing</a>. fromJust :: Maybe a -> a -- | The <a>fromMaybe</a> function takes a default value and and -- <a>Maybe</a> value. If the <a>Maybe</a> is <a>Nothing</a>, it returns -- the default values; otherwise, it returns the value contained in the -- <a>Maybe</a>. fromMaybe :: a -> Maybe a -> a -- | The <a>listToMaybe</a> function returns <a>Nothing</a> on an empty -- list or <tt><a>Just</a> a</tt> where <tt>a</tt> is the first element -- of the list. listToMaybe :: [a] -> Maybe a -- | The <a>maybeToList</a> function returns an empty list when given -- <a>Nothing</a> or a singleton list when not given <a>Nothing</a>. maybeToList :: Maybe a -> [a] -- | The <a>catMaybes</a> function takes a list of <a>Maybe</a>s and -- returns a list of all the <a>Just</a> values. catMaybes :: [Maybe a] -> [a] -- | The <a>mapMaybe</a> function is a version of <a>map</a> which can -- throw out elements. In particular, the functional argument returns -- something of type <tt><a>Maybe</a> b</tt>. If this is <a>Nothing</a>, -- no element is added on to the result list. If it just <tt><a>Just</a> -- b</tt>, then <tt>b</tt> is included in the result list. mapMaybe :: (a -> Maybe b) -> [a] -> [b] module Numeric -- | Converts a possibly-negative <a>Real</a> value to a string. showSigned :: Real a => (a -> ShowS) -> Int -> a -> ShowS -- | Shows a <i>non-negative</i> <a>Integral</a> number using the base -- specified by the first argument, and the character representation -- specified by the second. showIntAtBase :: (Integral a, Show a) => a -> (Int -> Char) -> a -> ShowS -- | Show <i>non-negative</i> <a>Integral</a> numbers in base 10. showInt :: Integral a => a -> ShowS -- | Show <i>non-negative</i> <a>Integral</a> numbers in base 16. showHex :: (Integral a, Show a) => a -> ShowS -- | Show <i>non-negative</i> <a>Integral</a> numbers in base 8. showOct :: (Integral a, Show a) => a -> ShowS -- | Show a signed <a>RealFloat</a> value using scientific (exponential) -- notation (e.g. <tt>2.45e2</tt>, <tt>1.5e-3</tt>). -- -- In the call <tt><a>showEFloat</a> digs val</tt>, if <tt>digs</tt> is -- <a>Nothing</a>, the value is shown to full precision; if <tt>digs</tt> -- is <tt><a>Just</a> d</tt>, then at most <tt>d</tt> digits after the -- decimal point are shown. showEFloat :: RealFloat a => Maybe Int -> a -> ShowS -- | Show a signed <a>RealFloat</a> value using standard decimal notation -- (e.g. <tt>245000</tt>, <tt>0.0015</tt>). -- -- In the call <tt><a>showFFloat</a> digs val</tt>, if <tt>digs</tt> is -- <a>Nothing</a>, the value is shown to full precision; if <tt>digs</tt> -- is <tt><a>Just</a> d</tt>, then at most <tt>d</tt> digits after the -- decimal point are shown. showFFloat :: RealFloat a => Maybe Int -> a -> ShowS -- | Show a signed <a>RealFloat</a> value using standard decimal notation -- for arguments whose absolute value lies between <tt>0.1</tt> and -- <tt>9,999,999</tt>, and scientific notation otherwise. -- -- In the call <tt><a>showGFloat</a> digs val</tt>, if <tt>digs</tt> is -- <a>Nothing</a>, the value is shown to full precision; if <tt>digs</tt> -- is <tt><a>Just</a> d</tt>, then at most <tt>d</tt> digits after the -- decimal point are shown. showGFloat :: RealFloat a => Maybe Int -> a -> ShowS -- | Show a signed <a>RealFloat</a> value to full precision using standard -- decimal notation for arguments whose absolute value lies between -- <tt>0.1</tt> and <tt>9,999,999</tt>, and scientific notation -- otherwise. showFloat :: RealFloat a => a -> ShowS -- | <a>floatToDigits</a> takes a base and a non-negative <a>RealFloat</a> -- number, and returns a list of digits and an exponent. In particular, -- if <tt>x>=0</tt>, and -- -- <pre> -- floatToDigits base x = ([d1,d2,...,dn], e) -- </pre> -- -- then -- -- <ol> -- <li><pre>n >= 1</pre></li> -- <li><pre>x = 0.d1d2...dn * (base**e)</pre></li> -- <li><pre>0 <= di <= base-1</pre></li> -- </ol> floatToDigits :: RealFloat a => Integer -> a -> ([Int], Int) -- | Reads a <i>signed</i> <a>Real</a> value, given a reader for an -- unsigned value. readSigned :: Real a => ReadS a -> ReadS a -- | Reads an <i>unsigned</i> <a>Integral</a> value in an arbitrary base. readInt :: Num a => a -> (Char -> Bool) -> (Char -> Int) -> ReadS a -- | Read an unsigned number in decimal notation. readDec :: (Eq a, Num a) => ReadS a -- | Read an unsigned number in octal notation. readOct :: (Eq a, Num a) => ReadS a -- | Read an unsigned number in hexadecimal notation. Both upper or lower -- case letters are allowed. readHex :: (Eq a, Num a) => ReadS a -- | Reads an <i>unsigned</i> <a>RealFrac</a> value, expressed in decimal -- scientific notation. readFloat :: RealFrac a => ReadS a -- | Reads a non-empty string of decimal digits. lexDigits :: ReadS String -- | Converts a <a>Rational</a> value into any type in class -- <a>RealFloat</a>. fromRat :: RealFloat a => Rational -> a module System.IO.Error -- | Errors of type <a>IOError</a> are used by the <a>IO</a> monad. This is -- an abstract type; the module <a>System.IO.Error</a> provides functions -- to interrogate and construct values of type <a>IOError</a>. type IOError = IOError -- | Construct an <a>IOError</a> value with a string describing the error. -- The <a>fail</a> method of the <a>IO</a> instance of the <a>Monad</a> -- class raises a <a>userError</a>, thus: -- -- <pre> -- instance Monad IO where -- ... -- fail s = ioError (userError s) -- </pre> userError :: String -> IOError -- | Construct an <a>IOError</a> of the given type where the second -- argument describes the error location and the third and fourth -- argument contain the file handle and file path of the file involved in -- the error if applicable. mkIOError :: IOErrorType -> String -> Maybe Handle -> Maybe FilePath -> IOError -- | Adds a location description and maybe a file path and file handle to -- an <a>IOError</a>. If any of the file handle or file path is not given -- the corresponding value in the <a>IOError</a> remains unaltered. annotateIOError :: IOError -> String -> Maybe Handle -> Maybe FilePath -> IOError -- | An error indicating that an <a>IO</a> operation failed because one of -- its arguments already exists. isAlreadyExistsError :: IOError -> Bool -- | An error indicating that an <a>IO</a> operation failed because one of -- its arguments does not exist. isDoesNotExistError :: IOError -> Bool -- | An error indicating that an <a>IO</a> operation failed because one of -- its arguments is a single-use resource, which is already being used -- (for example, opening the same file twice for writing might give this -- error). isAlreadyInUseError :: IOError -> Bool -- | An error indicating that an <a>IO</a> operation failed because the -- device is full. isFullError :: IOError -> Bool -- | An error indicating that an <a>IO</a> operation failed because the end -- of file has been reached. isEOFError :: IOError -> Bool -- | An error indicating that an <a>IO</a> operation failed because the -- operation was not possible. Any computation which returns an <a>IO</a> -- result may fail with <a>isIllegalOperation</a>. In some cases, an -- implementation will not be able to distinguish between the possible -- error causes. In this case it should fail with -- <a>isIllegalOperation</a>. isIllegalOperation :: IOError -> Bool -- | An error indicating that an <a>IO</a> operation failed because the -- user does not have sufficient operating system privilege to perform -- that operation. isPermissionError :: IOError -> Bool -- | A programmer-defined error value constructed using <a>userError</a>. isUserError :: IOError -> Bool ioeGetErrorString :: IOError -> String ioeGetHandle :: IOError -> Maybe Handle ioeGetFileName :: IOError -> Maybe FilePath -- | An abstract type that contains a value for each variant of -- <a>IOError</a>. data IOErrorType :: * -- | I/O error where the operation failed because one of its arguments -- already exists. alreadyExistsErrorType :: IOErrorType -- | I/O error where the operation failed because one of its arguments does -- not exist. doesNotExistErrorType :: IOErrorType -- | I/O error where the operation failed because one of its arguments is a -- single-use resource, which is already being used. alreadyInUseErrorType :: IOErrorType -- | I/O error where the operation failed because the device is full. fullErrorType :: IOErrorType -- | I/O error where the operation failed because the end of file has been -- reached. eofErrorType :: IOErrorType -- | I/O error where the operation is not possible. illegalOperationErrorType :: IOErrorType -- | I/O error where the operation failed because the user does not have -- sufficient operating system privilege to perform that operation. permissionErrorType :: IOErrorType -- | I/O error that is programmer-defined. userErrorType :: IOErrorType -- | Raise an <a>IOError</a> in the <a>IO</a> monad. ioError :: IOError -> IO a -- | The <a>catch</a> function establishes a handler that receives any -- <a>IOError</a> raised in the action protected by <a>catch</a>. An -- <a>IOError</a> is caught by the most recent handler established by -- <a>catch</a>. These handlers are not selective: all <a>IOError</a>s -- are caught. Exception propagation must be explicitly provided in a -- handler by re-raising any unwanted exceptions. For example, in -- -- <pre> -- f = catch g (\e -> if IO.isEOFError e then return [] else ioError e) -- </pre> -- -- the function <tt>f</tt> returns <tt>[]</tt> when an end-of-file -- exception (cf. <a>isEOFError</a>) occurs in <tt>g</tt>; otherwise, the -- exception is propagated to the next outer handler. -- -- When an exception propagates outside the main program, the Haskell -- system prints the associated <a>IOError</a> value and exits the -- program. catch :: IO a -> (IOError -> IO a) -> IO a -- | The construct <a>try</a> <tt>comp</tt> exposes IO errors which occur -- within a computation, and which are not fully handled. try :: IO a -> IO (Either IOError a) -- | This module defines bitwise operations for signed and unsigned -- integers. module Data.Bits -- | The <a>Bits</a> class defines bitwise operations over integral types. -- -- <ul> -- <li>Bits are numbered from 0 with bit 0 being the least significant -- bit.</li> -- </ul> -- -- Minimal complete definition: <a>.&.</a>, <a>.|.</a>, <a>xor</a>, -- <a>complement</a>, (<a>shift</a> or (<a>shiftL</a> and -- <a>shiftR</a>)), (<a>rotate</a> or (<a>rotateL</a> and -- <a>rotateR</a>)), <a>bitSize</a> and <a>isSigned</a>. class (Eq a, Num a) => Bits a (.&.) :: Bits a => a -> a -> a (.|.) :: Bits a => a -> a -> a xor :: Bits a => a -> a -> a complement :: Bits a => a -> a shift :: Bits a => a -> Int -> a rotate :: Bits a => a -> Int -> a bit :: Bits a => Int -> a setBit :: Bits a => a -> Int -> a clearBit :: Bits a => a -> Int -> a complementBit :: Bits a => a -> Int -> a testBit :: Bits a => a -> Int -> Bool bitSize :: Bits a => a -> Int isSigned :: Bits a => a -> Bool shiftL :: Bits a => a -> Int -> a shiftR :: Bits a => a -> Int -> a rotateL :: Bits a => a -> Int -> a rotateR :: Bits a => a -> Int -> a module Foreign.Storable -- | The member functions of this class facilitate writing values of -- primitive types to raw memory (which may have been allocated with the -- above mentioned routines) and reading values from blocks of raw -- memory. The class, furthermore, includes support for computing the -- storage requirements and alignment restrictions of storable types. -- -- Memory addresses are represented as values of type <tt><a>Ptr</a> -- a</tt>, for some <tt>a</tt> which is an instance of class -- <a>Storable</a>. The type argument to <a>Ptr</a> helps provide some -- valuable type safety in FFI code (you can't mix pointers of different -- types without an explicit cast), while helping the Haskell type system -- figure out which marshalling method is needed for a given pointer. -- -- All marshalling between Haskell and a foreign language ultimately -- boils down to translating Haskell data structures into the binary -- representation of a corresponding data structure of the foreign -- language and vice versa. To code this marshalling in Haskell, it is -- necessary to manipulate primitive data types stored in unstructured -- memory blocks. The class <a>Storable</a> facilitates this manipulation -- on all types for which it is instantiated, which are the standard -- basic types of Haskell, the fixed size <tt>Int</tt> types -- (<a>Int8</a>, <a>Int16</a>, <a>Int32</a>, <a>Int64</a>), the fixed -- size <tt>Word</tt> types (<a>Word8</a>, <a>Word16</a>, <a>Word32</a>, -- <a>Word64</a>), <a>StablePtr</a>, all types from -- <a>Foreign.C.Types</a>, as well as <a>Ptr</a>. -- -- Minimal complete definition: <a>sizeOf</a>, <a>alignment</a>, one of -- <a>peek</a>, <a>peekElemOff</a> and <a>peekByteOff</a>, and one of -- <a>poke</a>, <a>pokeElemOff</a> and <a>pokeByteOff</a>. class Storable a sizeOf :: Storable a => a -> Int alignment :: Storable a => a -> Int peekElemOff :: Storable a => Ptr a -> Int -> IO a pokeElemOff :: Storable a => Ptr a -> Int -> a -> IO () peekByteOff :: Storable a => Ptr b -> Int -> IO a pokeByteOff :: Storable a => Ptr b -> Int -> a -> IO () peek :: Storable a => Ptr a -> IO a poke :: Storable a => Ptr a -> a -> IO () module Foreign.C.Types -- | Haskell type representing the C <tt>char</tt> type. data CChar :: * -- | Haskell type representing the C <tt>signed char</tt> type. data CSChar :: * -- | Haskell type representing the C <tt>unsigned char</tt> type. data CUChar :: * -- | Haskell type representing the C <tt>short</tt> type. data CShort :: * -- | Haskell type representing the C <tt>unsigned short</tt> type. data CUShort :: * -- | Haskell type representing the C <tt>int</tt> type. data CInt :: * -- | Haskell type representing the C <tt>unsigned int</tt> type. data CUInt :: * -- | Haskell type representing the C <tt>long</tt> type. data CLong :: * -- | Haskell type representing the C <tt>unsigned long</tt> type. data CULong :: * -- | Haskell type representing the C <tt>ptrdiff_t</tt> type. data CPtrdiff :: * -- | Haskell type representing the C <tt>size_t</tt> type. data CSize :: * -- | Haskell type representing the C <tt>wchar_t</tt> type. data CWchar :: * -- | Haskell type representing the C <tt>sig_atomic_t</tt> type. data CSigAtomic :: * -- | Haskell type representing the C <tt>long long</tt> type. data CLLong :: * -- | Haskell type representing the C <tt>unsigned long long</tt> type. data CULLong :: * data CIntPtr :: * data CUIntPtr :: * data CIntMax :: * data CUIntMax :: * -- | Haskell type representing the C <tt>clock_t</tt> type. data CClock :: * -- | Haskell type representing the C <tt>time_t</tt> type. data CTime :: * -- | Haskell type representing the C <tt>float</tt> type. data CFloat :: * -- | Haskell type representing the C <tt>double</tt> type. data CDouble :: * -- | Haskell type representing the C <tt>FILE</tt> type. data CFile :: * -- | Haskell type representing the C <tt>fpos_t</tt> type. data CFpos :: * -- | Haskell type representing the C <tt>jmp_buf</tt> type. data CJmpBuf :: * module System.Exit -- | Defines the exit codes that a program can return. data ExitCode :: * -- | indicates successful termination; ExitSuccess :: ExitCode -- | indicates program failure with an exit code. The exact interpretation -- of the code is operating-system dependent. In particular, some values -- may be prohibited (e.g. 0 on a POSIX-compliant system). ExitFailure :: Int -> ExitCode -- | Computation <tt><a>exitWith</a> code</tt> terminates the program, -- returning <tt>code</tt> to the program's caller. The caller may -- interpret the return code as it wishes, but the program should return -- <a>ExitSuccess</a> to mean normal completion, and -- <tt><a>ExitFailure</a> n</tt> to mean that the program encountered a -- problem from which it could not recover. The value <a>exitFailure</a> -- is equal to <tt><a>exitWith</a> (<a>ExitFailure</a> exitfail)</tt>, -- where <tt>exitfail</tt> is implementation-dependent. <a>exitWith</a> -- bypasses the error handling in the I/O monad and cannot be intercepted -- by <a>catch</a> from the <tt>Prelude</tt>. exitWith :: ExitCode -> IO a -- | The computation <a>exitFailure</a> is equivalent to <a>exitWith</a> -- <tt>(</tt><a>ExitFailure</a> <i>exitfail</i><tt>)</tt>, where -- <i>exitfail</i> is implementation-dependent. exitFailure :: IO a -- | The computation <a>exitSuccess</a> is equivalent to <a>exitWith</a> -- <a>ExitSuccess</a>, It terminates the program successfully. exitSuccess :: IO a -- | The module <a>Foreign.Marshal.Alloc</a> provides operations to -- allocate and deallocate blocks of raw memory (i.e., unstructured -- chunks of memory outside of the area maintained by the Haskell storage -- manager). These memory blocks are commonly used to pass compound data -- structures to foreign functions or to provide space in which compound -- result values are obtained from foreign functions. -- -- If any of the allocation functions fails, a value of <tt>nullPtr</tt> -- is produced. If <a>free</a> or <a>reallocBytes</a> is applied to a -- memory area that has been allocated with <a>alloca</a> or -- <a>allocaBytes</a>, the behaviour is undefined. Any further access to -- memory areas allocated with <a>alloca</a> or <a>allocaBytes</a>, after -- the computation that was passed to the allocation function has -- terminated, leads to undefined behaviour. Any further access to the -- memory area referenced by a pointer passed to <a>realloc</a>, -- <a>reallocBytes</a>, or <a>free</a> entails undefined behaviour. -- -- All storage allocated by functions that allocate based on a <i>size in -- bytes</i> must be sufficiently aligned for any of the basic foreign -- types that fits into the newly allocated storage. All storage -- allocated by functions that allocate based on a specific type must be -- sufficiently aligned for that type. Array allocation routines need to -- obey the same alignment constraints for each array element. module Foreign.Marshal.Alloc -- | <tt><a>alloca</a> f</tt> executes the computation <tt>f</tt>, passing -- as argument a pointer to a temporarily allocated block of memory -- sufficient to hold values of type <tt>a</tt>. -- -- The memory is freed when <tt>f</tt> terminates (either normally or via -- an exception), so the pointer passed to <tt>f</tt> must <i>not</i> be -- used after this. alloca :: Storable a => (Ptr a -> IO b) -> IO b -- | <tt><a>allocaBytes</a> n f</tt> executes the computation <tt>f</tt>, -- passing as argument a pointer to a temporarily allocated block of -- memory of <tt>n</tt> bytes. The block of memory is sufficiently -- aligned for any of the basic foreign types that fits into a memory -- block of the allocated size. -- -- The memory is freed when <tt>f</tt> terminates (either normally or via -- an exception), so the pointer passed to <tt>f</tt> must <i>not</i> be -- used after this. allocaBytes :: Int -> (Ptr a -> IO b) -> IO b -- | Allocate a block of memory that is sufficient to hold values of type -- <tt>a</tt>. The size of the area allocated is determined by the -- <a>sizeOf</a> method from the instance of <a>Storable</a> for the -- appropriate type. -- -- The memory may be deallocated using <a>free</a> or -- <a>finalizerFree</a> when no longer required. malloc :: Storable a => IO (Ptr a) -- | Allocate a block of memory of the given number of bytes. The block of -- memory is sufficiently aligned for any of the basic foreign types that -- fits into a memory block of the allocated size. -- -- The memory may be deallocated using <a>free</a> or -- <a>finalizerFree</a> when no longer required. mallocBytes :: Int -> IO (Ptr a) -- | Resize a memory area that was allocated with <a>malloc</a> or -- <a>mallocBytes</a> to the size needed to store values of type -- <tt>b</tt>. The returned pointer may refer to an entirely different -- memory area, but will be suitably aligned to hold values of type -- <tt>b</tt>. The contents of the referenced memory area will be the -- same as of the original pointer up to the minimum of the original size -- and the size of values of type <tt>b</tt>. -- -- If the argument to <a>realloc</a> is <a>nullPtr</a>, <a>realloc</a> -- behaves like <a>malloc</a>. realloc :: Storable b => Ptr a -> IO (Ptr b) -- | Resize a memory area that was allocated with <a>malloc</a> or -- <a>mallocBytes</a> to the given size. The returned pointer may refer -- to an entirely different memory area, but will be sufficiently aligned -- for any of the basic foreign types that fits into a memory block of -- the given size. The contents of the referenced memory area will be the -- same as of the original pointer up to the minimum of the original size -- and the given size. -- -- If the pointer argument to <a>reallocBytes</a> is <a>nullPtr</a>, -- <a>reallocBytes</a> behaves like <a>malloc</a>. If the requested size -- is 0, <a>reallocBytes</a> behaves like <a>free</a>. reallocBytes :: Ptr a -> Int -> IO (Ptr a) -- | Free a block of memory that was allocated with <a>malloc</a>, -- <a>mallocBytes</a>, <a>realloc</a>, <a>reallocBytes</a>, <a>new</a> or -- any of the <tt>new</tt><i>X</i> functions in -- <a>Foreign.Marshal.Array</a> or <a>Foreign.C.String</a>. free :: Ptr a -> IO () -- | A pointer to a foreign function equivalent to <a>free</a>, which may -- be used as a finalizer (cf <a>ForeignPtr</a>) for storage allocated -- with <a>malloc</a>, <a>mallocBytes</a>, <a>realloc</a> or -- <a>reallocBytes</a>. finalizerFree :: FinalizerPtr a module Foreign.Marshal.Error -- | Execute an <a>IO</a> action, throwing a <a>userError</a> if the -- predicate yields <a>True</a> when applied to the result returned by -- the <a>IO</a> action. If no exception is raised, return the result of -- the computation. throwIf :: (a -> Bool) -> (a -> String) -> IO a -> IO a -- | Like <a>throwIf</a>, but discarding the result throwIf_ :: (a -> Bool) -> (a -> String) -> IO a -> IO () -- | Guards against negative result values throwIfNeg :: (Ord a, Num a) => (a -> String) -> IO a -> IO a -- | Like <a>throwIfNeg</a>, but discarding the result throwIfNeg_ :: (Ord a, Num a) => (a -> String) -> IO a -> IO () -- | Guards against null pointers throwIfNull :: String -> IO (Ptr a) -> IO (Ptr a) -- | Discard the return value of an <a>IO</a> action void :: IO a -> IO () module Foreign.Marshal.Utils -- | <tt><a>with</a> val f</tt> executes the computation <tt>f</tt>, -- passing as argument a pointer to a temporarily allocated block of -- memory into which <tt>val</tt> has been marshalled (the combination of -- <a>alloca</a> and <a>poke</a>). -- -- The memory is freed when <tt>f</tt> terminates (either normally or via -- an exception), so the pointer passed to <tt>f</tt> must <i>not</i> be -- used after this. with :: Storable a => a -> (Ptr a -> IO b) -> IO b -- | Allocate a block of memory and marshal a value into it (the -- combination of <a>malloc</a> and <a>poke</a>). The size of the area -- allocated is determined by the <a>sizeOf</a> method from the instance -- of <a>Storable</a> for the appropriate type. -- -- The memory may be deallocated using <a>free</a> or -- <a>finalizerFree</a> when no longer required. new :: Storable a => a -> IO (Ptr a) -- | Convert a Haskell <a>Bool</a> to its numeric representation fromBool :: Num a => Bool -> a -- | Convert a Boolean in numeric representation to a Haskell value toBool :: (Eq a, Num a) => a -> Bool -- | Allocate storage and marshal a storable value wrapped into a -- <a>Maybe</a> -- -- <ul> -- <li>the <a>nullPtr</a> is used to represent <a>Nothing</a></li> -- </ul> maybeNew :: (a -> IO (Ptr b)) -> Maybe a -> IO (Ptr b) -- | Converts a <tt>withXXX</tt> combinator into one marshalling a value -- wrapped into a <a>Maybe</a>, using <a>nullPtr</a> to represent -- <a>Nothing</a>. maybeWith :: (a -> (Ptr b -> IO c) -> IO c) -> Maybe a -> (Ptr b -> IO c) -> IO c -- | Convert a peek combinator into a one returning <a>Nothing</a> if -- applied to a <a>nullPtr</a> maybePeek :: (Ptr a -> IO b) -> Ptr a -> IO (Maybe b) -- | Replicates a <tt>withXXX</tt> combinator over a list of objects, -- yielding a list of marshalled objects withMany :: (a -> (b -> res) -> res) -> [a] -> ([b] -> res) -> res -- | Copies the given number of bytes from the second area (source) into -- the first (destination); the copied areas may <i>not</i> overlap copyBytes :: Ptr a -> Ptr a -> Int -> IO () -- | Copies the given number of bytes from the second area (source) into -- the first (destination); the copied areas <i>may</i> overlap moveBytes :: Ptr a -> Ptr a -> Int -> IO () -- | The module <a>Foreign.Marshal.Array</a> provides operations for -- marshalling Haskell lists into monolithic arrays and vice versa. Most -- functions come in two flavours: one for arrays terminated by a special -- termination element and one where an explicit length parameter is used -- to determine the extent of an array. The typical example for the -- former case are C's NUL terminated strings. However, please note that -- C strings should usually be marshalled using the functions provided by -- <a>Foreign.C.String</a> as the Unicode encoding has to be taken into -- account. All functions specifically operating on arrays that are -- terminated by a special termination element have a name ending on -- <tt>0</tt>---e.g., <a>mallocArray</a> allocates space for an array of -- the given size, whereas <a>mallocArray0</a> allocates space for one -- more element to ensure that there is room for the terminator. module Foreign.Marshal.Array -- | Allocate storage for the given number of elements of a storable type -- (like <a>malloc</a>, but for multiple elements). mallocArray :: Storable a => Int -> IO (Ptr a) -- | Like <a>mallocArray</a>, but add an extra position to hold a special -- termination element. mallocArray0 :: Storable a => Int -> IO (Ptr a) -- | Temporarily allocate space for the given number of elements (like -- <a>alloca</a>, but for multiple elements). allocaArray :: Storable a => Int -> (Ptr a -> IO b) -> IO b -- | Like <a>allocaArray</a>, but add an extra position to hold a special -- termination element. allocaArray0 :: Storable a => Int -> (Ptr a -> IO b) -> IO b -- | Adjust the size of an array reallocArray :: Storable a => Ptr a -> Int -> IO (Ptr a) -- | Adjust the size of an array including an extra position for the end -- marker. reallocArray0 :: Storable a => Ptr a -> Int -> IO (Ptr a) -- | Convert an array of given length into a Haskell list. peekArray :: Storable a => Int -> Ptr a -> IO [a] -- | Convert an array terminated by the given end marker into a Haskell -- list peekArray0 :: (Storable a, Eq a) => a -> Ptr a -> IO [a] -- | Write the list elements consecutive into memory pokeArray :: Storable a => Ptr a -> [a] -> IO () -- | Write the list elements consecutive into memory and terminate them -- with the given marker element pokeArray0 :: Storable a => a -> Ptr a -> [a] -> IO () -- | Write a list of storable elements into a newly allocated, consecutive -- sequence of storable values (like <a>new</a>, but for multiple -- elements). newArray :: Storable a => [a] -> IO (Ptr a) -- | Write a list of storable elements into a newly allocated, consecutive -- sequence of storable values, where the end is fixed by the given end -- marker newArray0 :: Storable a => a -> [a] -> IO (Ptr a) -- | Temporarily store a list of storable values in memory (like -- <a>with</a>, but for multiple elements). withArray :: Storable a => [a] -> (Ptr a -> IO b) -> IO b -- | Like <a>withArray</a>, but a terminator indicates where the array ends withArray0 :: Storable a => a -> [a] -> (Ptr a -> IO b) -> IO b -- | Like <a>withArray</a>, but the action gets the number of values as an -- additional parameter withArrayLen :: Storable a => [a] -> (Int -> Ptr a -> IO b) -> IO b -- | Like <a>withArrayLen</a>, but a terminator indicates where the array -- ends withArrayLen0 :: Storable a => a -> [a] -> (Int -> Ptr a -> IO b) -> IO b -- | Copy the given number of elements from the second array (source) into -- the first array (destination); the copied areas may <i>not</i> overlap copyArray :: Storable a => Ptr a -> Ptr a -> Int -> IO () -- | Copy the given number of elements from the second array (source) into -- the first array (destination); the copied areas <i>may</i> overlap moveArray :: Storable a => Ptr a -> Ptr a -> Int -> IO () -- | Return the number of elements in an array, excluding the terminator lengthArray0 :: (Storable a, Eq a) => a -> Ptr a -> IO Int -- | Advance a pointer into an array by the given number of elements advancePtr :: Storable a => Ptr a -> Int -> Ptr a -- | Utilities for primitive marshalling of C strings. -- -- The marshalling converts each Haskell character, representing a -- Unicode code point, to one or more bytes in a manner that, by default, -- is determined by the current locale. As a consequence, no guarantees -- can be made about the relative length of a Haskell string and its -- corresponding C string, and therefore all the marshalling routines -- include memory allocation. The translation between Unicode and the -- encoding of the current locale may be lossy. module Foreign.C.String -- | A C string is a reference to an array of C characters terminated by -- NUL. type CString = Ptr CChar -- | A string with explicit length information in bytes instead of a -- terminating NUL (allowing NUL characters in the middle of the string). type CStringLen = (Ptr CChar, Int) -- | Marshal a NUL terminated C string into a Haskell string. peekCString :: CString -> IO String -- | Marshal a C string with explicit length into a Haskell string. peekCStringLen :: CStringLen -> IO String -- | Marshal a Haskell string into a NUL terminated C string. -- -- <ul> -- <li>the Haskell string may <i>not</i> contain any NUL characters</li> -- <li>new storage is allocated for the C string and must be explicitly -- freed using <a>free</a> or <a>finalizerFree</a>.</li> -- </ul> newCString :: String -> IO CString -- | Marshal a Haskell string into a C string (ie, character array) with -- explicit length information. -- -- <ul> -- <li>new storage is allocated for the C string and must be explicitly -- freed using <a>free</a> or <a>finalizerFree</a>.</li> -- </ul> newCStringLen :: String -> IO CStringLen -- | Marshal a Haskell string into a NUL terminated C string using -- temporary storage. -- -- <ul> -- <li>the Haskell string may <i>not</i> contain any NUL characters</li> -- <li>the memory is freed when the subcomputation terminates (either -- normally or via an exception), so the pointer to the temporary storage -- must <i>not</i> be used after this.</li> -- </ul> withCString :: String -> (CString -> IO a) -> IO a -- | Marshal a Haskell string into a C string (ie, character array) in -- temporary storage, with explicit length information. -- -- <ul> -- <li>the memory is freed when the subcomputation terminates (either -- normally or via an exception), so the pointer to the temporary storage -- must <i>not</i> be used after this.</li> -- </ul> withCStringLen :: String -> (CStringLen -> IO a) -> IO a charIsRepresentable :: Char -> IO Bool -- | Convert a Haskell character to a C character. This function is only -- safe on the first 256 characters. castCharToCChar :: Char -> CChar -- | Convert a C byte, representing a Latin-1 character, to the -- corresponding Haskell character. castCCharToChar :: CChar -> Char -- | Convert a Haskell character to a C <tt>unsigned char</tt>. This -- function is only safe on the first 256 characters. castCharToCUChar :: Char -> CUChar -- | Convert a C <tt>unsigned char</tt>, representing a Latin-1 character, -- to the corresponding Haskell character. castCUCharToChar :: CUChar -> Char -- | Convert a Haskell character to a C <tt>signed char</tt>. This function -- is only safe on the first 256 characters. castCharToCSChar :: Char -> CSChar -- | Convert a C <tt>signed char</tt>, representing a Latin-1 character, to -- the corresponding Haskell character. castCSCharToChar :: CSChar -> Char -- | Marshal a NUL terminated C string into a Haskell string. peekCAString :: CString -> IO String -- | Marshal a C string with explicit length into a Haskell string. peekCAStringLen :: CStringLen -> IO String -- | Marshal a Haskell string into a NUL terminated C string. -- -- <ul> -- <li>the Haskell string may <i>not</i> contain any NUL characters</li> -- <li>new storage is allocated for the C string and must be explicitly -- freed using <a>free</a> or <a>finalizerFree</a>.</li> -- </ul> newCAString :: String -> IO CString -- | Marshal a Haskell string into a C string (ie, character array) with -- explicit length information. -- -- <ul> -- <li>new storage is allocated for the C string and must be explicitly -- freed using <a>free</a> or <a>finalizerFree</a>.</li> -- </ul> newCAStringLen :: String -> IO CStringLen -- | Marshal a Haskell string into a NUL terminated C string using -- temporary storage. -- -- <ul> -- <li>the Haskell string may <i>not</i> contain any NUL characters</li> -- <li>the memory is freed when the subcomputation terminates (either -- normally or via an exception), so the pointer to the temporary storage -- must <i>not</i> be used after this.</li> -- </ul> withCAString :: String -> (CString -> IO a) -> IO a -- | Marshal a Haskell string into a C string (ie, character array) in -- temporary storage, with explicit length information. -- -- <ul> -- <li>the memory is freed when the subcomputation terminates (either -- normally or via an exception), so the pointer to the temporary storage -- must <i>not</i> be used after this.</li> -- </ul> withCAStringLen :: String -> (CStringLen -> IO a) -> IO a -- | A C wide string is a reference to an array of C wide characters -- terminated by NUL. type CWString = Ptr CWchar -- | A wide character string with explicit length information in -- <a>CWchar</a>s instead of a terminating NUL (allowing NUL characters -- in the middle of the string). type CWStringLen = (Ptr CWchar, Int) -- | Marshal a NUL terminated C wide string into a Haskell string. peekCWString :: CWString -> IO String -- | Marshal a C wide string with explicit length into a Haskell string. peekCWStringLen :: CWStringLen -> IO String -- | Marshal a Haskell string into a NUL terminated C wide string. -- -- <ul> -- <li>the Haskell string may <i>not</i> contain any NUL characters</li> -- <li>new storage is allocated for the C wide string and must be -- explicitly freed using <a>free</a> or <a>finalizerFree</a>.</li> -- </ul> newCWString :: String -> IO CWString -- | Marshal a Haskell string into a C wide string (ie, wide character -- array) with explicit length information. -- -- <ul> -- <li>new storage is allocated for the C wide string and must be -- explicitly freed using <a>free</a> or <a>finalizerFree</a>.</li> -- </ul> newCWStringLen :: String -> IO CWStringLen -- | Marshal a Haskell string into a NUL terminated C wide string using -- temporary storage. -- -- <ul> -- <li>the Haskell string may <i>not</i> contain any NUL characters</li> -- <li>the memory is freed when the subcomputation terminates (either -- normally or via an exception), so the pointer to the temporary storage -- must <i>not</i> be used after this.</li> -- </ul> withCWString :: String -> (CWString -> IO a) -> IO a -- | Marshal a Haskell string into a C wide string (i.e. wide character -- array) in temporary storage, with explicit length information. -- -- <ul> -- <li>the memory is freed when the subcomputation terminates (either -- normally or via an exception), so the pointer to the temporary storage -- must <i>not</i> be used after this.</li> -- </ul> withCWStringLen :: String -> (CWStringLen -> IO a) -> IO a -- | The module <a>Foreign.C.Error</a> facilitates C-specific error -- handling of <tt>errno</tt>. module Foreign.C.Error -- | Haskell representation for <tt>errno</tt> values. The implementation -- is deliberately exposed, to allow users to add their own definitions -- of <a>Errno</a> values. newtype Errno :: * Errno :: CInt -> Errno eOK :: Errno e2BIG :: Errno eACCES :: Errno eADDRINUSE :: Errno eADDRNOTAVAIL :: Errno eADV :: Errno eAFNOSUPPORT :: Errno eAGAIN :: Errno eALREADY :: Errno eBADF :: Errno eBADMSG :: Errno eBADRPC :: Errno eBUSY :: Errno eCHILD :: Errno eCOMM :: Errno eCONNABORTED :: Errno eCONNREFUSED :: Errno eCONNRESET :: Errno eDEADLK :: Errno eDESTADDRREQ :: Errno eDIRTY :: Errno eDOM :: Errno eDQUOT :: Errno eEXIST :: Errno eFAULT :: Errno eFBIG :: Errno eFTYPE :: Errno eHOSTDOWN :: Errno eHOSTUNREACH :: Errno eIDRM :: Errno eILSEQ :: Errno eINPROGRESS :: Errno eINTR :: Errno eINVAL :: Errno eIO :: Errno eISCONN :: Errno eISDIR :: Errno eLOOP :: Errno eMFILE :: Errno eMLINK :: Errno eMSGSIZE :: Errno eMULTIHOP :: Errno eNAMETOOLONG :: Errno eNETDOWN :: Errno eNETRESET :: Errno eNETUNREACH :: Errno eNFILE :: Errno eNOBUFS :: Errno eNODATA :: Errno eNODEV :: Errno eNOENT :: Errno eNOEXEC :: Errno eNOLCK :: Errno eNOLINK :: Errno eNOMEM :: Errno eNOMSG :: Errno eNONET :: Errno eNOPROTOOPT :: Errno eNOSPC :: Errno eNOSR :: Errno eNOSTR :: Errno eNOSYS :: Errno eNOTBLK :: Errno eNOTCONN :: Errno eNOTDIR :: Errno eNOTEMPTY :: Errno eNOTSOCK :: Errno eNOTTY :: Errno eNXIO :: Errno eOPNOTSUPP :: Errno ePERM :: Errno ePFNOSUPPORT :: Errno ePIPE :: Errno ePROCLIM :: Errno ePROCUNAVAIL :: Errno ePROGMISMATCH :: Errno ePROGUNAVAIL :: Errno ePROTO :: Errno ePROTONOSUPPORT :: Errno ePROTOTYPE :: Errno eRANGE :: Errno eREMCHG :: Errno eREMOTE :: Errno eROFS :: Errno eRPCMISMATCH :: Errno eRREMOTE :: Errno eSHUTDOWN :: Errno eSOCKTNOSUPPORT :: Errno eSPIPE :: Errno eSRCH :: Errno eSRMNT :: Errno eSTALE :: Errno eTIME :: Errno eTIMEDOUT :: Errno eTOOMANYREFS :: Errno eTXTBSY :: Errno eUSERS :: Errno eWOULDBLOCK :: Errno eXDEV :: Errno -- | Yield <a>True</a> if the given <a>Errno</a> value is valid on the -- system. This implies that the <a>Eq</a> instance of <a>Errno</a> is -- also system dependent as it is only defined for valid values of -- <a>Errno</a>. isValidErrno :: Errno -> Bool -- | Get the current value of <tt>errno</tt> in the current thread. getErrno :: IO Errno -- | Reset the current thread's <tt>errno</tt> value to <a>eOK</a>. resetErrno :: IO () -- | Construct an <a>IOError</a> based on the given <a>Errno</a> value. The -- optional information can be used to improve the accuracy of error -- messages. errnoToIOError :: String -> Errno -> Maybe Handle -> Maybe String -> IOError -- | Throw an <a>IOError</a> corresponding to the current value of -- <a>getErrno</a>. throwErrno :: String -> IO a -- | Throw an <a>IOError</a> corresponding to the current value of -- <a>getErrno</a> if the result value of the <a>IO</a> action meets the -- given predicate. throwErrnoIf :: (a -> Bool) -> String -> IO a -> IO a -- | as <a>throwErrnoIf</a>, but discards the result of the <a>IO</a> -- action after error handling. throwErrnoIf_ :: (a -> Bool) -> String -> IO a -> IO () -- | as <a>throwErrnoIf</a>, but retry the <a>IO</a> action when it yields -- the error code <a>eINTR</a> - this amounts to the standard retry loop -- for interrupted POSIX system calls. throwErrnoIfRetry :: (a -> Bool) -> String -> IO a -> IO a -- | as <a>throwErrnoIfRetry</a>, but discards the result. throwErrnoIfRetry_ :: (a -> Bool) -> String -> IO a -> IO () -- | Throw an <a>IOError</a> corresponding to the current value of -- <a>getErrno</a> if the <a>IO</a> action returns a result of -- <tt>-1</tt>. throwErrnoIfMinus1 :: (Eq a, Num a) => String -> IO a -> IO a -- | as <a>throwErrnoIfMinus1</a>, but discards the result. throwErrnoIfMinus1_ :: (Eq a, Num a) => String -> IO a -> IO () -- | Throw an <a>IOError</a> corresponding to the current value of -- <a>getErrno</a> if the <a>IO</a> action returns a result of -- <tt>-1</tt>, but retries in case of an interrupted operation. throwErrnoIfMinus1Retry :: (Eq a, Num a) => String -> IO a -> IO a -- | as <a>throwErrnoIfMinus1</a>, but discards the result. throwErrnoIfMinus1Retry_ :: (Eq a, Num a) => String -> IO a -> IO () -- | Throw an <a>IOError</a> corresponding to the current value of -- <a>getErrno</a> if the <a>IO</a> action returns <a>nullPtr</a>. throwErrnoIfNull :: String -> IO (Ptr a) -> IO (Ptr a) -- | Throw an <a>IOError</a> corresponding to the current value of -- <a>getErrno</a> if the <a>IO</a> action returns <a>nullPtr</a>, but -- retry in case of an interrupted operation. throwErrnoIfNullRetry :: String -> IO (Ptr a) -> IO (Ptr a) -- | as <a>throwErrnoIfRetry</a>, but additionally if the operation yields -- the error code <a>eAGAIN</a> or <a>eWOULDBLOCK</a>, an alternative -- action is executed before retrying. throwErrnoIfRetryMayBlock :: (a -> Bool) -> String -> IO a -> IO b -> IO a -- | as <a>throwErrnoIfRetryMayBlock</a>, but discards the result. throwErrnoIfRetryMayBlock_ :: (a -> Bool) -> String -> IO a -> IO b -> IO () -- | as <a>throwErrnoIfMinus1Retry</a>, but checks for operations that -- would block. throwErrnoIfMinus1RetryMayBlock :: (Eq a, Num a) => String -> IO a -> IO b -> IO a -- | as <a>throwErrnoIfMinus1RetryMayBlock</a>, but discards the result. throwErrnoIfMinus1RetryMayBlock_ :: (Eq a, Num a) => String -> IO a -> IO b -> IO () -- | as <a>throwErrnoIfNullRetry</a>, but checks for operations that would -- block. throwErrnoIfNullRetryMayBlock :: String -> IO (Ptr a) -> IO b -> IO (Ptr a) -- | as <a>throwErrno</a>, but exceptions include the given path when -- appropriate. throwErrnoPath :: String -> FilePath -> IO a -- | as <a>throwErrnoIf</a>, but exceptions include the given path when -- appropriate. throwErrnoPathIf :: (a -> Bool) -> String -> FilePath -> IO a -> IO a -- | as <a>throwErrnoIf_</a>, but exceptions include the given path when -- appropriate. throwErrnoPathIf_ :: (a -> Bool) -> String -> FilePath -> IO a -> IO () -- | as <a>throwErrnoIfNull</a>, but exceptions include the given path when -- appropriate. throwErrnoPathIfNull :: String -> FilePath -> IO (Ptr a) -> IO (Ptr a) -- | as <a>throwErrnoIfMinus1</a>, but exceptions include the given path -- when appropriate. throwErrnoPathIfMinus1 :: (Eq a, Num a) => String -> FilePath -> IO a -> IO a -- | as <a>throwErrnoIfMinus1_</a>, but exceptions include the given path -- when appropriate. throwErrnoPathIfMinus1_ :: (Eq a, Num a) => String -> FilePath -> IO a -> IO () module Foreign.Marshal -- | Sometimes an external entity is a pure function, except that it passes -- arguments and/or results via pointers. The function -- <tt>unsafeLocalState</tt> permits the packaging of such entities as -- pure functions. -- -- The only IO operations allowed in the IO action passed to -- <tt>unsafeLocalState</tt> are (a) local allocation (<tt>alloca</tt>, -- <tt>allocaBytes</tt> and derived operations such as <tt>withArray</tt> -- and <tt>withCString</tt>), and (b) pointer operations -- (<tt>Foreign.Storable</tt> and <tt>Foreign.Ptr</tt>) on the pointers -- to local storage, and (c) foreign functions whose only observable -- effect is to read and/or write the locally allocated memory. Passing -- an IO operation that does not obey these rules results in undefined -- behaviour. -- -- It is expected that this operation will be replaced in a future -- revision of Haskell. unsafeLocalState :: IO a -> a module Data.Complex -- | Complex numbers are an algebraic type. -- -- For a complex number <tt>z</tt>, <tt><a>abs</a> z</tt> is a number -- with the magnitude of <tt>z</tt>, but oriented in the positive real -- direction, whereas <tt><a>signum</a> z</tt> has the phase of -- <tt>z</tt>, but unit magnitude. data Complex a :: * -> * -- | forms a complex number from its real and imaginary rectangular -- components. (:+) :: !a -> !a -> Complex a -- | Extracts the real part of a complex number. realPart :: RealFloat a => Complex a -> a -- | Extracts the imaginary part of a complex number. imagPart :: RealFloat a => Complex a -> a -- | Form a complex number from polar components of magnitude and phase. mkPolar :: RealFloat a => a -> a -> Complex a -- | <tt><a>cis</a> t</tt> is a complex value with magnitude <tt>1</tt> and -- phase <tt>t</tt> (modulo <tt>2*<a>pi</a></tt>). cis :: RealFloat a => a -> Complex a -- | The function <a>polar</a> takes a complex number and returns a -- (magnitude, phase) pair in canonical form: the magnitude is -- nonnegative, and the phase in the range <tt>(-<a>pi</a>, -- <a>pi</a>]</tt>; if the magnitude is zero, then so is the phase. polar :: RealFloat a => Complex a -> (a, a) -- | The nonnegative magnitude of a complex number. magnitude :: RealFloat a => Complex a -> a -- | The phase of a complex number, in the range <tt>(-<a>pi</a>, -- <a>pi</a>]</tt>. If the magnitude is zero, then so is the phase. phase :: RealFloat a => Complex a -> a -- | The conjugate of a complex number. conjugate :: RealFloat a => Complex a -> Complex a module System.Environment -- | Computation <a>getArgs</a> returns a list of the program's command -- line arguments (not including the program name). getArgs :: IO [String] -- | Computation <a>getProgName</a> returns the name of the program as it -- was invoked. -- -- However, this is hard-to-impossible to implement on some non-Unix -- OSes, so instead, for maximum portability, we just return the leafname -- of the program as invoked. Even then there are some differences -- between platforms: on Windows, for example, a program invoked as foo -- is probably really <tt>FOO.EXE</tt>, and that is what -- <a>getProgName</a> will return. getProgName :: IO String -- | Computation <a>getEnv</a> <tt>var</tt> returns the value of the -- environment variable <tt>var</tt>. -- -- This computation may fail with: -- -- <ul> -- <li><a>isDoesNotExistError</a> if the environment variable does not -- exist.</li> -- </ul> getEnv :: String -> IO String module Foreign.ForeignPtr -- | The type <a>ForeignPtr</a> represents references to objects that are -- maintained in a foreign language, i.e., that are not part of the data -- structures usually managed by the Haskell storage manager. The -- essential difference between <a>ForeignPtr</a>s and vanilla memory -- references of type <tt>Ptr a</tt> is that the former may be associated -- with <i>finalizers</i>. A finalizer is a routine that is invoked when -- the Haskell storage manager detects that - within the Haskell heap and -- stack - there are no more references left that are pointing to the -- <a>ForeignPtr</a>. Typically, the finalizer will, then, invoke -- routines in the foreign language that free the resources bound by the -- foreign object. -- -- The <a>ForeignPtr</a> is parameterised in the same way as <a>Ptr</a>. -- The type argument of <a>ForeignPtr</a> should normally be an instance -- of class <a>Storable</a>. data ForeignPtr a :: * -> * -- | A finalizer is represented as a pointer to a foreign function that, at -- finalisation time, gets as an argument a plain pointer variant of the -- foreign pointer that the finalizer is associated with. type FinalizerPtr a = FunPtr (Ptr a -> IO ()) type FinalizerEnvPtr env a = FunPtr (Ptr env -> Ptr a -> IO ()) -- | Turns a plain memory reference into a foreign pointer, and associates -- a finalizer with the reference. The finalizer will be executed after -- the last reference to the foreign object is dropped. There is no -- guarantee of promptness, however the finalizer will be executed before -- the program exits. newForeignPtr :: FinalizerPtr a -> Ptr a -> IO (ForeignPtr a) -- | Turns a plain memory reference into a foreign pointer that may be -- associated with finalizers by using <a>addForeignPtrFinalizer</a>. newForeignPtr_ :: Ptr a -> IO (ForeignPtr a) -- | This function adds a finalizer to the given foreign object. The -- finalizer will run <i>before</i> all other finalizers for the same -- object which have already been registered. addForeignPtrFinalizer :: FinalizerPtr a -> ForeignPtr a -> IO () -- | This variant of <a>newForeignPtr</a> adds a finalizer that expects an -- environment in addition to the finalized pointer. The environment that -- will be passed to the finalizer is fixed by the second argument to -- <a>newForeignPtrEnv</a>. newForeignPtrEnv :: FinalizerEnvPtr env a -> Ptr env -> Ptr a -> IO (ForeignPtr a) -- | Like <a>addForeignPtrFinalizerEnv</a> but allows the finalizer to be -- passed an additional environment parameter to be passed to the -- finalizer. The environment passed to the finalizer is fixed by the -- second argument to <a>addForeignPtrFinalizerEnv</a> addForeignPtrFinalizerEnv :: FinalizerEnvPtr env a -> Ptr env -> ForeignPtr a -> IO () -- | This is a way to look at the pointer living inside a foreign object. -- This function takes a function which is applied to that pointer. The -- resulting <a>IO</a> action is then executed. The foreign object is -- kept alive at least during the whole action, even if it is not used -- directly inside. Note that it is not safe to return the pointer from -- the action and use it after the action completes. All uses of the -- pointer should be inside the <a>withForeignPtr</a> bracket. The reason -- for this unsafeness is the same as for <a>unsafeForeignPtrToPtr</a> -- below: the finalizer may run earlier than expected, because the -- compiler can only track usage of the <a>ForeignPtr</a> object, not a -- <a>Ptr</a> object made from it. -- -- This function is normally used for marshalling data to or from the -- object pointed to by the <a>ForeignPtr</a>, using the operations from -- the <a>Storable</a> class. withForeignPtr :: ForeignPtr a -> (Ptr a -> IO b) -> IO b -- | Causes the finalizers associated with a foreign pointer to be run -- immediately. finalizeForeignPtr :: ForeignPtr a -> IO () unsafeForeignPtrToPtr :: ForeignPtr a -> Ptr a -- | This function ensures that the foreign object in question is alive at -- the given place in the sequence of IO actions. In particular -- <a>withForeignPtr</a> does a <a>touchForeignPtr</a> after it executes -- the user action. -- -- Note that this function should not be used to express dependencies -- between finalizers on <a>ForeignPtr</a>s. For example, if the -- finalizer for a <a>ForeignPtr</a> <tt>F1</tt> calls -- <a>touchForeignPtr</a> on a second <a>ForeignPtr</a> <tt>F2</tt>, then -- the only guarantee is that the finalizer for <tt>F2</tt> is never -- started before the finalizer for <tt>F1</tt>. They might be started -- together if for example both <tt>F1</tt> and <tt>F2</tt> are otherwise -- unreachable. -- -- In general, it is not recommended to use finalizers on separate -- objects with ordering constraints between them. To express the -- ordering robustly requires explicit synchronisation between -- finalizers. touchForeignPtr :: ForeignPtr a -> IO () -- | This function casts a <a>ForeignPtr</a> parameterised by one type into -- another type. castForeignPtr :: ForeignPtr a -> ForeignPtr b -- | Allocate some memory and return a <a>ForeignPtr</a> to it. The memory -- will be released automatically when the <a>ForeignPtr</a> is -- discarded. -- -- <a>mallocForeignPtr</a> is equivalent to -- -- <pre> -- do { p <- malloc; newForeignPtr finalizerFree p } -- </pre> -- -- although it may be implemented differently internally: you may not -- assume that the memory returned by <a>mallocForeignPtr</a> has been -- allocated with <a>malloc</a>. mallocForeignPtr :: Storable a => IO (ForeignPtr a) -- | This function is similar to <a>mallocForeignPtr</a>, except that the -- size of the memory required is given explicitly as a number of bytes. mallocForeignPtrBytes :: Int -> IO (ForeignPtr a) -- | This function is similar to <a>mallocArray</a>, but yields a memory -- area that has a finalizer attached that releases the memory area. As -- with <a>mallocForeignPtr</a>, it is not guaranteed that the block of -- memory was allocated by <a>malloc</a>. mallocForeignPtrArray :: Storable a => Int -> IO (ForeignPtr a) -- | This function is similar to <a>mallocArray0</a>, but yields a memory -- area that has a finalizer attached that releases the memory area. As -- with <a>mallocForeignPtr</a>, it is not guaranteed that the block of -- memory was allocated by <a>malloc</a>. mallocForeignPtrArray0 :: Storable a => Int -> IO (ForeignPtr a) module Foreign module Foreign.C module Data.List -- | Append two lists, i.e., -- -- <pre> -- [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn] -- [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...] -- </pre> -- -- If the first list is not finite, the result is the first list. (++) :: [a] -> [a] -> [a] -- | Extract the first element of a list, which must be non-empty. head :: [a] -> a -- | Extract the last element of a list, which must be finite and -- non-empty. last :: [a] -> a -- | Extract the elements after the head of a list, which must be -- non-empty. tail :: [a] -> [a] -- | Return all the elements of a list except the last one. The list must -- be non-empty. init :: [a] -> [a] -- | Test whether a list is empty. null :: [a] -> Bool -- | <i>O(n)</i>. <a>length</a> returns the length of a finite list as an -- <a>Int</a>. It is an instance of the more general -- <a>genericLength</a>, the result type of which may be any kind of -- number. length :: [a] -> Int -- | <a>map</a> <tt>f xs</tt> is the list obtained by applying <tt>f</tt> -- to each element of <tt>xs</tt>, i.e., -- -- <pre> -- map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn] -- map f [x1, x2, ...] == [f x1, f x2, ...] -- </pre> map :: (a -> b) -> [a] -> [b] -- | <a>reverse</a> <tt>xs</tt> returns the elements of <tt>xs</tt> in -- reverse order. <tt>xs</tt> must be finite. reverse :: [a] -> [a] -- | The <a>intersperse</a> function takes an element and a list and -- `intersperses' that element between the elements of the list. For -- example, -- -- <pre> -- intersperse ',' "abcde" == "a,b,c,d,e" -- </pre> intersperse :: a -> [a] -> [a] -- | <a>intercalate</a> <tt>xs xss</tt> is equivalent to <tt>(<a>concat</a> -- (<a>intersperse</a> xs xss))</tt>. It inserts the list <tt>xs</tt> in -- between the lists in <tt>xss</tt> and concatenates the result. intercalate :: [a] -> [[a]] -> [a] -- | The <a>transpose</a> function transposes the rows and columns of its -- argument. For example, -- -- <pre> -- transpose [[1,2,3],[4,5,6]] == [[1,4],[2,5],[3,6]] -- </pre> transpose :: [[a]] -> [[a]] -- | The <a>subsequences</a> function returns the list of all subsequences -- of the argument. -- -- <pre> -- subsequences "abc" == ["","a","b","ab","c","ac","bc","abc"] -- </pre> subsequences :: [a] -> [[a]] -- | The <a>permutations</a> function returns the list of all permutations -- of the argument. -- -- <pre> -- permutations "abc" == ["abc","bac","cba","bca","cab","acb"] -- </pre> permutations :: [a] -> [[a]] -- | <a>foldl</a>, applied to a binary operator, a starting value -- (typically the left-identity of the operator), and a list, reduces the -- list using the binary operator, from left to right: -- -- <pre> -- foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn -- </pre> -- -- The list must be finite. foldl :: (a -> b -> a) -> a -> [b] -> a -- | A strict version of <a>foldl</a>. foldl' :: (a -> b -> a) -> a -> [b] -> a -- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value -- argument, and thus must be applied to non-empty lists. foldl1 :: (a -> a -> a) -> [a] -> a -- | A strict version of <a>foldl1</a> foldl1' :: (a -> a -> a) -> [a] -> a -- | <a>foldr</a>, applied to a binary operator, a starting value -- (typically the right-identity of the operator), and a list, reduces -- the list using the binary operator, from right to left: -- -- <pre> -- foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...) -- </pre> foldr :: (a -> b -> b) -> b -> [a] -> b -- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value -- argument, and thus must be applied to non-empty lists. foldr1 :: (a -> a -> a) -> [a] -> a -- | Concatenate a list of lists. concat :: [[a]] -> [a] -- | Map a function over a list and concatenate the results. concatMap :: (a -> [b]) -> [a] -> [b] -- | <a>and</a> returns the conjunction of a Boolean list. For the result -- to be <a>True</a>, the list must be finite; <a>False</a>, however, -- results from a <a>False</a> value at a finite index of a finite or -- infinite list. and :: [Bool] -> Bool -- | <a>or</a> returns the disjunction of a Boolean list. For the result to -- be <a>False</a>, the list must be finite; <a>True</a>, however, -- results from a <a>True</a> value at a finite index of a finite or -- infinite list. or :: [Bool] -> Bool -- | Applied to a predicate and a list, <a>any</a> determines if any -- element of the list satisfies the predicate. For the result to be -- <a>False</a>, the list must be finite; <a>True</a>, however, results -- from a <a>True</a> value for the predicate applied to an element at a -- finite index of a finite or infinite list. any :: (a -> Bool) -> [a] -> Bool -- | Applied to a predicate and a list, <a>all</a> determines if all -- elements of the list satisfy the predicate. For the result to be -- <a>True</a>, the list must be finite; <a>False</a>, however, results -- from a <a>False</a> value for the predicate applied to an element at a -- finite index of a finite or infinite list. all :: (a -> Bool) -> [a] -> Bool -- | The <a>sum</a> function computes the sum of a finite list of numbers. sum :: Num a => [a] -> a -- | The <a>product</a> function computes the product of a finite list of -- numbers. product :: Num a => [a] -> a -- | <a>maximum</a> returns the maximum value from a list, which must be -- non-empty, finite, and of an ordered type. It is a special case of -- <a>maximumBy</a>, which allows the programmer to supply their own -- comparison function. maximum :: Ord a => [a] -> a -- | <a>minimum</a> returns the minimum value from a list, which must be -- non-empty, finite, and of an ordered type. It is a special case of -- <a>minimumBy</a>, which allows the programmer to supply their own -- comparison function. minimum :: Ord a => [a] -> a -- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of -- successive reduced values from the left: -- -- <pre> -- scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...] -- </pre> -- -- Note that -- -- <pre> -- last (scanl f z xs) == foldl f z xs. -- </pre> scanl :: (a -> b -> a) -> a -> [b] -> [a] -- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value -- argument: -- -- <pre> -- scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...] -- </pre> scanl1 :: (a -> a -> a) -> [a] -> [a] -- | <a>scanr</a> is the right-to-left dual of <a>scanl</a>. Note that -- -- <pre> -- head (scanr f z xs) == foldr f z xs. -- </pre> scanr :: (a -> b -> b) -> b -> [a] -> [b] -- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value -- argument. scanr1 :: (a -> a -> a) -> [a] -> [a] -- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a> -- and <a>foldl</a>; it applies a function to each element of a list, -- passing an accumulating parameter from left to right, and returning a -- final value of this accumulator together with the new list. mapAccumL :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y]) -- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a> -- and <a>foldr</a>; it applies a function to each element of a list, -- passing an accumulating parameter from right to left, and returning a -- final value of this accumulator together with the new list. mapAccumR :: (acc -> x -> (acc, y)) -> acc -> [x] -> (acc, [y]) -- | <a>iterate</a> <tt>f x</tt> returns an infinite list of repeated -- applications of <tt>f</tt> to <tt>x</tt>: -- -- <pre> -- iterate f x == [x, f x, f (f x), ...] -- </pre> iterate :: (a -> a) -> a -> [a] -- | <a>repeat</a> <tt>x</tt> is an infinite list, with <tt>x</tt> the -- value of every element. repeat :: a -> [a] -- | <a>replicate</a> <tt>n x</tt> is a list of length <tt>n</tt> with -- <tt>x</tt> the value of every element. It is an instance of the more -- general <a>genericReplicate</a>, in which <tt>n</tt> may be of any -- integral type. replicate :: Int -> a -> [a] -- | <a>cycle</a> ties a finite list into a circular one, or equivalently, -- the infinite repetition of the original list. It is the identity on -- infinite lists. cycle :: [a] -> [a] -- | The <a>unfoldr</a> function is a `dual' to <a>foldr</a>: while -- <a>foldr</a> reduces a list to a summary value, <a>unfoldr</a> builds -- a list from a seed value. The function takes the element and returns -- <a>Nothing</a> if it is done producing the list or returns <a>Just</a> -- <tt>(a,b)</tt>, in which case, <tt>a</tt> is a prepended to the list -- and <tt>b</tt> is used as the next element in a recursive call. For -- example, -- -- <pre> -- iterate f == unfoldr (\x -> Just (x, f x)) -- </pre> -- -- In some cases, <a>unfoldr</a> can undo a <a>foldr</a> operation: -- -- <pre> -- unfoldr f' (foldr f z xs) == xs -- </pre> -- -- if the following holds: -- -- <pre> -- f' (f x y) = Just (x,y) -- f' z = Nothing -- </pre> -- -- A simple use of unfoldr: -- -- <pre> -- unfoldr (\b -> if b == 0 then Nothing else Just (b, b-1)) 10 -- [10,9,8,7,6,5,4,3,2,1] -- </pre> unfoldr :: (b -> Maybe (a, b)) -> b -> [a] -- | <a>take</a> <tt>n</tt>, applied to a list <tt>xs</tt>, returns the -- prefix of <tt>xs</tt> of length <tt>n</tt>, or <tt>xs</tt> itself if -- <tt>n > <a>length</a> xs</tt>: -- -- <pre> -- take 5 "Hello World!" == "Hello" -- take 3 [1,2,3,4,5] == [1,2,3] -- take 3 [1,2] == [1,2] -- take 3 [] == [] -- take (-1) [1,2] == [] -- take 0 [1,2] == [] -- </pre> -- -- It is an instance of the more general <a>genericTake</a>, in which -- <tt>n</tt> may be of any integral type. take :: Int -> [a] -> [a] -- | <a>drop</a> <tt>n xs</tt> returns the suffix of <tt>xs</tt> after the -- first <tt>n</tt> elements, or <tt>[]</tt> if <tt>n > <a>length</a> -- xs</tt>: -- -- <pre> -- drop 6 "Hello World!" == "World!" -- drop 3 [1,2,3,4,5] == [4,5] -- drop 3 [1,2] == [] -- drop 3 [] == [] -- drop (-1) [1,2] == [1,2] -- drop 0 [1,2] == [1,2] -- </pre> -- -- It is an instance of the more general <a>genericDrop</a>, in which -- <tt>n</tt> may be of any integral type. drop :: Int -> [a] -> [a] -- | <a>splitAt</a> <tt>n xs</tt> returns a tuple where first element is -- <tt>xs</tt> prefix of length <tt>n</tt> and second element is the -- remainder of the list: -- -- <pre> -- splitAt 6 "Hello World!" == ("Hello ","World!") -- splitAt 3 [1,2,3,4,5] == ([1,2,3],[4,5]) -- splitAt 1 [1,2,3] == ([1],[2,3]) -- splitAt 3 [1,2,3] == ([1,2,3],[]) -- splitAt 4 [1,2,3] == ([1,2,3],[]) -- splitAt 0 [1,2,3] == ([],[1,2,3]) -- splitAt (-1) [1,2,3] == ([],[1,2,3]) -- </pre> -- -- It is equivalent to <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>. -- <a>splitAt</a> is an instance of the more general -- <a>genericSplitAt</a>, in which <tt>n</tt> may be of any integral -- type. splitAt :: Int -> [a] -> ([a], [a]) -- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a list -- <tt>xs</tt>, returns the longest prefix (possibly empty) of -- <tt>xs</tt> of elements that satisfy <tt>p</tt>: -- -- <pre> -- takeWhile (< 3) [1,2,3,4,1,2,3,4] == [1,2] -- takeWhile (< 9) [1,2,3] == [1,2,3] -- takeWhile (< 0) [1,2,3] == [] -- </pre> takeWhile :: (a -> Bool) -> [a] -> [a] -- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after -- <a>takeWhile</a> <tt>p xs</tt>: -- -- <pre> -- dropWhile (< 3) [1,2,3,4,5,1,2,3] == [3,4,5,1,2,3] -- dropWhile (< 9) [1,2,3] == [] -- dropWhile (< 0) [1,2,3] == [1,2,3] -- </pre> dropWhile :: (a -> Bool) -> [a] -> [a] -- | <a>span</a>, applied to a predicate <tt>p</tt> and a list <tt>xs</tt>, -- returns a tuple where first element is longest prefix (possibly empty) -- of <tt>xs</tt> of elements that satisfy <tt>p</tt> and second element -- is the remainder of the list: -- -- <pre> -- span (< 3) [1,2,3,4,1,2,3,4] == ([1,2],[3,4,1,2,3,4]) -- span (< 9) [1,2,3] == ([1,2,3],[]) -- span (< 0) [1,2,3] == ([],[1,2,3]) -- </pre> -- -- <a>span</a> <tt>p xs</tt> is equivalent to <tt>(<a>takeWhile</a> p xs, -- <a>dropWhile</a> p xs)</tt> span :: (a -> Bool) -> [a] -> ([a], [a]) -- | <a>break</a>, applied to a predicate <tt>p</tt> and a list -- <tt>xs</tt>, returns a tuple where first element is longest prefix -- (possibly empty) of <tt>xs</tt> of elements that <i>do not satisfy</i> -- <tt>p</tt> and second element is the remainder of the list: -- -- <pre> -- break (> 3) [1,2,3,4,1,2,3,4] == ([1,2,3],[4,1,2,3,4]) -- break (< 9) [1,2,3] == ([],[1,2,3]) -- break (> 9) [1,2,3] == ([1,2,3],[]) -- </pre> -- -- <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> . -- p)</tt>. break :: (a -> Bool) -> [a] -> ([a], [a]) -- | The <a>stripPrefix</a> function drops the given prefix from a list. It -- returns <a>Nothing</a> if the list did not start with the prefix -- given, or <a>Just</a> the list after the prefix, if it does. -- -- <pre> -- stripPrefix "foo" "foobar" == Just "bar" -- stripPrefix "foo" "foo" == Just "" -- stripPrefix "foo" "barfoo" == Nothing -- stripPrefix "foo" "barfoobaz" == Nothing -- </pre> stripPrefix :: Eq a => [a] -> [a] -> Maybe [a] -- | The <a>group</a> function takes a list and returns a list of lists -- such that the concatenation of the result is equal to the argument. -- Moreover, each sublist in the result contains only equal elements. For -- example, -- -- <pre> -- group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"] -- </pre> -- -- It is a special case of <a>groupBy</a>, which allows the programmer to -- supply their own equality test. group :: Eq a => [a] -> [[a]] -- | The <a>inits</a> function returns all initial segments of the -- argument, shortest first. For example, -- -- <pre> -- inits "abc" == ["","a","ab","abc"] -- </pre> -- -- Note that <a>inits</a> has the following strictness property: -- <tt>inits _|_ = [] : _|_</tt> inits :: [a] -> [[a]] -- | The <a>tails</a> function returns all final segments of the argument, -- longest first. For example, -- -- <pre> -- tails "abc" == ["abc", "bc", "c",""] -- </pre> -- -- Note that <a>tails</a> has the following strictness property: -- <tt>tails _|_ = _|_ : _|_</tt> tails :: [a] -> [[a]] -- | The <a>isPrefixOf</a> function takes two lists and returns <a>True</a> -- iff the first list is a prefix of the second. isPrefixOf :: Eq a => [a] -> [a] -> Bool -- | The <a>isSuffixOf</a> function takes two lists and returns <a>True</a> -- iff the first list is a suffix of the second. Both lists must be -- finite. isSuffixOf :: Eq a => [a] -> [a] -> Bool -- | The <a>isInfixOf</a> function takes two lists and returns <a>True</a> -- iff the first list is contained, wholly and intact, anywhere within -- the second. -- -- Example: -- -- <pre> -- isInfixOf "Haskell" "I really like Haskell." == True -- isInfixOf "Ial" "I really like Haskell." == False -- </pre> isInfixOf :: Eq a => [a] -> [a] -> Bool -- | <a>elem</a> is the list membership predicate, usually written in infix -- form, e.g., <tt>x `elem` xs</tt>. For the result to be <a>False</a>, -- the list must be finite; <a>True</a>, however, results from an element -- equal to <tt>x</tt> found at a finite index of a finite or infinite -- list. elem :: Eq a => a -> [a] -> Bool -- | <a>notElem</a> is the negation of <a>elem</a>. notElem :: Eq a => a -> [a] -> Bool -- | <a>lookup</a> <tt>key assocs</tt> looks up a key in an association -- list. lookup :: Eq a => a -> [(a, b)] -> Maybe b -- | The <a>find</a> function takes a predicate and a list and returns the -- first element in the list matching the predicate, or <a>Nothing</a> if -- there is no such element. find :: (a -> Bool) -> [a] -> Maybe a -- | <a>filter</a>, applied to a predicate and a list, returns the list of -- those elements that satisfy the predicate; i.e., -- -- <pre> -- filter p xs = [ x | x <- xs, p x] -- </pre> filter :: (a -> Bool) -> [a] -> [a] -- | The <a>partition</a> function takes a predicate a list and returns the -- pair of lists of elements which do and do not satisfy the predicate, -- respectively; i.e., -- -- <pre> -- partition p xs == (filter p xs, filter (not . p) xs) -- </pre> partition :: (a -> Bool) -> [a] -> ([a], [a]) -- | List index (subscript) operator, starting from 0. It is an instance of -- the more general <a>genericIndex</a>, which takes an index of any -- integral type. (!!) :: [a] -> Int -> a -- | The <a>elemIndex</a> function returns the index of the first element -- in the given list which is equal (by <a>==</a>) to the query element, -- or <a>Nothing</a> if there is no such element. elemIndex :: Eq a => a -> [a] -> Maybe Int -- | The <a>elemIndices</a> function extends <a>elemIndex</a>, by returning -- the indices of all elements equal to the query element, in ascending -- order. elemIndices :: Eq a => a -> [a] -> [Int] -- | The <a>findIndex</a> function takes a predicate and a list and returns -- the index of the first element in the list satisfying the predicate, -- or <a>Nothing</a> if there is no such element. findIndex :: (a -> Bool) -> [a] -> Maybe Int -- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning -- the indices of all elements satisfying the predicate, in ascending -- order. findIndices :: (a -> Bool) -> [a] -> [Int] -- | <a>zip</a> takes two lists and returns a list of corresponding pairs. -- If one input list is short, excess elements of the longer list are -- discarded. zip :: [a] -> [b] -> [(a, b)] -- | <a>zip3</a> takes three lists and returns a list of triples, analogous -- to <a>zip</a>. zip3 :: [a] -> [b] -> [c] -> [(a, b, c)] -- | The <a>zip4</a> function takes four lists and returns a list of -- quadruples, analogous to <a>zip</a>. zip4 :: [a] -> [b] -> [c] -> [d] -> [(a, b, c, d)] -- | The <a>zip5</a> function takes five lists and returns a list of -- five-tuples, analogous to <a>zip</a>. zip5 :: [a] -> [b] -> [c] -> [d] -> [e] -> [(a, b, c, d, e)] -- | The <a>zip6</a> function takes six lists and returns a list of -- six-tuples, analogous to <a>zip</a>. zip6 :: [a] -> [b] -> [c] -> [d] -> [e] -> [f] -> [(a, b, c, d, e, f)] -- | The <a>zip7</a> function takes seven lists and returns a list of -- seven-tuples, analogous to <a>zip</a>. zip7 :: [a] -> [b] -> [c] -> [d] -> [e] -> [f] -> [g] -> [(a, b, c, d, e, f, g)] -- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function -- given as the first argument, instead of a tupling function. For -- example, <tt><a>zipWith</a> (+)</tt> is applied to two lists to -- produce the list of corresponding sums. zipWith :: (a -> b -> c) -> [a] -> [b] -> [c] -- | The <a>zipWith3</a> function takes a function which combines three -- elements, as well as three lists and returns a list of their -- point-wise combination, analogous to <a>zipWith</a>. zipWith3 :: (a -> b -> c -> d) -> [a] -> [b] -> [c] -> [d] -- | The <a>zipWith4</a> function takes a function which combines four -- elements, as well as four lists and returns a list of their point-wise -- combination, analogous to <a>zipWith</a>. zipWith4 :: (a -> b -> c -> d -> e) -> [a] -> [b] -> [c] -> [d] -> [e] -- | The <a>zipWith5</a> function takes a function which combines five -- elements, as well as five lists and returns a list of their point-wise -- combination, analogous to <a>zipWith</a>. zipWith5 :: (a -> b -> c -> d -> e -> f) -> [a] -> [b] -> [c] -> [d] -> [e] -> [f] -- | The <a>zipWith6</a> function takes a function which combines six -- elements, as well as six lists and returns a list of their point-wise -- combination, analogous to <a>zipWith</a>. zipWith6 :: (a -> b -> c -> d -> e -> f -> g) -> [a] -> [b] -> [c] -> [d] -> [e] -> [f] -> [g] -- | The <a>zipWith7</a> function takes a function which combines seven -- elements, as well as seven lists and returns a list of their -- point-wise combination, analogous to <a>zipWith</a>. zipWith7 :: (a -> b -> c -> d -> e -> f -> g -> h) -> [a] -> [b] -> [c] -> [d] -> [e] -> [f] -> [g] -> [h] -- | <a>unzip</a> transforms a list of pairs into a list of first -- components and a list of second components. unzip :: [(a, b)] -> ([a], [b]) -- | The <a>unzip3</a> function takes a list of triples and returns three -- lists, analogous to <a>unzip</a>. unzip3 :: [(a, b, c)] -> ([a], [b], [c]) -- | The <a>unzip4</a> function takes a list of quadruples and returns four -- lists, analogous to <a>unzip</a>. unzip4 :: [(a, b, c, d)] -> ([a], [b], [c], [d]) -- | The <a>unzip5</a> function takes a list of five-tuples and returns -- five lists, analogous to <a>unzip</a>. unzip5 :: [(a, b, c, d, e)] -> ([a], [b], [c], [d], [e]) -- | The <a>unzip6</a> function takes a list of six-tuples and returns six -- lists, analogous to <a>unzip</a>. unzip6 :: [(a, b, c, d, e, f)] -> ([a], [b], [c], [d], [e], [f]) -- | The <a>unzip7</a> function takes a list of seven-tuples and returns -- seven lists, analogous to <a>unzip</a>. unzip7 :: [(a, b, c, d, e, f, g)] -> ([a], [b], [c], [d], [e], [f], [g]) -- | <a>lines</a> breaks a string up into a list of strings at newline -- characters. The resulting strings do not contain newlines. lines :: String -> [String] -- | <a>words</a> breaks a string up into a list of words, which were -- delimited by white space. words :: String -> [String] -- | <a>unlines</a> is an inverse operation to <a>lines</a>. It joins -- lines, after appending a terminating newline to each. unlines :: [String] -> String -- | <a>unwords</a> is an inverse operation to <a>words</a>. It joins words -- with separating spaces. unwords :: [String] -> String -- | <i>O(n^2)</i>. The <a>nub</a> function removes duplicate elements from -- a list. In particular, it keeps only the first occurrence of each -- element. (The name <a>nub</a> means `essence'.) It is a special case -- of <a>nubBy</a>, which allows the programmer to supply their own -- equality test. nub :: Eq a => [a] -> [a] -- | <a>delete</a> <tt>x</tt> removes the first occurrence of <tt>x</tt> -- from its list argument. For example, -- -- <pre> -- delete 'a' "banana" == "bnana" -- </pre> -- -- It is a special case of <a>deleteBy</a>, which allows the programmer -- to supply their own equality test. delete :: Eq a => a -> [a] -> [a] -- | The <a>\\</a> function is list difference (non-associative). In the -- result of <tt>xs</tt> <a>\\</a> <tt>ys</tt>, the first occurrence of -- each element of <tt>ys</tt> in turn (if any) has been removed from -- <tt>xs</tt>. Thus -- -- <pre> -- (xs ++ ys) \\ xs == ys. -- </pre> -- -- It is a special case of <a>deleteFirstsBy</a>, which allows the -- programmer to supply their own equality test. (\\) :: Eq a => [a] -> [a] -> [a] -- | The <a>union</a> function returns the list union of the two lists. For -- example, -- -- <pre> -- "dog" `union` "cow" == "dogcw" -- </pre> -- -- Duplicates, and elements of the first list, are removed from the the -- second list, but if the first list contains duplicates, so will the -- result. It is a special case of <a>unionBy</a>, which allows the -- programmer to supply their own equality test. union :: Eq a => [a] -> [a] -> [a] -- | The <a>intersect</a> function takes the list intersection of two -- lists. For example, -- -- <pre> -- [1,2,3,4] `intersect` [2,4,6,8] == [2,4] -- </pre> -- -- If the first list contains duplicates, so will the result. -- -- <pre> -- [1,2,2,3,4] `intersect` [6,4,4,2] == [2,2,4] -- </pre> -- -- It is a special case of <a>intersectBy</a>, which allows the -- programmer to supply their own equality test. intersect :: Eq a => [a] -> [a] -> [a] -- | The <a>sort</a> function implements a stable sorting algorithm. It is -- a special case of <a>sortBy</a>, which allows the programmer to supply -- their own comparison function. sort :: Ord a => [a] -> [a] -- | The <a>insert</a> function takes an element and a list and inserts the -- element into the list at the last position where it is still less than -- or equal to the next element. In particular, if the list is sorted -- before the call, the result will also be sorted. It is a special case -- of <a>insertBy</a>, which allows the programmer to supply their own -- comparison function. insert :: Ord a => a -> [a] -> [a] -- | The <a>nubBy</a> function behaves just like <a>nub</a>, except it uses -- a user-supplied equality predicate instead of the overloaded <a>==</a> -- function. nubBy :: (a -> a -> Bool) -> [a] -> [a] -- | The <a>deleteBy</a> function behaves like <a>delete</a>, but takes a -- user-supplied equality predicate. deleteBy :: (a -> a -> Bool) -> a -> [a] -> [a] -- | The <a>deleteFirstsBy</a> function takes a predicate and two lists and -- returns the first list with the first occurrence of each element of -- the second list removed. deleteFirstsBy :: (a -> a -> Bool) -> [a] -> [a] -> [a] -- | The <a>unionBy</a> function is the non-overloaded version of -- <a>union</a>. unionBy :: (a -> a -> Bool) -> [a] -> [a] -> [a] -- | The <a>intersectBy</a> function is the non-overloaded version of -- <a>intersect</a>. intersectBy :: (a -> a -> Bool) -> [a] -> [a] -> [a] -- | The <a>groupBy</a> function is the non-overloaded version of -- <a>group</a>. groupBy :: (a -> a -> Bool) -> [a] -> [[a]] -- | The <a>sortBy</a> function is the non-overloaded version of -- <a>sort</a>. sortBy :: (a -> a -> Ordering) -> [a] -> [a] -- | The non-overloaded version of <a>insert</a>. insertBy :: (a -> a -> Ordering) -> a -> [a] -> [a] -- | The <a>maximumBy</a> function takes a comparison function and a list -- and returns the greatest element of the list by the comparison -- function. The list must be finite and non-empty. maximumBy :: (a -> a -> Ordering) -> [a] -> a -- | The <a>minimumBy</a> function takes a comparison function and a list -- and returns the least element of the list by the comparison function. -- The list must be finite and non-empty. minimumBy :: (a -> a -> Ordering) -> [a] -> a -- | The <a>genericLength</a> function is an overloaded version of -- <a>length</a>. In particular, instead of returning an <a>Int</a>, it -- returns any type which is an instance of <a>Num</a>. It is, however, -- less efficient than <a>length</a>. genericLength :: Num i => [b] -> i -- | The <a>genericTake</a> function is an overloaded version of -- <a>take</a>, which accepts any <a>Integral</a> value as the number of -- elements to take. genericTake :: Integral i => i -> [a] -> [a] -- | The <a>genericDrop</a> function is an overloaded version of -- <a>drop</a>, which accepts any <a>Integral</a> value as the number of -- elements to drop. genericDrop :: Integral i => i -> [a] -> [a] -- | The <a>genericSplitAt</a> function is an overloaded version of -- <a>splitAt</a>, which accepts any <a>Integral</a> value as the -- position at which to split. genericSplitAt :: Integral i => i -> [b] -> ([b], [b]) -- | The <a>genericIndex</a> function is an overloaded version of -- <a>!!</a>, which accepts any <a>Integral</a> value as the index. genericIndex :: Integral a => [b] -> a -> b -- | The <a>genericReplicate</a> function is an overloaded version of -- <a>replicate</a>, which accepts any <a>Integral</a> value as the -- number of repetitions to make. genericReplicate :: Integral i => i -> a -> [a] -- | The <a>Control.Monad</a> module provides the <a>Functor</a>, -- <a>Monad</a> and <a>MonadPlus</a> classes, together with some useful -- operations on monads. module Control.Monad -- | The <a>Functor</a> class is used for types that can be mapped over. -- Instances of <a>Functor</a> should satisfy the following laws: -- -- <pre> -- fmap id == id -- fmap (f . g) == fmap f . fmap g -- </pre> -- -- The instances of <a>Functor</a> for lists, <a>Maybe</a> and <a>IO</a> -- satisfy these laws. class Functor (f :: * -> *) fmap :: Functor f => (a -> b) -> f a -> f b -- | The <a>Monad</a> class defines the basic operations over a -- <i>monad</i>, a concept from a branch of mathematics known as -- <i>category theory</i>. From the perspective of a Haskell programmer, -- however, it is best to think of a monad as an <i>abstract datatype</i> -- of actions. Haskell's <tt>do</tt> expressions provide a convenient -- syntax for writing monadic expressions. -- -- Minimal complete definition: <a>>>=</a> and <a>return</a>. -- -- Instances of <a>Monad</a> should satisfy the following laws: -- -- <pre> -- return a >>= k == k a -- m >>= return == m -- m >>= (\x -> k x >>= h) == (m >>= k) >>= h -- </pre> -- -- Instances of both <a>Monad</a> and <a>Functor</a> should additionally -- satisfy the law: -- -- <pre> -- fmap f xs == xs >>= return . f -- </pre> -- -- The instances of <a>Monad</a> for lists, <a>Maybe</a> and <a>IO</a> -- defined in the <a>Prelude</a> satisfy these laws. class Monad (m :: * -> *) (>>=) :: Monad m => m a -> (a -> m b) -> m b (>>) :: Monad m => m a -> m b -> m b return :: Monad m => a -> m a fail :: Monad m => String -> m a -- | Monads that also support choice and failure. class Monad m => MonadPlus (m :: * -> *) mzero :: MonadPlus m => m a mplus :: MonadPlus m => m a -> m a -> m a -- | <tt><a>mapM</a> f</tt> is equivalent to <tt><a>sequence</a> . -- <a>map</a> f</tt>. mapM :: Monad m => (a -> m b) -> [a] -> m [b] -- | <tt><a>mapM_</a> f</tt> is equivalent to <tt><a>sequence_</a> . -- <a>map</a> f</tt>. mapM_ :: Monad m => (a -> m b) -> [a] -> m () -- | <a>forM</a> is <a>mapM</a> with its arguments flipped forM :: Monad m => [a] -> (a -> m b) -> m [b] -- | <a>forM_</a> is <a>mapM_</a> with its arguments flipped forM_ :: Monad m => [a] -> (a -> m b) -> m () -- | Evaluate each action in the sequence from left to right, and collect -- the results. sequence :: Monad m => [m a] -> m [a] -- | Evaluate each action in the sequence from left to right, and ignore -- the results. sequence_ :: Monad m => [m a] -> m () -- | Same as <a>>>=</a>, but with the arguments interchanged. (=<<) :: Monad m => (a -> m b) -> m a -> m b -- | Left-to-right Kleisli composition of monads. (>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c -- | Right-to-left Kleisli composition of monads. -- <tt>(<a>>=></a>)</tt>, with the arguments flipped (<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c -- | <tt><a>forever</a> act</tt> repeats the action infinitely. forever :: Monad m => m a -> m b -- | <tt><a>void</a> value</tt> discards or ignores the result of -- evaluation, such as the return value of an <a>IO</a> action. void :: Functor f => f a -> f () -- | The <a>join</a> function is the conventional monad join operator. It -- is used to remove one level of monadic structure, projecting its bound -- argument into the outer level. join :: Monad m => m (m a) -> m a -- | This generalizes the list-based <a>concat</a> function. msum :: MonadPlus m => [m a] -> m a -- | This generalizes the list-based <a>filter</a> function. filterM :: Monad m => (a -> m Bool) -> [a] -> m [a] -- | The <a>mapAndUnzipM</a> function maps its first argument over a list, -- returning the result as a pair of lists. This function is mainly used -- with complicated data structures or a state-transforming monad. mapAndUnzipM :: Monad m => (a -> m (b, c)) -> [a] -> m ([b], [c]) -- | The <a>zipWithM</a> function generalizes <a>zipWith</a> to arbitrary -- monads. zipWithM :: Monad m => (a -> b -> m c) -> [a] -> [b] -> m [c] -- | <a>zipWithM_</a> is the extension of <a>zipWithM</a> which ignores the -- final result. zipWithM_ :: Monad m => (a -> b -> m c) -> [a] -> [b] -> m () -- | The <a>foldM</a> function is analogous to <a>foldl</a>, except that -- its result is encapsulated in a monad. Note that <a>foldM</a> works -- from left-to-right over the list arguments. This could be an issue -- where <tt>(<a>>></a>)</tt> and the `folded function' are not -- commutative. -- -- <pre> -- foldM f a1 [x1, x2, ..., xm] -- </pre> -- -- == -- -- <pre> -- do -- a2 <- f a1 x1 -- a3 <- f a2 x2 -- ... -- f am xm -- </pre> -- -- If right-to-left evaluation is required, the input list should be -- reversed. foldM :: Monad m => (a -> b -> m a) -> a -> [b] -> m a -- | Like <a>foldM</a>, but discards the result. foldM_ :: Monad m => (a -> b -> m a) -> a -> [b] -> m () -- | <tt><a>replicateM</a> n act</tt> performs the action <tt>n</tt> times, -- gathering the results. replicateM :: Monad m => Int -> m a -> m [a] -- | Like <a>replicateM</a>, but discards the result. replicateM_ :: Monad m => Int -> m a -> m () -- | <tt><a>guard</a> b</tt> is <tt><a>return</a> ()</tt> if <tt>b</tt> is -- <a>True</a>, and <a>mzero</a> if <tt>b</tt> is <a>False</a>. guard :: MonadPlus m => Bool -> m () -- | Conditional execution of monadic expressions. For example, -- -- <pre> -- when debug (putStr "Debugging\n") -- </pre> -- -- will output the string <tt>Debugging\n</tt> if the Boolean value -- <tt>debug</tt> is <a>True</a>, and otherwise do nothing. when :: Monad m => Bool -> m () -> m () -- | The reverse of <a>when</a>. unless :: Monad m => Bool -> m () -> m () -- | Promote a function to a monad. liftM :: Monad m => (a1 -> r) -> m a1 -> m r -- | Promote a function to a monad, scanning the monadic arguments from -- left to right. For example, -- -- <pre> -- liftM2 (+) [0,1] [0,2] = [0,2,1,3] -- liftM2 (+) (Just 1) Nothing = Nothing -- </pre> liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r -- | Promote a function to a monad, scanning the monadic arguments from -- left to right (cf. <a>liftM2</a>). liftM3 :: Monad m => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r -- | Promote a function to a monad, scanning the monadic arguments from -- left to right (cf. <a>liftM2</a>). liftM4 :: Monad m => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r -- | Promote a function to a monad, scanning the monadic arguments from -- left to right (cf. <a>liftM2</a>). liftM5 :: Monad m => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r -- | In many situations, the <a>liftM</a> operations can be replaced by -- uses of <a>ap</a>, which promotes function application. -- -- <pre> -- return f `ap` x1 `ap` ... `ap` xn -- </pre> -- -- is equivalent to -- -- <pre> -- liftMn f x1 x2 ... xn -- </pre> ap :: Monad m => m (a -> b) -> m a -> m b module System.IO -- | A value of type <tt><a>IO</a> a</tt> is a computation which, when -- performed, does some I/O before returning a value of type <tt>a</tt>. -- -- There is really only one way to "perform" an I/O action: bind it to -- <tt>Main.main</tt> in your program. When your program is run, the I/O -- will be performed. It isn't possible to perform I/O from an arbitrary -- function, unless that function is itself in the <a>IO</a> monad and -- called at some point, directly or indirectly, from <tt>Main.main</tt>. -- -- <a>IO</a> is a monad, so <a>IO</a> actions can be combined using -- either the do-notation or the <tt>>></tt> and <tt>>>=</tt> -- operations from the <tt>Monad</tt> class. data IO a :: * -> * fixIO :: (a -> IO a) -> IO a -- | File and directory names are values of type <a>String</a>, whose -- precise meaning is operating system dependent. Files can be opened, -- yielding a handle which can then be used to operate on the contents of -- that file. type FilePath = String -- | Haskell defines operations to read and write characters from and to -- files, represented by values of type <tt>Handle</tt>. Each value of -- this type is a <i>handle</i>: a record used by the Haskell run-time -- system to <i>manage</i> I/O with file system objects. A handle has at -- least the following properties: -- -- <ul> -- <li>whether it manages input or output or both;</li> -- <li>whether it is <i>open</i>, <i>closed</i> or -- <i>semi-closed</i>;</li> -- <li>whether the object is seekable;</li> -- <li>whether buffering is disabled, or enabled on a line or block -- basis;</li> -- <li>a buffer (whose length may be zero).</li> -- </ul> -- -- Most handles will also have a current I/O position indicating where -- the next input or output operation will occur. A handle is -- <i>readable</i> if it manages only input or both input and output; -- likewise, it is <i>writable</i> if it manages only output or both -- input and output. A handle is <i>open</i> when first allocated. Once -- it is closed it can no longer be used for either input or output, -- though an implementation cannot re-use its storage while references -- remain to it. Handles are in the <a>Show</a> and <a>Eq</a> classes. -- The string produced by showing a handle is system dependent; it should -- include enough information to identify the handle for debugging. A -- handle is equal according to <a>==</a> only to itself; no attempt is -- made to compare the internal state of different handles for equality. data Handle :: * -- | A handle managing input from the Haskell program's standard input -- channel. stdin :: Handle -- | A handle managing output to the Haskell program's standard output -- channel. stdout :: Handle -- | A handle managing output to the Haskell program's standard error -- channel. stderr :: Handle -- | <tt><a>withFile</a> name mode act</tt> opens a file using -- <a>openFile</a> and passes the resulting handle to the computation -- <tt>act</tt>. The handle will be closed on exit from <a>withFile</a>, -- whether by normal termination or by raising an exception. If closing -- the handle raises an exception, then this exception will be raised by -- <a>withFile</a> rather than any exception raised by <tt>act</tt>. withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r -- | Computation <a>openFile</a> <tt>file mode</tt> allocates and returns a -- new, open handle to manage the file <tt>file</tt>. It manages input if -- <tt>mode</tt> is <a>ReadMode</a>, output if <tt>mode</tt> is -- <a>WriteMode</a> or <a>AppendMode</a>, and both input and output if -- mode is <a>ReadWriteMode</a>. -- -- If the file does not exist and it is opened for output, it should be -- created as a new file. If <tt>mode</tt> is <a>WriteMode</a> and the -- file already exists, then it should be truncated to zero length. Some -- operating systems delete empty files, so there is no guarantee that -- the file will exist following an <a>openFile</a> with <tt>mode</tt> -- <a>WriteMode</a> unless it is subsequently written to successfully. -- The handle is positioned at the end of the file if <tt>mode</tt> is -- <a>AppendMode</a>, and otherwise at the beginning (in which case its -- internal position is 0). The initial buffer mode is -- implementation-dependent. -- -- This operation may fail with: -- -- <ul> -- <li><tt>isAlreadyInUseError</tt> if the file is already open and -- cannot be reopened;</li> -- <li><tt>isDoesNotExistError</tt> if the file does not exist; or</li> -- <li><tt>isPermissionError</tt> if the user does not have permission to -- open the file.</li> -- </ul> openFile :: FilePath -> IOMode -> IO Handle -- | See <a>openFile</a> data IOMode :: * ReadMode :: IOMode WriteMode :: IOMode AppendMode :: IOMode ReadWriteMode :: IOMode -- | Computation <a>hClose</a> <tt>hdl</tt> makes handle <tt>hdl</tt> -- closed. Before the computation finishes, if <tt>hdl</tt> is writable -- its buffer is flushed as for <a>hFlush</a>. Performing <a>hClose</a> -- on a handle that has already been closed has no effect; doing so is -- not an error. All other operations on a closed handle will fail. If -- <a>hClose</a> fails for any reason, any further operations (apart from -- <a>hClose</a>) on the handle will still fail as if <tt>hdl</tt> had -- been successfully closed. hClose :: Handle -> IO () -- | The <a>readFile</a> function reads a file and returns the contents of -- the file as a string. The file is read lazily, on demand, as with -- <a>getContents</a>. readFile :: FilePath -> IO String -- | The computation <a>writeFile</a> <tt>file str</tt> function writes the -- string <tt>str</tt>, to the file <tt>file</tt>. writeFile :: FilePath -> String -> IO () -- | The computation <a>appendFile</a> <tt>file str</tt> function appends -- the string <tt>str</tt>, to the file <tt>file</tt>. -- -- Note that <a>writeFile</a> and <a>appendFile</a> write a literal -- string to a file. To write a value of any printable type, as with -- <a>print</a>, use the <a>show</a> function to convert the value to a -- string first. -- -- <pre> -- main = appendFile "squares" (show [(x,x*x) | x <- [0,0.1..2]]) -- </pre> appendFile :: FilePath -> String -> IO () -- | For a handle <tt>hdl</tt> which attached to a physical file, -- <a>hFileSize</a> <tt>hdl</tt> returns the size of that file in 8-bit -- bytes. hFileSize :: Handle -> IO Integer -- | <a>hSetFileSize</a> <tt>hdl</tt> <tt>size</tt> truncates the physical -- file with handle <tt>hdl</tt> to <tt>size</tt> bytes. hSetFileSize :: Handle -> Integer -> IO () -- | For a readable handle <tt>hdl</tt>, <a>hIsEOF</a> <tt>hdl</tt> returns -- <a>True</a> if no further input can be taken from <tt>hdl</tt> or for -- a physical file, if the current I/O position is equal to the length of -- the file. Otherwise, it returns <a>False</a>. -- -- NOTE: <a>hIsEOF</a> may block, because it has to attempt to read from -- the stream to determine whether there is any more data to be read. hIsEOF :: Handle -> IO Bool -- | The computation <a>isEOF</a> is identical to <a>hIsEOF</a>, except -- that it works only on <a>stdin</a>. isEOF :: IO Bool -- | Three kinds of buffering are supported: line-buffering, -- block-buffering or no-buffering. These modes have the following -- effects. For output, items are written out, or <i>flushed</i>, from -- the internal buffer according to the buffer mode: -- -- <ul> -- <li><i>line-buffering</i>: the entire output buffer is flushed -- whenever a newline is output, the buffer overflows, a <a>hFlush</a> is -- issued, or the handle is closed.</li> -- <li><i>block-buffering</i>: the entire buffer is written out whenever -- it overflows, a <a>hFlush</a> is issued, or the handle is closed.</li> -- <li><i>no-buffering</i>: output is written immediately, and never -- stored in the buffer.</li> -- </ul> -- -- An implementation is free to flush the buffer more frequently, but not -- less frequently, than specified above. The output buffer is emptied as -- soon as it has been written out. -- -- Similarly, input occurs according to the buffer mode for the handle: -- -- <ul> -- <li><i>line-buffering</i>: when the buffer for the handle is not -- empty, the next item is obtained from the buffer; otherwise, when the -- buffer is empty, characters up to and including the next newline -- character are read into the buffer. No characters are available until -- the newline character is available or the buffer is full.</li> -- <li><i>block-buffering</i>: when the buffer for the handle becomes -- empty, the next block of data is read into the buffer.</li> -- <li><i>no-buffering</i>: the next input item is read and returned. The -- <a>hLookAhead</a> operation implies that even a no-buffered handle may -- require a one-character buffer.</li> -- </ul> -- -- The default buffering mode when a handle is opened is -- implementation-dependent and may depend on the file system object -- which is attached to that handle. For most implementations, physical -- files will normally be block-buffered and terminals will normally be -- line-buffered. data BufferMode :: * -- | buffering is disabled if possible. NoBuffering :: BufferMode -- | line-buffering should be enabled if possible. LineBuffering :: BufferMode -- | block-buffering should be enabled if possible. The size of the buffer -- is <tt>n</tt> items if the argument is <a>Just</a> <tt>n</tt> and is -- otherwise implementation-dependent. BlockBuffering :: Maybe Int -> BufferMode -- | Computation <a>hSetBuffering</a> <tt>hdl mode</tt> sets the mode of -- buffering for handle <tt>hdl</tt> on subsequent reads and writes. -- -- If the buffer mode is changed from <a>BlockBuffering</a> or -- <a>LineBuffering</a> to <a>NoBuffering</a>, then -- -- <ul> -- <li>if <tt>hdl</tt> is writable, the buffer is flushed as for -- <a>hFlush</a>;</li> -- <li>if <tt>hdl</tt> is not writable, the contents of the buffer is -- discarded.</li> -- </ul> -- -- This operation may fail with: -- -- <ul> -- <li><tt>isPermissionError</tt> if the handle has already been used for -- reading or writing and the implementation does not allow the buffering -- mode to be changed.</li> -- </ul> hSetBuffering :: Handle -> BufferMode -> IO () -- | Computation <a>hGetBuffering</a> <tt>hdl</tt> returns the current -- buffering mode for <tt>hdl</tt>. hGetBuffering :: Handle -> IO BufferMode -- | The action <a>hFlush</a> <tt>hdl</tt> causes any items buffered for -- output in handle <tt>hdl</tt> to be sent immediately to the operating -- system. -- -- This operation may fail with: -- -- <ul> -- <li><tt>isFullError</tt> if the device is full;</li> -- <li><tt>isPermissionError</tt> if a system resource limit would be -- exceeded. It is unspecified whether the characters in the buffer are -- discarded or retained under these circumstances.</li> -- </ul> hFlush :: Handle -> IO () -- | Computation <a>hGetPosn</a> <tt>hdl</tt> returns the current I/O -- position of <tt>hdl</tt> as a value of the abstract type -- <a>HandlePosn</a>. hGetPosn :: Handle -> IO HandlePosn -- | If a call to <a>hGetPosn</a> <tt>hdl</tt> returns a position -- <tt>p</tt>, then computation <a>hSetPosn</a> <tt>p</tt> sets the -- position of <tt>hdl</tt> to the position it held at the time of the -- call to <a>hGetPosn</a>. -- -- This operation may fail with: -- -- <ul> -- <li><tt>isPermissionError</tt> if a system resource limit would be -- exceeded.</li> -- </ul> hSetPosn :: HandlePosn -> IO () data HandlePosn :: * -- | Computation <a>hSeek</a> <tt>hdl mode i</tt> sets the position of -- handle <tt>hdl</tt> depending on <tt>mode</tt>. The offset <tt>i</tt> -- is given in terms of 8-bit bytes. -- -- If <tt>hdl</tt> is block- or line-buffered, then seeking to a position -- which is not in the current buffer will first cause any items in the -- output buffer to be written to the device, and then cause the input -- buffer to be discarded. Some handles may not be seekable (see -- <a>hIsSeekable</a>), or only support a subset of the possible -- positioning operations (for instance, it may only be possible to seek -- to the end of a tape, or to a positive offset from the beginning or -- current position). It is not possible to set a negative I/O position, -- or for a physical file, an I/O position beyond the current -- end-of-file. -- -- This operation may fail with: -- -- <ul> -- <li><tt>isIllegalOperationError</tt> if the Handle is not seekable, or -- does not support the requested seek mode.</li> -- <li><tt>isPermissionError</tt> if a system resource limit would be -- exceeded.</li> -- </ul> hSeek :: Handle -> SeekMode -> Integer -> IO () -- | A mode that determines the effect of <tt>hSeek</tt> <tt>hdl mode -- i</tt>. data SeekMode :: * -- | the position of <tt>hdl</tt> is set to <tt>i</tt>. AbsoluteSeek :: SeekMode -- | the position of <tt>hdl</tt> is set to offset <tt>i</tt> from the -- current position. RelativeSeek :: SeekMode -- | the position of <tt>hdl</tt> is set to offset <tt>i</tt> from the end -- of the file. SeekFromEnd :: SeekMode -- | Computation <a>hTell</a> <tt>hdl</tt> returns the current position of -- the handle <tt>hdl</tt>, as the number of bytes from the beginning of -- the file. The value returned may be subsequently passed to -- <a>hSeek</a> to reposition the handle to the current position. -- -- This operation may fail with: -- -- <ul> -- <li><tt>isIllegalOperationError</tt> if the Handle is not -- seekable.</li> -- </ul> hTell :: Handle -> IO Integer hIsOpen :: Handle -> IO Bool hIsClosed :: Handle -> IO Bool hIsReadable :: Handle -> IO Bool hIsWritable :: Handle -> IO Bool hIsSeekable :: Handle -> IO Bool -- | Is the handle connected to a terminal? hIsTerminalDevice :: Handle -> IO Bool -- | Set the echoing status of a handle connected to a terminal. hSetEcho :: Handle -> Bool -> IO () -- | Get the echoing status of a handle connected to a terminal. hGetEcho :: Handle -> IO Bool -- | <a>hShow</a> is in the <a>IO</a> monad, and gives more comprehensive -- output than the (pure) instance of <a>Show</a> for <a>Handle</a>. hShow :: Handle -> IO String -- | Computation <a>hWaitForInput</a> <tt>hdl t</tt> waits until input is -- available on handle <tt>hdl</tt>. It returns <a>True</a> as soon as -- input is available on <tt>hdl</tt>, or <a>False</a> if no input is -- available within <tt>t</tt> milliseconds. Note that -- <a>hWaitForInput</a> waits until one or more full <i>characters</i> -- are available, which means that it needs to do decoding, and hence may -- fail with a decoding error. -- -- If <tt>t</tt> is less than zero, then <tt>hWaitForInput</tt> waits -- indefinitely. -- -- This operation may fail with: -- -- <ul> -- <li><tt>isEOFError</tt> if the end of file has been reached.</li> -- <li>a decoding error, if the input begins with an invalid byte -- sequence in this Handle's encoding.</li> -- </ul> hWaitForInput :: Handle -> Int -> IO Bool -- | Computation <a>hReady</a> <tt>hdl</tt> indicates whether at least one -- item is available for input from handle <tt>hdl</tt>. -- -- This operation may fail with: -- -- <ul> -- <li><a>isEOFError</a> if the end of file has been reached.</li> -- </ul> hReady :: Handle -> IO Bool -- | Computation <a>hGetChar</a> <tt>hdl</tt> reads a character from the -- file or channel managed by <tt>hdl</tt>, blocking until a character is -- available. -- -- This operation may fail with: -- -- <ul> -- <li><a>isEOFError</a> if the end of file has been reached.</li> -- </ul> hGetChar :: Handle -> IO Char -- | Computation <a>hGetLine</a> <tt>hdl</tt> reads a line from the file or -- channel managed by <tt>hdl</tt>. -- -- This operation may fail with: -- -- <ul> -- <li><a>isEOFError</a> if the end of file is encountered when reading -- the <i>first</i> character of the line.</li> -- </ul> -- -- If <a>hGetLine</a> encounters end-of-file at any other point while -- reading in a line, it is treated as a line terminator and the -- (partial) line is returned. hGetLine :: Handle -> IO String -- | Computation <a>hLookAhead</a> returns the next character from the -- handle without removing it from the input buffer, blocking until a -- character is available. -- -- This operation may fail with: -- -- <ul> -- <li><tt>isEOFError</tt> if the end of file has been reached.</li> -- </ul> hLookAhead :: Handle -> IO Char -- | Computation <a>hGetContents</a> <tt>hdl</tt> returns the list of -- characters corresponding to the unread portion of the channel or file -- managed by <tt>hdl</tt>, which is put into an intermediate state, -- <i>semi-closed</i>. In this state, <tt>hdl</tt> is effectively closed, -- but items are read from <tt>hdl</tt> on demand and accumulated in a -- special list returned by <a>hGetContents</a> <tt>hdl</tt>. -- -- Any operation that fails because a handle is closed, also fails if a -- handle is semi-closed. The only exception is <tt>hClose</tt>. A -- semi-closed handle becomes closed: -- -- <ul> -- <li>if <tt>hClose</tt> is applied to it;</li> -- <li>if an I/O error occurs when reading an item from the handle;</li> -- <li>or once the entire contents of the handle has been read.</li> -- </ul> -- -- Once a semi-closed handle becomes closed, the contents of the -- associated list becomes fixed. The contents of this final list is only -- partially specified: it will contain at least all the items of the -- stream that were evaluated prior to the handle becoming closed. -- -- Any I/O errors encountered while a handle is semi-closed are simply -- discarded. -- -- This operation may fail with: -- -- <ul> -- <li><a>isEOFError</a> if the end of file has been reached.</li> -- </ul> hGetContents :: Handle -> IO String -- | Computation <a>hPutChar</a> <tt>hdl ch</tt> writes the character -- <tt>ch</tt> to the file or channel managed by <tt>hdl</tt>. Characters -- may be buffered if buffering is enabled for <tt>hdl</tt>. -- -- This operation may fail with: -- -- <ul> -- <li><a>isFullError</a> if the device is full; or</li> -- <li><a>isPermissionError</a> if another system resource limit would be -- exceeded.</li> -- </ul> hPutChar :: Handle -> Char -> IO () -- | Computation <a>hPutStr</a> <tt>hdl s</tt> writes the string <tt>s</tt> -- to the file or channel managed by <tt>hdl</tt>. -- -- This operation may fail with: -- -- <ul> -- <li><a>isFullError</a> if the device is full; or</li> -- <li><a>isPermissionError</a> if another system resource limit would be -- exceeded.</li> -- </ul> hPutStr :: Handle -> String -> IO () -- | The same as <a>hPutStr</a>, but adds a newline character. hPutStrLn :: Handle -> String -> IO () -- | Computation <a>hPrint</a> <tt>hdl t</tt> writes the string -- representation of <tt>t</tt> given by the <a>shows</a> function to the -- file or channel managed by <tt>hdl</tt> and appends a newline. -- -- This operation may fail with: -- -- <ul> -- <li><a>isFullError</a> if the device is full; or</li> -- <li><a>isPermissionError</a> if another system resource limit would be -- exceeded.</li> -- </ul> hPrint :: Show a => Handle -> a -> IO () -- | The <a>interact</a> function takes a function of type -- <tt>String->String</tt> as its argument. The entire input from the -- standard input device is passed to this function as its argument, and -- the resulting string is output on the standard output device. interact :: (String -> String) -> IO () -- | Write a character to the standard output device (same as -- <a>hPutChar</a> <a>stdout</a>). putChar :: Char -> IO () -- | Write a string to the standard output device (same as <a>hPutStr</a> -- <a>stdout</a>). putStr :: String -> IO () -- | The same as <a>putStr</a>, but adds a newline character. putStrLn :: String -> IO () -- | The <a>print</a> function outputs a value of any printable type to the -- standard output device. Printable types are those that are instances -- of class <a>Show</a>; <a>print</a> converts values to strings for -- output using the <a>show</a> operation and adds a newline. -- -- For example, a program to print the first 20 integers and their powers -- of 2 could be written as: -- -- <pre> -- main = print ([(n, 2^n) | n <- [0..19]]) -- </pre> print :: Show a => a -> IO () -- | Read a character from the standard input device (same as -- <a>hGetChar</a> <a>stdin</a>). getChar :: IO Char -- | Read a line from the standard input device (same as <a>hGetLine</a> -- <a>stdin</a>). getLine :: IO String -- | The <a>getContents</a> operation returns all user input as a single -- string, which is read lazily as it is needed (same as -- <a>hGetContents</a> <a>stdin</a>). getContents :: IO String -- | The <a>readIO</a> function is similar to <a>read</a> except that it -- signals parse failure to the <a>IO</a> monad instead of terminating -- the program. readIO :: Read a => String -> IO a -- | The <a>readLn</a> function combines <a>getLine</a> and <a>readIO</a>. readLn :: Read a => IO a module Data.Array -- | The type of immutable non-strict (boxed) arrays with indices in -- <tt>i</tt> and elements in <tt>e</tt>. data Array i e :: * -> * -> * -- | Construct an array with the specified bounds and containing values for -- given indices within these bounds. -- -- The array is undefined (i.e. bottom) if any index in the list is out -- of bounds. If any two associations in the list have the same index, -- the value at that index is undefined (i.e. bottom). -- -- Because the indices must be checked for these errors, <a>array</a> is -- strict in the bounds argument and in the indices of the association -- list, but non-strict in the values. Thus, recurrences such as the -- following are possible: -- -- <pre> -- a = array (1,100) ((1,1) : [(i, i * a!(i-1)) | i <- [2..100]]) -- </pre> -- -- Not every index within the bounds of the array need appear in the -- association list, but the values associated with indices that do not -- appear will be undefined (i.e. bottom). -- -- If, in any dimension, the lower bound is greater than the upper bound, -- then the array is legal, but empty. Indexing an empty array always -- gives an array-bounds error, but <a>bounds</a> still yields the bounds -- with which the array was constructed. array :: Ix i => (i, i) -> [(i, e)] -> Array i e -- | Construct an array from a pair of bounds and a list of values in index -- order. listArray :: Ix i => (i, i) -> [e] -> Array i e -- | The <a>accumArray</a> function deals with repeated indices in the -- association list using an <i>accumulating function</i> which combines -- the values of associations with the same index. For example, given a -- list of values of some index type, <tt>hist</tt> produces a histogram -- of the number of occurrences of each index within a specified range: -- -- <pre> -- hist :: (Ix a, Num b) => (a,a) -> [a] -> Array a b -- hist bnds is = accumArray (+) 0 bnds [(i, 1) | i<-is, inRange bnds i] -- </pre> -- -- If the accumulating function is strict, then <a>accumArray</a> is -- strict in the values, as well as the indices, in the association list. -- Thus, unlike ordinary arrays built with <a>array</a>, accumulated -- arrays should not in general be recursive. accumArray :: Ix i => (e -> a -> e) -> e -> (i, i) -> [(i, a)] -> Array i e -- | The value at the given index in an array. (!) :: Ix i => Array i e -> i -> e -- | The bounds with which an array was constructed. bounds :: Ix i => Array i e -> (i, i) -- | The list of indices of an array in ascending order. indices :: Ix i => Array i e -> [i] -- | The list of elements of an array in index order. elems :: Ix i => Array i e -> [e] -- | The list of associations of an array in index order. assocs :: Ix i => Array i e -> [(i, e)] -- | Constructs an array identical to the first argument except that it has -- been updated by the associations in the right argument. For example, -- if <tt>m</tt> is a 1-origin, <tt>n</tt> by <tt>n</tt> matrix, then -- -- <pre> -- m//[((i,i), 0) | i <- [1..n]] -- </pre> -- -- is the same matrix, except with the diagonal zeroed. -- -- Repeated indices in the association list are handled as for -- <a>array</a>: the resulting array is undefined (i.e. bottom), (//) :: Ix i => Array i e -> [(i, e)] -> Array i e -- | <tt><a>accum</a> f</tt> takes an array and an association list and -- accumulates pairs from the list into the array with the accumulating -- function <tt>f</tt>. Thus <a>accumArray</a> can be defined using -- <a>accum</a>: -- -- <pre> -- accumArray f z b = accum f (array b [(i, z) | i <- range b]) -- </pre> accum :: Ix i => (e -> a -> e) -> Array i e -> [(i, a)] -> Array i e -- | <a>ixmap</a> allows for transformations on array indices. It may be -- thought of as providing function composition on the right with the -- mapping that the original array embodies. -- -- A similar transformation of array values may be achieved using -- <a>fmap</a> from the <a>Array</a> instance of the <a>Functor</a> -- class. ixmap :: (Ix i, Ix j) => (i, i) -> (i -> j) -> Array j e -> Array i e