Binary bind.

Strict ap

Strict variant of <&>.

Monadic guard.

Monadic if-then-else.

ifNotM mc = ifM (not $ mc)

Lazy monadic conjunction.

Lazy monadic disjunction.

Lazy monadic disjunction with Either truth values. Returns the last error message if all fail.

Lazy monadic disjunction with accumulation of errors in a monoid. Errors are discarded if we succeed.

Generalized version of traverse_ :: Applicative m => (a -> m ()) -> [a] -> m () Executes effects and collects results in left-to-right order. Works best with left-associative monoids.

Note that there is an alternative

mapM' f t = foldr mappend mempty $ mapM f t

that collects results in right-to-left order (effects still left-to-right). It might be preferable for right associative monoids.

Generalized version of for_ :: Applicative m => [a] -> (a -> m ()) -> m ()

Variant of mapM which gets compiled to good code, assuming that we're mapping over an actual runtime list and don't intend for list fusion to fire.

Variant of mapM_ which gets compiled to good code, assuming that we're mapping over an actual runtime list and don't intend for list fusion to fire.

Spine-strict concatenation of lists in a monad.

Perform a left-to-right indexed monadic traversal of a list.

imapM_ is optimized for mapping over actual runtime lists when we don't intend for list fusion to fire. Users are encouraged to check the resulting core.

A flipped variant of imapM_ that makes it easier to write multi-line loop bodies.

The same caveats for list fusion apply, see imapM_ for details.

Performing an action for an inclusive range of Int-s, counting up by one.

A monadic version of mapMaybe :: (a -> Maybe b) -> [a] -> [b].

A version of mapMaybeM with a computation for the input list.

The for version of mapMaybeM.

The for version of mapMaybeMM.

A monadic version of dropWhile :: (a -> Bool) -> [a] -> [a].

A monadic version of dropWhileEnd :: (a -> Bool) -> [a] -> m [a]. Effects happen starting at the end of the list until p becomes false.

A "monadic" version of @partition :: (a -> Bool) -> [a] -> ([a],[a])

Translates Maybe to MonadPlus.

Generalises the catMaybes function from lists to an arbitrary MonadPlus.

Branch over elements of a monadic Foldable data structure.

Finally for the MonadError class. Errors in the finally part take precedence over prior errors.

A variant of finally for MonadError.

WARNING: This function is NOT async-exception safe, and should only be used for pure implementations of MonadError.

Try a computation, return Nothing if an error occurs.

Run a command, catch the exception and return it.

Like guard, but raise given error when condition fails.

Handle errors thrown in ExceptT.

Bracket without failure. Typically used to preserve state.

WARNING: Despite the name, this function is NOT exception safe. Users should use bracket_ instead.

Restore state after computation.

Output a single value.

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

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

atomically :: STM a -> IO a

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

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

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

Examples

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

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

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

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

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

Strict version of <$>.

Since: base-4.8.0.0

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

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

This generalizes the list-based filter function.

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

Examples

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

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

The zipWithM function generalizes zipWith to arbitrary applicative functors.

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

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.

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

msum is just like asum, but specialised to MonadPlus.

Examples

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

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

Examples

>>> void Nothing
Nothing

>>> void (Just 3)
Just ()

>>> void (Left 8675309)
Left 8675309

>>> void (Right 8675309)
Right ()

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

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

>>> mapM print [1,2]
1
2
[(),()]

>>> void $ mapM print [1,2]
1
2

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

Lift a binary function to actions.

Some functors support an implementation of liftA2 that is more efficient than the default one. In particular, if fmap is an expensive operation, it is likely better to use liftA2 than to fmap over the structure and then use <*>.

This became a typeclass method in 4.10.0.0. Prior to that, it was a function defined in terms of <*> and fmap.

Example

>>> liftA2 (,) (Just 3) (Just 5)
Just (3,5)

>>> liftA2 (+) [1, 2, 3] [4, 5, 6]
[5,6,7,6,7,8,7,8,9]

Monads that also support choice and failure.

The class of monad transformers. For any monad m, the result t m should also be a monad, and lift should be a monad transformation from m to t m, i.e. it should satisfy the following laws:

• lift . return = return

• lift (m >>= f) = lift m >>= (lift . f)

Since 0.6.0.0 and for GHC 8.6 and later, the requirement that t m be a Monad is enforced by the implication constraint forall m. Monad m => Monad (t m) enabled by the QuantifiedConstraints extension.

Ambiguity error with GHC 9.0 to 9.2.2

(MonadTrans t, forall m. Monad m => Monad (t m)) => ...

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

>>> show <$> Nothing
Nothing

>>> show <$> Just 3
Just "3"

>>> show <$> Left 17
Left 17

>>> show <$> Right 17
Right "17"

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

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

Sequential application.

A few functors support an implementation of <*> that is more efficient than the default one.

Example

>>> data MyState = MyState {arg1 :: Foo, arg2 :: Bar, arg3 :: Baz}

>>> produceFoo :: Applicative f => f Foo
>>> produceBar :: Applicative f => f Bar
>>> produceBaz :: Applicative f => f Baz

>>> mkState :: Applicative f => f MyState
>>> mkState = MyState <$> produceFoo <*> produceBar <*> produceBaz

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

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

MonadError analogue to the try function.

MonadError analogue to the withExceptT function. Modify the value (but not the type) of an error. The type is fixed because of the functional dependency m -> e. If you need to change the type of e use mapError or modifyError.