-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A small prelude. -- -- A sensible set of defaults for writing custom Preludes. @package protolude @version 0.3.2 module Protolude.Applicative orAlt :: (Alternative f, Monoid a) => f a -> f a orEmpty :: Alternative f => Bool -> a -> f a eitherA :: Alternative f => f a -> f b -> f (Either a b) purer :: (Applicative f, Applicative g) => a -> f (g a) liftAA2 :: (Applicative f, Applicative g) => (a -> b -> c) -> f (g a) -> f (g b) -> f (g c) (<<*>>) :: (Applicative f, Applicative g) => f (g (a -> b)) -> f (g a) -> f (g b) infixl 4 <<*>> module Protolude.Base -- | Append two lists, i.e., -- --

--   [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
--   [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
--

--   main = print ([(n, 2^n) | n <- [0..19]])
--

print :: Show a => a -> IO () -- | 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 Bounded class is used to name the upper and lower limits of -- a type. Ord is not a superclass of Bounded since types -- that are not totally ordered may also have upper and lower bounds. -- -- The Bounded class may be derived for any enumeration type; -- minBound is the first constructor listed in the data -- declaration and maxBound is the last. Bounded may also -- be derived for single-constructor datatypes whose constituent types -- are in Bounded. class Bounded a minBound :: Bounded a => a maxBound :: Bounded a => a -- | Class Enum defines operations on sequentially ordered types. -- -- The enumFrom... methods are used in Haskell's translation of -- arithmetic sequences. -- -- Instances of Enum 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 fromEnum from -- 0 through n-1. See Chapter 10 of the Haskell -- Report for more details. -- -- For any type that is an instance of class Bounded as well as -- Enum, the following should hold: -- --

The calls succ maxBound and pred -- minBound should result in a runtime error.
fromEnum and toEnum should give a runtime error if -- the result value is not representable in the result type. For example, -- toEnum 7 :: Bool is an error.
enumFrom and enumFromThen should be defined with an -- implicit bound, thus:

-- --

--   enumFrom     x   = enumFromTo     x maxBound
--   enumFromThen x y = enumFromThenTo x y bound
--     where
--       bound | fromEnum y >= fromEnum x = maxBound
--             | otherwise                = minBound
--

class Enum a -- | the successor of a value. For numeric types, succ adds 1. succ :: Enum a => a -> a -- | the predecessor of a value. For numeric types, pred subtracts -- 1. pred :: Enum a => a -> a -- | Convert from an Int. toEnum :: Enum a => Int -> a -- | Convert to an Int. It is implementation-dependent what -- fromEnum returns when applied to a value that is too large to -- fit in an Int. fromEnum :: Enum a => a -> Int -- | Used in Haskell's translation of [n..] with [n..] = -- enumFrom n, a possible implementation being enumFrom n = n : -- enumFrom (succ n). For example: -- --

```
enumFrom 4 :: [Integer] = [4,5,6,7,...]
```

enumFrom 6 :: [Int] = [6,7,8,9,...,maxBound ::
--   Int]

enumFrom :: Enum a => a -> [a] -- | Used in Haskell's translation of [n,n'..] with [n,n'..] = -- enumFromThen n n', a possible implementation being -- enumFromThen n n' = n : n' : worker (f x) (f x n'), -- worker s v = v : worker s (s v), x = fromEnum n' - -- fromEnum n and f n y | n > 0 = f (n - 1) (succ y) | n < -- 0 = f (n + 1) (pred y) | otherwise = y For example: -- --

enumFromThen 4 6 :: [Integer] = [4,6,8,10...]

enumFromThen 6 2 :: [Int] = [6,2,-2,-6,...,minBound ::
--   Int]

enumFromThen :: Enum a => a -> a -> [a] -- | Used in Haskell's translation of [n..m] with [n..m] = -- enumFromTo n m, a possible implementation being enumFromTo n -- m | n <= m = n : enumFromTo (succ n) m | otherwise = []. For -- example: -- --

```
enumFromTo 6 10 :: [Int] = [6,7,8,9,10]
```
```
enumFromTo 42 1 :: [Integer] = []
```

enumFromTo :: Enum a => a -> a -> [a] -- | Used in Haskell's translation of [n,n'..m] with [n,n'..m] -- = enumFromThenTo n n' m, a possible implementation being -- enumFromThenTo n n' m = worker (f x) (c x) n m, x = -- fromEnum n' - fromEnum n, c x = bool (>=) ((x -- 0) f n y | n > 0 = f (n - 1) (succ y) | n < 0 = f (n + -- 1) (pred y) | otherwise = y and worker s c v m | c v m = v : -- worker s c (s v) m | otherwise = [] For example: -- --

enumFromThenTo 4 2 -6 :: [Integer] =
--   [4,2,0,-2,-4,-6]

```
enumFromThenTo 6 8 2 :: [Int] = []
```

enumFromThenTo :: Enum a => a -> a -> a -> [a] -- | Trigonometric and hyperbolic functions and related functions. -- -- The Haskell Report defines no laws for Floating. However, -- (+), (*) and exp are -- customarily expected to define an exponential field and have the -- following properties: -- --

exp (a + b) = exp a * exp b
exp (fromInteger 0) = fromInteger 1

class Fractional a => Floating a pi :: Floating a => a exp :: Floating a => a -> a log :: Floating a => a -> a sqrt :: Floating a => a -> a (**) :: Floating a => a -> a -> a logBase :: Floating a => a -> a -> a sin :: Floating a => a -> a cos :: Floating a => a -> a tan :: Floating a => a -> a asin :: Floating a => a -> a acos :: Floating a => a -> a atan :: Floating a => a -> a sinh :: Floating a => a -> a cosh :: Floating a => a -> a tanh :: Floating a => a -> a asinh :: Floating a => a -> a acosh :: Floating a => a -> a atanh :: Floating a => a -> a -- | log1p x computes log (1 + x), but -- provides more precise results for small (absolute) values of -- x if possible. log1p :: Floating a => a -> a -- | expm1 x computes exp x - 1, but -- provides more precise results for small (absolute) values of -- x if possible. expm1 :: Floating a => a -> a -- | log1pexp x computes log (1 + exp -- x), but provides more precise results if possible. -- -- Examples: -- --

if x is a large negative number, log (1 + -- exp x) will be imprecise for the reasons given in -- log1p.
if exp x is close to -1, log -- (1 + exp x) will be imprecise for the reasons given in -- expm1.

log1pexp :: Floating a => a -> a -- | log1mexp x computes log (1 - exp -- x), but provides more precise results if possible. -- -- Examples: -- --

if x is a large negative number, log (1 - -- exp x) will be imprecise for the reasons given in -- log1p.
if exp x is close to 1, log (1 -- - exp x) will be imprecise for the reasons given in -- expm1.

log1mexp :: Floating a => a -> a infixr 8 ** -- | Fractional numbers, supporting real division. -- -- The Haskell Report defines no laws for Fractional. However, -- (+) and (*) are customarily expected -- to define a division ring and have the following properties: -- --

recip gives the multiplicative inverse x -- * recip x = recip x * x = fromInteger 1

-- -- Note that it isn't customarily expected that a type instance of -- Fractional implement a field. However, all instances in -- base do. class Num a => Fractional a -- | Fractional division. (/) :: Fractional a => a -> a -> a -- | Reciprocal fraction. recip :: Fractional a => a -> a -- | Conversion from a Rational (that is Ratio -- Integer). A floating literal stands for an application of -- fromRational to a value of type Rational, so such -- literals have type (Fractional a) => a. fromRational :: Fractional a => Rational -> a infixl 7 / -- | Integral numbers, supporting integer division. -- -- The Haskell Report defines no laws for Integral. However, -- Integral instances are customarily expected to define a -- Euclidean domain and have the following properties for the -- div/mod and quot/rem pairs, given suitable -- Euclidean functions f and g: -- --

x = y * quot x y + rem x y with rem x y -- = fromInteger 0 or g (rem x y) < g -- y
x = y * div x y + mod x y with mod x y -- = fromInteger 0 or f (mod x y) < f -- y

-- -- An example of a suitable Euclidean function, for Integer's -- instance, is abs. class (Real a, Enum a) => Integral a -- | integer division truncated toward zero quot :: Integral a => a -> a -> a -- | integer remainder, satisfying -- --

--   (x `quot` y)*y + (x `rem` y) == x
--

rem :: Integral a => a -> a -> a -- | integer division truncated toward negative infinity div :: Integral a => a -> a -> a -- | integer modulus, satisfying -- --

--   (x `div` y)*y + (x `mod` y) == x
--

mod :: Integral a => a -> a -> a -- | simultaneous quot and rem quotRem :: Integral a => a -> a -> (a, a) -- | simultaneous div and mod divMod :: Integral a => a -> a -> (a, a) -- | conversion to Integer toInteger :: Integral a => a -> Integer infixl 7 `mod` infixl 7 `div` infixl 7 `rem` infixl 7 `quot` -- | Basic numeric class. -- -- The Haskell Report defines no laws for Num. However, -- (+) and (*) are customarily expected -- to define a ring and have the following properties: -- --

Associativity of (+) (x + y) + -- z = x + (y + z)
Commutativity of (+) x + y -- = y + x
fromInteger 0 is the additive -- identity x + fromInteger 0 = x
negate gives the additive inverse x + -- negate x = fromInteger 0
Associativity of (*) (x * y) * -- z = x * (y * z)
fromInteger 1 is the multiplicative -- identity x * fromInteger 1 = x and -- fromInteger 1 * x = x
Distributivity of (*) with respect to -- (+) a * (b + c) = (a * b) + (a * -- c) and (b + c) * a = (b * a) + (c * a)

-- -- Note that it isn't customarily expected that a type instance of -- both Num and Ord implement an ordered ring. Indeed, in -- base only Integer and Rational do. class Num a (+) :: Num a => a -> a -> a (-) :: Num a => a -> a -> a (*) :: Num a => a -> a -> a -- | Unary negation. negate :: Num a => a -> a -- | Absolute value. abs :: Num a => a -> a -- | Sign of a number. The functions abs and signum should -- satisfy the law: -- --

--   abs x * signum x == x
--

-- -- For real numbers, the signum is either -1 (negative), -- 0 (zero) or 1 (positive). signum :: Num a => a -> a -- | Conversion from an Integer. An integer literal represents the -- application of the function fromInteger to the appropriate -- value of type Integer, so such literals have type -- (Num a) => a. fromInteger :: Num a => Integer -> a infixl 6 - infixl 6 + infixl 7 * class (Num a, Ord a) => Real a -- | the rational equivalent of its real argument with full precision toRational :: Real a => a -> Rational -- | Efficient, machine-independent access to the components of a -- floating-point number. class (RealFrac a, Floating a) => RealFloat a -- | a constant function, returning the radix of the representation (often -- 2) floatRadix :: RealFloat a => a -> Integer -- | a constant function, returning the number of digits of -- floatRadix in the significand floatDigits :: RealFloat a => a -> Int -- | a constant function, returning the lowest and highest values the -- exponent may assume floatRange :: RealFloat a => a -> (Int, Int) -- | The function decodeFloat applied to a real floating-point -- number returns the significand expressed as an Integer and an -- appropriately scaled exponent (an Int). If -- decodeFloat x yields (m,n), then x -- is equal in value to m*b^^n, where b is the -- floating-point radix, and furthermore, either m and -- n are both zero or else b^(d-1) <= abs m < -- b^d, where d is the value of floatDigits -- x. In particular, decodeFloat 0 = (0,0). If the -- type contains a negative zero, also decodeFloat (-0.0) = -- (0,0). The result of decodeFloat x is -- unspecified if either of isNaN x or -- isInfinite x is True. decodeFloat :: RealFloat a => a -> (Integer, Int) -- | encodeFloat performs the inverse of decodeFloat in the -- sense that for finite x with the exception of -0.0, -- uncurry encodeFloat (decodeFloat x) = x. -- encodeFloat m n is one of the two closest -- representable floating-point numbers to m*b^^n (or -- ±Infinity if overflow occurs); usually the closer, but if -- m contains too many bits, the result may be rounded in the -- wrong direction. encodeFloat :: RealFloat a => Integer -> Int -> a -- | exponent corresponds to the second component of -- decodeFloat. exponent 0 = 0 and for finite -- nonzero x, exponent x = snd (decodeFloat x) -- + floatDigits x. If x is a finite floating-point -- number, it is equal in value to significand x * b ^^ -- exponent x, where b is the floating-point radix. -- The behaviour is unspecified on infinite or NaN values. exponent :: RealFloat a => a -> Int -- | The first component of decodeFloat, scaled to lie in the open -- interval (-1,1), either 0.0 or of absolute -- value >= 1/b, where b is the floating-point -- radix. The behaviour is unspecified on infinite or NaN -- values. significand :: RealFloat a => a -> a -- | multiplies a floating-point number by an integer power of the radix scaleFloat :: RealFloat a => Int -> a -> a -- | True if the argument is an IEEE "not-a-number" (NaN) value isNaN :: RealFloat a => a -> Bool -- | True if the argument is an IEEE infinity or negative infinity isInfinite :: RealFloat a => a -> Bool -- | True if the argument is too small to be represented in -- normalized format isDenormalized :: RealFloat a => a -> Bool -- | True if the argument is an IEEE negative zero isNegativeZero :: RealFloat a => a -> Bool -- | True if the argument is an IEEE floating point number isIEEE :: RealFloat a => a -> Bool -- | a version of arctangent taking two real floating-point arguments. For -- real floating x and y, atan2 y x -- computes the angle (from the positive x-axis) of the vector from the -- origin to the point (x,y). atan2 y x returns -- a value in the range [-pi, pi]. It follows the -- Common Lisp semantics for the origin when signed zeroes are supported. -- atan2 y 1, with y in a type that is -- RealFloat, should return the same value as atan -- y. A default definition of atan2 is provided, but -- implementors can provide a more accurate implementation. atan2 :: RealFloat a => a -> a -> a -- | Extracting components of fractions. class (Real a, Fractional a) => RealFrac a -- | The function properFraction takes a real fractional number -- x and returns a pair (n,f) such that x = -- n+f, and: -- --

n is an integral number with the same sign as x; -- and
f is a fraction with the same type and sign as -- x, and with absolute value less than 1.

-- -- The default definitions of the ceiling, floor, -- truncate and round functions are in terms of -- properFraction. properFraction :: (RealFrac a, Integral b) => a -> (b, a) -- | truncate x returns the integer nearest x -- between zero and x truncate :: (RealFrac a, Integral b) => a -> b -- | round x returns the nearest integer to x; the -- even integer if x is equidistant between two integers round :: (RealFrac a, Integral b) => a -> b -- | ceiling x returns the least integer not less than -- x ceiling :: (RealFrac a, Integral b) => a -> b -- | floor x returns the greatest integer not greater than -- x floor :: (RealFrac a, Integral b) => a -> b -- | Conversion of values to readable Strings. -- -- Derived instances of Show have the following properties, which -- are compatible with derived instances of Read: -- --

The result of show 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.
If the constructor is defined to be an infix operator, then -- showsPrec will produce infix applications of the -- constructor.
the representation will be enclosed in parentheses if the -- precedence of the top-level constructor in x is less than -- d (associativity is ignored). Thus, if d is -- 0 then the result is never surrounded in parentheses; if -- d is 11 it is always surrounded in parentheses, -- unless it is an atomic expression.
If the constructor is defined using record syntax, then -- show will produce the record-syntax form, with the fields given -- in the same order as the original declaration.

-- -- For example, given the declarations -- --

--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--

-- -- the derived instance of Show is equivalent to -- --

--   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
--

-- -- Note that right-associativity of :^: is ignored. For example, -- --

show (Leaf 1 :^: Leaf 2 :^: Leaf 3) produces the -- string "Leaf 1 :^: (Leaf 2 :^: Leaf 3)".

class Show a -- | Convert a value to a readable String. -- -- showsPrec should satisfy the law -- --

--   showsPrec d x r ++ s  ==  showsPrec d x (r ++ s)
--

-- -- Derived instances of Read and Show satisfy the -- following: -- --

(x,"") is an element of (readsPrec d -- (showsPrec d x "")).

-- -- That is, readsPrec parses the string produced by -- showsPrec, and delivers the value that showsPrec started -- with. showsPrec :: Show a => Int -> a -> ShowS -- | A specialised variant of showsPrec, using precedence context -- zero, and returning an ordinary String. show :: Show a => a -> String -- | The method showList is provided to allow the programmer to give -- a specialised way of showing lists of values. For example, this is -- used by the predefined Show instance of the Char type, -- where values of type String should be shown in double quotes, -- rather than between square brackets. showList :: Show a => [a] -> ShowS -- | This class gives the integer associated with a type-level natural. -- There are instances of the class for every concrete literal: 0, 1, 2, -- etc. class KnownNat (n :: Nat) -- | This class gives the string associated with a type-level symbol. There -- are instances of the class for every concrete literal: "hello", etc. class KnownSymbol (n :: Symbol) class IsLabel (x :: Symbol) a fromLabel :: IsLabel x a => a -- | Constraint representing the fact that the field x belongs to -- the record type r and has field type a. This will be -- solved automatically, but manual instances may be provided as well. class HasField (x :: k) r a | x r -> a -- | Selector function to extract the field from the record. getField :: HasField x r a => r -> a data Bool -- | The character type Char is an enumeration whose values -- represent Unicode (or equivalently ISO/IEC 10646) code points (i.e. -- characters, see http://www.unicode.org/ 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 -- Char. -- -- To convert a Char to or from the corresponding Int value -- defined by Unicode, use toEnum and fromEnum from the -- Enum class respectively (or equivalently ord and -- chr). data Char -- | 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 D# :: Double# -> Double -- | 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 F# :: Float# -> Float -- | A fixed-precision integer type with at least the range [-2^29 .. -- 2^29-1]. The exact range for a given implementation can be -- determined by using minBound and maxBound from the -- Bounded class. data Int -- | Arbitrary precision integers. In contrast with fixed-size integral -- types such as Int, the Integer type represents the -- entire infinite range of integers. -- -- For more information about this type's representation, see the -- comments in its implementation. data Integer data Ordering -- | Rational numbers, with numerator and denominator of some -- Integral type. -- -- Note that Ratio's instances inherit the deficiencies from the -- type parameter's. For example, Ratio Natural's Num -- instance has similar problems to Natural's. data Ratio a -- | Arbitrary-precision rational numbers, represented as a ratio of two -- Integer values. A rational number may be constructed using the -- % operator. type Rational = Ratio Integer -- | A value of type IO a is a computation which, when -- performed, does some I/O before returning a value of type a. -- -- There is really only one way to "perform" an I/O action: bind it to -- Main.main 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 IO monad and -- called at some point, directly or indirectly, from Main.main. -- -- IO is a monad, so IO actions can be combined using -- either the do-notation or the >> and >>= -- operations from the Monad class. data IO a -- | A Word is an unsigned integral type, with the same size as -- Int. data Word -- | A value of type Ptr a represents a pointer to an -- object, or an array of objects, which may be marshalled to or from -- Haskell values of type a. -- -- The type a will often be an instance of class Storable -- 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 struct. data Ptr a -- | A value of type FunPtr a is a pointer to a function -- callable from foreign code. The type a will normally be a -- foreign type, a function type with zero or more arguments where -- --

the argument types are marshallable foreign types, i.e. -- Char, Int, Double, Float, Bool, -- Int8, Int16, Int32, Int64, Word8, -- Word16, Word32, Word64, Ptr a, -- FunPtr a, StablePtr a or a renaming of -- any of these using newtype.
the return type is either a marshallable foreign type or has the -- form IO t where t is a marshallable foreign -- type or ().

-- -- A value of type FunPtr a may be a pointer to a foreign -- function, either returned by another foreign function or imported with -- a a static address import like -- --

--   foreign import ccall "stdlib.h &free"
--     p_free :: FunPtr (Ptr a -> IO ())
--

-- -- or a pointer to a Haskell function created using a wrapper stub -- declared to produce a FunPtr of the correct type. For example: -- --

--   type Compare = Int -> Int -> Bool
--   foreign import ccall "wrapper"
--     mkCompare :: Compare -> IO (FunPtr Compare)
--

-- -- Calls to wrapper stubs like mkCompare allocate storage, which -- should be released with freeHaskellFunPtr when no longer -- required. -- -- To convert FunPtr values to corresponding Haskell functions, -- one can define a dynamic stub for the specific foreign type, -- e.g. -- --

--   type IntFunction = CInt -> IO ()
--   foreign import ccall "dynamic"
--     mkFun :: FunPtr IntFunction -> IntFunction
--

data FunPtr a -- | The kind of types with lifted values. For example Int :: -- Type. type Type = Type -- | The kind of constraints, like Show a data Constraint -- | (Kind) This is the kind of type-level natural numbers. data Nat -- | (Kind) This is the kind of type-level symbols. Declared here because -- class IP needs it data Symbol -- | Comparison of type-level naturals, as a function. type family CmpNat (a :: Nat) (b :: Nat) :: Ordering -- | Coercible is a two-parameter class that has instances for -- types a and b if the compiler can infer that they -- have the same representation. This class does not have regular -- instances; instead they are created on-the-fly during type-checking. -- Trying to manually declare an instance of Coercible is an -- error. -- -- Nevertheless one can pretend that the following three kinds of -- instances exist. First, as a trivial base-case: -- --

--   instance Coercible a a
--

-- -- Furthermore, for every type constructor there is an instance that -- allows to coerce under the type constructor. For example, let -- D be a prototypical type constructor (data or -- newtype) with three type arguments, which have roles -- nominal, representational resp. phantom. -- Then there is an instance of the form -- --

--   instance Coercible b b' => Coercible (D a b c) (D a b' c')
--

-- -- Note that the nominal type arguments are equal, the -- representational type arguments can differ, but need to have -- a Coercible instance themself, and the phantom type -- arguments can be changed arbitrarily. -- -- The third kind of instance exists for every newtype NT = MkNT -- T and comes in two variants, namely -- --

--   instance Coercible a T => Coercible a NT
--

-- --

--   instance Coercible T b => Coercible NT b
--

-- -- This instance is only usable if the constructor MkNT is in -- scope. -- -- If, as a library author of a type constructor like Set a, you -- want to prevent a user of your module to write coerce :: Set T -- -> Set NT, you need to set the role of Set's type -- parameter to nominal, by writing -- --

--   type role Set nominal
--

-- -- For more details about this feature, please refer to Safe -- Coercions by Joachim Breitner, Richard A. Eisenberg, Simon Peyton -- Jones and Stephanie Weirich. class a ~R# b => Coercible (a :: k) (b :: k) -- | A reference to a value of type a. data StaticPtr a -- | CallStacks are a lightweight method of obtaining a partial -- call-stack at any point in the program. -- -- A function can request its call-site with the HasCallStack -- constraint. For example, we can define -- --

--   putStrLnWithCallStack :: HasCallStack => String -> IO ()
--

-- -- as a variant of putStrLn that will get its call-site and -- print it, along with the string given as argument. We can access the -- call-stack inside putStrLnWithCallStack with -- callStack. -- --

--   putStrLnWithCallStack :: HasCallStack => String -> IO ()
--   putStrLnWithCallStack msg = do
--     putStrLn msg
--     putStrLn (prettyCallStack callStack)
--

-- -- Thus, if we call putStrLnWithCallStack we will get a -- formatted call-stack alongside our string. -- --

--   >>> putStrLnWithCallStack "hello"
--   hello
--   CallStack (from HasCallStack):
--     putStrLnWithCallStack, called at <interactive>:2:1 in interactive:Ghci1
--

-- -- GHC solves HasCallStack constraints in three steps: -- --

If there is a CallStack in scope -- i.e. the enclosing -- function has a HasCallStack constraint -- GHC will append the -- new call-site to the existing CallStack.
If there is no CallStack in scope -- e.g. in the GHCi -- session above -- and the enclosing definition does not have an -- explicit type signature, GHC will infer a HasCallStack -- constraint for the enclosing definition (subject to the monomorphism -- restriction).
If there is no CallStack in scope and the enclosing -- definition has an explicit type signature, GHC will solve the -- HasCallStack constraint for the singleton CallStack -- containing just the current call-site.

-- -- CallStacks do not interact with the RTS and do not require -- compilation with -prof. On the other hand, as they are built -- up explicitly via the HasCallStack constraints, they will -- generally not contain as much information as the simulated call-stacks -- maintained by the RTS. -- -- A CallStack is a [(String, SrcLoc)]. The -- String is the name of function that was called, the -- SrcLoc is the call-site. The list is ordered with the most -- recently called function at the head. -- -- NOTE: The intrepid user may notice that HasCallStack is just an -- alias for an implicit parameter ?callStack :: CallStack. This -- is an implementation detail and should not be considered part -- of the CallStack API, we may decide to change the -- implementation in the future. data CallStack -- | Get a string representation of the current execution stack state. showStackTrace :: IO (Maybe String) -- | Get a trace of the current execution stack state. -- -- Returns Nothing if stack trace support isn't available on -- host machine. getStackTrace :: IO (Maybe [Location]) -- | A location in the original program source. data SrcLoc SrcLoc :: String -> Int -> Int -> SrcLoc -- | Location information about an address from a backtrace. data Location Location :: String -> String -> Maybe SrcLoc -> Location [objectName] :: Location -> String [functionName] :: Location -> String [srcLoc] :: Location -> Maybe SrcLoc -- | The same as putStr, but adds a newline character. putStrLn :: String -> IO () -- | Write a string to the standard output device (same as hPutStr -- stdout). putStr :: String -> IO () -- | Perform some computation without adding new entries to the -- CallStack. withFrozenCallStack :: HasCallStack => (HasCallStack => a) -> a -- | Return the current CallStack. -- -- Does *not* include the call-site of callStack. callStack :: HasCallStack => CallStack -- | Pretty print a CallStack. prettyCallStack :: CallStack -> String -- | Pretty print a SrcLoc. prettySrcLoc :: SrcLoc -> String -- | Convert a string into an unknown type-level symbol. someSymbolVal :: String -> SomeSymbol -- | Convert an integer into an unknown type-level natural. someNatVal :: Integer -> Maybe SomeNat symbolVal :: forall (n :: Symbol) proxy. KnownSymbol n => proxy n -> String natVal :: forall (n :: Nat) proxy. KnownNat n => proxy n -> Integer -- | This type represents unknown type-level symbols. data SomeSymbol SomeSymbol :: Proxy n -> SomeSymbol -- | This type represents unknown type-level natural numbers. data SomeNat SomeNat :: Proxy n -> SomeNat showSignedFloat :: RealFloat a => (a -> ShowS) -> Int -> a -> ShowS -- | Show a signed RealFloat value to full precision using standard -- decimal notation for arguments whose absolute value lies between -- 0.1 and 9,999,999, and scientific notation -- otherwise. showFloat :: RealFloat a => a -> ShowS integralEnumFromThenTo :: Integral a => a -> a -> a -> [a] integralEnumFromTo :: Integral a => a -> a -> [a] integralEnumFromThen :: (Integral a, Bounded a) => a -> a -> [a] integralEnumFrom :: (Integral a, Bounded a) => a -> [a] -- | lcm x y is the smallest positive integer that both -- x and y divide. lcm :: Integral a => a -> a -> a -- | gcd x y is the non-negative factor of both x -- and y of which every common factor of x and -- y is also a factor; for example gcd 4 2 = 2, -- gcd (-4) 6 = 2, gcd 0 4 = 4. -- gcd 0 0 = 0. (That is, the common divisor -- that is "greatest" in the divisibility preordering.) -- -- Note: Since for signed fixed-width integer types, abs -- minBound < 0, the result may be negative if one of the -- arguments is minBound (and necessarily is if the other -- is 0 or minBound) for such types. gcd :: Integral a => a -> a -> a (^^%^^) :: Integral a => Rational -> a -> Rational (^%^) :: Integral a => Rational -> a -> Rational -- | raise a number to an integral power (^^) :: (Fractional a, Integral b) => a -> b -> a infixr 8 ^^ -- | raise a number to a non-negative integral power (^) :: (Num a, Integral b) => a -> b -> a infixr 8 ^ odd :: Integral a => a -> Bool even :: Integral a => a -> Bool -- | Converts a possibly-negative Real value to a string. showSigned :: Real a => (a -> ShowS) -> Int -> a -> ShowS numericEnumFromThenTo :: (Ord a, Fractional a) => a -> a -> a -> [a] numericEnumFromTo :: (Ord a, Fractional a) => a -> a -> [a] numericEnumFromThen :: Fractional a => a -> a -> [a] numericEnumFrom :: Fractional a => 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 :: Ratio a -> a -- | Extract the numerator of the ratio in reduced form: the numerator and -- denominator have no common factor and the denominator is positive. numerator :: Ratio a -> a -- | Forms the ratio of two integral numbers. (%) :: Integral a => a -> a -> Ratio a infixl 7 % -- | reduce is a subsidiary function used only in this module. It -- normalises a ratio by dividing both numerator and denominator by their -- greatest common divisor. reduce :: Integral a => a -> a -> Ratio a notANumber :: Rational infinity :: Rational ratioPrec1 :: Int ratioPrec :: Int underflowError :: a overflowError :: a ratioZeroDenominatorError :: a divZeroError :: a boundedEnumFromThen :: (Enum a, Bounded a) => a -> a -> [a] boundedEnumFrom :: (Enum a, Bounded a) => a -> [a] -- | the same as flip (-). -- -- Because - is treated specially in the Haskell grammar, -- (- e) is not a section, but an application of -- prefix negation. However, (subtract -- exp) is equivalent to the disallowed section. subtract :: Num a => a -> a -> a -- | Returns a [String] representing the current call stack. This -- can be useful for debugging. -- -- The implementation uses the call-stack simulation maintained by the -- profiler, so it only works if the program was compiled with -- -prof and contains suitable SCC annotations (e.g. by using -- -fprof-auto). Otherwise, the list returned is likely to be -- empty or uninformative. currentCallStack :: IO [String] -- | asTypeOf is a type-restricted version of const. 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 -- | until p f yields the result of applying f -- until p holds. until :: (a -> Bool) -> (a -> a) -> a -> a maxInt :: Int minInt :: Int -- | The fromEnum method restricted to the type Char. ord :: Char -> Int -- | Extract a list of call-sites from the CallStack. -- -- The list is ordered by most recent call. getCallStack :: CallStack -> [([Char], SrcLoc)] -- | Request a CallStack. -- -- NOTE: The implicit parameter ?callStack :: CallStack is an -- implementation detail and should not be considered part of the -- CallStack API, we may decide to change the implementation in -- the future. type HasCallStack = ?callStack :: CallStack ($!) :: (a -> b) -> a -> b infixr 0 $! module Protolude.Bifunctor class Bifunctor p bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d first :: Bifunctor p => (a -> b) -> p a c -> p b c second :: Bifunctor p => (b -> c) -> p a b -> p a c instance Protolude.Bifunctor.Bifunctor (,) instance Protolude.Bifunctor.Bifunctor ((,,) x1) instance Protolude.Bifunctor.Bifunctor ((,,,) x1 x2) instance Protolude.Bifunctor.Bifunctor ((,,,,) x1 x2 x3) instance Protolude.Bifunctor.Bifunctor ((,,,,,) x1 x2 x3 x4) instance Protolude.Bifunctor.Bifunctor ((,,,,,,) x1 x2 x3 x4 x5) instance Protolude.Bifunctor.Bifunctor Data.Either.Either instance Protolude.Bifunctor.Bifunctor Data.Functor.Const.Const module Protolude.Bool whenM :: Monad m => m Bool -> m () -> m () unlessM :: Monad m => m Bool -> m () -> m () ifM :: Monad m => m Bool -> m a -> m a -> m a guardM :: MonadPlus m => m Bool -> m () bool :: a -> a -> Bool -> a -- | The && operator lifted to a monad. If the first -- argument evaluates to False the second argument will not be -- evaluated. (&&^) :: Monad m => m Bool -> m Bool -> m Bool infixr 3 &&^ -- | The || operator lifted to a monad. If the first argument -- evaluates to True the second argument will not be evaluated. (||^) :: Monad m => m Bool -> m Bool -> m Bool infixr 2 ||^ -- | && lifted to an Applicative. Unlike &&^ -- the operator is not short-circuiting. (<&&>) :: Applicative a => a Bool -> a Bool -> a Bool infixr 3 <&&> -- | || lifted to an Applicative. Unlike ||^ the operator is -- not short-circuiting. (<||>) :: Applicative a => a Bool -> a Bool -> a Bool infixr 2 <||> module Protolude.CallStack -- | Request a CallStack. -- -- NOTE: The implicit parameter ?callStack :: CallStack is an -- implementation detail and should not be considered part of the -- CallStack API, we may decide to change the implementation in -- the future. type HasCallStack = ?callStack :: CallStack -- | An alternative to ConvertText that includes partial -- conversions. Not re-exported by Protolude. module Protolude.Conv class StringConv a b strConv :: StringConv a b => Leniency -> a -> b toS :: StringConv a b => a -> b toSL :: StringConv a b => a -> b data Leniency Lenient :: Leniency Strict :: Leniency instance GHC.Enum.Bounded Protolude.Conv.Leniency instance GHC.Enum.Enum Protolude.Conv.Leniency instance GHC.Classes.Ord Protolude.Conv.Leniency instance GHC.Show.Show Protolude.Conv.Leniency instance GHC.Classes.Eq Protolude.Conv.Leniency instance Protolude.Conv.StringConv GHC.Base.String GHC.Base.String instance Protolude.Conv.StringConv GHC.Base.String Data.ByteString.Internal.ByteString instance Protolude.Conv.StringConv GHC.Base.String Data.ByteString.Lazy.Internal.ByteString instance Protolude.Conv.StringConv GHC.Base.String Data.Text.Internal.Text instance Protolude.Conv.StringConv GHC.Base.String Data.Text.Internal.Lazy.Text instance Protolude.Conv.StringConv Data.ByteString.Internal.ByteString GHC.Base.String instance Protolude.Conv.StringConv Data.ByteString.Internal.ByteString Data.ByteString.Internal.ByteString instance Protolude.Conv.StringConv Data.ByteString.Internal.ByteString Data.ByteString.Lazy.Internal.ByteString instance Protolude.Conv.StringConv Data.ByteString.Internal.ByteString Data.Text.Internal.Text instance Protolude.Conv.StringConv Data.ByteString.Internal.ByteString Data.Text.Internal.Lazy.Text instance Protolude.Conv.StringConv Data.ByteString.Lazy.Internal.ByteString GHC.Base.String instance Protolude.Conv.StringConv Data.ByteString.Lazy.Internal.ByteString Data.ByteString.Internal.ByteString instance Protolude.Conv.StringConv Data.ByteString.Lazy.Internal.ByteString Data.ByteString.Lazy.Internal.ByteString instance Protolude.Conv.StringConv Data.ByteString.Lazy.Internal.ByteString Data.Text.Internal.Text instance Protolude.Conv.StringConv Data.ByteString.Lazy.Internal.ByteString Data.Text.Internal.Lazy.Text instance Protolude.Conv.StringConv Data.Text.Internal.Text GHC.Base.String instance Protolude.Conv.StringConv Data.Text.Internal.Text Data.ByteString.Internal.ByteString instance Protolude.Conv.StringConv Data.Text.Internal.Text Data.ByteString.Lazy.Internal.ByteString instance Protolude.Conv.StringConv Data.Text.Internal.Text Data.Text.Internal.Lazy.Text instance Protolude.Conv.StringConv Data.Text.Internal.Text Data.Text.Internal.Text instance Protolude.Conv.StringConv Data.Text.Internal.Lazy.Text GHC.Base.String instance Protolude.Conv.StringConv Data.Text.Internal.Lazy.Text Data.Text.Internal.Text instance Protolude.Conv.StringConv Data.Text.Internal.Lazy.Text Data.Text.Internal.Lazy.Text instance Protolude.Conv.StringConv Data.Text.Internal.Lazy.Text Data.ByteString.Lazy.Internal.ByteString instance Protolude.Conv.StringConv Data.Text.Internal.Lazy.Text Data.ByteString.Internal.ByteString -- | Non-partial text conversion typeclass and functions. For an -- alternative with partial conversions import Conv. module Protolude.ConvertText -- | Convert from one Unicode textual type to another. Not for -- serialization/deserialization, so doesn't have instances for -- bytestrings. class ConvertText a b toS :: ConvertText a b => a -> b toUtf8 :: ConvertText a Text => a -> ByteString toUtf8Lazy :: ConvertText a Text => a -> ByteString instance Protolude.ConvertText.ConvertText GHC.Base.String GHC.Base.String instance Protolude.ConvertText.ConvertText GHC.Base.String Data.Text.Internal.Text instance Protolude.ConvertText.ConvertText GHC.Base.String Data.Text.Internal.Lazy.Text instance Protolude.ConvertText.ConvertText Data.Text.Internal.Text GHC.Base.String instance Protolude.ConvertText.ConvertText Data.Text.Internal.Text Data.Text.Internal.Lazy.Text instance Protolude.ConvertText.ConvertText Data.Text.Internal.Text Data.Text.Internal.Text instance Protolude.ConvertText.ConvertText Data.Text.Internal.Lazy.Text GHC.Base.String instance Protolude.ConvertText.ConvertText Data.Text.Internal.Lazy.Text Data.Text.Internal.Text instance Protolude.ConvertText.ConvertText Data.Text.Internal.Lazy.Text Data.Text.Internal.Lazy.Text instance Protolude.ConvertText.ConvertText Data.ByteString.Lazy.Internal.ByteString Data.ByteString.Internal.ByteString instance Protolude.ConvertText.ConvertText Data.ByteString.Lazy.Internal.ByteString Data.ByteString.Lazy.Internal.ByteString instance Protolude.ConvertText.ConvertText Data.ByteString.Internal.ByteString Data.ByteString.Internal.ByteString instance Protolude.ConvertText.ConvertText Data.ByteString.Internal.ByteString Data.ByteString.Lazy.Internal.ByteString module Protolude.Either maybeToLeft :: r -> Maybe l -> Either l r maybeToRight :: l -> Maybe r -> Either l r leftToMaybe :: Either l r -> Maybe l rightToMaybe :: Either l r -> Maybe r maybeEmpty :: Monoid b => (a -> b) -> Maybe a -> b maybeToEither :: e -> Maybe a -> Either e a -- | Return the contents of a Left-value or a default value -- otherwise. -- --

Examples

-- -- Basic usage: -- --

--   >>> fromLeft 1 (Left 3)
--   3
--   
--   >>> fromLeft 1 (Right "foo")
--   1
--

fromLeft :: a -> Either a b -> a -- | Return the contents of a Right-value or a default value -- otherwise. -- --

Examples

-- -- Basic usage: -- --

--   >>> fromRight 1 (Right 3)
--   3
--   
--   >>> fromRight 1 (Left "foo")
--   1
--

fromRight :: b -> Either a b -> b module Protolude.Error -- | Warning: error remains in code error :: forall (r :: RuntimeRep). forall (a :: TYPE r). HasCallStack => Text -> a module Protolude.Exceptions hush :: Alternative m => Either e a -> m a note :: MonadError e m => e -> Maybe a -> m a tryIO :: MonadIO m => IO a -> ExceptT IOException m a module Protolude.Functor -- | A type f is a Functor if it provides a function fmap -- which, given any types a and b lets you apply any -- function from (a -> b) to turn an f a into an -- f b, preserving the structure of f. Furthermore -- f needs to adhere to the following: -- --

Identity fmap id == id
Composition fmap (f . g) == fmap f . -- fmap g

-- -- Note, that the second law follows from the free theorem of the type -- fmap and the first law, so you need only check that the former -- condition holds. class Functor (f :: Type -> Type) -- | Using ApplicativeDo: 'fmap f as' can be -- understood as the do expression -- --

--   do a <- as
--      pure (f a)
--

-- -- with an inferred Functor constraint. fmap :: Functor f => (a -> b) -> f a -> f b -- | Flipped version of <$. -- -- Using ApplicativeDo: 'as $> b' can be -- understood as the do expression -- --

--   do as
--      pure b
--

-- -- with an inferred Functor constraint. -- --

Examples

-- -- Replace the contents of a Maybe Int with a -- constant String: -- --

--   >>> Nothing $> "foo"
--   Nothing
--   
--   >>> Just 90210 $> "foo"
--   Just "foo"
--

-- -- Replace the contents of an Either Int -- Int with a constant String, resulting in an -- Either Int String: -- --

--   >>> Left 8675309 $> "foo"
--   Left 8675309
--   
--   >>> Right 8675309 $> "foo"
--   Right "foo"
--

-- -- Replace each element of a list with a constant String: -- --

--   >>> [1,2,3] $> "foo"
--   ["foo","foo","foo"]
--

-- -- Replace the second element of a pair with a constant String: -- --

--   >>> (1,2) $> "foo"
--   (1,"foo")
--

($>) :: Functor f => f a -> b -> f b infixl 4 $> -- | Replace all locations in the input with the same value. The default -- definition is fmap . const, but this may be -- overridden with a more efficient version. -- -- Using ApplicativeDo: 'a <$ bs' can be -- understood as the do expression -- --

--   do bs
--      pure a
--

-- -- with an inferred Functor constraint. (<$) :: Functor f => a -> f b -> f a infixl 4 <$ -- | An infix synonym for fmap. -- -- The name of this operator is an allusion to $. Note the -- similarities between their types: -- --

--    ($)  ::              (a -> b) ->   a ->   b
--   (<$>) :: Functor f => (a -> b) -> f a -> f b
--

-- -- Whereas $ is function application, <$> is function -- application lifted over a Functor. -- --

Examples

-- -- Convert from a Maybe Int to a Maybe -- String using show: -- --

--   >>> show <$> Nothing
--   Nothing
--   
--   >>> show <$> Just 3
--   Just "3"
--

-- -- Convert from an Either Int Int to an -- Either Int String using show: -- --

--   >>> show <$> Left 17
--   Left 17
--   
--   >>> show <$> Right 17
--   Right "17"
--

-- -- Double each element of a list: -- --

--   >>> (*2) <$> [1,2,3]
--   [2,4,6]
--

-- -- Apply even to the second element of a pair: -- --

--   >>> even <$> (2,2)
--   (2,True)
--

(<$>) :: Functor f => (a -> b) -> f a -> f b infixl 4 <$> (<<$>>) :: (Functor f, Functor g) => (a -> b) -> f (g a) -> f (g b) infixl 4 <<$>> -- | Flipped version of <$>. -- --

--   (<&>) = flip fmap
--

-- --

Examples

-- -- Apply (+1) to a list, a Just and a Right: -- --

--   >>> Just 2 <&> (+1)
--   Just 3
--

-- --

--   >>> [1,2,3] <&> (+1)
--   [2,3,4]
--

-- --

--   >>> Right 3 <&> (+1)
--   Right 4
--

(<&>) :: Functor f => f a -> (a -> b) -> f b infixl 1 <&> -- | void value discards or ignores the result of -- evaluation, such as the return value of an IO action. -- -- Using ApplicativeDo: 'void as' can be -- understood as the do expression -- --

--   do as
--      pure ()
--

-- -- with an inferred Functor constraint. -- --

Examples

-- -- Replace the contents of a Maybe Int with unit: -- --

--   >>> void Nothing
--   Nothing
--   
--   >>> void (Just 3)
--   Just ()
--

-- -- Replace the contents of an Either Int -- Int with unit, resulting in an Either -- Int (): -- --

--   >>> void (Left 8675309)
--   Left 8675309
--   
--   >>> void (Right 8675309)
--   Right ()
--

-- -- Replace every element of a list with unit: -- --

--   >>> void [1,2,3]
--   [(),(),()]
--

-- -- Replace the second element of a pair with unit: -- --

--   >>> void (1,2)
--   (1,())
--

-- -- Discard the result of an IO action: -- --

--   >>> mapM print [1,2]
--   1
--   2
--   [(),()]
--   
--   >>> void $ mapM print [1,2]
--   1
--   2
--

void :: Functor f => f a -> f () foreach :: Functor f => f a -> (a -> b) -> f b module Protolude.List head :: Foldable f => f a -> Maybe a ordNub :: Ord a => [a] -> [a] sortOn :: Ord o => (a -> o) -> [a] -> [a] list :: [b] -> (a -> b) -> [a] -> [b] product :: (Foldable f, Num a) => f a -> a sum :: (Foldable f, Num a) => f a -> a -- | The groupBy function is the non-overloaded version of -- group. groupBy :: (a -> a -> Bool) -> [a] -> [[a]] module Protolude.Monad -- | The Monad class defines the basic operations over a -- monad, a concept from a branch of mathematics known as -- category theory. From the perspective of a Haskell programmer, -- however, it is best to think of a monad as an abstract datatype -- of actions. Haskell's do expressions provide a convenient -- syntax for writing monadic expressions. -- -- Instances of Monad should satisfy the following: -- --

Left identity return a >>= k = k -- a
Right identity m >>= return = -- m
Associativity m >>= (\x -> k x -- >>= h) = (m >>= k) >>= -- h

-- -- Furthermore, the Monad and Applicative operations should -- relate as follows: -- --

```
pure = return
```

m1 <*> m2 = m1 >>= (x1 -> m2
--   >>= (x2 -> return (x1 x2)))

-- -- The above laws imply: -- --

```
fmap f xs = xs >>= return .
--   f
```
```
(>>) = (*>)
```

-- -- and that pure and (<*>) satisfy the applicative -- functor laws. -- -- The instances of Monad for lists, Maybe and IO -- defined in the Prelude satisfy these laws. class Applicative m => Monad (m :: Type -> Type) -- | Sequentially compose two actions, passing any value produced by the -- first as an argument to the second. -- -- 'as >>= bs' can be understood as the do -- expression -- --

--   do a <- as
--      bs a
--

(>>=) :: Monad m => m a -> (a -> m b) -> m b -- | Inject a value into the monadic type. return :: Monad m => a -> m a infixl 1 >>= -- | Monads that also support choice and failure. class (Alternative m, Monad m) => MonadPlus (m :: Type -> Type) -- | The identity of mplus. It should also satisfy the equations -- --

--   mzero >>= f  =  mzero
--   v >> mzero   =  mzero
--

-- -- The default definition is -- --

--   mzero = empty
--

mzero :: MonadPlus m => m a -- | An associative operation. The default definition is -- --

--   mplus = (<|>)
--

mplus :: MonadPlus m => m a -> m a -> m a -- | Same as >>=, but with the arguments interchanged. (=<<) :: Monad m => (a -> m b) -> m a -> m b infixr 1 =<< -- | Left-to-right composition of Kleisli arrows. -- -- '(bs >=> cs) a' can be understood as the -- do expression -- --

--   do b <- bs a
--      cs b
--

(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c infixr 1 >=> -- | Right-to-left composition of Kleisli arrows. -- (>=>), with the arguments flipped. -- -- Note how this operator resembles function composition -- (.): -- --

--   (.)   ::            (b ->   c) -> (a ->   b) -> a ->   c
--   (<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
--

(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c infixr 1 <=< -- | Sequentially compose two actions, discarding any value produced by the -- first, like sequencing operators (such as the semicolon) in imperative -- languages. -- -- 'as >> bs' can be understood as the do -- expression -- --

--   do as
--      bs
--

(>>) :: Monad m => m a -> m b -> m b infixl 1 >> -- | Repeat an action indefinitely. -- -- Using ApplicativeDo: 'forever as' can be -- understood as the pseudo-do expression -- --

--   do as
--      as
--      ..
--

-- -- with as repeating. -- --

Examples

-- -- A common use of forever is to process input from network -- sockets, Handles, and channels (e.g. MVar and -- Chan). -- -- For example, here is how we might implement an echo server, -- using forever both to listen for client connections on a -- network socket and to echo client input on client connection handles: -- --

--   echoServer :: Socket -> IO ()
--   echoServer socket = forever $ do
--     client <- accept socket
--     forkFinally (echo client) (\_ -> hClose client)
--     where
--       echo :: Handle -> IO ()
--       echo client = forever $
--         hGetLine client >>= hPutStrLn client
--

forever :: Applicative f => f a -> f b -- | The join 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 bss' can be understood as the do -- expression -- --

--   do bs <- bss
--      bs
--

-- --

Examples

-- -- A common use of join is to run an IO computation -- returned from an STM transaction, since STM transactions -- can't perform IO directly. Recall that -- --

--   atomically :: STM a -> IO a
--

-- -- is used to run STM transactions atomically. So, by specializing -- the types of atomically and join to -- --

--   atomically :: STM (IO b) -> IO (IO b)
--   join       :: IO (IO b)  -> IO b
--

-- -- we can compose them as -- --

--   join . atomically :: STM (IO b) -> IO b
--

-- -- to run an STM transaction and the IO action it returns. join :: Monad m => m (m a) -> m a -- | Direct MonadPlus equivalent of filter. -- --

Examples

-- -- The filter function is just mfilter specialized to the -- list monad: -- --

--   filter = ( mfilter :: (a -> Bool) -> [a] -> [a] )
--

-- -- An example using mfilter with the Maybe monad: -- --

--   >>> mfilter odd (Just 1)
--   Just 1
--   >>> mfilter odd (Just 2)
--   Nothing
--

mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a -- | This generalizes the list-based filter function. filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a] -- | The mapAndUnzipM 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 monad. mapAndUnzipM :: Applicative m => (a -> m (b, c)) -> [a] -> m ([b], [c]) -- | The zipWithM function generalizes zipWith to arbitrary -- applicative functors. zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c] -- | zipWithM_ is the extension of zipWithM which ignores the -- final result. zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m () -- | The foldM function is analogous to foldl, except that -- its result is encapsulated in a monad. Note that foldM works -- from left-to-right over the list arguments. This could be an issue -- where (>>) and the `folded function' are not -- commutative. -- --

--   foldM f a1 [x1, x2, ..., xm]
--   
--   ==
--   
--   do
--     a2 <- f a1 x1
--     a3 <- f a2 x2
--     ...
--     f am xm
--

-- -- If right-to-left evaluation is required, the input list should be -- reversed. -- -- Note: foldM is the same as foldlM foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b -- | Like foldM, but discards the result. foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m () -- | replicateM n act performs the action n times, -- gathering the results. -- -- Using ApplicativeDo: 'replicateM 5 as' can be -- understood as the do expression -- --

--   do a1 <- as
--      a2 <- as
--      a3 <- as
--      a4 <- as
--      a5 <- as
--      pure [a1,a2,a3,a4,a5]
--

-- -- Note the Applicative constraint. replicateM :: Applicative m => Int -> m a -> m [a] -- | Like replicateM, but discards the result. replicateM_ :: Applicative m => Int -> m a -> m () concatMapM :: Monad m => (a -> m [b]) -> [a] -> m [b] -- | Conditional failure of Alternative computations. Defined by -- --

--   guard True  = pure ()
--   guard False = empty
--

-- --

Examples

-- -- Common uses of guard include conditionally signaling an error -- in an error monad and conditionally rejecting the current choice in an -- Alternative-based parser. -- -- As an example of signaling an error in the error monad Maybe, -- consider a safe division function safeDiv x y that returns -- Nothing when the denominator y is zero and -- Just (x `div` y) otherwise. For example: -- --

--   >>> safeDiv 4 0
--   Nothing
--   >>> safeDiv 4 2
--   Just 2
--

-- -- A definition of safeDiv using guards, but not guard: -- --

--   safeDiv :: Int -> Int -> Maybe Int
--   safeDiv x y | y /= 0    = Just (x `div` y)
--               | otherwise = Nothing
--

-- -- A definition of safeDiv using guard and Monad -- do-notation: -- --

--   safeDiv :: Int -> Int -> Maybe Int
--   safeDiv x y = do
--     guard (y /= 0)
--     return (x `div` y)
--

guard :: Alternative f => Bool -> f () -- | Conditional execution of Applicative expressions. For example, -- --

--   when debug (putStrLn "Debugging")
--

-- -- will output the string Debugging if the Boolean value -- debug is True, and otherwise do nothing. when :: Applicative f => Bool -> f () -> f () -- | The reverse of when. unless :: Applicative f => Bool -> f () -> f () -- | 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, -- --

--   liftM2 (+) [0,1] [0,2] = [0,2,1,3]
--   liftM2 (+) (Just 1) Nothing = Nothing
--

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. liftM2). 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. liftM2). 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. liftM2). liftM5 :: Monad m => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r liftM' :: Monad m => (a -> b) -> m a -> m b liftM2' :: Monad m => (a -> b -> c) -> m a -> m b -> m c -- | In many situations, the liftM operations can be replaced by -- uses of ap, which promotes function application. -- --

--   return f `ap` x1 `ap` ... `ap` xn
--

-- -- is equivalent to -- --

--   liftMn f x1 x2 ... xn
--

ap :: Monad m => m (a -> b) -> m a -> m b -- | Strict version of <$>. (<$!>) :: Monad m => (a -> b) -> m a -> m b infixl 4 <$!> module Protolude.Panic -- | Uncatchable exceptions thrown and never caught. newtype FatalError FatalError :: Text -> FatalError [fatalErrorMessage] :: FatalError -> Text panic :: HasCallStack => Text -> a instance GHC.Show.Show Protolude.Panic.FatalError instance GHC.Exception.Type.Exception Protolude.Panic.FatalError module Protolude.Partial -- | <math>. Extract the first element of a list, which must be -- non-empty. head :: [a] -> a -- | <math>. Return all the elements of a list except the last one. -- The list must be non-empty. init :: [a] -> [a] -- | <math>. Extract the elements after the head of a list, which -- must be non-empty. tail :: [a] -> [a] -- | <math>. Extract the last element of a list, which must be finite -- and non-empty. last :: [a] -> a -- | Left-associative fold of a structure. -- -- In the case of lists, foldl, when 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: -- --

--   foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn
--

-- -- Note that to produce the outermost application of the operator the -- entire input list must be traversed. This means that foldl' -- will diverge if given an infinite list. -- -- Also note that if you want an efficient left-fold, you probably want -- to use foldl' instead of foldl. The reason for this is -- that latter does not force the "inner" results (e.g. z `f` x1 -- in the above example) before applying them to the operator (e.g. to -- (`f` x2)). This results in a thunk chain <math> -- elements long, which then must be evaluated from the outside-in. -- -- For a general Foldable structure this should be semantically -- identical to, -- --

--   foldl f z = foldl f z . toList
--

foldl :: Foldable t => (b -> a -> b) -> b -> t a -> b -- | Right-associative fold of a structure. -- -- In the case of lists, foldr, when 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: -- --

--   foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
--

-- -- Note that, since the head of the resulting expression is produced by -- an application of the operator to the first element of the list, -- foldr can produce a terminating expression from an infinite -- list. -- -- For a general Foldable structure this should be semantically -- identical to, -- --

--   foldr f z = foldr f z . toList
--

foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b -- | Left-associative fold of a structure but with strict application of -- the operator. -- -- This ensures that each step of the fold is forced to weak head normal -- form before being applied, avoiding the collection of thunks that -- would otherwise occur. This is often what you want to strictly reduce -- a finite list to a single, monolithic result (e.g. length). -- -- For a general Foldable structure this should be semantically -- identical to, -- --

--   foldl' f z = foldl' f z . toList
--

foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b -- | Right-associative fold of a structure, but with strict application of -- the operator. foldr' :: Foldable t => (a -> b -> b) -> b -> t a -> b -- | A variant of foldr that has no base case, and thus may only be -- applied to non-empty structures. -- --

--   foldr1 f = foldr1 f . toList
--

foldr1 :: Foldable t => (a -> a -> a) -> t a -> a -- | A variant of foldl that has no base case, and thus may only be -- applied to non-empty structures. -- --

--   foldl1 f = foldl1 f . toList
--

foldl1 :: Foldable t => (a -> a -> a) -> t a -> a -- | cycle 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 largest element of a non-empty structure. maximum :: (Foldable t, Ord a) => t a -> a -- | The least element of a non-empty structure. minimum :: (Foldable t, Ord a) => t a -> a -- | List index (subscript) operator, starting from 0. It is an instance of -- the more general genericIndex, which takes an index of any -- integral type. (!!) :: [a] -> Int -> a infixl 9 !! -- | The sum function computes the sum of the numbers of a -- structure. sum :: (Foldable t, Num a) => t a -> a -- | The product function computes the product of the numbers of a -- structure. product :: (Foldable t, Num a) => t a -> a -- | The fromJust function extracts the element out of a Just -- and throws an error if its argument is Nothing. -- --

Examples

-- -- Basic usage: -- --

--   >>> fromJust (Just 1)
--   1
--

-- --

--   >>> 2 * (fromJust (Just 10))
--   20
--

-- --

--   >>> 2 * (fromJust Nothing)
--   *** Exception: Maybe.fromJust: Nothing
--

fromJust :: HasCallStack => Maybe a -> a -- | The read function reads input from a string, which must be -- completely consumed by the input process. read fails with an -- error if the parse is unsuccessful, and it is therefore -- discouraged from being used in real applications. Use readMaybe -- or readEither for safe alternatives. -- --

--   >>> read "123" :: Int
--   123
--

-- --

--   >>> read "hello" :: Int
--   *** Exception: Prelude.read: no parse
--

read :: Read a => String -> a module Protolude.Safe headMay :: [a] -> Maybe a headDef :: a -> [a] -> a initMay :: [a] -> Maybe [a] initDef :: [a] -> [a] -> [a] initSafe :: [a] -> [a] tailMay :: [a] -> Maybe [a] tailDef :: [a] -> [a] -> [a] tailSafe :: [a] -> [a] lastDef :: a -> [a] -> a lastMay :: [a] -> Maybe a foldr1May :: (a -> a -> a) -> [a] -> Maybe a foldl1May :: (a -> a -> a) -> [a] -> Maybe a foldl1May' :: (a -> a -> a) -> [a] -> Maybe a maximumMay :: Ord a => [a] -> Maybe a minimumMay :: Ord a => [a] -> Maybe a maximumDef :: Ord a => a -> [a] -> a minimumDef :: Ord a => a -> [a] -> a atMay :: [a] -> Int -> Maybe a atDef :: a -> [a] -> Int -> a module Protolude.Semiring class Monoid m => Semiring m one :: Semiring m => m (<.>) :: Semiring m => m -> m -> m -- | Alias for mempty zero :: Monoid m => m module Protolude.Show class Print a hPutStr :: (Print a, MonadIO m) => Handle -> a -> m () putStr :: (Print a, MonadIO m) => a -> m () hPutStrLn :: (Print a, MonadIO m) => Handle -> a -> m () putStrLn :: (Print a, MonadIO m) => a -> m () putErrLn :: (Print a, MonadIO m) => a -> m () putText :: MonadIO m => Text -> m () putErrText :: MonadIO m => Text -> m () putLText :: MonadIO m => Text -> m () putByteString :: MonadIO m => ByteString -> m () putLByteString :: MonadIO m => ByteString -> m () instance Protolude.Show.Print Data.Text.Internal.Text instance Protolude.Show.Print Data.Text.Internal.Lazy.Text instance Protolude.Show.Print Data.ByteString.Internal.ByteString instance Protolude.Show.Print Data.ByteString.Lazy.Internal.ByteString instance Protolude.Show.Print [GHC.Types.Char] module Protolude.Debug -- | Warning: undefined remains in code undefined :: a -- | Warning: trace remains in code trace :: Print b => b -> a -> a -- | Warning: traceM remains in code traceM :: Monad m => Text -> m () -- | Warning: traceId remains in code traceId :: Text -> Text -- | Warning: traceIO remains in code traceIO :: Print b => b -> a -> IO a -- | Warning: traceShow remains in code traceShow :: Show a => a -> b -> b -- | Warning: traceShowId remains in code traceShowId :: Show a => a -> a -- | Warning: traceShowM remains in code traceShowM :: (Show a, Monad m) => a -> m () -- | Warning: notImplemented remains in code notImplemented :: a witness :: a module Protolude -- | Append two lists, i.e., -- --

--   [x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
--   [x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]
--

-- -- If the first list is not finite, the result is the first list. (++) :: [a] -> [a] -> [a] infixr 5 ++ -- | The value of seq a b is bottom if a is bottom, and -- otherwise equal to b. In other words, it evaluates the first -- argument a to weak head normal form (WHNF). seq is -- usually introduced to improve performance by avoiding unneeded -- laziness. -- -- A note on evaluation order: the expression seq a b does -- not guarantee that a will be evaluated before -- b. The only guarantee given by seq is that the both -- a and b will be evaluated before seq -- returns a value. In particular, this means that b may be -- evaluated before a. If you need to guarantee a specific order -- of evaluation, you must use the function pseq from the -- "parallel" package. seq :: forall (r :: RuntimeRep) a (b :: TYPE r). a -> b -> b infixr 0 `seq` -- | 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 Bounded class is used to name the upper and lower limits of -- a type. Ord is not a superclass of Bounded since types -- that are not totally ordered may also have upper and lower bounds. -- -- The Bounded class may be derived for any enumeration type; -- minBound is the first constructor listed in the data -- declaration and maxBound is the last. Bounded may also -- be derived for single-constructor datatypes whose constituent types -- are in Bounded. class Bounded a minBound :: Bounded a => a maxBound :: Bounded a => a -- | Class Enum defines operations on sequentially ordered types. -- -- The enumFrom... methods are used in Haskell's translation of -- arithmetic sequences. -- -- Instances of Enum 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 fromEnum from -- 0 through n-1. See Chapter 10 of the Haskell -- Report for more details. -- -- For any type that is an instance of class Bounded as well as -- Enum, the following should hold: -- --

The calls succ maxBound and pred -- minBound should result in a runtime error.
fromEnum and toEnum should give a runtime error if -- the result value is not representable in the result type. For example, -- toEnum 7 :: Bool is an error.
enumFrom and enumFromThen should be defined with an -- implicit bound, thus:

-- --

--   enumFrom     x   = enumFromTo     x maxBound
--   enumFromThen x y = enumFromThenTo x y bound
--     where
--       bound | fromEnum y >= fromEnum x = maxBound
--             | otherwise                = minBound
--

```
enumFrom 4 :: [Integer] = [4,5,6,7,...]
```

enumFrom 6 :: [Int] = [6,7,8,9,...,maxBound ::
--   Int]

enumFromThen 4 6 :: [Integer] = [4,6,8,10...]

enumFromThen 6 2 :: [Int] = [6,2,-2,-6,...,minBound ::
--   Int]

```
enumFromTo 6 10 :: [Int] = [6,7,8,9,10]
```
```
enumFromTo 42 1 :: [Integer] = []
```

enumFromThenTo 4 2 -6 :: [Integer] =
--   [4,2,0,-2,-4,-6]

```
enumFromThenTo 6 8 2 :: [Int] = []
```

exp (a + b) = exp a * exp b
exp (fromInteger 0) = fromInteger 1

if x is a large negative number, log (1 + -- exp x) will be imprecise for the reasons given in -- log1p.
if exp x is close to -1, log -- (1 + exp x) will be imprecise for the reasons given in -- expm1.

log1pexp :: Floating a => a -> a -- | log1mexp x computes log (1 - exp -- x), but provides more precise results if possible. -- -- Examples: -- --

if x is a large negative number, log (1 - -- exp x) will be imprecise for the reasons given in -- log1p.
if exp x is close to 1, log (1 -- - exp x) will be imprecise for the reasons given in -- expm1.

recip gives the multiplicative inverse x -- * recip x = recip x * x = fromInteger 1

x = y * quot x y + rem x y with rem x y -- = fromInteger 0 or g (rem x y) < g -- y
x = y * div x y + mod x y with mod x y -- = fromInteger 0 or f (mod x y) < f -- y

--   (x `quot` y)*y + (x `rem` y) == x
--

rem :: Integral a => a -> a -> a -- | integer division truncated toward negative infinity div :: Integral a => a -> a -> a -- | integer modulus, satisfying -- --

--   (x `div` y)*y + (x `mod` y) == x
--

Associativity of (+) (x + y) + -- z = x + (y + z)
Commutativity of (+) x + y -- = y + x
fromInteger 0 is the additive -- identity x + fromInteger 0 = x
negate gives the additive inverse x + -- negate x = fromInteger 0
Associativity of (*) (x * y) * -- z = x * (y * z)
fromInteger 1 is the multiplicative -- identity x * fromInteger 1 = x and -- fromInteger 1 * x = x
Distributivity of (*) with respect to -- (+) a * (b + c) = (a * b) + (a * -- c) and (b + c) * a = (b * a) + (c * a)

--   abs x * signum x == x
--

n is an integral number with the same sign as x; -- and
f is a fraction with the same type and sign as -- x, and with absolute value less than 1.

The result of show 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.
If the constructor is defined to be an infix operator, then -- showsPrec will produce infix applications of the -- constructor.
the representation will be enclosed in parentheses if the -- precedence of the top-level constructor in x is less than -- d (associativity is ignored). Thus, if d is -- 0 then the result is never surrounded in parentheses; if -- d is 11 it is always surrounded in parentheses, -- unless it is an atomic expression.
If the constructor is defined using record syntax, then -- show will produce the record-syntax form, with the fields given -- in the same order as the original declaration.

-- -- For example, given the declarations -- --

--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--

-- -- the derived instance of Show is equivalent to -- --

--   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
--

-- -- Note that right-associativity of :^: is ignored. For example, -- --

show (Leaf 1 :^: Leaf 2 :^: Leaf 3) produces the -- string "Leaf 1 :^: (Leaf 2 :^: Leaf 3)".

class Show a -- | This class gives the integer associated with a type-level natural. -- There are instances of the class for every concrete literal: 0, 1, 2, -- etc. class KnownNat (n :: Nat) -- | This class gives the string associated with a type-level symbol. There -- are instances of the class for every concrete literal: "hello", etc. class KnownSymbol (n :: Symbol) class IsLabel (x :: Symbol) a fromLabel :: IsLabel x a => a -- | Constraint representing the fact that the field x belongs to -- the record type r and has field type a. This will be -- solved automatically, but manual instances may be provided as well. class HasField (x :: k) r a | x r -> a -- | Selector function to extract the field from the record. getField :: HasField x r a => r -> a data Bool -- | The character type Char is an enumeration whose values -- represent Unicode (or equivalently ISO/IEC 10646) code points (i.e. -- characters, see http://www.unicode.org/ 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 -- Char. -- -- To convert a Char to or from the corresponding Int value -- defined by Unicode, use toEnum and fromEnum from the -- Enum class respectively (or equivalently ord and -- chr). data Char -- | 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 D# :: Double# -> Double -- | 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 F# :: Float# -> Float -- | A fixed-precision integer type with at least the range [-2^29 .. -- 2^29-1]. The exact range for a given implementation can be -- determined by using minBound and maxBound from the -- Bounded class. data Int -- | Arbitrary precision integers. In contrast with fixed-size integral -- types such as Int, the Integer type represents the -- entire infinite range of integers. -- -- For more information about this type's representation, see the -- comments in its implementation. data Integer data Ordering -- | Rational numbers, with numerator and denominator of some -- Integral type. -- -- Note that Ratio's instances inherit the deficiencies from the -- type parameter's. For example, Ratio Natural's Num -- instance has similar problems to Natural's. data Ratio a -- | Arbitrary-precision rational numbers, represented as a ratio of two -- Integer values. A rational number may be constructed using the -- % operator. type Rational = Ratio Integer -- | A value of type IO a is a computation which, when -- performed, does some I/O before returning a value of type a. -- -- There is really only one way to "perform" an I/O action: bind it to -- Main.main 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 IO monad and -- called at some point, directly or indirectly, from Main.main. -- -- IO is a monad, so IO actions can be combined using -- either the do-notation or the >> and >>= -- operations from the Monad class. data IO a -- | A Word is an unsigned integral type, with the same size as -- Int. data Word -- | A value of type Ptr a represents a pointer to an -- object, or an array of objects, which may be marshalled to or from -- Haskell values of type a. -- -- The type a will often be an instance of class Storable -- 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 struct. data Ptr a -- | A value of type FunPtr a is a pointer to a function -- callable from foreign code. The type a will normally be a -- foreign type, a function type with zero or more arguments where -- --

the argument types are marshallable foreign types, i.e. -- Char, Int, Double, Float, Bool, -- Int8, Int16, Int32, Int64, Word8, -- Word16, Word32, Word64, Ptr a, -- FunPtr a, StablePtr a or a renaming of -- any of these using newtype.
the return type is either a marshallable foreign type or has the -- form IO t where t is a marshallable foreign -- type or ().

-- -- A value of type FunPtr a may be a pointer to a foreign -- function, either returned by another foreign function or imported with -- a a static address import like -- --

--   foreign import ccall "stdlib.h &free"
--     p_free :: FunPtr (Ptr a -> IO ())
--

-- -- or a pointer to a Haskell function created using a wrapper stub -- declared to produce a FunPtr of the correct type. For example: -- --

--   type Compare = Int -> Int -> Bool
--   foreign import ccall "wrapper"
--     mkCompare :: Compare -> IO (FunPtr Compare)
--

--   type IntFunction = CInt -> IO ()
--   foreign import ccall "dynamic"
--     mkFun :: FunPtr IntFunction -> IntFunction
--

--   instance Coercible a a
--

--   instance Coercible b b' => Coercible (D a b c) (D a b' c')
--

--   instance Coercible a T => Coercible a NT
--

-- --

--   instance Coercible T b => Coercible NT b
--

--   type role Set nominal
--

--   putStrLnWithCallStack :: HasCallStack => String -> IO ()
--

--   putStrLnWithCallStack :: HasCallStack => String -> IO ()
--   putStrLnWithCallStack msg = do
--     putStrLn msg
--     putStrLn (prettyCallStack callStack)
--

-- -- Thus, if we call putStrLnWithCallStack we will get a -- formatted call-stack alongside our string. -- --

--   >>> putStrLnWithCallStack "hello"
--   hello
--   CallStack (from HasCallStack):
--     putStrLnWithCallStack, called at <interactive>:2:1 in interactive:Ghci1
--

-- -- GHC solves HasCallStack constraints in three steps: -- --

If there is a CallStack in scope -- i.e. the enclosing -- function has a HasCallStack constraint -- GHC will append the -- new call-site to the existing CallStack.
If there is no CallStack in scope -- e.g. in the GHCi -- session above -- and the enclosing definition does not have an -- explicit type signature, GHC will infer a HasCallStack -- constraint for the enclosing definition (subject to the monomorphism -- restriction).
If there is no CallStack in scope and the enclosing -- definition has an explicit type signature, GHC will solve the -- HasCallStack constraint for the singleton CallStack -- containing just the current call-site.

--   f $ g $ h x  =  f (g (h x))
--

-- -- It is also useful in higher-order situations, such as map -- ($ 0) xs, or zipWith ($) fs xs. -- -- Note that ($) is levity-polymorphic in its result -- type, so that foo $ True where foo :: Bool -> -- Int# is well-typed. ($) :: forall (r :: RuntimeRep) a (b :: TYPE r). (a -> b) -> a -> b infixr 0 $ -- | & is a reverse application operator. This provides -- notational convenience. Its precedence is one higher than that of the -- forward application operator $, which allows & to be -- nested in $. -- --

--   >>> 5 & (+1) & show
--   "6"
--

(&) :: a -> (a -> b) -> b infixl 1 & -- | on b u x y runs the binary function b -- on the results of applying unary function u to two -- arguments x and y. From the opposite perspective, it -- transforms two inputs and combines the outputs. -- --

--   ((+) `on` f) x y = f x + f y
--

-- -- Typical usage: sortBy (compare `on` -- fst). -- -- Algebraic properties: -- --

(*) `on` id = (*) -- (if (*) ∉ {⊥, const
--   ⊥})

```
((*) `on` f) `on` g = (*) `on` (f . g)
```

flip on f . flip on g = flip on (g .
--   f)

on :: (b -> b -> c) -> (a -> b) -> a -> a -> c infixl 0 `on` -- | fix f is the least fixed point of the function -- f, i.e. the least defined x such that f x = -- x. -- -- For example, we can write the factorial function using direct -- recursion as -- --

--   >>> let fac n = if n <= 1 then 1 else n * fac (n-1) in fac 5
--   120
--

-- -- This uses the fact that Haskell’s let introduces recursive -- bindings. We can rewrite this definition using fix, -- --

--   >>> fix (\rec n -> if n <= 1 then 1 else n * rec (n-1)) 5
--   120
--

-- -- Instead of making a recursive call, we introduce a dummy parameter -- rec; when used within fix, this parameter then refers -- to fix’s argument, hence the recursion is reintroduced. fix :: (a -> a) -> a -- | flip f takes its (first) two arguments in the reverse -- order of f. -- --

--   >>> flip (++) "hello" "world"
--   "worldhello"
--

flip :: (a -> b -> c) -> b -> a -> c -- | Function composition. (.) :: (b -> c) -> (a -> b) -> a -> c infixr 9 . -- | const x is a unary function which evaluates to x for -- all inputs. -- --

--   >>> const 42 "hello"
--   42
--

-- --

--   >>> map (const 42) [0..3]
--   [42,42,42,42]
--

const :: a -> b -> a -- | Apply a function n times to a given value applyN :: Int -> (a -> a) -> a -> a -- | <math>. filter, applied to a predicate and a list, -- returns the list of those elements that satisfy the predicate; i.e., -- --

--   filter p xs = [ x | x <- xs, p x]
--

-- --

--   >>> filter odd [1, 2, 3]
--   [1,3]
--

filter :: (a -> Bool) -> [a] -> [a] -- | <math>. zip takes two lists and returns a list of -- corresponding pairs. -- --

--   zip [1, 2] ['a', 'b'] = [(1, 'a'), (2, 'b')]
--

-- -- If one input list is short, excess elements of the longer list are -- discarded: -- --

--   zip [1] ['a', 'b'] = [(1, 'a')]
--   zip [1, 2] ['a'] = [(1, 'a')]
--

-- -- zip is right-lazy: -- --

--   zip [] _|_ = []
--   zip _|_ [] = _|_
--

-- -- zip is capable of list fusion, but it is restricted to its -- first list argument and its resulting list. zip :: [a] -> [b] -> [(a, b)] -- | nonEmpty efficiently turns a normal list into a NonEmpty -- stream, producing Nothing if the input is empty. nonEmpty :: [a] -> Maybe (NonEmpty a) -- | The unfoldr function is a `dual' to foldr: while -- foldr reduces a list to a summary value, unfoldr builds -- a list from a seed value. The function takes the element and returns -- Nothing if it is done producing the list or returns Just -- (a,b), in which case, a is a prepended to the list -- and b is used as the next element in a recursive call. For -- example, -- --

--   iterate f == unfoldr (\x -> Just (x, f x))
--

-- -- In some cases, unfoldr can undo a foldr operation: -- --

--   unfoldr f' (foldr f z xs) == xs
--

-- -- if the following holds: -- --

--   f' (f x y) = Just (x,y)
--   f' z       = Nothing
--

-- -- A simple use of unfoldr: -- --

--   >>> unfoldr (\b -> if b == 0 then Nothing else Just (b, b-1)) 10
--   [10,9,8,7,6,5,4,3,2,1]
--

unfoldr :: (b -> Maybe (a, b)) -> b -> [a] -- | The sortBy function is the non-overloaded version of -- sort. -- --

--   >>> sortBy (\(a,_) (b,_) -> compare a b) [(2, "world"), (4, "!"), (1, "Hello")]
--   [(1,"Hello"),(2,"world"),(4,"!")]
--

sortBy :: (a -> a -> Ordering) -> [a] -> [a] -- | The sort function implements a stable sorting algorithm. It is -- a special case of sortBy, which allows the programmer to supply -- their own comparison function. -- -- Elements are arranged from lowest to highest, keeping duplicates in -- the order they appeared in the input. -- --

--   >>> sort [1,6,4,3,2,5]
--   [1,2,3,4,5,6]
--

sort :: Ord a => [a] -> [a] -- | The permutations function returns the list of all permutations -- of the argument. -- --

--   >>> permutations "abc"
--   ["abc","bac","cba","bca","cab","acb"]
--

permutations :: [a] -> [[a]] -- | The subsequences function returns the list of all subsequences -- of the argument. -- --

--   >>> subsequences "abc"
--   ["","a","b","ab","c","ac","bc","abc"]
--

subsequences :: [a] -> [[a]] -- | <math>. The tails function returns all final segments of -- the argument, longest first. For example, -- --

--   >>> tails "abc"
--   ["abc","bc","c",""]
--

-- -- Note that tails has the following strictness property: -- tails _|_ = _|_ : _|_ tails :: [a] -> [[a]] -- | The inits function returns all initial segments of the -- argument, shortest first. For example, -- --

--   >>> inits "abc"
--   ["","a","ab","abc"]
--

-- -- Note that inits has the following strictness property: -- inits (xs ++ _|_) = inits xs ++ _|_ -- -- In particular, inits _|_ = [] : _|_ inits :: [a] -> [[a]] -- | The groupBy function is the non-overloaded version of -- group. groupBy :: (a -> a -> Bool) -> [a] -> [[a]] -- | The group 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, -- --

--   >>> group "Mississippi"
--   ["M","i","ss","i","ss","i","pp","i"]
--

-- -- It is a special case of groupBy, which allows the programmer to -- supply their own equality test. group :: Eq a => [a] -> [[a]] -- | The genericReplicate function is an overloaded version of -- replicate, which accepts any Integral value as the -- number of repetitions to make. genericReplicate :: Integral i => i -> a -> [a] -- | The genericSplitAt function is an overloaded version of -- splitAt, which accepts any Integral value as the -- position at which to split. genericSplitAt :: Integral i => i -> [a] -> ([a], [a]) -- | The genericDrop function is an overloaded version of -- drop, which accepts any Integral value as the number of -- elements to drop. genericDrop :: Integral i => i -> [a] -> [a] -- | The genericTake function is an overloaded version of -- take, which accepts any Integral value as the number of -- elements to take. genericTake :: Integral i => i -> [a] -> [a] -- | <math>. The genericLength function is an overloaded -- version of length. In particular, instead of returning an -- Int, it returns any type which is an instance of Num. It -- is, however, less efficient than length. -- --

--   >>> genericLength [1, 2, 3] :: Int
--   3
--   
--   >>> genericLength [1, 2, 3] :: Float
--   3.0
--

genericLength :: Num i => [a] -> i -- | The transpose function transposes the rows and columns of its -- argument. For example, -- --

--   >>> transpose [[1,2,3],[4,5,6]]
--   [[1,4],[2,5],[3,6]]
--

-- -- If some of the rows are shorter than the following rows, their -- elements are skipped: -- --

--   >>> transpose [[10,11],[20],[],[30,31,32]]
--   [[10,20,30],[11,31],[32]]
--

transpose :: [[a]] -> [[a]] -- | intercalate xs xss is equivalent to (concat -- (intersperse xs xss)). It inserts the list xs in -- between the lists in xss and concatenates the result. -- --

--   >>> intercalate ", " ["Lorem", "ipsum", "dolor"]
--   "Lorem, ipsum, dolor"
--

intercalate :: [a] -> [[a]] -> [a] -- | <math>. The intersperse function takes an element and a -- list and `intersperses' that element between the elements of the list. -- For example, -- --

--   >>> intersperse ',' "abcde"
--   "a,b,c,d,e"
--

intersperse :: a -> [a] -> [a] -- | The isInfixOf function takes two lists and returns True -- iff the first list is contained, wholly and intact, anywhere within -- the second. -- --

--   >>> isInfixOf "Haskell" "I really like Haskell."
--   True
--

-- --

--   >>> isInfixOf "Ial" "I really like Haskell."
--   False
--

isInfixOf :: Eq a => [a] -> [a] -> Bool -- | The isSuffixOf function takes two lists and returns True -- iff the first list is a suffix of the second. The second list must be -- finite. -- --

--   >>> "ld!" `isSuffixOf` "Hello World!"
--   True
--

-- --

--   >>> "World" `isSuffixOf` "Hello World!"
--   False
--

isSuffixOf :: Eq a => [a] -> [a] -> Bool -- | <math>. The isPrefixOf function takes two lists and -- returns True iff the first list is a prefix of the second. -- --

--   >>> "Hello" `isPrefixOf` "Hello World!"
--   True
--

-- --

--   >>> "Hello" `isPrefixOf` "Wello Horld!"
--   False
--

isPrefixOf :: Eq a => [a] -> [a] -> Bool -- | unzip transforms a list of pairs into a list of first -- components and a list of second components. unzip :: [(a, b)] -> ([a], [b]) -- | <math>. zipWith generalises zip by zipping with -- the function given as the first argument, instead of a tupling -- function. For example, zipWith (+) is applied to two -- lists to produce the list of corresponding sums: -- --

--   >>> zipWith (+) [1, 2, 3] [4, 5, 6]
--   [5,7,9]
--

-- -- zipWith is right-lazy: -- --

--   zipWith f [] _|_ = []
--

-- -- zipWith is capable of list fusion, but it is restricted to its -- first list argument and its resulting list. zipWith :: (a -> b -> c) -> [a] -> [b] -> [c] -- | reverse xs returns the elements of xs in -- reverse order. xs must be finite. reverse :: [a] -> [a] -- | break, applied to a predicate p and a list -- xs, returns a tuple where first element is longest prefix -- (possibly empty) of xs of elements that do not satisfy -- p and second element is the remainder of the list: -- --

--   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],[])
--

-- -- break p is equivalent to span (not . -- p). break :: (a -> Bool) -> [a] -> ([a], [a]) -- | splitAt n xs returns a tuple where first element is -- xs prefix of length n and second element is the -- remainder of the list: -- --

--   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])
--

-- -- It is equivalent to (take n xs, drop n xs) when -- n is not _|_ (splitAt _|_ xs = _|_). -- splitAt is an instance of the more general -- genericSplitAt, in which n may be of any integral -- type. splitAt :: Int -> [a] -> ([a], [a]) -- | drop n xs returns the suffix of xs after the -- first n elements, or [] if n > length -- xs: -- --

--   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]
--

-- -- It is an instance of the more general genericDrop, in which -- n may be of any integral type. drop :: Int -> [a] -> [a] -- | take n, applied to a list xs, returns the -- prefix of xs of length n, or xs itself if -- n > length xs: -- --

--   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] == []
--

-- -- It is an instance of the more general genericTake, in which -- n may be of any integral type. take :: Int -> [a] -> [a] -- | dropWhile p xs returns the suffix remaining after -- takeWhile p xs: -- --

--   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]
--

dropWhile :: (a -> Bool) -> [a] -> [a] -- | takeWhile, applied to a predicate p and a list -- xs, returns the longest prefix (possibly empty) of -- xs of elements that satisfy p: -- --

--   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] == []
--

takeWhile :: (a -> Bool) -> [a] -> [a] -- | cycle 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] -- | replicate n x is a list of length n with -- x the value of every element. It is an instance of the more -- general genericReplicate, in which n may be of any -- integral type. replicate :: Int -> a -> [a] -- | repeat x is an infinite list, with x the -- value of every element. repeat :: a -> [a] -- | iterate f x returns an infinite list of repeated -- applications of f to x: -- --

--   iterate f x == [x, f x, f (f x), ...]
--

-- -- Note that iterate is lazy, potentially leading to thunk -- build-up if the consumer doesn't force each iterate. See -- iterate' for a strict variant of this function. iterate :: (a -> a) -> a -> [a] -- | <math>. scanr is the right-to-left dual of scanl. -- Note that -- --

--   head (scanr f z xs) == foldr f z xs.
--

scanr :: (a -> b -> b) -> b -> [a] -> [b] -- | <math>. A strictly accumulating version of scanl scanl' :: (b -> a -> b) -> b -> [a] -> [b] -- | <math>. scanl is similar to foldl, but returns a -- list of successive reduced values from the left: -- --

--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--

-- -- Note that -- --

--   last (scanl f z xs) == foldl f z xs.
--

scanl :: (b -> a -> b) -> b -> [a] -> [b] -- | Non-empty (and non-strict) list type. data NonEmpty a (:|) :: a -> [a] -> NonEmpty a infixr 5 :| head :: Foldable f => f a -> Maybe a sortOn :: Ord o => (a -> o) -> [a] -> [a] ordNub :: Ord a => [a] -> [a] list :: [b] -> (a -> b) -> [a] -> [b] product :: (Foldable f, Num a) => f a -> a sum :: (Foldable f, Num a) => f a -> a map :: Functor f => (a -> b) -> f a -> f b uncons :: [a] -> Maybe (a, [a]) unsnoc :: [x] -> Maybe ([x], x) -- | A map of integers to values a. data IntMap a -- | A set of integers. data IntSet -- | A Map from keys k to values a. -- -- The Semigroup operation for Map is union, which -- prefers values from the left operand. If m1 maps a key -- k to a value a1, and m2 maps the same key -- to a different value a2, then their union m1 <> -- m2 maps k to a1. data Map k a -- | General-purpose finite sequences. data Seq a -- | A set of values a. data Set a show :: (Show a, StringConv String b) => a -> b -- | The print function outputs a value of any printable type to the -- standard output device. Printable types are those that are instances -- of class Show; print converts values to strings for output using the -- show operation and adds a newline. print :: (MonadIO m, Show a) => a -> m () -- | otherwise is defined as the value True. It helps to make -- guards more readable. eg. -- --

--   f x | x < 0     = ...
--       | otherwise = ...
--

otherwise :: Bool data Bool False :: Bool True :: Bool -- | Boolean "and", lazy in the second argument (&&) :: Bool -> Bool -> Bool infixr 3 && -- | Boolean "or", lazy in the second argument (||) :: Bool -> Bool -> Bool infixr 2 || -- | Boolean "not" not :: Bool -> Bool bool :: a -> a -> Bool -> a whenM :: Monad m => m Bool -> m () -> m () unlessM :: Monad m => m Bool -> m () -> m () ifM :: Monad m => m Bool -> m a -> m a -> m a guardM :: MonadPlus m => m Bool -> m () -- | The || operator lifted to a monad. If the first argument -- evaluates to True the second argument will not be evaluated. (||^) :: Monad m => m Bool -> m Bool -> m Bool infixr 2 ||^ -- | || lifted to an Applicative. Unlike ||^ the operator is -- not short-circuiting. (<||>) :: Applicative a => a Bool -> a Bool -> a Bool infixr 2 <||> -- | The && operator lifted to a monad. If the first -- argument evaluates to False the second argument will not be -- evaluated. (&&^) :: Monad m => m Bool -> m Bool -> m Bool infixr 3 &&^ -- | && lifted to an Applicative. Unlike &&^ -- the operator is not short-circuiting. (<&&>) :: Applicative a => a Bool -> a Bool -> a Bool infixr 3 <&&> -- | Lift an IO operation with 1 argument into another monad liftIO1 :: MonadIO m => (a -> IO b) -> a -> m b -- | Lift an IO operation with 2 arguments into another monad liftIO2 :: MonadIO m => (a -> b -> IO c) -> a -> b -> m c -- | A type f is a Functor if it provides a function fmap -- which, given any types a and b lets you apply any -- function from (a -> b) to turn an f a into an -- f b, preserving the structure of f. Furthermore -- f needs to adhere to the following: -- --

Identity fmap id == id
Composition fmap (f . g) == fmap f . -- fmap g

--   do a <- as
--      pure (f a)
--

-- -- with an inferred Functor constraint. fmap :: Functor f => (a -> b) -> f a -> f b -- | Replace all locations in the input with the same value. The default -- definition is fmap . const, but this may be -- overridden with a more efficient version. -- -- Using ApplicativeDo: 'a <$ bs' can be -- understood as the do expression -- --

--   do bs
--      pure a
--

-- -- with an inferred Functor constraint. (<$) :: Functor f => a -> f b -> f a infixl 4 <$ -- | Identity functor and monad. (a non-strict monad) newtype Identity a Identity :: a -> Identity a [runIdentity] :: Identity a -> a -- | void value discards or ignores the result of -- evaluation, such as the return value of an IO action. -- -- Using ApplicativeDo: 'void as' can be -- understood as the do expression -- --

--   do as
--      pure ()
--

-- -- with an inferred Functor constraint. -- --

Examples

-- -- Replace the contents of a Maybe Int with unit: -- --

--   >>> void Nothing
--   Nothing
--   
--   >>> void (Just 3)
--   Just ()
--

-- -- Replace the contents of an Either Int -- Int with unit, resulting in an Either -- Int (): -- --

--   >>> void (Left 8675309)
--   Left 8675309
--   
--   >>> void (Right 8675309)
--   Right ()
--

-- -- Replace every element of a list with unit: -- --

--   >>> void [1,2,3]
--   [(),(),()]
--

-- -- Replace the second element of a pair with unit: -- --

--   >>> void (1,2)
--   (1,())
--

-- -- Discard the result of an IO action: -- --

--   >>> mapM print [1,2]
--   1
--   2
--   [(),()]
--   
--   >>> void $ mapM print [1,2]
--   1
--   2
--

void :: Functor f => f a -> f () -- | Flipped version of <$. -- -- Using ApplicativeDo: 'as $> b' can be -- understood as the do expression -- --

--   do as
--      pure b
--

-- -- with an inferred Functor constraint. -- --

Examples

-- -- Replace the contents of a Maybe Int with a -- constant String: -- --

--   >>> Nothing $> "foo"
--   Nothing
--   
--   >>> Just 90210 $> "foo"
--   Just "foo"
--

-- -- Replace the contents of an Either Int -- Int with a constant String, resulting in an -- Either Int String: -- --

--   >>> Left 8675309 $> "foo"
--   Left 8675309
--   
--   >>> Right 8675309 $> "foo"
--   Right "foo"
--

-- -- Replace each element of a list with a constant String: -- --

--   >>> [1,2,3] $> "foo"
--   ["foo","foo","foo"]
--

-- -- Replace the second element of a pair with a constant String: -- --

--   >>> (1,2) $> "foo"
--   (1,"foo")
--

($>) :: Functor f => f a -> b -> f b infixl 4 $> -- | Flipped version of <$>. -- --

--   (<&>) = flip fmap
--

-- --

Examples

-- -- Apply (+1) to a list, a Just and a Right: -- --

--   >>> Just 2 <&> (+1)
--   Just 3
--

-- --

--   >>> [1,2,3] <&> (+1)
--   [2,3,4]
--

-- --

--   >>> Right 3 <&> (+1)
--   Right 4
--

(<&>) :: Functor f => f a -> (a -> b) -> f b infixl 1 <&> -- | An infix synonym for fmap. -- -- The name of this operator is an allusion to $. Note the -- similarities between their types: -- --

--    ($)  ::              (a -> b) ->   a ->   b
--   (<$>) :: Functor f => (a -> b) -> f a -> f b
--

-- -- Whereas $ is function application, <$> is function -- application lifted over a Functor. -- --

Examples

-- -- Convert from a Maybe Int to a Maybe -- String using show: -- --

--   >>> show <$> Nothing
--   Nothing
--   
--   >>> show <$> Just 3
--   Just "3"
--

-- -- Convert from an Either Int Int to an -- Either Int String using show: -- --

--   >>> show <$> Left 17
--   Left 17
--   
--   >>> show <$> Right 17
--   Right "17"
--

-- -- Double each element of a list: -- --

--   >>> (*2) <$> [1,2,3]
--   [2,4,6]
--

-- -- Apply even to the second element of a pair: -- --

--   >>> even <$> (2,2)
--   (2,True)
--

(<$>) :: Functor f => (a -> b) -> f a -> f b infixl 4 <$> (<<$>>) :: (Functor f, Functor g) => (a -> b) -> f (g a) -> f (g b) infixl 4 <<$>> foreach :: Functor f => f a -> (a -> b) -> f b -- | The Either type represents values with two possibilities: a -- value of type Either a b is either Left -- a or Right b. -- -- The Either type is sometimes used to represent a value which is -- either correct or an error; by convention, the Left constructor -- is used to hold an error value and the Right constructor is -- used to hold a correct value (mnemonic: "right" also means "correct"). -- --

Examples

-- -- The type Either String Int is the type -- of values which can be either a String or an Int. The -- Left constructor can be used only on Strings, and the -- Right constructor can be used only on Ints: -- --

--   >>> let s = Left "foo" :: Either String Int
--   
--   >>> s
--   Left "foo"
--   
--   >>> let n = Right 3 :: Either String Int
--   
--   >>> n
--   Right 3
--   
--   >>> :type s
--   s :: Either String Int
--   
--   >>> :type n
--   n :: Either String Int
--

-- -- The fmap from our Functor instance will ignore -- Left values, but will apply the supplied function to values -- contained in a Right: -- --

--   >>> let s = Left "foo" :: Either String Int
--   
--   >>> let n = Right 3 :: Either String Int
--   
--   >>> fmap (*2) s
--   Left "foo"
--   
--   >>> fmap (*2) n
--   Right 6
--

-- -- The Monad instance for Either allows us to chain -- together multiple actions which may fail, and fail overall if any of -- the individual steps failed. First we'll write a function that can -- either parse an Int from a Char, or fail. -- --

--   >>> import Data.Char ( digitToInt, isDigit )
--   
--   >>> :{
--       let parseEither :: Char -> Either String Int
--           parseEither c
--             | isDigit c = Right (digitToInt c)
--             | otherwise = Left "parse error"
--   
--   >>> :}
--

-- -- The following should work, since both '1' and '2' -- can be parsed as Ints. -- --

--   >>> :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x <- parseEither '1'
--             y <- parseEither '2'
--             return (x + y)
--   
--   >>> :}
--

-- --

--   >>> parseMultiple
--   Right 3
--

-- -- But the following should fail overall, since the first operation where -- we attempt to parse 'm' as an Int will fail: -- --

--   >>> :{
--       let parseMultiple :: Either String Int
--           parseMultiple = do
--             x <- parseEither 'm'
--             y <- parseEither '2'
--             return (x + y)
--   
--   >>> :}
--

-- --

--   >>> parseMultiple
--   Left "parse error"
--

data Either a b Left :: a -> Either a b Right :: b -> Either a b -- | Return the contents of a Right-value or a default value -- otherwise. -- --

Examples

-- -- Basic usage: -- --

--   >>> fromRight 1 (Right 3)
--   3
--   
--   >>> fromRight 1 (Left "foo")
--   1
--

fromRight :: b -> Either a b -> b -- | Return the contents of a Left-value or a default value -- otherwise. -- --

Examples

-- -- Basic usage: -- --

--   >>> fromLeft 1 (Left 3)
--   3
--   
--   >>> fromLeft 1 (Right "foo")
--   1
--

fromLeft :: a -> Either a b -> a -- | Return True if the given value is a Right-value, -- False otherwise. -- --

Examples

-- -- Basic usage: -- --

--   >>> isRight (Left "foo")
--   False
--   
--   >>> isRight (Right 3)
--   True
--

-- -- Assuming a Left value signifies some sort of error, we can use -- isRight to write a very simple reporting function that only -- outputs "SUCCESS" when a computation has succeeded. -- -- This example shows how isRight might be used to avoid pattern -- matching when one does not care about the value contained in the -- constructor: -- --

--   >>> import Control.Monad ( when )
--   
--   >>> let report e = when (isRight e) $ putStrLn "SUCCESS"
--   
--   >>> report (Left "parse error")
--   
--   >>> report (Right 1)
--   SUCCESS
--

isRight :: Either a b -> Bool -- | Return True if the given value is a Left-value, -- False otherwise. -- --

Examples

-- -- Basic usage: -- --

--   >>> isLeft (Left "foo")
--   True
--   
--   >>> isLeft (Right 3)
--   False
--

-- -- Assuming a Left value signifies some sort of error, we can use -- isLeft to write a very simple error-reporting function that -- does absolutely nothing in the case of success, and outputs "ERROR" if -- any error occurred. -- -- This example shows how isLeft might be used to avoid pattern -- matching when one does not care about the value contained in the -- constructor: -- --

--   >>> import Control.Monad ( when )
--   
--   >>> let report e = when (isLeft e) $ putStrLn "ERROR"
--   
--   >>> report (Right 1)
--   
--   >>> report (Left "parse error")
--   ERROR
--

isLeft :: Either a b -> Bool -- | Partitions a list of Either into two lists. All the Left -- elements are extracted, in order, to the first component of the -- output. Similarly the Right elements are extracted to the -- second component of the output. -- --

Examples

-- -- Basic usage: -- --

--   >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   >>> partitionEithers list
--   (["foo","bar","baz"],[3,7])
--

-- -- The pair returned by partitionEithers x should be the -- same pair as (lefts x, rights x): -- --

--   >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   >>> partitionEithers list == (lefts list, rights list)
--   True
--

partitionEithers :: [Either a b] -> ([a], [b]) -- | Extracts from a list of Either all the Right elements. -- All the Right elements are extracted in order. -- --

Examples

-- -- Basic usage: -- --

--   >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   >>> rights list
--   [3,7]
--

rights :: [Either a b] -> [b] -- | Extracts from a list of Either all the Left elements. -- All the Left elements are extracted in order. -- --

Examples

-- -- Basic usage: -- --

--   >>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]
--   
--   >>> lefts list
--   ["foo","bar","baz"]
--

lefts :: [Either a b] -> [a] -- | Case analysis for the Either type. If the value is -- Left a, apply the first function to a; if it -- is Right b, apply the second function to b. -- --

Examples

-- -- We create two values of type Either String -- Int, one using the Left constructor and another -- using the Right constructor. Then we apply "either" the -- length function (if we have a String) or the "times-two" -- function (if we have an Int): -- --

--   >>> let s = Left "foo" :: Either String Int
--   
--   >>> let n = Right 3 :: Either String Int
--   
--   >>> either length (*2) s
--   3
--   
--   >>> either length (*2) n
--   6
--

either :: (a -> c) -> (b -> c) -> Either a b -> c leftToMaybe :: Either l r -> Maybe l rightToMaybe :: Either l r -> Maybe r maybeToRight :: l -> Maybe r -> Either l r maybeToLeft :: r -> Maybe l -> Either l r maybeEmpty :: Monoid b => (a -> b) -> Maybe a -> b maybeToEither :: e -> Maybe a -> Either e a -- | A functor with application, providing operations to -- --

embed pure expressions (pure), and
sequence computations and combine their results (<*> -- and liftA2).

-- -- A minimal complete definition must include implementations of -- pure and of either <*> or liftA2. If it -- defines both, then they must behave the same as their default -- definitions: -- --

--   (<*>) = liftA2 id
--

-- --

--   liftA2 f x y = f <$> x <*> y
--

-- -- Further, any definition must satisfy the following: -- --

Identity
```
pure id <*> v =
--   v
```

Composition

pure (.) <*> u
--   <*> v <*> w = u <*> (v
--   <*> w)

Homomorphism
```
pure f <*>
--   pure x = pure (f x)
```
Interchange
```
u <*> pure y =
--   pure ($ y) <*> u
```

-- -- The other methods have the following default definitions, which may be -- overridden with equivalent specialized implementations: -- --

```
u *> v = (id <$ u)
--   <*> v
```
```
u <* v = liftA2 const u v
```

-- -- As a consequence of these laws, the Functor instance for -- f will satisfy -- --

```
fmap f x = pure f <*> x
```

-- -- It may be useful to note that supposing -- --

--   forall x y. p (q x y) = f x . g y
--

-- -- it follows from the above that -- --

--   liftA2 p (liftA2 q u v) = liftA2 f u . liftA2 g v
--

-- -- If f is also a Monad, it should satisfy -- --

```
pure = return
```

m1 <*> m2 = m1 >>= (x1 -> m2
--   >>= (x2 -> return (x1 x2)))

```
(*>) = (>>)
```

-- -- (which implies that pure and <*> satisfy the -- applicative functor laws). class Functor f => Applicative (f :: Type -> Type) -- | Lift a value. pure :: Applicative f => a -> f a -- | Sequential application. -- -- A few functors support an implementation of <*> that is -- more efficient than the default one. -- -- Using ApplicativeDo: 'fs <*> as' can be -- understood as the do expression -- --

--   do f <- fs
--      a <- as
--      pure (f a)
--

(<*>) :: Applicative f => f (a -> b) -> f a -> f b -- | Lift a binary function to actions. -- -- Some functors support an implementation of liftA2 that is more -- efficient than the default one. In particular, if fmap is an -- expensive operation, it is likely better to use liftA2 than to -- fmap over the structure and then use <*>. -- -- This became a typeclass method in 4.10.0.0. Prior to that, it was a -- function defined in terms of <*> and fmap. -- -- Using ApplicativeDo: 'liftA2 f as bs' can be -- understood as the do expression -- --

--   do a <- as
--      b <- bs
--      pure (f a b)
--

liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c -- | Sequence actions, discarding the value of the first argument. -- -- 'as *> bs' can be understood as the do -- expression -- --

--   do as
--      bs
--

-- -- This is a tad complicated for our ApplicativeDo extension -- which will give it a Monad constraint. For an -- Applicative constraint we write it of the form -- --

--   do _ <- as
--      b <- bs
--      pure b
--

(*>) :: Applicative f => f a -> f b -> f b -- | Sequence actions, discarding the value of the second argument. -- -- Using ApplicativeDo: 'as <* bs' can be -- understood as the do expression -- --

--   do a <- as
--      bs
--      pure a
--

(<*) :: Applicative f => f a -> f b -> f a infixl 4 <* infixl 4 *> infixl 4 <*> -- | One or none. optional :: Alternative f => f a -> f (Maybe a) -- | Lists, but with an Applicative functor based on zipping. newtype ZipList a ZipList :: [a] -> ZipList a [getZipList] :: ZipList a -> [a] -- | The Const functor. newtype Const a (b :: k) Const :: a -> Const a (b :: k) [getConst] :: Const a (b :: k) -> a -- | Lift a ternary function to actions. -- -- Using ApplicativeDo: 'liftA3 f as bs cs' can -- be understood as the do expression -- --

--   do a <- as
--      b <- bs
--      c <- cs
--      pure (f a b c)
--

liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d -- | Lift a function to actions. This function may be used as a value for -- fmap in a Functor instance. -- -- | Using ApplicativeDo: 'liftA f as' can be -- understood as the do expression -- --

--   do a <- as
--      pure (f a)
--

-- -- with an inferred Functor constraint, weaker than -- Applicative. liftA :: Applicative f => (a -> b) -> f a -> f b -- | A variant of <*> with the arguments reversed. -- -- Using ApplicativeDo: 'as <**> fs' can -- be understood as the do expression -- --

--   do a <- as
--      f <- fs
--      pure (f a)
--

(<**>) :: Applicative f => f a -> f (a -> b) -> f b infixl 4 <**> -- | A monoid on applicative functors. -- -- If defined, some and many should be the least solutions -- of the equations: -- --

```
some v = (:) <$> v <*>
--   many v
```
```
many v = some v <|> pure
--   []
```

class Applicative f => Alternative (f :: Type -> Type) -- | The identity of <|> empty :: Alternative f => f a -- | An associative binary operation (<|>) :: Alternative f => f a -> f a -> f a -- | One or more. some :: Alternative f => f a -> f [a] -- | Zero or more. many :: Alternative f => f a -> f [a] infixl 3 <|> orAlt :: (Alternative f, Monoid a) => f a -> f a orEmpty :: Alternative f => Bool -> a -> f a eitherA :: Alternative f => f a -> f b -> f (Either a b) purer :: (Applicative f, Applicative g) => a -> f (g a) liftAA2 :: (Applicative f, Applicative g) => (a -> b -> c) -> f (g a) -> f (g b) -> f (g c) (<<*>>) :: (Applicative f, Applicative g) => f (g (a -> b)) -> f (g a) -> f (g b) infixl 4 <<*>> guarded :: Alternative f => (a -> Bool) -> a -> f a guardedA :: (Functor f, Alternative t) => (a -> f Bool) -> a -> f (t a) -- | When invoked inside mask, this function allows a masked -- asynchronous exception to be raised, if one exists. It is equivalent -- to performing an interruptible operation (see #interruptible), but -- does not involve any actual blocking. -- -- When called outside mask, or inside uninterruptibleMask, -- this function has no effect. allowInterrupt :: IO () -- | Sometimes you want to catch two different sorts of exception. You -- could do something like -- --

--   f = expr `catch` \ (ex :: ArithException) -> handleArith ex
--            `catch` \ (ex :: IOException)    -> handleIO    ex
--

-- -- However, there are a couple of problems with this approach. The first -- is that having two exception handlers is inefficient. However, the -- more serious issue is that the second exception handler will catch -- exceptions in the first, e.g. in the example above, if -- handleArith throws an IOException then the second -- exception handler will catch it. -- -- Instead, we provide a function catches, which would be used -- thus: -- --

--   f = expr `catches` [Handler (\ (ex :: ArithException) -> handleArith ex),
--                       Handler (\ (ex :: IOException)    -> handleIO    ex)]
--

catches :: IO a -> [Handler a] -> IO a -- | You need this when using catches. data Handler a Handler :: (e -> IO a) -> Handler a -- | Like bracket, but only performs the final action if there was -- an exception raised by the in-between computation. bracketOnError :: IO a -> (a -> IO b) -> (a -> IO c) -> IO c -- | A variant of bracket where the return value from the first -- computation is not required. bracket_ :: IO a -> IO b -> IO c -> IO c -- | A specialised variant of bracket with just a computation to run -- afterward. finally :: IO a -> IO b -> IO a -- | When you want to acquire a resource, do some work with it, and then -- release the resource, it is a good idea to use bracket, because -- bracket will install the necessary exception handler to release -- the resource in the event that an exception is raised during the -- computation. If an exception is raised, then bracket will -- re-raise the exception (after performing the release). -- -- A common example is opening a file: -- --

--   bracket
--     (openFile "filename" ReadMode)
--     (hClose)
--     (\fileHandle -> do { ... })
--

-- -- The arguments to bracket are in this order so that we can -- partially apply it, e.g.: -- --

--   withFile name mode = bracket (openFile name mode) hClose
--

bracket :: IO a -> (a -> IO b) -> (a -> IO c) -> IO c -- | Like finally, but only performs the final action if there was -- an exception raised by the computation. onException :: IO a -> IO b -> IO a -- | A variant of try that takes an exception predicate to select -- which exceptions are caught (c.f. catchJust). If the exception -- does not match the predicate, it is re-thrown. tryJust :: Exception e => (e -> Maybe b) -> IO a -> IO (Either b a) -- | Similar to catch, but returns an Either result which is -- (Right a) if no exception of type e was -- raised, or (Left ex) if an exception of type -- e was raised and its value is ex. If any other type -- of exception is raised than it will be propogated up to the next -- enclosing exception handler. -- --

--   try a = catch (Right `liftM` a) (return . Left)
--

try :: Exception e => IO a -> IO (Either e a) -- | This function maps one exception into another as proposed in the paper -- "A semantics for imprecise exceptions". mapException :: (Exception e1, Exception e2) => (e1 -> e2) -> a -> a -- | A version of catchJust with the arguments swapped around (see -- handle). handleJust :: Exception e => (e -> Maybe b) -> (b -> IO a) -> IO a -> IO a -- | A version of catch with the arguments swapped around; useful in -- situations where the code for the handler is shorter. For example: -- --

--   do handle (\NonTermination -> exitWith (ExitFailure 1)) $
--      ...
--

handle :: Exception e => (e -> IO a) -> IO a -> IO a -- | The function catchJust is like catch, but it takes an -- extra argument which is an exception predicate, a function -- which selects which type of exceptions we're interested in. -- --

--   catchJust (\e -> if isDoesNotExistErrorType (ioeGetErrorType e) then Just () else Nothing)
--             (readFile f)
--             (\_ -> do hPutStrLn stderr ("No such file: " ++ show f)
--                       return "")
--

-- -- Any other exceptions which are not matched by the predicate are -- re-raised, and may be caught by an enclosing catch, -- catchJust, etc. catchJust :: Exception e => (e -> Maybe b) -> IO a -> (b -> IO a) -> IO a -- | A pattern match failed. The String gives information about -- the source location of the pattern. newtype PatternMatchFail PatternMatchFail :: String -> PatternMatchFail -- | A record selector was applied to a constructor without the appropriate -- field. This can only happen with a datatype with multiple -- constructors, where some fields are in one constructor but not -- another. The String gives information about the source -- location of the record selector. newtype RecSelError RecSelError :: String -> RecSelError -- | An uninitialised record field was used. The String gives -- information about the source location where the record was -- constructed. newtype RecConError RecConError :: String -> RecConError -- | A record update was performed on a constructor without the appropriate -- field. This can only happen with a datatype with multiple -- constructors, where some fields are in one constructor but not -- another. The String gives information about the source -- location of the record update. newtype RecUpdError RecUpdError :: String -> RecUpdError -- | A class method without a definition (neither a default definition, nor -- a definition in the appropriate instance) was called. The -- String gives information about which method it was. newtype NoMethodError NoMethodError :: String -> NoMethodError -- | An expression that didn't typecheck during compile time was called. -- This is only possible with -fdefer-type-errors. The String -- gives details about the failed type check. newtype TypeError TypeError :: String -> TypeError -- | Thrown when the runtime system detects that the computation is -- guaranteed not to terminate. Note that there is no guarantee that the -- runtime system will notice whether any given computation is guaranteed -- to terminate or not. data NonTermination NonTermination :: NonTermination -- | Thrown when the program attempts to call atomically, from the -- stm package, inside another call to atomically. data NestedAtomically NestedAtomically :: NestedAtomically -- | Raise an IOError in the IO monad. ioError :: IOError -> IO a asyncExceptionFromException :: Exception e => SomeException -> Maybe e asyncExceptionToException :: Exception e => e -> SomeException -- | The thread is blocked on an MVar, but there are no other -- references to the MVar so it can't ever continue. data BlockedIndefinitelyOnMVar BlockedIndefinitelyOnMVar :: BlockedIndefinitelyOnMVar -- | The thread is waiting to retry an STM transaction, but there are no -- other references to any TVars involved, so it can't ever -- continue. data BlockedIndefinitelyOnSTM BlockedIndefinitelyOnSTM :: BlockedIndefinitelyOnSTM -- | There are no runnable threads, so the program is deadlocked. The -- Deadlock exception is raised in the main thread only. data Deadlock Deadlock :: Deadlock -- | This thread has exceeded its allocation limit. See -- setAllocationCounter and enableAllocationLimit. data AllocationLimitExceeded AllocationLimitExceeded :: AllocationLimitExceeded -- | Compaction found an object that cannot be compacted. Functions cannot -- be compacted, nor can mutable objects or pinned objects. See -- compact. newtype CompactionFailed CompactionFailed :: String -> CompactionFailed -- | assert was applied to False. newtype AssertionFailed AssertionFailed :: String -> AssertionFailed -- | Superclass for asynchronous exceptions. data SomeAsyncException SomeAsyncException :: e -> SomeAsyncException -- | Asynchronous exceptions. data AsyncException -- | The current thread's stack exceeded its limit. Since an exception has -- been raised, the thread's stack will certainly be below its limit -- again, but the programmer should take remedial action immediately. StackOverflow :: AsyncException -- | The program's heap is reaching its limit, and the program should take -- action to reduce the amount of live data it has. Notes: -- --

It is undefined which thread receives this exception. GHC -- currently throws this to the same thread that receives -- UserInterrupt, but this may change in the future.
The GHC RTS currently can only recover from heap overflow if it -- detects that an explicit memory limit (set via RTS flags). has been -- exceeded. Currently, failure to allocate memory from the operating -- system results in immediate termination of the program.

HeapOverflow :: AsyncException -- | This exception is raised by another thread calling killThread, -- or by the system if it needs to terminate the thread for some reason. ThreadKilled :: AsyncException -- | This exception is raised by default in the main thread of the program -- when the user requests to terminate the program via the usual -- mechanism(s) (e.g. Control-C in the console). UserInterrupt :: AsyncException -- | Exceptions generated by array operations data ArrayException -- | An attempt was made to index an array outside its declared bounds. IndexOutOfBounds :: String -> ArrayException -- | An attempt was made to evaluate an element of an array that had not -- been initialized. UndefinedElement :: String -> ArrayException -- | Evaluate the argument to weak head normal form. -- -- evaluate is typically used to uncover any exceptions that a -- lazy value may contain, and possibly handle them. -- -- evaluate only evaluates to weak head normal form. If -- deeper evaluation is needed, the force function from -- Control.DeepSeq may be handy: -- --

--   evaluate $ force x
--

-- -- There is a subtle difference between evaluate x and -- return $! x, analogous to the difference -- between throwIO and throw. If the lazy value x -- throws an exception, return $! x will fail to -- return an IO action and will throw an exception instead. -- evaluate x, on the other hand, always produces an -- IO action; that action will throw an exception upon -- execution iff x throws an exception upon -- evaluation. -- -- The practical implication of this difference is that due to the -- imprecise exceptions semantics, -- --

--   (return $! error "foo") >> error "bar"
--

-- -- may throw either "foo" or "bar", depending on the -- optimizations performed by the compiler. On the other hand, -- --

--   evaluate (error "foo") >> error "bar"
--

-- -- is guaranteed to throw "foo". -- -- The rule of thumb is to use evaluate to force or handle -- exceptions in lazy values. If, on the other hand, you are forcing a -- lazy value for efficiency reasons only and do not care about -- exceptions, you may use return $! x. evaluate :: a -> IO a -- | Like mask, but the masked computation is not interruptible (see -- Control.Exception#interruptible). THIS SHOULD BE USED WITH -- GREAT CARE, because if a thread executing in -- uninterruptibleMask blocks for any reason, then the thread (and -- possibly the program, if this is the main thread) will be unresponsive -- and unkillable. This function should only be necessary if you need to -- mask exceptions around an interruptible operation, and you can -- guarantee that the interruptible operation will only block for a short -- period of time. uninterruptibleMask :: ((forall a. () => IO a -> IO a) -> IO b) -> IO b -- | Like uninterruptibleMask, but does not pass a restore -- action to the argument. uninterruptibleMask_ :: IO a -> IO a -- | Executes an IO computation with asynchronous exceptions masked. -- That is, any thread which attempts to raise an exception in the -- current thread with throwTo will be blocked until asynchronous -- exceptions are unmasked again. -- -- The argument passed to mask is a function that takes as its -- argument another function, which can be used to restore the prevailing -- masking state within the context of the masked computation. For -- example, a common way to use mask is to protect the acquisition -- of a resource: -- --

--   mask $ \restore -> do
--       x <- acquire
--       restore (do_something_with x) `onException` release
--       release
--

-- -- This code guarantees that acquire is paired with -- release, by masking asynchronous exceptions for the critical -- parts. (Rather than write this code yourself, it would be better to -- use bracket which abstracts the general pattern). -- -- Note that the restore action passed to the argument to -- mask does not necessarily unmask asynchronous exceptions, it -- just restores the masking state to that of the enclosing context. Thus -- if asynchronous exceptions are already masked, mask cannot be -- used to unmask exceptions again. This is so that if you call a library -- function with exceptions masked, you can be sure that the library call -- will not be able to unmask exceptions again. If you are writing -- library code and need to use asynchronous exceptions, the only way is -- to create a new thread; see forkIOWithUnmask. -- -- Asynchronous exceptions may still be received while in the masked -- state if the masked thread blocks in certain ways; see -- Control.Exception#interruptible. -- -- Threads created by forkIO inherit the MaskingState from -- the parent; that is, to start a thread in the -- MaskedInterruptible state, use mask_ $ forkIO .... -- This is particularly useful if you need to establish an exception -- handler in the forked thread before any asynchronous exceptions are -- received. To create a new thread in an unmasked state use -- forkIOWithUnmask. mask :: ((forall a. () => IO a -> IO a) -> IO b) -> IO b -- | Like mask, but does not pass a restore action to the -- argument. mask_ :: IO a -> IO a -- | Returns the MaskingState for the current thread. getMaskingState :: IO MaskingState -- | Allow asynchronous exceptions to be raised even inside mask, -- making the operation interruptible (see the discussion of -- "Interruptible operations" in Exception). -- -- When called outside mask, or inside uninterruptibleMask, -- this function has no effect. interruptible :: IO a -> IO a -- | This is the simplest of the exception-catching functions. It takes a -- single argument, runs it, and if an exception is raised the "handler" -- is executed, with the value of the exception passed as an argument. -- Otherwise, the result is returned as normal. For example: -- --

--   catch (readFile f)
--         (\e -> do let err = show (e :: IOException)
--                   hPutStr stderr ("Warning: Couldn't open " ++ f ++ ": " ++ err)
--                   return "")
--

-- -- Note that we have to give a type signature to e, or the -- program will not typecheck as the type is ambiguous. While it is -- possible to catch exceptions of any type, see the section "Catching -- all exceptions" (in Control.Exception) for an explanation of -- the problems with doing so. -- -- For catching exceptions in pure (non-IO) expressions, see the -- function evaluate. -- -- Note that due to Haskell's unspecified evaluation order, an expression -- may throw one of several possible exceptions: consider the expression -- (error "urk") + (1 `div` 0). Does the expression throw -- ErrorCall "urk", or DivideByZero? -- -- The answer is "it might throw either"; the choice is -- non-deterministic. If you are catching any type of exception then you -- might catch either. If you are calling catch with type IO -- Int -> (ArithException -> IO Int) -> IO Int then the -- handler may get run with DivideByZero as an argument, or an -- ErrorCall "urk" exception may be propogated further up. If -- you call it again, you might get a the opposite behaviour. This is ok, -- because catch is an IO computation. catch :: Exception e => IO a -> (e -> IO a) -> IO a -- | Describes the behaviour of a thread when an asynchronous exception is -- received. data MaskingState -- | asynchronous exceptions are unmasked (the normal state) Unmasked :: MaskingState -- | the state during mask: asynchronous exceptions are masked, but -- blocking operations may still be interrupted MaskedInterruptible :: MaskingState -- | the state during uninterruptibleMask: asynchronous exceptions -- are masked, and blocking operations may not be interrupted MaskedUninterruptible :: MaskingState -- | Exceptions that occur in the IO monad. An -- IOException records a more specific error type, a descriptive -- string and maybe the handle that was used when the error was flagged. data IOException -- | This is thrown when the user calls error. The first -- String is the argument given to error, second -- String is the location. data ErrorCall ErrorCallWithLocation :: String -> String -> ErrorCall pattern ErrorCall :: String -> ErrorCall -- | Any type that you wish to throw or catch as an exception must be an -- instance of the Exception class. The simplest case is a new -- exception type directly below the root: -- --

--   data MyException = ThisException | ThatException
--       deriving Show
--   
--   instance Exception MyException
--

-- -- The default method definitions in the Exception class do what -- we need in this case. You can now throw and catch -- ThisException and ThatException as exceptions: -- --

--   *Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
--   Caught ThisException
--

-- -- In more complicated examples, you may wish to define a whole hierarchy -- of exceptions: -- --

--   ---------------------------------------------------------------------
--   -- Make the root exception type for all the exceptions in a compiler
--   
--   data SomeCompilerException = forall e . Exception e => SomeCompilerException e
--   
--   instance Show SomeCompilerException where
--       show (SomeCompilerException e) = show e
--   
--   instance Exception SomeCompilerException
--   
--   compilerExceptionToException :: Exception e => e -> SomeException
--   compilerExceptionToException = toException . SomeCompilerException
--   
--   compilerExceptionFromException :: Exception e => SomeException -> Maybe e
--   compilerExceptionFromException x = do
--       SomeCompilerException a <- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make a subhierarchy for exceptions in the frontend of the compiler
--   
--   data SomeFrontendException = forall e . Exception e => SomeFrontendException e
--   
--   instance Show SomeFrontendException where
--       show (SomeFrontendException e) = show e
--   
--   instance Exception SomeFrontendException where
--       toException = compilerExceptionToException
--       fromException = compilerExceptionFromException
--   
--   frontendExceptionToException :: Exception e => e -> SomeException
--   frontendExceptionToException = toException . SomeFrontendException
--   
--   frontendExceptionFromException :: Exception e => SomeException -> Maybe e
--   frontendExceptionFromException x = do
--       SomeFrontendException a <- fromException x
--       cast a
--   
--   ---------------------------------------------------------------------
--   -- Make an exception type for a particular frontend compiler exception
--   
--   data MismatchedParentheses = MismatchedParentheses
--       deriving Show
--   
--   instance Exception MismatchedParentheses where
--       toException   = frontendExceptionToException
--       fromException = frontendExceptionFromException
--

-- -- We can now catch a MismatchedParentheses exception as -- MismatchedParentheses, SomeFrontendException or -- SomeCompilerException, but not other types, e.g. -- IOException: -- --

--   *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
--   Caught MismatchedParentheses
--   *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
--   Caught MismatchedParentheses
--   *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
--   Caught MismatchedParentheses
--   *Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
--   *** Exception: MismatchedParentheses
--

class (Typeable e, Show e) => Exception e toException :: Exception e => e -> SomeException fromException :: Exception e => SomeException -> Maybe e -- | Render this exception value in a human-friendly manner. -- -- Default implementation: show. displayException :: Exception e => e -> String -- | Arithmetic exceptions. data ArithException Overflow :: ArithException Underflow :: ArithException LossOfPrecision :: ArithException DivideByZero :: ArithException Denormal :: ArithException RatioZeroDenominator :: ArithException -- | The SomeException type is the root of the exception type -- hierarchy. When an exception of type e is thrown, behind the -- scenes it is encapsulated in a SomeException. data SomeException SomeException :: e -> SomeException hush :: Alternative m => Either e a -> m a note :: MonadError e m => e -> Maybe a -> m a tryIO :: MonadIO m => IO a -> ExceptT IOException m a -- | Lifted throwIO throwIO :: (MonadIO m, Exception e) => e -> m a -- | Lifted throwTo throwTo :: (MonadIO m, Exception e) => ThreadId -> e -> m () -- | Class for string-like datastructures; used by the overloaded string -- extension (-XOverloadedStrings in GHC). class IsString a headMay :: [a] -> Maybe a headDef :: a -> [a] -> a initMay :: [a] -> Maybe [a] initDef :: [a] -> [a] -> [a] initSafe :: [a] -> [a] tailMay :: [a] -> Maybe [a] tailDef :: [a] -> [a] -> [a] tailSafe :: [a] -> [a] lastMay :: [a] -> Maybe a lastDef :: a -> [a] -> a minimumMay :: Ord a => [a] -> Maybe a maximumMay :: Ord a => [a] -> Maybe a minimumDef :: Ord a => a -> [a] -> a maximumDef :: Ord a => a -> [a] -> a foldr1May :: (a -> a -> a) -> [a] -> Maybe a foldl1May :: (a -> a -> a) -> [a] -> Maybe a foldl1May' :: (a -> a -> a) -> [a] -> Maybe a atMay :: [a] -> Int -> Maybe a atDef :: a -> [a] -> Int -> a -- | The Eq class defines equality (==) and inequality -- (/=). All the basic datatypes exported by the Prelude -- are instances of Eq, and Eq may be derived for any -- datatype whose constituents are also instances of Eq. -- -- The Haskell Report defines no laws for Eq. However, == -- is customarily expected to implement an equivalence relationship where -- two values comparing equal are indistinguishable by "public" -- functions, with a "public" function being one not allowing to see -- implementation details. For example, for a type representing -- non-normalised natural numbers modulo 100, a "public" function doesn't -- make the difference between 1 and 201. It is expected to have the -- following properties: -- --

Reflexivity x == x = True
Symmetry x == y = y == x
Transitivity if x == y && y == z = -- True, then x == z = True
Substitutivity if x == y = True and -- f is a "public" function whose return type is an instance of -- Eq, then f x == f y = True
Negation x /= y = not (x == -- y)

-- -- Minimal complete definition: either == or /=. class Eq a (==) :: Eq a => a -> a -> Bool (/=) :: Eq a => a -> a -> Bool infix 4 == infix 4 /= -- | The Ord class is used for totally ordered datatypes. -- -- Instances of Ord can be derived for any user-defined datatype -- whose constituent types are in Ord. The declared order of the -- constructors in the data declaration determines the ordering in -- derived Ord instances. The Ordering datatype allows a -- single comparison to determine the precise ordering of two objects. -- -- The Haskell Report defines no laws for Ord. However, -- <= is customarily expected to implement a non-strict partial -- order and have the following properties: -- --

Transitivity if x <= y && y <= -- z = True, then x <= z = True
Reflexivity x <= x = True
Antisymmetry if x <= y && y <= -- x = True, then x == y = True

-- -- Note that the following operator interactions are expected to hold: -- --

x >= y = y <= x
x < y = x <= y && x /= y
x > y = y < x
x < y = compare x y == LT
x > y = compare x y == GT
x == y = compare x y == EQ
min x y == if x <= y then x else y = True
max x y == if x >= y then x else y = True

-- -- Note that (7.) and (8.) do not require min and -- max to return either of their arguments. The result is merely -- required to equal one of the arguments in terms of (==). -- -- Minimal complete definition: either compare or <=. -- Using compare 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 infix 4 < infix 4 <= infix 4 > infix 4 >= data Ordering LT :: Ordering EQ :: Ordering GT :: Ordering -- |

--   comparing p x y = compare (p x) (p y)
--

-- -- Useful combinator for use in conjunction with the xxxBy -- family of functions from Data.List, for example: -- --

--   ... sortBy (comparing fst) ...
--

comparing :: Ord a => (b -> a) -> b -> b -> Ordering -- | The Down type allows you to reverse sort order conveniently. A -- value of type Down a contains a value of type -- a (represented as Down a). If a has -- an Ord instance associated with it then comparing two -- values thus wrapped will give you the opposite of their normal sort -- order. This is particularly useful when sorting in generalised list -- comprehensions, as in: then sortWith by Down x newtype Down a Down :: a -> Down a -- | Data structures that can be folded. -- -- For example, given a data type -- --

--   data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--

-- -- a suitable instance would be -- --

--   instance Foldable Tree where
--      foldMap f Empty = mempty
--      foldMap f (Leaf x) = f x
--      foldMap f (Node l k r) = foldMap f l `mappend` f k `mappend` foldMap f r
--

-- -- This is suitable even for abstract types, as the monoid is assumed to -- satisfy the monoid laws. Alternatively, one could define -- foldr: -- --

--   instance Foldable Tree where
--      foldr f z Empty = z
--      foldr f z (Leaf x) = f x z
--      foldr f z (Node l k r) = foldr f (f k (foldr f z r)) l
--

-- -- Foldable instances are expected to satisfy the following -- laws: -- --

--   foldr f z t = appEndo (foldMap (Endo . f) t ) z
--

-- --

--   foldl f z t = appEndo (getDual (foldMap (Dual . Endo . flip f) t)) z
--

-- --

--   fold = foldMap id
--

-- --

--   length = getSum . foldMap (Sum . const  1)
--

-- -- sum, product, maximum, and minimum -- should all be essentially equivalent to foldMap forms, such -- as -- --

--   sum = getSum . foldMap Sum
--

-- -- but may be less defined. -- -- If the type is also a Functor instance, it should satisfy -- --

--   foldMap f = fold . fmap f
--

-- -- which implies that -- --

--   foldMap f . fmap g = foldMap (f . g)
--

class Foldable (t :: Type -> Type) -- | Combine the elements of a structure using a monoid. fold :: (Foldable t, Monoid m) => t m -> m -- | Map each element of the structure to a monoid, and combine the -- results. foldMap :: (Foldable t, Monoid m) => (a -> m) -> t a -> m -- | Right-associative fold of a structure. -- -- In the case of lists, foldr, when 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: -- --

--   foldr f z [x1, x2, ..., xn] == x1 `f` (x2 `f` ... (xn `f` z)...)
--

--   foldr f z = foldr f z . toList
--

foldr :: Foldable t => (a -> b -> b) -> b -> t a -> b -- | Right-associative fold of a structure, but with strict application of -- the operator. foldr' :: Foldable t => (a -> b -> b) -> b -> t a -> b -- | Left-associative fold of a structure. -- -- In the case of lists, foldl, when 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: -- --

--   foldl f z [x1, x2, ..., xn] == (...((z `f` x1) `f` x2) `f`...) `f` xn
--

--   foldl f z = foldl f z . toList
--

foldl :: Foldable t => (b -> a -> b) -> b -> t a -> b -- | Left-associative fold of a structure but with strict application of -- the operator. -- -- This ensures that each step of the fold is forced to weak head normal -- form before being applied, avoiding the collection of thunks that -- would otherwise occur. This is often what you want to strictly reduce -- a finite list to a single, monolithic result (e.g. length). -- -- For a general Foldable structure this should be semantically -- identical to, -- --

--   foldl' f z = foldl' f z . toList
--

foldl' :: Foldable t => (b -> a -> b) -> b -> t a -> b -- | List of elements of a structure, from left to right. toList :: Foldable t => t a -> [a] -- | Test whether the structure is empty. The default implementation is -- optimized for structures that are similar to cons-lists, because there -- is no general way to do better. null :: Foldable t => t a -> Bool -- | Returns the size/length of a finite structure as an Int. The -- default implementation is optimized for structures that are similar to -- cons-lists, because there is no general way to do better. length :: Foldable t => t a -> Int -- | Does the element occur in the structure? elem :: (Foldable t, Eq a) => a -> t a -> Bool -- | The largest element of a non-empty structure. maximum :: (Foldable t, Ord a) => t a -> a -- | The least element of a non-empty structure. minimum :: (Foldable t, Ord a) => t a -> a infix 4 `elem` -- | forM_ is mapM_ with its arguments flipped. For a version -- that doesn't ignore the results see forM. -- -- As of base 4.8.0.0, forM_ is just for_, specialized to -- Monad. forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m () -- | Map each element of a structure to a monadic action, evaluate these -- actions from left to right, and ignore the results. For a version that -- doesn't ignore the results see mapM. -- -- As of base 4.8.0.0, mapM_ is just traverse_, specialized -- to Monad. mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m () -- | The find function takes a predicate and a structure and returns -- the leftmost element of the structure matching the predicate, or -- Nothing if there is no such element. find :: Foldable t => (a -> Bool) -> t a -> Maybe a -- | notElem is the negation of elem. notElem :: (Foldable t, Eq a) => a -> t a -> Bool infix 4 `notElem` -- | The least element of a non-empty structure with respect to the given -- comparison function. minimumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a -- | The largest element of a non-empty structure with respect to the given -- comparison function. maximumBy :: Foldable t => (a -> a -> Ordering) -> t a -> a -- | Determines whether all elements of the structure satisfy the -- predicate. all :: Foldable t => (a -> Bool) -> t a -> Bool -- | Determines whether any element of the structure satisfies the -- predicate. any :: Foldable t => (a -> Bool) -> t a -> Bool -- | or returns the disjunction of a container of Bools. For the -- result to be False, the container must be finite; True, -- however, results from a True value finitely far from the left -- end. or :: Foldable t => t Bool -> Bool -- | and returns the conjunction of a container of Bools. For the -- result to be True, the container must be finite; False, -- however, results from a False value finitely far from the left -- end. and :: Foldable t => t Bool -> Bool -- | Map a function over all the elements of a container and concatenate -- the resulting lists. concatMap :: Foldable t => (a -> [b]) -> t a -> [b] -- | The concatenation of all the elements of a container of lists. concat :: Foldable t => t [a] -> [a] -- | The sum of a collection of actions, generalizing concat. As of -- base 4.8.0.0, msum is just asum, specialized to -- MonadPlus. msum :: (Foldable t, MonadPlus m) => t (m a) -> m a -- | The sum of a collection of actions, generalizing concat. -- --

--   >>> asum [Just "Hello", Nothing, Just "World"]
--   Just "Hello"
--

asum :: (Foldable t, Alternative f) => t (f a) -> f a -- | Evaluate each monadic action in the structure from left to right, and -- ignore the results. For a version that doesn't ignore the results see -- sequence. -- -- As of base 4.8.0.0, sequence_ is just sequenceA_, -- specialized to Monad. sequence_ :: (Foldable t, Monad m) => t (m a) -> m () -- | Evaluate each action in the structure from left to right, and ignore -- the results. For a version that doesn't ignore the results see -- sequenceA. sequenceA_ :: (Foldable t, Applicative f) => t (f a) -> f () -- | for_ is traverse_ with its arguments flipped. For a -- version that doesn't ignore the results see for. -- --

--   >>> for_ [1..4] print
--   1
--   2
--   3
--   4
--

for_ :: (Foldable t, Applicative f) => t a -> (a -> f b) -> f () -- | Map each element of a structure to an action, evaluate these actions -- from left to right, and ignore the results. For a version that doesn't -- ignore the results see traverse. traverse_ :: (Foldable t, Applicative f) => (a -> f b) -> t a -> f () -- | Monadic fold over the elements of a structure, associating to the -- left, i.e. from left to right. foldlM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b -- | Monadic fold over the elements of a structure, associating to the -- right, i.e. from right to left. foldrM :: (Foldable t, Monad m) => (a -> b -> m b) -> b -> t a -> m b -- | The class of semigroups (types with an associative binary operation). -- -- Instances should satisfy the following: -- --

Associativity x <> (y <> z) = -- (x <> y) <> z

class Semigroup a -- | Reduce a non-empty list with <> -- -- The default definition should be sufficient, but this can be -- overridden for efficiency. -- --

--   >>> import Data.List.NonEmpty
--   
--   >>> sconcat $ "Hello" :| [" ", "Haskell", "!"]
--   "Hello Haskell!"
--

sconcat :: Semigroup a => NonEmpty a -> a -- | Repeat a value n times. -- -- Given that this works on a Semigroup it is allowed to fail if -- you request 0 or fewer repetitions, and the default definition will do -- so. -- -- By making this a member of the class, idempotent semigroups and -- monoids can upgrade this to execute in <math> by picking -- stimes = stimesIdempotent or stimes = -- stimesIdempotentMonoid respectively. -- --

--   >>> stimes 4 [1]
--   [1,1,1,1]
--

stimes :: (Semigroup a, Integral b) => b -> a -> a -- | Fold an Option case-wise, just like maybe. option :: b -> (a -> b) -> Option a -> b -- | Repeat a value n times. -- --

--   mtimesDefault n a = a <> a <> ... <> a  -- using <> (n-1) times
--

-- -- Implemented using stimes and mempty. -- -- This is a suitable definition for an mtimes member of -- Monoid. mtimesDefault :: (Integral b, Monoid a) => b -> a -> a -- | This lets you use a difference list of a Semigroup as a -- Monoid. diff :: Semigroup m => m -> Endo m -- | A generalization of cycle to an arbitrary Semigroup. May -- fail to terminate for some values in some semigroups. cycle1 :: Semigroup m => m -> m -- | Provide a Semigroup for an arbitrary Monoid. -- -- NOTE: This is not needed anymore since Semigroup became -- a superclass of Monoid in base-4.11 and this newtype be -- deprecated at some point in the future. data WrappedMonoid m -- | Option is effectively Maybe with a better instance of -- Monoid, built off of an underlying Semigroup instead of -- an underlying Monoid. -- -- Ideally, this type would not exist at all and we would just fix the -- Monoid instance of Maybe. -- -- In GHC 8.4 and higher, the Monoid instance for Maybe has -- been corrected to lift a Semigroup instance instead of a -- Monoid instance. Consequently, this type is no longer useful. -- It will be marked deprecated in GHC 8.8 and removed in GHC 8.10. newtype Option a Option :: Maybe a -> Option a [getOption] :: Option a -> Maybe a -- | This is a valid definition of stimes for a Monoid. -- -- Unlike the default definition of stimes, it is defined for 0 -- and so it should be preferred where possible. stimesMonoid :: (Integral b, Monoid a) => b -> a -> a -- | This is a valid definition of stimes for an idempotent -- Semigroup. -- -- When x <> x = x, this definition should be preferred, -- because it works in <math> rather than <math>. stimesIdempotent :: Integral b => b -> a -> a -- | This is a valid definition of stimes for an idempotent -- Monoid. -- -- When mappend x x = x, this definition should be preferred, -- because it works in <math> rather than <math> stimesIdempotentMonoid :: (Integral b, Monoid a) => b -> a -> a -- | A bifunctor is a type constructor that takes two type arguments and is -- a functor in both arguments. That is, unlike with -- Functor, a type constructor such as Either does not need -- to be partially applied for a Bifunctor instance, and the -- methods in this class permit mapping functions over the Left -- value or the Right value, or both at the same time. -- -- Formally, the class Bifunctor represents a bifunctor from -- Hask -> Hask. -- -- Intuitively it is a bifunctor where both the first and second -- arguments are covariant. -- -- You can define a Bifunctor by either defining bimap or -- by defining both first and second. -- -- If you supply bimap, you should ensure that: -- --

--   bimap id id ≡ id
--

-- -- If you supply first and second, ensure: -- --

--   first id ≡ id
--   second id ≡ id
--

-- -- If you supply both, you should also ensure: -- --

--   bimap f g ≡ first f . second g
--

-- -- These ensure by parametricity: -- --

--   bimap  (f . g) (h . i) ≡ bimap f h . bimap g i
--   first  (f . g) ≡ first  f . first  g
--   second (f . g) ≡ second f . second g
--

class Bifunctor (p :: Type -> Type -> Type) -- | Map over both arguments at the same time. -- --

--   bimap f g ≡ first f . second g
--

-- --

Examples

-- --

--   >>> bimap toUpper (+1) ('j', 3)
--   ('J',4)
--

-- --

--   >>> bimap toUpper (+1) (Left 'j')
--   Left 'J'
--

-- --

--   >>> bimap toUpper (+1) (Right 3)
--   Right 4
--

bimap :: Bifunctor p => (a -> b) -> (c -> d) -> p a c -> p b d -- | Map covariantly over the first argument. -- --

--   first f ≡ bimap f id
--

-- --

Examples

-- --

--   >>> first toUpper ('j', 3)
--   ('J',3)
--

-- --

--   >>> first toUpper (Left 'j')
--   Left 'J'
--

first :: Bifunctor p => (a -> b) -> p a c -> p b c -- | Map covariantly over the second argument. -- --

--   second ≡ bimap id
--

-- --

Examples

-- --

--   >>> second (+1) ('j', 3)
--   ('j',4)
--

-- --

--   >>> second (+1) (Right 3)
--   Right 4
--

second :: Bifunctor p => (b -> c) -> p a b -> p a c -- | Transform a value into a Hashable value, then hash the -- transformed value using the given salt. -- -- This is a useful shorthand in cases where a type can easily be mapped -- to another type that is already an instance of Hashable. -- Example: -- --

--   data Foo = Foo | Bar
--            deriving (Enum)
--   
--   instance Hashable Foo where
--       hashWithSalt = hashUsing fromEnum
--

hashUsing :: Hashable b => (a -> b) -> Int -> a -> Int -- | The class of types that can be converted to a hash value. -- -- Minimal implementation: hashWithSalt. -- -- Note: the hash is not guaranteed to be stable across library -- versions, operating systems or architectures. For stable hashing use -- named hashes: SHA256, CRC32 etc. -- -- If you are looking for Hashable instance in time -- package, check time-compat class Eq a => Hashable a -- | Return a hash value for the argument, using the given salt. -- -- The general contract of hashWithSalt is: -- --

If two values are equal according to the == method, then -- applying the hashWithSalt method on each of the two values -- must produce the same integer result if the same salt is used -- in each case.
It is not required that if two values are unequal according -- to the == method, then applying the hashWithSalt method -- on each of the two values must produce distinct integer results. -- However, the programmer should be aware that producing distinct -- integer results for unequal values may improve the performance of -- hashing-based data structures.
This method can be used to compute different hash values for the -- same input by providing a different salt in each application of the -- method. This implies that any instance that defines -- hashWithSalt must make use of the salt in its -- implementation.
hashWithSalt may return negative Int values.

hashWithSalt :: Hashable a => Int -> a -> Int -- | Like hashWithSalt, but no salt is used. The default -- implementation uses hashWithSalt with some default salt. -- Instances might want to implement this method to provide a more -- efficient implementation than the default implementation. hash :: Hashable a => a -> Int infixl 0 `hashWithSalt` -- | a variant of deepseq that is useful in some circumstances: -- --

--   force x = x `deepseq` x
--

-- -- force x fully evaluates x, and then returns it. Note -- that force x only performs evaluation when the value of -- force x itself is demanded, so essentially it turns shallow -- evaluation into deep evaluation. -- -- force can be conveniently used in combination with -- ViewPatterns: -- --

--   {-# LANGUAGE BangPatterns, ViewPatterns #-}
--   import Control.DeepSeq
--   
--   someFun :: ComplexData -> SomeResult
--   someFun (force -> !arg) = {- 'arg' will be fully evaluated -}
--

-- -- Another useful application is to combine force with -- evaluate in order to force deep evaluation relative to other -- IO operations: -- --

--   import Control.Exception (evaluate)
--   import Control.DeepSeq
--   
--   main = do
--     result <- evaluate $ force $ pureComputation
--     {- 'result' will be fully evaluated at this point -}
--     return ()
--

-- -- Finally, here's an exception safe variant of the readFile' -- example: -- --

--   readFile' :: FilePath -> IO String
--   readFile' fn = bracket (openFile fn ReadMode) hClose $ \h ->
--                          evaluate . force =<< hGetContents h
--

force :: NFData a => a -> a -- | the deep analogue of $!. In the expression f $!! x, -- x is fully evaluated before the function f is -- applied to it. ($!!) :: NFData a => (a -> b) -> a -> b infixr 0 $!! -- | deepseq: fully evaluates the first argument, before returning -- the second. -- -- The name deepseq is used to illustrate the relationship to -- seq: where seq is shallow in the sense that it only -- evaluates the top level of its argument, deepseq traverses the -- entire data structure evaluating it completely. -- -- deepseq can be useful for forcing pending exceptions, -- eradicating space leaks, or forcing lazy I/O to happen. It is also -- useful in conjunction with parallel Strategies (see the -- parallel package). -- -- There is no guarantee about the ordering of evaluation. The -- implementation may evaluate the components of the structure in any -- order or in parallel. To impose an actual order on evaluation, use -- pseq from Control.Parallel in the parallel -- package. deepseq :: NFData a => a -> b -> b -- | A class of types that can be fully evaluated. class NFData a -- | rnf should reduce its argument to normal form (that is, fully -- evaluate all sub-components), and then return (). -- --

Generic NFData deriving

-- -- Starting with GHC 7.2, you can automatically derive instances for -- types possessing a Generic instance. -- -- Note: Generic1 can be auto-derived starting with GHC 7.4 -- --

--   {-# LANGUAGE DeriveGeneric #-}
--   
--   import GHC.Generics (Generic, Generic1)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic, Generic1)
--   
--   instance NFData a => NFData (Foo a)
--   instance NFData1 Foo
--   
--   data Colour = Red | Green | Blue
--                 deriving Generic
--   
--   instance NFData Colour
--

-- -- Starting with GHC 7.10, the example above can be written more -- concisely by enabling the new DeriveAnyClass extension: -- --

--   {-# LANGUAGE DeriveGeneric, DeriveAnyClass #-}
--   
--   import GHC.Generics (Generic)
--   import Control.DeepSeq
--   
--   data Foo a = Foo a String
--                deriving (Eq, Generic, Generic1, NFData, NFData1)
--   
--   data Colour = Red | Green | Blue
--                 deriving (Generic, NFData)
--

-- --

Compatibility with previous `deepseq` versions

-- -- Prior to version 1.4.0.0, the default implementation of the rnf -- method was defined as -- --

--   rnf a = seq a ()
--

-- -- However, starting with deepseq-1.4.0.0, the default -- implementation is based on DefaultSignatures allowing for -- more accurate auto-derived NFData instances. If you need the -- previously used exact default rnf method implementation -- semantics, use -- --

--   instance NFData Colour where rnf x = seq x ()
--

-- -- or alternatively -- --

--   instance NFData Colour where rnf = rwhnf
--

-- -- or -- --

--   {-# LANGUAGE BangPatterns #-}
--   instance NFData Colour where rnf !_ = ()
--

rnf :: NFData a => a -> () -- | Extract the first component of a pair. fst :: (a, b) -> a -- | Extract the second component of a pair. snd :: (a, b) -> b -- | Swap the components of a pair. swap :: (a, b) -> (b, a) -- | uncurry converts a curried function to a function on pairs. -- --

Examples

-- --

--   >>> uncurry (+) (1,2)
--   3
--

-- --

--   >>> uncurry ($) (show, 1)
--   "1"
--

-- --

--   >>> map (uncurry max) [(1,2), (3,4), (6,8)]
--   [2,4,8]
--

uncurry :: (a -> b -> c) -> (a, b) -> c -- | curry converts an uncurried function to a curried function. -- --

Examples

-- --

--   >>> curry fst 1 2
--   1
--

curry :: ((a, b) -> c) -> a -> b -> c -- | The class Typeable allows a concrete representation of a type -- to be calculated. class Typeable (a :: k) -- | A flexible variation parameterised in a type constructor gcast :: forall k (a :: k) (b :: k) c. (Typeable a, Typeable b) => c a -> Maybe (c b) -- | Extract a witness of equality of two types eqT :: forall k (a :: k) (b :: k). (Typeable a, Typeable b) => Maybe (a :~: b) -- | The type-safe cast operation cast :: (Typeable a, Typeable b) => a -> Maybe b -- | Takes a value of type a and returns a concrete representation -- of that type. typeRep :: forall k proxy (a :: k). Typeable a => proxy a -> TypeRep -- | Observe a type representation for the type of a value. typeOf :: Typeable a => a -> TypeRep -- | A quantified type representation. type TypeRep = SomeTypeRep -- | If Void is uninhabited then any Functor that holds only -- values of type Void is holding no values. -- -- Using ApplicativeDo: 'vacuous theVoid' can be -- understood as the do expression -- --

--   do void <- theVoid
--      pure (absurd void)
--

-- -- with an inferred Functor constraint. vacuous :: Functor f => f Void -> f a -- | Since Void values logically don't exist, this witnesses the -- logical reasoning tool of "ex falso quodlibet". -- --

--   >>> let x :: Either Void Int; x = Right 5
--   
--   >>> :{
--   case x of
--       Right r -> r
--       Left l  -> absurd l
--   :}
--   5
--

absurd :: Void -> a -- | Uninhabited data type data Void -- | Proxy is a type that holds no data, but has a phantom parameter -- of arbitrary type (or even kind). Its use is to provide type -- information, even though there is no value available of that type (or -- it may be too costly to create one). -- -- Historically, Proxy :: Proxy a is a safer -- alternative to the undefined :: a idiom. -- --

--   >>> Proxy :: Proxy (Void, Int -> Int)
--   Proxy
--

-- -- Proxy can even hold types of higher kinds, -- --

--   >>> Proxy :: Proxy Either
--   Proxy
--

-- --

--   >>> Proxy :: Proxy Functor
--   Proxy
--

-- --

--   >>> Proxy :: Proxy complicatedStructure
--   Proxy
--

data Proxy (t :: k) Proxy :: Proxy (t :: k) -- | Convert propositional (nominal) equality to representational equality repr :: forall k (a :: k) (b :: k). (a :~: b) -> Coercion a b -- | Type-safe cast, using representational equality coerceWith :: Coercion a b -> a -> b -- | Representational equality. If Coercion a b is inhabited by -- some terminating value, then the type a has the same -- underlying representation as the type b. -- -- To use this equality in practice, pattern-match on the Coercion a -- b to get out the Coercible a b instance, and then use -- coerce to apply it. data Coercion (a :: k) (b :: k) [Coercion] :: forall k (a :: k) (b :: k). Coercible a b => Coercion a b -- | Generalized form of type-safe cast using propositional equality gcastWith :: forall k (a :: k) (b :: k) r. (a :~: b) -> (a ~ b => r) -> r -- | Type-safe cast, using propositional equality castWith :: (a :~: b) -> a -> b -- | Transitivity of equality trans :: forall k (a :: k) (b :: k) (c :: k). (a :~: b) -> (b :~: c) -> a :~: c -- | Symmetry of equality sym :: forall k (a :: k) (b :: k). (a :~: b) -> b :~: a -- | Propositional equality. If a :~: b is inhabited by some -- terminating value, then the type a is the same as the type -- b. To use this equality in practice, pattern-match on the -- a :~: b to get out the Refl constructor; in the body -- of the pattern-match, the compiler knows that a ~ b. data (a :: k) :~: (b :: k) [Refl] :: forall k (a :: k). a :~: a infix 4 :~: -- | A type family to compute Boolean equality. type family (a :: k) == (b :: k) :: Bool infix 4 == -- | When a value is bound in do-notation, the pattern on the left -- hand side of <- might not match. In this case, this class -- provides a function to recover. -- -- A Monad without a MonadFail instance may only be used in -- conjunction with pattern that always match, such as newtypes, tuples, -- data types with only a single data constructor, and irrefutable -- patterns (~pat). -- -- Instances of MonadFail should satisfy the following law: -- fail s should be a left zero for >>=, -- --

--   fail s >>= f  =  fail s
--

-- -- If your Monad is also MonadPlus, a popular definition is -- --

--   fail _ = mzero
--

class Monad m => MonadFail (m :: Type -> Type) -- | Gets specific component of the state, using a projection function -- supplied. gets :: MonadState s m => (s -> a) -> m a -- | Monadic state transformer. -- -- Maps an old state to a new state inside a state monad. The old state -- is thrown away. -- --

--   Main> :t modify ((+1) :: Int -> Int)
--   modify (...) :: (MonadState Int a) => a ()
--

-- -- This says that modify (+1) acts over any Monad that is a -- member of the MonadState class, with an Int state. modify :: MonadState s m => (s -> s) -> m () -- | Minimal definition is either both of get and put or -- just state class Monad m => MonadState s (m :: Type -> Type) | m -> s -- | Return the state from the internals of the monad. get :: MonadState s m => m s -- | Replace the state inside the monad. put :: MonadState s m => s -> m () -- | Embed a simple state action into the monad. state :: MonadState s m => (s -> (a, s)) -> m a -- | A state transformer monad parameterized by: -- --

s - The state.
m - The inner monad.

-- -- The return function leaves the state unchanged, while -- >>= uses the final state of the first computation as -- the initial state of the second. newtype StateT s (m :: Type -> Type) a StateT :: (s -> m (a, s)) -> StateT s (m :: Type -> Type) a [runStateT] :: StateT s (m :: Type -> Type) a -> s -> m (a, s) -- | A state monad parameterized by the type s of the state to -- carry. -- -- The return function leaves the state unchanged, while -- >>= uses the final state of the first computation as -- the initial state of the second. type State s = StateT s Identity -- | Unwrap a state monad computation as a function. (The inverse of -- state.) runState :: State s a -> s -> (a, s) -- | Evaluate a state computation with the given initial state and return -- the final value, discarding the final state. -- --

```
evalState m s = fst (runState m
--   s)
```

evalState :: State s a -> s -> a -- | Evaluate a state computation with the given initial state and return -- the final state, discarding the final value. -- --

```
execState m s = snd (runState m
--   s)
```

execState :: State s a -> s -> s -- | withState f m executes action m on a state -- modified by applying f. -- --

```
withState f m = modify f >> m
```

withState :: (s -> s) -> State s a -> State s a -- | Evaluate a state computation with the given initial state and return -- the final value, discarding the final state. -- --

evalStateT m s = liftM fst
--   (runStateT m s)

evalStateT :: Monad m => StateT s m a -> s -> m a -- | Evaluate a state computation with the given initial state and return -- the final state, discarding the final value. -- --

execStateT m s = liftM snd
--   (runStateT m s)

execStateT :: Monad m => StateT s m a -> s -> m s -- | Retrieves a function of the current environment. asks :: MonadReader r m => (r -> a) -> m a -- | See examples in Control.Monad.Reader. Note, the partially -- applied function type (->) r is a simple reader monad. See -- the instance declaration below. class Monad m => MonadReader r (m :: Type -> Type) | m -> r -- | Retrieves the monad environment. ask :: MonadReader r m => m r -- | Executes a computation in a modified environment. local :: MonadReader r m => (r -> r) -> m a -> m a -- | Retrieves a function of the current environment. reader :: MonadReader r m => (r -> a) -> m a -- | The reader monad transformer, which adds a read-only environment to -- the given monad. -- -- The return function ignores the environment, while -- >>= passes the inherited environment to both -- subcomputations. newtype ReaderT r (m :: Type -> Type) a ReaderT :: (r -> m a) -> ReaderT r (m :: Type -> Type) a [runReaderT] :: ReaderT r (m :: Type -> Type) a -> r -> m a -- | The parameterizable reader monad. -- -- Computations are functions of a shared environment. -- -- The return function ignores the environment, while -- >>= passes the inherited environment to both -- subcomputations. type Reader r = ReaderT r Identity -- | Runs a Reader and extracts the final value from it. (The -- inverse of reader.) runReader :: Reader r a -> r -> a -- | The strategy of combining computations that can throw exceptions by -- bypassing bound functions from the point an exception is thrown to the -- point that it is handled. -- -- Is parameterized over the type of error information and the monad type -- constructor. It is common to use Either String as the -- monad type constructor for an error monad in which error descriptions -- take the form of strings. In that case and many other common cases the -- resulting monad is already defined as an instance of the -- MonadError class. You can also define your own error type -- and/or use a monad type constructor other than Either -- String or Either IOError. In -- these cases you will have to explicitly define instances of the -- MonadError class. (If you are using the deprecated -- Control.Monad.Error or Control.Monad.Trans.Error, you -- may also have to define an Error instance.) class Monad m => MonadError e (m :: Type -> Type) | m -> e -- | Is used within a monadic computation to begin exception processing. throwError :: MonadError e m => e -> m a -- | A handler function to handle previous errors and return to normal -- execution. A common idiom is: -- --

--   do { action1; action2; action3 } `catchError` handler
--

-- -- where the action functions can call throwError. Note -- that handler and the do-block must have the same return type. catchError :: MonadError e m => m a -> (e -> m a) -> m a -- | A monad transformer that adds exceptions to other monads. -- -- ExceptT constructs a monad parameterized over two things: -- --

e - The exception type.
m - The inner monad.

-- -- The return function yields a computation that produces the -- given value, while >>= sequences two subcomputations, -- exiting on the first exception. newtype ExceptT e (m :: Type -> Type) a ExceptT :: m (Either e a) -> ExceptT e (m :: Type -> Type) a -- | The parameterizable exception monad. -- -- Computations are either exceptions or normal values. -- -- The return function returns a normal value, while -- >>= exits on the first exception. For a variant that -- continues after an error and collects all the errors, see -- Errors. type Except e = ExceptT e Identity -- | Extractor for computations in the exception monad. (The inverse of -- except). runExcept :: Except e a -> Either e a -- | Map the unwrapped computation using the given function. -- --

runExcept (mapExcept f m) = f (runExcept
--   m)

mapExcept :: (Either e a -> Either e' b) -> Except e a -> Except e' b -- | Transform any exceptions thrown by the computation using the given -- function (a specialization of withExceptT). withExcept :: (e -> e') -> Except e a -> Except e' a -- | The inverse of ExceptT. runExceptT :: ExceptT e m a -> m (Either e a) -- | Map the unwrapped computation using the given function. -- --

runExceptT (mapExceptT f m) = f
--   (runExceptT m)

mapExceptT :: (m (Either e a) -> n (Either e' b)) -> ExceptT e m a -> ExceptT e' n b -- | Transform any exceptions thrown by the computation using the given -- function. withExceptT :: forall (m :: Type -> Type) e e' a. Functor m => (e -> e') -> ExceptT e m a -> ExceptT e' m a -- | Handle an exception. -- --

```
catchE (lift m) h = lift m
```
```
catchE (throwE e) h = h e
```

catchE :: forall (m :: Type -> Type) e a e'. Monad m => ExceptT e m a -> (e -> ExceptT e' m a) -> ExceptT e' m a -- | Signal an exception value e. -- --

runExceptT (throwE e) = return
--   (Left e)

```
throwE e >>= m = throwE e
```

throwE :: forall (m :: Type -> Type) e a. Monad m => e -> ExceptT e m a -- | Monads in which IO computations may be embedded. Any monad -- built by applying a sequence of monad transformers to the IO -- monad will be an instance of this class. -- -- Instances should satisfy the following laws, which state that -- liftIO is a transformer of monads: -- --

```
liftIO . return = return
```

liftIO (m >>= f) = liftIO m >>=
--   (liftIO . f)

class Monad m => MonadIO (m :: Type -> Type) -- | Lift a computation from the IO monad. liftIO :: MonadIO m => IO a -> m a -- | Lift a computation from the argument monad to the constructed monad. lift :: (MonadTrans t, Monad m) => m a -> t m a -- | The strict ST monad. The ST monad allows for destructive -- updates, but is escapable (unlike IO). A computation of type -- ST s a returns a value of type a, and execute -- in "thread" s. The s parameter is either -- --

an uninstantiated type variable (inside invocations of -- runST), or
RealWorld (inside invocations of stToIO).

-- -- It serves to keep the internal states of different invocations of -- runST separate from each other and from invocations of -- stToIO. -- -- The >>= and >> operations are strict in the -- state (though not in values stored in the state). For example, -- --

--   runST (writeSTRef _|_ v >>= f) = _|_
--

data ST s a -- | Allow the result of an ST computation to be used (lazily) -- inside the computation. -- -- Note that if f is strict, fixST f = _|_. fixST :: (a -> ST s a) -> ST s a -- | Return the value computed by a state thread. The forall -- ensures that the internal state used by the ST computation is -- inaccessible to the rest of the program. runST :: (forall s. () => ST s a) -> a -- | Exception handling within STM actions. -- -- catchSTM m f catches any exception thrown by -- m using throwSTM, using the function f to -- handle the exception. If an exception is thrown, any changes made by -- m are rolled back, but changes prior to m persist. catchSTM :: Exception e => STM a -> (e -> STM a) -> STM a -- | A variant of throw that can only be used within the STM -- monad. -- -- Throwing an exception in STM aborts the transaction and -- propagates the exception. If the exception is caught via -- catchSTM, only the changes enclosed by the catch are rolled -- back; changes made outside of catchSTM persist. -- -- If the exception is not caught inside of the STM, it is -- re-thrown by atomically, and the entire STM is rolled -- back. -- -- Although throwSTM has a type that is an instance of the type of -- throw, the two functions are subtly different: -- --

--   throw e    `seq` x  ===> throw e
--   throwSTM e `seq` x  ===> x
--

-- -- The first example will cause the exception e to be raised, -- whereas the second one won't. In fact, throwSTM will only cause -- an exception to be raised when it is used within the STM monad. -- The throwSTM variant should be used in preference to -- throw to raise an exception within the STM monad because -- it guarantees ordering with respect to other STM operations, -- whereas throw does not. throwSTM :: Exception e => e -> STM a -- | Compose two alternative STM actions (GHC only). -- -- If the first action completes without retrying then it forms the -- result of the orElse. Otherwise, if the first action retries, -- then the second action is tried in its place. If both actions retry -- then the orElse as a whole retries. orElse :: STM a -> STM a -> STM a -- | Retry execution of the current memory transaction because it has seen -- values in TVars which mean that it should not continue (e.g. -- the TVars represent a shared buffer that is now empty). The -- implementation may block the thread until one of the TVars that -- it has read from has been updated. (GHC only) retry :: STM a -- | Perform a series of STM actions atomically. -- -- Using atomically inside an unsafePerformIO or -- unsafeInterleaveIO subverts some of guarantees that STM -- provides. It makes it possible to run a transaction inside of another -- transaction, depending on when the thunk is evaluated. If a nested -- transaction is attempted, an exception is thrown by the runtime. It is -- possible to safely use atomically inside unsafePerformIO -- or unsafeInterleaveIO, but the typechecker does not rule out -- programs that may attempt nested transactions, meaning that the -- programmer must take special care to prevent these. -- -- However, there are functions for creating transactional variables that -- can always be safely called in unsafePerformIO. See: -- newTVarIO, newTChanIO, newBroadcastTChanIO, -- newTQueueIO, newTBQueueIO, and newTMVarIO. -- -- Using unsafePerformIO inside of atomically is also -- dangerous but for different reasons. See unsafeIOToSTM for more -- on this. atomically :: STM a -> IO a -- | A monad supporting atomic memory transactions. data STM a -- | Check that the boolean condition is true and, if not, retry. -- -- In other words, check b = unless b retry. check :: Bool -> STM () -- | A fixed-precision integer type with at least the range [-2^29 .. -- 2^29-1]. The exact range for a given implementation can be -- determined by using minBound and maxBound from the -- Bounded 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 -- | A Word is an unsigned integral type, with the same size as -- Int. 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 -- | Reverse order of bytes in Word64. byteSwap64 :: Word64 -> Word64 -- | Reverse order of bytes in Word32. byteSwap32 :: Word32 -> Word32 -- | Reverse order of bytes in Word16. byteSwap16 :: Word16 -> Word16 -- | Attempt to convert an Integral type a to an -- Integral type b using the size of the types as -- measured by Bits methods. -- -- A simpler version of this function is: -- --

--   toIntegral :: (Integral a, Integral b) => a -> Maybe b
--   toIntegral x
--     | toInteger x == y = Just (fromInteger y)
--     | otherwise        = Nothing
--     where
--       y = toInteger x
--

-- -- This version requires going through Integer, which can be -- inefficient. However, toIntegralSized is optimized to allow -- GHC to statically determine the relative type sizes (as measured by -- bitSizeMaybe and isSigned) and avoid going through -- Integer for many types. (The implementation uses -- fromIntegral, which is itself optimized with rules for -- base types but may go through Integer for some type -- pairs.) toIntegralSized :: (Integral a, Integral b, Bits a, Bits b) => a -> Maybe b -- | Default implementation for popCount. -- -- This implementation is intentionally naive. Instances are expected to -- provide an optimized implementation for their size. popCountDefault :: (Bits a, Num a) => a -> Int -- | Default implementation for testBit. -- -- Note that: testBitDefault x i = (x .&. bit i) /= 0 testBitDefault :: (Bits a, Num a) => a -> Int -> Bool -- | Default implementation for bit. -- -- Note that: bitDefault i = 1 shiftL i bitDefault :: (Bits a, Num a) => Int -> a -- | The Bits class defines bitwise operations over integral types. -- --

Bits are numbered from 0 with bit 0 being the least significant -- bit.

class Eq a => Bits a -- | Bitwise "and" (.&.) :: Bits a => a -> a -> a -- | Bitwise "or" (.|.) :: Bits a => a -> a -> a -- | Bitwise "xor" xor :: Bits a => a -> a -> a -- | Reverse all the bits in the argument complement :: Bits a => a -> a -- | shift x i shifts x left by i bits if -- i is positive, or right by -i bits otherwise. Right -- shifts perform sign extension on signed number types; i.e. they fill -- the top bits with 1 if the x is negative and with 0 -- otherwise. -- -- An instance can define either this unified shift or -- shiftL and shiftR, depending on which is more convenient -- for the type in question. shift :: Bits a => a -> Int -> a -- | rotate x i rotates x left by i bits -- if i is positive, or right by -i bits otherwise. -- -- For unbounded types like Integer, rotate is equivalent -- to shift. -- -- An instance can define either this unified rotate or -- rotateL and rotateR, depending on which is more -- convenient for the type in question. rotate :: Bits a => a -> Int -> a -- | zeroBits is the value with all bits unset. -- -- The following laws ought to hold (for all valid bit indices -- n): -- --

```
clearBit zeroBits n ==
--   zeroBits
```
```
setBit zeroBits n == bit
--   n
```
```
testBit zeroBits n == False
```
```
popCount zeroBits == 0
```

-- -- This method uses clearBit (bit 0) 0 as its -- default implementation (which ought to be equivalent to -- zeroBits for types which possess a 0th bit). zeroBits :: Bits a => a -- | bit i is a value with the ith bit set -- and all other bits clear. -- -- Can be implemented using bitDefault if a is also an -- instance of Num. -- -- See also zeroBits. bit :: Bits a => Int -> a -- | x `setBit` i is the same as x .|. bit i setBit :: Bits a => a -> Int -> a -- | x `clearBit` i is the same as x .&. complement (bit -- i) clearBit :: Bits a => a -> Int -> a -- | x `complementBit` i is the same as x `xor` bit i complementBit :: Bits a => a -> Int -> a -- | Return True if the nth bit of the argument is 1 -- -- Can be implemented using testBitDefault if a is also -- an instance of Num. testBit :: Bits a => a -> Int -> Bool -- | Return the number of bits in the type of the argument. The actual -- value of the argument is ignored. Returns Nothing for types that do -- not have a fixed bitsize, like Integer. bitSizeMaybe :: Bits a => a -> Maybe Int -- | Return the number of bits in the type of the argument. The actual -- value of the argument is ignored. The function bitSize is -- undefined for types that do not have a fixed bitsize, like -- Integer. -- -- Default implementation based upon bitSizeMaybe provided since -- 4.12.0.0. bitSize :: Bits a => a -> Int -- | Return True if the argument is a signed type. The actual value -- of the argument is ignored isSigned :: Bits a => a -> Bool -- | Shift the argument left by the specified number of bits (which must be -- non-negative). Some instances may throw an Overflow exception -- if given a negative input. -- -- An instance can define either this and shiftR or the unified -- shift, depending on which is more convenient for the type in -- question. shiftL :: Bits a => a -> Int -> a -- | Shift the first argument right by the specified number of bits. The -- result is undefined for negative shift amounts and shift amounts -- greater or equal to the bitSize. Some instances may throw an -- Overflow exception if given a negative input. -- -- Right shifts perform sign extension on signed number types; i.e. they -- fill the top bits with 1 if the x is negative and with 0 -- otherwise. -- -- An instance can define either this and shiftL or the unified -- shift, depending on which is more convenient for the type in -- question. shiftR :: Bits a => a -> Int -> a -- | Rotate the argument left by the specified number of bits (which must -- be non-negative). -- -- An instance can define either this and rotateR or the unified -- rotate, depending on which is more convenient for the type in -- question. rotateL :: Bits a => a -> Int -> a -- | Rotate the argument right by the specified number of bits (which must -- be non-negative). -- -- An instance can define either this and rotateL or the unified -- rotate, depending on which is more convenient for the type in -- question. rotateR :: Bits a => a -> Int -> a -- | Return the number of set bits in the argument. This number is known as -- the population count or the Hamming weight. -- -- Can be implemented using popCountDefault if a is also -- an instance of Num. popCount :: Bits a => a -> Int infixl 8 `rotateR` infixl 8 `rotateL` infixl 8 `shiftR` infixl 8 `shiftL` infixl 8 `rotate` infixl 8 `shift` infixl 6 `xor` infixl 7 .&. infixl 5 .|. -- | The FiniteBits class denotes types with a finite, fixed number -- of bits. class Bits b => FiniteBits b -- | Return the number of bits in the type of the argument. The actual -- value of the argument is ignored. Moreover, finiteBitSize is -- total, in contrast to the deprecated bitSize function it -- replaces. -- --

--   finiteBitSize = bitSize
--   bitSizeMaybe = Just . finiteBitSize
--

finiteBitSize :: FiniteBits b => b -> Int -- | Count number of zero bits preceding the most significant set bit. -- --

--   countLeadingZeros (zeroBits :: a) = finiteBitSize (zeroBits :: a)
--

-- -- countLeadingZeros can be used to compute log base 2 via -- --

--   logBase2 x = finiteBitSize x - 1 - countLeadingZeros x
--

--   countTrailingZeros (zeroBits :: a) = finiteBitSize (zeroBits :: a)
--   countTrailingZeros . negate = countTrailingZeros
--

-- -- The related find-first-set operation can be expressed in terms -- of countTrailingZeros as follows -- --

--   findFirstSet x = 1 + countTrailingZeros x
--

-- -- Note: The default implementation for this method is intentionally -- naive. However, the instances provided for the primitive integral -- types are implemented using CPU specific machine instructions. countTrailingZeros :: FiniteBits b => b -> Int -- | The phase of a complex number, in the range (-pi, -- pi]. If the magnitude is zero, then so is the phase. phase :: RealFloat a => Complex a -> a -- | The nonnegative magnitude of a complex number. magnitude :: RealFloat a => Complex a -> a -- | The function polar takes a complex number and returns a -- (magnitude, phase) pair in canonical form: the magnitude is -- nonnegative, and the phase in the range (-pi, -- pi]; if the magnitude is zero, then so is the phase. polar :: RealFloat a => Complex a -> (a, a) -- | cis t is a complex value with magnitude 1 and -- phase t (modulo 2*pi). cis :: Floating a => a -> Complex a -- | Form a complex number from polar components of magnitude and phase. mkPolar :: Floating a => a -> a -> Complex a -- | The conjugate of a complex number. conjugate :: Num a => Complex a -> Complex a -- | Extracts the imaginary part of a complex number. imagPart :: Complex a -> a -- | Extracts the real part of a complex number. realPart :: Complex a -> a -- | Complex numbers are an algebraic type. -- -- For a complex number z, abs z is a number -- with the magnitude of z, but oriented in the positive real -- direction, whereas signum z has the phase of -- z, but unit magnitude. -- -- The Foldable and Traversable instances traverse the real -- part first. -- -- Note that Complex's instances inherit the deficiencies from the -- type parameter's. For example, Complex Float's Ord -- instance has similar problems to Float's. data Complex a -- | forms a complex number from its real and imaginary rectangular -- components. (:+) :: !a -> !a -> Complex a infix 6 :+ -- | The character type Char is an enumeration whose values -- represent Unicode (or equivalently ISO/IEC 10646) code points (i.e. -- characters, see http://www.unicode.org/ 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 -- Char. -- -- To convert a Char to or from the corresponding Int value -- defined by Unicode, use toEnum and fromEnum from the -- Enum class respectively (or equivalently ord and -- chr). data Char -- | 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 isAlpha. -- -- This function returns True if its argument has one of the -- following GeneralCategorys, or False otherwise: -- --

UppercaseLetter
LowercaseLetter
TitlecaseLetter
ModifierLetter
OtherLetter

-- -- These classes are defined in the Unicode Character Database, -- part of the Unicode standard. The same document defines what is and is -- not a "Letter". -- --

Examples

-- -- Basic usage: -- --

--   >>> isLetter 'a'
--   True
--   
--   >>> isLetter 'A'
--   True
--   
--   >>> isLetter 'λ'
--   True
--   
--   >>> isLetter '0'
--   False
--   
--   >>> isLetter '%'
--   False
--   
--   >>> isLetter '♥'
--   False
--   
--   >>> isLetter '\31'
--   False
--

-- -- Ensure that isLetter and isAlpha are equivalent. -- --

--   >>> let chars = [(chr 0)..]
--   
--   >>> let letters = map isLetter chars
--   
--   >>> let alphas = map isAlpha chars
--   
--   >>> letters == alphas
--   True
--

isLetter :: Char -> Bool -- | Convert a single digit Char to the corresponding Int. -- This function fails unless its argument satisfies isHexDigit, -- but recognises both upper- and lower-case hexadecimal digits (that is, -- '0'..'9', 'a'..'f', -- 'A'..'F'). -- --

Examples

-- -- Characters '0' through '9' are converted properly to -- 0..9: -- --

--   >>> map digitToInt ['0'..'9']
--   [0,1,2,3,4,5,6,7,8,9]
--

-- -- Both upper- and lower-case 'A' through 'F' are -- converted as well, to 10..15. -- --

--   >>> map digitToInt ['a'..'f']
--   [10,11,12,13,14,15]
--   
--   >>> map digitToInt ['A'..'F']
--   [10,11,12,13,14,15]
--

-- -- Anything else throws an exception: -- --

--   >>> digitToInt 'G'
--   *** Exception: Char.digitToInt: not a digit 'G'
--   
--   >>> digitToInt '♥'
--   *** Exception: Char.digitToInt: not a digit '\9829'
--

digitToInt :: Char -> Int -- | 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 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 -- | 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 Lj. isUpper :: Char -> Bool -- | Selects printable Unicode characters (letters, numbers, marks, -- punctuation, symbols and spaces). isPrint :: Char -> Bool -- | Selects control characters, which are the non-printing characters of -- the Latin-1 subset of Unicode. isControl :: Char -> Bool -- | Selects alphabetic or numeric Unicode characters. -- -- Note that numeric digits outside the ASCII range, as well as numeric -- characters which aren't digits, are selected by this function but not -- by isDigit. Such characters may be part of identifiers but are -- not used by the printer and reader to represent numbers. isAlphaNum :: 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 isLetter. isAlpha :: Char -> Bool -- | Selects ASCII hexadecimal digits, i.e. '0'..'9', -- 'a'..'f', 'A'..'F'. isHexDigit :: Char -> Bool -- | Selects ASCII digits, i.e. '0'..'9'. isDigit :: Char -> Bool -- | Returns True for any Unicode space character, and the control -- characters \t, \n, \r, \f, -- \v. isSpace :: Char -> Bool -- | Selects the first 128 characters of the Unicode character set, -- corresponding to the ASCII character set. isAscii :: Char -> Bool -- | The toEnum method restricted to the type Char. chr :: Int -> Char -- | Convert an Int in the range 0..15 to the -- corresponding single digit Char. This function fails on other -- inputs, and generates lower-case hexadecimal digits. intToDigit :: Int -> Char -- | The fromEnum method restricted to the type Char. ord :: Char -> Int -- | The Maybe type encapsulates an optional value. A value of type -- Maybe a either contains a value of type a -- (represented as Just a), or it is empty (represented -- as Nothing). Using Maybe is a good way to deal with -- errors or exceptional cases without resorting to drastic measures such -- as error. -- -- The Maybe type is also a monad. It is a simple kind of error -- monad, where all errors are represented by Nothing. A richer -- error monad can be built using the Either type. data Maybe a Nothing :: Maybe a Just :: a -> Maybe a -- | The mapMaybe function is a version of map which can -- throw out elements. In particular, the functional argument returns -- something of type Maybe b. If this is Nothing, -- no element is added on to the result list. If it is Just -- b, then b is included in the result list. -- --

Examples

-- -- Using mapMaybe f x is a shortcut for -- catMaybes $ map f x in most cases: -- --

--   >>> import Text.Read ( readMaybe )
--   
--   >>> let readMaybeInt = readMaybe :: String -> Maybe Int
--   
--   >>> mapMaybe readMaybeInt ["1", "Foo", "3"]
--   [1,3]
--   
--   >>> catMaybes $ map readMaybeInt ["1", "Foo", "3"]
--   [1,3]
--

-- -- If we map the Just constructor, the entire list should be -- returned: -- --

--   >>> mapMaybe Just [1,2,3]
--   [1,2,3]
--

mapMaybe :: (a -> Maybe b) -> [a] -> [b] -- | The catMaybes function takes a list of Maybes and -- returns a list of all the Just values. -- --

Examples

-- -- Basic usage: -- --

--   >>> catMaybes [Just 1, Nothing, Just 3]
--   [1,3]
--

-- -- When constructing a list of Maybe values, catMaybes can -- be used to return all of the "success" results (if the list is the -- result of a map, then mapMaybe would be more -- appropriate): -- --

--   >>> import Text.Read ( readMaybe )
--   
--   >>> [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
--   [Just 1,Nothing,Just 3]
--   
--   >>> catMaybes $ [readMaybe x :: Maybe Int | x <- ["1", "Foo", "3"] ]
--   [1,3]
--

catMaybes :: [Maybe a] -> [a] -- | The listToMaybe function returns Nothing on an empty -- list or Just a where a is the first element -- of the list. -- --

Examples

-- -- Basic usage: -- --

--   >>> listToMaybe []
--   Nothing
--

-- --

--   >>> listToMaybe [9]
--   Just 9
--

-- --

--   >>> listToMaybe [1,2,3]
--   Just 1
--

-- -- Composing maybeToList with listToMaybe should be the -- identity on singleton/empty lists: -- --

--   >>> maybeToList $ listToMaybe [5]
--   [5]
--   
--   >>> maybeToList $ listToMaybe []
--   []
--

-- -- But not on lists with more than one element: -- --

--   >>> maybeToList $ listToMaybe [1,2,3]
--   [1]
--

listToMaybe :: [a] -> Maybe a -- | The maybeToList function returns an empty list when given -- Nothing or a singleton list when given Just. -- --

Examples

-- -- Basic usage: -- --

--   >>> maybeToList (Just 7)
--   [7]
--

-- --

--   >>> maybeToList Nothing
--   []
--

-- -- One can use maybeToList to avoid pattern matching when combined -- with a function that (safely) works on lists: -- --

--   >>> import Text.Read ( readMaybe )
--   
--   >>> sum $ maybeToList (readMaybe "3")
--   3
--   
--   >>> sum $ maybeToList (readMaybe "")
--   0
--

maybeToList :: Maybe a -> [a] -- | The fromMaybe function takes a default value and and -- Maybe value. If the Maybe is Nothing, it returns -- the default values; otherwise, it returns the value contained in the -- Maybe. -- --

Examples

-- -- Basic usage: -- --

--   >>> fromMaybe "" (Just "Hello, World!")
--   "Hello, World!"
--

-- --

--   >>> fromMaybe "" Nothing
--   ""
--

-- -- Read an integer from a string using readMaybe. If we fail to -- parse an integer, we want to return 0 by default: -- --

--   >>> import Text.Read ( readMaybe )
--   
--   >>> fromMaybe 0 (readMaybe "5")
--   5
--   
--   >>> fromMaybe 0 (readMaybe "")
--   0
--

fromMaybe :: a -> Maybe a -> a -- | The isNothing function returns True iff its argument is -- Nothing. -- --

Examples

-- -- Basic usage: -- --

--   >>> isNothing (Just 3)
--   False
--

-- --

--   >>> isNothing (Just ())
--   False
--

-- --

--   >>> isNothing Nothing
--   True
--

-- -- Only the outer constructor is taken into consideration: -- --

--   >>> isNothing (Just Nothing)
--   False
--

isNothing :: Maybe a -> Bool -- | The isJust function returns True iff its argument is of -- the form Just _. -- --

Examples

-- -- Basic usage: -- --

--   >>> isJust (Just 3)
--   True
--

-- --

--   >>> isJust (Just ())
--   True
--

-- --

--   >>> isJust Nothing
--   False
--

-- -- Only the outer constructor is taken into consideration: -- --

--   >>> isJust (Just Nothing)
--   True
--

isJust :: Maybe a -> Bool -- | The maybe function takes a default value, a function, and a -- Maybe value. If the Maybe value is Nothing, the -- function returns the default value. Otherwise, it applies the function -- to the value inside the Just and returns the result. -- --

Examples

-- -- Basic usage: -- --

--   >>> maybe False odd (Just 3)
--   True
--

-- --

--   >>> maybe False odd Nothing
--   False
--

-- -- Read an integer from a string using readMaybe. If we succeed, -- return twice the integer; that is, apply (*2) to it. If -- instead we fail to parse an integer, return 0 by default: -- --

--   >>> import Text.Read ( readMaybe )
--   
--   >>> maybe 0 (*2) (readMaybe "5")
--   10
--   
--   >>> maybe 0 (*2) (readMaybe "")
--   0
--

-- -- Apply show to a Maybe Int. If we have Just n, -- we want to show the underlying Int n. But if we have -- Nothing, we return the empty string instead of (for example) -- "Nothing": -- --

--   >>> maybe "" show (Just 5)
--   "5"
--   
--   >>> maybe "" show Nothing
--   ""
--

maybe :: b -> (a -> b) -> Maybe a -> b -- | Representable types of kind *. This class is derivable in GHC -- with the DeriveGeneric flag on. -- -- A Generic instance must satisfy the following laws: -- --

--   from . to ≡ id
--   to . from ≡ id
--

class Generic a where { -- | Generic representation type type family Rep a :: Type -> Type; } -- | Convert from the datatype to its representation from :: Generic a => a -> Rep a x -- | Convert from the representation to the datatype to :: Generic a => Rep a x -> a -- | Representable types of kind * -> * (or kind k -> -- *, when PolyKinds is enabled). This class is derivable -- in GHC with the DeriveGeneric flag on. -- -- A Generic1 instance must satisfy the following laws: -- --

--   from1 . to1 ≡ id
--   to1 . from1 ≡ id
--

class Generic1 (f :: k -> Type) -- | Class for datatypes that represent datatypes class Datatype (d :: k) -- | The name of the datatype (unqualified) datatypeName :: forall k1 t (f :: k1 -> Type) (a :: k1). Datatype d => t d f a -> [Char] -- | The fully-qualified name of the module where the type is declared moduleName :: forall k1 t (f :: k1 -> Type) (a :: k1). Datatype d => t d f a -> [Char] -- | The package name of the module where the type is declared packageName :: forall k1 t (f :: k1 -> Type) (a :: k1). Datatype d => t d f a -> [Char] -- | Marks if the datatype is actually a newtype isNewtype :: forall k1 t (f :: k1 -> Type) (a :: k1). Datatype d => t d f a -> Bool -- | Class for datatypes that represent data constructors class Constructor (c :: k) -- | The name of the constructor conName :: forall k1 t (f :: k1 -> Type) (a :: k1). Constructor c => t c f a -> [Char] -- | The fixity of the constructor conFixity :: forall k1 t (f :: k1 -> Type) (a :: k1). Constructor c => t c f a -> Fixity -- | Marks if this constructor is a record conIsRecord :: forall k1 t (f :: k1 -> Type) (a :: k1). Constructor c => t c f a -> Bool -- | Class for datatypes that represent records class Selector (s :: k) -- | The name of the selector selName :: forall k1 t (f :: k1 -> Type) (a :: k1). Selector s => t s f a -> [Char] -- | The selector's unpackedness annotation (if any) selSourceUnpackedness :: forall k1 t (f :: k1 -> Type) (a :: k1). Selector s => t s f a -> SourceUnpackedness -- | The selector's strictness annotation (if any) selSourceStrictness :: forall k1 t (f :: k1 -> Type) (a :: k1). Selector s => t s f a -> SourceStrictness -- | The strictness that the compiler inferred for the selector selDecidedStrictness :: forall k1 t (f :: k1 -> Type) (a :: k1). Selector s => t s f a -> DecidedStrictness -- | Void: used for datatypes without constructors data V1 (p :: k) -- | Unit: used for constructors without arguments data U1 (p :: k) U1 :: U1 (p :: k) -- | Constants, additional parameters and recursion of kind * newtype K1 i c (p :: k) K1 :: c -> K1 i c (p :: k) [unK1] :: K1 i c (p :: k) -> c -- | Meta-information (constructor names, etc.) newtype M1 i (c :: Meta) (f :: k -> Type) (p :: k) M1 :: f p -> M1 i (c :: Meta) (f :: k -> Type) (p :: k) [unM1] :: M1 i (c :: Meta) (f :: k -> Type) (p :: k) -> f p -- | Sums: encode choice between constructors data ( (f :: k -> Type) :+: (g :: k -> Type) ) (p :: k) L1 :: f p -> (:+:) (f :: k -> Type) (g :: k -> Type) (p :: k) R1 :: g p -> (:+:) (f :: k -> Type) (g :: k -> Type) (p :: k) infixr 5 :+: -- | Products: encode multiple arguments to constructors data ( (f :: k -> Type) :*: (g :: k -> Type) ) (p :: k) (:*:) :: f p -> g p -> (:*:) (f :: k -> Type) (g :: k -> Type) (p :: k) infixr 6 :*: infixr 6 :*: -- | Composition of functors newtype ( (f :: k2 -> Type) :.: (g :: k1 -> k2) ) (p :: k1) Comp1 :: f (g p) -> (:.:) (f :: k2 -> Type) (g :: k1 -> k2) (p :: k1) [unComp1] :: (:.:) (f :: k2 -> Type) (g :: k1 -> k2) (p :: k1) -> f (g p) infixr 7 :.: -- | Type synonym for encoding recursion (of kind Type) type Rec0 = K1 R :: Type -> k -> Type -- | Type synonym for encoding meta-information for datatypes type D1 = M1 D :: Meta -> k -> Type -> k -> Type -- | Type synonym for encoding meta-information for constructors type C1 = M1 C :: Meta -> k -> Type -> k -> Type -- | Type synonym for encoding meta-information for record selectors type S1 = M1 S :: Meta -> k -> Type -> k -> Type -- | Generic representation type type family Rep a :: Type -> Type -- | Constants of unlifted kinds data family URec a (p :: k) -- | Datatype to represent the fixity of a constructor. An infix | -- declaration directly corresponds to an application of Infix. data Fixity Prefix :: Fixity Infix :: Associativity -> Int -> Fixity -- | This variant of Fixity appears at the type level. data FixityI PrefixI :: FixityI InfixI :: Associativity -> Nat -> FixityI -- | Datatype to represent the associativity of a constructor data Associativity LeftAssociative :: Associativity RightAssociative :: Associativity NotAssociative :: Associativity -- | Datatype to represent metadata associated with a datatype -- (MetaData), constructor (MetaCons), or field -- selector (MetaSel). -- --

In MetaData n m p nt, n is the datatype's name, -- m is the module in which the datatype is defined, p -- is the package in which the datatype is defined, and nt is -- 'True if the datatype is a newtype.
In MetaCons n f s, n is the constructor's name, -- f is its fixity, and s is 'True if the -- constructor contains record selectors.
In MetaSel mn su ss ds, if the field uses record syntax, -- then mn is Just the record name. Otherwise, -- mn is Nothing. su and ss are the -- field's unpackedness and strictness annotations, and ds is -- the strictness that GHC infers for the field.

data Meta MetaData :: Symbol -> Symbol -> Symbol -> Bool -> Meta MetaCons :: Symbol -> FixityI -> Bool -> Meta MetaSel :: Maybe Symbol -> SourceUnpackedness -> SourceStrictness -> DecidedStrictness -> Meta -- | A space-efficient representation of a Word8 vector, supporting -- many efficient operations. -- -- A ByteString contains 8-bit bytes, or by using the operations -- from Data.ByteString.Char8 it can be interpreted as containing -- 8-bit characters. data ByteString type LByteString = ByteString -- | Read a single line of user input from stdin. getLine :: IO Text -- | Read all user input on stdin as a single string. getContents :: IO Text -- | The interact function takes a function of type Text -> -- Text 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 :: (Text -> Text) -> IO () -- | Write a string the end of a file. appendFile :: FilePath -> Text -> IO () -- | Write a string to a file. The file is truncated to zero length before -- writing begins. writeFile :: FilePath -> Text -> IO () -- | The readFile function reads a file and returns the contents of -- the file as a string. The entire file is read strictly, as with -- getContents. readFile :: FilePath -> IO Text -- | O(c) Convert a strict Text into a lazy Text. fromStrict :: Text -> Text -- | O(n) Convert a lazy Text into a strict Text. toStrict :: Text -> Text -- | O(n) Joins words using single space characters. unwords :: [Text] -> Text -- | O(n) Joins lines, after appending a terminating newline to -- each. unlines :: [Text] -> Text -- | O(n) Breaks a Text up into a list of Texts at -- newline Chars. The resulting strings do not contain newlines. lines :: Text -> [Text] -- | O(n) Breaks a Text up into a list of words, delimited by -- Chars representing white space. words :: Text -> [Text] -- | Encode text using UTF-8 encoding. encodeUtf8 :: Text -> ByteString -- | Decode a ByteString containing UTF-8 encoded text. -- -- If the input contains any invalid UTF-8 data, the relevant exception -- will be returned, otherwise the decoded text. decodeUtf8' :: ByteString -> Either UnicodeException Text -- | Decode a ByteString containing UTF-8 encoded text that is known -- to be valid. -- -- If the input contains any invalid UTF-8 data, an exception will be -- thrown that cannot be caught in pure code. For more control over the -- handling of invalid data, use decodeUtf8' or -- decodeUtf8With. decodeUtf8 :: ByteString -> Text -- | Decode a ByteString containing UTF-8 encoded text. -- -- NOTE: The replacement character returned by -- OnDecodeError MUST be within the BMP plane; surrogate code -- points will automatically be remapped to the replacement char -- U+FFFD (since 0.11.3.0), whereas code points beyond -- the BMP will throw an error (since 1.2.3.1); For earlier -- versions of text using those unsupported code points would -- result in undefined behavior. decodeUtf8With :: OnDecodeError -> ByteString -> Text -- | A space efficient, packed, unboxed Unicode text type. data Text -- | Replace an invalid input with a valid output. replace :: b -> OnError a b -- | Ignore an invalid input, substituting nothing in the output. ignore :: OnError a b -- | Replace an invalid input byte with the Unicode replacement character -- U+FFFD. lenientDecode :: OnDecodeError -- | Throw a UnicodeException if decoding fails. strictDecode :: OnDecodeError -- | Function type for handling a coding error. It is supplied with two -- inputs: -- --

A String that describes the error.
The input value that caused the error. If the error arose because -- the end of input was reached or could not be identified precisely, -- this value will be Nothing.

-- -- If the handler returns a value wrapped with Just, that value -- will be used in the output as the replacement for the invalid input. -- If it returns Nothing, no value will be used in the output. -- -- Should the handler need to abort processing, it should use -- error or throw an exception (preferably a -- UnicodeException). It may use the description provided to -- construct a more helpful error report. type OnError a b = String -> Maybe a -> Maybe b -- | A handler for a decoding error. type OnDecodeError = OnError Word8 Char -- | An exception type for representing Unicode encoding errors. data UnicodeException type LText = Text -- | Parsing of Strings, producing values. -- -- Derived instances of Read make the following assumptions, which -- derived instances of Show obey: -- --

If the constructor is defined to be an infix operator, then the -- derived Read instance will parse only infix applications of the -- constructor (not the prefix form).
Associativity is not used to reduce the occurrence of parentheses, -- although precedence may be.
If the constructor is defined using record syntax, the derived -- Read will parse only the record-syntax form, and furthermore, -- the fields must be given in the same order as the original -- declaration.
The derived Read instance allows arbitrary Haskell -- whitespace between tokens of the input string. Extra parentheses are -- also allowed.

-- -- For example, given the declarations -- --

--   infixr 5 :^:
--   data Tree a =  Leaf a  |  Tree a :^: Tree a
--

-- -- the derived instance of Read in Haskell 2010 is equivalent to -- --

--   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
--

-- -- Note that right-associativity of :^: is unused. -- -- The derived instance in GHC is equivalent to -- --

--   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
--

-- -- Why do both readsPrec and readPrec exist, and why does -- GHC opt to implement readPrec in derived Read instances -- instead of readsPrec? The reason is that readsPrec is -- based on the ReadS type, and although ReadS is mentioned -- in the Haskell 2010 Report, it is not a very efficient parser data -- structure. -- -- readPrec, on the other hand, is based on a much more efficient -- ReadPrec datatype (a.k.a "new-style parsers"), but its -- definition relies on the use of the RankNTypes language -- extension. Therefore, readPrec (and its cousin, -- readListPrec) are marked as GHC-only. Nevertheless, it is -- recommended to use readPrec instead of readsPrec -- whenever possible for the efficiency improvements it brings. -- -- As mentioned above, derived Read instances in GHC will -- implement readPrec instead of readsPrec. The default -- implementations of readsPrec (and its cousin, readList) -- will simply use readPrec under the hood. If you are writing a -- Read instance by hand, it is recommended to write it like so: -- --

--   instance Read T where
--     readPrec     = ...
--     readListPrec = readListPrecDefault
--

class Read a -- | equivalent to readsPrec with a precedence of 0. reads :: Read a => ReadS a -- | Parse a string using the Read instance. Succeeds if there is -- exactly one valid result. -- --

--   >>> readMaybe ("123" :: Text) :: Maybe Int
--   Just 123
--

-- --

--   >>> readMaybe ("hello" :: Text) :: Maybe Int
--   Nothing
--

readMaybe :: (Read b, StringConv a String) => a -> Maybe b -- | Parse a string using the Read instance. Succeeds if there is -- exactly one valid result. A Left value indicates a parse error. -- --

--   >>> readEither "123" :: Either Text Int
--   Right 123
--

-- --

--   >>> readEither "hello" :: Either Text Int
--   Left "Prelude.read: no parse"
--

readEither :: (Read a, StringConv String e, StringConv e String) => e -> Either e a -- | Haskell defines operations to read and write characters from and to -- files, represented by values of type Handle. Each value of -- this type is a handle: a record used by the Haskell run-time -- system to manage I/O with file system objects. A handle has at -- least the following properties: -- --

whether it manages input or output or both;
whether it is open, closed or -- semi-closed;
whether the object is seekable;
whether buffering is disabled, or enabled on a line or block -- basis;
a buffer (whose length may be zero).

-- -- Most handles will also have a current I/O position indicating where -- the next input or output operation will occur. A handle is -- readable if it manages only input or both input and output; -- likewise, it is writable if it manages only output or both -- input and output. A handle is open 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 Show and Eq 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 == only to itself; no attempt is -- made to compare the internal state of different handles for equality. data Handle -- | Computation getArgs returns a list of the program's command -- line arguments (not including the program name). getArgs :: IO [String] -- | The computation exitSuccess is equivalent to exitWith -- ExitSuccess, It terminates the program successfully. exitSuccess :: IO a -- | The computation exitFailure is equivalent to exitWith -- (ExitFailure exitfail), where -- exitfail is implementation-dependent. exitFailure :: IO a -- | Computation exitWith code throws ExitCode -- code. Normally this terminates the program, returning -- code to the program's caller. -- -- On program termination, the standard Handles stdout and -- stderr are flushed automatically; any other buffered -- Handles need to be flushed manually, otherwise the buffered -- data will be discarded. -- -- A program that fails in any other way is treated as if it had called -- exitFailure. A program that terminates successfully without -- calling exitWith explicitly is treated as if it had called -- exitWith ExitSuccess. -- -- As an ExitCode is not an IOError, exitWith -- bypasses the error handling in the IO monad and cannot be -- intercepted by catch from the Prelude. However it is a -- SomeException, and can be caught using the functions of -- Control.Exception. This means that cleanup computations added -- with bracket (from Control.Exception) are also executed -- properly on exitWith. -- -- Note: in GHC, exitWith should be called from the main program -- thread in order to exit the process. When called from another thread, -- exitWith will throw an ExitException as normal, but -- the exception will not cause the process itself to exit. exitWith :: ExitCode -> IO a -- | withFile name mode act opens a file using -- openFile and passes the resulting handle to the computation -- act. The handle will be closed on exit from withFile, -- whether by normal termination or by raising an exception. If closing -- the handle raises an exception, then this exception will be raised by -- withFile rather than any exception raised by act. withFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r -- | Computation openFile file mode allocates and returns a -- new, open handle to manage the file file. It manages input if -- mode is ReadMode, output if mode is -- WriteMode or AppendMode, and both input and output if -- mode is ReadWriteMode. -- -- If the file does not exist and it is opened for output, it should be -- created as a new file. If mode is WriteMode 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 openFile with mode -- WriteMode unless it is subsequently written to successfully. -- The handle is positioned at the end of the file if mode is -- AppendMode, 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: -- --

isAlreadyInUseError if the file is already open and cannot -- be reopened;
isDoesNotExistError if the file does not exist or (on POSIX -- systems) is a FIFO without a reader and WriteMode was -- requested; or
isPermissionError if the user does not have permission to -- open the file.

-- -- Note: if you will be working with files containing binary data, you'll -- want to be using openBinaryFile. openFile :: FilePath -> IOMode -> IO Handle -- | A handle managing output to the Haskell program's standard error -- channel. stderr :: Handle -- | A handle managing input from the Haskell program's standard input -- channel. stdin :: Handle -- | 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 -- | A handle managing output to the Haskell program's standard output -- channel. stdout :: Handle -- | File and directory names are values of type String, 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 -- | See openFile data IOMode ReadMode :: IOMode WriteMode :: IOMode AppendMode :: IOMode ReadWriteMode :: IOMode -- | Terminate main process with failure die :: Text -> IO a -- | Like forkIOWithUnmask, but the child thread is pinned to the -- given CPU, as with forkOn. forkOnWithUnmask :: Int -> ((forall a. () => IO a -> IO a) -> IO ()) -> IO ThreadId -- | Like forkIO, but the child thread is passed a function that can -- be used to unmask asynchronous exceptions. This function is typically -- used in the following way -- --

--   ... mask_ $ forkIOWithUnmask $ \unmask ->
--                  catch (unmask ...) handler
--

-- -- so that the exception handler in the child thread is established with -- asynchronous exceptions masked, meanwhile the main body of the child -- thread is executed in the unmasked state. -- -- Note that the unmask function passed to the child thread should only -- be used in that thread; the behaviour is undefined if it is invoked in -- a different thread. forkIOWithUnmask :: ((forall a. () => IO a -> IO a) -> IO ()) -> IO ThreadId -- | Like forkIO, but lets you specify on which capability the -- thread should run. Unlike a forkIO thread, a thread created by -- forkOn will stay on the same capability for its entire lifetime -- (forkIO threads can migrate between capabilities according to -- the scheduling policy). forkOn is useful for overriding the -- scheduling policy when you know in advance how best to distribute the -- threads. -- -- The Int argument specifies a capability number (see -- getNumCapabilities). Typically capabilities correspond to -- physical processors, but the exact behaviour is -- implementation-dependent. The value passed to forkOn is -- interpreted modulo the total number of capabilities as returned by -- getNumCapabilities. -- -- GHC note: the number of capabilities is specified by the +RTS -- -N option when the program is started. Capabilities can be fixed -- to actual processor cores with +RTS -qa if the underlying -- operating system supports that, although in practice this is usually -- unnecessary (and may actually degrade performance in some cases - -- experimentation is recommended). forkOn :: Int -> IO () -> IO ThreadId -- | Like forkIO, this sparks off a new thread to run the IO -- computation passed as the first argument, and returns the -- ThreadId of the newly created thread. -- -- However, forkOS creates a bound thread, which is -- necessary if you need to call foreign (non-Haskell) libraries that -- make use of thread-local state, such as OpenGL (see -- Control.Concurrent#boundthreads). -- -- Using forkOS instead of forkIO makes no difference at -- all to the scheduling behaviour of the Haskell runtime system. It is a -- common misconception that you need to use forkOS instead of -- forkIO to avoid blocking all the Haskell threads when making a -- foreign call; this isn't the case. To allow foreign calls to be made -- without blocking all the Haskell threads (with GHC), it is only -- necessary to use the -threaded option when linking your -- program, and to make sure the foreign import is not marked -- unsafe. forkOS :: IO () -> IO ThreadId -- | Creates a new thread to run the IO computation passed as the -- first argument, and returns the ThreadId of the newly created -- thread. -- -- The new thread will be a lightweight, unbound thread. Foreign -- calls made by this thread are not guaranteed to be made by any -- particular OS thread; if you need foreign calls to be made by a -- particular OS thread, then use forkOS instead. -- -- The new thread inherits the masked state of the parent (see -- mask). -- -- The newly created thread has an exception handler that discards the -- exceptions BlockedIndefinitelyOnMVar, -- BlockedIndefinitelyOnSTM, and ThreadKilled, and passes -- all other exceptions to the uncaught exception handler. forkIO :: IO () -> IO ThreadId -- | A ThreadId is an abstract type representing a handle to a -- thread. ThreadId is an instance of Eq, Ord and -- Show, where the Ord instance implements an arbitrary -- total ordering over ThreadIds. The Show instance lets -- you convert an arbitrary-valued ThreadId to string form; -- showing a ThreadId value is occasionally useful when debugging -- or diagnosing the behaviour of a concurrent program. -- -- Note: in GHC, if you have a ThreadId, you essentially -- have a pointer to the thread itself. This means the thread itself -- can't be garbage collected until you drop the ThreadId. This -- misfeature will hopefully be corrected at a later date. data ThreadId -- | Run two IO actions concurrently, and return both results. If -- either action throws an exception at any time, then the other action -- is cancelled, and the exception is re-thrown by -- concurrently. -- --

--   concurrently left right =
--     withAsync left $ \a ->
--     withAsync right $ \b ->
--     waitBoth a b
--

concurrently :: IO a -> IO b -> IO (a, b) -- | Like race, but the result is ignored. race_ :: IO a -> IO b -> IO () -- | Run two IO actions concurrently, and return the first to -- finish. The loser of the race is cancelled. -- --

--   race left right =
--     withAsync left $ \a ->
--     withAsync right $ \b ->
--     waitEither a b
--

race :: IO a -> IO b -> IO (Either a b) -- | Link two Asyncs together, such that if either raises an -- exception, the same exception is re-thrown in the other -- Async, wrapped in ExceptionInLinkedThread. -- -- link2 ignores AsyncCancelled exceptions, so that it's -- possible to cancel either thread without cancelling the other. -- If you want different behaviour, use link2Only. link2 :: Async a -> Async b -> IO () -- | Link the given Async to the current thread, such that if the -- Async raises an exception, that exception will be re-thrown -- in the current thread, wrapped in ExceptionInLinkedThread. -- -- link ignores AsyncCancelled exceptions thrown in the -- other thread, so that it's safe to cancel a thread you're -- linked to. If you want different behaviour, use linkOnly. link :: Async a -> IO () -- | Waits for both Asyncs to finish, but if either of them throws -- an exception before they have both finished, then the exception is -- re-thrown by waitBoth. waitBoth :: Async a -> Async b -> IO (a, b) -- | Like waitEither, but also cancels both Asyncs -- before returning. waitEitherCancel :: Async a -> Async b -> IO (Either a b) -- | Like waitEither, but the result is ignored. waitEither_ :: Async a -> Async b -> IO () -- | Wait for the first of two Asyncs to finish. If the -- Async that finished first raised an exception, then the -- exception is re-thrown by waitEither. waitEither :: Async a -> Async b -> IO (Either a b) -- | Like waitEitherCatch, but also cancels both -- Asyncs before returning. waitEitherCatchCancel :: Async a -> Async b -> IO (Either (Either SomeException a) (Either SomeException b)) -- | Wait for the first of two Asyncs to finish. waitEitherCatch :: Async a -> Async b -> IO (Either (Either SomeException a) (Either SomeException b)) -- | Like waitAny, but also cancels the other asynchronous -- operations as soon as one has completed. waitAnyCancel :: [Async a] -> IO (Async a, a) -- | Wait for any of the supplied Asyncs to complete. If the first -- to complete throws an exception, then that exception is re-thrown by -- waitAny. -- -- If multiple Asyncs complete or have completed, then the value -- returned corresponds to the first completed Async in the list. waitAny :: [Async a] -> IO (Async a, a) -- | Like waitAnyCatch, but also cancels the other asynchronous -- operations as soon as one has completed. waitAnyCatchCancel :: [Async a] -> IO (Async a, Either SomeException a) -- | Wait for any of the supplied asynchronous operations to complete. The -- value returned is a pair of the Async that completed, and the -- result that would be returned by wait on that Async. -- -- If multiple Asyncs complete or have completed, then the value -- returned corresponds to the first completed Async in the list. waitAnyCatch :: [Async a] -> IO (Async a, Either SomeException a) -- | Cancel an asynchronous action by throwing the supplied exception to -- it. -- --

--   cancelWith a x = throwTo (asyncThreadId a) x
--

-- -- The notes about the synchronous nature of cancel also apply to -- cancelWith. cancelWith :: Exception e => Async a -> e -> IO () -- | Cancel an asynchronous action by throwing the AsyncCancelled -- exception to it, and waiting for the Async thread to quit. Has -- no effect if the Async has already completed. -- --

--   cancel a = throwTo (asyncThreadId a) AsyncCancelled <* waitCatch a
--

-- -- Note that cancel will not terminate until the thread the -- Async refers to has terminated. This means that cancel -- will block for as long said thread blocks when receiving an -- asynchronous exception. -- -- For example, it could block if: -- --

It's executing a foreign call, and thus cannot receive the -- asynchronous exception;
It's executing some cleanup handler after having received the -- exception, and the handler is blocking.

cancel :: Async a -> IO () -- | Check whether an Async has completed yet. If it has not -- completed yet, then the result is Nothing, otherwise the -- result is Just e where e is Left x if the -- Async raised an exception x, or Right a if -- it returned a value a. -- --

--   poll = atomically . pollSTM
--

poll :: Async a -> IO (Maybe (Either SomeException a)) -- | Wait for an asynchronous action to complete, and return either -- Left e if the action raised an exception e, or -- Right a if it returned a value a. -- --

--   waitCatch = atomically . waitCatchSTM
--

waitCatch :: Async a -> IO (Either SomeException a) -- | Wait for an asynchronous action to complete, and return its value. If -- the asynchronous action threw an exception, then the exception is -- re-thrown by wait. -- --

--   wait = atomically . waitSTM
--

wait :: Async a -> IO a -- | Like withAsync but uses forkOn internally. withAsyncOn :: Int -> IO a -> (Async a -> IO b) -> IO b -- | Like withAsync but uses forkOS internally. withAsyncBound :: IO a -> (Async a -> IO b) -> IO b -- | Spawn an asynchronous action in a separate thread, and pass its -- Async handle to the supplied function. When the function -- returns or throws an exception, uninterruptibleCancel is called -- on the Async. -- --

--   withAsync action inner = mask $ \restore -> do
--     a <- async (restore action)
--     restore (inner a) `finally` uninterruptibleCancel a
--

-- -- This is a useful variant of async that ensures an -- Async is never left running unintentionally. -- -- Note: a reference to the child thread is kept alive until the call to -- withAsync returns, so nesting many withAsync calls -- requires linear memory. withAsync :: IO a -> (Async a -> IO b) -> IO b -- | Like async but using forkOn internally. asyncOn :: Int -> IO a -> IO (Async a) -- | Like async but using forkOS internally. asyncBound :: IO a -> IO (Async a) -- | Spawn an asynchronous action in a separate thread. -- -- Like for forkIO, the action may be left running unintentinally -- (see module-level documentation for details). -- -- Use withAsync style functions wherever you can instead! async :: IO a -> IO (Async a) -- | An asynchronous action spawned by async or withAsync. -- Asynchronous actions are executed in a separate thread, and operations -- are provided for waiting for asynchronous actions to complete and -- obtaining their results (see e.g. wait). data Async a -- | A value of type Concurrently a is an IO operation -- that can be composed with other Concurrently values, using -- the Applicative and Alternative instances. -- -- Calling runConcurrently on a value of type Concurrently -- a will execute the IO operations it contains -- concurrently, before delivering the result of type a. -- -- For example -- --

--   (page1, page2, page3)
--       <- runConcurrently $ (,,)
--       <$> Concurrently (getURL "url1")
--       <*> Concurrently (getURL "url2")
--       <*> Concurrently (getURL "url3")
--

newtype Concurrently a Concurrently :: IO a -> Concurrently a [runConcurrently] :: Concurrently a -> IO a -- | Returns an STM action that can be used to wait until data can be -- written to a file descriptor. The second returned value is an IO -- action that can be used to deregister interest in the file descriptor. threadWaitWriteSTM :: Fd -> IO (STM (), IO ()) -- | Returns an STM action that can be used to wait for data to read from a -- file descriptor. The second returned value is an IO action that can be -- used to deregister interest in the file descriptor. threadWaitReadSTM :: Fd -> IO (STM (), IO ()) -- | Block the current thread until data can be written to the given file -- descriptor (GHC only). -- -- This will throw an IOError if the file descriptor was closed -- while this thread was blocked. To safely close a file descriptor that -- has been used with threadWaitWrite, use closeFdWith. threadWaitWrite :: Fd -> IO () -- | Block the current thread until data is available to read on the given -- file descriptor (GHC only). -- -- This will throw an IOError if the file descriptor was closed -- while this thread was blocked. To safely close a file descriptor that -- has been used with threadWaitRead, use closeFdWith. threadWaitRead :: Fd -> IO () -- | Run the IO computation passed as the first argument. If the -- calling thread is bound, an unbound thread is created -- temporarily using forkIO. runInBoundThread doesn't -- finish until the IO computation finishes. -- -- Use this function only in the rare case that you have actually -- observed a performance loss due to the use of bound threads. A program -- that doesn't need its main thread to be bound and makes heavy -- use of concurrency (e.g. a web server), might want to wrap its -- main action in runInUnboundThread. -- -- Note that exceptions which are thrown to the current thread are thrown -- in turn to the thread that is executing the given computation. This -- ensures there's always a way of killing the forked thread. runInUnboundThread :: IO a -> IO a -- | Run the IO computation passed as the first argument. If the -- calling thread is not bound, a bound thread is created -- temporarily. runInBoundThread doesn't finish until the -- IO computation finishes. -- -- You can wrap a series of foreign function calls that rely on -- thread-local state with runInBoundThread so that you can use -- them without knowing whether the current thread is bound. runInBoundThread :: IO a -> IO a -- | Returns True if the calling thread is bound, that is, if -- it is safe to use foreign libraries that rely on thread-local state -- from the calling thread. isCurrentThreadBound :: IO Bool -- | Like forkIOWithUnmask, but the child thread is a bound thread, -- as with forkOS. forkOSWithUnmask :: ((forall a. () => IO a -> IO a) -> IO ()) -> IO ThreadId -- | Fork a thread and call the supplied function when the thread is about -- to terminate, with an exception or a returned value. The function is -- called with asynchronous exceptions masked. -- --

--   forkFinally action and_then =
--     mask $ \restore ->
--       forkIO $ try (restore action) >>= and_then
--

-- -- This function is useful for informing the parent when a child -- terminates, for example. forkFinally :: IO a -> (Either SomeException a -> IO ()) -> IO ThreadId -- | True if bound threads are supported. If -- rtsSupportsBoundThreads is False, -- isCurrentThreadBound will always return False and both -- forkOS and runInBoundThread will fail. rtsSupportsBoundThreads :: Bool -- | Write an entire list of items to a Chan. writeList2Chan :: Chan a -> [a] -> IO () -- | Return a lazy list representing the contents of the supplied -- Chan, much like hGetContents. getChanContents :: Chan a -> IO [a] -- | Duplicate a Chan: the duplicate channel begins empty, but data -- written to either channel from then on will be available from both. -- Hence this creates a kind of broadcast channel, where data written by -- anyone is seen by everyone else. -- -- (Note that a duplicated channel is not equal to its original. So: -- fmap (c /=) $ dupChan c returns True for all -- c.) dupChan :: Chan a -> IO (Chan a) -- | Read the next value from the Chan. Blocks when the channel is -- empty. Since the read end of a channel is an MVar, this -- operation inherits fairness guarantees of MVars (e.g. threads -- blocked in this operation are woken up in FIFO order). -- -- Throws BlockedIndefinitelyOnMVar when the channel is empty and -- no other thread holds a reference to the channel. readChan :: Chan a -> IO a -- | Write a value to a Chan. writeChan :: Chan a -> a -> IO () -- | Build and returns a new instance of Chan. newChan :: IO (Chan a) -- | Chan is an abstract type representing an unbounded FIFO -- channel. data Chan a -- | Signal that a unit of the QSem is available signalQSem :: QSem -> IO () -- | Wait for a unit to become available waitQSem :: QSem -> IO () -- | Build a new QSem with a supplied initial quantity. The initial -- quantity must be at least 0. newQSem :: Int -> IO QSem -- | QSem is a quantity semaphore in which the resource is acquired -- and released in units of one. It provides guaranteed FIFO ordering for -- satisfying blocked waitQSem calls. -- -- The pattern -- --

--   bracket_ waitQSem signalQSem (...)
--

-- -- is safe; it never loses a unit of the resource. data QSem -- | Signal that a given quantity is now available from the QSemN. signalQSemN :: QSemN -> Int -> IO () -- | Wait for the specified quantity to become available waitQSemN :: QSemN -> Int -> IO () -- | Build a new QSemN with a supplied initial quantity. The initial -- quantity must be at least 0. newQSemN :: Int -> IO QSemN -- | QSemN is a quantity semaphore in which the resource is acquired -- and released in units of one. It provides guaranteed FIFO ordering for -- satisfying blocked waitQSemN calls. -- -- The pattern -- --

--   bracket_ (waitQSemN n) (signalQSemN n) (...)
--

-- -- is safe; it never loses any of the resource. data QSemN -- | Suspends the current thread for a given number of microseconds (GHC -- only). -- -- There is no guarantee that the thread will be rescheduled promptly -- when the delay has expired, but the thread will never continue to run -- earlier than specified. threadDelay :: Int -> IO () -- | Make a Weak pointer to an MVar, using the second -- argument as a finalizer to run when MVar is garbage-collected mkWeakMVar :: MVar a -> IO () -> IO (Weak (MVar a)) addMVarFinalizer :: MVar a -> IO () -> IO () -- | Like modifyMVar, but the IO action in the second -- argument is executed with asynchronous exceptions masked. modifyMVarMasked :: MVar a -> (a -> IO (a, b)) -> IO b -- | Like modifyMVar_, but the IO action in the second -- argument is executed with asynchronous exceptions masked. modifyMVarMasked_ :: MVar a -> (a -> IO a) -> IO () -- | A slight variation on modifyMVar_ that allows a value to be -- returned (b) in addition to the modified value of the -- MVar. modifyMVar :: MVar a -> (a -> IO (a, b)) -> IO b -- | An exception-safe wrapper for modifying the contents of an -- MVar. Like withMVar, modifyMVar will replace the -- original contents of the MVar if an exception is raised during -- the operation. This function is only atomic if there are no other -- producers for this MVar. modifyMVar_ :: MVar a -> (a -> IO a) -> IO () -- | Like withMVar, but the IO action in the second -- argument is executed with asynchronous exceptions masked. withMVarMasked :: MVar a -> (a -> IO b) -> IO b -- | withMVar is an exception-safe wrapper for operating on the -- contents of an MVar. This operation is exception-safe: it will -- replace the original contents of the MVar if an exception is -- raised (see Control.Exception). However, it is only atomic if -- there are no other producers for this MVar. withMVar :: MVar a -> (a -> IO b) -> IO b -- | Take a value from an MVar, put a new value into the MVar -- and return the value taken. This function is atomic only if there are -- no other producers for this MVar. swapMVar :: MVar a -> a -> IO a -- | Make a weak pointer to a ThreadId. It can be important to do -- this if you want to hold a reference to a ThreadId while still -- allowing the thread to receive the BlockedIndefinitely family -- of exceptions (e.g. BlockedIndefinitelyOnMVar). Holding a -- normal ThreadId reference will prevent the delivery of -- BlockedIndefinitely exceptions because the reference could be -- used as the target of throwTo at any time, which would unblock -- the thread. -- -- Holding a Weak ThreadId, on the other hand, will not prevent -- the thread from receiving BlockedIndefinitely exceptions. It -- is still possible to throw an exception to a Weak ThreadId, -- but the caller must use deRefWeak first to determine whether -- the thread still exists. mkWeakThreadId :: ThreadId -> IO (Weak ThreadId) -- | Returns the number of the capability on which the thread is currently -- running, and a boolean indicating whether the thread is locked to that -- capability or not. A thread is locked to a capability if it was -- created with forkOn. threadCapability :: ThreadId -> IO (Int, Bool) -- | The yield action allows (forces, in a co-operative multitasking -- implementation) a context-switch to any other currently runnable -- threads (if any), and is occasionally useful when implementing -- concurrency abstractions. yield :: IO () -- | Returns the ThreadId of the calling thread (GHC only). myThreadId :: IO ThreadId -- | killThread raises the ThreadKilled exception in the -- given thread (GHC only). -- --

--   killThread tid = throwTo tid ThreadKilled
--

killThread :: ThreadId -> IO () -- | Set the number of Haskell threads that can run truly simultaneously -- (on separate physical processors) at any given time. The number passed -- to forkOn is interpreted modulo this value. The initial value -- is given by the +RTS -N runtime flag. -- -- This is also the number of threads that will participate in parallel -- garbage collection. It is strongly recommended that the number of -- capabilities is not set larger than the number of physical processor -- cores, and it may often be beneficial to leave one or more cores free -- to avoid contention with other processes in the machine. setNumCapabilities :: Int -> IO () -- | Returns the number of Haskell threads that can run truly -- simultaneously (on separate physical processors) at any given time. To -- change this value, use setNumCapabilities. getNumCapabilities :: IO Int -- | Check whether a given MVar is empty. -- -- Notice that the boolean value returned is just a snapshot of the state -- of the MVar. By the time you get to react on its result, the MVar may -- have been filled (or emptied) - so be extremely careful when using -- this operation. Use tryTakeMVar instead if possible. isEmptyMVar :: MVar a -> IO Bool -- | A non-blocking version of readMVar. The tryReadMVar -- function returns immediately, with Nothing if the MVar -- was empty, or Just a if the MVar was full with -- contents a. tryReadMVar :: MVar a -> IO (Maybe a) -- | A non-blocking version of putMVar. The tryPutMVar -- function attempts to put the value a into the MVar, -- returning True if it was successful, or False otherwise. tryPutMVar :: MVar a -> a -> IO Bool -- | A non-blocking version of takeMVar. The tryTakeMVar -- function returns immediately, with Nothing if the MVar -- was empty, or Just a if the MVar was full with -- contents a. After tryTakeMVar, the MVar is left -- empty. tryTakeMVar :: MVar a -> IO (Maybe a) -- | Put a value into an MVar. If the MVar is currently full, -- putMVar will wait until it becomes empty. -- -- There are two further important properties of putMVar: -- --

putMVar is single-wakeup. That is, if there are multiple -- threads blocked in putMVar, and the MVar becomes empty, -- only one thread will be woken up. The runtime guarantees that the -- woken thread completes its putMVar operation.
When multiple threads are blocked on an MVar, they are -- woken up in FIFO order. This is useful for providing fairness -- properties of abstractions built using MVars.

putMVar :: MVar a -> a -> IO () -- | Atomically read the contents of an MVar. If the MVar is -- currently empty, readMVar will wait until it is full. -- readMVar is guaranteed to receive the next putMVar. -- -- readMVar is multiple-wakeup, so when multiple readers are -- blocked on an MVar, all of them are woken up at the same time. -- -- Compatibility note: Prior to base 4.7, readMVar was a -- combination of takeMVar and putMVar. This mean that in -- the presence of other threads attempting to putMVar, -- readMVar could block. Furthermore, readMVar would not -- receive the next putMVar if there was already a pending thread -- blocked on takeMVar. The old behavior can be recovered by -- implementing 'readMVar as follows: -- --

--   readMVar :: MVar a -> IO a
--   readMVar m =
--     mask_ $ do
--       a <- takeMVar m
--       putMVar m a
--       return a
--

readMVar :: MVar a -> IO a -- | Return the contents of the MVar. If the MVar is -- currently empty, takeMVar will wait until it is full. After a -- takeMVar, the MVar is left empty. -- -- There are two further important properties of takeMVar: -- --

takeMVar is single-wakeup. That is, if there are multiple -- threads blocked in takeMVar, and the MVar becomes full, -- only one thread will be woken up. The runtime guarantees that the -- woken thread completes its takeMVar operation.
When multiple threads are blocked on an MVar, they are -- woken up in FIFO order. This is useful for providing fairness -- properties of abstractions built using MVars.

takeMVar :: MVar a -> IO a -- | Create an MVar which contains the supplied value. newMVar :: a -> IO (MVar a) -- | Create an MVar which is initially empty. newEmptyMVar :: IO (MVar a) -- | An MVar (pronounced "em-var") is a synchronising variable, used -- for communication between concurrent threads. It can be thought of as -- a box, which may be empty or full. data MVar a -- | A stable pointer 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 StablePtr a is a stable pointer to a Haskell -- expression of type a. data StablePtr a -- | An unsigned integral type that can be losslessly converted to and from -- Ptr. This type is also compatible with the C99 type -- uintptr_t, and can be marshalled to and from that type -- safely. data WordPtr -- | A signed integral type that can be losslessly converted to and from -- Ptr. This type is also compatible with the C99 type -- intptr_t, and can be marshalled to and from that type safely. data IntPtr -- | 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 Ptr -- a, for some a which is an instance of class -- Storable. The type argument to Ptr 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 Storable facilitates this manipulation -- on all types for which it is instantiated, which are the standard -- basic types of Haskell, the fixed size Int types -- (Int8, Int16, Int32, Int64), the fixed -- size Word types (Word8, Word16, Word32, -- Word64), StablePtr, all types from -- Foreign.C.Types, as well as Ptr. class Storable a module Protolude.Unsafe unsafeHead :: HasCallStack => [a] -> a unsafeTail :: HasCallStack => [a] -> [a] unsafeInit :: HasCallStack => [a] -> [a] unsafeLast :: HasCallStack => [a] -> a unsafeFromJust :: HasCallStack => Maybe a -> a unsafeIndex :: HasCallStack => [a] -> Int -> a unsafeThrow :: Exception e => e -> a unsafeRead :: (HasCallStack, Read a) => [Char] -> a

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Generic NFData deriving

Compatibility with previous deepseq versions

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Compatibility with previous `deepseq` versions