ghc-internal-9.1200.0: Basic libraries
CopyrightConor McBride and Ross Paterson 2005
LicenseBSD-style (see the LICENSE file in the distribution)
Maintainerlibraries@haskell.org
Stabilitystable
Portabilityportable
Safe HaskellTrustworthy
LanguageHaskell2010

GHC.Internal.Data.Traversable

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

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 TyVarBndr Source # 
Instance details

Defined in GHC.Internal.TH.Syntax

Methods

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

sequenceA :: Applicative f => TyVarBndr (f a) -> f (TyVarBndr a) Source #

mapM :: Monad m => (a -> m b) -> TyVarBndr a -> m (TyVarBndr b) Source #

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

Traversable Maybe Source #

Since: base-2.1

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

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

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.

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

Since: base-4.18.0.0

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)