Module

# Data.Lens.Traversal

Package
purescript-profunctor-lenses
Repository
purescript-contrib/purescript-profunctor-lenses

`Traversal` is an optic that focuses on zero or more values. An `Array` would be a typical example:

``````over    traversed negate [1, 2, 3] == [-1, -2, -3]
preview traversed [1, 2, 3] == Just 1
firstOf traversed [1, 2, 3] == Just 1  -- same as `preview`
lastOf  traversed [1, 2, 3] == Just 3
``````

`view` might surprise you. It assumes that the wrapped values are a monoid, and `append`s them together:

``````view traversed ["D", "a", "w", "n"] == "Dawn"
``````

Many of the functions you'll use are documented in `Data.Lens.Fold`.

### #traversedSource

``traversed :: forall b a t. Traversable t => Traversal (t a) (t b) a b``

A `Traversal` for the elements of a `Traversable` functor.

``````over traversed negate [1, 2, 3] == [-1,-2,-3]
over traversed negate (Just 3) == Just -3
``````

### #elementSource

``element :: forall a t s p. Wander p => Int -> Traversal s t a a -> Optic p s t a a``

Combine an index and a traversal to narrow the focus to a single element. Compare to `Data.Lens.Index`.

``````set     (element 2 traversed) 8888 [0, 0, 3] == [0, 0, 8888]
preview (element 2 traversed)      [0, 0, 3] == Just 3
``````

The resulting traversal is called an affine traversal, which means that the traversal focuses on one or zero (if the index is out of range) results.

### #traverseOfSource

``traverseOf :: forall b a t s f. Applicative f => Optic (Star f) s t a b -> (a -> f b) -> s -> f t``

Turn a pure profunctor `Traversal` into a `lens`-like `Traversal`.

### #sequenceOfSource

``sequenceOf :: forall a t s f. Applicative f => Optic (Star f) s t (f a) a -> s -> f t``

Sequence the foci of a `Traversal`, pulling out an `Applicative` effect. If you do not need the result, see `sequenceOf_` for `Fold`s.

`sequenceOf traversed` has the same result as `Data.Traversable.sequence`:

``````sequenceOf traversed (Just [1, 2]) == [Just 1, Just 2]
sequence             (Just [1, 2]) == [Just 1, Just 2]
``````

An example with effects:

``````> array = [random, random]
> :t array
Array (Eff ... Number)

> effect = sequenceOf traversed array
> :t effect
Eff ... (Array Number)

> effect >>= logShow
[0.15556037108154985,0.28500369615270515]
unit
``````

### #failoverSource

``failover :: forall b a t s f. Alternative f => Optic (Star (Tuple (Disj Boolean))) s t a b -> (a -> b) -> s -> f t``

Tries to map over a `Traversal`; returns `empty` if the traversal did not have any new focus.

### #elementsOfSource

``elementsOf :: forall a t s i p. Wander p => IndexedTraversal i s t a a -> (i -> Boolean) -> IndexedOptic p i s t a a``

Traverse elements of an `IndexedTraversal` whose index satisfy a predicate.

### #itraverseOfSource

``itraverseOf :: forall b a t s i f. Applicative f => IndexedOptic (Star f) i s t a b -> (i -> a -> f b) -> s -> f t``

Turn a pure profunctor `IndexedTraversal` into a `lens`-like `IndexedTraversal`.

## Re-exports from Data.Lens.Types

### #Traversal'Source

``type Traversal' s a = Traversal s s a a``

### #TraversalSource

``type Traversal s t a b = forall p. Wander p => Optic p s t a b``

A traversal.