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

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

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

Stability | provisional |

Portability | Rank2Types |

Safe Haskell | Trustworthy |

Language | Haskell98 |

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.

- 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
- (^?!) :: 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, Contravariant g, Applicative g) => (s -> f a) -> LensLike g s t a b
- ifolding :: (Foldable f, Indexable i p, Contravariant g, Applicative g) => (s -> f (i, a)) -> Over p g 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
- 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 :: Profunctor p => Accessing p r s a -> p a r -> s -> r
- foldOf :: Getting a s a -> s -> a
- foldrOf :: Profunctor p => Accessing p (Endo r) s a -> p 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]
- anyOf :: Profunctor p => Accessing p Any s a -> p a Bool -> s -> Bool
- allOf :: Profunctor p => Accessing p All s a -> p a Bool -> s -> Bool
- noneOf :: Profunctor p => Accessing p Any s a -> p 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_ :: (Profunctor p, Functor f) => Accessing p (Traversed r f) s a -> p a (f r) -> s -> f ()
- forOf_ :: (Profunctor p, Functor f) => Accessing p (Traversed r f) s a -> s -> p a (f r) -> f ()
- sequenceAOf_ :: Functor f => Getting (Traversed a f) s (f a) -> s -> f ()
- mapMOf_ :: (Profunctor p, Monad m) => Accessing p (Sequenced r m) s a -> p a (m r) -> s -> m ()
- forMOf_ :: (Profunctor p, Monad m) => Accessing p (Sequenced r m) s a -> s -> p 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 :: Profunctor p => Accessing p [r] s a -> p 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
- lastOf :: Getting (Rightmost a) s a -> s -> Maybe a
- maximumOf :: Ord a => Getting (Endo (Endo (Maybe a))) s a -> s -> Maybe a
- minimumOf :: Ord a => Getting (Endo (Endo (Maybe a))) s a -> s -> Maybe 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 :: Conjoined p => Accessing p (Endo (Maybe a)) s a -> p a Bool -> s -> Maybe a
- findMOf :: (Monad m, Conjoined p) => Accessing p (Endo (m (Maybe a))) s a -> p 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 :: Getting (Endo (Maybe a)) s a -> (a -> a -> a) -> s -> a
- foldl1Of :: Getting (Dual (Endo (Maybe a))) s a -> (a -> a -> a) -> s -> a
- foldr1Of' :: Getting (Dual (Endo (Endo (Maybe a)))) s a -> (a -> a -> a) -> s -> a
- foldl1Of' :: 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
- (^@..) :: s -> IndexedGetting i (Endo [(i, a)]) s a -> [(i, a)]
- (^@?) :: s -> IndexedGetting i (Endo (Maybe (i, a))) s a -> Maybe (i, a)
- (^@?!) :: 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)]
- 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 s a a -> Optical p q f s s a 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 :: (forall i. Getting (M a i) s a) -> (a -> a -> a) -> a -> s -> a
- foldMapBy :: Foldable t => (r -> r -> r) -> r -> (a -> r) -> t a -> r
- foldMapByOf :: (forall s. Getting (M r s) t a) -> (r -> r -> r) -> r -> (a -> r) -> t -> 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]]^..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.

`>>>`

Just 4`Left 4 ^?_Left`

`>>>`

Nothing`Right 4 ^?_Left`

`>>>`

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

`>>>`

Nothing`"world" ^? ix 20`

(`^?`

) ≡`flip`

`preview`

(`^?`

) :: 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 (`^?`

).

`listToMaybe`

`.`

`toList`

≡`preview`

`folded`

This is usually applied in the `Reader`

`Monad`

`(->) s`

.

`preview`

=`view`

`.`

`pre`

`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

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

transformer stack:

`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

folding :: (Foldable f, Contravariant g, Applicative g) => (s -> f a) -> LensLike g s t a b Source

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

folded :: Foldable f => IndexedFold Int (f a) a Source

folded64 :: Foldable f => IndexedFold Int64 (f a) a Source

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

Obtain an `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 matches 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.

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 also pass the predicate! Otherwise subsequent traversals will visit fewer elements
and `Traversal`

fusion is not sound.

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 :: Profunctor p => Accessing p r s a -> p 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`

::`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`

::`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 :: Profunctor p => Accessing p (Endo r) s a -> p 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

anyOf :: Profunctor p => Accessing p Any s a -> p 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 ≡`allOf`

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 :: Profunctor p => Accessing p All s a -> p 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 :: Profunctor p => Accessing p Any s a -> p 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_ :: (Profunctor p, Functor f) => Accessing p (Traversed r f) s a -> p 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_ :: (Profunctor p, Functor f) => Accessing p (Traversed r f) s a -> s -> p 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 ()

mapMOf_ :: (Profunctor p, Monad m) => Accessing p (Sequenced r m) s a -> p 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_ :: (Profunctor p, Monad m) => Accessing p (Sequenced r m) s a -> s -> p 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 :: Profunctor p => Accessing p [r] s a -> p 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`

.

`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

and gives you back access to the outermost `ala`

`First`

`.`

`foldMapOf`

`Just`

constructor more quickly, but may have worse
constant factors.

`>>>`

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

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

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

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

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 :: Conjoined p => Accessing p (Endo (Maybe a)) s a -> p 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, Conjoined p) => Accessing p (Endo (m (Maybe a))) s a -> p 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 :: 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 :: 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' :: 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' :: 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

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

(^@?!) :: 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`

`fst`

`.`

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

## 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 `filtered`

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 s a a -> Optical p q f s s a 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

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

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 targets to ones 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!

Used internally by `mapM_`

and the like.

The argument `a`

of the result should not be used!

# Fold with Reified Monoid

foldMapByOf :: (forall s. Getting (M r s) t a) -> (r -> r -> r) -> r -> (a -> r) -> t -> r Source