base-4.10.1.0: Basic libraries

Copyright | (c) The University of Glasgow 2001
License | BSD-style (see the file libraries/base/LICENSE)
Maintainer | libraries@haskell.org
Stability | provisional
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

Control.Monad

Contents

- Functor and monad classes
- Functions
  - Naming conventions
  - Basic `Monad` functions
  - Generalisations of list functions
  - Conditional execution of monadic expressions
  - Monadic lifting operators
  - Strict monadic functions

Description

The `Functor`, `Monad` and `MonadPlus` classes, with some useful operations on monads.

Synopsis

- class Functor f where
- class Applicative m => Monad m where
- class (Alternative m, Monad m) => MonadPlus m where
- mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b)
- mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m ()
- forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)
- forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m ()
- sequence :: (Traversable t, Monad m) => t (m a) -> m (t a)
- sequence_ :: (Foldable t, Monad m) => t (m a) -> m ()
- (=<<) :: Monad m => (a -> m b) -> m a -> m b
- (>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c
- (<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c
- forever :: Applicative f => f a -> f b
- void :: Functor f => f a -> f ()
- join :: Monad m => m (m a) -> m a
- msum :: (Foldable t, MonadPlus m) => t (m a) -> m a
- mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a
- filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a]
- mapAndUnzipM :: Applicative m => (a -> m (b, c)) -> [a] -> m ([b], [c])
- zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c]
- zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m ()
- foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b
- foldM_ :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m ()
- replicateM :: Applicative m => Int -> m a -> m [a]
- replicateM_ :: Applicative m => Int -> m a -> m ()
- guard :: Alternative f => Bool -> f ()
- when :: Applicative f => Bool -> f () -> f ()
- unless :: Applicative f => Bool -> f () -> f ()
- liftM :: Monad m => (a1 -> r) -> m a1 -> m r
- liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r
- liftM3 :: Monad m => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r
- liftM4 :: Monad m => (a1 -> a2 -> a3 -> a4 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m r
- liftM5 :: Monad m => (a1 -> a2 -> a3 -> a4 -> a5 -> r) -> m a1 -> m a2 -> m a3 -> m a4 -> m a5 -> m r
- ap :: Monad m => m (a -> b) -> m a -> m b
- (<$!>) :: Monad m => (a -> b) -> m a -> m b

# Functor and monad classes

class Functor f where #

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.

Minimal complete definition

fmap

Methods

fmap :: (a -> b) -> f a -> f b #

Instances

Functor [] # | Since: 2.1
Methods fmap :: (a -> b) -> [a] -> [b] # (<$) :: a -> [b] -> [a] #
Functor Maybe # | Since: 2.1
Methods fmap :: (a -> b) -> Maybe a -> Maybe b # (<$) :: a -> Maybe b -> Maybe a #
Functor IO # | Since: 2.1
Methods fmap :: (a -> b) -> IO a -> IO b # (<$) :: a -> IO b -> IO a #
Functor Par1 # |
Methods fmap :: (a -> b) -> Par1 a -> Par1 b # (<$) :: a -> Par1 b -> Par1 a #
Functor ReadP # | Since: 2.1
Methods fmap :: (a -> b) -> ReadP a -> ReadP b # (<$) :: a -> ReadP b -> ReadP a #
Functor ReadPrec # | Since: 2.1
Methods fmap :: (a -> b) -> ReadPrec a -> ReadPrec b # (<$) :: a -> ReadPrec b -> ReadPrec a #
Functor Last # |
Methods fmap :: (a -> b) -> Last a -> Last b # (<$) :: a -> Last b -> Last a #
Functor First # |
Methods fmap :: (a -> b) -> First a -> First b # (<$) :: a -> First b -> First a #
Functor Product # | Since: 4.8.0.0
Methods fmap :: (a -> b) -> Product a -> Product b # (<$) :: a -> Product b -> Product a #
Functor Sum # | Since: 4.8.0.0
Methods fmap :: (a -> b) -> Sum a -> Sum b # (<$) :: a -> Sum b -> Sum a #
Functor Dual # | Since: 4.8.0.0
Methods fmap :: (a -> b) -> Dual a -> Dual b # (<$) :: a -> Dual b -> Dual a #
Functor STM # | Since: 4.3.0.0
Methods fmap :: (a -> b) -> STM a -> STM b # (<$) :: a -> STM b -> STM a #
Functor Handler # | Since: 4.6.0.0
Methods fmap :: (a -> b) -> Handler a -> Handler b # (<$) :: a -> Handler b -> Handler a #
Functor Identity # | Since: 4.8.0.0
Methods fmap :: (a -> b) -> Identity a -> Identity b # (<$) :: a -> Identity b -> Identity a #
Functor ZipList # |
Methods fmap :: (a -> b) -> ZipList a -> ZipList b # (<$) :: a -> ZipList b -> ZipList a #
Functor ArgDescr # | Since: 4.6.0.0
Methods fmap :: (a -> b) -> ArgDescr a -> ArgDescr b # (<$) :: a -> ArgDescr b -> ArgDescr a #
Functor OptDescr # | Since: 4.6.0.0
Methods fmap :: (a -> b) -> OptDescr a -> OptDescr b # (<$) :: a -> OptDescr b -> OptDescr a #
Functor ArgOrder # | Since: 4.6.0.0
Methods fmap :: (a -> b) -> ArgOrder a -> ArgOrder b # (<$) :: a -> ArgOrder b -> ArgOrder a #
Functor NonEmpty # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> NonEmpty a -> NonEmpty b # (<$) :: a -> NonEmpty b -> NonEmpty a #
Functor Option # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> Option a -> Option b # (<$) :: a -> Option b -> Option a #
Functor Last # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> Last a -> Last b # (<$) :: a -> Last b -> Last a #
Functor First # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> First a -> First b # (<$) :: a -> First b -> First a #
Functor Max # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> Max a -> Max b # (<$) :: a -> Max b -> Max a #
Functor Min # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> Min a -> Min b # (<$) :: a -> Min b -> Min a #
Functor Complex # |
Methods fmap :: (a -> b) -> Complex a -> Complex b # (<$) :: a -> Complex b -> Complex a #
Functor (Either a) # | Since: 3.0
Methods fmap :: (a -> b) -> Either a a -> Either a b # (<$) :: a -> Either a b -> Either a a #
Functor (V1 *) # |
Methods fmap :: (a -> b) -> V1 * a -> V1 * b # (<$) :: a -> V1 * b -> V1 * a #
Functor (U1 *) # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> U1 * a -> U1 * b # (<$) :: a -> U1 * b -> U1 * a #
Functor ((,) a) # | Since: 2.1
Methods fmap :: (a -> b) -> (a, a) -> (a, b) # (<$) :: a -> (a, b) -> (a, a) #
Functor (ST s) # | Since: 2.1
Methods fmap :: (a -> b) -> ST s a -> ST s b # (<$) :: a -> ST s b -> ST s a #
Functor (Proxy *) # | Since: 4.7.0.0
Methods fmap :: (a -> b) -> Proxy * a -> Proxy * b # (<$) :: a -> Proxy * b -> Proxy * a #
Arrow a => Functor (ArrowMonad a) # | Since: 4.6.0.0
Methods fmap :: (a -> b) -> ArrowMonad a a -> ArrowMonad a b # (<$) :: a -> ArrowMonad a b -> ArrowMonad a a #
Monad m => Functor (WrappedMonad m) # | Since: 2.1
Methods fmap :: (a -> b) -> WrappedMonad m a -> WrappedMonad m b # (<$) :: a -> WrappedMonad m b -> WrappedMonad m a #
Functor (ST s) # | Since: 2.1
Methods fmap :: (a -> b) -> ST s a -> ST s b # (<$) :: a -> ST s b -> ST s a #
Functor (Arg a) # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> Arg a a -> Arg a b # (<$) :: a -> Arg a b -> Arg a a #
Functor f => Functor (Rec1 * f) # |
Methods fmap :: (a -> b) -> Rec1 * f a -> Rec1 * f b # (<$) :: a -> Rec1 * f b -> Rec1 * f a #
Functor (URec * Char) # |
Methods fmap :: (a -> b) -> URec * Char a -> URec * Char b # (<$) :: a -> URec * Char b -> URec * Char a #
Functor (URec * Double) # |
Methods fmap :: (a -> b) -> URec * Double a -> URec * Double b # (<$) :: a -> URec * Double b -> URec * Double a #
Functor (URec * Float) # |
Methods fmap :: (a -> b) -> URec * Float a -> URec * Float b # (<$) :: a -> URec * Float b -> URec * Float a #
Functor (URec * Int) # |
Methods fmap :: (a -> b) -> URec * Int a -> URec * Int b # (<$) :: a -> URec * Int b -> URec * Int a #
Functor (URec * Word) # |
Methods fmap :: (a -> b) -> URec * Word a -> URec * Word b # (<$) :: a -> URec * Word b -> URec * Word a #
Functor (URec * (Ptr ())) # |
Methods fmap :: (a -> b) -> URec * (Ptr ()) a -> URec * (Ptr ()) b # (<$) :: a -> URec * (Ptr ()) b -> URec * (Ptr ()) a #
Functor f => Functor (Alt * f) # |
Methods fmap :: (a -> b) -> Alt * f a -> Alt * f b # (<$) :: a -> Alt * f b -> Alt * f a #
Functor (Const * m) # | Since: 2.1
Methods fmap :: (a -> b) -> Const * m a -> Const * m b # (<$) :: a -> Const * m b -> Const * m a #
Arrow a => Functor (WrappedArrow a b) # | Since: 2.1
Methods fmap :: (a -> b) -> WrappedArrow a b a -> WrappedArrow a b b # (<$) :: a -> WrappedArrow a b b -> WrappedArrow a b a #
Functor ((->) LiftedRep LiftedRep r) # | Since: 2.1
Methods fmap :: (a -> b) -> (LiftedRep -> LiftedRep) r a -> (LiftedRep -> LiftedRep) r b # (<$) :: a -> (LiftedRep -> LiftedRep) r b -> (LiftedRep -> LiftedRep) r a #
Functor (K1 * i c) # |
Methods fmap :: (a -> b) -> K1 * i c a -> K1 * i c b # (<$) :: a -> K1 * i c b -> K1 * i c a #
(Functor g, Functor f) => Functor ((:+:) * f g) # |
Methods fmap :: (a -> b) -> (* :+: f) g a -> (* :+: f) g b # (<$) :: a -> (* :+: f) g b -> (* :+: f) g a #
(Functor g, Functor f) => Functor ((:*:) * f g) # |
Methods fmap :: (a -> b) -> (* :*: f) g a -> (* :*: f) g b # (<$) :: a -> (* :*: f) g b -> (* :*: f) g a #
(Functor f, Functor g) => Functor (Sum * f g) # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> Sum * f g a -> Sum * f g b # (<$) :: a -> Sum * f g b -> Sum * f g a #
(Functor f, Functor g) => Functor (Product * f g) # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> Product * f g a -> Product * f g b # (<$) :: a -> Product * f g b -> Product * f g a #
Functor f => Functor (M1 * i c f) # |
Methods fmap :: (a -> b) -> M1 * i c f a -> M1 * i c f b # (<$) :: a -> M1 * i c f b -> M1 * i c f a #
(Functor g, Functor f) => Functor ((:.:) * * f g) # |
Methods fmap :: (a -> b) -> (* :.: *) f g a -> (* :.: *) f g b # (<$) :: a -> (* :.: *) f g b -> (* :.: *) f g a #
(Functor f, Functor g) => Functor (Compose * * f g) # | Since: 4.9.0.0
Methods fmap :: (a -> b) -> Compose * * f g a -> Compose * * f g b # (<$) :: a -> Compose * * f g b -> Compose * * f g a #

class Applicative m => Monad m where #

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:

-     return a >>= k  =  k a

-     m >>= return  =  m

-     m >>= (\x -> k x >>= h)  =  (m >>= k) >>= h

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

-     pure = return

-     (<*>) = ap

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.

Minimal complete definition

(>>=)

Methods

(>>=) :: forall a b. m a -> (a -> m b) -> m b infixl 1 #

Sequentially compose two actions, passing any value produced by the first as an argument to the second.

(>>) :: forall a b. m a -> m b -> m b infixl 1 #

Sequentially compose two actions, discarding any value produced by the first, like sequencing operators (such as the semicolon) in imperative languages.

return :: a -> m a #

Inject a value into the monadic type.

fail :: String -> 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.

Instances

Monad [] # | Since: 2.1
Methods (>>=) :: [a] -> (a -> [b]) -> [b] # (>>) :: [a] -> [b] -> [b] # return :: a -> [a] # fail :: String -> [a] #
Monad Maybe # | Since: 2.1
Methods (>>=) :: Maybe a -> (a -> Maybe b) -> Maybe b # (>>) :: Maybe a -> Maybe b -> Maybe b # return :: a -> Maybe a # fail :: String -> Maybe a #
Monad IO # | Since: 2.1
Methods (>>=) :: IO a -> (a -> IO b) -> IO b # (>>) :: IO a -> IO b -> IO b # return :: a -> IO a # fail :: String -> IO a #
Monad Par1 # | Since: 4.9.0.0
Methods (>>=) :: Par1 a -> (a -> Par1 b) -> Par1 b # (>>) :: Par1 a -> Par1 b -> Par1 b # return :: a -> Par1 a # fail :: String -> Par1 a #
Monad ReadP # | Since: 2.1
Methods (>>=) :: ReadP a -> (a -> ReadP b) -> ReadP b # (>>) :: ReadP a -> ReadP b -> ReadP b # return :: a -> ReadP a # fail :: String -> ReadP a #
Monad ReadPrec # | Since: 2.1
Methods (>>=) :: ReadPrec a -> (a -> ReadPrec b) -> ReadPrec b # (>>) :: ReadPrec a -> ReadPrec b -> ReadPrec b # return :: a -> ReadPrec a # fail :: String -> ReadPrec a #
Monad Last # |
Methods (>>=) :: Last a -> (a -> Last b) -> Last b # (>>) :: Last a -> Last b -> Last b # return :: a -> Last a # fail :: String -> Last a #
Monad First # |
Methods (>>=) :: First a -> (a -> First b) -> First b # (>>) :: First a -> First b -> First b # return :: a -> First a # fail :: String -> First a #
Monad Product # | Since: 4.8.0.0
Methods (>>=) :: Product a -> (a -> Product b) -> Product b # (>>) :: Product a -> Product b -> Product b # return :: a -> Product a # fail :: String -> Product a #
Monad Sum # | Since: 4.8.0.0
Methods (>>=) :: Sum a -> (a -> Sum b) -> Sum b # (>>) :: Sum a -> Sum b -> Sum b # return :: a -> Sum a # fail :: String -> Sum a #
Monad Dual # | Since: 4.8.0.0
Methods (>>=) :: Dual a -> (a -> Dual b) -> Dual b # (>>) :: Dual a -> Dual b -> Dual b # return :: a -> Dual a # fail :: String -> Dual a #
Monad STM # | Since: 4.3.0.0
Methods (>>=) :: STM a -> (a -> STM b) -> STM b # (>>) :: STM a -> STM b -> STM b # return :: a -> STM a # fail :: String -> STM a #
Monad Identity # | Since: 4.8.0.0
Methods (>>=) :: Identity a -> (a -> Identity b) -> Identity b # (>>) :: Identity a -> Identity b -> Identity b # return :: a -> Identity a # fail :: String -> Identity a #
Monad NonEmpty # | Since: 4.9.0.0
Methods (>>=) :: NonEmpty a -> (a -> NonEmpty b) -> NonEmpty b # (>>) :: NonEmpty a -> NonEmpty b -> NonEmpty b # return :: a -> NonEmpty a # fail :: String -> NonEmpty a #
Monad Option # | Since: 4.9.0.0
Methods (>>=) :: Option a -> (a -> Option b) -> Option b # (>>) :: Option a -> Option b -> Option b # return :: a -> Option a # fail :: String -> Option a #
Monad Last # | Since: 4.9.0.0
Methods (>>=) :: Last a -> (a -> Last b) -> Last b # (>>) :: Last a -> Last b -> Last b # return :: a -> Last a # fail :: String -> Last a #
Monad First # | Since: 4.9.0.0
Methods (>>=) :: First a -> (a -> First b) -> First b # (>>) :: First a -> First b -> First b # return :: a -> First a # fail :: String -> First a #
Monad Max # | Since: 4.9.0.0
Methods (>>=) :: Max a -> (a -> Max b) -> Max b # (>>) :: Max a -> Max b -> Max b # return :: a -> Max a # fail :: String -> Max a #
Monad Min # | Since: 4.9.0.0
Methods (>>=) :: Min a -> (a -> Min b) -> Min b # (>>) :: Min a -> Min b -> Min b # return :: a -> Min a # fail :: String -> Min a #
Monad Complex # | Since: 4.9.0.0
Methods (>>=) :: Complex a -> (a -> Complex b) -> Complex b # (>>) :: Complex a -> Complex b -> Complex b # return :: a -> Complex a # fail :: String -> Complex a #
Monad (Either e) # | Since: 4.4.0.0
Methods (>>=) :: Either e a -> (a -> Either e b) -> Either e b # (>>) :: Either e a -> Either e b -> Either e b # return :: a -> Either e a # fail :: String -> Either e a #
Monad (U1 *) # | Since: 4.9.0.0
Methods (>>=) :: U1 * a -> (a -> U1 * b) -> U1 * b # (>>) :: U1 * a -> U1 * b -> U1 * b # return :: a -> U1 * a # fail :: String -> U1 * a #
Monoid a => Monad ((,) a) # | Since: 4.9.0.0
Methods (>>=) :: (a, a) -> (a -> (a, b)) -> (a, b) # (>>) :: (a, a) -> (a, b) -> (a, b) # return :: a -> (a, a) # fail :: String -> (a, a) #
Monad (ST s) # | Since: 2.1
Methods (>>=) :: ST s a -> (a -> ST s b) -> ST s b # (>>) :: ST s a -> ST s b -> ST s b # return :: a -> ST s a # fail :: String -> ST s a #
Monad (Proxy *) # | Since: 4.7.0.0
Methods (>>=) :: Proxy * a -> (a -> Proxy * b) -> Proxy * b # (>>) :: Proxy * a -> Proxy * b -> Proxy * b # return :: a -> Proxy * a # fail :: String -> Proxy * a #
ArrowApply a => Monad (ArrowMonad a) # | Since: 2.1
Methods (>>=) :: ArrowMonad a a -> (a -> ArrowMonad a b) -> ArrowMonad a b # (>>) :: ArrowMonad a a -> ArrowMonad a b -> ArrowMonad a b # return :: a -> ArrowMonad a a # fail :: String -> ArrowMonad a a #
Monad m => Monad (WrappedMonad m) # |
Methods (>>=) :: WrappedMonad m a -> (a -> WrappedMonad m b) -> WrappedMonad m b # (>>) :: WrappedMonad m a -> WrappedMonad m b -> WrappedMonad m b # return :: a -> WrappedMonad m a # fail :: String -> WrappedMonad m a #
Monad (ST s) # | Since: 2.1
Methods (>>=) :: ST s a -> (a -> ST s b) -> ST s b # (>>) :: ST s a -> ST s b -> ST s b # return :: a -> ST s a # fail :: String -> ST s a #
Monad f => Monad (Rec1 * f) # | Since: 4.9.0.0
Methods (>>=) :: Rec1 * f a -> (a -> Rec1 * f b) -> Rec1 * f b # (>>) :: Rec1 * f a -> Rec1 * f b -> Rec1 * f b # return :: a -> Rec1 * f a # fail :: String -> Rec1 * f a #
Monad f => Monad (Alt * f) # |
Methods (>>=) :: Alt * f a -> (a -> Alt * f b) -> Alt * f b # (>>) :: Alt * f a -> Alt * f b -> Alt * f b # return :: a -> Alt * f a # fail :: String -> Alt * f a #
Monad ((->) LiftedRep LiftedRep r) # | Since: 2.1
Methods (>>=) :: (LiftedRep -> LiftedRep) r a -> (a -> (LiftedRep -> LiftedRep) r b) -> (LiftedRep -> LiftedRep) r b # (>>) :: (LiftedRep -> LiftedRep) r a -> (LiftedRep -> LiftedRep) r b -> (LiftedRep -> LiftedRep) r b # return :: a -> (LiftedRep -> LiftedRep) r a # fail :: String -> (LiftedRep -> LiftedRep) r a #
(Monad f, Monad g) => Monad ((:*:) * f g) # | Since: 4.9.0.0
Methods (>>=) :: (* :*: f) g a -> (a -> (* :*: f) g b) -> (* :*: f) g b # (>>) :: (* :*: f) g a -> (* :*: f) g b -> (* :*: f) g b # return :: a -> (* :*: f) g a # fail :: String -> (* :*: f) g a #
(Monad f, Monad g) => Monad (Product * f g) # | Since: 4.9.0.0
Methods (>>=) :: Product * f g a -> (a -> Product * f g b) -> Product * f g b # (>>) :: Product * f g a -> Product * f g b -> Product * f g b # return :: a -> Product * f g a # fail :: String -> Product * f g a #
Monad f => Monad (M1 * i c f) # | Since: 4.9.0.0
Methods (>>=) :: M1 * i c f a -> (a -> M1 * i c f b) -> M1 * i c f b # (>>) :: M1 * i c f a -> M1 * i c f b -> M1 * i c f b # return :: a -> M1 * i c f a # fail :: String -> M1 * i c f a #

class (Alternative m, Monad m) => MonadPlus m where #

Monads that also support choice and failure.

Methods

mzero :: m a #

the identity of `mplus`. It should also satisfy the equations

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

mplus :: m a -> m a -> m a #

an associative operation

Instances

MonadPlus [] # | Since: 2.1
Methods mzero :: [a] # mplus :: [a] -> [a] -> [a] #
MonadPlus Maybe # | Since: 2.1
Methods mzero :: Maybe a # mplus :: Maybe a -> Maybe a -> Maybe a #
MonadPlus IO # | Since: 4.9.0.0
Methods mzero :: IO a # mplus :: IO a -> IO a -> IO a #
MonadPlus ReadP # | Since: 2.1
Methods mzero :: ReadP a # mplus :: ReadP a -> ReadP a -> ReadP a #
MonadPlus ReadPrec # | Since: 2.1
Methods mzero :: ReadPrec a # mplus :: ReadPrec a -> ReadPrec a -> ReadPrec a #
MonadPlus STM # | Since: 4.3.0.0
Methods mzero :: STM a # mplus :: STM a -> STM a -> STM a #
MonadPlus Option # | Since: 4.9.0.0
Methods mzero :: Option a # mplus :: Option a -> Option a -> Option a #
MonadPlus (U1 *) # | Since: 4.9.0.0
Methods mzero :: U1 * a # mplus :: U1 * a -> U1 * a -> U1 * a #
MonadPlus (Proxy *) # | Since: 4.9.0.0
Methods mzero :: Proxy * a # mplus :: Proxy * a -> Proxy * a -> Proxy * a #
(ArrowApply a, ArrowPlus a) => MonadPlus (ArrowMonad a) # | Since: 4.6.0.0
Methods mzero :: ArrowMonad a a # mplus :: ArrowMonad a a -> ArrowMonad a a -> ArrowMonad a a #
MonadPlus f => MonadPlus (Rec1 * f) # | Since: 4.9.0.0
Methods mzero :: Rec1 * f a # mplus :: Rec1 * f a -> Rec1 * f a -> Rec1 * f a #
MonadPlus f => MonadPlus (Alt * f) # |
Methods mzero :: Alt * f a # mplus :: Alt * f a -> Alt * f a -> Alt * f a #
(MonadPlus f, MonadPlus g) => MonadPlus ((:*:) * f g) # | Since: 4.9.0.0
Methods mzero :: (* :*: f) g a # mplus :: (* :*: f) g a -> (* :*: f) g a -> (* :*: f) g a #
(MonadPlus f, MonadPlus g) => MonadPlus (Product * f g) # | Since: 4.9.0.0
Methods mzero :: Product * f g a # mplus :: Product * f g a -> Product * f g a -> Product * f g a #
MonadPlus f => MonadPlus (M1 * i c f) # | Since: 4.9.0.0
Methods mzero :: M1 * i c f a # mplus :: M1 * i c f a -> M1 * i c f a -> M1 * i c f a #

# Functions

## Naming conventions

The functions in this library use the following naming conventions:

- A postfix '`M`' always stands for a function in the Kleisli category: The monad type constructor `m` is added to function results (modulo currying) and nowhere else. So, for example,

     filter  ::              (a ->   Bool) -> [a] ->   [a]
     filterM :: (Monad m) => (a -> m Bool) -> [a] -> m [a]

- A postfix '`_`' changes the result type from `(m a)` to `(m ())`. Thus, for example:

     sequence  :: Monad m => [m a] -> m [a]
     sequence_ :: Monad m => [m a] -> m ()

- A prefix '`m`' generalizes an existing function to a monadic form. Thus, for example:

     sum  :: Num a       => [a]   -> a
     msum :: MonadPlus m => [m a] -> m a

## Basic `Monad` functions

mapM :: (Traversable t, Monad m) => (a -> m b) -> t a -> m (t b) #

Map each element of a structure to a monadic action, evaluate these actions from left to right, and collect the results. For a version that ignores the results see `mapM_`.

mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> 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`.

forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b) #

`forM` is `mapM` with its arguments flipped. For a version that ignores the results see `forM_`.

forM_ :: (Foldable t, Monad m) => t a -> (a -> m b) -> m () #

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

sequence :: (Traversable t, Monad m) => t (m a) -> m (t a) #

Evaluate each monadic action in the structure from left to right, and collect the results. For a version that ignores the results see `sequence_`.

sequence_ :: (Foldable t, Monad m) => t (m a) -> m () #

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

(=<<) :: Monad m => (a -> m b) -> m a -> m b infixr 1 #

Same as `>>=`, but with the arguments interchanged.

(>=>) :: Monad m => (a -> m b) -> (b -> m c) -> a -> m c infixr 1 #

Left-to-right Kleisli composition of monads.

(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> 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

forever :: Applicative f => f a -> f b #

``forever` act` repeats the action infinitely.

void :: Functor f => f a -> f () #

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

## Generalisations of list functions

join :: Monad m => m (m a) -> m a #

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.

msum :: (Foldable t, MonadPlus m) => t (m a) -> m a #

The sum of a collection of actions, generalizing `concat`. As of base 4.8.0.0, `msum` is just `asum`, specialized to `MonadPlus`.

mfilter :: MonadPlus m => (a -> Bool) -> m a -> m a #

Direct `MonadPlus` equivalent of `filter` ``filter`` = `(mfilter:: (a -> Bool) -> [a] -> [a]` applicable to any `MonadPlus`, for example `mfilter odd (Just 1) == Just 1` `mfilter odd (Just 2) == Nothing`

filterM :: Applicative m => (a -> m Bool) -> [a] -> m [a] #

This generalizes the list-based `filter` function.

mapAndUnzipM :: Applicative m => (a -> m (b, c)) -> [a] -> m ([b], [c]) #

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-transforming monad.

zipWithM :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m [c] #

The `zipWithM` function generalizes `zipWith` to arbitrary applicative functors.

zipWithM_ :: Applicative m => (a -> b -> m c) -> [a] -> [b] -> m () #

`zipWithM_` is the extension of `zipWithM` which ignores the final result.

foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b #

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 () #

Like `foldM`, but discards the result.

replicateM :: Applicative m => Int -> m a -> m [a] #

``replicateM` n act` performs the action `n` times, gathering the results.

replicateM_ :: Applicative m => Int -> m a -> m () #

Like `replicateM`, but discards the result.

## Conditional execution of monadic expressions

guard :: Alternative f => Bool -> f () #

``guard` b` is ``pure` ()` if `b` is `True`, and `empty` if `b` is `False`.

when :: Applicative f => Bool -> f () -> 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.

unless :: Applicative f => Bool -> f () -> f () #

The reverse of `when`.

## Monadic lifting operators

liftM :: Monad m => (a1 -> r) -> m a1 -> m r #

Promote a function to a monad.

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. For example,

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

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 #

Promote a function to a monad, scanning the monadic arguments from left to right (cf. `liftM2`).

ap :: Monad m => m (a -> b) -> m a -> m b #

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

## Strict monadic functions

(<$!>) :: Monad m => (a -> b) -> m a -> m b infixl 4 #

Strict version of `<$>`.

Since: 4.8.0.0