Data.Traversable

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

See also

• "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.
• "The Essence of the Iterator Pattern", by Jeremy Gibbons and Bruno Oliveira, in Mathematically-Structured Functional Programming, 2006, online at http://web.comlab.ox.ac.uk/oucl/work/jeremy.gibbons/publications/#iterator.
• "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.

The Traversable class

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

Functors representing data structures that can be traversed from left to right.

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 (x <*> y) = t x <*> t y

and the identity functor Identity and composition of functors Compose are defined as

  newtype Identity a = Identity a

  instance Functor Identity where
    fmap f (Identity x) = Identity (f x)

  instance Applicative Identity where
    pure x = Identity x
    Identity f <*> Identity x = Identity (f x)

  newtype Compose f g a = Compose (f (g a))

  instance (Functor f, Functor g) => Functor (Compose f g) where
    fmap f (Compose x) = Compose (fmap (fmap f) x)

  instance (Applicative f, Applicative g) => Applicative (Compose f g) where
    pure x = Compose (pure (pure x))
    Compose f <*> Compose x = Compose ((<*>) <$> f <*> x)

(The naturality law is implied by parametricity.)

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 is suitable even for abstract types, as the laws for <*> imply a form of associativity.

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

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

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

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

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

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

Instances

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

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 V1

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

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 Par1

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 Last

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

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 Product

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

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

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 ZipList

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

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 Option

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

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

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

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

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 Identity

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 (Either a)

Methods

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

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

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

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

Traversable f => Traversable (Rec1 f)

Methods

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

sequenceA :: Applicative f => Rec1 f (f a) -> f (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 (URec Char)

Methods

traverse :: Applicative f => (a -> f b) -> URec Char a -> f (URec Char b)

sequenceA :: Applicative f => URec Char (f a) -> f (URec Char a)

mapM :: Monad m => (a -> m b) -> URec Char a -> m (URec Char b)

sequence :: Monad m => URec Char (m a) -> m (URec Char a)

Traversable (URec Double)

Methods

traverse :: Applicative f => (a -> f b) -> URec Double a -> f (URec Double b)

sequenceA :: Applicative f => URec Double (f a) -> f (URec Double a)

mapM :: Monad m => (a -> m b) -> URec Double a -> m (URec Double b)

sequence :: Monad m => URec Double (m a) -> m (URec Double a)

Traversable (URec Float)

Methods

traverse :: Applicative f => (a -> f b) -> URec Float a -> f (URec Float b)

sequenceA :: Applicative f => URec Float (f a) -> f (URec Float a)

mapM :: Monad m => (a -> m b) -> URec Float a -> m (URec Float b)

sequence :: Monad m => URec Float (m a) -> m (URec Float a)

Traversable (URec Int)

Methods

traverse :: Applicative f => (a -> f b) -> URec Int a -> f (URec Int b)

sequenceA :: Applicative f => URec Int (f a) -> f (URec Int a)

mapM :: Monad m => (a -> m b) -> URec Int a -> m (URec Int b)

sequence :: Monad m => URec Int (m a) -> m (URec Int a)

Traversable (URec Word)

Methods

traverse :: Applicative f => (a -> f b) -> URec Word a -> f (URec Word b)

sequenceA :: Applicative f => URec Word (f a) -> f (URec Word a)

mapM :: Monad m => (a -> m b) -> URec Word a -> m (URec Word b)

sequence :: Monad m => URec Word (m a) -> m (URec Word a)

Traversable (URec (Ptr ()))

Methods

traverse :: Applicative f => (a -> f b) -> URec (Ptr ()) a -> f (URec (Ptr ()) b)

sequenceA :: Applicative f => URec (Ptr ()) (f a) -> f (URec (Ptr ()) a)

mapM :: Monad m => (a -> m b) -> URec (Ptr ()) a -> m (URec (Ptr ()) b)

sequence :: Monad m => URec (Ptr ()) (m a) -> m (URec (Ptr ()) a)

Traversable ((,) a)

Methods

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

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

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

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

Traversable (Proxy *)

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)

Methods

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

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

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

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

Traversable (K1 i c)

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)

Methods

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

sequenceA :: Applicative f => (f :+: g) (f a) -> f ((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)

Methods

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

sequenceA :: Applicative f => (f :*: g) (f a) -> f ((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)

Methods

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

sequenceA :: Applicative f => (f :.: g) (f a) -> f ((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 (Const * m)

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 m => (a -> m b) -> Const * m a -> m (Const * m b)

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

Traversable f => Traversable (M1 i c f)

Methods

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

sequenceA :: Applicative f => M1 i c f (f a) -> f (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 (Product * f g)

Methods

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

sequenceA :: Applicative f => Product * f g (f a) -> f (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 g) => Traversable (Sum * f g)

Methods

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

sequenceA :: Applicative f => Sum * f g (f a) -> f (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 (Compose * * f g)

Methods

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

sequenceA :: Applicative f => Compose * * f g (f a) -> f (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.

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.

General definitions for superclass methods

fmapDefault :: 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.)

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

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