W3cubDocs

/Haskell 9

Control.Monad

Copyright	(c) The University of Glasgow 2001
License	BSD-style (see the file libraries/base/LICENSE)
Maintainer	[email protected]
Stability	provisional
Portability	portable
Safe Haskell	Safe
Language	Haskell2010

Functor and monad classes
Functions

Description

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

Functor and monad classes

class Functor (f :: Type -> Type) where Source

A type f is a Functor if it provides a function fmap which, given any types a and b lets you apply any function from (a -> b) to turn an f a into an f b, preserving the structure of f. Furthermore f needs to adhere to the following:

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

Note, that the second law follows from the free theorem of the type fmap and the first law, so you need only check that the former condition holds. See these articles by School of Haskell or David Luposchainsky for an explanation.

Minimal complete definition

fmap

Methods

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

fmap is used to apply a function of type (a -> b) to a value of type f a, where f is a functor, to produce a value of type f b. Note that for any type constructor with more than one parameter (e.g., Either), only the last type parameter can be modified with fmap (e.g., b in `Either a b`).

Some type constructors with two parameters or more have a Bifunctor instance that allows both the last and the penultimate parameters to be mapped over.

Examples

Expand

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

>>> fmap show Nothing
Nothing
>>> fmap show (Just 3)
Just "3"

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

>>> fmap show (Left 17)
Left 17
>>> fmap show (Right 17)
Right "17"

Double each element of a list:

>>> fmap (*2) [1,2,3]
[2,4,6]

Apply even to the second element of a pair:

>>> fmap even (2,2)
(2,True)

It may seem surprising that the function is only applied to the last element of the tuple compared to the list example above which applies it to every element in the list. To understand, remember that tuples are type constructors with multiple type parameters: a tuple of 3 elements (a,b,c) can also be written (,,) a b c and its Functor instance is defined for Functor ((,,) a b) (i.e., only the third parameter is free to be mapped over with fmap).

It explains why fmap can be used with tuples containing values of different types as in the following example:

>>> fmap even ("hello", 1.0, 4)
("hello",1.0,True)

(<$) :: a -> f b -> f a infixl 4 Source

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.

Examples

Expand

Perform a computation with Maybe and replace the result with a constant value if it is Just:

>>> 'a' <$ Just 2
Just 'a'
>>> 'a' <$ Nothing
Nothing

Instances

Instances details

Functor Complex Source	Since: base-4.9.0.0
Instance details Defined in Data.Complex Methods fmap :: (a -> b) -> Complex a -> Complex b Source (<$) :: a -> Complex b -> Complex a Source
Functor First Source	Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods fmap :: (a -> b) -> First a -> First b Source (<$) :: a -> First b -> First a Source
Functor Last Source	Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods fmap :: (a -> b) -> Last a -> Last b Source (<$) :: a -> Last b -> Last a Source
Functor Max Source	Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods fmap :: (a -> b) -> Max a -> Max b Source (<$) :: a -> Max b -> Max a Source
Functor Min Source	Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods fmap :: (a -> b) -> Min a -> Min b Source (<$) :: a -> Min b -> Min a Source
Functor ArgDescr Source	Since: base-4.7.0.0
Instance details Defined in System.Console.GetOpt Methods fmap :: (a -> b) -> ArgDescr a -> ArgDescr b Source (<$) :: a -> ArgDescr b -> ArgDescr a Source
Functor ArgOrder Source	Since: base-4.7.0.0
Instance details Defined in System.Console.GetOpt Methods fmap :: (a -> b) -> ArgOrder a -> ArgOrder b Source (<$) :: a -> ArgOrder b -> ArgOrder a Source
Functor OptDescr Source	Since: base-4.7.0.0
Instance details Defined in System.Console.GetOpt Methods fmap :: (a -> b) -> OptDescr a -> OptDescr b Source (<$) :: a -> OptDescr b -> OptDescr a Source
Functor NonEmpty Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Base Methods fmap :: (a -> b) -> NonEmpty a -> NonEmpty b Source (<$) :: a -> NonEmpty b -> NonEmpty a Source
Functor STM Source	Since: base-4.3.0.0
Instance details Defined in GHC.Internal.Conc.Sync Methods fmap :: (a -> b) -> STM a -> STM b Source (<$) :: a -> STM b -> STM a Source
Functor Handler Source	Since: base-4.6.0.0
Instance details Defined in GHC.Internal.Control.Exception Methods fmap :: (a -> b) -> Handler a -> Handler b Source (<$) :: a -> Handler b -> Handler a Source
Functor Identity Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Functor.Identity Methods fmap :: (a -> b) -> Identity a -> Identity b Source (<$) :: a -> Identity b -> Identity a Source
Functor First Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Monoid Methods fmap :: (a -> b) -> First a -> First b Source (<$) :: a -> First b -> First a Source
Functor Last Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Monoid Methods fmap :: (a -> b) -> Last a -> Last b Source (<$) :: a -> Last b -> Last a Source
Functor Down Source	Since: base-4.11.0.0
Instance details Defined in GHC.Internal.Data.Ord Methods fmap :: (a -> b) -> Down a -> Down b Source (<$) :: a -> Down b -> Down a Source
Functor Dual Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Semigroup.Internal Methods fmap :: (a -> b) -> Dual a -> Dual b Source (<$) :: a -> Dual b -> Dual a Source
Functor Product Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Semigroup.Internal Methods fmap :: (a -> b) -> Product a -> Product b Source (<$) :: a -> Product b -> Product a Source
Functor Sum Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Semigroup.Internal Methods fmap :: (a -> b) -> Sum a -> Sum b Source (<$) :: a -> Sum b -> Sum a Source
Functor ZipList Source	Since: base-2.1
Instance details Defined in GHC.Internal.Functor.ZipList Methods fmap :: (a -> b) -> ZipList a -> ZipList b Source (<$) :: a -> ZipList b -> ZipList a Source
Functor NoIO Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.GHCi Methods fmap :: (a -> b) -> NoIO a -> NoIO b Source (<$) :: a -> NoIO b -> NoIO a Source
Functor Par1 Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> Par1 a -> Par1 b Source (<$) :: a -> Par1 b -> Par1 a Source
Functor Q Source
Instance details Defined in GHC.Internal.TH.Syntax Methods fmap :: (a -> b) -> Q a -> Q b Source (<$) :: a -> Q b -> Q a Source
Functor TyVarBndr Source
Instance details Defined in GHC.Internal.TH.Syntax Methods fmap :: (a -> b) -> TyVarBndr a -> TyVarBndr b Source (<$) :: a -> TyVarBndr b -> TyVarBndr a Source
Functor P Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadP Methods fmap :: (a -> b) -> P a -> P b Source (<$) :: a -> P b -> P a Source
Functor ReadP Source	Since: base-2.1
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadP Methods fmap :: (a -> b) -> ReadP a -> ReadP b Source (<$) :: a -> ReadP b -> ReadP a Source
Functor ReadPrec Source	Since: base-2.1
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadPrec Methods fmap :: (a -> b) -> ReadPrec a -> ReadPrec b Source (<$) :: a -> ReadPrec b -> ReadPrec a Source
Functor IO Source	Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods fmap :: (a -> b) -> IO a -> IO b Source (<$) :: a -> IO b -> IO a Source
Functor Maybe Source	Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods fmap :: (a -> b) -> Maybe a -> Maybe b Source (<$) :: a -> Maybe b -> Maybe a Source
Functor Solo Source	Since: base-4.15
Instance details Defined in GHC.Internal.Base Methods fmap :: (a -> b) -> Solo a -> Solo b Source (<$) :: a -> Solo b -> Solo a Source
Functor [] Source	Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods fmap :: (a -> b) -> [a] -> [b] Source (<$) :: a -> [b] -> [a] Source
Monad m => Functor (WrappedMonad m) Source	Since: base-2.1
Instance details Defined in Control.Applicative Methods fmap :: (a -> b) -> WrappedMonad m a -> WrappedMonad m b Source (<$) :: a -> WrappedMonad m b -> WrappedMonad m a Source
Functor (Arg a) Source	Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods fmap :: (a0 -> b) -> Arg a a0 -> Arg a b Source (<$) :: a0 -> Arg a b -> Arg a a0 Source
Functor (Array i) Source	Since: base-2.1
Instance details Defined in GHC.Internal.Arr Methods fmap :: (a -> b) -> Array i a -> Array i b Source (<$) :: a -> Array i b -> Array i a Source
Arrow a => Functor (ArrowMonad a) Source	Since: base-4.6.0.0
Instance details Defined in GHC.Internal.Control.Arrow Methods fmap :: (a0 -> b) -> ArrowMonad a a0 -> ArrowMonad a b Source (<$) :: a0 -> ArrowMonad a b -> ArrowMonad a a0 Source
Functor (ST s) Source	Since: base-2.1
Instance details Defined in GHC.Internal.Control.Monad.ST.Lazy.Imp Methods fmap :: (a -> b) -> ST s a -> ST s b Source (<$) :: a -> ST s b -> ST s a Source
Functor (Either a) Source	Since: base-3.0
Instance details Defined in GHC.Internal.Data.Either Methods fmap :: (a0 -> b) -> Either a a0 -> Either a b Source (<$) :: a0 -> Either a b -> Either a a0 Source
Functor (StateL s) Source	Since: base-4.0
Instance details Defined in GHC.Internal.Data.Functor.Utils Methods fmap :: (a -> b) -> StateL s a -> StateL s b Source (<$) :: a -> StateL s b -> StateL s a Source
Functor (StateR s) Source	Since: base-4.0
Instance details Defined in GHC.Internal.Data.Functor.Utils Methods fmap :: (a -> b) -> StateR s a -> StateR s b Source (<$) :: a -> StateR s b -> StateR s a Source
Functor (Proxy :: Type -> Type) Source	Since: base-4.7.0.0
Instance details Defined in GHC.Internal.Data.Proxy Methods fmap :: (a -> b) -> Proxy a -> Proxy b Source (<$) :: a -> Proxy b -> Proxy a Source
Functor (U1 :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> U1 a -> U1 b Source (<$) :: a -> U1 b -> U1 a Source
Functor (V1 :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> V1 a -> V1 b Source (<$) :: a -> V1 b -> V1 a Source
Functor (ST s) Source	Since: base-2.1
Instance details Defined in GHC.Internal.ST Methods fmap :: (a -> b) -> ST s a -> ST s b Source (<$) :: a -> ST s b -> ST s a Source
Functor ((,) a) Source	Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods fmap :: (a0 -> b) -> (a, a0) -> (a, b) Source (<$) :: a0 -> (a, b) -> (a, a0) Source
Arrow a => Functor (WrappedArrow a b) Source	Since: base-2.1
Instance details Defined in Control.Applicative Methods fmap :: (a0 -> b0) -> WrappedArrow a b a0 -> WrappedArrow a b b0 Source (<$) :: a0 -> WrappedArrow a b b0 -> WrappedArrow a b a0 Source
Functor m => Functor (Kleisli m a) Source	Since: base-4.14.0.0
Instance details Defined in GHC.Internal.Control.Arrow Methods fmap :: (a0 -> b) -> Kleisli m a a0 -> Kleisli m a b Source (<$) :: a0 -> Kleisli m a b -> Kleisli m a a0 Source
Functor (Const m :: Type -> Type) Source	Since: base-2.1
Instance details Defined in GHC.Internal.Data.Functor.Const Methods fmap :: (a -> b) -> Const m a -> Const m b Source (<$) :: a -> Const m b -> Const m a Source
Monad m => Functor (StateT s m) Source	Since: base-4.18.0.0
Instance details Defined in GHC.Internal.Data.Functor.Utils Methods fmap :: (a -> b) -> StateT s m a -> StateT s m b Source (<$) :: a -> StateT s m b -> StateT s m a Source
Functor f => Functor (Ap f) Source	Since: base-4.12.0.0
Instance details Defined in GHC.Internal.Data.Monoid Methods fmap :: (a -> b) -> Ap f a -> Ap f b Source (<$) :: a -> Ap f b -> Ap f a Source
Functor f => Functor (Alt f) Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Semigroup.Internal Methods fmap :: (a -> b) -> Alt f a -> Alt f b Source (<$) :: a -> Alt f b -> Alt f a Source
(Generic1 f, Functor (Rep1 f)) => Functor (Generically1 f) Source	Since: base-4.17.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> Generically1 f a -> Generically1 f b Source (<$) :: a -> Generically1 f b -> Generically1 f a Source
Functor f => Functor (Rec1 f) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> Rec1 f a -> Rec1 f b Source (<$) :: a -> Rec1 f b -> Rec1 f a Source
Functor (URec (Ptr ()) :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> URec (Ptr ()) a -> URec (Ptr ()) b Source (<$) :: a -> URec (Ptr ()) b -> URec (Ptr ()) a Source
Functor (URec Char :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> URec Char a -> URec Char b Source (<$) :: a -> URec Char b -> URec Char a Source
Functor (URec Double :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> URec Double a -> URec Double b Source (<$) :: a -> URec Double b -> URec Double a Source
Functor (URec Float :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> URec Float a -> URec Float b Source (<$) :: a -> URec Float b -> URec Float a Source
Functor (URec Int :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> URec Int a -> URec Int b Source (<$) :: a -> URec Int b -> URec Int a Source
Functor (URec Word :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> URec Word a -> URec Word b Source (<$) :: a -> URec Word b -> URec Word a Source
Functor ((,,) a b) Source	Since: base-4.14.0.0
Instance details Defined in GHC.Internal.Base Methods fmap :: (a0 -> b0) -> (a, b, a0) -> (a, b, b0) Source (<$) :: a0 -> (a, b, b0) -> (a, b, a0) Source
(Functor f, Functor g) => Functor (Product f g) Source	Since: base-4.9.0.0
Instance details Defined in Data.Functor.Product Methods fmap :: (a -> b) -> Product f g a -> Product f g b Source (<$) :: a -> Product f g b -> Product f g a Source
(Functor f, Functor g) => Functor (Sum f g) Source	Since: base-4.9.0.0
Instance details Defined in Data.Functor.Sum Methods fmap :: (a -> b) -> Sum f g a -> Sum f g b Source (<$) :: a -> Sum f g b -> Sum f g a Source
(Functor f, Functor g) => Functor (f :*: g) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> (f :: g) a -> (f :: g) b Source (<$) :: a -> (f :: g) b -> (f :: g) a Source
(Functor f, Functor g) => Functor (f :+: g) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> (f :+: g) a -> (f :+: g) b Source (<$) :: a -> (f :+: g) b -> (f :+: g) a Source
Functor (K1 i c :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> K1 i c a -> K1 i c b Source (<$) :: a -> K1 i c b -> K1 i c a Source
Functor ((,,,) a b c) Source	Since: base-4.14.0.0
Instance details Defined in GHC.Internal.Base Methods fmap :: (a0 -> b0) -> (a, b, c, a0) -> (a, b, c, b0) Source (<$) :: a0 -> (a, b, c, b0) -> (a, b, c, a0) Source
Functor ((->) r) Source	Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods fmap :: (a -> b) -> (r -> a) -> r -> b Source (<$) :: a -> (r -> b) -> r -> a Source
(Functor f, Functor g) => Functor (Compose f g) Source	Since: base-4.9.0.0
Instance details Defined in Data.Functor.Compose Methods fmap :: (a -> b) -> Compose f g a -> Compose f g b Source (<$) :: a -> Compose f g b -> Compose f g a Source
(Functor f, Functor g) => Functor (f :.: g) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> (f :.: g) a -> (f :.: g) b Source (<$) :: a -> (f :.: g) b -> (f :.: g) a Source
Functor f => Functor (M1 i c f) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods fmap :: (a -> b) -> M1 i c f a -> M1 i c f b Source (<$) :: a -> M1 i c f b -> M1 i c f a Source
Functor ((,,,,) a b c d) Source	Since: base-4.18.0.0
Instance details Defined in GHC.Internal.Base Methods fmap :: (a0 -> b0) -> (a, b, c, d, a0) -> (a, b, c, d, b0) Source (<$) :: a0 -> (a, b, c, d, b0) -> (a, b, c, d, a0) Source
Functor ((,,,,,) a b c d e) Source	Since: base-4.18.0.0
Instance details Defined in GHC.Internal.Base Methods fmap :: (a0 -> b0) -> (a, b, c, d, e, a0) -> (a, b, c, d, e, b0) Source (<$) :: a0 -> (a, b, c, d, e, b0) -> (a, b, c, d, e, a0) Source
Functor ((,,,,,,) a b c d e f) Source	Since: base-4.18.0.0
Instance details Defined in GHC.Internal.Base Methods fmap :: (a0 -> b0) -> (a, b, c, d, e, f, a0) -> (a, b, c, d, e, f, b0) Source (<$) :: a0 -> (a, b, c, d, e, f, b0) -> (a, b, c, d, e, f, a0) Source

class Applicative m => Monad (m :: Type -> Type) where Source

The Monad class defines the basic operations over a monad, a concept from a branch of mathematics known as category theory. From the perspective of a Haskell programmer, however, it is best to think of a monad as an abstract datatype of actions. Haskell's do expressions provide a convenient syntax for writing monadic expressions.

Instances of Monad should satisfy the following:

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

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

```
pure = return
```

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

The above laws imply:

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

and that pure and (<*>) satisfy the applicative functor laws.

The instances of Monad for List, Maybe and IO defined in the Prelude satisfy these laws.

Minimal complete definition

(>>=)

Methods

(>>=) :: m a -> (a -> m b) -> m b infixl 1 Source

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

'as >>= bs' can be understood as the do expression

do a <- as
   bs a

An alternative name for this function is 'bind', but some people may refer to it as 'flatMap', which results from it being equivalent to

\x f -> join (fmap f x) :: Monad m => m a -> (a -> m b) -> m b

which can be seen as mapping a value with Monad m => m a -> m (m b) and then 'flattening' m (m b) to m b using join.

(>>) :: m a -> m b -> m b infixl 1 Source

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

'as >> bs' can be understood as the do expression

do as
   bs

or in terms of (>>=) as

as >>= const bs

return :: a -> m a Source

Inject a value into the monadic type. This function should not be different from its default implementation as pure. The justification for the existence of this function is merely historic.

Instances

Instances details

Monad Complex Source	Since: base-4.9.0.0
Instance details Defined in Data.Complex Methods (>>=) :: Complex a -> (a -> Complex b) -> Complex b Source (>>) :: Complex a -> Complex b -> Complex b Source return :: a -> Complex a Source
Monad First Source	Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods (>>=) :: First a -> (a -> First b) -> First b Source (>>) :: First a -> First b -> First b Source return :: a -> First a Source
Monad Last Source	Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods (>>=) :: Last a -> (a -> Last b) -> Last b Source (>>) :: Last a -> Last b -> Last b Source return :: a -> Last a Source
Monad Max Source	Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods (>>=) :: Max a -> (a -> Max b) -> Max b Source (>>) :: Max a -> Max b -> Max b Source return :: a -> Max a Source
Monad Min Source	Since: base-4.9.0.0
Instance details Defined in Data.Semigroup Methods (>>=) :: Min a -> (a -> Min b) -> Min b Source (>>) :: Min a -> Min b -> Min b Source return :: a -> Min a Source
Monad NonEmpty Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Base Methods (>>=) :: NonEmpty a -> (a -> NonEmpty b) -> NonEmpty b Source (>>) :: NonEmpty a -> NonEmpty b -> NonEmpty b Source return :: a -> NonEmpty a Source
Monad STM Source	Since: base-4.3.0.0
Instance details Defined in GHC.Internal.Conc.Sync Methods (>>=) :: STM a -> (a -> STM b) -> STM b Source (>>) :: STM a -> STM b -> STM b Source return :: a -> STM a Source
Monad Identity Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Functor.Identity Methods (>>=) :: Identity a -> (a -> Identity b) -> Identity b Source (>>) :: Identity a -> Identity b -> Identity b Source return :: a -> Identity a Source
Monad First Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Monoid Methods (>>=) :: First a -> (a -> First b) -> First b Source (>>) :: First a -> First b -> First b Source return :: a -> First a Source
Monad Last Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Monoid Methods (>>=) :: Last a -> (a -> Last b) -> Last b Source (>>) :: Last a -> Last b -> Last b Source return :: a -> Last a Source
Monad Down Source	Since: base-4.11.0.0
Instance details Defined in GHC.Internal.Data.Ord Methods (>>=) :: Down a -> (a -> Down b) -> Down b Source (>>) :: Down a -> Down b -> Down b Source return :: a -> Down a Source
Monad Dual Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Semigroup.Internal Methods (>>=) :: Dual a -> (a -> Dual b) -> Dual b Source (>>) :: Dual a -> Dual b -> Dual b Source return :: a -> Dual a Source
Monad Product Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Semigroup.Internal Methods (>>=) :: Product a -> (a -> Product b) -> Product b Source (>>) :: Product a -> Product b -> Product b Source return :: a -> Product a Source
Monad Sum Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Semigroup.Internal Methods (>>=) :: Sum a -> (a -> Sum b) -> Sum b Source (>>) :: Sum a -> Sum b -> Sum b Source return :: a -> Sum a Source
Monad NoIO Source	Since: base-4.4.0.0
Instance details Defined in GHC.Internal.GHCi Methods (>>=) :: NoIO a -> (a -> NoIO b) -> NoIO b Source (>>) :: NoIO a -> NoIO b -> NoIO b Source return :: a -> NoIO a Source
Monad Par1 Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods (>>=) :: Par1 a -> (a -> Par1 b) -> Par1 b Source (>>) :: Par1 a -> Par1 b -> Par1 b Source return :: a -> Par1 a Source
Monad Q Source
Instance details Defined in GHC.Internal.TH.Syntax Methods (>>=) :: Q a -> (a -> Q b) -> Q b Source (>>) :: Q a -> Q b -> Q b Source return :: a -> Q a Source
Monad P Source	Since: base-2.1
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadP Methods (>>=) :: P a -> (a -> P b) -> P b Source (>>) :: P a -> P b -> P b Source return :: a -> P a Source
Monad ReadP Source	Since: base-2.1
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadP Methods (>>=) :: ReadP a -> (a -> ReadP b) -> ReadP b Source (>>) :: ReadP a -> ReadP b -> ReadP b Source return :: a -> ReadP a Source
Monad ReadPrec Source	Since: base-2.1
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadPrec Methods (>>=) :: ReadPrec a -> (a -> ReadPrec b) -> ReadPrec b Source (>>) :: ReadPrec a -> ReadPrec b -> ReadPrec b Source return :: a -> ReadPrec a Source
Monad IO Source	Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods (>>=) :: IO a -> (a -> IO b) -> IO b Source (>>) :: IO a -> IO b -> IO b Source return :: a -> IO a Source
Monad Maybe Source	Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods (>>=) :: Maybe a -> (a -> Maybe b) -> Maybe b Source (>>) :: Maybe a -> Maybe b -> Maybe b Source return :: a -> Maybe a Source
Monad Solo Source	Since: base-4.15
Instance details Defined in GHC.Internal.Base Methods (>>=) :: Solo a -> (a -> Solo b) -> Solo b Source (>>) :: Solo a -> Solo b -> Solo b Source return :: a -> Solo a Source
Monad [] Source	Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods (>>=) :: [a] -> (a -> [b]) -> [b] Source (>>) :: [a] -> [b] -> [b] Source return :: a -> [a] Source
Monad m => Monad (WrappedMonad m) Source	Since: base-4.7.0.0
Instance details Defined in Control.Applicative Methods (>>=) :: WrappedMonad m a -> (a -> WrappedMonad m b) -> WrappedMonad m b Source (>>) :: WrappedMonad m a -> WrappedMonad m b -> WrappedMonad m b Source return :: a -> WrappedMonad m a Source
ArrowApply a => Monad (ArrowMonad a) Source	Since: base-2.1
Instance details Defined in GHC.Internal.Control.Arrow Methods (>>=) :: ArrowMonad a a0 -> (a0 -> ArrowMonad a b) -> ArrowMonad a b Source (>>) :: ArrowMonad a a0 -> ArrowMonad a b -> ArrowMonad a b Source return :: a0 -> ArrowMonad a a0 Source
Monad (ST s) Source	Since: base-2.1
Instance details Defined in GHC.Internal.Control.Monad.ST.Lazy.Imp Methods (>>=) :: ST s a -> (a -> ST s b) -> ST s b Source (>>) :: ST s a -> ST s b -> ST s b Source return :: a -> ST s a Source
Monad (Either e) Source	Since: base-4.4.0.0
Instance details Defined in GHC.Internal.Data.Either Methods (>>=) :: Either e a -> (a -> Either e b) -> Either e b Source (>>) :: Either e a -> Either e b -> Either e b Source return :: a -> Either e a Source
Monad (Proxy :: Type -> Type) Source	Since: base-4.7.0.0
Instance details Defined in GHC.Internal.Data.Proxy Methods (>>=) :: Proxy a -> (a -> Proxy b) -> Proxy b Source (>>) :: Proxy a -> Proxy b -> Proxy b Source return :: a -> Proxy a Source
Monad (U1 :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods (>>=) :: U1 a -> (a -> U1 b) -> U1 b Source (>>) :: U1 a -> U1 b -> U1 b Source return :: a -> U1 a Source
Monad (ST s) Source	Since: base-2.1
Instance details Defined in GHC.Internal.ST Methods (>>=) :: ST s a -> (a -> ST s b) -> ST s b Source (>>) :: ST s a -> ST s b -> ST s b Source return :: a -> ST s a Source
Monoid a => Monad ((,) a) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Base Methods (>>=) :: (a, a0) -> (a0 -> (a, b)) -> (a, b) Source (>>) :: (a, a0) -> (a, b) -> (a, b) Source return :: a0 -> (a, a0) Source
Monad m => Monad (Kleisli m a) Source	Since: base-4.14.0.0
Instance details Defined in GHC.Internal.Control.Arrow Methods (>>=) :: Kleisli m a a0 -> (a0 -> Kleisli m a b) -> Kleisli m a b Source (>>) :: Kleisli m a a0 -> Kleisli m a b -> Kleisli m a b Source return :: a0 -> Kleisli m a a0 Source
Monad m => Monad (StateT s m) Source	Since: base-4.18.0.0
Instance details Defined in GHC.Internal.Data.Functor.Utils Methods (>>=) :: StateT s m a -> (a -> StateT s m b) -> StateT s m b Source (>>) :: StateT s m a -> StateT s m b -> StateT s m b Source return :: a -> StateT s m a Source
Monad f => Monad (Ap f) Source	Since: base-4.12.0.0
Instance details Defined in GHC.Internal.Data.Monoid Methods (>>=) :: Ap f a -> (a -> Ap f b) -> Ap f b Source (>>) :: Ap f a -> Ap f b -> Ap f b Source return :: a -> Ap f a Source
Monad f => Monad (Alt f) Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Semigroup.Internal Methods (>>=) :: Alt f a -> (a -> Alt f b) -> Alt f b Source (>>) :: Alt f a -> Alt f b -> Alt f b Source return :: a -> Alt f a Source
Monad f => Monad (Rec1 f) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods (>>=) :: Rec1 f a -> (a -> Rec1 f b) -> Rec1 f b Source (>>) :: Rec1 f a -> Rec1 f b -> Rec1 f b Source return :: a -> Rec1 f a Source
(Monoid a, Monoid b) => Monad ((,,) a b) Source	Since: base-4.14.0.0
Instance details Defined in GHC.Internal.Base Methods (>>=) :: (a, b, a0) -> (a0 -> (a, b, b0)) -> (a, b, b0) Source (>>) :: (a, b, a0) -> (a, b, b0) -> (a, b, b0) Source return :: a0 -> (a, b, a0) Source
(Monad f, Monad g) => Monad (Product f g) Source	Since: base-4.9.0.0
Instance details Defined in Data.Functor.Product Methods (>>=) :: Product f g a -> (a -> Product f g b) -> Product f g b Source (>>) :: Product f g a -> Product f g b -> Product f g b Source return :: a -> Product f g a Source
(Monad f, Monad g) => Monad (f :*: g) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods (>>=) :: (f :: g) a -> (a -> (f :: g) b) -> (f :: g) b Source (>>) :: (f :: g) a -> (f :: g) b -> (f :: g) b Source return :: a -> (f :*: g) a Source
(Monoid a, Monoid b, Monoid c) => Monad ((,,,) a b c) Source	Since: base-4.14.0.0
Instance details Defined in GHC.Internal.Base Methods (>>=) :: (a, b, c, a0) -> (a0 -> (a, b, c, b0)) -> (a, b, c, b0) Source (>>) :: (a, b, c, a0) -> (a, b, c, b0) -> (a, b, c, b0) Source return :: a0 -> (a, b, c, a0) Source
Monad ((->) r) Source	Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods (>>=) :: (r -> a) -> (a -> r -> b) -> r -> b Source (>>) :: (r -> a) -> (r -> b) -> r -> b Source return :: a -> r -> a Source
Monad f => Monad (M1 i c f) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods (>>=) :: M1 i c f a -> (a -> M1 i c f b) -> M1 i c f b Source (>>) :: M1 i c f a -> M1 i c f b -> M1 i c f b Source return :: a -> M1 i c f a Source

class Monad m => MonadFail (m :: Type -> Type) where Source

When a value is bound in do-notation, the pattern on the left hand side of <- might not match. In this case, this class provides a function to recover.

A Monad without a MonadFail instance may only be used in conjunction with pattern that always match, such as newtypes, tuples, data types with only a single data constructor, and irrefutable patterns (~pat).

Instances of MonadFail should satisfy the following law: fail s should be a left zero for >>=,

fail s >>= f  =  fail s

If your Monad is also MonadPlus, a popular definition is

fail _ = mzero

fail s should be an action that runs in the monad itself, not an exception (except in instances of MonadIO). In particular, fail should not be implemented in terms of error.

Since: base-4.9.0.0

Methods

fail :: String -> m a Source

Instances

Instances details

MonadFail Q Source
Instance details Defined in GHC.Internal.TH.Syntax Methods fail :: String -> Q a Source
MonadFail P Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadP Methods fail :: String -> P a Source
MonadFail ReadP Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadP Methods fail :: String -> ReadP a Source
MonadFail ReadPrec Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadPrec Methods fail :: String -> ReadPrec a Source
MonadFail IO Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Control.Monad.Fail Methods fail :: String -> IO a Source
MonadFail Maybe Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Control.Monad.Fail Methods fail :: String -> Maybe a Source
MonadFail [] Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Control.Monad.Fail Methods fail :: String -> [a] Source
MonadFail f => MonadFail (Ap f) Source	Since: base-4.12.0.0
Instance details Defined in GHC.Internal.Data.Monoid Methods fail :: String -> Ap f a Source

class (Alternative m, Monad m) => MonadPlus (m :: Type -> Type) where Source

Monads that also support choice and failure.

Minimal complete definition

Nothing

Methods

mzero :: m a Source

The identity of mplus. It should also satisfy the equations

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

The default definition is

mzero = empty

mplus :: m a -> m a -> m a Source

An associative operation. The default definition is

mplus = (<|>)

Instances

Instances details

MonadPlus STM Source	Takes the first non-`retry`ing `STM` action. Since: base-4.3.0.0
Instance details Defined in GHC.Internal.Conc.Sync Methods mzero :: STM a Source mplus :: STM a -> STM a -> STM a Source
MonadPlus P Source	Since: base-2.1
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadP Methods mzero :: P a Source mplus :: P a -> P a -> P a Source
MonadPlus ReadP Source	Since: base-2.1
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadP Methods mzero :: ReadP a Source mplus :: ReadP a -> ReadP a -> ReadP a Source
MonadPlus ReadPrec Source	Since: base-2.1
Instance details Defined in GHC.Internal.Text.ParserCombinators.ReadPrec Methods mzero :: ReadPrec a Source mplus :: ReadPrec a -> ReadPrec a -> ReadPrec a Source
MonadPlus IO Source	Takes the first non-throwing `IO` action's result. `mzero` throws an exception. Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Base Methods mzero :: IO a Source mplus :: IO a -> IO a -> IO a Source
MonadPlus Maybe Source	Picks the leftmost `Just` value, or, alternatively, `Nothing`. Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods mzero :: Maybe a Source mplus :: Maybe a -> Maybe a -> Maybe a Source
MonadPlus [] Source	Combines lists by concatenation, starting from the empty list. Since: base-2.1
Instance details Defined in GHC.Internal.Base Methods mzero :: [a] Source mplus :: [a] -> [a] -> [a] Source
(ArrowApply a, ArrowPlus a) => MonadPlus (ArrowMonad a) Source	Since: base-4.6.0.0
Instance details Defined in GHC.Internal.Control.Arrow Methods mzero :: ArrowMonad a a0 Source mplus :: ArrowMonad a a0 -> ArrowMonad a a0 -> ArrowMonad a a0 Source
MonadPlus (Proxy :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Proxy Methods mzero :: Proxy a Source mplus :: Proxy a -> Proxy a -> Proxy a Source
MonadPlus (U1 :: Type -> Type) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods mzero :: U1 a Source mplus :: U1 a -> U1 a -> U1 a Source
MonadPlus m => MonadPlus (Kleisli m a) Source	Since: base-4.14.0.0
Instance details Defined in GHC.Internal.Control.Arrow Methods mzero :: Kleisli m a a0 Source mplus :: Kleisli m a a0 -> Kleisli m a a0 -> Kleisli m a a0 Source
MonadPlus f => MonadPlus (Ap f) Source	Since: base-4.12.0.0
Instance details Defined in GHC.Internal.Data.Monoid Methods mzero :: Ap f a Source mplus :: Ap f a -> Ap f a -> Ap f a Source
MonadPlus f => MonadPlus (Alt f) Source	Since: base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Semigroup.Internal Methods mzero :: Alt f a Source mplus :: Alt f a -> Alt f a -> Alt f a Source
MonadPlus f => MonadPlus (Rec1 f) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods mzero :: Rec1 f a Source mplus :: Rec1 f a -> Rec1 f a -> Rec1 f a Source
(MonadPlus f, MonadPlus g) => MonadPlus (Product f g) Source	Since: base-4.9.0.0
Instance details Defined in Data.Functor.Product Methods mzero :: Product f g a Source mplus :: Product f g a -> Product f g a -> Product f g a Source
(MonadPlus f, MonadPlus g) => MonadPlus (f :*: g) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods mzero :: (f :: g) a Source mplus :: (f :: g) a -> (f :: g) a -> (f :: g) a Source
MonadPlus f => MonadPlus (M1 i c f) Source	Since: base-4.9.0.0
Instance details Defined in GHC.Internal.Generics Methods mzero :: M1 i c f a Source mplus :: M1 i c f a -> M1 i c f a -> M1 i c f a Source

Functions

Naming conventions

The functions in this module 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:

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

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

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

Examples

Expand

mapM is literally a traverse with a type signature restricted to Monad. Its implementation may be more efficient due to additional power of Monad.

mapM_ :: (Foldable t, Monad m) => (a -> m b) -> t a -> m () Source

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.

mapM_ is just like traverse_, but specialised to monadic actions.

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

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

forM_ is mapM_ with its arguments flipped. For a version that doesn't ignore the results see forM.

forM_ is just like for_, but specialised to monadic actions.

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

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

Examples

Expand

Basic usage:

The first two examples are instances where the input and and output of sequence are isomorphic.

>>> sequence $ Right [1,2,3,4]
[Right 1,Right 2,Right 3,Right 4]

>>> sequence $ [Right 1,Right 2,Right 3,Right 4]
Right [1,2,3,4]

The following examples demonstrate short circuit behavior for sequence.

>>> sequence $ Left [1,2,3,4]
Left [1,2,3,4]

>>> sequence $ [Left 0, Right 1,Right 2,Right 3,Right 4]
Left 0

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

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.

sequence_ is just like sequenceA_, but specialised to monadic actions.

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

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

as >>= f == f =<< as

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

Left-to-right composition of Kleisli arrows.

'(bs >=> cs) a' can be understood as the do expression

do b <- bs a
   cs b

or in terms of (>>=) as

bs a >>= cs

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

Right-to-left composition of Kleisli arrows. (>=>), with the arguments flipped.

Note how this operator resembles function composition (.):

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

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

Repeat an action indefinitely.

Examples

Expand

A common use of forever is to process input from network sockets, Handles, and channels (e.g. MVar and Chan).

For example, here is how we might implement an echo server, using forever both to listen for client connections on a network socket and to echo client input on client connection handles:

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

Note that "forever" isn't necessarily non-terminating. If the action is in a MonadPlus and short-circuits after some number of iterations. then forever actually returns mzero, effectively short-circuiting its caller.

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

void value discards or ignores the result of evaluation, such as the return value of an IO action.

Examples

Expand

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 Source

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

'join bss' can be understood as the do expression

do bs <- bss
   bs

Examples

Expand

>>> join [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
[1,2,3,4,5,6,7,8,9]

>>> join (Just (Just 3))
Just 3

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

atomically :: STM a -> IO a

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

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

we can compose them as

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

to run an STM transaction and the IO action it returns.

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

The sum of a collection of actions using (<|>), generalizing concat.

msum is just like asum, but specialised to MonadPlus.

Examples

Expand

Basic usage, using the MonadPlus instance for Maybe:

>>> msum [Just "Hello", Nothing, Just "World"]
Just "Hello"

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

Direct MonadPlus equivalent of filter.

Examples

Expand

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

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

An example using mfilter with the Maybe monad:

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

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

This generalizes the list-based filter function.

runIdentity (filterM (Identity . p) xs) == filter p xs

Examples

Expand

>>> filterM (\x -> do
      putStrLn ("Keep: " ++ show x ++ "?")
      answer <- getLine
      pure (answer == "y"))
    [1, 2, 3]
Keep: 1?
y
Keep: 2?
n
Keep: 3?
y
[1,3]

>>> filterM (\x -> do
      putStr (show x)
      x' <- readLn
      pure (x == x'))
    [1, 2, 3]
12
22
33
[2,3]

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

The mapAndUnzipM function maps its first argument over a list, returning the result as a pair of lists. This function is mainly used with complicated data structures or a state monad.

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

The zipWithM function generalizes zipWith to arbitrary applicative functors.

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

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 Source

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

Like foldM, but discards the result.

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

replicateM n act performs the action act n times, and then returns the list of results.

replicateM n (pure x) == replicate n x

Examples

Expand

>>> replicateM 3 getLine
hi
heya
hiya
["hi","heya","hiya"]

>>> import Control.Monad.State
>>> runState (replicateM 3 $ state $ \s -> (s, s + 1)) 1
([1,2,3],4)

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

Like replicateM, but discards the result.

Examples

Expand

>>> replicateM_ 3 (putStr "a")
aaa

Conditional execution of monadic expressions

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

Conditional failure of Alternative computations. Defined by

guard True  = pure ()
guard False = empty

Examples

Expand

Common uses of guard include conditionally signalling an error in an error monad and conditionally rejecting the current choice in an Alternative-based parser.

As an example of signalling an error in the error monad Maybe, consider a safe division function safeDiv x y that returns Nothing when the denominator y is zero and Just (x `div` y) otherwise. For example:

>>> safeDiv 4 0
Nothing

>>> safeDiv 4 2
Just 2

A definition of safeDiv using guards, but not guard:

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

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

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

when :: Applicative f => Bool -> f () -> f () Source

Conditional execution of Applicative expressions. For example,

Examples

Expand

when debug (putStrLn "Debugging")

will output the string Debugging if the Boolean value debug is True, and otherwise do nothing.

>>> putStr "pi:" >> when False (print 3.14159)
pi:

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

The reverse of when.

Examples

Expand

>>> do x <- getLine
       unless (x == "hi") (putStrLn "hi!")
comingupwithexamplesisdifficult
hi!

>>> unless (pi > exp 1) Nothing
Just ()

Monadic lifting operators

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

Promote a function to a monad. This is equivalent to fmap but specialised to Monads.

liftM2 :: Monad m => (a1 -> a2 -> r) -> m a1 -> m a2 -> m r Source

Promote a function to a monad, scanning the monadic arguments from left to right.

Examples

Expand

>>> liftM2 (+) [0,1] [0,2]
[0,2,1,3]

>>> liftM2 (+) (Just 1) Nothing
Nothing

>>> liftM2 (+) (+ 3) (* 2) 5
18

liftM3 :: Monad m => (a1 -> a2 -> a3 -> r) -> m a1 -> m a2 -> m a3 -> m r Source

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 Source

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 Source

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 Source

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

liftM<n> f x1 x2 ... xn

Examples

Expand

>>> pure (\x y z -> x + y * z) `ap` Just 1 `ap` Just 5 `ap` Just 10
Just 51

Strict monadic functions

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

Strict version of <$>.

Since: base-4.8.0.0

© The University of Glasgow and others
Licensed under a BSD-style license (see top of the page).
https://downloads.haskell.org/~ghc/9.12.1/docs/libraries/base-4.21.0.0-8e62/Control-Monad.html

Control.Monad

Contents

Description

Functor and monad classes

Minimal complete definition

Methods

Examples

Examples

Instances

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods

Methods