Control.Lens.Fold

lens-4.13.2.1: Lenses, Folds and Traversals

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 | None
Language | Haskell98

Control.Lens.Fold

Contents

- Folds
- Getting Started
  - Building Folds
  - Folding
- Indexed Folds
  - Indexed Folding
  - Building Indexed Folds
- Internal types
- Fold with Reified Monoid

Description

A ``Fold` s a` is a generalization of something `Foldable`. It allows you to extract multiple results from a container. A `Foldable` container can be characterized by the behavior of ``foldMap` :: (`Foldable` t, `Monoid` m) => (a -> m) -> t a -> m`. Since we want to be able to work with monomorphic containers, we could generalize this signature to `forall m. `Monoid` m => (a -> m) -> s -> m`, and then decorate it with `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
- (^?!) :: 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
- 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]
- 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 ()
- 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
- 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 :: 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 :: 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
- 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)
- (^@?!) :: 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

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

A ``Fold` s a` provides a structure with operations very similar to those of the `Foldable` typeclass, see `foldMapOf` and the other `Fold` combinators.

By convention, if there exists a `foo` method that expects a ``Foldable` (f a)`, then there should be a `fooOf` method that takes a ``Fold` s a` and a value of type `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

Every `IndexedFold` is a valid `Fold` and can be used for `Getting`.

# Getting Started

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

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

    >>> [[1,2],[3]]^..id
    [[[1,2],[3]]]
    >>> [[1,2],[3]]^..traverse
    [[1,2],[3]]
    >>> [[1,2],[3]]^..traverse.traverse
    [1,2,3]

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

    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

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.

    >>> Left 4 ^?_Left
    Just 4

    >>> Right 4 ^?_Left
    Nothing

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

    >>> "world" ^? ix 20
    Nothing

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

(^?!) :: s -> Getting (Endo a) s a -> a infixl 8

Perform an *UNSAFE* `head` of a `Fold` or `Traversal` assuming that it is there.

    >>> Left 4 ^?! _Left
    4

    >>> "world" ^?! ix 3
    'l'

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

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

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

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)

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)

previews :: MonadReader s m => Getting (First r) s a -> (a -> r) -> m (Maybe r)

Retrieve a function of the first value targeted by a `Fold` or `Traversal` (or `Just` the result from a `Getter` or `Lens`).

This is usually applied in the `Reader` `Monad` `(->) s`.

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

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)

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)

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)

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

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)

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

Check to see if this `Fold` or `Traversal` matches 1 or more entries.

    >>> has (element 0) []
    False

    >>> has _Left (Left 12)
    True

    >>> has _Right (Left 12)
    False

This will always return `True` for a `Lens` or `Getter`.

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

    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

hasn't :: Getting All s a -> s -> Bool

Check to see if this `Fold` or `Traversal` has no matches.

    >>> hasn't _Left (Right 12)
    True

    >>> hasn't _Left (Left 12)
    False

## Building Folds

folding :: Foldable f => (s -> f a) -> Fold s a

Obtain a `Fold` by lifting an operation that returns a `Foldable` result.

This can be useful to lift operations from `Data.List` and elsewhere into a `Fold`.

    >>> [1,2,3,4]^..folding tail
    [2,3,4]

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

Obtain a `Fold` by lifting `foldr` like function.

    >>> [1,2,3,4]^..foldring foldr
    [1,2,3,4]

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

Obtain `FoldWithIndex` by lifting `ifoldr` like function.

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

Obtain a `Fold` from any `Foldable` indexed by ordinal position.

    >>> Just 3^..folded
    [3]

    >>> Nothing^..folded
    []

    >>> [(1,2),(3,4)]^..folded.both
    [1,2,3,4]

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

Obtain a `Fold` from any `Foldable` indexed by ordinal position.

unfolded :: (b -> Maybe (a, b)) -> Fold b a

Build a `Fold` that unfolds its values from a seed.

    unfoldr ≡ toListOf . unfolded

    >>> 10^..unfolded (\b -> if b == 0 then Nothing else Just (b, b-1))
    [10,9,8,7,6,5,4,3,2,1]

iterated :: Apply f => (a -> a) -> LensLike' f a a

`x `^.` `iterated` f` returns an infinite `Fold1` of repeated applications of `f` to `x`.

    toListOf (iterated f) a ≡ iterate f a

    iterated :: (a -> a) -> Fold1 a a

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

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 = `filtered` `even`` the second `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!

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

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

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

repeated :: Apply f => LensLike' f a a

Form a `Fold1` by repeating the input forever.

    repeat ≡ toListOf repeated

    >>> timingOut $ 5^..taking 20 repeated
    [5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5]

    repeated :: Fold1 a a

replicated :: Int -> Fold a a

A `Fold` that replicates its input `n` times.

    replicate n ≡ toListOf (replicated n)

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

cycled :: Apply f => LensLike f s t a b -> LensLike f s t a b

Transform a non-empty `Fold` into a `Fold1` that loops over its elements over and over.

    >>> timingOut $ [1,2,3]^..taking 7 (cycled traverse)
    [1,2,3,1,2,3,1]

    cycled :: Fold1 s a -> Fold1 s a

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

Obtain a `Fold` by taking elements from another `Fold`, `Lens`, `Iso`, `Getter` or `Traversal` while a predicate holds.

    takeWhile p ≡ toListOf (takingWhile p folded)

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

    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

Obtain a `Fold` by dropping elements from another `Fold`, `Lens`, `Iso`, `Getter` or `Traversal` while a predicate holds.

    dropWhile p ≡ toListOf (droppingWhile p folded)

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

    >>> toListOf (droppingWhile (<=3) folded) [1,6,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

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

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

Map each part of a structure viewed through a `Lens`, `Getter`, `Fold` or `Traversal` to a monoid and combine the results.

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

    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

Combine the elements of a structure viewed through a `Lens`, `Getter`, `Fold` or `Traversal` using a monoid.

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

    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

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

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

toListOf :: Getting (Endo [a]) s a -> s -> [a]

Extract a list of the targets of a `Fold`. See also (`^..`).

    toList ≡ toListOf folded
    (^..) ≡ flip toListOf

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

Returns `True` if any target of a `Fold` satisfies a predicate.

    >>> anyOf both (=='x') ('x','y')
    True
    >>> import Data.Data.Lens
    >>> anyOf biplate (== "world") (((),2::Int),"hello",("world",11::Int))
    True

    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

Returns `True` if every target of a `Fold` satisfies a predicate.

    >>> allOf both (>=3) (4,5)
    True
    >>> allOf folded (>=2) [1..10]
    False

    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

Returns `True` only if no targets of a `Fold` satisfy a predicate.

    >>> noneOf each (is _Nothing) (Just 3, Just 4, Just 5)
    True
    >>> noneOf (folded.folded) (<10) [[13,99,20],[3,71,42]]
    False

    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

Returns `True` if every target of a `Fold` is `True`.

    >>> andOf both (True,False)
    False
    >>> andOf both (True,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

Returns `True` if any target of a `Fold` is `True`.

    >>> orOf both (True,False)
    True
    >>> orOf both (False,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

Calculate the `Product` of every number targeted by a `Fold`.

    >>> productOf both (4,5)
    20
    >>> productOf folded [1,2,3,4,5]
    120

    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

Calculate the `Sum` of every number targeted by a `Fold`.

    >>> sumOf both (5,6)
    11
    >>> sumOf folded [1,2,3,4]
    10
    >>> sumOf (folded.both) [(1,2),(3,4)]
    10
    >>> import Data.Data.Lens
    >>> sumOf biplate [(1::Int,[]),(2,[(3::Int,4::Int)])] :: Int
    10

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

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

    >>> traverseOf_ both putStrLn ("hello","world")
    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 ()

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

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

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

Evaluate each action in observed by a `Fold` on a structure from left to right, ignoring the results.

    sequenceA_ ≡ sequenceAOf_ folded

    >>> sequenceAOf_ both (putStrLn "hello",putStrLn "world")
    hello
    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_ :: Monad m => Getting (Sequenced r m) s a -> (a -> m r) -> s -> m ()

Map each target of a `Fold` on a structure to a monadic action, evaluate these actions from left to right, and ignore the results.

    >>> mapMOf_ both putStrLn ("hello","world")
    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 ()

`forMOf_` is `mapMOf_` with two of its arguments flipped.

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

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

Evaluate each monadic action referenced by a `Fold` on the structure from left to right, and ignore the results.

    >>> sequenceOf_ both (putStrLn "hello",putStrLn "world")
    hello
    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

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

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

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

    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

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

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

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

    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]

Map a function over all the targets of a `Fold` of a container and concatenate the resulting lists.

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

    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]

Concatenate all of the lists targeted by a `Fold` into a longer list.

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

    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

Does the element occur anywhere within a given `Fold` of the structure?

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

    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

Does the element not occur anywhere within a given `Fold` of the structure?

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

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

    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

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

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

    >>> lengthOf traverse [1..10]
    10

    >>> lengthOf (traverse.traverse) [[1,2],[3,4],[5,6]]
    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

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.

    >>> nullOf _1 (1,2)
    False

    >>> nullOf ignored ()
    True

    >>> nullOf traverse []
    True

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

    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

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 ``not` `.` `null`` check of many containers.

    >>> notNullOf _1 (1,2)
    True

    >>> notNullOf traverse [1..10]
    True

    >>> notNullOf folded []
    False

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

    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

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 ``ala` `First` `.` `foldMapOf`` and gives you back access to the outermost `Just` constructor more quickly, but may have worse constant factors.

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

    >>> firstOf both (1,2)
    Just 1

    >>> firstOf ignored ()
    Nothing

    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

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 ``ala` `Last` `.` `foldMapOf`` and gives you back access to the outermost `Just` constructor more quickly, but may have worse constant factors.

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

    >>> lastOf both (1,2)
    Just 2

    >>> lastOf ignored ()
    Nothing

    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

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.

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

    >>> maximumOf traverse []
    Nothing

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

    maximum ≡ fromMaybe (error "empty") . maximumOf folded

In the interest of efficiency, This operation has semantics more strict than strictly necessary. ``rmap` `getMax` (`foldMapOf` l `Max`)` has lazier semantics but could leak memory.

    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

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.

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

    >>> minimumOf traverse []
    Nothing

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

    minimum ≡ fromMaybe (error "empty") . minimumOf folded

In the interest of efficiency, This operation has semantics more strict than strictly necessary. ``rmap` `getMin` (`foldMapOf` l `Min`)` has lazier semantics but could leak memory.

    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

Obtain the maximum element (if any) targeted by a `Fold`, `Traversal`, `Lens`, `Iso`, or `Getter` according to a user supplied `Ordering`.

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

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

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.

    >>> minimumByOf traverse (compare `on` length) ["mustard","relish","ham"]
    Just "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

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.

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

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

    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)

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.

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

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

    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

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

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

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.

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

    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

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.

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

    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

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

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

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

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

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.

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

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

    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

An infix version of `itoListOf`.

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

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

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

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

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

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

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

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

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

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

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

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

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]

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

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)

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

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

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

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

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

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

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]

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

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]

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

Filter an `IndexedFold` or `IndexedGetter`, obtaining an `IndexedFold`.

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

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

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

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

data Leftmost a

Used for `preview`.

Instances

Monoid (Leftmost a) |
Semigroup (Leftmost a) |

data Rightmost a

Used for `lastOf`.

Instances

Monoid (Rightmost a) |
Semigroup (Rightmost a) |

data Traversed a f

Used internally by `traverseOf_` and the like.

The argument `a` of the result should not be used!

Instances

Applicative f => Monoid (Traversed a f) |
Apply f => Semigroup (Traversed a f) |

data Sequenced a m

Used internally by `mapM_` and the like.

The argument `a` of the result should not be used!

Instances

Monad m => Monoid (Sequenced a m) |
Apply m => Semigroup (Sequenced a m) |

# Fold with Reified Monoid

foldBy :: Foldable t => (a -> a -> a) -> a -> t a -> a

Fold a value using its `Foldable` instance using explicitly provided `Monoid` operations. This is like `fold` where the `Monoid` instance can be manually specified.

    foldBy mappend mempty ≡ fold

    >>> foldBy (++) [] ["hello","world"]
    "helloworld"

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

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

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

foldMapBy :: Foldable t => (r -> r -> r) -> r -> (a -> r) -> t a -> r

Fold a value using its `Foldable` instance using explicitly provided `Monoid` operations. This is like `foldMap` where the `Monoid` instance can be manually specified.

    foldMapBy mappend mempty ≡ foldMap

    >>> foldMapBy (+) 0 length ["hello","world"]
    10

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

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

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