{-# LANGUAGE Trustworthy #-}{-# LANGUAGE ScopedTypeVariables #-}------------------------------------------------------------------------------- |-- Module : Data.Bitraversable-- Copyright : (C) 2011-2016 Edward Kmett-- License : BSD-style (see the file LICENSE)---- Maintainer : libraries@haskell.org-- Stability : provisional-- Portability : portable---- @since 4.10.0.0----------------------------------------------------------------------------moduleData.Bitraversable(Bitraversable (..),bisequenceA ,bisequence ,bimapM ,bifor ,biforM ,bimapAccumL ,bimapAccumR ,bimapDefault ,bifoldMapDefault )whereimportControl.Applicative importData.Bifunctor importData.Bifoldable importData.Coerce importData.Functor.Identity (Identity (..))importData.Functor.Utils (StateL (..),StateR (..))importGHC.Generics (K1 (..))-- | 'Bitraversable' identifies bifunctorial data structures whose elements can-- be traversed in order, performing 'Applicative' or 'Monad' actions at each-- element, and collecting a result structure with the same shape.---- As opposed to 'Traversable' data structures, which have one variety of-- element on which an action can be performed, 'Bitraversable' data structures-- have two such varieties of elements.---- A definition of 'bitraverse' must satisfy the following laws:---- [/naturality/]-- @'bitraverse' (t . f) (t . g) ≡ t . 'bitraverse' f g@-- for every applicative transformation @t@---- [/identity/]-- @'bitraverse' 'Identity' 'Identity' ≡ 'Identity'@---- [/composition/]-- @'Compose' . 'fmap' ('bitraverse' g1 g2) . 'bitraverse' f1 f2-- ≡ 'traverse' ('Compose' . 'fmap' g1 . f1) ('Compose' . 'fmap' g2 . f2)@---- where an /applicative transformation/ is a function---- @t :: ('Applicative' f, 'Applicative' g) => f a -> g a@---- preserving the 'Applicative' operations:---- @-- t ('pure' x) = 'pure' x-- t (f '<*>' x) = t f '<*>' t x-- @---- and the identity functor 'Identity' and composition functors 'Compose' are-- defined as---- > newtype Identity a = Identity { runIdentity :: a }-- >-- > instance Functor Identity where-- > fmap f (Identity x) = Identity (f x)-- >-- > instance Applicative Identity where-- > pure = Identity-- > 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 = Compose . pure . pure-- > Compose f <*> Compose x = Compose ((<*>) <$> f <*> x)---- Some simple examples are 'Either' and '(,)':---- > instance Bitraversable Either where-- > bitraverse f _ (Left x) = Left <$> f x-- > bitraverse _ g (Right y) = Right <$> g y-- >-- > instance Bitraversable (,) where-- > bitraverse f g (x, y) = (,) <$> f x <*> g y---- 'Bitraversable' relates to its superclasses in the following ways:---- @-- 'bimap' f g ≡ 'runIdentity' . 'bitraverse' ('Identity' . f) ('Identity' . g)-- 'bifoldMap' f g = 'getConst' . 'bitraverse' ('Const' . f) ('Const' . g)-- @---- These are available as 'bimapDefault' and 'bifoldMapDefault' respectively.---- @since 4.10.0.0class(Bifunctor t ,Bifoldable t )=>Bitraversable t where-- | Evaluates the relevant functions at each element in the structure,-- running the action, and builds a new structure with the same shape, using-- the results produced from sequencing the actions.---- @'bitraverse' f g ≡ 'bisequenceA' . 'bimap' f g@---- For a version that ignores the results, see 'bitraverse_'.---- @since 4.10.0.0bitraverse ::Applicative f =>(a ->f c )->(b ->f d )->t a b ->f (t c d )bitraverse f g =bisequenceA . bimap f g -- | Alias for 'bisequence'.---- @since 4.10.0.0bisequenceA::(Bitraversable t ,Applicative f )=>t (f a )(f b )->f (t a b )bisequenceA =bisequence -- | Alias for 'bitraverse'.---- @since 4.10.0.0bimapM::(Bitraversable t ,Applicative f )=>(a ->f c )->(b ->f d )->t a b ->f (t c d )bimapM =bitraverse -- | Sequences all the actions in a structure, building a new structure with-- the same shape using the results of the actions. For a version that ignores-- the results, see 'bisequence_'.---- @'bisequence' ≡ 'bitraverse' 'id' 'id'@---- @since 4.10.0.0bisequence::(Bitraversable t ,Applicative f )=>t (f a )(f b )->f (t a b )bisequence =bitraverse id id -- | @since 4.10.0.0instanceBitraversable (,)wherebitraverse f g ~(a ,b )=liftA2 (,)(f a )(g b )-- | @since 4.10.0.0instanceBitraversable ((,,)x )wherebitraverse f g ~(x ,a ,b )=liftA2 ((,,)x )(f a )(g b )-- | @since 4.10.0.0instanceBitraversable ((,,,)x y )wherebitraverse f g ~(x ,y ,a ,b )=liftA2 ((,,,)x y )(f a )(g b )-- | @since 4.10.0.0instanceBitraversable ((,,,,)x y z )wherebitraverse f g ~(x ,y ,z ,a ,b )=liftA2 ((,,,,)x y z )(f a )(g b )-- | @since 4.10.0.0instanceBitraversable ((,,,,,)x y z w )wherebitraverse f g ~(x ,y ,z ,w ,a ,b )=liftA2 ((,,,,,)x y z w )(f a )(g b )-- | @since 4.10.0.0instanceBitraversable ((,,,,,,)x y z w v )wherebitraverse f g ~(x ,y ,z ,w ,v ,a ,b )=liftA2 ((,,,,,,)x y z w v )(f a )(g b )-- | @since 4.10.0.0instanceBitraversable Either wherebitraverse f _(Left a )=Left <$> f a bitraverse_g (Right b )=Right <$> g b -- | @since 4.10.0.0instanceBitraversable Const wherebitraverse f _(Const a )=Const <$> f a -- | @since 4.10.0.0instanceBitraversable (K1 i )wherebitraverse f _(K1 c )=K1 <$> f c -- | 'bifor' is 'bitraverse' with the structure as the first argument. For a-- version that ignores the results, see 'bifor_'.---- @since 4.10.0.0bifor::(Bitraversable t ,Applicative f )=>t a b ->(a ->f c )->(b ->f d )->f (t c d )bifor t f g =bitraverse f g t -- | Alias for 'bifor'.---- @since 4.10.0.0biforM::(Bitraversable t ,Applicative f )=>t a b ->(a ->f c )->(b ->f d )->f (t c d )biforM =bifor -- | The 'bimapAccumL' function behaves like a combination of 'bimap' and-- 'bifoldl'; it traverses a structure from left to right, threading a state-- of type @a@ and using the given actions to compute new elements for the-- structure.---- @since 4.10.0.0bimapAccumL::Bitraversable t =>(a ->b ->(a ,c ))->(a ->d ->(a ,e ))->a ->t b d ->(a ,t c e )bimapAccumL f g s t =runStateL(bitraverse (StateL . flip f )(StateL . flip g )t )s -- | The 'bimapAccumR' function behaves like a combination of 'bimap' and-- 'bifoldl'; it traverses a structure from right to left, threading a state-- of type @a@ and using the given actions to compute new elements for the-- structure.---- @since 4.10.0.0bimapAccumR::Bitraversable t =>(a ->b ->(a ,c ))->(a ->d ->(a ,e ))->a ->t b d ->(a ,t c e )bimapAccumR f g s t =runStateR(bitraverse (StateR . flip f )(StateR . flip g )t )s -- | A default definition of 'bimap' in terms of the 'Bitraversable'-- operations.---- @'bimapDefault' f g ≡-- 'runIdentity' . 'bitraverse' ('Identity' . f) ('Identity' . g)@---- @since 4.10.0.0bimapDefault::forallt a b c d .Bitraversable t =>(a ->b )->(c ->d )->t a c ->t b d -- See Note [Function coercion] in Data.Functor.Utils.bimapDefault =coerce(bitraverse ::(a ->Identity b )->(c ->Identity d )->t a c ->Identity (t b d )){-# INLINEbimapDefault#-}-- | A default definition of 'bifoldMap' in terms of the 'Bitraversable'-- operations.---- @'bifoldMapDefault' f g ≡-- 'getConst' . 'bitraverse' ('Const' . f) ('Const' . g)@---- @since 4.10.0.0bifoldMapDefault::forallt m a b .(Bitraversable t ,Monoid m )=>(a ->m )->(b ->m )->t a b ->m -- See Note [Function coercion] in Data.Functor.Utils.bifoldMapDefault =coerce(bitraverse ::(a ->Const m ())->(b ->Const m ())->t a b ->Const m (t ()())){-# INLINEbifoldMapDefault#-}