Home

A tour of the Haskell Monad functions

This reference guide describes monad and functor functions in the modules Prelude and Control.Monad. It describes functions of The Haskell 98 Library Report only; example code is limited to Haskell 2010. The lines in the "Usage" sections, starting with "> " are commands/expressions typed in a Hugs 98 shell. For most of the examples, it is necessary to give the command :l Control.Monad first; in some cases, source code must be entered in a file and the file must be loaded.
If you have any suggestions for improvement, send me an e-mail (remove "REMOVE-THIS." from the address.)

Acknowledgements:


Last updated:
2013-09-01

Copyright 2005 - 2013, Henk-Jan van Tuyl
No part of this text may be sold, either seperately or as part of a product.
(=<<)(>>)(>>=)apfailfilterMfmapfoldMguardjoinliftMliftM2liftM3liftM4liftM5mapAndUnzipMmapMmapM_mplusmsummzeroreturnsequencesequence_unlesswhenzipWithMzipWithM_


Some books on Haskell:




(=<<)
module: Prelude
type: (=<<) :: Monad m => (a -> m b) -> m a -> m b
description: This is the "reverse binder" function; the expression
  f =<< m
takes the contents of monad m and passes it to function f as a parameter. It may be useful when used as a parameter of a higher order function, or one can use it as a more readable way of coding, in some cases.
definition:
infixr 1  =<<
f =<< x  =  x >>= f
      
usage:
> replicate 2 =<< [1, 2, 3]
[1,1,2,2,3,3]
      
see also:
(>>=)(>>)
      


(>>)
module: Prelude
type: (>>) :: m a -> m b -> m b
description: This operator is essentially the same as (>>=), but does not pass the contents of the monad to the function specified as second parameter. It can be used to define the order in which actions take place.
definition:
infixl 1  >>
m >> k  =  m >>= \_ -> k
      
usage:
> putStrLn "asd" >> putStrLn "qwerty"
asd
qwerty
      
see also:
(>>=)(=<<)
      


(>>=)
module: Prelude
type: (>>=) :: m a -> (a -> m b) -> m b
description: This is the "bind" function; the expression
  m >>= f
takes the contents of monad m and passes it to function f as a parameter. >>= is one of the two basic operators of the Monad class (the other is return). Any instantiation of >>= and return must obey the following laws:
  return a >>= k                 = k a 	
  m        >>= return            = m 	
  m        >>= (\x -> k x >>= h) = (m >>= k) >>= h	
Sometimes a fourth law is mentioned, but not everybody agrees with this one:
  xs       >>= return . f        = fmap f xs	
definition:
infixl 1  >>=

instance Monad Maybe where
  (Just x) >>= k   =  k x
  Nothing  >>= k   =  Nothing

instance Monad IO where
  (>>=)  = ... -- No Haskell representation possible.

instance  Monad []  where
  m >>= k          = concat (map k m)
      
usage:
> Just 3 >>= Just
Just 3

> Just 3 >>= return
Just 3

> getLine >>= print . tail
nice
"ice"
      
see also:
(>>)(=<<)
      


ap
module: Control.Monad
type: ap :: (Monad m) => m (a -> b) -> m a -> m b
description: ap applies a function inside a monad to a value inside a monad of the same type. A call to liftMn can often be replaced by one or more calls to ap:
  return f `ap` x1 `ap` ... `ap` xn
is the same as:
  liftMn f x1 x2 ... xn
definition:
ap = liftM2 ($)
      
usage:
Apply a list of functions to a list of values:
> [(+ 1), (+ 2)] `ap` [1, 2, 3]
[2, 3, 4, 3, 4, 5] 

Apply a function in the Maybe monad to a value 
in the Maybe monad:
> Just (+ 1) `ap` Just 1
Just 2

Apply a function, with two parameters, in the 
Maybe monad, to two values in the Maybe monad:
> Just (*) `ap` (Just 2) `ap` (Just 3)
Just 6 

> return cos `ap` Just pi
Just (-1.0)
      
see also:
liftM2liftM3liftM4liftM5
      


fail
module: Prelude
type: fail :: String -> m a
description: fail is to be called in case a certain condition is not met. When using the IO () version of fail, the program is interrupted; in other monads, the effect is less drastic; the list version, for example, returns an empty list.
definition:
class  Monad m  where
  fail s = error s

instance  Monad Maybe  where
  fail s = Nothing

instance  Monad IO  where
  fail s = ioError (userError s)

instance  Monad []  where
  fail s = []
      
usage:
> fail "Cannot do that" :: Maybe Int
Nothing  

> fail "Cannot do that" :: [Int]
[]

> fail "Cannot do that" :: IO ()

Program error: user error (Cannot do that)

> if 'a' == 'b' then [333] else fail "'a' is not 'b'"
[] 

-- Begin source code --
{-
   Read a list of sublists, and return a list containing the sums
   of only those sublists with exactly two elements, while
   ignoring the rest of the sublists.
-}

f :: Num a => [[a]] -> [a]
f xs = 
  do
   [x, y] <- xs
   return (x + y)

-- End source code --

> f [[1, 2], [3], [4, 5]]
[3, 9]
      
see also:
error, ioError, userError
      


filterM
module: Control.Monad
type: filterM :: Monad m => (a -> m Bool) -> [a] -> m [a]
description: filterM p xs filters out all elements of xs that do not fulfill the predicate p, where p is a function that returns a value of type Monad m => m Bool; the result is a list inside a monad of the same type.
definition:
filterM p []       = return []
filterM p (x : xs) = 
  do 
    b  <- p x
    ys <- filterM p xs
    return (if b then (x : ys) else ys)
      
usage:
> filterM (\x -> Just (x > 0)) [2, 1, 0, -1] 
Just [2, 1] 

> filterM (\x -> [x > 0]) [2, 1, 0, -1]
[[2, 1]] 
      
see also:
filter
      


fmap
module: Prelude
type: fmap :: Functor f => (a -> b) -> f a -> f b
description: fmap f x lets function f operate on x, even though x has a different type then f was designed for. fmap is defined for the types Maybe, IO and [] in Prelude. In case of lists, fmap behaves exactly like map and liftM; in case of the Maybe monad, fmap behaves like liftM. Every instance of fmap should satisfy the following laws:
fmap id      = id
fmap (f . g) = fmap f . fmap g
definition:
In module Control.Monad:
instance Functor Maybe where
  fmap f Nothing    =  Nothing
  fmap f (Just x)   =  Just (f x)

instance Functor IO where
  fmap f x          =  x >>= (return . f)

instance Functor [] where
  fmap = map

In module Data.Array:
instance (Ix a) => Functor (Array a) where
  fmap fn (MkArray b f) =  MkArray b (fn . f) 

In modules Control.Monad.ST.Lazy and Control.Monad.ST:
instance Functor (ST s) where
  fmap = liftM

Other modules with definitions exist.
      
usage:
Apply "negate" to a value in a Maybe monad:
> fmap negate (Just 1)
Just (-1) 

Take the square root of all elements in a list:
> fmap sqrt [1.0, 4.0, 9.0]
[1.0, 2.0, 3.0] 

Increment a value in a Maybe monad:
> let inc = fmap (+ 1) in inc (Just 2)
Just 3 

Increment a value in a Maybe monad, using liftM:
> let inc = liftM (+ 1) in inc (Just 2)
Just 3 

Increment all elements in a list:
> let inc = fmap (+ 1) in inc [2, 3]
[3, 4] 

Convert input to uppercase:
> putStr =<< fmap (fmap toUpper) getLine
asdf
ASDF
      
see also:
mapliftM
      


foldM
module: Control.Monad
type: foldM :: (Monad m) => (a -> b -> m a) -> a -> [b] -> m a
description: foldM is the monadic version of foldl, whereas foldl takes a function of type
  a -> b -> a
foldM takes a function of type:
  (Monad m) => (a -> b -> m a) 
In different words, it takes a function with two non-monadic parameters, resulting in a monadic value and folds a list with it. The expression:
  foldM f a [x1, x2, ..., xn]
is equal to:
  f (... f (f (f a x1) x2 ...) xn
The equivalent of foldr can be achieved by:
  foldrM f a xs = foldM f a (reverse xs)

definition:
foldM f a []       =  return a
foldM f a (x : xs) =  f a x >>= \ y -> foldM f y xs
      
usage:
-- Begin source code --
{-
   Create a function that divides by a list of numbers,
   similar to "sum" and "product"
-}
import Data.Maybe
import Control.Monad

-- A function that takes care of the "divide by zero" problem
(./.) :: Fractional a => a -> a -> Maybe a
x ./. 0 = Nothing
x ./. y = Just (x / y)

divide :: Fractional a => a -> [a] -> Maybe a
divide x ys = foldM (./.) x ys

-- End source code --


> divide 1 [2, 3]
Just 0.166666666666667
      
see also:
foldlfoldr
      


guard
module: Control.Monad
type: guard :: MonadPlus m => Bool -> m ()
description: guard p returns () if p is True, otherwise mzero; it can be used as follows:
myDiv :: Fractional a => a -> a -> Maybe a
myDiv x y = 
  do
    guard (y /= 0)
    return (x / y)
Or:
myDiv :: Fractional a => a -> a -> Maybe a
myDiv x y = guard (y /= 0) >> return (x / y)
When y == 0, The function returns Nothing, otherwise Just (x / y).
definition:
guard p = if p then return () else mzero
      
usage:
> :l Monad
> guard True >> Just 3
Just 3
> guard False >> Just 3
Nothing

> guard True >> [1, 2, 3]
[1,2,3]
> guard False >> [1, 2, 3]
[]

> myDiv 1 0
Nothing
> myDiv 1 1
Just 1.0

> :m +Control.Monad.Error
> guard True >> print "OK"
"OK"

> guard False >> print "OK"

Program error: user error (mzero)

      
see also:
mzerowhenunless
      


join
module: Control.Monad
type: join :: (Monad m) => m (m a) -> m a
description: join removes one layer of nesting of a monadic value: join (m (m x)) changes m (m x) to m x
definition:
join x  =  x >>= id
      
usage:
> join (Just (Just 1))
Just 1 
      
see also:

      


liftM
module: Control.Monad
type: liftM :: (Monad m) => (a -> b) -> (m a -> m b)
description: liftM f m lets a non-monadic function f operate on the contents of monad m
definition:
liftM f  =  \a -> do { a' <- a; return (f a') }
      
usage:
> liftM sin (Just 0)
Just 0.0

> liftM (replicate 10) ['a']
["aaaaaaaaaa"]
      
see also:
fmapliftM2liftM3liftM4liftM5
      


liftM2
module: Control.Monad
type: liftM2 :: (Monad m) => (a -> b -> c) -> (m a -> m b -> m c)
description: liftM2 f m1 m2 lets a non-monadic function f operate on the contents of monads m1 and m2
definition:
liftM2 f  =  \a b -> do { a' <- a; b' <- b; return (f a' b') }
      
usage:
-- Create the new operator ?- to subtract
-- numbers encapsulated in monads:
> let (?-) = liftM2 (-) in Just 3 ?- (Just 2)
Just 1 

-- Create the new operator ?* to multiply
-- numbers encapsulated in monads,
-- multiply with "Nothing":
> let (?*) = liftM2 (*) in Just 3 ?* Nothing
Nothing 
      
see also:
liftMliftM3liftM4liftM5fmap
      


liftM3
module: Control.Monad
type: liftM3 :: (Monad m) => (a -> b -> c -> d) -> (m a -> m b -> m c -> m d)
description: liftM3 f m1 m2 m3 lets a non-monadic function f operate on the contents of monads m1, m2 and m3
definition:
liftM3 f  =  \a b c -> do { a' <- a
                          ; b' <- b
                          ; c' <- c
                          ; return (f a' b' c')
                          }
      
usage:
> liftM3 flip (Just elem) (Just [1..10]) (Just 5)
Just True
      
see also:
liftMliftM2liftM4liftM5fmap
      


liftM4
module: Control.Monad
type: liftM4 :: (Monad m) => (a -> b -> c -> d -> e) -> (m a -> m b -> m c -> m d -> m e)
description: liftM4 f m1 m2 m3 m4 lets a non-monadic function f operate on the contents of monads m1, m2, m3 and m4
definition:
liftM4 f  =  \a b c d -> do { a' <- a
                            ; b' <- b
                            ; c' <- c
                            ; d' <- d
                            ; return (f a' b' c' d')
                            }
      
usage:
> let sum4 w x y z = w + x + y + z in liftM4 sum4 (Just 0) (Just 1) (Just 2) (Just 3)
Just 6
      
see also:
liftMliftM2liftM3liftM5fmap
      


liftM5
module: Control.Monad
type: liftM5 :: (Monad m) => (a -> b -> c -> d -> e -> f) -> (m a -> m b -> m c -> m d -> m e -> m f)
description: liftM5 f m1 m2 m3 m4 m5 lets a non-monadic function f operate on the contents of monads m1, m2, m3, m4 and m5
definition:
liftM5 f  =  \a b c d e -> do { a' <- a
                              ; b' <- b
                              ; c' <- c
                              ; d' <- d
                              ; e' <- e
                              ; return (f a' b' c' d' e')
                              }
      
usage:
> let sum5 v w x y z = v + w + x + y + z in liftM5 sum5 (Just 0) (Just 1) (Just 2) (Just 3) (Just 4)
Just 10
      
see also:
liftMliftM2liftM3liftM4fmap
      


mapAndUnzipM
module: Control.Monad
type: mapAndUnzipM :: (Monad m) => (a -> m (b,c)) -> [a] -> m ([b], [c])
description: mapAndUnzipM mf xs takes a monadic function mf (having type (Monad m) => (a -> m (b,c))) and applies it to each element in list xs; the resulting list of two-tuples is then unzipped, the final result is a two-tuple of lists inside a monad.
definition:
mapAndUnzipM f xs  =  sequence (map f xs) >>= return . unzip
      
usage:
> map (divMod 3) [1, 2, 3, 4, 5]
[(3,0),(1,1),(1,0),(0,3),(0,3)]

> unzip (map (divMod 3) [1, 2, 3, 4, 5])
([3,1,1,0,0],[0,1,0,3,3]) 

> mapAndUnzipM (Just . divMod 3) [1, 2, 3, 4, 5]
Just ([3,1,1,0,0],[0,1,0,3,3])
      
see also:
map, unzip
      


mapM
module: Prelude
type: mapM :: Monad m => (a -> m b) -> [a] -> m [b]
description: mapM mf xs takes a monadic function mf (having type Monad m => (a -> m b)) and applies it to each element in list xs; the result is a list inside a monad.
The difference between mapM and mapM_ is, that mapM returns a list of the results, while mapM_ returns an empty result.
definition:
mapM f as  =  sequence (map f as)
      
usage:
> mapM Just [0, 1, 2]
Just [0,1,2]

> mapM print [0, 1, 2]
0
1
2

> mapM (\x -> [x]) [0, 1, 2]
[[0,1,2]]
      
see also:
mapmapM_sequence
      


mapM_
module: Prelude
type: mapM_ :: Monad m => (a -> m b) -> [a] -> m ()
description: mapM_ mf xs takes a monadic function mf (having type Monad m => (a -> m b)) and applies it to each element in list xs; the result of each action is not stored.
The difference between mapM and mapM_ is, that mapM returns a list of the results, while mapM_ returns an empty result.
definition:
mapM_ f as  =  sequence_ (map f as)
      
usage:
> mapM_ Just [0, 1, 2]
Just ()

> mapM_ print [0, 1, 2]
0
1
2
 
> mapM_ (\x -> [x]) [0, 1, 2]
[()]
      
see also:
mapmapMsequence
      


mplus
module: Control.Monad
type: mplus :: MonadPlus a => a b -> a b -> a b
description: The method mplus is the plus of the MonadPlus class. Any definition of mplus must obey the following laws:
  m `mplus` mzero = m	
  mzero `mplus` m = m	
definition:
class  Monad m => MonadPlus m  where
  mplus  :: m a -> m a -> m a

instance  MonadPlus Maybe  where
  Nothing `mplus` ys    = ys
  xs      `mplus` ys    = xs

instance  MonadPlus []  where
  mplus = (++)

-- Other instances can be found in other modules
      
usage:
> "a" `mplus` "b"
"ab"

> Just "a" `mplus` Just "b"
Just "a"

> Nothing `mplus` Just "b"
Just "b"

> undefined `mplus` Just 2

Program error: Prelude.undefined

> Just 1 `mplus` undefined
Just 1
      
see also:
mzeromsum
      


msum
module: Control.Monad
type: msum :: MonadPlus m => [m a] -> m a
description: msum is the monadic version of sum, it sums the elements of a list with mplus, using mzero as a starting value.
definition:
msum xs = foldr mplus mzero xs
      
usage:
> msum ["a", "b", "c"]
"abc"

> msum [Just "a", Just "b", Just "c"]
Just "a"

> msum [Nothing, Just "b", Just "c"]
Just "b"
      
see also:
mplusmzerofoldr
      


mzero
module: Control.Monad
type: mzero :: MonadPlus m => m a
description: mzero is the zero of the MonadPlus class. Any definition of mzero must obey the following laws:
  m >>= \x -> mzero = mzero
  mzero >>= m = mzero
definition:
class  Monad m => MonadPlus m  where
  mzero  :: m a

instance  MonadPlus Maybe  where
  mzero  = Nothing

instance  MonadPlus []  where
  mzero  = []

-- Other instances may be found in other modules
      
usage:
> mzero :: [Int]
[]

> mzero :: Maybe Int
Nothing

> (mzero :: Maybe Int) >>= \x -> Just (x * x)
Nothing

> Just 1 `mplus` mzero
Just 1

> mzero `mplus` Just 2
Just 2

> mzero `mplus` [1]
[1]
      
see also:
mplusmsum
      


return
module: Prelude
type: return :: Monad m => a -> m a
description: return is one of the two basic operators of the Monad class (the other is >>= (called "bind")). One could say, it converts a value to a monad containing this value; the type of this monad depends on the type of the expression.
Any instantiation of >>= and return must obey the laws mentioned at the desciption of (>>=)
definition:
class  Monad m  where
  return :: a -> m a

instance  Monad Maybe  where
  return  =  Just

instance  Monad IO  where
  return  =  ...  -- This cannot be expressed in Haskell

instance  Monad []  where
  return x  =  [x]
      
usage:
> (return 3) :: Maybe Int
Just 3

> (return 3) :: [Int]
[3]

> getLine >>= \x -> return (x ++ x) >>= print
haha
"hahahaha"

> do {x <- getLine; y <- return (x ++ x); print y}
qwerty
"qwertyqwerty"
      
see also:
(>>=)
      


sequence
module: Prelude
type: sequence :: Monad m => [m a] -> m [a]
description: sequence xs evaluates all monadic values in the list xs, from left to right, and returns a list of the "contents" of these monads, placing this list in a monad of the same type. Note, that "evaluating" can be interpreted as "performing an action", for example in the case of print.
The difference between sequence and sequence_ is that sequence returns a list of the results, while sequence_ returns an empty result.
definition:
sequence = foldr mcons (return [])
  where
    mcons p q = p >>= \x -> q >>= \y -> return (x : y)
      
usage:
> sequence [print 1, print 2, print 3]
1
2
3

> sequence [print 1, print 2, print 3] >>= print
1
2
3
[(),(),()]

> sequence [Just 1, Just 2, Just 3]
Just [1,2,3]
      
see also:
sequence_
      


sequence_
module: Prelude
type: sequence_ :: Monad m => [m a] -> m ()
description: sequence_ xs evaluates all monadic values in the list xs, from left to right, and returns () inside a monad. Note, that "evaluating" can be read as "performing an action".
The difference between sequence and sequence_ is that sequence returns a list of the results, while sequence_ returns an empty result.
definition:
sequence_  =  foldr (>>) (return ())
      
usage:
> sequence_ [print 1, print 2, print 3]
1
2
3

> sequence_ [print 1, print 2, print 3] >>= print
1
2
3
()

> sequence_ [Just 1, Just 2, Just 3]
Just ()
      
see also:
sequence
      


unless
module: Control.Monad
type: unless :: (Monad m) => Bool -> m () -> m ()
description: unless p me executes monadic expression me when p is False.
definition:
unless p s = when (not p) s
      
usage:
> unless (0 == 1) (print "OK")
"OK"

> unless (1 == 1) (print "This is the end of logic")

> let simulation = True in unless simulation (putStrLn "Launching Ariane 5 now")

      
see also:
whenguard
      


when
module: Control.Monad
type: when :: (Monad m) => Bool -> m () -> m ()
description: when p me executes monadic expression me when p is True.
definition:
when p s = if p then s else return ()
      
usage:
> when (1 == 1) (print "OK")
"OK"

> when (0 == 1) (print "This is the end of logic")

      
see also:
unlessguard
      


zipWithM
module: Control.Monad
type: zipWithM :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m [c]
description: zipWithM is the monadic version of zipWith; zipWithM me xs ys uses monadic expression me to zip the lists xs and ys.
definition:
zipWithM f xs ys = sequence (zipWith f xs ys)
      
usage:
> zipWithM (\x y -> Just (x + y)) [1, 2, 3] [4, 5, 6]
Just [5,7,9]

> zipWithM (\x y -> print (x + y)) [1, 2, 3] [4, 5, 6]
5
7
9

> zipWithM (\x y -> print (x + y)) [1, 2, 3] [4, 5, 6] >>= print
5
7
9
[(),(),()]
      
see also:
zipWithM_zipWith
      


zipWithM_
module: Control.Monad
type: zipWithM_ :: (Monad m) => (a -> b -> m c) -> [a] -> [b] -> m ()
description: zipWithM_ is the monadic version of zipWith; zipWithM_ me xs ys uses monadic expression me to zip the lists xs and ys; it returns m (), where m is a monad of the same type as the result of me.
definition:
zipWithM_ f xs ys  =  sequence_ (zipWith f xs ys)
      
usage:
> zipWithM_ (\x y -> Just (x + y)) [1, 2, 3] [4, 5, 6]
Just ()

> zipWithM_ (\x y -> print (x + y)) [1, 2, 3] [4, 5, 6]
5
7
9

> zipWithM_ (\x y -> print (x + y)) [1, 2, 3] [4, 5, 6] >>= print
5
7
9
()
      
see also:
zipWithMzipWith
      
Home

Valid HTML 4.01!

Valid CSS!


Statistics from 2005-06-05 until 2009-01-19