A Traversal processes 0 or more parts of the whole, with Applicative interactions.

\( \mathsf{Traversal}\;S\;A = \exists F : \mathsf{Traversable}, S \equiv F\,A \)

Obtain a Traversal by lifting a lens getter and setter into a Traversable functor.

 withLens o traversing ≡ traversed . o

Compare folding.

Caution: In order for the generated optic to be well-defined, you must ensure that the input functions constitute a legal lens:

• sa (sbt s a) ≡ a

• sbt s (sa s) ≡ s

• sbt (sbt s a1) a2 ≡ sbt s a2

See Property.

The resulting optic can detect copies of the lens stucture inside any Traversable container. For example:

>>> lists (traversing snd $ \(s,_) b -> (s,b)) [(0,'f'),(1,'o'),(2,'o'),(3,'b'),(4,'a'),(5,'r')]
"foobar"

Obtain a Ixtraversal by lifting an indexed lens getter and setter into a Traversable functor.

 withIxlens o ixtraversing ≡ ixtraversed . o

Caution: In order for the generated optic to be well-defined, you must ensure that the input functions constitute a legal indexed lens:

• snd . sia (sbt s a) ≡ a

• sbt s (snd $ sia s) ≡ s

• sbt (sbt s a1) a2 ≡ sbt s a2

See Property.

Obtain a profunctor Traversal from a Van Laarhoven Traversal.

Caution: In order for the generated optic to be well-defined, you must ensure that the input satisfies the following properties:

• abst pure ≡ pure

• fmap (abst f) . abst g ≡ getCompose . abst (Compose . fmap f . g)

See Property.

Lift an indexed VL traversal into an indexed profunctor traversal.

Caution: In order for the generated optic to be well-defined, you must ensure that the input satisfies the following properties:

• iabst (const pure) ≡ pure

• fmap (iabst $ const f) . (iabst $ const g) ≡ getCompose . iabst (const $ Compose . fmap f . g)

See Property.

Lift a VL traversal into an indexed profunctor traversal that ignores its input.

Useful as the first optic in a chain when no indexed equivalent is at hand.

>>> ixlists (noix traversed . ixtraversed) ["foo", "bar"]
[(0,'f'),(1,'o'),(2,'o'),(0,'b'),(1,'a'),(2,'r')]

>>> ixlists (ixtraversed . noix traversed) ["foo", "bar"]
[(0,'f'),(0,'o'),(0,'o'),(0,'b'),(0,'a'),(0,'r')]

Index a traversal with a Semiring.

>>> ixlists (ix traversed . ix traversed) ["foo", "bar"]
[((),'f'),((),'o'),((),'o'),((),'b'),((),'a'),((),'r')]

>>> ixlists (ix @Int traversed . ix traversed) ["foo", "bar"]
[(0,'f'),(1,'o'),(2,'o'),(0,'b'),(1,'a'),(2,'r')]

>>> ixlists (ix @[()] traversed . ix traversed) ["foo", "bar"]
[([],'f'),([()],'o'),([(),()],'o'),([],'b'),([()],'a'),([(),()],'r')]

>>> ixlists (ix @[()] traversed % ix traversed) ["foo", "bar"]
[([],'f'),([()],'o'),([(),()],'o'),([()],'b'),([(),()],'a'),([(),(),()],'r')]

The traversal laws can be stated in terms of withTraversal:

Identity:

withTraversal t (Identity . f) ≡  Identity (fmap f)

Composition:

Compose . fmap (withTraversal t f) . withTraversal t g ≡ withTraversal t (Compose . fmap f . g)

withTraversal :: Functor f => Lens s t a b -> (a -> f b) -> s -> f t
withTraversal :: Applicative f => Traversal s t a b -> (a -> f b) -> s -> f t

TODO: Document

TODO: Document

>>> withTraversal both (pure . length) ("hello","world")
(5,5)

Duplicate the results of any Fold.

>>> lists (both . duplicated) ("hello","world")
["hello","hello","world","world"]

Traverse both parts of a Bitraversable container with matching types.

>>> withTraversal bitraversed (pure . length) (Right "hello")
Right 5

>>> withTraversal bitraversed (pure . length) ("hello","world")
(5,5)

>>> ("hello","world") ^. bitraversed
"helloworld"

bitraversed :: Traversal (a , a) (b , b) a b
bitraversed :: Traversal (a + a) (b + b) a b

TODO: Document

Lift a Functor into a Profunctor (forwards).

Lift a Functor into a Profunctor (backwards).

A Profunctor p is Representable if there exists a Functor f such that p d c is isomorphic to d -> f c.

A Profunctor p is Corepresentable if there exists a Functor f such that p d c is isomorphic to f d -> c.