Copyright | (C) 2012-16 Edward Kmett |
---|---|

License | BSD-style (see the file LICENSE) |

Maintainer | Edward Kmett <ekmett@gmail.com> |

Stability | provisional |

Portability | Rank2Types |

Safe Haskell | Trustworthy |

Language | Haskell2010 |

A
```
```

is a generalization of something
```
Fold
```

s a
```
Foldable
```

. It allows
you to extract multiple results from a container. A
```
Foldable
```

container
can be characterized by the behavior of
```
```

.
Since we want to be able to work with monomorphic containers, we could
generalize this signature to
```
foldMap
```

:: (
```
Foldable
```

t,
```
Monoid
```

m) => (a -> m) -> t a -> m
```
forall m.
```

,
and then decorate it with
```
Monoid
```

m => (a -> m) -> s -> m
```
Const
```

to obtain

type`Fold`

s a = forall m.`Monoid`

m =>`Getting`

m s a

Every
```
Getter
```

is a valid
```
Fold
```

that simply doesn't use the
```
Monoid
```

it is passed.

In practice the type we use is slightly more complicated to allow for
better error messages and for it to be transformed by certain
```
Applicative
```

transformers.

Everything you can do with a
```
Foldable
```

container, you can with with a
```
Fold
```

and there are
combinators that generalize the usual
```
Foldable
```

operations here.

## Synopsis

- type Fold s a = forall f. ( Contravariant f, Applicative f) => (a -> f a) -> s -> f s
- type IndexedFold i s a = forall p f. ( Indexable i p, Contravariant f, Applicative f) => p a (f a) -> s -> f s
- (^..) :: s -> Getting ( Endo [a]) s a -> [a]
- (^?) :: s -> Getting ( First a) s a -> Maybe a
- (^?!) :: HasCallStack => s -> Getting ( Endo a) s a -> a
- pre :: Getting ( First a) s a -> IndexPreservingGetter s ( Maybe a)
- ipre :: IndexedGetting i ( First (i, a)) s a -> IndexPreservingGetter s ( Maybe (i, a))
- preview :: MonadReader s m => Getting ( First a) s a -> m ( Maybe a)
- previews :: MonadReader s m => Getting ( First r) s a -> (a -> r) -> m ( Maybe r)
- ipreview :: MonadReader s m => IndexedGetting i ( First (i, a)) s a -> m ( Maybe (i, a))
- ipreviews :: MonadReader s m => IndexedGetting i ( First r) s a -> (i -> a -> r) -> m ( Maybe r)
- preuse :: MonadState s m => Getting ( First a) s a -> m ( Maybe a)
- preuses :: MonadState s m => Getting ( First r) s a -> (a -> r) -> m ( Maybe r)
- ipreuse :: MonadState s m => IndexedGetting i ( First (i, a)) s a -> m ( Maybe (i, a))
- ipreuses :: MonadState s m => IndexedGetting i ( First r) s a -> (i -> a -> r) -> m ( Maybe r)
- has :: Getting Any s a -> s -> Bool
- hasn't :: Getting All s a -> s -> Bool
- folding :: Foldable f => (s -> f a) -> Fold s a
- ifolding :: ( Foldable f, Indexable i p, Contravariant g, Applicative g) => (s -> f (i, a)) -> Over p g s t a b
- foldring :: ( Contravariant f, Applicative f) => ((a -> f a -> f a) -> f a -> s -> f a) -> LensLike f s t a b
- ifoldring :: ( Indexable i p, Contravariant f, Applicative f) => ((i -> a -> f a -> f a) -> f a -> s -> f a) -> Over p f s t a b
- folded :: Foldable f => IndexedFold Int (f a) a
- folded64 :: Foldable f => IndexedFold Int64 (f a) a
- unfolded :: (b -> Maybe (a, b)) -> Fold b a
- iterated :: Apply f => (a -> a) -> LensLike' f a a
- filtered :: ( Choice p, Applicative f) => (a -> Bool ) -> Optic' p f a a
- filteredBy :: ( Indexable i p, Applicative f) => Getting ( First i) a i -> p a (f a) -> a -> f a
- backwards :: ( Profunctor p, Profunctor q) => Optical p q ( Backwards f) s t a b -> Optical p q f s t a b
- repeated :: Apply f => LensLike' f a a
- replicated :: Int -> Fold a a
- cycled :: Apply f => LensLike f s t a b -> LensLike f s t a b
- takingWhile :: ( Conjoined p, Applicative f) => (a -> Bool ) -> Over p ( TakingWhile p f a a) s t a a -> Over p f s t a a
- droppingWhile :: ( Conjoined p, Profunctor q, Applicative f) => (a -> Bool ) -> Optical p q ( Compose ( State Bool ) f) s t a a -> Optical p q f s t a a
- worded :: Applicative f => IndexedLensLike' Int f String String
- lined :: Applicative f => IndexedLensLike' Int f String String
- foldMapOf :: Getting r s a -> (a -> r) -> s -> r
- foldOf :: Getting a s a -> s -> a
- foldrOf :: Getting ( Endo r) s a -> (a -> r -> r) -> r -> s -> r
- foldlOf :: Getting ( Dual ( Endo r)) s a -> (r -> a -> r) -> r -> s -> r
- toListOf :: Getting ( Endo [a]) s a -> s -> [a]
- toNonEmptyOf :: Getting ( NonEmptyDList a) s a -> s -> NonEmpty a
- anyOf :: Getting Any s a -> (a -> Bool ) -> s -> Bool
- allOf :: Getting All s a -> (a -> Bool ) -> s -> Bool
- noneOf :: Getting Any s a -> (a -> Bool ) -> s -> Bool
- andOf :: Getting All s Bool -> s -> Bool
- orOf :: Getting Any s Bool -> s -> Bool
- productOf :: Num a => Getting ( Endo ( Endo a)) s a -> s -> a
- sumOf :: Num a => Getting ( Endo ( Endo a)) s a -> s -> a
- traverseOf_ :: Functor f => Getting ( Traversed r f) s a -> (a -> f r) -> s -> f ()
- forOf_ :: Functor f => Getting ( Traversed r f) s a -> s -> (a -> f r) -> f ()
- sequenceAOf_ :: Functor f => Getting ( Traversed a f) s (f a) -> s -> f ()
- traverse1Of_ :: Functor f => Getting ( TraversedF r f) s a -> (a -> f r) -> s -> f ()
- for1Of_ :: Functor f => Getting ( TraversedF r f) s a -> s -> (a -> f r) -> f ()
- sequence1Of_ :: Functor f => Getting ( TraversedF a f) s (f a) -> s -> f ()
- mapMOf_ :: Monad m => Getting ( Sequenced r m) s a -> (a -> m r) -> s -> m ()
- forMOf_ :: Monad m => Getting ( Sequenced r m) s a -> s -> (a -> m r) -> m ()
- sequenceOf_ :: Monad m => Getting ( Sequenced a m) s (m a) -> s -> m ()
- asumOf :: Alternative f => Getting ( Endo (f a)) s (f a) -> s -> f a
- msumOf :: MonadPlus m => Getting ( Endo (m a)) s (m a) -> s -> m a
- concatMapOf :: Getting [r] s a -> (a -> [r]) -> s -> [r]
- concatOf :: Getting [r] s [r] -> s -> [r]
- elemOf :: Eq a => Getting Any s a -> a -> s -> Bool
- notElemOf :: Eq a => Getting All s a -> a -> s -> Bool
- lengthOf :: Getting ( Endo ( Endo Int )) s a -> s -> Int
- nullOf :: Getting All s a -> s -> Bool
- notNullOf :: Getting Any s a -> s -> Bool
- firstOf :: Getting ( Leftmost a) s a -> s -> Maybe a
- first1Of :: Getting ( First a) s a -> s -> a
- lastOf :: Getting ( Rightmost a) s a -> s -> Maybe a
- last1Of :: Getting ( Last a) s a -> s -> a
- maximumOf :: Ord a => Getting ( Endo ( Endo ( Maybe a))) s a -> s -> Maybe a
- maximum1Of :: Ord a => Getting ( Max a) s a -> s -> a
- minimumOf :: Ord a => Getting ( Endo ( Endo ( Maybe a))) s a -> s -> Maybe a
- minimum1Of :: Ord a => Getting ( Min a) s a -> s -> a
- maximumByOf :: Getting ( Endo ( Endo ( Maybe a))) s a -> (a -> a -> Ordering ) -> s -> Maybe a
- minimumByOf :: Getting ( Endo ( Endo ( Maybe a))) s a -> (a -> a -> Ordering ) -> s -> Maybe a
- findOf :: Getting ( Endo ( Maybe a)) s a -> (a -> Bool ) -> s -> Maybe a
- findMOf :: Monad m => Getting ( Endo (m ( Maybe a))) s a -> (a -> m Bool ) -> s -> m ( Maybe a)
- foldrOf' :: Getting ( Dual ( Endo ( Endo r))) s a -> (a -> r -> r) -> r -> s -> r
- foldlOf' :: Getting ( Endo ( Endo r)) s a -> (r -> a -> r) -> r -> s -> r
- foldr1Of :: HasCallStack => Getting ( Endo ( Maybe a)) s a -> (a -> a -> a) -> s -> a
- foldl1Of :: HasCallStack => Getting ( Dual ( Endo ( Maybe a))) s a -> (a -> a -> a) -> s -> a
- foldr1Of' :: HasCallStack => Getting ( Dual ( Endo ( Endo ( Maybe a)))) s a -> (a -> a -> a) -> s -> a
- foldl1Of' :: HasCallStack => Getting ( Endo ( Endo ( Maybe a))) s a -> (a -> a -> a) -> s -> a
- foldrMOf :: Monad m => Getting ( Dual ( Endo (r -> m r))) s a -> (a -> r -> m r) -> r -> s -> m r
- foldlMOf :: Monad m => Getting ( Endo (r -> m r)) s a -> (r -> a -> m r) -> r -> s -> m r
- lookupOf :: Eq k => Getting ( Endo ( Maybe v)) s (k, v) -> k -> s -> Maybe v
- (^@..) :: s -> IndexedGetting i ( Endo [(i, a)]) s a -> [(i, a)]
- (^@?) :: s -> IndexedGetting i ( Endo ( Maybe (i, a))) s a -> Maybe (i, a)
- (^@?!) :: HasCallStack => s -> IndexedGetting i ( Endo (i, a)) s a -> (i, a)
- ifoldMapOf :: IndexedGetting i m s a -> (i -> a -> m) -> s -> m
- ifoldrOf :: IndexedGetting i ( Endo r) s a -> (i -> a -> r -> r) -> r -> s -> r
- ifoldlOf :: IndexedGetting i ( Dual ( Endo r)) s a -> (i -> r -> a -> r) -> r -> s -> r
- ianyOf :: IndexedGetting i Any s a -> (i -> a -> Bool ) -> s -> Bool
- iallOf :: IndexedGetting i All s a -> (i -> a -> Bool ) -> s -> Bool
- inoneOf :: IndexedGetting i Any s a -> (i -> a -> Bool ) -> s -> Bool
- itraverseOf_ :: Functor f => IndexedGetting i ( Traversed r f) s a -> (i -> a -> f r) -> s -> f ()
- iforOf_ :: Functor f => IndexedGetting i ( Traversed r f) s a -> s -> (i -> a -> f r) -> f ()
- imapMOf_ :: Monad m => IndexedGetting i ( Sequenced r m) s a -> (i -> a -> m r) -> s -> m ()
- iforMOf_ :: Monad m => IndexedGetting i ( Sequenced r m) s a -> s -> (i -> a -> m r) -> m ()
- iconcatMapOf :: IndexedGetting i [r] s a -> (i -> a -> [r]) -> s -> [r]
- ifindOf :: IndexedGetting i ( Endo ( Maybe a)) s a -> (i -> a -> Bool ) -> s -> Maybe a
- ifindMOf :: Monad m => IndexedGetting i ( Endo (m ( Maybe a))) s a -> (i -> a -> m Bool ) -> s -> m ( Maybe a)
- ifoldrOf' :: IndexedGetting i ( Dual ( Endo (r -> r))) s a -> (i -> a -> r -> r) -> r -> s -> r
- ifoldlOf' :: IndexedGetting i ( Endo (r -> r)) s a -> (i -> r -> a -> r) -> r -> s -> r
- ifoldrMOf :: Monad m => IndexedGetting i ( Dual ( Endo (r -> m r))) s a -> (i -> a -> r -> m r) -> r -> s -> m r
- ifoldlMOf :: Monad m => IndexedGetting i ( Endo (r -> m r)) s a -> (i -> r -> a -> m r) -> r -> s -> m r
- itoListOf :: IndexedGetting i ( Endo [(i, a)]) s a -> s -> [(i, a)]
- elemIndexOf :: Eq a => IndexedGetting i ( First i) s a -> a -> s -> Maybe i
- elemIndicesOf :: Eq a => IndexedGetting i ( Endo [i]) s a -> a -> s -> [i]
- findIndexOf :: IndexedGetting i ( First i) s a -> (a -> Bool ) -> s -> Maybe i
- findIndicesOf :: IndexedGetting i ( Endo [i]) s a -> (a -> Bool ) -> s -> [i]
- ifiltered :: ( Indexable i p, Applicative f) => (i -> a -> Bool ) -> Optical' p ( Indexed i) f a a
- itakingWhile :: ( Indexable i p, Profunctor q, Contravariant f, Applicative f) => (i -> a -> Bool ) -> Optical' ( Indexed i) q ( Const ( Endo (f s))) s a -> Optical' p q f s a
- idroppingWhile :: ( Indexable i p, Profunctor q, Applicative f) => (i -> a -> Bool ) -> Optical ( Indexed i) q ( Compose ( State Bool ) f) s t a a -> Optical p q f s t a a
- data Leftmost a
- data Rightmost a
- data Traversed a f
- data Sequenced a m
- foldBy :: Foldable t => (a -> a -> a) -> a -> t a -> a
- foldByOf :: Fold s a -> (a -> a -> a) -> a -> s -> a
- foldMapBy :: Foldable t => (r -> r -> r) -> r -> (a -> r) -> t a -> r
- foldMapByOf :: Fold s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r

# Folds

type Fold s a = forall f. ( Contravariant f, Applicative f) => (a -> f a) -> s -> f s Source #

A
```
Fold
```

describes how to retrieve multiple values in a way that can be composed
with other
```
LensLike
```

constructions.

A
```
```

provides a structure with operations very similar to those of the
```
Fold
```

s a
```
Foldable
```

typeclass, see
```
foldMapOf
```

and the other
```
Fold
```

combinators.

By convention, if there exists a
```
foo
```

method that expects a
```
```

, then there should be a
```
Foldable
```

(f a)
```
fooOf
```

method that takes a
```
```

and a value of type
```
Fold
```

s a
```
s
```

.

A
```
Getter
```

is a legal
```
Fold
```

that just ignores the supplied
```
Monoid
```

.

Unlike a
```
Traversal
```

a
```
Fold
```

is read-only. Since a
```
Fold
```

cannot be used to write back
there are no
```
Lens
```

laws that apply.

type IndexedFold i s a = forall p f. ( Indexable i p, Contravariant f, Applicative f) => p a (f a) -> s -> f s Source #

Every
```
IndexedFold
```

is a valid
```
Fold
```

and can be used for
```
Getting
```

.

# Getting Started

(^..) :: s -> Getting ( Endo [a]) s a -> [a] infixl 8 Source #

A convenient infix (flipped) version of
```
toListOf
```

.

`>>>`

[[[1,2],[3]]]`[[1,2],[3]]^..id`

`>>>`

[[1,2],[3]]`[[1,2],[3]]^..traverse`

`>>>`

[1,2,3]`[[1,2],[3]]^..traverse.traverse`

`>>>`

[1,2]`(1,2)^..both`

`toList`

xs ≡ xs`^..`

`folded`

(`^..`

) ≡`flip`

`toListOf`

(`^..`

) :: s ->`Getter`

s a -> a :: s ->`Fold`

s a -> a :: s ->`Lens'`

s a -> a :: s ->`Iso'`

s a -> a :: s ->`Traversal'`

s a -> a :: s ->`Prism'`

s a -> [a]

(^?) :: s -> Getting ( First a) s a -> Maybe a infixl 8 Source #

Perform a safe
```
head
```

of a
```
Fold
```

or
```
Traversal
```

or retrieve
```
Just
```

the result
from a
```
Getter
```

or
```
Lens
```

.

When using a
```
Traversal
```

as a partial
```
Lens
```

, or a
```
Fold
```

as a partial
```
Getter
```

this can be a convenient
way to extract the optional value.

Note: if you get stack overflows due to this, you may want to use
```
firstOf
```

instead, which can deal
more gracefully with heavily left-biased trees. This is because
```
^?
```

works by using the
```
First
```

monoid, which can occasionally cause space leaks.

`>>>`

Just 4`Left 4 ^?_Left`

`>>>`

Nothing`Right 4 ^?_Left`

`>>>`

Just 'l'`"world" ^? ix 3`

`>>>`

Nothing`"world" ^? ix 20`

This operator works as an infix version of
```
preview
```

.

(`^?`

) ≡`flip`

`preview`

It may be helpful to think of
```
^?
```

as having one of the following
more specialized types:

(`^?`

) :: s ->`Getter`

s a ->`Maybe`

a (`^?`

) :: s ->`Fold`

s a ->`Maybe`

a (`^?`

) :: s ->`Lens'`

s a ->`Maybe`

a (`^?`

) :: s ->`Iso'`

s a ->`Maybe`

a (`^?`

) :: s ->`Traversal'`

s a ->`Maybe`

a

pre :: Getting ( First a) s a -> IndexPreservingGetter s ( Maybe a) Source #

This converts a
```
Fold
```

to a
```
IndexPreservingGetter
```

that returns the first element, if it
exists, as a
```
Maybe
```

.

`pre`

::`Getter`

s a ->`IndexPreservingGetter`

s (`Maybe`

a)`pre`

::`Fold`

s a ->`IndexPreservingGetter`

s (`Maybe`

a)`pre`

::`Traversal'`

s a ->`IndexPreservingGetter`

s (`Maybe`

a)`pre`

::`Lens'`

s a ->`IndexPreservingGetter`

s (`Maybe`

a)`pre`

::`Iso'`

s a ->`IndexPreservingGetter`

s (`Maybe`

a)`pre`

::`Prism'`

s a ->`IndexPreservingGetter`

s (`Maybe`

a)

ipre :: IndexedGetting i ( First (i, a)) s a -> IndexPreservingGetter s ( Maybe (i, a)) Source #

This converts an
```
IndexedFold
```

to an
```
IndexPreservingGetter
```

that returns the first index
and element, if they exist, as a
```
Maybe
```

.

`ipre`

::`IndexedGetter`

i s a ->`IndexPreservingGetter`

s (`Maybe`

(i, a))`ipre`

::`IndexedFold`

i s a ->`IndexPreservingGetter`

s (`Maybe`

(i, a))`ipre`

::`IndexedTraversal'`

i s a ->`IndexPreservingGetter`

s (`Maybe`

(i, a))`ipre`

::`IndexedLens'`

i s a ->`IndexPreservingGetter`

s (`Maybe`

(i, a))

preview :: MonadReader s m => Getting ( First a) s a -> m ( Maybe a) Source #

Retrieve the first value targeted by a
```
Fold
```

or
```
Traversal
```

(or
```
Just
```

the result
from a
```
Getter
```

or
```
Lens
```

). See also
```
firstOf
```

and
```
^?
```

, which are similar with
some subtle differences (explained below).

`listToMaybe`

`.`

`toList`

≡`preview`

`folded`

`preview`

=`view`

`.`

`pre`

Unlike
```
^?
```

, this function uses a
```
MonadReader
```

to read the value to be focused in on.
This allows one to pass the value as the last argument by using the
```
MonadReader
```

instance for
```
(->) s
```

However, it may also be used as part of some deeply nested transformer stack.

```
preview
```

uses a monoidal value to obtain the result.
This means that it generally has good performance, but can occasionally cause space leaks
or even stack overflows on some data types.
There is another function,
```
firstOf
```

, which avoids these issues at the cost of
a slight constant performance cost and a little less flexibility.

It may be helpful to think of
```
preview
```

as having one of the following
more specialized types:

`preview`

::`Getter`

s a -> s ->`Maybe`

a`preview`

::`Fold`

s a -> s ->`Maybe`

a`preview`

::`Lens'`

s a -> s ->`Maybe`

a`preview`

::`Iso'`

s a -> s ->`Maybe`

a`preview`

::`Traversal'`

s a -> s ->`Maybe`

a

`preview`

::`MonadReader`

s m =>`Getter`

s a -> m (`Maybe`

a)`preview`

::`MonadReader`

s m =>`Fold`

s a -> m (`Maybe`

a)`preview`

::`MonadReader`

s m =>`Lens'`

s a -> m (`Maybe`

a)`preview`

::`MonadReader`

s m =>`Iso'`

s a -> m (`Maybe`

a)`preview`

::`MonadReader`

s m =>`Traversal'`

s a -> m (`Maybe`

a)

ipreview :: MonadReader s m => IndexedGetting i ( First (i, a)) s a -> m ( Maybe (i, a)) Source #

Retrieve the first index and value targeted by a
```
Fold
```

or
```
Traversal
```

(or
```
Just
```

the result
from a
```
Getter
```

or
```
Lens
```

). See also (
```
^@?
```

).

`ipreview`

=`view`

`.`

`ipre`

This is usually applied in the
```
Reader
```

```
Monad
```

```
(->) s
```

.

`ipreview`

::`IndexedGetter`

i s a -> s ->`Maybe`

(i, a)`ipreview`

::`IndexedFold`

i s a -> s ->`Maybe`

(i, a)`ipreview`

::`IndexedLens'`

i s a -> s ->`Maybe`

(i, a)`ipreview`

::`IndexedTraversal'`

i s a -> s ->`Maybe`

(i, a)

However, it may be useful to think of its full generality when working with
a
```
Monad
```

transformer stack:

`ipreview`

::`MonadReader`

s m =>`IndexedGetter`

s a -> m (`Maybe`

(i, a))`ipreview`

::`MonadReader`

s m =>`IndexedFold`

s a -> m (`Maybe`

(i, a))`ipreview`

::`MonadReader`

s m =>`IndexedLens'`

s a -> m (`Maybe`

(i, a))`ipreview`

::`MonadReader`

s m =>`IndexedTraversal'`

s a -> m (`Maybe`

(i, a))

ipreviews :: MonadReader s m => IndexedGetting i ( First r) s a -> (i -> a -> r) -> m ( Maybe r) Source #

Retrieve a function of the first index and value targeted by an
```
IndexedFold
```

or
```
IndexedTraversal
```

(or
```
Just
```

the result from an
```
IndexedGetter
```

or
```
IndexedLens
```

).
See also (
```
^@?
```

).

`ipreviews`

=`views`

`.`

`ipre`

This is usually applied in the
```
Reader
```

```
Monad
```

```
(->) s
```

.

`ipreviews`

::`IndexedGetter`

i s a -> (i -> a -> r) -> s ->`Maybe`

r`ipreviews`

::`IndexedFold`

i s a -> (i -> a -> r) -> s ->`Maybe`

r`ipreviews`

::`IndexedLens'`

i s a -> (i -> a -> r) -> s ->`Maybe`

r`ipreviews`

::`IndexedTraversal'`

i s a -> (i -> a -> r) -> s ->`Maybe`

r

However, it may be useful to think of its full generality when working with
a
```
Monad
```

transformer stack:

`ipreviews`

::`MonadReader`

s m =>`IndexedGetter`

i s a -> (i -> a -> r) -> m (`Maybe`

r)`ipreviews`

::`MonadReader`

s m =>`IndexedFold`

i s a -> (i -> a -> r) -> m (`Maybe`

r)`ipreviews`

::`MonadReader`

s m =>`IndexedLens'`

i s a -> (i -> a -> r) -> m (`Maybe`

r)`ipreviews`

::`MonadReader`

s m =>`IndexedTraversal'`

i s a -> (i -> a -> r) -> m (`Maybe`

r)

preuse :: MonadState s m => Getting ( First a) s a -> m ( Maybe a) Source #

Retrieve the first value targeted by a
```
Fold
```

or
```
Traversal
```

(or
```
Just
```

the result
from a
```
Getter
```

or
```
Lens
```

) into the current state.

`preuse`

=`use`

`.`

`pre`

`preuse`

::`MonadState`

s m =>`Getter`

s a -> m (`Maybe`

a)`preuse`

::`MonadState`

s m =>`Fold`

s a -> m (`Maybe`

a)`preuse`

::`MonadState`

s m =>`Lens'`

s a -> m (`Maybe`

a)`preuse`

::`MonadState`

s m =>`Iso'`

s a -> m (`Maybe`

a)`preuse`

::`MonadState`

s m =>`Traversal'`

s a -> m (`Maybe`

a)

preuses :: MonadState s m => Getting ( First r) s a -> (a -> r) -> m ( Maybe r) Source #

Retrieve a function of the first value targeted by a
```
Fold
```

or
```
Traversal
```

(or
```
Just
```

the result from a
```
Getter
```

or
```
Lens
```

) into the current state.

`preuses`

=`uses`

`.`

`pre`

`preuses`

::`MonadState`

s m =>`Getter`

s a -> (a -> r) -> m (`Maybe`

r)`preuses`

::`MonadState`

s m =>`Fold`

s a -> (a -> r) -> m (`Maybe`

r)`preuses`

::`MonadState`

s m =>`Lens'`

s a -> (a -> r) -> m (`Maybe`

r)`preuses`

::`MonadState`

s m =>`Iso'`

s a -> (a -> r) -> m (`Maybe`

r)`preuses`

::`MonadState`

s m =>`Traversal'`

s a -> (a -> r) -> m (`Maybe`

r)

ipreuse :: MonadState s m => IndexedGetting i ( First (i, a)) s a -> m ( Maybe (i, a)) Source #

Retrieve the first index and value targeted by an
```
IndexedFold
```

or
```
IndexedTraversal
```

(or
```
Just
```

the index
and result from an
```
IndexedGetter
```

or
```
IndexedLens
```

) into the current state.

`ipreuse`

=`use`

`.`

`ipre`

`ipreuse`

::`MonadState`

s m =>`IndexedGetter`

i s a -> m (`Maybe`

(i, a))`ipreuse`

::`MonadState`

s m =>`IndexedFold`

i s a -> m (`Maybe`

(i, a))`ipreuse`

::`MonadState`

s m =>`IndexedLens'`

i s a -> m (`Maybe`

(i, a))`ipreuse`

::`MonadState`

s m =>`IndexedTraversal'`

i s a -> m (`Maybe`

(i, a))

ipreuses :: MonadState s m => IndexedGetting i ( First r) s a -> (i -> a -> r) -> m ( Maybe r) Source #

Retrieve a function of the first index and value targeted by an
```
IndexedFold
```

or
```
IndexedTraversal
```

(or a function of
```
Just
```

the index and result from an
```
IndexedGetter
```

or
```
IndexedLens
```

) into the current state.

`ipreuses`

=`uses`

`.`

`ipre`

`ipreuses`

::`MonadState`

s m =>`IndexedGetter`

i s a -> (i -> a -> r) -> m (`Maybe`

r)`ipreuses`

::`MonadState`

s m =>`IndexedFold`

i s a -> (i -> a -> r) -> m (`Maybe`

r)`ipreuses`

::`MonadState`

s m =>`IndexedLens'`

i s a -> (i -> a -> r) -> m (`Maybe`

r)`ipreuses`

::`MonadState`

s m =>`IndexedTraversal'`

i s a -> (i -> a -> r) -> m (`Maybe`

r)

has :: Getting Any s a -> s -> Bool Source #

Check to see if this
```
Fold
```

or
```
Traversal
```

matches 1 or more entries.

`>>>`

False`has (element 0) []`

`>>>`

True`has _Left (Left 12)`

`>>>`

False`has _Right (Left 12)`

This will always return
```
True
```

for a
```
Lens
```

or
```
Getter
```

.

`>>>`

True`has _1 ("hello","world")`

`has`

::`Getter`

s a -> s ->`Bool`

`has`

::`Fold`

s a -> s ->`Bool`

`has`

::`Iso'`

s a -> s ->`Bool`

`has`

::`Lens'`

s a -> s ->`Bool`

`has`

::`Traversal'`

s a -> s ->`Bool`

## Building Folds

ifolding :: ( Foldable f, Indexable i p, Contravariant g, Applicative g) => (s -> f (i, a)) -> Over p g s t a b Source #

foldring :: ( Contravariant f, Applicative f) => ((a -> f a -> f a) -> f a -> s -> f a) -> LensLike f s t a b Source #

ifoldring :: ( Indexable i p, Contravariant f, Applicative f) => ((i -> a -> f a -> f a) -> f a -> s -> f a) -> Over p f s t a b Source #

Obtain
```
FoldWithIndex
```

by lifting
```
ifoldr
```

like function.

filtered :: ( Choice p, Applicative f) => (a -> Bool ) -> Optic' p f a a Source #

Obtain a
```
Fold
```

that can be composed with to filter another
```
Lens
```

,
```
Iso
```

,
```
Getter
```

,
```
Fold
```

(or
```
Traversal
```

).

Note: This is
*
not
*
a legal
```
Traversal
```

, unless you are very careful not to invalidate the predicate on the target.

Note: This is also
*
not
*
a legal
```
Prism
```

, unless you are very careful not to inject a value that fails the predicate.

As a counter example, consider that given
```
evens =
```

the second
```
filtered
```

```
even
```

```
Traversal
```

law is violated:

`over`

evens`succ`

`.`

`over`

evens`succ`

`/=`

`over`

evens (`succ`

`.`

`succ`

)

So, in order for this to qualify as a legal
```
Traversal
```

you can only use it for actions that preserve the result of the predicate!

`>>>`

[2,4,6,8,10]`[1..10]^..folded.filtered even`

This will preserve an index if it is present.

filteredBy :: ( Indexable i p, Applicative f) => Getting ( First i) a i -> p a (f a) -> a -> f a Source #

Obtain a potentially empty
```
IndexedTraversal
```

by taking the first element from another,
potentially empty
```
Fold
```

and using it as an index.

The resulting optic can be composed with to filter another
```
Lens
```

,
```
Iso
```

,
```
Getter
```

,
```
Fold
```

(or
```
Traversal
```

).

`>>>`

[(Just 2,6),(Nothing,4)]`[(Just 2, 3), (Nothing, 4)] & mapped . filteredBy (_1 . _Just) <. _2 %@~ (*) :: [(Maybe Int, Int)]`

`filteredBy`

::`Fold`

a i ->`IndexedTraversal'`

i a a

Note: As with
```
filtered
```

, this is
*
not
*
a legal
```
IndexedTraversal
```

, unless you are very careful not to invalidate the predicate on the target!

backwards :: ( Profunctor p, Profunctor q) => Optical p q ( Backwards f) s t a b -> Optical p q f s t a b Source #

This allows you to
```
traverse
```

the elements of a pretty much any
```
LensLike
```

construction in the opposite order.

This will preserve indexes on
```
Indexed
```

types and will give you the elements of a (finite)
```
Fold
```

or
```
Traversal
```

in the opposite order.

This has no practical impact on a
```
Getter
```

,
```
Setter
```

,
```
Lens
```

or
```
Iso
```

.

*
NB:
*
To write back through an
```
Iso
```

, you want to use
```
from
```

.
Similarly, to write back through an
```
Prism
```

, you want to use
```
re
```

.

replicated :: Int -> Fold a a Source #

A
```
Fold
```

that replicates its input
```
n
```

times.

`replicate`

n ≡`toListOf`

(`replicated`

n)

`>>>`

[5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5]`5^..replicated 20`

takingWhile :: ( Conjoined p, Applicative f) => (a -> Bool ) -> Over p ( TakingWhile p f a a) s t a a -> Over p f s t a a Source #

Obtain a
```
Fold
```

by taking elements from another
```
Fold
```

,
```
Lens
```

,
```
Iso
```

,
```
Getter
```

or
```
Traversal
```

while a predicate holds.

`takeWhile`

p ≡`toListOf`

(`takingWhile`

p`folded`

)

`>>>`

[1,2,3]`timingOut $ toListOf (takingWhile (<=3) folded) [1..]`

`takingWhile`

:: (a ->`Bool`

) ->`Fold`

s a ->`Fold`

s a`takingWhile`

:: (a ->`Bool`

) ->`Getter`

s a ->`Fold`

s a`takingWhile`

:: (a ->`Bool`

) ->`Traversal'`

s a ->`Fold`

s a -- * See note below`takingWhile`

:: (a ->`Bool`

) ->`Lens'`

s a ->`Fold`

s a -- * See note below`takingWhile`

:: (a ->`Bool`

) ->`Prism'`

s a ->`Fold`

s a -- * See note below`takingWhile`

:: (a ->`Bool`

) ->`Iso'`

s a ->`Fold`

s a -- * See note below`takingWhile`

:: (a ->`Bool`

) ->`IndexedTraversal'`

i s a ->`IndexedFold`

i s a -- * See note below`takingWhile`

:: (a ->`Bool`

) ->`IndexedLens'`

i s a ->`IndexedFold`

i s a -- * See note below`takingWhile`

:: (a ->`Bool`

) ->`IndexedFold`

i s a ->`IndexedFold`

i s a`takingWhile`

:: (a ->`Bool`

) ->`IndexedGetter`

i s a ->`IndexedFold`

i s a

*
Note:
*
When applied to a
```
Traversal
```

,
```
takingWhile
```

yields something that can be used as if it were a
```
Traversal
```

, but
which is not a
```
Traversal
```

per the laws, unless you are careful to ensure that you do not invalidate the predicate when
writing back through it.

droppingWhile :: ( Conjoined p, Profunctor q, Applicative f) => (a -> Bool ) -> Optical p q ( Compose ( State Bool ) f) s t a a -> Optical p q f s t a a Source #

Obtain a
```
Fold
```

by dropping elements from another
```
Fold
```

,
```
Lens
```

,
```
Iso
```

,
```
Getter
```

or
```
Traversal
```

while a predicate holds.

`dropWhile`

p ≡`toListOf`

(`droppingWhile`

p`folded`

)

`>>>`

[4,5,6]`toListOf (droppingWhile (<=3) folded) [1..6]`

`>>>`

[6,1]`toListOf (droppingWhile (<=3) folded) [1,6,1]`

`droppingWhile`

:: (a ->`Bool`

) ->`Fold`

s a ->`Fold`

s a`droppingWhile`

:: (a ->`Bool`

) ->`Getter`

s a ->`Fold`

s a`droppingWhile`

:: (a ->`Bool`

) ->`Traversal'`

s a ->`Fold`

s a -- see notes`droppingWhile`

:: (a ->`Bool`

) ->`Lens'`

s a ->`Fold`

s a -- see notes`droppingWhile`

:: (a ->`Bool`

) ->`Prism'`

s a ->`Fold`

s a -- see notes`droppingWhile`

:: (a ->`Bool`

) ->`Iso'`

s a ->`Fold`

s a -- see notes

`droppingWhile`

:: (a ->`Bool`

) ->`IndexPreservingTraversal'`

s a ->`IndexPreservingFold`

s a -- see notes`droppingWhile`

:: (a ->`Bool`

) ->`IndexPreservingLens'`

s a ->`IndexPreservingFold`

s a -- see notes`droppingWhile`

:: (a ->`Bool`

) ->`IndexPreservingGetter`

s a ->`IndexPreservingFold`

s a`droppingWhile`

:: (a ->`Bool`

) ->`IndexPreservingFold`

s a ->`IndexPreservingFold`

s a

`droppingWhile`

:: (a ->`Bool`

) ->`IndexedTraversal'`

i s a ->`IndexedFold`

i s a -- see notes`droppingWhile`

:: (a ->`Bool`

) ->`IndexedLens'`

i s a ->`IndexedFold`

i s a -- see notes`droppingWhile`

:: (a ->`Bool`

) ->`IndexedGetter`

i s a ->`IndexedFold`

i s a`droppingWhile`

:: (a ->`Bool`

) ->`IndexedFold`

i s a ->`IndexedFold`

i s a

Note: Many uses of this combinator will yield something that meets the types, but not the laws of a valid
```
Traversal
```

or
```
IndexedTraversal
```

. The
```
Traversal
```

and
```
IndexedTraversal
```

laws are only satisfied if the
new values you assign to the first target also does not pass the predicate! Otherwise subsequent traversals
will visit fewer elements and
```
Traversal
```

fusion is not sound.

So for any traversal
```
t
```

and predicate
```
p
```

,
```
```

may not be lawful, but
```
droppingWhile
```

p t
```
(
```

is. For example:
```
dropping
```

1 .
```
droppingWhile
```

p) t

`>>>`

`let l :: Traversal' [Int] Int; l = droppingWhile (<= 1) traverse`

`>>>`

`let l' :: Traversal' [Int] Int; l' = dropping 1 l`

```
l
```

is not a lawful setter because
```
```

:
```
over
```

l f .
```
over
```

l g ≢
```
over
```

l (f . g)

`>>>`

[1,0,0]`[1,2,3] & l .~ 0 & l .~ 4`

`>>>`

[1,4,4]`[1,2,3] & l .~ 4`

```
l'
```

on the other hand behaves lawfully:

`>>>`

[1,2,4]`[1,2,3] & l' .~ 0 & l' .~ 4`

`>>>`

[1,2,4]`[1,2,3] & l' .~ 4`

worded :: Applicative f => IndexedLensLike' Int f String String Source #

A
```
Fold
```

over the individual
```
words
```

of a
```
String
```

.

`worded`

::`Fold`

`String`

`String`

`worded`

::`Traversal'`

`String`

`String`

`worded`

::`IndexedFold`

`Int`

`String`

`String`

`worded`

::`IndexedTraversal'`

`Int`

`String`

`String`

Note: This function type-checks as a
```
Traversal
```

but it doesn't satisfy the laws. It's only valid to use it
when you don't insert any whitespace characters while traversing, and if your original
```
String
```

contains only
isolated space characters (and no other characters that count as space, such as non-breaking spaces).

lined :: Applicative f => IndexedLensLike' Int f String String Source #

A
```
Fold
```

over the individual
```
lines
```

of a
```
String
```

.

`lined`

::`Fold`

`String`

`String`

`lined`

::`Traversal'`

`String`

`String`

`lined`

::`IndexedFold`

`Int`

`String`

`String`

`lined`

::`IndexedTraversal'`

`Int`

`String`

`String`

Note: This function type-checks as a
```
Traversal
```

but it doesn't satisfy the laws. It's only valid to use it
when you don't insert any newline characters while traversing, and if your original
```
String
```

contains only
isolated newline characters.

## Folding

foldMapOf :: Getting r s a -> (a -> r) -> s -> r Source #

Map each part of a structure viewed through a
```
Lens
```

,
```
Getter
```

,
```
Fold
```

or
```
Traversal
```

to a monoid and combine the results.

`>>>`

Sum {getSum = 42}`foldMapOf (folded . both . _Just) Sum [(Just 21, Just 21)]`

`foldMap`

=`foldMapOf`

`folded`

`foldMapOf`

≡`views`

`ifoldMapOf`

l =`foldMapOf`

l`.`

`Indexed`

`foldMapOf`

::`Getter`

s a -> (a -> r) -> s -> r`foldMapOf`

::`Monoid`

r =>`Fold`

s a -> (a -> r) -> s -> r`foldMapOf`

::`Semigroup`

r =>`Fold1`

s a -> (a -> r) -> s -> r`foldMapOf`

::`Lens'`

s a -> (a -> r) -> s -> r`foldMapOf`

::`Iso'`

s a -> (a -> r) -> s -> r`foldMapOf`

::`Monoid`

r =>`Traversal'`

s a -> (a -> r) -> s -> r`foldMapOf`

::`Semigroup`

r =>`Traversal1'`

s a -> (a -> r) -> s -> r`foldMapOf`

::`Monoid`

r =>`Prism'`

s a -> (a -> r) -> s -> r

`foldMapOf`

::`Getting`

r s a -> (a -> r) -> s -> r

foldOf :: Getting a s a -> s -> a Source #

Combine the elements of a structure viewed through a
```
Lens
```

,
```
Getter
```

,
```
Fold
```

or
```
Traversal
```

using a monoid.

`>>>`

Sum {getSum = 42}`foldOf (folded.folded) [[Sum 1,Sum 4],[Sum 8, Sum 8],[Sum 21]]`

`fold`

=`foldOf`

`folded`

`foldOf`

≡`view`

`foldOf`

::`Getter`

s m -> s -> m`foldOf`

::`Monoid`

m =>`Fold`

s m -> s -> m`foldOf`

::`Lens'`

s m -> s -> m`foldOf`

::`Iso'`

s m -> s -> m`foldOf`

::`Monoid`

m =>`Traversal'`

s m -> s -> m`foldOf`

::`Monoid`

m =>`Prism'`

s m -> s -> m

foldrOf :: Getting ( Endo r) s a -> (a -> r -> r) -> r -> s -> r Source #

Right-associative fold of parts of a structure that are viewed through a
```
Lens
```

,
```
Getter
```

,
```
Fold
```

or
```
Traversal
```

.

`foldr`

≡`foldrOf`

`folded`

`foldrOf`

::`Getter`

s a -> (a -> r -> r) -> r -> s -> r`foldrOf`

::`Fold`

s a -> (a -> r -> r) -> r -> s -> r`foldrOf`

::`Lens'`

s a -> (a -> r -> r) -> r -> s -> r`foldrOf`

::`Iso'`

s a -> (a -> r -> r) -> r -> s -> r`foldrOf`

::`Traversal'`

s a -> (a -> r -> r) -> r -> s -> r`foldrOf`

::`Prism'`

s a -> (a -> r -> r) -> r -> s -> r

`ifoldrOf`

l ≡`foldrOf`

l`.`

`Indexed`

`foldrOf`

::`Getting`

(`Endo`

r) s a -> (a -> r -> r) -> r -> s -> r

foldlOf :: Getting ( Dual ( Endo r)) s a -> (r -> a -> r) -> r -> s -> r Source #

Left-associative fold of the parts of a structure that are viewed through a
```
Lens
```

,
```
Getter
```

,
```
Fold
```

or
```
Traversal
```

.

`foldl`

≡`foldlOf`

`folded`

`foldlOf`

::`Getter`

s a -> (r -> a -> r) -> r -> s -> r`foldlOf`

::`Fold`

s a -> (r -> a -> r) -> r -> s -> r`foldlOf`

::`Lens'`

s a -> (r -> a -> r) -> r -> s -> r`foldlOf`

::`Iso'`

s a -> (r -> a -> r) -> r -> s -> r`foldlOf`

::`Traversal'`

s a -> (r -> a -> r) -> r -> s -> r`foldlOf`

::`Prism'`

s a -> (r -> a -> r) -> r -> s -> r

toNonEmptyOf :: Getting ( NonEmptyDList a) s a -> s -> NonEmpty a Source #

Extract a
```
NonEmpty
```

of the targets of
```
Fold1
```

.

`>>>`

"hello" :| ["world"]`toNonEmptyOf both1 ("hello", "world")`

`toNonEmptyOf`

::`Getter`

s a -> s -> NonEmpty a`toNonEmptyOf`

::`Fold1`

s a -> s -> NonEmpty a`toNonEmptyOf`

::`Lens'`

s a -> s -> NonEmpty a`toNonEmptyOf`

::`Iso'`

s a -> s -> NonEmpty a`toNonEmptyOf`

::`Traversal1'`

s a -> s -> NonEmpty a`toNonEmptyOf`

::`Prism'`

s a -> s -> NonEmpty a

anyOf :: Getting Any s a -> (a -> Bool ) -> s -> Bool Source #

Returns
```
True
```

if any target of a
```
Fold
```

satisfies a predicate.

`>>>`

True`anyOf both (=='x') ('x','y')`

`>>>`

`import Data.Data.Lens`

`>>>`

True`anyOf biplate (== "world") (((),2::Int),"hello",("world",11::Int))`

`any`

≡`anyOf`

`folded`

`ianyOf`

l ≡`anyOf`

l`.`

`Indexed`

`anyOf`

::`Getter`

s a -> (a ->`Bool`

) -> s ->`Bool`

`anyOf`

::`Fold`

s a -> (a ->`Bool`

) -> s ->`Bool`

`anyOf`

::`Lens'`

s a -> (a ->`Bool`

) -> s ->`Bool`

`anyOf`

::`Iso'`

s a -> (a ->`Bool`

) -> s ->`Bool`

`anyOf`

::`Traversal'`

s a -> (a ->`Bool`

) -> s ->`Bool`

`anyOf`

::`Prism'`

s a -> (a ->`Bool`

) -> s ->`Bool`

allOf :: Getting All s a -> (a -> Bool ) -> s -> Bool Source #

Returns
```
True
```

if every target of a
```
Fold
```

satisfies a predicate.

`>>>`

True`allOf both (>=3) (4,5)`

`>>>`

False`allOf folded (>=2) [1..10]`

`all`

≡`allOf`

`folded`

`iallOf`

l =`allOf`

l`.`

`Indexed`

`allOf`

::`Getter`

s a -> (a ->`Bool`

) -> s ->`Bool`

`allOf`

::`Fold`

s a -> (a ->`Bool`

) -> s ->`Bool`

`allOf`

::`Lens'`

s a -> (a ->`Bool`

) -> s ->`Bool`

`allOf`

::`Iso'`

s a -> (a ->`Bool`

) -> s ->`Bool`

`allOf`

::`Traversal'`

s a -> (a ->`Bool`

) -> s ->`Bool`

`allOf`

::`Prism'`

s a -> (a ->`Bool`

) -> s ->`Bool`

noneOf :: Getting Any s a -> (a -> Bool ) -> s -> Bool Source #

Returns
```
True
```

only if no targets of a
```
Fold
```

satisfy a predicate.

`>>>`

True`noneOf each (is _Nothing) (Just 3, Just 4, Just 5)`

`>>>`

False`noneOf (folded.folded) (<10) [[13,99,20],[3,71,42]]`

`inoneOf`

l =`noneOf`

l`.`

`Indexed`

`noneOf`

::`Getter`

s a -> (a ->`Bool`

) -> s ->`Bool`

`noneOf`

::`Fold`

s a -> (a ->`Bool`

) -> s ->`Bool`

`noneOf`

::`Lens'`

s a -> (a ->`Bool`

) -> s ->`Bool`

`noneOf`

::`Iso'`

s a -> (a ->`Bool`

) -> s ->`Bool`

`noneOf`

::`Traversal'`

s a -> (a ->`Bool`

) -> s ->`Bool`

`noneOf`

::`Prism'`

s a -> (a ->`Bool`

) -> s ->`Bool`

andOf :: Getting All s Bool -> s -> Bool Source #

Returns
```
True
```

if every target of a
```
Fold
```

is
```
True
```

.

`>>>`

False`andOf both (True,False)`

`>>>`

True`andOf both (True,True)`

`and`

≡`andOf`

`folded`

`andOf`

::`Getter`

s`Bool`

-> s ->`Bool`

`andOf`

::`Fold`

s`Bool`

-> s ->`Bool`

`andOf`

::`Lens'`

s`Bool`

-> s ->`Bool`

`andOf`

::`Iso'`

s`Bool`

-> s ->`Bool`

`andOf`

::`Traversal'`

s`Bool`

-> s ->`Bool`

`andOf`

::`Prism'`

s`Bool`

-> s ->`Bool`

orOf :: Getting Any s Bool -> s -> Bool Source #

Returns
```
True
```

if any target of a
```
Fold
```

is
```
True
```

.

`>>>`

True`orOf both (True,False)`

`>>>`

False`orOf both (False,False)`

`or`

≡`orOf`

`folded`

`orOf`

::`Getter`

s`Bool`

-> s ->`Bool`

`orOf`

::`Fold`

s`Bool`

-> s ->`Bool`

`orOf`

::`Lens'`

s`Bool`

-> s ->`Bool`

`orOf`

::`Iso'`

s`Bool`

-> s ->`Bool`

`orOf`

::`Traversal'`

s`Bool`

-> s ->`Bool`

`orOf`

::`Prism'`

s`Bool`

-> s ->`Bool`

productOf :: Num a => Getting ( Endo ( Endo a)) s a -> s -> a Source #

Calculate the
```
Product
```

of every number targeted by a
```
Fold
```

.

`>>>`

20`productOf both (4,5)`

`>>>`

120`productOf folded [1,2,3,4,5]`

`product`

≡`productOf`

`folded`

This operation may be more strict than you would expect. If you
want a lazier version use
```
```

```
ala
```

```
Product
```

```
.
```

```
foldMapOf
```

`productOf`

::`Num`

a =>`Getter`

s a -> s -> a`productOf`

::`Num`

a =>`Fold`

s a -> s -> a`productOf`

::`Num`

a =>`Lens'`

s a -> s -> a`productOf`

::`Num`

a =>`Iso'`

s a -> s -> a`productOf`

::`Num`

a =>`Traversal'`

s a -> s -> a`productOf`

::`Num`

a =>`Prism'`

s a -> s -> a

sumOf :: Num a => Getting ( Endo ( Endo a)) s a -> s -> a Source #

Calculate the
```
Sum
```

of every number targeted by a
```
Fold
```

.

`>>>`

11`sumOf both (5,6)`

`>>>`

10`sumOf folded [1,2,3,4]`

`>>>`

10`sumOf (folded.both) [(1,2),(3,4)]`

`>>>`

`import Data.Data.Lens`

`>>>`

10`sumOf biplate [(1::Int,[]),(2,[(3::Int,4::Int)])] :: Int`

`sum`

≡`sumOf`

`folded`

This operation may be more strict than you would expect. If you
want a lazier version use
```
```

```
ala
```

```
Sum
```

```
.
```

```
foldMapOf
```

`sumOf`

`_1`

::`Num`

a => (a, b) -> a`sumOf`

(`folded`

`.`

`_1`

) :: (`Foldable`

f,`Num`

a) => f (a, b) -> a

`sumOf`

::`Num`

a =>`Getter`

s a -> s -> a`sumOf`

::`Num`

a =>`Fold`

s a -> s -> a`sumOf`

::`Num`

a =>`Lens'`

s a -> s -> a`sumOf`

::`Num`

a =>`Iso'`

s a -> s -> a`sumOf`

::`Num`

a =>`Traversal'`

s a -> s -> a`sumOf`

::`Num`

a =>`Prism'`

s a -> s -> a

traverseOf_ :: Functor f => Getting ( Traversed r f) s a -> (a -> f r) -> s -> f () Source #

Traverse over all of the targets of a
```
Fold
```

(or
```
Getter
```

), computing an
```
Applicative
```

(or
```
Functor
```

)-based answer,
but unlike
```
traverseOf
```

do not construct a new structure.
```
traverseOf_
```

generalizes
```
traverse_
```

to work over any
```
Fold
```

.

When passed a
```
Getter
```

,
```
traverseOf_
```

can work over any
```
Functor
```

, but when passed a
```
Fold
```

,
```
traverseOf_
```

requires
an
```
Applicative
```

.

`>>>`

hello world`traverseOf_ both putStrLn ("hello","world")`

`traverse_`

≡`traverseOf_`

`folded`

`traverseOf_`

`_2`

::`Functor`

f => (c -> f r) -> (d, c) -> f ()`traverseOf_`

`_Left`

::`Applicative`

f => (a -> f b) ->`Either`

a c -> f ()

`itraverseOf_`

l ≡`traverseOf_`

l`.`

`Indexed`

The rather specific signature of
```
traverseOf_
```

allows it to be used as if the signature was any of:

`traverseOf_`

::`Functor`

f =>`Getter`

s a -> (a -> f r) -> s -> f ()`traverseOf_`

::`Applicative`

f =>`Fold`

s a -> (a -> f r) -> s -> f ()`traverseOf_`

::`Functor`

f =>`Lens'`

s a -> (a -> f r) -> s -> f ()`traverseOf_`

::`Functor`

f =>`Iso'`

s a -> (a -> f r) -> s -> f ()`traverseOf_`

::`Applicative`

f =>`Traversal'`

s a -> (a -> f r) -> s -> f ()`traverseOf_`

::`Applicative`

f =>`Prism'`

s a -> (a -> f r) -> s -> f ()

forOf_ :: Functor f => Getting ( Traversed r f) s a -> s -> (a -> f r) -> f () Source #

Traverse over all of the targets of a
```
Fold
```

(or
```
Getter
```

), computing an
```
Applicative
```

(or
```
Functor
```

)-based answer,
but unlike
```
forOf
```

do not construct a new structure.
```
forOf_
```

generalizes
```
for_
```

to work over any
```
Fold
```

.

When passed a
```
Getter
```

,
```
forOf_
```

can work over any
```
Functor
```

, but when passed a
```
Fold
```

,
```
forOf_
```

requires
an
```
Applicative
```

.

`for_`

≡`forOf_`

`folded`

`>>>`

hello world`forOf_ both ("hello","world") putStrLn`

The rather specific signature of
```
forOf_
```

allows it to be used as if the signature was any of:

`iforOf_`

l s ≡`forOf_`

l s`.`

`Indexed`

`forOf_`

::`Functor`

f =>`Getter`

s a -> s -> (a -> f r) -> f ()`forOf_`

::`Applicative`

f =>`Fold`

s a -> s -> (a -> f r) -> f ()`forOf_`

::`Functor`

f =>`Lens'`

s a -> s -> (a -> f r) -> f ()`forOf_`

::`Functor`

f =>`Iso'`

s a -> s -> (a -> f r) -> f ()`forOf_`

::`Applicative`

f =>`Traversal'`

s a -> s -> (a -> f r) -> f ()`forOf_`

::`Applicative`

f =>`Prism'`

s a -> s -> (a -> f r) -> f ()

sequenceAOf_ :: Functor f => Getting ( Traversed a f) s (f a) -> s -> f () Source #

Evaluate each action in observed by a
```
Fold
```

on a structure from left to right, ignoring the results.

`sequenceA_`

≡`sequenceAOf_`

`folded`

`>>>`

hello world`sequenceAOf_ both (putStrLn "hello",putStrLn "world")`

`sequenceAOf_`

::`Functor`

f =>`Getter`

s (f a) -> s -> f ()`sequenceAOf_`

::`Applicative`

f =>`Fold`

s (f a) -> s -> f ()`sequenceAOf_`

::`Functor`

f =>`Lens'`

s (f a) -> s -> f ()`sequenceAOf_`

::`Functor`

f =>`Iso'`

s (f a) -> s -> f ()`sequenceAOf_`

::`Applicative`

f =>`Traversal'`

s (f a) -> s -> f ()`sequenceAOf_`

::`Applicative`

f =>`Prism'`

s (f a) -> s -> f ()

traverse1Of_ :: Functor f => Getting ( TraversedF r f) s a -> (a -> f r) -> s -> f () Source #

Traverse over all of the targets of a
```
Fold1
```

, computing an
```
Apply
```

based answer.

As long as you have
```
Applicative
```

or
```
Functor
```

effect you are better using
```
traverseOf_
```

.
The
```
traverse1Of_
```

is useful only when you have genuine
```
Apply
```

effect.

`>>>`

fromList [('b',()),('c',())]`traverse1Of_ both1 (\ks -> Map.fromList [ (k, ()) | k <- ks ]) ("abc", "bcd")`

`traverse1Of_`

::`Apply`

f =>`Fold1`

s a -> (a -> f r) -> s -> f ()

*
Since: 4.16
*

for1Of_ :: Functor f => Getting ( TraversedF r f) s a -> s -> (a -> f r) -> f () Source #

See
```
forOf_
```

and
```
traverse1Of_
```

.

`>>>`

fromList [('b',()),('c',())]`for1Of_ both1 ("abc", "bcd") (\ks -> Map.fromList [ (k, ()) | k <- ks ])`

`for1Of_`

::`Apply`

f =>`Fold1`

s a -> s -> (a -> f r) -> f ()

*
Since: 4.16
*

sequence1Of_ :: Functor f => Getting ( TraversedF a f) s (f a) -> s -> f () Source #

See
```
sequenceAOf_
```

and
```
traverse1Of_
```

.

`sequence1Of_`

::`Apply`

f =>`Fold1`

s (f a) -> s -> f ()

*
Since: 4.16
*

mapMOf_ :: Monad m => Getting ( Sequenced r m) s a -> (a -> m r) -> s -> m () Source #

Map each target of a
```
Fold
```

on a structure to a monadic action, evaluate these actions from left to right, and ignore the results.

`>>>`

hello world`mapMOf_ both putStrLn ("hello","world")`

`mapM_`

≡`mapMOf_`

`folded`

`mapMOf_`

::`Monad`

m =>`Getter`

s a -> (a -> m r) -> s -> m ()`mapMOf_`

::`Monad`

m =>`Fold`

s a -> (a -> m r) -> s -> m ()`mapMOf_`

::`Monad`

m =>`Lens'`

s a -> (a -> m r) -> s -> m ()`mapMOf_`

::`Monad`

m =>`Iso'`

s a -> (a -> m r) -> s -> m ()`mapMOf_`

::`Monad`

m =>`Traversal'`

s a -> (a -> m r) -> s -> m ()`mapMOf_`

::`Monad`

m =>`Prism'`

s a -> (a -> m r) -> s -> m ()

forMOf_ :: Monad m => Getting ( Sequenced r m) s a -> s -> (a -> m r) -> m () Source #

```
forMOf_
```

is
```
mapMOf_
```

with two of its arguments flipped.

`>>>`

hello world`forMOf_ both ("hello","world") putStrLn`

`forM_`

≡`forMOf_`

`folded`

`forMOf_`

::`Monad`

m =>`Getter`

s a -> s -> (a -> m r) -> m ()`forMOf_`

::`Monad`

m =>`Fold`

s a -> s -> (a -> m r) -> m ()`forMOf_`

::`Monad`

m =>`Lens'`

s a -> s -> (a -> m r) -> m ()`forMOf_`

::`Monad`

m =>`Iso'`

s a -> s -> (a -> m r) -> m ()`forMOf_`

::`Monad`

m =>`Traversal'`

s a -> s -> (a -> m r) -> m ()`forMOf_`

::`Monad`

m =>`Prism'`

s a -> s -> (a -> m r) -> m ()

sequenceOf_ :: Monad m => Getting ( Sequenced a m) s (m a) -> s -> m () Source #

Evaluate each monadic action referenced by a
```
Fold
```

on the structure from left to right, and ignore the results.

`>>>`

hello world`sequenceOf_ both (putStrLn "hello",putStrLn "world")`

`sequence_`

≡`sequenceOf_`

`folded`

`sequenceOf_`

::`Monad`

m =>`Getter`

s (m a) -> s -> m ()`sequenceOf_`

::`Monad`

m =>`Fold`

s (m a) -> s -> m ()`sequenceOf_`

::`Monad`

m =>`Lens'`

s (m a) -> s -> m ()`sequenceOf_`

::`Monad`

m =>`Iso'`

s (m a) -> s -> m ()`sequenceOf_`

::`Monad`

m =>`Traversal'`

s (m a) -> s -> m ()`sequenceOf_`

::`Monad`

m =>`Prism'`

s (m a) -> s -> m ()

asumOf :: Alternative f => Getting ( Endo (f a)) s (f a) -> s -> f a Source #

The sum of a collection of actions, generalizing
```
concatOf
```

.

`>>>`

"helloworld"`asumOf both ("hello","world")`

`>>>`

Just "hello"`asumOf each (Nothing, Just "hello", Nothing)`

`asum`

≡`asumOf`

`folded`

`asumOf`

::`Alternative`

f =>`Getter`

s (f a) -> s -> f a`asumOf`

::`Alternative`

f =>`Fold`

s (f a) -> s -> f a`asumOf`

::`Alternative`

f =>`Lens'`

s (f a) -> s -> f a`asumOf`

::`Alternative`

f =>`Iso'`

s (f a) -> s -> f a`asumOf`

::`Alternative`

f =>`Traversal'`

s (f a) -> s -> f a`asumOf`

::`Alternative`

f =>`Prism'`

s (f a) -> s -> f a

msumOf :: MonadPlus m => Getting ( Endo (m a)) s (m a) -> s -> m a Source #

The sum of a collection of actions, generalizing
```
concatOf
```

.

`>>>`

"helloworld"`msumOf both ("hello","world")`

`>>>`

Just "hello"`msumOf each (Nothing, Just "hello", Nothing)`

`msum`

≡`msumOf`

`folded`

`msumOf`

::`MonadPlus`

m =>`Getter`

s (m a) -> s -> m a`msumOf`

::`MonadPlus`

m =>`Fold`

s (m a) -> s -> m a`msumOf`

::`MonadPlus`

m =>`Lens'`

s (m a) -> s -> m a`msumOf`

::`MonadPlus`

m =>`Iso'`

s (m a) -> s -> m a`msumOf`

::`MonadPlus`

m =>`Traversal'`

s (m a) -> s -> m a`msumOf`

::`MonadPlus`

m =>`Prism'`

s (m a) -> s -> m a

concatMapOf :: Getting [r] s a -> (a -> [r]) -> s -> [r] Source #

Map a function over all the targets of a
```
Fold
```

of a container and concatenate the resulting lists.

`>>>`

[1,2,3,4]`concatMapOf both (\x -> [x, x + 1]) (1,3)`

`concatMap`

≡`concatMapOf`

`folded`

`concatMapOf`

::`Getter`

s a -> (a -> [r]) -> s -> [r]`concatMapOf`

::`Fold`

s a -> (a -> [r]) -> s -> [r]`concatMapOf`

::`Lens'`

s a -> (a -> [r]) -> s -> [r]`concatMapOf`

::`Iso'`

s a -> (a -> [r]) -> s -> [r]`concatMapOf`

::`Traversal'`

s a -> (a -> [r]) -> s -> [r]

concatOf :: Getting [r] s [r] -> s -> [r] Source #

Concatenate all of the lists targeted by a
```
Fold
```

into a longer list.

`>>>`

"panama"`concatOf both ("pan","ama")`

`concat`

≡`concatOf`

`folded`

`concatOf`

≡`view`

`concatOf`

::`Getter`

s [r] -> s -> [r]`concatOf`

::`Fold`

s [r] -> s -> [r]`concatOf`

::`Iso'`

s [r] -> s -> [r]`concatOf`

::`Lens'`

s [r] -> s -> [r]`concatOf`

::`Traversal'`

s [r] -> s -> [r]

elemOf :: Eq a => Getting Any s a -> a -> s -> Bool Source #

Does the element occur anywhere within a given
```
Fold
```

of the structure?

`>>>`

True`elemOf both "hello" ("hello","world")`

`elem`

≡`elemOf`

`folded`

`elemOf`

::`Eq`

a =>`Getter`

s a -> a -> s ->`Bool`

`elemOf`

::`Eq`

a =>`Fold`

s a -> a -> s ->`Bool`

`elemOf`

::`Eq`

a =>`Lens'`

s a -> a -> s ->`Bool`

`elemOf`

::`Eq`

a =>`Iso'`

s a -> a -> s ->`Bool`

`elemOf`

::`Eq`

a =>`Traversal'`

s a -> a -> s ->`Bool`

`elemOf`

::`Eq`

a =>`Prism'`

s a -> a -> s ->`Bool`

notElemOf :: Eq a => Getting All s a -> a -> s -> Bool Source #

Does the element not occur anywhere within a given
```
Fold
```

of the structure?

`>>>`

True`notElemOf each 'd' ('a','b','c')`

`>>>`

False`notElemOf each 'a' ('a','b','c')`

`notElem`

≡`notElemOf`

`folded`

`notElemOf`

::`Eq`

a =>`Getter`

s a -> a -> s ->`Bool`

`notElemOf`

::`Eq`

a =>`Fold`

s a -> a -> s ->`Bool`

`notElemOf`

::`Eq`

a =>`Iso'`

s a -> a -> s ->`Bool`

`notElemOf`

::`Eq`

a =>`Lens'`

s a -> a -> s ->`Bool`

`notElemOf`

::`Eq`

a =>`Traversal'`

s a -> a -> s ->`Bool`

`notElemOf`

::`Eq`

a =>`Prism'`

s a -> a -> s ->`Bool`

lengthOf :: Getting ( Endo ( Endo Int )) s a -> s -> Int Source #

Calculate the number of targets there are for a
```
Fold
```

in a given container.

*
Note:
*
This can be rather inefficient for large containers and just like
```
length
```

,
this will not terminate for infinite folds.

`length`

≡`lengthOf`

`folded`

`>>>`

1`lengthOf _1 ("hello",())`

`>>>`

10`lengthOf traverse [1..10]`

`>>>`

6`lengthOf (traverse.traverse) [[1,2],[3,4],[5,6]]`

`lengthOf`

(`folded`

`.`

`folded`

) :: (`Foldable`

f,`Foldable`

g) => f (g a) ->`Int`

`lengthOf`

::`Getter`

s a -> s ->`Int`

`lengthOf`

::`Fold`

s a -> s ->`Int`

`lengthOf`

::`Lens'`

s a -> s ->`Int`

`lengthOf`

::`Iso'`

s a -> s ->`Int`

`lengthOf`

::`Traversal'`

s a -> s ->`Int`

nullOf :: Getting All s a -> s -> Bool Source #

Returns
```
True
```

if this
```
Fold
```

or
```
Traversal
```

has no targets in the given container.

Note:
```
nullOf
```

on a valid
```
Iso
```

,
```
Lens
```

or
```
Getter
```

should always return
```
False
```

.

`null`

≡`nullOf`

`folded`

This may be rather inefficient compared to the
```
null
```

check of many containers.

`>>>`

False`nullOf _1 (1,2)`

`>>>`

True`nullOf ignored ()`

`>>>`

True`nullOf traverse []`

`>>>`

True`nullOf (element 20) [1..10]`

`nullOf`

(`folded`

`.`

`_1`

`.`

`folded`

) :: (`Foldable`

f,`Foldable`

g) => f (g a, b) ->`Bool`

`nullOf`

::`Getter`

s a -> s ->`Bool`

`nullOf`

::`Fold`

s a -> s ->`Bool`

`nullOf`

::`Iso'`

s a -> s ->`Bool`

`nullOf`

::`Lens'`

s a -> s ->`Bool`

`nullOf`

::`Traversal'`

s a -> s ->`Bool`

notNullOf :: Getting Any s a -> s -> Bool Source #

Returns
```
True
```

if this
```
Fold
```

or
```
Traversal
```

has any targets in the given container.

A more "conversational" alias for this combinator is
```
has
```

.

Note:
```
notNullOf
```

on a valid
```
Iso
```

,
```
Lens
```

or
```
Getter
```

should always return
```
True
```

.

`not`

`.`

`null`

≡`notNullOf`

`folded`

This may be rather inefficient compared to the
```
```

check of many containers.
```
not
```

```
.
```

```
null
```

`>>>`

True`notNullOf _1 (1,2)`

`>>>`

True`notNullOf traverse [1..10]`

`>>>`

False`notNullOf folded []`

`>>>`

False`notNullOf (element 20) [1..10]`

`notNullOf`

(`folded`

`.`

`_1`

`.`

`folded`

) :: (`Foldable`

f,`Foldable`

g) => f (g a, b) ->`Bool`

`notNullOf`

::`Getter`

s a -> s ->`Bool`

`notNullOf`

::`Fold`

s a -> s ->`Bool`

`notNullOf`

::`Iso'`

s a -> s ->`Bool`

`notNullOf`

::`Lens'`

s a -> s ->`Bool`

`notNullOf`

::`Traversal'`

s a -> s ->`Bool`

firstOf :: Getting ( Leftmost a) s a -> s -> Maybe a Source #

Retrieve the
```
First
```

entry of a
```
Fold
```

or
```
Traversal
```

or retrieve
```
Just
```

the result
from a
```
Getter
```

or
```
Lens
```

.

The answer is computed in a manner that leaks space less than
```
```

or
```
preview
```

```
^?'
```

and gives you back access to the outermost
```
Just
```

constructor more quickly, but does so
in a way that builds an intermediate structure, and thus may have worse
constant factors. This also means that it can not be used in any
```
MonadReader
```

,
but must instead have
```
s
```

passed as its last argument, unlike
```
preview
```

.

Note: this could been named
```
headOf
```

.

`>>>`

Just 1`firstOf traverse [1..10]`

`>>>`

Just 1`firstOf both (1,2)`

`>>>`

Nothing`firstOf ignored ()`

`firstOf`

::`Getter`

s a -> s ->`Maybe`

a`firstOf`

::`Fold`

s a -> s ->`Maybe`

a`firstOf`

::`Lens'`

s a -> s ->`Maybe`

a`firstOf`

::`Iso'`

s a -> s ->`Maybe`

a`firstOf`

::`Traversal'`

s a -> s ->`Maybe`

a

first1Of :: Getting ( First a) s a -> s -> a Source #

Retrieve the
```
First
```

entry of a
```
Fold1
```

or
```
Traversal1
```

or the result from a
```
Getter
```

or
```
Lens
```

.

`>>>`

1`first1Of traverse1 (1 :| [2..10])`

`>>>`

1`first1Of both1 (1,2)`

*
Note:
*
this is different from
```
^.
```

.

`>>>`

[1,2]`first1Of traverse1 ([1,2] :| [[3,4],[5,6]])`

`>>>`

[1,2,3,4,5,6]`([1,2] :| [[3,4],[5,6]]) ^. traverse1`

`first1Of`

::`Getter`

s a -> s -> a`first1Of`

::`Fold1`

s a -> s -> a`first1Of`

::`Lens'`

s a -> s -> a`first1Of`

::`Iso'`

s a -> s -> a`first1Of`

::`Traversal1'`

s a -> s -> a

lastOf :: Getting ( Rightmost a) s a -> s -> Maybe a Source #

Retrieve the
```
Last
```

entry of a
```
Fold
```

or
```
Traversal
```

or retrieve
```
Just
```

the result
from a
```
Getter
```

or
```
Lens
```

.

The answer is computed in a manner that leaks space less than
```
```

and gives you back access to the outermost
```
ala
```

```
Last
```

```
.
```

```
foldMapOf
```

```
Just
```

constructor more quickly, but may have worse
constant factors.

`>>>`

Just 10`lastOf traverse [1..10]`

`>>>`

Just 2`lastOf both (1,2)`

`>>>`

Nothing`lastOf ignored ()`

`lastOf`

::`Getter`

s a -> s ->`Maybe`

a`lastOf`

::`Fold`

s a -> s ->`Maybe`

a`lastOf`

::`Lens'`

s a -> s ->`Maybe`

a`lastOf`

::`Iso'`

s a -> s ->`Maybe`

a`lastOf`

::`Traversal'`

s a -> s ->`Maybe`

a

last1Of :: Getting ( Last a) s a -> s -> a Source #

Retrieve the
```
Last
```

entry of a
```
Fold1
```

or
```
Traversal1
```

or retrieve the result
from a
```
Getter
```

or
```
Lens
```

.o

`>>>`

10`last1Of traverse1 (1 :| [2..10])`

`>>>`

2`last1Of both1 (1,2)`

`last1Of`

::`Getter`

s a -> s ->`Maybe`

a`last1Of`

::`Fold1`

s a -> s ->`Maybe`

a`last1Of`

::`Lens'`

s a -> s ->`Maybe`

a`last1Of`

::`Iso'`

s a -> s ->`Maybe`

a`last1Of`

::`Traversal1'`

s a -> s ->`Maybe`

a

maximumOf :: Ord a => Getting ( Endo ( Endo ( Maybe a))) s a -> s -> Maybe a Source #

Obtain the maximum element (if any) targeted by a
```
Fold
```

or
```
Traversal
```

safely.

Note:
```
maximumOf
```

on a valid
```
Iso
```

,
```
Lens
```

or
```
Getter
```

will always return
```
Just
```

a value.

`>>>`

Just 10`maximumOf traverse [1..10]`

`>>>`

Nothing`maximumOf traverse []`

`>>>`

Just 6`maximumOf (folded.filtered even) [1,4,3,6,7,9,2]`

`maximum`

≡`fromMaybe`

(`error`

"empty")`.`

`maximumOf`

`folded`

In the interest of efficiency, This operation has semantics more strict than strictly necessary.
```
```

has lazier semantics but could leak memory.
```
rmap
```

```
getMax
```

(
```
foldMapOf
```

l
```
Max
```

)

`maximumOf`

::`Ord`

a =>`Getter`

s a -> s ->`Maybe`

a`maximumOf`

::`Ord`

a =>`Fold`

s a -> s ->`Maybe`

a`maximumOf`

::`Ord`

a =>`Iso'`

s a -> s ->`Maybe`

a`maximumOf`

::`Ord`

a =>`Lens'`

s a -> s ->`Maybe`

a`maximumOf`

::`Ord`

a =>`Traversal'`

s a -> s ->`Maybe`

a

maximum1Of :: Ord a => Getting ( Max a) s a -> s -> a Source #

Obtain the maximum element targeted by a
```
Fold1
```

or
```
Traversal1
```

.

`>>>`

10`maximum1Of traverse1 (1 :| [2..10])`

`maximum1Of`

::`Ord`

a =>`Getter`

s a -> s -> a`maximum1Of`

::`Ord`

a =>`Fold1`

s a -> s -> a`maximum1Of`

::`Ord`

a =>`Iso'`

s a -> s -> a`maximum1Of`

::`Ord`

a =>`Lens'`

s a -> s -> a`maximum1Of`

::`Ord`

a =>`Traversal1'`

s a -> s -> a

minimumOf :: Ord a => Getting ( Endo ( Endo ( Maybe a))) s a -> s -> Maybe a Source #

Obtain the minimum element (if any) targeted by a
```
Fold
```

or
```
Traversal
```

safely.

Note:
```
minimumOf
```

on a valid
```
Iso
```

,
```
Lens
```

or
```
Getter
```

will always return
```
Just
```

a value.

`>>>`

Just 1`minimumOf traverse [1..10]`

`>>>`

Nothing`minimumOf traverse []`

`>>>`

Just 2`minimumOf (folded.filtered even) [1,4,3,6,7,9,2]`

`minimum`

≡`fromMaybe`

(`error`

"empty")`.`

`minimumOf`

`folded`

In the interest of efficiency, This operation has semantics more strict than strictly necessary.
```
```

has lazier semantics but could leak memory.
```
rmap
```

```
getMin
```

(
```
foldMapOf
```

l
```
Min
```

)

`minimumOf`

::`Ord`

a =>`Getter`

s a -> s ->`Maybe`

a`minimumOf`

::`Ord`

a =>`Fold`

s a -> s ->`Maybe`

a`minimumOf`

::`Ord`

a =>`Iso'`

s a -> s ->`Maybe`

a`minimumOf`

::`Ord`

a =>`Lens'`

s a -> s ->`Maybe`

a`minimumOf`

::`Ord`

a =>`Traversal'`

s a -> s ->`Maybe`

a

minimum1Of :: Ord a => Getting ( Min a) s a -> s -> a Source #

Obtain the minimum element targeted by a
```
Fold1
```

or
```
Traversal1
```

.

`>>>`

1`minimum1Of traverse1 (1 :| [2..10])`

`minimum1Of`

::`Ord`

a =>`Getter`

s a -> s -> a`minimum1Of`

::`Ord`

a =>`Fold1`

s a -> s -> a`minimum1Of`

::`Ord`

a =>`Iso'`

s a -> s -> a`minimum1Of`

::`Ord`

a =>`Lens'`

s a -> s -> a`minimum1Of`

::`Ord`

a =>`Traversal1'`

s a -> s -> a

maximumByOf :: Getting ( Endo ( Endo ( Maybe a))) s a -> (a -> a -> Ordering ) -> s -> Maybe a Source #

Obtain the maximum element (if any) targeted by a
```
Fold
```

,
```
Traversal
```

,
```
Lens
```

,
```
Iso
```

,
or
```
Getter
```

according to a user supplied
```
Ordering
```

.

`>>>`

Just "mustard"`maximumByOf traverse (compare `on` length) ["mustard","relish","ham"]`

In the interest of efficiency, This operation has semantics more strict than strictly necessary.

`maximumBy`

cmp ≡`fromMaybe`

(`error`

"empty")`.`

`maximumByOf`

`folded`

cmp

`maximumByOf`

::`Getter`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a`maximumByOf`

::`Fold`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a`maximumByOf`

::`Iso'`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a`maximumByOf`

::`Lens'`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a`maximumByOf`

::`Traversal'`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a

minimumByOf :: Getting ( Endo ( Endo ( Maybe a))) s a -> (a -> a -> Ordering ) -> s -> Maybe a Source #

Obtain the minimum element (if any) targeted by a
```
Fold
```

,
```
Traversal
```

,
```
Lens
```

,
```
Iso
```

or
```
Getter
```

according to a user supplied
```
Ordering
```

.

In the interest of efficiency, This operation has semantics more strict than strictly necessary.

`>>>`

Just "ham"`minimumByOf traverse (compare `on` length) ["mustard","relish","ham"]`

`minimumBy`

cmp ≡`fromMaybe`

(`error`

"empty")`.`

`minimumByOf`

`folded`

cmp

`minimumByOf`

::`Getter`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a`minimumByOf`

::`Fold`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a`minimumByOf`

::`Iso'`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a`minimumByOf`

::`Lens'`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a`minimumByOf`

::`Traversal'`

s a -> (a -> a ->`Ordering`

) -> s ->`Maybe`

a

findOf :: Getting ( Endo ( Maybe a)) s a -> (a -> Bool ) -> s -> Maybe a Source #

The
```
findOf
```

function takes a
```
Lens
```

(or
```
Getter
```

,
```
Iso
```

,
```
Fold
```

, or
```
Traversal
```

),
a predicate and a structure and returns the leftmost element of the structure
matching the predicate, or
```
Nothing
```

if there is no such element.

`>>>`

Just 4`findOf each even (1,3,4,6)`

`>>>`

Nothing`findOf folded even [1,3,5,7]`

`findOf`

::`Getter`

s a -> (a ->`Bool`

) -> s ->`Maybe`

a`findOf`

::`Fold`

s a -> (a ->`Bool`

) -> s ->`Maybe`

a`findOf`

::`Iso'`

s a -> (a ->`Bool`

) -> s ->`Maybe`

a`findOf`

::`Lens'`

s a -> (a ->`Bool`

) -> s ->`Maybe`

a`findOf`

::`Traversal'`

s a -> (a ->`Bool`

) -> s ->`Maybe`

a

`find`

≡`findOf`

`folded`

`ifindOf`

l ≡`findOf`

l`.`

`Indexed`

A simpler version that didn't permit indexing, would be:

`findOf`

::`Getting`

(`Endo`

(`Maybe`

a)) s a -> (a ->`Bool`

) -> s ->`Maybe`

a`findOf`

l p =`foldrOf`

l (a y -> if p a then`Just`

a else y)`Nothing`

findMOf :: Monad m => Getting ( Endo (m ( Maybe a))) s a -> (a -> m Bool ) -> s -> m ( Maybe a) Source #

The
```
findMOf
```

function takes a
```
Lens
```

(or
```
Getter
```

,
```
Iso
```

,
```
Fold
```

, or
```
Traversal
```

),
a monadic predicate and a structure and returns in the monad the leftmost element of the structure
matching the predicate, or
```
Nothing
```

if there is no such element.

`>>>`

"Checking 1" "Checking 3" "Checking 4" Just 4`findMOf each ( \x -> print ("Checking " ++ show x) >> return (even x)) (1,3,4,6)`

`>>>`

"Checking 1" "Checking 3" "Checking 5" "Checking 7" Nothing`findMOf each ( \x -> print ("Checking " ++ show x) >> return (even x)) (1,3,5,7)`

`findMOf`

:: (`Monad`

m,`Getter`

s a) -> (a -> m`Bool`

) -> s -> m (`Maybe`

a)`findMOf`

:: (`Monad`

m,`Fold`

s a) -> (a -> m`Bool`

) -> s -> m (`Maybe`

a)`findMOf`

:: (`Monad`

m,`Iso'`

s a) -> (a -> m`Bool`

) -> s -> m (`Maybe`

a)`findMOf`

:: (`Monad`

m,`Lens'`

s a) -> (a -> m`Bool`

) -> s -> m (`Maybe`

a)`findMOf`

:: (`Monad`

m,`Traversal'`

s a) -> (a -> m`Bool`

) -> s -> m (`Maybe`

a)

`findMOf`

`folded`

:: (Monad m, Foldable f) => (a -> m Bool) -> f a -> m (Maybe a)`ifindMOf`

l ≡`findMOf`

l`.`

`Indexed`

A simpler version that didn't permit indexing, would be:

`findMOf`

:: Monad m =>`Getting`

(`Endo`

(m (`Maybe`

a))) s a -> (a -> m`Bool`

) -> s -> m (`Maybe`

a)`findMOf`

l p =`foldrOf`

l (a y -> p a >>= x -> if x then return (`Just`

a) else y) $ return`Nothing`

foldrOf' :: Getting ( Dual ( Endo ( Endo r))) s a -> (a -> r -> r) -> r -> s -> r Source #

Strictly fold right over the elements of a structure.

`foldr'`

≡`foldrOf'`

`folded`

`foldrOf'`

::`Getter`

s a -> (a -> r -> r) -> r -> s -> r`foldrOf'`

::`Fold`

s a -> (a -> r -> r) -> r -> s -> r`foldrOf'`

::`Iso'`

s a -> (a -> r -> r) -> r -> s -> r`foldrOf'`

::`Lens'`

s a -> (a -> r -> r) -> r -> s -> r`foldrOf'`

::`Traversal'`

s a -> (a -> r -> r) -> r -> s -> r

foldlOf' :: Getting ( Endo ( Endo r)) s a -> (r -> a -> r) -> r -> s -> r Source #

Fold over the elements of a structure, associating to the left, but strictly.

`foldl'`

≡`foldlOf'`

`folded`

`foldlOf'`

::`Getter`

s a -> (r -> a -> r) -> r -> s -> r`foldlOf'`

::`Fold`

s a -> (r -> a -> r) -> r -> s -> r`foldlOf'`

::`Iso'`

s a -> (r -> a -> r) -> r -> s -> r`foldlOf'`

::`Lens'`

s a -> (r -> a -> r) -> r -> s -> r`foldlOf'`

::`Traversal'`

s a -> (r -> a -> r) -> r -> s -> r

foldr1Of :: HasCallStack => Getting ( Endo ( Maybe a)) s a -> (a -> a -> a) -> s -> a Source #

A variant of
```
foldrOf
```

that has no base case and thus may only be applied
to lenses and structures such that the
```
Lens
```

views at least one element of
the structure.

`>>>`

10`foldr1Of each (+) (1,2,3,4)`

`foldr1Of`

l f ≡`foldr1`

f`.`

`toListOf`

l`foldr1`

≡`foldr1Of`

`folded`

`foldr1Of`

::`Getter`

s a -> (a -> a -> a) -> s -> a`foldr1Of`

::`Fold`

s a -> (a -> a -> a) -> s -> a`foldr1Of`

::`Iso'`

s a -> (a -> a -> a) -> s -> a`foldr1Of`

::`Lens'`

s a -> (a -> a -> a) -> s -> a`foldr1Of`

::`Traversal'`

s a -> (a -> a -> a) -> s -> a

foldl1Of :: HasCallStack => Getting ( Dual ( Endo ( Maybe a))) s a -> (a -> a -> a) -> s -> a Source #

A variant of
```
foldlOf
```

that has no base case and thus may only be applied to lenses and structures such
that the
```
Lens
```

views at least one element of the structure.

`>>>`

10`foldl1Of each (+) (1,2,3,4)`

`foldl1Of`

l f ≡`foldl1`

f`.`

`toListOf`

l`foldl1`

≡`foldl1Of`

`folded`

`foldl1Of`

::`Getter`

s a -> (a -> a -> a) -> s -> a`foldl1Of`

::`Fold`

s a -> (a -> a -> a) -> s -> a`foldl1Of`

::`Iso'`

s a -> (a -> a -> a) -> s -> a`foldl1Of`

::`Lens'`

s a -> (a -> a -> a) -> s -> a`foldl1Of`

::`Traversal'`

s a -> (a -> a -> a) -> s -> a

foldr1Of' :: HasCallStack => Getting ( Dual ( Endo ( Endo ( Maybe a)))) s a -> (a -> a -> a) -> s -> a Source #

A variant of
```
foldrOf'
```

that has no base case and thus may only be applied
to folds and structures such that the fold views at least one element of the
structure.

`foldr1Of`

l f ≡`foldr1`

f`.`

`toListOf`

l

`foldr1Of'`

::`Getter`

s a -> (a -> a -> a) -> s -> a`foldr1Of'`

::`Fold`

s a -> (a -> a -> a) -> s -> a`foldr1Of'`

::`Iso'`

s a -> (a -> a -> a) -> s -> a`foldr1Of'`

::`Lens'`

s a -> (a -> a -> a) -> s -> a`foldr1Of'`

::`Traversal'`

s a -> (a -> a -> a) -> s -> a

foldl1Of' :: HasCallStack => Getting ( Endo ( Endo ( Maybe a))) s a -> (a -> a -> a) -> s -> a Source #

A variant of
```
foldlOf'
```

that has no base case and thus may only be applied
to folds and structures such that the fold views at least one element of
the structure.

`foldl1Of'`

l f ≡`foldl1'`

f`.`

`toListOf`

l

`foldl1Of'`

::`Getter`

s a -> (a -> a -> a) -> s -> a`foldl1Of'`

::`Fold`

s a -> (a -> a -> a) -> s -> a`foldl1Of'`

::`Iso'`

s a -> (a -> a -> a) -> s -> a`foldl1Of'`

::`Lens'`

s a -> (a -> a -> a) -> s -> a`foldl1Of'`

::`Traversal'`

s a -> (a -> a -> a) -> s -> a

foldrMOf :: Monad m => Getting ( Dual ( Endo (r -> m r))) s a -> (a -> r -> m r) -> r -> s -> m r Source #

Monadic fold over the elements of a structure, associating to the right, i.e. from right to left.

`foldrM`

≡`foldrMOf`

`folded`

`foldrMOf`

::`Monad`

m =>`Getter`

s a -> (a -> r -> m r) -> r -> s -> m r`foldrMOf`

::`Monad`

m =>`Fold`

s a -> (a -> r -> m r) -> r -> s -> m r`foldrMOf`

::`Monad`

m =>`Iso'`

s a -> (a -> r -> m r) -> r -> s -> m r`foldrMOf`

::`Monad`

m =>`Lens'`

s a -> (a -> r -> m r) -> r -> s -> m r`foldrMOf`

::`Monad`

m =>`Traversal'`

s a -> (a -> r -> m r) -> r -> s -> m r

foldlMOf :: Monad m => Getting ( Endo (r -> m r)) s a -> (r -> a -> m r) -> r -> s -> m r Source #

Monadic fold over the elements of a structure, associating to the left, i.e. from left to right.

`foldlM`

≡`foldlMOf`

`folded`

`foldlMOf`

::`Monad`

m =>`Getter`

s a -> (r -> a -> m r) -> r -> s -> m r`foldlMOf`

::`Monad`

m =>`Fold`

s a -> (r -> a -> m r) -> r -> s -> m r`foldlMOf`

::`Monad`

m =>`Iso'`

s a -> (r -> a -> m r) -> r -> s -> m r`foldlMOf`

::`Monad`

m =>`Lens'`

s a -> (r -> a -> m r) -> r -> s -> m r`foldlMOf`

::`Monad`

m =>`Traversal'`

s a -> (r -> a -> m r) -> r -> s -> m r

lookupOf :: Eq k => Getting ( Endo ( Maybe v)) s (k, v) -> k -> s -> Maybe v Source #

The
```
lookupOf
```

function takes a
```
Fold
```

(or
```
Getter
```

,
```
Traversal
```

,
```
Lens
```

,
```
Iso
```

, etc.), a key, and a structure containing key/value pairs.
It returns the first value corresponding to the given key. This function
generalizes
```
lookup
```

to work on an arbitrary
```
Fold
```

instead of lists.

`>>>`

Just 'b'`lookupOf folded 4 [(2, 'a'), (4, 'b'), (4, 'c')]`

`>>>`

Just 'a'`lookupOf each 2 [(2, 'a'), (4, 'b'), (4, 'c')]`

`lookupOf`

::`Eq`

k =>`Fold`

s (k,v) -> k -> s ->`Maybe`

v

# Indexed Folds

(^@..) :: s -> IndexedGetting i ( Endo [(i, a)]) s a -> [(i, a)] infixl 8 Source #

An infix version of
```
itoListOf
```

.

(^@?) :: s -> IndexedGetting i ( Endo ( Maybe (i, a))) s a -> Maybe (i, a) infixl 8 Source #

Perform a safe
```
head
```

(with index) of an
```
IndexedFold
```

or
```
IndexedTraversal
```

or retrieve
```
Just
```

the index and result
from an
```
IndexedGetter
```

or
```
IndexedLens
```

.

When using a
```
IndexedTraversal
```

as a partial
```
IndexedLens
```

, or an
```
IndexedFold
```

as a partial
```
IndexedGetter
```

this can be a convenient
way to extract the optional value.

(`^@?`

) :: s ->`IndexedGetter`

i s a ->`Maybe`

(i, a) (`^@?`

) :: s ->`IndexedFold`

i s a ->`Maybe`

(i, a) (`^@?`

) :: s ->`IndexedLens'`

i s a ->`Maybe`

(i, a) (`^@?`

) :: s ->`IndexedTraversal'`

i s a ->`Maybe`

(i, a)

(^@?!) :: HasCallStack => s -> IndexedGetting i ( Endo (i, a)) s a -> (i, a) infixl 8 Source #

Perform an *UNSAFE*
```
head
```

(with index) of an
```
IndexedFold
```

or
```
IndexedTraversal
```

assuming that it is there.

(`^@?!`

) :: s ->`IndexedGetter`

i s a -> (i, a) (`^@?!`

) :: s ->`IndexedFold`

i s a -> (i, a) (`^@?!`

) :: s ->`IndexedLens'`

i s a -> (i, a) (`^@?!`

) :: s ->`IndexedTraversal'`

i s a -> (i, a)

## Indexed Folding

ifoldMapOf :: IndexedGetting i m s a -> (i -> a -> m) -> s -> m Source #

Fold an
```
IndexedFold
```

or
```
IndexedTraversal
```

by mapping indices and values to an arbitrary
```
Monoid
```

with access
to the
```
i
```

.

When you don't need access to the index then
```
foldMapOf
```

is more flexible in what it accepts.

`foldMapOf`

l ≡`ifoldMapOf`

l`.`

`const`

`ifoldMapOf`

::`IndexedGetter`

i s a -> (i -> a -> m) -> s -> m`ifoldMapOf`

::`Monoid`

m =>`IndexedFold`

i s a -> (i -> a -> m) -> s -> m`ifoldMapOf`

::`IndexedLens'`

i s a -> (i -> a -> m) -> s -> m`ifoldMapOf`

::`Monoid`

m =>`IndexedTraversal'`

i s a -> (i -> a -> m) -> s -> m

ifoldrOf :: IndexedGetting i ( Endo r) s a -> (i -> a -> r -> r) -> r -> s -> r Source #

Right-associative fold of parts of a structure that are viewed through an
```
IndexedFold
```

or
```
IndexedTraversal
```

with
access to the
```
i
```

.

When you don't need access to the index then
```
foldrOf
```

is more flexible in what it accepts.

`foldrOf`

l ≡`ifoldrOf`

l`.`

`const`

`ifoldrOf`

::`IndexedGetter`

i s a -> (i -> a -> r -> r) -> r -> s -> r`ifoldrOf`

::`IndexedFold`

i s a -> (i -> a -> r -> r) -> r -> s -> r`ifoldrOf`

::`IndexedLens'`

i s a -> (i -> a -> r -> r) -> r -> s -> r`ifoldrOf`

::`IndexedTraversal'`

i s a -> (i -> a -> r -> r) -> r -> s -> r

ifoldlOf :: IndexedGetting i ( Dual ( Endo r)) s a -> (i -> r -> a -> r) -> r -> s -> r Source #

Left-associative fold of the parts of a structure that are viewed through an
```
IndexedFold
```

or
```
IndexedTraversal
```

with
access to the
```
i
```

.

When you don't need access to the index then
```
foldlOf
```

is more flexible in what it accepts.

`foldlOf`

l ≡`ifoldlOf`

l`.`

`const`

`ifoldlOf`

::`IndexedGetter`

i s a -> (i -> r -> a -> r) -> r -> s -> r`ifoldlOf`

::`IndexedFold`

i s a -> (i -> r -> a -> r) -> r -> s -> r`ifoldlOf`

::`IndexedLens'`

i s a -> (i -> r -> a -> r) -> r -> s -> r`ifoldlOf`

::`IndexedTraversal'`

i s a -> (i -> r -> a -> r) -> r -> s -> r

ianyOf :: IndexedGetting i Any s a -> (i -> a -> Bool ) -> s -> Bool Source #

Return whether or not any element viewed through an
```
IndexedFold
```

or
```
IndexedTraversal
```

satisfy a predicate, with access to the
```
i
```

.

When you don't need access to the index then
```
anyOf
```

is more flexible in what it accepts.

`anyOf`

l ≡`ianyOf`

l`.`

`const`

`ianyOf`

::`IndexedGetter`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

`ianyOf`

::`IndexedFold`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

`ianyOf`

::`IndexedLens'`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

`ianyOf`

::`IndexedTraversal'`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

iallOf :: IndexedGetting i All s a -> (i -> a -> Bool ) -> s -> Bool Source #

Return whether or not all elements viewed through an
```
IndexedFold
```

or
```
IndexedTraversal
```

satisfy a predicate, with access to the
```
i
```

.

When you don't need access to the index then
```
allOf
```

is more flexible in what it accepts.

`allOf`

l ≡`iallOf`

l`.`

`const`

`iallOf`

::`IndexedGetter`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

`iallOf`

::`IndexedFold`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

`iallOf`

::`IndexedLens'`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

`iallOf`

::`IndexedTraversal'`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

inoneOf :: IndexedGetting i Any s a -> (i -> a -> Bool ) -> s -> Bool Source #

Return whether or not none of the elements viewed through an
```
IndexedFold
```

or
```
IndexedTraversal
```

satisfy a predicate, with access to the
```
i
```

.

When you don't need access to the index then
```
noneOf
```

is more flexible in what it accepts.

`noneOf`

l ≡`inoneOf`

l`.`

`const`

`inoneOf`

::`IndexedGetter`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

`inoneOf`

::`IndexedFold`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

`inoneOf`

::`IndexedLens'`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

`inoneOf`

::`IndexedTraversal'`

i s a -> (i -> a ->`Bool`

) -> s ->`Bool`

itraverseOf_ :: Functor f => IndexedGetting i ( Traversed r f) s a -> (i -> a -> f r) -> s -> f () Source #

Traverse the targets of an
```
IndexedFold
```

or
```
IndexedTraversal
```

with access to the
```
i
```

, discarding the results.

When you don't need access to the index then
```
traverseOf_
```

is more flexible in what it accepts.

`traverseOf_`

l ≡`itraverseOf`

l`.`

`const`

`itraverseOf_`

::`Functor`

f =>`IndexedGetter`

i s a -> (i -> a -> f r) -> s -> f ()`itraverseOf_`

::`Applicative`

f =>`IndexedFold`

i s a -> (i -> a -> f r) -> s -> f ()`itraverseOf_`

::`Functor`

f =>`IndexedLens'`

i s a -> (i -> a -> f r) -> s -> f ()`itraverseOf_`

::`Applicative`

f =>`IndexedTraversal'`

i s a -> (i -> a -> f r) -> s -> f ()

iforOf_ :: Functor f => IndexedGetting i ( Traversed r f) s a -> s -> (i -> a -> f r) -> f () Source #

Traverse the targets of an
```
IndexedFold
```

or
```
IndexedTraversal
```

with access to the index, discarding the results
(with the arguments flipped).

`iforOf_`

≡`flip`

`.`

`itraverseOf_`

When you don't need access to the index then
```
forOf_
```

is more flexible in what it accepts.

`forOf_`

l a ≡`iforOf_`

l a`.`

`const`

`iforOf_`

::`Functor`

f =>`IndexedGetter`

i s a -> s -> (i -> a -> f r) -> f ()`iforOf_`

::`Applicative`

f =>`IndexedFold`

i s a -> s -> (i -> a -> f r) -> f ()`iforOf_`

::`Functor`

f =>`IndexedLens'`

i s a -> s -> (i -> a -> f r) -> f ()`iforOf_`

::`Applicative`

f =>`IndexedTraversal'`

i s a -> s -> (i -> a -> f r) -> f ()

imapMOf_ :: Monad m => IndexedGetting i ( Sequenced r m) s a -> (i -> a -> m r) -> s -> m () Source #

Run monadic actions for each target of an
```
IndexedFold
```

or
```
IndexedTraversal
```

with access to the index,
discarding the results.

When you don't need access to the index then
```
mapMOf_
```

is more flexible in what it accepts.

`mapMOf_`

l ≡`imapMOf`

l`.`

`const`

`imapMOf_`

::`Monad`

m =>`IndexedGetter`

i s a -> (i -> a -> m r) -> s -> m ()`imapMOf_`

::`Monad`

m =>`IndexedFold`

i s a -> (i -> a -> m r) -> s -> m ()`imapMOf_`

::`Monad`

m =>`IndexedLens'`

i s a -> (i -> a -> m r) -> s -> m ()`imapMOf_`

::`Monad`

m =>`IndexedTraversal'`

i s a -> (i -> a -> m r) -> s -> m ()

iforMOf_ :: Monad m => IndexedGetting i ( Sequenced r m) s a -> s -> (i -> a -> m r) -> m () Source #

Run monadic actions for each target of an
```
IndexedFold
```

or
```
IndexedTraversal
```

with access to the index,
discarding the results (with the arguments flipped).

`iforMOf_`

≡`flip`

`.`

`imapMOf_`

When you don't need access to the index then
```
forMOf_
```

is more flexible in what it accepts.

`forMOf_`

l a ≡`iforMOf`

l a`.`

`const`

`iforMOf_`

::`Monad`

m =>`IndexedGetter`

i s a -> s -> (i -> a -> m r) -> m ()`iforMOf_`

::`Monad`

m =>`IndexedFold`

i s a -> s -> (i -> a -> m r) -> m ()`iforMOf_`

::`Monad`

m =>`IndexedLens'`

i s a -> s -> (i -> a -> m r) -> m ()`iforMOf_`

::`Monad`

m =>`IndexedTraversal'`

i s a -> s -> (i -> a -> m r) -> m ()

iconcatMapOf :: IndexedGetting i [r] s a -> (i -> a -> [r]) -> s -> [r] Source #

Concatenate the results of a function of the elements of an
```
IndexedFold
```

or
```
IndexedTraversal
```

with access to the index.

When you don't need access to the index then
```
concatMapOf
```

is more flexible in what it accepts.

`concatMapOf`

l ≡`iconcatMapOf`

l`.`

`const`

`iconcatMapOf`

≡`ifoldMapOf`

`iconcatMapOf`

::`IndexedGetter`

i s a -> (i -> a -> [r]) -> s -> [r]`iconcatMapOf`

::`IndexedFold`

i s a -> (i -> a -> [r]) -> s -> [r]`iconcatMapOf`

::`IndexedLens'`

i s a -> (i -> a -> [r]) -> s -> [r]`iconcatMapOf`

::`IndexedTraversal'`

i s a -> (i -> a -> [r]) -> s -> [r]

ifindOf :: IndexedGetting i ( Endo ( Maybe a)) s a -> (i -> a -> Bool ) -> s -> Maybe a Source #

The
```
ifindOf
```

function takes an
```
IndexedFold
```

or
```
IndexedTraversal
```

, a predicate that is also
supplied the index, a structure and returns the left-most element of the structure
matching the predicate, or
```
Nothing
```

if there is no such element.

When you don't need access to the index then
```
findOf
```

is more flexible in what it accepts.

`findOf`

l ≡`ifindOf`

l`.`

`const`

`ifindOf`

::`IndexedGetter`

i s a -> (i -> a ->`Bool`

) -> s ->`Maybe`

a`ifindOf`

::`IndexedFold`

i s a -> (i -> a ->`Bool`

) -> s ->`Maybe`

a`ifindOf`

::`IndexedLens'`

i s a -> (i -> a ->`Bool`

) -> s ->`Maybe`

a`ifindOf`

::`IndexedTraversal'`

i s a -> (i -> a ->`Bool`

) -> s ->`Maybe`

a

ifindMOf :: Monad m => IndexedGetting i ( Endo (m ( Maybe a))) s a -> (i -> a -> m Bool ) -> s -> m ( Maybe a) Source #

The
```
ifindMOf
```

function takes an
```
IndexedFold
```

or
```
IndexedTraversal
```

, a monadic predicate that is also
supplied the index, a structure and returns in the monad the left-most element of the structure
matching the predicate, or
```
Nothing
```

if there is no such element.

When you don't need access to the index then
```
findMOf
```

is more flexible in what it accepts.

`findMOf`

l ≡`ifindMOf`

l`.`

`const`

`ifindMOf`

::`Monad`

m =>`IndexedGetter`

i s a -> (i -> a -> m`Bool`

) -> s -> m (`Maybe`

a)`ifindMOf`

::`Monad`

m =>`IndexedFold`

i s a -> (i -> a -> m`Bool`

) -> s -> m (`Maybe`

a)`ifindMOf`

::`Monad`

m =>`IndexedLens'`

i s a -> (i -> a -> m`Bool`

) -> s -> m (`Maybe`

a)`ifindMOf`

::`Monad`

m =>`IndexedTraversal'`

i s a -> (i -> a -> m`Bool`

) -> s -> m (`Maybe`

a)

ifoldrOf' :: IndexedGetting i ( Dual ( Endo (r -> r))) s a -> (i -> a -> r -> r) -> r -> s -> r Source #

*
Strictly
*
fold right over the elements of a structure with an index.

When you don't need access to the index then
```
foldrOf'
```

is more flexible in what it accepts.

`foldrOf'`

l ≡`ifoldrOf'`

l`.`

`const`

`ifoldrOf'`

::`IndexedGetter`

i s a -> (i -> a -> r -> r) -> r -> s -> r`ifoldrOf'`

::`IndexedFold`

i s a -> (i -> a -> r -> r) -> r -> s -> r`ifoldrOf'`

::`IndexedLens'`

i s a -> (i -> a -> r -> r) -> r -> s -> r`ifoldrOf'`

::`IndexedTraversal'`

i s a -> (i -> a -> r -> r) -> r -> s -> r

ifoldlOf' :: IndexedGetting i ( Endo (r -> r)) s a -> (i -> r -> a -> r) -> r -> s -> r Source #

Fold over the elements of a structure with an index, associating to the left, but
*
strictly
*
.

When you don't need access to the index then
```
foldlOf'
```

is more flexible in what it accepts.

`foldlOf'`

l ≡`ifoldlOf'`

l`.`

`const`

`ifoldlOf'`

::`IndexedGetter`

i s a -> (i -> r -> a -> r) -> r -> s -> r`ifoldlOf'`

::`IndexedFold`

i s a -> (i -> r -> a -> r) -> r -> s -> r`ifoldlOf'`

::`IndexedLens'`

i s a -> (i -> r -> a -> r) -> r -> s -> r`ifoldlOf'`

::`IndexedTraversal'`

i s a -> (i -> r -> a -> r) -> r -> s -> r

ifoldrMOf :: Monad m => IndexedGetting i ( Dual ( Endo (r -> m r))) s a -> (i -> a -> r -> m r) -> r -> s -> m r Source #

Monadic fold right over the elements of a structure with an index.

When you don't need access to the index then
```
foldrMOf
```

is more flexible in what it accepts.

`foldrMOf`

l ≡`ifoldrMOf`

l`.`

`const`

`ifoldrMOf`

::`Monad`

m =>`IndexedGetter`

i s a -> (i -> a -> r -> m r) -> r -> s -> m r`ifoldrMOf`

::`Monad`

m =>`IndexedFold`

i s a -> (i -> a -> r -> m r) -> r -> s -> m r`ifoldrMOf`

::`Monad`

m =>`IndexedLens'`

i s a -> (i -> a -> r -> m r) -> r -> s -> m r`ifoldrMOf`

::`Monad`

m =>`IndexedTraversal'`

i s a -> (i -> a -> r -> m r) -> r -> s -> m r

ifoldlMOf :: Monad m => IndexedGetting i ( Endo (r -> m r)) s a -> (i -> r -> a -> m r) -> r -> s -> m r Source #

Monadic fold over the elements of a structure with an index, associating to the left.

When you don't need access to the index then
```
foldlMOf
```

is more flexible in what it accepts.

`foldlMOf`

l ≡`ifoldlMOf`

l`.`

`const`

`ifoldlMOf`

::`Monad`

m =>`IndexedGetter`

i s a -> (i -> r -> a -> m r) -> r -> s -> m r`ifoldlMOf`

::`Monad`

m =>`IndexedFold`

i s a -> (i -> r -> a -> m r) -> r -> s -> m r`ifoldlMOf`

::`Monad`

m =>`IndexedLens'`

i s a -> (i -> r -> a -> m r) -> r -> s -> m r`ifoldlMOf`

::`Monad`

m =>`IndexedTraversal'`

i s a -> (i -> r -> a -> m r) -> r -> s -> m r

itoListOf :: IndexedGetting i ( Endo [(i, a)]) s a -> s -> [(i, a)] Source #

Extract the key-value pairs from a structure.

When you don't need access to the indices in the result, then
```
toListOf
```

is more flexible in what it accepts.

`toListOf`

l ≡`map`

`snd`

`.`

`itoListOf`

l

`itoListOf`

::`IndexedGetter`

i s a -> s -> [(i,a)]`itoListOf`

::`IndexedFold`

i s a -> s -> [(i,a)]`itoListOf`

::`IndexedLens'`

i s a -> s -> [(i,a)]`itoListOf`

::`IndexedTraversal'`

i s a -> s -> [(i,a)]

elemIndexOf :: Eq a => IndexedGetting i ( First i) s a -> a -> s -> Maybe i Source #

Retrieve the index of the first value targeted by a
```
IndexedFold
```

or
```
IndexedTraversal
```

which is equal to a given value.

`elemIndex`

≡`elemIndexOf`

`folded`

`elemIndexOf`

::`Eq`

a =>`IndexedFold`

i s a -> a -> s ->`Maybe`

i`elemIndexOf`

::`Eq`

a =>`IndexedTraversal'`

i s a -> a -> s ->`Maybe`

i

elemIndicesOf :: Eq a => IndexedGetting i ( Endo [i]) s a -> a -> s -> [i] Source #

Retrieve the indices of the values targeted by a
```
IndexedFold
```

or
```
IndexedTraversal
```

which are equal to a given value.

`elemIndices`

≡`elemIndicesOf`

`folded`

`elemIndicesOf`

::`Eq`

a =>`IndexedFold`

i s a -> a -> s -> [i]`elemIndicesOf`

::`Eq`

a =>`IndexedTraversal'`

i s a -> a -> s -> [i]

findIndexOf :: IndexedGetting i ( First i) s a -> (a -> Bool ) -> s -> Maybe i Source #

Retrieve the index of the first value targeted by a
```
IndexedFold
```

or
```
IndexedTraversal
```

which satisfies a predicate.

`findIndex`

≡`findIndexOf`

`folded`

`findIndexOf`

::`IndexedFold`

i s a -> (a ->`Bool`

) -> s ->`Maybe`

i`findIndexOf`

::`IndexedTraversal'`

i s a -> (a ->`Bool`

) -> s ->`Maybe`

i

findIndicesOf :: IndexedGetting i ( Endo [i]) s a -> (a -> Bool ) -> s -> [i] Source #

Retrieve the indices of the values targeted by a
```
IndexedFold
```

or
```
IndexedTraversal
```

which satisfy a predicate.

`findIndices`

≡`findIndicesOf`

`folded`

`findIndicesOf`

::`IndexedFold`

i s a -> (a ->`Bool`

) -> s -> [i]`findIndicesOf`

::`IndexedTraversal'`

i s a -> (a ->`Bool`

) -> s -> [i]

## Building Indexed Folds

ifiltered :: ( Indexable i p, Applicative f) => (i -> a -> Bool ) -> Optical' p ( Indexed i) f a a Source #

Filter an
```
IndexedFold
```

or
```
IndexedGetter
```

, obtaining an
```
IndexedFold
```

.

`>>>`

[0,5,5,5]`[0,0,0,5,5,5]^..traversed.ifiltered (\i a -> i <= a)`

Compose with
```
ifiltered
```

to filter another
```
IndexedLens
```

,
```
IndexedIso
```

,
```
IndexedGetter
```

,
```
IndexedFold
```

(or
```
IndexedTraversal
```

) with
access to both the value and the index.

Note: As with
```
filtered
```

, this is
*
not
*
a legal
```
IndexedTraversal
```

, unless you are very careful not to invalidate the predicate on the target!

itakingWhile :: ( Indexable i p, Profunctor q, Contravariant f, Applicative f) => (i -> a -> Bool ) -> Optical' ( Indexed i) q ( Const ( Endo (f s))) s a -> Optical' p q f s a Source #

Obtain an
```
IndexedFold
```

by taking elements from another
```
IndexedFold
```

,
```
IndexedLens
```

,
```
IndexedGetter
```

or
```
IndexedTraversal
```

while a predicate holds.

`itakingWhile`

:: (i -> a ->`Bool`

) ->`IndexedFold`

i s a ->`IndexedFold`

i s a`itakingWhile`

:: (i -> a ->`Bool`

) ->`IndexedTraversal'`

i s a ->`IndexedFold`

i s a`itakingWhile`

:: (i -> a ->`Bool`

) ->`IndexedLens'`

i s a ->`IndexedFold`

i s a`itakingWhile`

:: (i -> a ->`Bool`

) ->`IndexedGetter`

i s a ->`IndexedFold`

i s a

Note: Applying
```
itakingWhile
```

to an
```
IndexedLens
```

or
```
IndexedTraversal
```

will still allow you to use it as a
pseudo-
```
IndexedTraversal
```

, but if you change the value of any target to one where the predicate returns
```
False
```

, then you will break the
```
Traversal
```

laws and
```
Traversal
```

fusion will no longer be sound.

idroppingWhile :: ( Indexable i p, Profunctor q, Applicative f) => (i -> a -> Bool ) -> Optical ( Indexed i) q ( Compose ( State Bool ) f) s t a a -> Optical p q f s t a a Source #

Obtain an
```
IndexedFold
```

by dropping elements from another
```
IndexedFold
```

,
```
IndexedLens
```

,
```
IndexedGetter
```

or
```
IndexedTraversal
```

while a predicate holds.

`idroppingWhile`

:: (i -> a ->`Bool`

) ->`IndexedFold`

i s a ->`IndexedFold`

i s a`idroppingWhile`

:: (i -> a ->`Bool`

) ->`IndexedTraversal'`

i s a ->`IndexedFold`

i s a -- see notes`idroppingWhile`

:: (i -> a ->`Bool`

) ->`IndexedLens'`

i s a ->`IndexedFold`

i s a -- see notes`idroppingWhile`

:: (i -> a ->`Bool`

) ->`IndexedGetter`

i s a ->`IndexedFold`

i s a

Note: As with
```
droppingWhile
```

applying
```
idroppingWhile
```

to an
```
IndexedLens
```

or
```
IndexedTraversal
```

will still
allow you to use it as a pseudo-
```
IndexedTraversal
```

, but if you change the value of the first target to one
where the predicate returns
```
True
```

, then you will break the
```
Traversal
```

laws and
```
Traversal
```

fusion will
no longer be sound.

# Internal types

Used internally by
```
traverseOf_
```

and the like.

The argument
```
a
```

of the result should not be used!

#### Instances

Applicative f => Semigroup ( Traversed a f) Source # | |

Applicative f => Monoid ( Traversed a f) Source # | |

Used internally by
```
mapM_
```

and the like.

The argument
```
a
```

of the result should not be used!

See 4.16 Changelog entry for the explanation of "why not Apply f =>"?

# Fold with Reified Monoid

foldByOf :: Fold s a -> (a -> a -> a) -> a -> s -> a Source #

Fold a value using a specified
```
Fold
```

and
```
Monoid
```

operations.
This is like
```
foldBy
```

where the
```
Foldable
```

instance can be
manually specified.

`foldByOf`

`folded`

≡`foldBy`

`foldByOf`

::`Getter`

s a -> (a -> a -> a) -> a -> s -> a`foldByOf`

::`Fold`

s a -> (a -> a -> a) -> a -> s -> a`foldByOf`

::`Lens'`

s a -> (a -> a -> a) -> a -> s -> a`foldByOf`

::`Traversal'`

s a -> (a -> a -> a) -> a -> s -> a`foldByOf`

::`Iso'`

s a -> (a -> a -> a) -> a -> s -> a

`>>>`

"helloworld"`foldByOf both (++) [] ("hello","world")`

foldMapByOf :: Fold s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r Source #

Fold a value using a specified
```
Fold
```

and
```
Monoid
```

operations.
This is like
```
foldMapBy
```

where the
```
Foldable
```

instance can be
manually specified.

`foldMapByOf`

`folded`

≡`foldMapBy`

`foldMapByOf`

::`Getter`

s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r`foldMapByOf`

::`Fold`

s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r`foldMapByOf`

::`Traversal'`

s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r`foldMapByOf`

::`Lens'`

s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r`foldMapByOf`

::`Iso'`

s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r

`>>>`

10`foldMapByOf both (+) 0 length ("hello","world")`