Data.Traversable

Class of data structures that can be traversed from left to right, performing an action on each element.

The Traversable class

class (Functor t, Foldable t) => Traversable t where

Functors representing data structures that can be traversed from left to right, performing an action on each element.

A more detailed description can be found in the overview section of Data.Traversable.

Minimal complete definition

traverse | sequenceA

Methods

traverse :: Applicative f => (a -> f b) -> t a -> f (t b)

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

Examples

Basic usage:

In the first two examples we show each evaluated action mapping to the output structure.

>>> traverse Just [1,2,3,4]
Just [1,2,3,4]

>>> traverse id [Right 1, Right 2, Right 3, Right 4]
Right [1,2,3,4]

In the next examples, we show that Nothing and Left values short circuit the created structure.

>>> traverse (const Nothing) [1,2,3,4]
Nothing

>>> traverse (\x -> if odd x then Just x else Nothing)  [1,2,3,4]
Nothing

>>> traverse id [Right 1, Right 2, Right 3, Right 4, Left 0]
Left 0

sequenceA :: Applicative f => t (f a) -> f (t a)

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

Examples

Basic usage:

For the first two examples we show sequenceA fully evaluating a a structure and collecting the results.

>>> sequenceA [Just 1, Just 2, Just 3]
Just [1,2,3]

>>> sequenceA [Right 1, Right 2, Right 3]
Right [1,2,3]

The next two example show Nothing and Just will short circuit the resulting structure if present in the input. For more context, check the Traversable instances for Either and Maybe.

>>> sequenceA [Just 1, Just 2, Just 3, Nothing]
Nothing

>>> sequenceA [Right 1, Right 2, Right 3, Left 4]
Left 4

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

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

Examples

mapM is traverse for Monad, and the following example shows how mapM can apply an IO action to a List to produce a structured result.

Basic usage:

>>> import System.IO
>>> mapM (openTempFile ".") ["t1", "t2"]
[("./t169980-3",{handle: ./t169980-3}),("./t269980-4",{handle: ./t269980-4})]

sequence :: Monad m => t (m a) -> m (t a)

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

Examples

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

Instances

Traversable []

Since: base-2.1

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> [a] -> f [b]

sequenceA :: Applicative f => [f a] -> f [a]

mapM :: Monad m => (a -> m b) -> [a] -> m [b]

sequence :: Monad m => [m a] -> m [a]

Traversable Maybe

Since: base-2.1

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Maybe a -> f (Maybe b)

sequenceA :: Applicative f => Maybe (f a) -> f (Maybe a)

mapM :: Monad m => (a -> m b) -> Maybe a -> m (Maybe b)

sequence :: Monad m => Maybe (m a) -> m (Maybe a)

Traversable Par1

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Par1 a -> f (Par1 b)

sequenceA :: Applicative f => Par1 (f a) -> f (Par1 a)

mapM :: Monad m => (a -> m b) -> Par1 a -> m (Par1 b)

sequence :: Monad m => Par1 (m a) -> m (Par1 a)

Traversable Solo

Since: base-4.15

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Solo a -> f (Solo b)

sequenceA :: Applicative f => Solo (f a) -> f (Solo a)

mapM :: Monad m => (a -> m b) -> Solo a -> m (Solo b)

sequence :: Monad m => Solo (m a) -> m (Solo a)

Traversable NonEmpty

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> NonEmpty a -> f (NonEmpty b)

sequenceA :: Applicative f => NonEmpty (f a) -> f (NonEmpty a)

mapM :: Monad m => (a -> m b) -> NonEmpty a -> m (NonEmpty b)

sequence :: Monad m => NonEmpty (m a) -> m (NonEmpty a)

Traversable Down

Since: base-4.12.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Down a -> f (Down b)

sequenceA :: Applicative f => Down (f a) -> f (Down a)

mapM :: Monad m => (a -> m b) -> Down a -> m (Down b)

sequence :: Monad m => Down (m a) -> m (Down a)

Traversable Product

Since: base-4.8.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Product a -> f (Product b)

sequenceA :: Applicative f => Product (f a) -> f (Product a)

mapM :: Monad m => (a -> m b) -> Product a -> m (Product b)

sequence :: Monad m => Product (m a) -> m (Product a)

Traversable Sum

Since: base-4.8.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Sum a -> f (Sum b)

sequenceA :: Applicative f => Sum (f a) -> f (Sum a)

mapM :: Monad m => (a -> m b) -> Sum a -> m (Sum b)

sequence :: Monad m => Sum (m a) -> m (Sum a)

Traversable Dual

Since: base-4.8.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Dual a -> f (Dual b)

sequenceA :: Applicative f => Dual (f a) -> f (Dual a)

mapM :: Monad m => (a -> m b) -> Dual a -> m (Dual b)

sequence :: Monad m => Dual (m a) -> m (Dual a)

Traversable Last

Since: base-4.8.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Last a -> f (Last b)

sequenceA :: Applicative f => Last (f a) -> f (Last a)

mapM :: Monad m => (a -> m b) -> Last a -> m (Last b)

sequence :: Monad m => Last (m a) -> m (Last a)

Traversable First

Since: base-4.8.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> First a -> f (First b)

sequenceA :: Applicative f => First (f a) -> f (First a)

mapM :: Monad m => (a -> m b) -> First a -> m (First b)

sequence :: Monad m => First (m a) -> m (First a)

Traversable Identity

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Identity a -> f (Identity b)

sequenceA :: Applicative f => Identity (f a) -> f (Identity a)

mapM :: Monad m => (a -> m b) -> Identity a -> m (Identity b)

sequence :: Monad m => Identity (m a) -> m (Identity a)

Traversable ZipList

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> ZipList a -> f (ZipList b)

sequenceA :: Applicative f => ZipList (f a) -> f (ZipList a)

mapM :: Monad m => (a -> m b) -> ZipList a -> m (ZipList b)

sequence :: Monad m => ZipList (m a) -> m (ZipList a)

Traversable Option

Since: base-4.9.0.0

Defined in Data.Semigroup

Methods

traverse :: Applicative f => (a -> f b) -> Option a -> f (Option b)

sequenceA :: Applicative f => Option (f a) -> f (Option a)

mapM :: Monad m => (a -> m b) -> Option a -> m (Option b)

sequence :: Monad m => Option (m a) -> m (Option a)

Traversable Last

Since: base-4.9.0.0

Defined in Data.Semigroup

Methods

traverse :: Applicative f => (a -> f b) -> Last a -> f (Last b)

sequenceA :: Applicative f => Last (f a) -> f (Last a)

mapM :: Monad m => (a -> m b) -> Last a -> m (Last b)

sequence :: Monad m => Last (m a) -> m (Last a)

Traversable First

Since: base-4.9.0.0

Defined in Data.Semigroup

Methods

traverse :: Applicative f => (a -> f b) -> First a -> f (First b)

sequenceA :: Applicative f => First (f a) -> f (First a)

mapM :: Monad m => (a -> m b) -> First a -> m (First b)

sequence :: Monad m => First (m a) -> m (First a)

Traversable Max

Since: base-4.9.0.0

Defined in Data.Semigroup

Methods

traverse :: Applicative f => (a -> f b) -> Max a -> f (Max b)

sequenceA :: Applicative f => Max (f a) -> f (Max a)

mapM :: Monad m => (a -> m b) -> Max a -> m (Max b)

sequence :: Monad m => Max (m a) -> m (Max a)

Traversable Min

Since: base-4.9.0.0

Defined in Data.Semigroup

Methods

traverse :: Applicative f => (a -> f b) -> Min a -> f (Min b)

sequenceA :: Applicative f => Min (f a) -> f (Min a)

mapM :: Monad m => (a -> m b) -> Min a -> m (Min b)

sequence :: Monad m => Min (m a) -> m (Min a)

Traversable Complex

Since: base-4.9.0.0

Defined in Data.Complex

Methods

traverse :: Applicative f => (a -> f b) -> Complex a -> f (Complex b)

sequenceA :: Applicative f => Complex (f a) -> f (Complex a)

mapM :: Monad m => (a -> m b) -> Complex a -> m (Complex b)

sequence :: Monad m => Complex (m a) -> m (Complex a)

Traversable (Either a)

Since: base-4.7.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a0 -> f b) -> Either a a0 -> f (Either a b)

sequenceA :: Applicative f => Either a (f a0) -> f (Either a a0)

mapM :: Monad m => (a0 -> m b) -> Either a a0 -> m (Either a b)

sequence :: Monad m => Either a (m a0) -> m (Either a a0)

Traversable (V1 :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> V1 a -> f (V1 b)

sequenceA :: Applicative f => V1 (f a) -> f (V1 a)

mapM :: Monad m => (a -> m b) -> V1 a -> m (V1 b)

sequence :: Monad m => V1 (m a) -> m (V1 a)

Traversable (U1 :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> U1 a -> f (U1 b)

sequenceA :: Applicative f => U1 (f a) -> f (U1 a)

mapM :: Monad m => (a -> m b) -> U1 a -> m (U1 b)

sequence :: Monad m => U1 (m a) -> m (U1 a)

Traversable (UAddr :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> UAddr a -> f (UAddr b)

sequenceA :: Applicative f => UAddr (f a) -> f (UAddr a)

mapM :: Monad m => (a -> m b) -> UAddr a -> m (UAddr b)

sequence :: Monad m => UAddr (m a) -> m (UAddr a)

Traversable (UChar :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> UChar a -> f (UChar b)

sequenceA :: Applicative f => UChar (f a) -> f (UChar a)

mapM :: Monad m => (a -> m b) -> UChar a -> m (UChar b)

sequence :: Monad m => UChar (m a) -> m (UChar a)

Traversable (UDouble :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> UDouble a -> f (UDouble b)

sequenceA :: Applicative f => UDouble (f a) -> f (UDouble a)

mapM :: Monad m => (a -> m b) -> UDouble a -> m (UDouble b)

sequence :: Monad m => UDouble (m a) -> m (UDouble a)

Traversable (UFloat :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> UFloat a -> f (UFloat b)

sequenceA :: Applicative f => UFloat (f a) -> f (UFloat a)

mapM :: Monad m => (a -> m b) -> UFloat a -> m (UFloat b)

sequence :: Monad m => UFloat (m a) -> m (UFloat a)

Traversable (UInt :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> UInt a -> f (UInt b)

sequenceA :: Applicative f => UInt (f a) -> f (UInt a)

mapM :: Monad m => (a -> m b) -> UInt a -> m (UInt b)

sequence :: Monad m => UInt (m a) -> m (UInt a)

Traversable (UWord :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> UWord a -> f (UWord b)

sequenceA :: Applicative f => UWord (f a) -> f (UWord a)

mapM :: Monad m => (a -> m b) -> UWord a -> m (UWord b)

sequence :: Monad m => UWord (m a) -> m (UWord a)

Traversable ((,) a)

Since: base-4.7.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a0 -> f b) -> (a, a0) -> f (a, b)

sequenceA :: Applicative f => (a, f a0) -> f (a, a0)

mapM :: Monad m => (a0 -> m b) -> (a, a0) -> m (a, b)

sequence :: Monad m => (a, m a0) -> m (a, a0)

Ix i => Traversable (Array i)

Since: base-2.1

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Array i a -> f (Array i b)

sequenceA :: Applicative f => Array i (f a) -> f (Array i a)

mapM :: Monad m => (a -> m b) -> Array i a -> m (Array i b)

sequence :: Monad m => Array i (m a) -> m (Array i a)

Traversable (Proxy :: Type -> Type)

Since: base-4.7.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Proxy a -> f (Proxy b)

sequenceA :: Applicative f => Proxy (f a) -> f (Proxy a)

mapM :: Monad m => (a -> m b) -> Proxy a -> m (Proxy b)

sequence :: Monad m => Proxy (m a) -> m (Proxy a)

Traversable (Arg a)

Since: base-4.9.0.0

Defined in Data.Semigroup

Methods

traverse :: Applicative f => (a0 -> f b) -> Arg a a0 -> f (Arg a b)

sequenceA :: Applicative f => Arg a (f a0) -> f (Arg a a0)

mapM :: Monad m => (a0 -> m b) -> Arg a a0 -> m (Arg a b)

sequence :: Monad m => Arg a (m a0) -> m (Arg a a0)

Traversable f => Traversable (Rec1 f)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f0 => (a -> f0 b) -> Rec1 f a -> f0 (Rec1 f b)

sequenceA :: Applicative f0 => Rec1 f (f0 a) -> f0 (Rec1 f a)

mapM :: Monad m => (a -> m b) -> Rec1 f a -> m (Rec1 f b)

sequence :: Monad m => Rec1 f (m a) -> m (Rec1 f a)

Traversable f => Traversable (Alt f)

Since: base-4.12.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f0 => (a -> f0 b) -> Alt f a -> f0 (Alt f b)

sequenceA :: Applicative f0 => Alt f (f0 a) -> f0 (Alt f a)

mapM :: Monad m => (a -> m b) -> Alt f a -> m (Alt f b)

sequence :: Monad m => Alt f (m a) -> m (Alt f a)

Traversable f => Traversable (Ap f)

Since: base-4.12.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f0 => (a -> f0 b) -> Ap f a -> f0 (Ap f b)

sequenceA :: Applicative f0 => Ap f (f0 a) -> f0 (Ap f a)

mapM :: Monad m => (a -> m b) -> Ap f a -> m (Ap f b)

sequence :: Monad m => Ap f (m a) -> m (Ap f a)

Traversable (Const m :: Type -> Type)

Since: base-4.7.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> Const m a -> f (Const m b)

sequenceA :: Applicative f => Const m (f a) -> f (Const m a)

mapM :: Monad m0 => (a -> m0 b) -> Const m a -> m0 (Const m b)

sequence :: Monad m0 => Const m (m0 a) -> m0 (Const m a)

Traversable (K1 i c :: Type -> Type)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f => (a -> f b) -> K1 i c a -> f (K1 i c b)

sequenceA :: Applicative f => K1 i c (f a) -> f (K1 i c a)

mapM :: Monad m => (a -> m b) -> K1 i c a -> m (K1 i c b)

sequence :: Monad m => K1 i c (m a) -> m (K1 i c a)

(Traversable f, Traversable g) => Traversable (f :+: g)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f0 => (a -> f0 b) -> (f :+: g) a -> f0 ((f :+: g) b)

sequenceA :: Applicative f0 => (f :+: g) (f0 a) -> f0 ((f :+: g) a)

mapM :: Monad m => (a -> m b) -> (f :+: g) a -> m ((f :+: g) b)

sequence :: Monad m => (f :+: g) (m a) -> m ((f :+: g) a)

(Traversable f, Traversable g) => Traversable (f :*: g)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f0 => (a -> f0 b) -> (f :*: g) a -> f0 ((f :*: g) b)

sequenceA :: Applicative f0 => (f :*: g) (f0 a) -> f0 ((f :*: g) a)

mapM :: Monad m => (a -> m b) -> (f :*: g) a -> m ((f :*: g) b)

sequence :: Monad m => (f :*: g) (m a) -> m ((f :*: g) a)

(Traversable f, Traversable g) => Traversable (Sum f g)

Since: base-4.9.0.0

Defined in Data.Functor.Sum

Methods

traverse :: Applicative f0 => (a -> f0 b) -> Sum f g a -> f0 (Sum f g b)

sequenceA :: Applicative f0 => Sum f g (f0 a) -> f0 (Sum f g a)

mapM :: Monad m => (a -> m b) -> Sum f g a -> m (Sum f g b)

sequence :: Monad m => Sum f g (m a) -> m (Sum f g a)

(Traversable f, Traversable g) => Traversable (Product f g)

Since: base-4.9.0.0

Defined in Data.Functor.Product

Methods

traverse :: Applicative f0 => (a -> f0 b) -> Product f g a -> f0 (Product f g b)

sequenceA :: Applicative f0 => Product f g (f0 a) -> f0 (Product f g a)

mapM :: Monad m => (a -> m b) -> Product f g a -> m (Product f g b)

sequence :: Monad m => Product f g (m a) -> m (Product f g a)

Traversable f => Traversable (M1 i c f)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f0 => (a -> f0 b) -> M1 i c f a -> f0 (M1 i c f b)

sequenceA :: Applicative f0 => M1 i c f (f0 a) -> f0 (M1 i c f a)

mapM :: Monad m => (a -> m b) -> M1 i c f a -> m (M1 i c f b)

sequence :: Monad m => M1 i c f (m a) -> m (M1 i c f a)

(Traversable f, Traversable g) => Traversable (f :.: g)

Since: base-4.9.0.0

Defined in Data.Traversable

Methods

traverse :: Applicative f0 => (a -> f0 b) -> (f :.: g) a -> f0 ((f :.: g) b)

sequenceA :: Applicative f0 => (f :.: g) (f0 a) -> f0 ((f :.: g) a)

mapM :: Monad m => (a -> m b) -> (f :.: g) a -> m ((f :.: g) b)

sequence :: Monad m => (f :.: g) (m a) -> m ((f :.: g) a)

(Traversable f, Traversable g) => Traversable (Compose f g)

Since: base-4.9.0.0

Defined in Data.Functor.Compose

Methods

traverse :: Applicative f0 => (a -> f0 b) -> Compose f g a -> f0 (Compose f g b)

sequenceA :: Applicative f0 => Compose f g (f0 a) -> f0 (Compose f g a)

mapM :: Monad m => (a -> m b) -> Compose f g a -> m (Compose f g b)

sequence :: Monad m => Compose f g (m a) -> m (Compose f g a)

Utility functions

for :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b)

for is traverse with its arguments flipped. For a version that ignores the results see for_.

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

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

mapAccumL :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)

The mapAccumL function behaves like a combination of fmap and foldl; it applies a function to each element of a structure, passing an accumulating parameter from left to right, and returning a final value of this accumulator together with the new structure.

Examples

Basic usage:

>>> mapAccumL (\a b -> (a + b, a)) 0 [1..10]
(55,[0,1,3,6,10,15,21,28,36,45])

>>> mapAccumL (\a b -> (a <> show b, a)) "0" [1..5]
("012345",["0","01","012","0123","01234"])

mapAccumR :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)

The mapAccumR function behaves like a combination of fmap and foldr; it applies a function to each element of a structure, passing an accumulating parameter from right to left, and returning a final value of this accumulator together with the new structure.

Examples

Basic usage:

>>> mapAccumR (\a b -> (a + b, a)) 0 [1..10]
(55,[54,52,49,45,40,34,27,19,10,0])

>>> mapAccumR (\a b -> (a <> show b, a)) "0" [1..5]
("054321",["05432","0543","054","05","0"])

General definitions for superclass methods

fmapDefault :: forall t a b. Traversable t => (a -> b) -> t a -> t b

This function may be used as a value for fmap in a Functor instance, provided that traverse is defined. (Using fmapDefault with a Traversable instance defined only by sequenceA will result in infinite recursion.)

fmapDefault f ≡ runIdentity . traverse (Identity . f)

foldMapDefault :: forall t m a. (Traversable t, Monoid m) => (a -> m) -> t a -> m

This function may be used as a value for foldMap in a Foldable instance.

foldMapDefault f ≡ getConst . traverse (Const . f)

Overview

Traversable functors can be thought of as polymorphic containers that support mapping of applicative (or monadic) effects over the container (element-wise) to create a new container of the same shape, with the effects sequenced in a natural order for the container type in question.

The Functor base class means that the container cannot impose any constraints on the element type, so containers that require elements to be comparable, or hashable, etc., cannot be instances of the Traversable class.

The traverse and mapM methods

For an Applicative functor f and a Traversable functor t, the type signatures of traverse and fmap are rather similar:

fmap     :: (a -> f b) -> t a -> t (f b)
traverse :: (a -> f b) -> t a -> f (t b)

with one crucial difference: fmap produces a container of effects, while traverse produces an aggregate container-valued effect. For example, when f is the IO monad, and t is the List functor, while fmap returns a list of pending IO actions traverse returns an IO action that evaluates to a list of the return values of the individual actions performed left-to-right.

More concretely, if nameAndLineCount counts the number of lines in a file, returning a pair with input filename and the line count, then traversal over a list of file names produces an IO action that evaluates to a list of (fileName, lineCount) pairs:

>>> nameAndLineCount :: FilePath -> IO (FilePath, Int)
>>> nameAndLineCount fn = ...
>>> traverse nameAndLineCount ["/etc/passwd","/etc/hosts"]
[("/etc/passwd",56),("/etc/hosts",32)]

The specialisation of traverse to the case when f is a monad is called mapM. The two are otherwise generally identical:

traverse :: (Applicative f, Traversable t) => (a -> f b) -> t a -> f (t b)
mapM     :: (Monad       m, Traversable t) => (a -> m b) -> t a -> m (t b)

The behaviour of traverse and mapM can be at first surprising when the applicative functor f is [] (i.e. the List monad). The List monad is said to be non-deterministic, by which is meant that applying a list of n functions [a -> b] to a list of k values [a] produces a list of n*k values of each function applied to each input value.

As a result, traversal with a function f :: a -> [b], over an input container t a, yields a list [t b], whose length is the product of the lengths of the lists that the function returns for each element of the input container! The individual elements a of the container are replaced by each element of f a in turn:

>>> mapM (\n -> [0..n]) $ Just 2
[Just 0, Just 1, Just 2]
>>> mapM (\n -> [0..n]) [0..2]
[[0,0,0],[0,0,1],[0,0,2],[0,1,0],[0,1,1],[0,1,2]]

If any element of the container is mapped to an empty list, then the aggregate result is empty (no value is available to fill one of the slots of the output container).

>>> traverse (const []) $ Just 0
[]

When however the traversed container is empty, the result is always a singleton of the empty container, the function is never evaluated as there are no input values for it to be applied to.

>>> traverse (const []) Nothing
[Nothing]

The result of traverse is all-or-nothing, either containers of exactly the same shape as the input or a failure (Nothing, Left, empty list, etc.). The traverse function does not perform selective filtering as with e.g. mapMaybe:

>>> let incOdd n = if odd n then Just $ n + 1 else Nothing
>>> traverse incOdd [1, 2, 3]
Nothing
>>> mapMaybe incOdd [1, 2, 3]
[2,4]

Validation use-case

A hypothetical application of the above is to validate a structure:

>>> validate :: Int -> Either (String, Int) Int
>>> validate i = if odd i then Left ("That's odd", i) else Right i
>>> traverse validate [2,4,6,8,10]
Right [2,4,6,8,10]
>>> traverse validate [2,4,6,8,9]
Left ("That's odd",9)

>>> -- Since 'Nothing' is an empty structure, none of its elements are odd.
>>> traverse validate Nothing
Right Nothing
>>> traverse validate (Just 42)
Right (Just 42)
>>> traverse validate (Just 17)
Left ("That's odd",17)

However, this is not terribly efficient, because we pay the cost of reconstructing the entire structure as a side effect of validation. It is generally cheaper to just check all the elements and then use the original structure if it is valid. This can be done via the methods of the Foldable superclass, which perform only the side effects without generating a new structure:

>>> traverse_ validate [2,4,6,8,10]
Right ()
>>> traverse_ validate [2,4,6,8,9]
Left ("That's odd",9)

The Foldable instance should be defined in a manner that avoids construction of an unnecesary copy of the container.

The Foldable method mapM_ and its flipped version forM_ can be used to sequence IO actions over all the elements of a Traversable container (just for their side-effects, ignoring any results) . One special case is a Maybe container that optionally holds a value. Given:

action :: a -> IO ()
mvalue :: Maybe a

if you want to evaluate the action in the Just case, and do nothing otherwise, you can write the more concise and more general:

mapM_ action mvalue

rather than

maybe (return ()) action mvalue

The mapM_ form works verbatim if the type of mvalue is later refactored from Maybe a to Either e a (assuming it remains OK to silently do nothing in the error case).

There's even a generic way to handle empty values (Nothing, Left, etc.):

case traverse_ (const Nothing) mvalue of
    Nothing -> mapM_ action mvalue -- mvalue is non-empty
    Just () -> ... handle empty mvalue ...

The sequenceA and sequence methods

The sequenceA and sequence methods are useful when what you have is a container of applicative or, respectively, monadic actions, and you want to evaluate them left-to-right to obtain a container of the computed values.

sequenceA :: (Applicative f, Traversable t) => t (f a) -> f (t a)
sequence  :: (Monad       m, Traversable t) => t (m a) -> m (t a)
sequenceA = traverse id
sequence  = mapM id

When the monad m is IO, applying sequence to a list of IO actions, performs each in turn, returning a list of the results:

sequence [putStr "Hello ", putStrLn "World!"]
    = (\a b -> [a,b]) <$> putStr "Hello " <*> putStrLn "World!"
    = do u1 <- putStr "Hello "
         u2 <- putStrLn "World!"
         return (u1, u2)

For sequenceA, the non-deterministic behaviour of List is most easily seen in the case of a list of lists (of elements of some common fixed type). The result is a cross-product of all the sublists:

>>> sequenceA [[0, 1, 2], [30, 40], [500]]
[[0,30,500],[0,40,500],[1,30,500],[1,40,500],[2,30,500],[2,40,500]]

When the monad m is Maybe or Either, the effect in question is to short-circuit the computation on encountering Nothing or Left.

>>> sequence [Just 1,Just 2,Just 3]
Just [1,2,3]
>>> sequence [Just 1,Nothing,Just 3]
Nothing
>>> sequence [Right 1,Right 2,Right 3]
Right [1,2,3]
>>> sequence [Right 1,Left "sorry",Right 3]
Left "sorry"

The result of sequence is all-or-nothing, either containers of exactly the same shape as the input or a failure (Nothing, Left, empty list, etc.). The sequence function does not perform selective filtering as with e.g. catMaybes or rights:

>>> catMaybes [Just 1,Nothing,Just 3]
[1,3]
>>> rights [Right 1,Left "sorry",Right 3]
[1,3]

Sample instance

Instances are similar to Functor, e.g. given a data type

data Tree a = Empty | Leaf a | Node (Tree a) a (Tree a)

a suitable instance would be

instance Traversable Tree where
   traverse f Empty = pure Empty
   traverse f (Leaf x) = Leaf <$> f x
   traverse f (Node l k r) = Node <$> traverse f l <*> f k <*> traverse f r

This definition works for any applicative functor in the co-domain of f, as the laws for <*> imply a form of associativity.

Construction

How do Traversable functors manage to construct a new container of the same shape by sequencing effects over their elements? Well, left-to-right traversal with sequencing of effects suggests induction from a base case, so the first question is what is the base case? A Traversable container with elements of type a generally has some minimal form that is either "empty" or has just a single element (think Data.List vs. Data.List.Nonempty).

• If the base case is empty (no associated first value of a) then traversal just reproduces the empty structure with no side effects, so we have:

  traverse _ empty = pure empty

  With the List monad, "empty" is [], while with Maybe it is Nothing. With Either e a we have an empty case for each value of e.

• If the base case is a singleton a, then traverse can take that a, apply f :: a -> F b getting an F b, then fmap singleton over that, getting F (singleton b):

  traverse f (singleton a) = singleton <$> f a

Since Maybe and Either are either empty or singletons, we have

traverse _ Nothing = pure Nothing
traverse f (Just a) = Just <$> f a

traverse _ (Left e) = pure (Left e)
traverse f (Right a) = Right <$> f a

Similarly, for List, we have:

traverse f [] = pure []
traverse f [a] = fmap (:[]) (f a) = (:) <$> f a <*> pure []

What remains to be done is an inductive step beyond the empty and singleton cases. For a concrete Traversable functor T we need to be able to extend our structure incrementally by filling in holes. We can view a partially built structure t0 :: T a as a function append :: a -> T a that takes one more element a to insert into the container to the right of the existing elements to produce a larger structure. Conversely, we can view an element a as a function prepend :: T a -> T a of a partially built structure that inserts the element to the left of the existing elements.

Assuming that traverse has already been defined on the partially built structure:

f0 = traverse f t0 :: F (T b)

we aim to define traverse f (append t0 a) and/or traverse f (prepend a t0).

We can lift append and apply it to f0 to get:

append <$> f0 :: F (b -> T b)

and from the next element a we can obtain f a :: F b, and this is where we'll make use of the applicative instance of F. Adding one more element on the right is then:

traverse f (append t0 a) = append <$> traverse f t0 <*> f a

while prepending an element on the left is:

traverse f (prepend a t0) = prepend <$> f a <*> traverse f t0

The (binary) Tree instance example makes use of both, after defining the Empty base case and the singleton Leaf node case, non-empty internal nodes introduce both a prepended child node on the left and an appended child node on the right:

traverse f (Node l k r) = Node <$> traverse f l <*> f k <*> traverse f r

The above definitions sequence the Applicative effects of F in the expected order while producing results of the expected shape T.

For lists we get the natural order of effects by using (prepend <$> f a) as the operator and (traverse f as) as the operand (the actual definition is written as an equivalent right fold in order to enable fusion rules):

traverse f [] = pure []
traverse f (a:as) = (:) <$> f a <*> traverse f as

The origin of the combinatorial product when F is [] should now be apparent, the non-deterministic definition of <*> for List makes multiple independent choices for each element of the structure.

Laws

A definition of traverse must satisfy the following laws:

Naturality

t . traverse f = traverse (t . f) for every applicative transformation t

Identity

traverse Identity = Identity

Composition

traverse (Compose . fmap g . f) = Compose . fmap (traverse g) . traverse f

A definition of sequenceA must satisfy the following laws:

Naturality

t . sequenceA = sequenceA . fmap t for every applicative transformation t

Identity

sequenceA . fmap Identity = Identity

Composition

sequenceA . fmap Compose = Compose . fmap sequenceA . sequenceA

where an applicative transformation is a function

t :: (Applicative f, Applicative g) => f a -> g a

preserving the Applicative operations, i.e.

t (pure x) = pure x
t (f <*> x) = t f <*> t x

and the identity functor Identity and composition functors Compose are from Data.Functor.Identity and Data.Functor.Compose.

A result of the naturality law is a purity law for traverse

traverse pure = pure

(The naturality law is implied by parametricity and thus so is the purity law [1, p15].)

The superclass instances should satisfy the following:

• In the Functor instance, fmap should be equivalent to traversal with the identity applicative functor (fmapDefault).
• In the Foldable instance, foldMap should be equivalent to traversal with a constant applicative functor (foldMapDefault).

See also

• [1] "The Essence of the Iterator Pattern", by Jeremy Gibbons and Bruno Oliveira, in Mathematically-Structured Functional Programming, 2006, online at http://www.cs.ox.ac.uk/people/jeremy.gibbons/publications/#iterator.
• "Applicative Programming with Effects", by Conor McBride and Ross Paterson, Journal of Functional Programming 18:1 (2008) 1-13, online at http://www.soi.city.ac.uk/~ross/papers/Applicative.html.
• "An Investigation of the Laws of Traversals", by Mauro Jaskelioff and Ondrej Rypacek, in Mathematically-Structured Functional Programming, 2012, online at http://arxiv.org/pdf/1202.2919.