GHC.Internal.Data.Traversable

ghc-internal-9.1001.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 | stable
Portability | portable
Safe Haskell | Trustworthy
Language | Haskell2010

GHC.Internal.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. Instances are expected to satisfy the listed laws.

Synopsis

- class (Functor t, Foldable t) => Traversable (t :: Type -> Type) where
  - traverse :: Applicative f => (a -> f b) -> t a -> f (t b)
  - sequenceA :: Applicative f => t (f a) -> f (t a)
  - mapM :: Monad m => (a -> m b) -> t a -> m (t b)
  - sequence :: Monad m => t (m a) -> m (t a)
- 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)
- forAccumM :: (Monad m, Traversable t) => s -> t a -> (s -> a -> m (s, b)) -> m (s, t b)
- mapAccumL :: Traversable t => (s -> a -> (s, b)) -> s -> t a -> (s, t b)
- mapAccumR :: Traversable t => (s -> a -> (s, b)) -> s -> t a -> (s, t b)
- mapAccumM :: (Monad m, Traversable t) => (s -> a -> m (s, b)) -> s -> t a -> m (s, t b)
- fmapDefault :: Traversable t => (a -> b) -> t a -> t b
- foldMapDefault :: (Traversable t, Monoid m) => (a -> m) -> t a -> m

# The `Traversable` class

class (Functor t, Foldable t) => Traversable (t :: Type -> Type) where Source #

Functors representing data structures that can be transformed to structures of the same shape by performing an `Applicative` (or, therefore, `Monad`) action on each element from left to right.

A more detailed description of what same shape means, the various methods, how traversals are constructed, and example advanced use-cases can be found in the Overview section of Data.Traversable.

For the class laws see the Laws section of Data.Traversable.

Minimal complete definition

traverse | sequenceA

Methods

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

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

Expand

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) Source #

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

#### Examples

Expand

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) Source #

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

Expand

`mapM` is literally a `traverse` with a type signature restricted to `Monad`. Its implementation may be more efficient due to additional power of `Monad`.

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

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

Expand

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

Instances details

Traversable NonEmpty Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> NonEmpty a -> f (NonEmpty b) Source # sequenceA :: Applicative f => NonEmpty (f a) -> f (NonEmpty a) Source # mapM :: Monad m => (a -> m b) -> NonEmpty a -> m (NonEmpty b) Source # sequence :: Monad m => NonEmpty (m a) -> m (NonEmpty a) Source #
Traversable Identity Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Identity a -> f (Identity b) Source # sequenceA :: Applicative f => Identity (f a) -> f (Identity a) Source # mapM :: Monad m => (a -> m b) -> Identity a -> m (Identity b) Source # sequence :: Monad m => Identity (m a) -> m (Identity a) Source #
Traversable First Source # | @since base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> First a -> f (First b) Source # sequenceA :: Applicative f => First (f a) -> f (First a) Source # mapM :: Monad m => (a -> m b) -> First a -> m (First b) Source # sequence :: Monad m => First (m a) -> m (First a) Source #
Traversable Last Source # | @since base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Last a -> f (Last b) Source # sequenceA :: Applicative f => Last (f a) -> f (Last a) Source # mapM :: Monad m => (a -> m b) -> Last a -> m (Last b) Source # sequence :: Monad m => Last (m a) -> m (Last a) Source #
Traversable Down Source # | @since base-4.12.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Down a -> f (Down b) Source # sequenceA :: Applicative f => Down (f a) -> f (Down a) Source # mapM :: Monad m => (a -> m b) -> Down a -> m (Down b) Source # sequence :: Monad m => Down (m a) -> m (Down a) Source #
Traversable Dual Source # | @since base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Dual a -> f (Dual b) Source # sequenceA :: Applicative f => Dual (f a) -> f (Dual a) Source # mapM :: Monad m => (a -> m b) -> Dual a -> m (Dual b) Source # sequence :: Monad m => Dual (m a) -> m (Dual a) Source #
Traversable Product Source # | @since base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Product a -> f (Product b) Source # sequenceA :: Applicative f => Product (f a) -> f (Product a) Source # mapM :: Monad m => (a -> m b) -> Product a -> m (Product b) Source # sequence :: Monad m => Product (m a) -> m (Product a) Source #
Traversable Sum Source # | @since base-4.8.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Sum a -> f (Sum b) Source # sequenceA :: Applicative f => Sum (f a) -> f (Sum a) Source # mapM :: Monad m => (a -> m b) -> Sum a -> m (Sum b) Source # sequence :: Monad m => Sum (m a) -> m (Sum a) Source #
Traversable ZipList Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Functor.ZipList Methods traverse :: Applicative f => (a -> f b) -> ZipList a -> f (ZipList b) Source # sequenceA :: Applicative f => ZipList (f a) -> f (ZipList a) Source # mapM :: Monad m => (a -> m b) -> ZipList a -> m (ZipList b) Source # sequence :: Monad m => ZipList (m a) -> m (ZipList a) Source #
Traversable Par1 Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Par1 a -> f (Par1 b) Source # sequenceA :: Applicative f => Par1 (f a) -> f (Par1 a) Source # mapM :: Monad m => (a -> m b) -> Par1 a -> m (Par1 b) Source # sequence :: Monad m => Par1 (m a) -> m (Par1 a) Source #
Traversable Maybe Source # | @since base-2.01
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Maybe a -> f (Maybe b) Source # sequenceA :: Applicative f => Maybe (f a) -> f (Maybe a) Source # mapM :: Monad m => (a -> m b) -> Maybe a -> m (Maybe b) Source # sequence :: Monad m => Maybe (m a) -> m (Maybe a) Source #
Traversable Solo Source # | @since base-4.15
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Solo a -> f (Solo b) Source # sequenceA :: Applicative f => Solo (f a) -> f (Solo a) Source # mapM :: Monad m => (a -> m b) -> Solo a -> m (Solo b) Source # sequence :: Monad m => Solo (m a) -> m (Solo a) Source #
Traversable [] Source # | @since base-2.01
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> [a] -> f [b] Source # sequenceA :: Applicative f => [f a] -> f [a] Source # mapM :: Monad m => (a -> m b) -> [a] -> m [b] Source # sequence :: Monad m => [m a] -> m [a] Source #
Ix i => Traversable (Array i) Source # | @since base-2.01
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Array i a -> f (Array i b) Source # sequenceA :: Applicative f => Array i (f a) -> f (Array i a) Source # mapM :: Monad m => (a -> m b) -> Array i a -> m (Array i b) Source # sequence :: Monad m => Array i (m a) -> m (Array i a) Source #
Traversable (Either a) Source # | @since base-4.7.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a0 -> f b) -> Either a a0 -> f (Either a b) Source # sequenceA :: Applicative f => Either a (f a0) -> f (Either a a0) Source # mapM :: Monad m => (a0 -> m b) -> Either a a0 -> m (Either a b) Source # sequence :: Monad m => Either a (m a0) -> m (Either a a0) Source #
Traversable (Proxy :: Type -> Type) Source # | @since base-4.7.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Proxy a -> f (Proxy b) Source # sequenceA :: Applicative f => Proxy (f a) -> f (Proxy a) Source # mapM :: Monad m => (a -> m b) -> Proxy a -> m (Proxy b) Source # sequence :: Monad m => Proxy (m a) -> m (Proxy a) Source #
Traversable (U1 :: Type -> Type) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> U1 a -> f (U1 b) Source # sequenceA :: Applicative f => U1 (f a) -> f (U1 a) Source # mapM :: Monad m => (a -> m b) -> U1 a -> m (U1 b) Source # sequence :: Monad m => U1 (m a) -> m (U1 a) Source #
Traversable (UAddr :: Type -> Type) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> UAddr a -> f (UAddr b) Source # sequenceA :: Applicative f => UAddr (f a) -> f (UAddr a) Source # mapM :: Monad m => (a -> m b) -> UAddr a -> m (UAddr b) Source # sequence :: Monad m => UAddr (m a) -> m (UAddr a) Source #
Traversable (UChar :: Type -> Type) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> UChar a -> f (UChar b) Source # sequenceA :: Applicative f => UChar (f a) -> f (UChar a) Source # mapM :: Monad m => (a -> m b) -> UChar a -> m (UChar b) Source # sequence :: Monad m => UChar (m a) -> m (UChar a) Source #
Traversable (UDouble :: Type -> Type) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> UDouble a -> f (UDouble b) Source # sequenceA :: Applicative f => UDouble (f a) -> f (UDouble a) Source # mapM :: Monad m => (a -> m b) -> UDouble a -> m (UDouble b) Source # sequence :: Monad m => UDouble (m a) -> m (UDouble a) Source #
Traversable (UFloat :: Type -> Type) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> UFloat a -> f (UFloat b) Source # sequenceA :: Applicative f => UFloat (f a) -> f (UFloat a) Source # mapM :: Monad m => (a -> m b) -> UFloat a -> m (UFloat b) Source # sequence :: Monad m => UFloat (m a) -> m (UFloat a) Source #
Traversable (UInt :: Type -> Type) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> UInt a -> f (UInt b) Source # sequenceA :: Applicative f => UInt (f a) -> f (UInt a) Source # mapM :: Monad m => (a -> m b) -> UInt a -> m (UInt b) Source # sequence :: Monad m => UInt (m a) -> m (UInt a) Source #
Traversable (UWord :: Type -> Type) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> UWord a -> f (UWord b) Source # sequenceA :: Applicative f => UWord (f a) -> f (UWord a) Source # mapM :: Monad m => (a -> m b) -> UWord a -> m (UWord b) Source # sequence :: Monad m => UWord (m a) -> m (UWord a) Source #
Traversable (V1 :: Type -> Type) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> V1 a -> f (V1 b) Source # sequenceA :: Applicative f => V1 (f a) -> f (V1 a) Source # mapM :: Monad m => (a -> m b) -> V1 a -> m (V1 b) Source # sequence :: Monad m => V1 (m a) -> m (V1 a) Source #
Traversable ((,) a) Source # | @since base-4.7.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a0 -> f b) -> (a, a0) -> f (a, b) Source # sequenceA :: Applicative f => (a, f a0) -> f (a, a0) Source # mapM :: Monad m => (a0 -> m b) -> (a, a0) -> m (a, b) Source # sequence :: Monad m => (a, m a0) -> m (a, a0) Source #
Traversable (Const m :: Type -> Type) Source # | @since base-4.7.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> Const m a -> f (Const m b) Source # sequenceA :: Applicative f => Const m (f a) -> f (Const m a) Source # mapM :: Monad m0 => (a -> m0 b) -> Const m a -> m0 (Const m b) Source # sequence :: Monad m0 => Const m (m0 a) -> m0 (Const m a) Source #
Traversable f => Traversable (Ap f) Source # | @since base-4.12.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f0 => (a -> f0 b) -> Ap f a -> f0 (Ap f b) Source # sequenceA :: Applicative f0 => Ap f (f0 a) -> f0 (Ap f a) Source # mapM :: Monad m => (a -> m b) -> Ap f a -> m (Ap f b) Source # sequence :: Monad m => Ap f (m a) -> m (Ap f a) Source #
Traversable f => Traversable (Alt f) Source # | @since base-4.12.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f0 => (a -> f0 b) -> Alt f a -> f0 (Alt f b) Source # sequenceA :: Applicative f0 => Alt f (f0 a) -> f0 (Alt f a) Source # mapM :: Monad m => (a -> m b) -> Alt f a -> m (Alt f b) Source # sequence :: Monad m => Alt f (m a) -> m (Alt f a) Source #
Traversable f => Traversable (Rec1 f) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f0 => (a -> f0 b) -> Rec1 f a -> f0 (Rec1 f b) Source # sequenceA :: Applicative f0 => Rec1 f (f0 a) -> f0 (Rec1 f a) Source # mapM :: Monad m => (a -> m b) -> Rec1 f a -> m (Rec1 f b) Source # sequence :: Monad m => Rec1 f (m a) -> m (Rec1 f a) Source #
(Traversable f, Traversable g) => Traversable (f :*: g) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f0 => (a -> f0 b) -> (f :*: g) a -> f0 ((f :*: g) b) Source # sequenceA :: Applicative f0 => (f :*: g) (f0 a) -> f0 ((f :*: g) a) Source # mapM :: Monad m => (a -> m b) -> (f :*: g) a -> m ((f :*: g) b) Source # sequence :: Monad m => (f :*: g) (m a) -> m ((f :*: g) a) Source #
(Traversable f, Traversable g) => Traversable (f :+: g) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f0 => (a -> f0 b) -> (f :+: g) a -> f0 ((f :+: g) b) Source # sequenceA :: Applicative f0 => (f :+: g) (f0 a) -> f0 ((f :+: g) a) Source # mapM :: Monad m => (a -> m b) -> (f :+: g) a -> m ((f :+: g) b) Source # sequence :: Monad m => (f :+: g) (m a) -> m ((f :+: g) a) Source #
Traversable (K1 i c :: Type -> Type) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f => (a -> f b) -> K1 i c a -> f (K1 i c b) Source # sequenceA :: Applicative f => K1 i c (f a) -> f (K1 i c a) Source # mapM :: Monad m => (a -> m b) -> K1 i c a -> m (K1 i c b) Source # sequence :: Monad m => K1 i c (m a) -> m (K1 i c a) Source #
(Traversable f, Traversable g) => Traversable (f :.: g) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f0 => (a -> f0 b) -> (f :.: g) a -> f0 ((f :.: g) b) Source # sequenceA :: Applicative f0 => (f :.: g) (f0 a) -> f0 ((f :.: g) a) Source # mapM :: Monad m => (a -> m b) -> (f :.: g) a -> m ((f :.: g) b) Source # sequence :: Monad m => (f :.: g) (m a) -> m ((f :.: g) a) Source #
Traversable f => Traversable (M1 i c f) Source # | @since base-4.9.0.0
Instance details Defined in GHC.Internal.Data.Traversable Methods traverse :: Applicative f0 => (a -> f0 b) -> M1 i c f a -> f0 (M1 i c f b) Source # sequenceA :: Applicative f0 => M1 i c f (f0 a) -> f0 (M1 i c f a) Source # mapM :: Monad m => (a -> m b) -> M1 i c f a -> m (M1 i c f b) Source # sequence :: Monad m => M1 i c f (m a) -> m (M1 i c f a) Source #

# Utility functions

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

`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) Source #

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

forAccumM :: (Monad m, Traversable t) => s -> t a -> (s -> a -> m (s, b)) -> m (s, t b) Source #

`forAccumM` is `mapAccumM` with the arguments rearranged.

@since base-4.18.0.0

mapAccumL :: Traversable t => (s -> a -> (s, b)) -> s -> t a -> (s, t b) Source #

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

Expand

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 => (s -> a -> (s, b)) -> s -> t a -> (s, t b) Source #

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

Expand

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"])

mapAccumM :: (Monad m, Traversable t) => (s -> a -> m (s, b)) -> s -> t a -> m (s, t b) Source #

The `mapAccumM` function behaves like a combination of `mapM` and `mapAccumL` that traverses the structure while evaluating the actions and passing an accumulating parameter from left to right. It returns a final value of this accumulator together with the new structure. The accumulator is often used for caching the intermediate results of a computation.

@since base-4.18.0.0

#### Examples

Expand

Basic usage:

    >>> let expensiveDouble a = putStrLn ("Doubling " <> show a) >> pure (2 * a)
    >>> :{
    mapAccumM (\cache a -> case lookup a cache of
        Nothing -> expensiveDouble a >>= \double -> pure ((a, double):cache, double)
        Just double -> pure (cache, double)
        ) [] [1, 2, 3, 1, 2, 3]
    :}
    Doubling 1
    Doubling 2
    Doubling 3
    ([(3,6),(2,4),(1,2)],[2,4,6,2,4,6])

# General definitions for superclass methods

fmapDefault :: Traversable t => (a -> b) -> t a -> t b Source #

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 :: (Traversable t, Monoid m) => (a -> m) -> t a -> m Source #

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

    foldMapDefault f ≡ getConst . traverse (Const . f)