Data.Traversable

base-4.11.1.0: Basic libraries

Copyright | Conor McBride and Ross Paterson 2005
License | BSD-style (see the LICENSE file in the distribution)
Maintainer | libraries@haskell.org
Stability | experimental
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

Data.Traversable

Contents

- The `Traversable` class
- Utility functions
- General definitions for superclass methods

Description

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.

Synopsis

- class (Functor t, Foldable t) => Traversable t where
- for :: (Traversable t, Applicative f) => t a -> (a -> f b) -> f (t b)
- forM :: (Traversable t, Monad m) => t a -> (a -> m b) -> m (t b)
- mapAccumL :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
- mapAccumR :: Traversable t => (a -> b -> (a, c)) -> a -> t b -> (a, t c)
- fmapDefault :: forall t a b. Traversable t => (a -> b) -> t a -> t b
- foldMapDefault :: forall t m a. (Traversable t, Monoid m) => (a -> m) -> t a -> m

# 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 [] # | Since: base-2.1
Instance details 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
Instance details 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 # |
Instance details 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 NonEmpty # | Since: base-4.9.0.0
Instance details 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 Product # | Since: base-4.8.0.0
Instance details 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
Instance details 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
Instance details 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
Instance details 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
Instance details 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 # |
Instance details 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
Instance details 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
Instance details 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
Instance details 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
Instance details 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
Instance details 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
Instance details 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 # |
Instance details 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
Instance details 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 :: * -> *) # |
Instance details 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 :: * -> *) # | Since: base-4.9.0.0
Instance details 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 ((,) a) # | Since: base-4.7.0.0
Instance details 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) #
Traversable (Proxy :: * -> *) # | Since: base-4.7.0.0
Instance details 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
Instance details 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) # |
Instance details 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 (URec Char :: * -> *) # |
Instance details Defined in Data.Traversable 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 :: * -> *) # |
Instance details Defined in Data.Traversable 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 :: * -> *) # |
Instance details Defined in Data.Traversable 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 :: * -> *) # |
Instance details Defined in Data.Traversable 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 :: * -> *) # |
Instance details Defined in Data.Traversable 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 ()) :: * -> *) # |
Instance details Defined in Data.Traversable 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 (Const m :: * -> *) # | Since: base-4.7.0.0
Instance details 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 :: * -> *) # |
Instance details 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) # |
Instance details 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) # |
Instance details 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
Instance details 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
Instance details 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) # |
Instance details 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) # |
Instance details 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
Instance details 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.

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