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:

• For this reference manual, "A tour of the Haskell Prelude", by Bernie Pope and Arjan van IJzendoorn was used as an example.
• The example at fail, summing lists of two elements, was written by Yitzchak Gale.

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: ```(>>), (=<<) ```

 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: ```liftM2, liftM3, liftM4, liftM5 ```

 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  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], , [4, 5]] [3, 9] ``` see also: ```error, ioError, userError ```

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

 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: ```map, liftM ```

 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: ```foldl, foldr ```

 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: ```mzero, when, unless ```

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

 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: ```fmap, liftM2, liftM3, liftM4, liftM5 ```

 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: ```liftM, liftM3, liftM4, liftM5, fmap ```

 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: ```liftM, liftM2, liftM4, liftM5, fmap ```

 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: ```liftM, liftM2, liftM3, liftM5, fmap ```

 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: ```liftM, liftM2, liftM3, liftM4, fmap ```

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

 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: ```map, mapM_, sequence ```

 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: ```map, mapM, sequence ```

 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: ```mzero, 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: ```mplus, mzero, foldr ```

 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`   ``` see also: ```mplus, msum ```

 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]  > getLine >>= \x -> return (x ++ x) >>= print haha "hahahaha" > do {x <- getLine; y <- return (x ++ x); print y} qwerty "qwertyqwerty" ``` see also: ```(>>=) ```

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

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

 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: ```when, guard ```

 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: ```unless, guard ```

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

 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: ```zipWithM, zipWith ```
Home
Statistics from 2005-06-05 until 2009-01-19