-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A Haskell prelude optimized for safety
--
-- Please see README.md
@package safe-prelude
@version 0.1.0.0
module SafePrelude
-- | 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
data Ordering :: *
LT :: Ordering
EQ :: Ordering
GT :: Ordering
data Bool :: *
False :: Bool
True :: Bool
-- | The character type Char is an enumeration whose values
-- represent Unicode (or equivalently ISO/IEC 10646) 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 :: *
-- | 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 :: * -> *
-- | 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
-- | 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 :: *
-- | A space efficient, packed, unboxed Unicode text type.
data Text :: *
-- | A Map from keys k to values a.
data Map k a :: * -> * -> *
-- | A map from keys to values. A map cannot contain duplicate keys; each
-- key can map to at most one value.
data HashMap k v :: * -> * -> *
-- | A map of integers to values a.
data IntMap a :: * -> *
-- | A set of values a.
data Set a :: * -> *
-- | A set of values. A set cannot contain duplicate values.
data HashSet a :: * -> *
-- | A set of integers.
data IntSet :: *
-- | General-purpose finite sequences.
data Seq a :: * -> *
-- | Identity functor and monad. (a non-strict monad)
newtype Identity a :: * -> *
Identity :: a -> Identity a
[runIdentity] :: Identity a -> a
-- | 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] :: SomeException
-- | Superclass for asynchronous exceptions.
data SomeAsyncException :: *
[SomeAsyncException] :: SomeAsyncException
-- | A String is a list of characters. String constants in Haskell
-- are values of type String.
type String = [Char]
-- | 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
-- | 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 :: *
-- | 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 :: *
-- | Invariant: Jn# and Jp# are used iff value doesn't fit in
-- S#
--
-- Useful properties resulting from the invariants:
--
--
data Integer :: *
-- | 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
-- | Single-precision floating point numbers. It is desirable that this
-- type be at least equal in range and precision to the IEEE
-- single-precision type.
data Float :: *
-- | Double-precision floating point numbers. It is desirable that this
-- type be at least equal in range and precision to the IEEE
-- double-precision type.
data Double :: *
-- | A concrete, poly-kinded proxy type
data Proxy k (t :: k) :: forall k. k -> *
Proxy :: Proxy k
-- | 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.
--
-- Minimal complete definition: either compare or <=.
-- Using compare can be more efficient for complex types.
class Eq a => Ord a
compare :: a -> a -> Ordering
(<) :: a -> a -> Bool
(<=) :: a -> a -> Bool
(>) :: a -> a -> Bool
(>=) :: a -> a -> Bool
max :: a -> a -> a
min :: a -> a -> 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.
--
-- Minimal complete definition: either == or /=.
class Eq a
(==) :: a -> a -> Bool
(/=) :: a -> a -> Bool
-- | 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 :: a
maxBound :: a
-- | 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:
--
--
--
-- That is, readsPrec parses the string produced by
-- showsPrec, and delivers the value that showsPrec started
-- with.
showsPrec :: Int -> a -> ShowS
-- | A specialised variant of showsPrec, using precedence context
-- zero, and returning an ordinary String.
show :: 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 :: [a] -> ShowS
-- | 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
--
class Read a
-- | attempts to parse a value from the front of the string, returning a
-- list of (parsed value, remaining string) pairs. If there is no
-- successful parse, the returned list is empty.
--
-- Derived instances of Read and Show satisfy the
-- following:
--
--
--
-- That is, readsPrec parses the string produced by
-- showsPrec, and delivers the value that showsPrec started
-- with.
readsPrec :: Int -> ReadS a
-- | The method readList is provided to allow the programmer to give
-- a specialised way of parsing lists of values. For example, this is
-- used by the predefined Read instance of the Char type,
-- where values of type String should be are expected to use
-- double quotes, rather than square brackets.
readList :: ReadS [a]
-- | Proposed replacement for readsPrec using new-style parsers (GHC
-- only).
readPrec :: ReadPrec a
-- | Proposed replacement for readList using new-style parsers (GHC
-- only). The default definition uses readList. Instances that
-- define readPrec should also define readListPrec as
-- readListPrecDefault.
readListPrec :: ReadPrec [a]
-- | The Functor class is used for types that can be mapped over.
-- Instances of Functor should satisfy the following laws:
--
--
-- fmap id == id
-- fmap (f . g) == fmap f . fmap g
--
--
-- The instances of Functor for lists, Maybe and IO
-- satisfy these laws.
class Functor (f :: * -> *)
fmap :: (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.
(<$) :: a -> f b -> f a
-- | A functor with application, providing operations to
--
--
-- - embed pure expressions (pure), and
-- - sequence computations and combine their results
-- (<*>).
--
--
-- A minimal complete definition must include implementations of these
-- functions satisfying the following laws:
--
--
--
-- The other methods have the following default definitions, which may be
-- overridden with equivalent specialized implementations:
--
--
--
-- As a consequence of these laws, the Functor instance for
-- f will satisfy
--
--
--
-- If f is also a Monad, it should satisfy
--
--
--
-- (which implies that pure and <*> satisfy the
-- applicative functor laws).
class Functor f => Applicative (f :: * -> *)
-- | Lift a value.
pure :: a -> f a
-- | Sequential application.
(<*>) :: f (a -> b) -> f a -> f b
-- | Sequence actions, discarding the value of the first argument.
(*>) :: f a -> f b -> f b
-- | Sequence actions, discarding the value of the second argument.
(<*) :: f a -> f b -> f a
-- | A monoid on applicative functors.
--
-- If defined, some and many should be the least solutions
-- of the equations:
--
--
class Applicative f => Alternative (f :: * -> *)
-- | The identity of <|>
empty :: f a
-- | An associative binary operation
(<|>) :: f a -> f a -> f a
-- | One or more.
some :: f a -> f [a]
-- | Zero or more.
many :: f a -> f [a]
-- | 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 laws:
--
--
--
-- Furthermore, the Monad and Applicative operations should
-- relate as follows:
--
--
--
-- The above laws imply:
--
--
--
-- 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 :: * -> *)
-- | Sequentially compose two actions, passing any value produced by the
-- first as an argument to the second.
(>>=) :: m a -> (a -> m b) -> m b
-- | Sequentially compose two actions, discarding any value produced by the
-- first, like sequencing operators (such as the semicolon) in imperative
-- languages.
(>>) :: m a -> m b -> m b
-- | Inject a value into the monadic type.
return :: a -> m a
-- | Fail with a message. This operation is not part of the mathematical
-- definition of a monad, but is invoked on pattern-match failure in a
-- do expression.
--
-- As part of the MonadFail proposal (MFP), this function is moved to its
-- own class MonadFail (see Control.Monad.Fail for more
-- details). The definition here will be removed in a future release.
fail :: String -> 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:
--
--
class Monad m => MonadIO (m :: * -> *)
-- | Lift a computation from the IO monad.
liftIO :: IO a -> m a
-- | The class of monad transformers. Instances should satisfy the
-- following laws, which state that lift is a monad
-- transformation:
--
--
class MonadTrans (t :: (* -> *) -> * -> *)
-- | Lift a computation from the argument monad to the constructed monad.
lift :: Monad m => m a -> t 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 :: * -> *) | m -> r
-- | Retrieves the monad environment.
ask :: m r
-- | Executes a computation in a modified environment.
local :: (r -> r) -> m a -> m a
-- | Retrieves a function of the current environment.
reader :: (r -> a) -> m a
-- | A class for monads in which exceptions may be thrown.
--
-- Instances should obey the following law:
--
--
-- throwM e >> x = throwM e
--
--
-- In other words, throwing an exception short-circuits the rest of the
-- monadic computation.
class Monad m => MonadThrow (m :: * -> *)
-- | 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, Typeable)
--
-- 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
-- deriving Typeable
--
-- 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
-- deriving Typeable
--
-- 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 (Typeable, 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 :: e -> SomeException
fromException :: SomeException -> Maybe e
-- | Render this exception value in a human-friendly manner.
--
-- Default implementation: show.
displayException :: e -> String
-- | A class for monads which allow exceptions to be caught, in particular
-- exceptions which were thrown by throwM.
--
-- Instances should obey the following law:
--
--
-- catch (throwM e) f = f e
--
--
-- Note that the ability to catch an exception does not guarantee
-- that we can deal with all possible exit points from a computation.
-- Some monads, such as continuation-based stacks, allow for more than
-- just a success/failure strategy, and therefore catch
-- cannot be used by those monads to properly implement a function
-- such as finally. For more information, see MonadMask.
class MonadThrow m => MonadCatch (m :: * -> *)
-- | A class for monads which provide for the ability to account for all
-- possible exit points from a computation, and to mask asynchronous
-- exceptions. Continuation-based monads, and stacks such as ErrorT e
-- IO which provide for multiple failure modes, are invalid
-- instances of this class.
--
-- Note that this package does provide a MonadMask
-- instance for CatchT. This instance is only valid if
-- the base monad provides no ability to provide multiple exit. For
-- example, IO or Either would be invalid base monads,
-- but Reader or State would be acceptable.
--
-- Instances should ensure that, in the following code:
--
--
-- f `finally` g
--
--
-- The action g is called regardless of what occurs within
-- f, including async exceptions.
class MonadCatch m => MonadMask (m :: * -> *)
-- | 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
--
--
-- 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 :: * -> *)
-- | Combine the elements of a structure using a monoid.
fold :: Monoid m => t m -> m
-- | Map each element of the structure to a monoid, and combine the
-- results.
foldMap :: 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)...)
--
--
-- 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 :: (a -> b -> b) -> b -> t a -> b
-- | Right-associative fold of a structure, but with strict application of
-- the operator.
foldr' :: (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
--
--
-- 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
-- O(n) 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 :: (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' :: (b -> a -> b) -> b -> t a -> b
-- | List of elements of a structure, from left to right.
toList :: 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 :: 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 :: t a -> Int
-- | Does the element occur in the structure?
elem :: Eq a => a -> t a -> Bool
-- | List of elements of a structure, from left to right.
toList :: Foldable t => forall a. 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 => forall a. 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 => forall a. t a -> Int
-- | Does the element occur in the structure?
elem :: Foldable t => forall a. Eq a => a -> t a -> Bool
-- | Functors representing data structures that can be traversed from left
-- to right.
--
-- A definition of traverse must satisfy the following laws:
--
--
--
-- A definition of sequenceA must satisfy the following laws:
--
--
--
-- where an applicative transformation is a function
--
--
-- t :: (Applicative f, Applicative g) => f a -> g a
--
--
-- preserving the Applicative operations, i.e.
--
--
--
-- and the identity functor Identity and composition of functors
-- Compose are defined as
--
--
-- newtype Identity a = Identity a
--
-- instance Functor Identity where
-- fmap f (Identity x) = Identity (f x)
--
-- instance Applicative Identity where
-- pure x = Identity x
-- Identity f <*> Identity x = Identity (f x)
--
-- newtype Compose f g a = Compose (f (g a))
--
-- instance (Functor f, Functor g) => Functor (Compose f g) where
-- fmap f (Compose x) = Compose (fmap (fmap f) x)
--
-- instance (Applicative f, Applicative g) => Applicative (Compose f g) where
-- pure x = Compose (pure (pure x))
-- Compose f <*> Compose x = Compose ((<*>) <$> f <*> x)
--
--
-- (The naturality law is implied by parametricity.)
--
-- Instances are similar to Functor, e.g. given a data type
--
--
-- data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)
--
--
-- a suitable instance would be
--
--
-- instance Traversable Tree where
-- traverse f Empty = pure Empty
-- traverse f (Leaf x) = Leaf <$> f x
-- traverse f (Node l k r) = Node <$> traverse f l <*> f k <*> traverse f r
--
--
-- This is suitable even for abstract types, as the laws for
-- <*> imply a form of associativity.
--
-- The superclass instances should satisfy the following:
--
--
-- - In the Functor instance, fmap should be equivalent
-- to traversal with the identity applicative functor
-- (fmapDefault).
-- - In the Foldable instance, foldMap should be
-- equivalent to traversal with a constant applicative functor
-- (foldMapDefault).
--
class (Functor t, Foldable t) => Traversable (t :: * -> *)
-- | Map each element of a structure to an action, evaluate these actions
-- from left to right, and collect the results. For a version that
-- ignores the results see traverse_.
traverse :: Applicative f => (a -> f b) -> t a -> f (t b)
-- | Evaluate each action in the structure from left to right, and and
-- collect the results. For a version that ignores the results see
-- sequenceA_.
sequenceA :: Applicative f => t (f a) -> f (t a)
-- | The class Typeable allows a concrete representation of a type
-- to be calculated.
class Typeable k (a :: k)
-- | Class for string-like datastructures; used by the overloaded string
-- extension (-XOverloadedStrings in GHC).
class IsString a
fromString :: String -> a
-- | The class of types that can be converted to a hash value.
--
-- Minimal implementation: hashWithSalt.
class 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 :: 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 :: a -> Int
-- | The class of semigroups (types with an associative binary operation).
class Semigroup a
-- | An associative operation.
--
--
-- (a <> b) <> c = a <> (b <> c)
--
--
-- If a is also a Monoid we further require
--
--
-- (<>) = mappend
--
(<>) :: a -> a -> a
-- | Reduce a non-empty list with <>
--
-- The default definition should be sufficient, but this can be
-- overridden for efficiency.
sconcat :: 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 O(1) by picking
-- stimes = stimesIdempotent or stimes =
-- stimesIdempotentMonoid respectively.
stimes :: Integral b => b -> a -> a
-- | The class of monoids (types with an associative binary operation that
-- has an identity). Instances should satisfy the following laws:
--
--
--
-- The method names refer to the monoid of lists under concatenation, but
-- there are many other instances.
--
-- Some types can be viewed as a monoid in more than one way, e.g. both
-- addition and multiplication on numbers. In such cases we often define
-- newtypes and make those instances of Monoid, e.g.
-- Sum and Product.
class Monoid a
-- | Identity of mappend
mempty :: a
-- | An associative operation
mappend :: a -> a -> a
-- | Fold a list using the monoid. For most types, the default definition
-- for mconcat will be used, but the function is included in the
-- class definition so that an optimized version can be provided for
-- specific types.
mconcat :: [a] -> a
-- | Basic numeric class.
class Num a
(+) :: a -> a -> a
(-) :: a -> a -> a
(*) :: a -> a -> a
-- | Unary negation.
negate :: a -> a
-- | Absolute value.
abs :: 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 :: 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 :: Integer -> a
class (Num a, Ord a) => Real a
-- | the rational equivalent of its real argument with full precision
toRational :: a -> Rational
-- | Integral numbers, supporting integer division.
class (Real a, Enum a) => Integral a
-- | integer division truncated toward zero
quot :: a -> a -> a
-- | integer remainder, satisfying
--
--
-- (x `quot` y)*y + (x `rem` y) == x
--
rem :: a -> a -> a
-- | integer division truncated toward negative infinity
div :: a -> a -> a
-- | integer modulus, satisfying
--
--
-- (x `div` y)*y + (x `mod` y) == x
--
mod :: a -> a -> a
-- | simultaneous quot and rem
quotRem :: a -> a -> (a, a)
-- | simultaneous div and mod
divMod :: a -> a -> (a, a)
-- | conversion to Integer
toInteger :: a -> Integer
-- | Fractional numbers, supporting real division.
class Num a => Fractional a
-- | fractional division
(/) :: a -> a -> a
-- | reciprocal fraction
recip :: 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 :: Rational -> a
-- | Trigonometric and hyperbolic functions and related functions.
class Fractional a => Floating a
pi :: a
exp :: a -> a
log :: a -> a
sqrt :: a -> a
(**) :: a -> a -> a
logBase :: a -> a -> a
sin :: a -> a
cos :: a -> a
tan :: a -> a
asin :: a -> a
acos :: a -> a
atan :: a -> a
sinh :: a -> a
cosh :: a -> a
tanh :: a -> a
asinh :: a -> a
acosh :: a -> a
atanh :: 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 :: Integral b => a -> (b, a)
-- | truncate x returns the integer nearest x
-- between zero and x
truncate :: Integral b => a -> b
-- | round x returns the nearest integer to x; the
-- even integer if x is equidistant between two integers
round :: Integral b => a -> b
-- | ceiling x returns the least integer not less than
-- x
ceiling :: Integral b => a -> b
-- | floor x returns the greatest integer not greater than
-- x
floor :: Integral b => a -> b
-- | 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 :: a -> Integer
-- | a constant function, returning the number of digits of
-- floatRadix in the significand
floatDigits :: a -> Int
-- | a constant function, returning the lowest and highest values the
-- exponent may assume
floatRange :: 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 :: 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 :: 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 :: 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 :: a -> a
-- | multiplies a floating-point number by an integer power of the radix
scaleFloat :: Int -> a -> a
-- | True if the argument is an IEEE "not-a-number" (NaN) value
isNaN :: a -> Bool
-- | True if the argument is an IEEE infinity or negative infinity
isInfinite :: a -> Bool
-- | True if the argument is too small to be represented in
-- normalized format
isDenormalized :: a -> Bool
-- | True if the argument is an IEEE negative zero
isNegativeZero :: a -> Bool
-- | True if the argument is an IEEE floating point number
isIEEE :: 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 :: a -> a -> a
-- | Application operator. This operator is redundant, since ordinary
-- application (f x) means the same as (f $ x).
-- However, $ has low, right-associative binding precedence, so it
-- sometimes allows parentheses to be omitted; for example:
--
--
-- 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.
($) :: (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 $.
(&) :: a -> (a -> b) -> b
infixl 1 &
-- | Strict (call-by-value) application operator. It takes a function and
-- an argument, evaluates the argument to weak head normal form (WHNF),
-- then calls the function with that value.
($!) :: (a -> b) -> a -> b
infixr 0 $!
-- | Boolean "and"
(&&) :: Bool -> Bool -> Bool
infixr 3 &&
-- | Boolean "or"
(||) :: Bool -> Bool -> Bool
infixr 2 ||
-- | Function composition.
(.) :: (b -> c) -> (a -> b) -> a -> c
infixr 9 .
-- | Boolean "not"
not :: Bool -> Bool
-- | otherwise is defined as the value True. It helps to make
-- guards more readable. eg.
--
--
-- f x | x < 0 = ...
-- | otherwise = ...
--
otherwise :: Bool
-- | Extract the first component of a pair.
fst :: (a, b) -> a
-- | Extract the second component of a pair.
snd :: (a, b) -> b
-- | Identity function.
id :: a -> a
-- | 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
-- | 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
-- | flip f takes its (first) two arguments in the reverse
-- order of f.
flip :: (a -> b -> c) -> b -> a -> c
-- | const x is a unary function which evaluates to x for
-- all inputs.
--
-- For instance,
--
--
-- >>> map (const 42) [0..3]
-- [42,42,42,42]
--
const :: a -> b -> a
odd :: Integral a => a -> Bool
even :: Integral a => a -> Bool
-- | uncurry converts a curried function to a function on pairs.
uncurry :: (a -> b -> c) -> (a, b) -> c
-- | curry converts an uncurried function to a curried function.
curry :: ((a, b) -> c) -> a -> b -> c
-- | 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
-- | The value of seq a b is bottom if a is bottom, and
-- otherwise equal to b. 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 :: a -> b -> b
-- | fix f is the least fixed point of the function
-- f, i.e. the least defined x such that f x =
-- x.
fix :: (a -> a) -> a
-- | raise a number to a non-negative integral power
(^) :: (Num a, Integral b) => a -> b -> a
infixr 8 ^
-- | raise a number to an integral power
(^^) :: (Fractional a, Integral b) => a -> b -> a
infixr 8 ^^
-- | 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
-- | general coercion from integral types
fromIntegral :: (Integral a, Num b) => a -> b
-- | general coercion to fractional types
realToFrac :: (Real a, Fractional b) => a -> b
-- | Get the sum of the elements in a Foldable.
--
-- This is not the same as the function from Foldable; instead,
-- this function uses a strict left fold.
sum :: (Foldable f, Num a) => f a -> a
-- | Get the product of the elements in a Foldable.
--
-- This is not the same as the function from Foldable; instead,
-- this function uses a strict left fold.
product :: (Foldable f, Num a) => f a -> a
-- | 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
-- | 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
-- | 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 ()
-- | 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 ()
-- | 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 ()
-- | The sum of a collection of actions, generalizing concat.
asum :: (Foldable t, Alternative f) => t (f a) -> f a
-- | Synonym for traverse_; different from base to generalize to
-- Applicative.
mapM_ :: (Applicative m, Foldable f) => (a -> m b) -> f a -> m ()
-- | Flipped version of mapM_.
forM_ :: (Applicative m, Foldable f) => f a -> (a -> m b) -> m ()
-- | Synonym for sequence_; different from base to generalize to
-- Applicative.
sequence_ :: (Applicative m, Foldable f) => f (m a) -> m ()
-- | 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 concatenation of all the elements of a container of lists.
concat :: Foldable t => t [a] -> [a]
-- | Map a function over all the elements of a container and concatenate
-- the resulting lists.
concatMap :: Foldable t => (a -> [b]) -> t a -> [b]
-- | 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
-- | 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
-- | Determines whether any element of the structure satisfies the
-- predicate.
any :: Foldable t => (a -> Bool) -> t a -> Bool
-- | Determines whether all elements of the structure satisfy the
-- predicate.
all :: Foldable t => (a -> Bool) -> t a -> Bool
-- | notElem is the negation of elem.
notElem :: (Foldable t, Eq a) => a -> t a -> Bool
infix 4 `notElem`
-- | 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
-- | Synonym for traverse; different from base to generalize to
-- Applicative.
mapM :: (Applicative m, Traversable t) => (a -> m b) -> t a -> m (t b)
-- | Synonym for sequenceA; different from base to generalize to
-- Applicative.
sequence :: (Applicative m, Traversable t) => t (m a) -> m (t a)
-- | for is traverse with its arguments flipped. For a
-- version that ignores the results see for_.
for :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b)
-- | Flipped version of mapM.
forM :: (Applicative m, Traversable t) => t a -> (a -> m b) -> m (t b)
-- | The mapAccumL function behaves like a combination of
-- fmap and foldl; it applies a function to each element
-- of a structure, passing an accumulating parameter from left to right,
-- and returning a final value of this accumulator together with the new
-- structure.
mapAccumL :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
-- | The mapAccumR function behaves like a combination of
-- fmap and foldr; it applies a function to each element
-- of a structure, passing an accumulating parameter from right to left,
-- and returning a final value of this accumulator together with the new
-- structure.
mapAccumR :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
-- | Flipped version of <$.
--
-- 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 $>
-- | 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 <$>
-- | void value discards or ignores the result of
-- evaluation, such as the return value of an IO action.
--
-- 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 ()
-- | Lift a function to actions. This function may be used as a value for
-- fmap in a Functor instance.
liftA :: Applicative f => (a -> b) -> f a -> f b
-- | Lift a binary function to actions.
liftA2 :: Applicative f => (a -> b -> c) -> f a -> f b -> f c
-- | Lift a ternary function to actions.
liftA3 :: Applicative f => (a -> b -> c -> d) -> f a -> f b -> f c -> f d
-- | One or none.
optional :: Alternative f => f a -> f (Maybe a)
-- | Same as >>=, but with the arguments interchanged.
(=<<) :: Monad m => (a -> m b) -> m a -> m b
infixr 1 =<<
-- | Left-to-right Kleisli composition of monads.
(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
infixr 1 >=>
-- | Right-to-left Kleisli composition of monads.
-- (>=>), 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 <=<
-- | forever act repeats the action infinitely.
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 :: Monad m => m (m a) -> m a
-- | 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 ()
-- | Like replicateM, but discards the result.
replicateM_ :: Applicative m => Int -> m a -> m ()
-- | guard b is pure () if b is
-- True, and empty if b is False.
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
-- | 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 <$!>
-- | 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 ()
-- | An MVar (pronounced "em-var") is a synchronising variable, used
-- for communication between concurrent threads. It can be thought of as
-- a a box, which may be empty or full.
data MVar a :: * -> *
-- | Create an MVar which is initially empty.
newEmptyMVar :: IO (MVar a)
-- | Create an MVar which contains the supplied value.
newMVar :: a -> IO (MVar 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
-- | 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 its 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
-- | 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
-- | 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)
-- | 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
-- | 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
-- | 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
-- | Like withMVar, but the IO action in the second
-- argument is executed with asynchronous exceptions masked.
withMVarMasked :: MVar a -> (a -> IO 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 ()
-- | 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
-- | Like modifyMVar_, but the IO action in the second
-- argument is executed with asynchronous exceptions masked.
modifyMVarMasked_ :: MVar a -> (a -> IO a) -> 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
-- | 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)
-- | 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))
-- | Chan is an abstract type representing an unbounded FIFO
-- channel.
data Chan a :: * -> *
-- | Build and returns a new instance of Chan.
newChan :: IO (Chan a)
-- | Write a value to a Chan.
writeChan :: Chan a -> a -> IO ()
-- | Read the next value from the Chan.
readChan :: 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)
-- | Retrieves a function of the current environment.
asks :: MonadReader r m => (r -> a) -> m a
-- | Synonym for throw
throwIO :: (MonadThrow m, Exception e) => e -> m a
-- | Synonym for throw
throwM :: (MonadThrow m, Exception e) => e -> m a
-- | Throw an asynchronous exception to another thread
--
-- It's usually a better idea to use the async package, see
-- https://github.com/fpco/safe-exceptions#quickstart
throwTo :: (Exception e, MonadIO m) => ThreadId -> e -> m ()
-- | Same as upstream catch, but will not catch asynchronous
-- exceptions
catch :: (MonadCatch m, Exception e) => m a -> (e -> m a) -> m a
-- | catch specialized to only catching IOExceptions
catchIO :: MonadCatch m => m a -> (IOException -> m a) -> m a
-- | catch specialized to catch all synchronous exception
catchAny :: MonadCatch m => m a -> (SomeException -> m a) -> m a
-- | Same as catch, but fully force evaluation of the result value
-- to find all impure exceptions.
catchDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> (e -> m a) -> m a
-- | catchDeep specialized to catch all synchronous exception
catchAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> (SomeException -> m a) -> m a
-- | Flipped version of catch
handle :: (MonadCatch m, Exception e) => (e -> m a) -> m a -> m a
-- | handle specialized to only catching IOExceptions
handleIO :: MonadCatch m => (IOException -> m a) -> m a -> m a
-- | Flipped version of catchAny
handleAny :: MonadCatch m => (SomeException -> m a) -> m a -> m a
-- | Flipped version of catchDeep
handleDeep :: (MonadCatch m, Exception e, MonadIO m, NFData a) => (e -> m a) -> m a -> m a
-- | Flipped version of catchAnyDeep
handleAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => (SomeException -> m a) -> m a -> m a
-- | Same as upstream try, but will not catch asynchronous
-- exceptions
try :: (MonadCatch m, Exception e) => m a -> m (Either e a)
-- | try specialized to only catching IOExceptions
tryIO :: MonadCatch m => m a -> m (Either IOException a)
-- | try specialized to catch all synchronous exceptions
tryAny :: MonadCatch m => m a -> m (Either SomeException a)
-- | Same as try, but fully force evaluation of the result value to
-- find all impure exceptions.
tryDeep :: (MonadCatch m, MonadIO m, Exception e, NFData a) => m a -> m (Either e a)
-- | tryDeep specialized to catch all synchronous exceptions
tryAnyDeep :: (MonadCatch m, MonadIO m, NFData a) => m a -> m (Either SomeException a)
-- | Async safe version of onException
onException :: MonadMask m => m a -> m b -> m a
-- | Async safe version of bracket
bracket :: MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | Async safe version of bracket_
bracket_ :: MonadMask m => m a -> m b -> m c -> m c
-- | Async safe version of finally
finally :: MonadMask m => m a -> m b -> m a
-- | Like onException, but provides the handler the thrown
-- exception.
withException :: (MonadMask m, Exception e) => m a -> (e -> m b) -> m a
-- | Async safe version of bracketOnError
bracketOnError :: MonadMask m => m a -> (a -> m b) -> (a -> m c) -> m c
-- | Async safe version of bracketOnError_
bracketOnError_ :: MonadMask m => m a -> m b -> m c -> m c
-- | Render this exception value in a human-friendly manner.
--
-- Default implementation: show.
displayException :: Exception e => e -> String
-- | Fanout: send the input to both argument arrows and combine their
-- output.
--
-- The default definition may be overridden with a more efficient version
-- if desired.
(&&&) :: Arrow a => forall b c c'. a b c -> a b c' -> a b (c, c')
-- | Split the input between the two argument arrows and combine their
-- output. Note that this is in general not a functor.
--
-- The default definition may be overridden with a more efficient version
-- if desired.
(***) :: Arrow a => forall b c b' c'. a b c -> a b' c' -> a (b, b') (c, c')
-- | 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 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 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 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 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
-- | 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 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]
-- | 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]
-- | (*) `on` f = \x y -> f x * f y.
--
-- Typical usage: sortBy (compare `on`
-- fst).
--
-- Algebraic properties:
--
--
on :: (b -> b -> c) -> (a -> b) -> a -> a -> c
infixl 0 `on`
-- |
-- 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
-- | Send a Text to standard output, appending a newline, and
-- chunking the data. By default, the chunk size is 2048 characters, so
-- any messages below that size will be sent as one contiguous unit. If
-- larger messages are used, it is possible for interleaving with other
-- threads to occur.
say :: MonadIO m => Text -> m ()
-- | Same as say, but operates on a String. Note that this
-- will force the entire String into memory at once, and will
-- fail for infinite Strings.
sayString :: MonadIO m => String -> m ()
-- | Same as say, but for instances of Show.
--
-- If your Show instance generates infinite output, this will
-- fail. However, an infinite result for show would generally be
-- considered an invalid instance anyway.
sayShow :: (MonadIO m, Show a) => a -> m ()
-- | Same as say, but data is sent to standard error.
sayErr :: MonadIO m => Text -> m ()
-- | Same as sayString, but data is sent to standard error.
sayErrString :: MonadIO m => String -> m ()
-- | Same as sayShow, but data is sent to standard error.
sayErrShow :: (MonadIO m, Show a) => a -> m ()
-- | Same as say, but data is sent to the provided Handle.
hSay :: MonadIO m => Handle -> Text -> m ()
-- | Same as sayString, but data is sent to the provided
-- Handle.
hSayString :: MonadIO m => Handle -> String -> m ()
-- | Same as sayShow, but data is sent to the provided
-- Handle.
hSayShow :: (MonadIO m, Show a) => Handle -> a -> m ()
-- | A mutable variable in the IO monad
data IORef a :: * -> *
-- | Build a new IORef
newIORef :: a -> IO (IORef a)
-- | Read the value of an IORef
readIORef :: IORef a -> IO a
-- | Write a new value into an IORef
writeIORef :: IORef a -> a -> IO ()
-- | Mutate the contents of an IORef.
--
-- Be warned that modifyIORef does not apply the function
-- strictly. This means if the program calls modifyIORef many
-- times, but seldomly uses the value, thunks will pile up in memory
-- resulting in a space leak. This is a common mistake made when using an
-- IORef as a counter. For example, the following will likely produce a
-- stack overflow:
--
--
-- ref <- newIORef 0
-- replicateM_ 1000000 $ modifyIORef ref (+1)
-- readIORef ref >>= print
--
--
-- To avoid this problem, use modifyIORef' instead.
modifyIORef :: IORef a -> (a -> a) -> IO ()
-- | Strict version of modifyIORef
modifyIORef' :: IORef a -> (a -> a) -> IO ()
-- | Atomically modifies the contents of an IORef.
--
-- This function is useful for using IORef in a safe way in a
-- multithreaded program. If you only have one IORef, then using
-- atomicModifyIORef to access and modify it will prevent race
-- conditions.
--
-- Extending the atomicity to multiple IORefs is problematic, so
-- it is recommended that if you need to do anything more complicated
-- then using MVar instead is a good idea.
--
-- atomicModifyIORef does not apply the function strictly. This is
-- important to know even if all you are doing is replacing the value.
-- For example, this will leak memory:
--
--
-- ref <- newIORef '1'
-- forever $ atomicModifyIORef ref (\_ -> ('2', ()))
--
--
-- Use atomicModifyIORef' or atomicWriteIORef to avoid this
-- problem.
atomicModifyIORef :: IORef a -> (a -> (a, b)) -> IO b
-- | Strict version of atomicModifyIORef. This forces both the value
-- stored in the IORef as well as the value returned.
atomicModifyIORef' :: IORef a -> (a -> (a, b)) -> IO b
-- | Variant of writeIORef with the "barrier to reordering" property
-- that atomicModifyIORef has.
atomicWriteIORef :: IORef a -> a -> IO ()
-- | Make a Weak pointer to an IORef, using the second
-- argument as a finalizer to run when IORef is garbage-collected
mkWeakIORef :: IORef a -> IO () -> IO (Weak (IORef 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 :: *
-- | See openFile
data IOMode :: *
ReadMode :: IOMode
WriteMode :: IOMode
AppendMode :: IOMode
ReadWriteMode :: IOMode
-- | A handle managing input from the Haskell program's standard input
-- channel.
stdin :: Handle
-- | A handle managing output to the Haskell program's standard output
-- channel.
stdout :: Handle
-- | A handle managing output to the Haskell program's standard error
-- channel.
stderr :: Handle
-- | Computation hClose hdl makes handle hdl
-- closed. Before the computation finishes, if hdl is writable
-- its buffer is flushed as for hFlush. Performing hClose
-- on a handle that has already been closed has no effect; doing so is
-- not an error. All other operations on a closed handle will fail. If
-- hClose fails for any reason, any further operations (apart from
-- hClose) on the handle will still fail as if hdl had
-- been successfully closed.
hClose :: Handle -> IO ()
-- | withBinaryFile name mode act opens a file using
-- openBinaryFile and passes the resulting handle to the
-- computation act. The handle will be closed on exit from
-- withBinaryFile, whether by normal termination or by raising an
-- exception.
withBinaryFile :: FilePath -> IOMode -> (Handle -> IO r) -> IO r
-- | Read an entire file strictly into a ByteString.
readFile :: FilePath -> IO ByteString
-- | Write a ByteString to a file.
writeFile :: FilePath -> ByteString -> IO ()
-- | Read a file assuming a UTF-8 character encoding.
--
-- This leverages decodeUtf8, so in the event of a character
-- encoding issue, replacement characters will be used.
readFileUtf8 :: MonadIO m => FilePath -> m Text
-- | Write a file using a UTF-8 character encoding.
writeFileUtf8 :: MonadIO m => FilePath -> Text -> m ()
-- | Encode text using UTF-8 encoding.
encodeUtf8 :: Text -> ByteString
-- | A total function for decoding a ByteString into Text
-- using a UTF-8 character encoding. This uses lenientDecode in
-- the case of any encoding errors.
decodeUtf8 :: ByteString -> Text
-- | 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 '()'.
--
--
--
-- Starting with GHC 7.2, you can automatically derive instances for
-- types possessing a Generic instance.
--
--
-- {-# LANGUAGE DeriveGeneric #-}
--
-- import GHC.Generics (Generic)
-- import Control.DeepSeq
--
-- data Foo a = Foo a String
-- deriving (Eq, Generic)
--
-- instance NFData a => NFData (Foo a)
--
-- 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, NFData)
--
-- 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
--
--
-- {-# LANGUAGE BangPatterns #-}
-- instance NFData Colour where rnf !_ = ()
--
rnf :: a -> ()
-- | 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
-- | 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 $!!
-- | 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 ()
--
force :: NFData a => a -> a
-- | Operator version of mappend.
--
-- In base, this operator is known as <>. However, this is
-- the name of the operator for Semigroup as well. Once
-- Semigroup is a superclass of Monoid, this historical
-- accident will be unimportant. In the meanwhile, SafePrelude
-- deals with this situation by making <> the
-- Semigroup operator, and ++ the Monoid operator.
(++) :: Monoid m => m -> m -> m
infixr 5 ++
-- | Parse a string using the Read instance. Succeeds if there is
-- exactly one valid result.
readMaybe :: Read a => String -> Maybe a
-- | Parse a string using the Read instance. Succeeds if there is
-- exactly one valid result. A Left value indicates a parse error.
readEither :: Read a => String -> Either String a