Portability  Rank2Types 

Stability  provisional 
Maintainer  Edward Kmett <ekmett@gmail.com> 
Safe Haskell  SafeInfered 
A
is a generalization of something Fold
a cFoldable
. It allows
you to extract multiple results from a container. A Foldable
container
can be characterized by the behavior of
foldMap :: (
.
Since we want to be able to work with monomorphic containers, we could
generalize this signature to Foldable
t, Monoid
m) => (c > m) > t c > mforall m.
,
and then decorate it with Monoid
m => (c > m) > a > mAccessor
to obtain
typeFold
a c = forall m.Monoid
m =>Getting
m a c
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 a c = forall f. (Gettable f, Applicative f) => (c > f c) > a > f a
 (^?) :: a > Getting (First c) a c > Maybe c
 (^..) :: a > Getting [c] a c > [c]
 folding :: (Foldable f, Applicative g, Gettable g) => (a > f c) > LensLike g a b c d
 folded :: Foldable f => Fold (f c) c
 unfolded :: (b > Maybe (a, b)) > Fold b a
 iterated :: (a > a) > Fold a a
 filtered :: (Gettable f, Applicative f) => (c > Bool) > SimpleLensLike f a c > SimpleLensLike f a c
 backwards :: LensLike (Backwards f) a b c d > LensLike f a b c d
 repeated :: Fold a a
 replicated :: Int > Fold a a
 cycled :: (Applicative f, Gettable f) => SimpleLensLike f a c > SimpleLensLike f a c
 takingWhile :: (Gettable f, Applicative f) => (c > Bool) > Getting (Endo (f a)) a c > SimpleLensLike f a c
 droppingWhile :: (Gettable f, Applicative f) => (c > Bool) > Getting (Endo (f a)) a c > SimpleLensLike f a c
 foldMapOf :: Getting r a c > (c > r) > a > r
 foldOf :: Getting c a c > a > c
 foldrOf :: Getting (Endo e) a c > (c > e > e) > e > a > e
 foldlOf :: Getting (Dual (Endo e)) a c > (e > c > e) > e > a > e
 toListOf :: Getting [c] a c > a > [c]
 anyOf :: Getting Any a c > (c > Bool) > a > Bool
 allOf :: Getting All a c > (c > Bool) > a > Bool
 andOf :: Getting All a Bool > a > Bool
 orOf :: Getting Any a Bool > a > Bool
 productOf :: Getting (Product c) a c > a > c
 sumOf :: Getting (Sum c) a c > a > c
 traverseOf_ :: Functor f => Getting (Traversed f) a c > (c > f e) > a > f ()
 forOf_ :: Functor f => Getting (Traversed f) a c > a > (c > f e) > f ()
 sequenceAOf_ :: Functor f => Getting (Traversed f) a (f ()) > a > f ()
 mapMOf_ :: Monad m => Getting (Sequenced m) a c > (c > m e) > a > m ()
 forMOf_ :: Monad m => Getting (Sequenced m) a c > a > (c > m e) > m ()
 sequenceOf_ :: Monad m => Getting (Sequenced m) a (m c) > a > m ()
 asumOf :: Alternative f => Getting (Endo (f c)) a (f c) > a > f c
 msumOf :: MonadPlus m => Getting (Endo (m c)) a (m c) > a > m c
 concatMapOf :: Getting [e] a c > (c > [e]) > a > [e]
 concatOf :: Getting [e] a [e] > a > [e]
 elemOf :: Eq c => Getting Any a c > c > a > Bool
 notElemOf :: Eq c => Getting All a c > c > a > Bool
 lengthOf :: Getting (Sum Int) a c > a > Int
 nullOf :: Getting All a c > a > Bool
 headOf :: Getting (First c) a c > a > Maybe c
 lastOf :: Getting (Last c) a c > a > Maybe c
 maximumOf :: Getting (Max c) a c > a > Maybe c
 minimumOf :: Getting (Min c) a c > a > Maybe c
 maximumByOf :: Getting (Endo (Maybe c)) a c > (c > c > Ordering) > a > Maybe c
 minimumByOf :: Getting (Endo (Maybe c)) a c > (c > c > Ordering) > a > Maybe c
 findOf :: Getting (First c) a c > (c > Bool) > a > Maybe c
 foldrOf' :: Getting (Dual (Endo (e > e))) a c > (c > e > e) > e > a > e
 foldlOf' :: Getting (Endo (e > e)) a c > (e > c > e) > e > a > e
 foldr1Of :: Getting (Endo (Maybe c)) a c > (c > c > c) > a > c
 foldl1Of :: Getting (Dual (Endo (Maybe c))) a c > (c > c > c) > a > c
 foldrMOf :: Monad m => Getting (Dual (Endo (e > m e))) a c > (c > e > m e) > e > a > m e
 foldlMOf :: Monad m => Getting (Endo (e > m e)) a c > (e > c > m e) > e > a > m e
 newtype ReifiedFold a c = ReifyFold {
 reflectFold :: Fold a c
Folds
type Fold a c = forall f. (Gettable f, Applicative f) => (c > f c) > a > f aSource
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
a cFoldable
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 c)fooOf
method that takes a
and a value of type Fold
a ca
.
A Getter
is a legal Fold
that just ignores the supplied Monoid
Unlike a Traversal
a Fold
is readonly. Since a Fold
cannot be used to write back
there are no lens laws that apply.
(^?) :: a > Getting (First c) a c > Maybe cSource
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.
(^?
) =flip
headOf
(^?
) :: a >Getter
a c >Maybe
c (^?
) :: a >Fold
a c >Maybe
c (^?
) :: a >Simple
Lens
a c >Maybe
c (^?
) :: a >Simple
Iso
a c >Maybe
c (^?
) :: a >Simple
Traversal
a c >Maybe
c
Building Folds
iterated :: (a > a) > Fold a aSource
x ^.
Return an infinite fold of repeated applications of iterated
ff
to x
.
toListOf (iterated f) a = iterate f a
filtered :: (Gettable f, Applicative f) => (c > Bool) > SimpleLensLike f a c > SimpleLensLike f a cSource
replicated :: Int > Fold a aSource
A fold that replicates its input n
times.
replicate
n =toListOf
(replicated
n)
cycled :: (Applicative f, Gettable f) => SimpleLensLike f a c > SimpleLensLike f a cSource
Transform a fold into a fold that loops over its elements over and over.
>>>
import Control.Lens
>>>
take 6 $ toListOf (cycled traverse) [1,2,3]
[1,2,3,1,2,3]
takingWhile :: (Gettable f, Applicative f) => (c > Bool) > Getting (Endo (f a)) a c > SimpleLensLike f a cSource
droppingWhile :: (Gettable f, Applicative f) => (c > Bool) > Getting (Endo (f a)) a c > SimpleLensLike f a cSource
Folding
foldMapOf :: Getting r a c > (c > r) > a > rSource
foldMap
=foldMapOf
folded
foldMapOf
=views
foldMapOf
::Getter
a c > (c > r) > a > rfoldMapOf
::Monoid
r =>Fold
a c > (c > r) > a > rfoldMapOf
::Simple
Lens
a c > (c > r) > a > rfoldMapOf
::Simple
Iso
a c > (c > r) > a > rfoldMapOf
::Monoid
r =>Simple
Traversal
a c > (c > r) > a > r
foldrOf :: Getting (Endo e) a c > (c > e > e) > e > a > eSource
Rightassociative fold of parts of a structure that are viewed through a Lens
, Getter
, Fold
or Traversal
.
foldr
=foldrOf
folded
foldrOf
::Getter
a c > (c > e > e) > e > a > efoldrOf
::Fold
a c > (c > e > e) > e > a > efoldrOf
::Simple
Lens
a c > (c > e > e) > e > a > efoldrOf
::Simple
Iso
a c > (c > e > e) > e > a > efoldrOf
::Simple
Traversal
a c > (c > e > e) > e > a > e
foldlOf :: Getting (Dual (Endo e)) a c > (e > c > e) > e > a > eSource
Leftassociative fold of the parts of a structure that are viewed through a Lens
, Getter
, Fold
or Traversal
.
foldl
=foldlOf
folded
foldlOf
::Getter
a c > (e > c > e) > e > a > efoldlOf
::Fold
a c > (e > c > e) > e > a > efoldlOf
::Simple
Lens
a c > (e > c > e) > e > a > efoldlOf
::Simple
Iso
a c > (e > c > e) > e > a > efoldlOf
::Simple
Traversal
a c > (e > c > e) > e > a > e
traverseOf_ :: Functor f => Getting (Traversed f) a c > (c > f e) > a > f ()Source
When passed a Getter
, traverseOf_
can work over a Functor
.
When passed a Fold
, traverseOf_
requires an Applicative
.
traverse_
=traverseOf_
folded
traverseOf_
_2
::Functor
f => (c > f e) > (c1, c) > f ()
traverseOf_
traverseLeft
::Applicative
f => (a > f b) >Either
a c > f ()
The rather specific signature of traverseOf_ allows it to be used as if the signature was either:
traverseOf_
::Functor
f =>Getter
a c > (c > f e) > a > f ()traverseOf_
::Applicative
f =>Fold
a c > (c > f e) > a > f ()traverseOf_
::Functor
f =>Simple
Lens
a c > (c > f e) > a > f ()traverseOf_
::Functor
f =>Simple
Iso
a c > (c > f e) > a > f ()traverseOf_
::Applicative
f =>Simple
Traversal
a c > (c > f e) > a > f ()
forOf_ :: Functor f => Getting (Traversed f) a c > a > (c > f e) > f ()Source
for_
=forOf_
folded
forOf_
::Functor
f =>Getter
a c > a > (c > f e) > f ()forOf_
::Applicative
f =>Fold
a c > a > (c > f e) > f ()forOf_
::Functor
f =>Simple
Lens
a c > a > (c > f e) > f ()forOf_
::Functor
f =>Simple
Iso
a c > a > (c > f e) > f ()forOf_
::Applicative
f =>Simple
Traversal
a c > a > (c > f e) > f ()
sequenceAOf_ :: Functor f => Getting (Traversed f) a (f ()) > a > f ()Source
sequenceA_
=sequenceAOf_
folded
sequenceAOf_
::Functor
f =>Getter
a (f ()) > a > f ()sequenceAOf_
::Applicative
f =>Fold
a (f ()) > a > f ()sequenceAOf_
::Functor
f =>Simple
Lens
a (f ()) > a > f ()sequenceAOf_
::Functor
f =>Simple
Iso
a (f ()) > a > f ()sequenceAOf_
::Applicative
f =>Simple
Traversal
a (f ()) > a > f ()
mapMOf_ :: Monad m => Getting (Sequenced m) a c > (c > m e) > a > m ()Source
mapM_
=mapMOf_
folded
mapMOf_
::Monad
m =>Getter
a c > (c > m e) > a > m ()mapMOf_
::Monad
m =>Fold
a c > (c > m e) > a > m ()mapMOf_
::Monad
m =>Simple
Lens
a c > (c > m e) > a > m ()mapMOf_
::Monad
m =>Simple
Iso
a c > (c > m e) > a > m ()mapMOf_
::Monad
m =>Simple
Traversal
a c > (c > m e) > a > m ()
forMOf_ :: Monad m => Getting (Sequenced m) a c > a > (c > m e) > m ()Source
forM_
=forMOf_
folded
forMOf_
::Monad
m =>Getter
a c > a > (c > m e) > m ()forMOf_
::Monad
m =>Fold
a c > a > (c > m e) > m ()forMOf_
::Monad
m =>Simple
Lens
a c > a > (c > m e) > m ()forMOf_
::Monad
m =>Simple
Iso
a c > a > (c > m e) > m ()forMOf_
::Monad
m =>Simple
Traversal
a c > a > (c > m e) > m ()
sequenceOf_ :: Monad m => Getting (Sequenced m) a (m c) > a > m ()Source
sequence_
=sequenceOf_
folded
sequenceOf_
::Monad
m =>Getter
a (m b) > a > m ()sequenceOf_
::Monad
m =>Fold
a (m b) > a > m ()sequenceOf_
::Monad
m =>Simple
Lens
a (m b) > a > m ()sequenceOf_
::Monad
m =>Simple
Iso
a (m b) > a > m ()sequenceOf_
::Monad
m =>Simple
Traversal
a (m b) > a > m ()
asumOf :: Alternative f => Getting (Endo (f c)) a (f c) > a > f cSource
The sum of a collection of actions, generalizing concatOf
.
asum
=asumOf
folded
asumOf
::Alternative
f =>Getter
a c > a > f casumOf
::Alternative
f =>Fold
a c > a > f casumOf
::Alternative
f =>Simple
Lens
a c > a > f casumOf
::Alternative
f =>Simple
Iso
a c > a > f casumOf
::Alternative
f =>Simple
Traversal
a c > a > f c
msumOf :: MonadPlus m => Getting (Endo (m c)) a (m c) > a > m cSource
The sum of a collection of actions, generalizing concatOf
.
msum
=msumOf
folded
msumOf
::MonadPlus
m =>Getter
a c > a > m cmsumOf
::MonadPlus
m =>Fold
a c > a > m cmsumOf
::MonadPlus
m =>Simple
Lens
a c > a > m cmsumOf
::MonadPlus
m =>Simple
Iso
a c > a > m cmsumOf
::MonadPlus
m =>Simple
Traversal
a c > a > m c
concatMapOf :: Getting [e] a c > (c > [e]) > a > [e]Source
concatMap
=concatMapOf
folded
concatMapOf
::Getter
a c > (c > [e]) > a > [e]concatMapOf
::Fold
a c > (c > [e]) > a > [e]concatMapOf
::Simple
Lens
a c > (c > [e]) > a > [e]concatMapOf
::Simple
Iso
a c > (c > [e]) > a > [e]concatMapOf
::Simple
Traversal
a c > (c > [e]) > a > [e]
lengthOf :: Getting (Sum Int) a c > a > IntSource
Note: this can be rather inefficient for large containers.
length
=lengthOf
folded
>>>
import Control.Lens
>>>
lengthOf _1 ("hello",())
1
lengthOf
(folded
.folded
) ::Foldable
f => f (g a) >Int
lengthOf
::Getter
a c > a >Int
lengthOf
::Fold
a c > a >Int
lengthOf
::Simple
Lens
a c > a >Int
lengthOf
::Simple
Iso
a c > a >Int
lengthOf
::Simple
Traversal
a c > a >Int
nullOf :: Getting All a c > a > BoolSource
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.
>>>
import Control.Lens
>>>
nullOf _1 (1,2)
False
nullOf
(folded
._1
.folded
) ::Foldable
f => f (g a, b) >Bool
nullOf
::Getter
a c > a >Bool
nullOf
::Fold
a c > a >Bool
nullOf
::Simple
Iso
a c > a >Bool
nullOf
::Simple
Lens
a c > a >Bool
nullOf
::Simple
Traversal
a c > a >Bool
headOf :: Getting (First c) a c > a > Maybe cSource
Perform a safe head
of a Fold
or Traversal
or retrieve Just
the result
from a Getter
or Lens
. See also (^?
).
listToMaybe
.toList
=headOf
folded
headOf
::Getter
a c > a >Maybe
cheadOf
::Fold
a c > a >Maybe
cheadOf
::Simple
Lens
a c > a >Maybe
cheadOf
::Simple
Iso
a c > a >Maybe
cheadOf
::Simple
Traversal
a c > a >Maybe
c
maximumOf :: Getting (Max c) a c > a > Maybe cSource
Obtain the maximum element (if any) targeted by a Fold
or Traversal
Note: maximumOf on a valid Iso
, Lens
or Getter
will always return Just
a value.
maximum
=fromMaybe
(error
empty) .maximumOf
folded
maximumOf
::Getter
a c > a >Maybe
cmaximumOf
::Ord
c =>Fold
a c > a >Maybe
cmaximumOf
::Simple
Iso
a c > a >Maybe
cmaximumOf
::Simple
Lens
a c > a >Maybe
cmaximumOf
::Ord
c =>Simple
Traversal
a c > a >Maybe
c
minimumOf :: Getting (Min c) a c > a > Maybe cSource
Obtain the minimum element (if any) targeted by a Fold
or Traversal
Note: minimumOf on a valid Iso
, Lens
or Getter
will always return Just
a value.
minimum
=fromMaybe
(error
empty) .minimumOf
folded
minimumOf
::Getter
a c > a >Maybe
cminimumOf
::Ord
c =>Fold
a c > a >Maybe
cminimumOf
::Simple
Iso
a c > a >Maybe
cminimumOf
::Simple
Lens
a c > a >Maybe
cminimumOf
::Ord
c =>Simple
Traversal
a c > a >Maybe
c
maximumByOf :: Getting (Endo (Maybe c)) a c > (c > c > Ordering) > a > Maybe cSource
Obtain the maximum element (if any) targeted by a Fold
, Traversal
, Lens
, Iso
,
or Getter
according to a user supplied ordering.
maximumBy
cmp =fromMaybe
(error
empty) .maximumByOf
folded
cmp
maximumByOf
::Getter
a c > (c > c >Ordering
) > a >Maybe
cmaximumByOf
::Fold
a c > (c > c >Ordering
) > a >Maybe
cmaximumByOf
::Simple
Iso
a c > (c > c >Ordering
) > a >Maybe
cmaximumByOf
::Simple
Lens
a c > (c > c >Ordering
) > a >Maybe
cmaximumByOf
::Simple
Traversal
a c > (c > c >Ordering
) > a >Maybe
c
minimumByOf :: Getting (Endo (Maybe c)) a c > (c > c > Ordering) > a > Maybe cSource
Obtain the minimum element (if any) targeted by a Fold
, Traversal
, Lens
, Iso
or Getter
according to a user supplied ordering.
minimumBy cmp = fromMaybe (error "empty") . minimumByOf folded cmp
minimumByOf
::Getter
a c > (c > c >Ordering
) > a >Maybe
cminimumByOf
::Fold
a c > (c > c >Ordering
) > a >Maybe
cminimumByOf
::Simple
Iso
a c > (c > c >Ordering
) > a >Maybe
cminimumByOf
::Simple
Lens
a c > (c > c >Ordering
) > a >Maybe
cminimumByOf
::Simple
Traversal
a c > (c > c >Ordering
) > a >Maybe
c
findOf :: Getting (First c) a c > (c > Bool) > a > Maybe cSource
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
::Getter
a c > (c >Bool
) > a >Maybe
cfindOf
::Fold
a c > (c >Bool
) > a >Maybe
cfindOf
::Simple
Iso
a c > (c >Bool
) > a >Maybe
cfindOf
::Simple
Lens
a c > (c >Bool
) > a >Maybe
cfindOf
::Simple
Traversal
a c > (c >Bool
) > a >Maybe
c
foldrOf' :: Getting (Dual (Endo (e > e))) a c > (c > e > e) > e > a > eSource
Strictly fold right over the elements of a structure.
foldr'
=foldrOf'
folded
foldrOf'
::Getter
a c > (c > e > e) > e > a > efoldrOf'
::Fold
a c > (c > e > e) > e > a > efoldrOf'
::Simple
Iso
a c > (c > e > e) > e > a > efoldrOf'
::Simple
Lens
a c > (c > e > e) > e > a > efoldrOf'
::Simple
Traversal
a c > (c > e > e) > e > a > e
foldlOf' :: Getting (Endo (e > e)) a c > (e > c > e) > e > a > eSource
Fold over the elements of a structure, associating to the left, but strictly.
foldl'
=foldlOf'
folded
foldlOf'
::Getter
a c > (e > c > e) > e > a > efoldlOf'
::Fold
a c > (e > c > e) > e > a > efoldlOf'
::Simple
Iso
a c > (e > c > e) > e > a > efoldlOf'
::Simple
Lens
a c > (e > c > e) > e > a > efoldlOf'
::Simple
Traversal
a c > (e > c > e) > e > a > e
foldr1Of :: Getting (Endo (Maybe c)) a c > (c > c > c) > a > cSource
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
l f =foldr1
f .toListOf
l
foldr1
=foldr1Of
folded
foldr1Of
::Getter
a c > (c > c > c) > a > cfoldr1Of
::Fold
a c > (c > c > c) > a > cfoldr1Of
::Simple
Iso
a c > (c > c > c) > a > cfoldr1Of
::Simple
Lens
a c > (c > c > c) > a > cfoldr1Of
::Simple
Traversal
a c > (c > c > c) > a > c
foldl1Of :: Getting (Dual (Endo (Maybe c))) a c > (c > c > c) > a > cSource
A variant of foldlOf
that has no base case and thus may only be applied to lenses and strutures such
that the lens views at least one element of the structure.
foldl1Of
l f =foldl1Of
l f .toList
foldl1
=foldl1Of
folded
foldl1Of
::Getter
a c > (c > c > c) > a > cfoldl1Of
::Fold
a c > (c > c > c) > a > cfoldl1Of
::Simple
Iso
a c > (c > c > c) > a > cfoldl1Of
::Simple
Lens
a c > (c > c > c) > a > cfoldl1Of
::Simple
Traversal
a c > (c > c > c) > a > c
foldrMOf :: Monad m => Getting (Dual (Endo (e > m e))) a c > (c > e > m e) > e > a > m eSource
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
a c > (c > e > m e) > e > a > m efoldrMOf
::Monad
m =>Fold
a c > (c > e > m e) > e > a > m efoldrMOf
::Monad
m =>Simple
Iso
a c > (c > e > m e) > e > a > m efoldrMOf
::Monad
m =>Simple
Lens
a c > (c > e > m e) > e > a > m efoldrMOf
::Monad
m =>Simple
Traversal
a c > (c > e > m e) > e > a > m e
foldlMOf :: Monad m => Getting (Endo (e > m e)) a c > (e > c > m e) > e > a > m eSource
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
a c > (e > c > m e) > e > a > m efoldlMOf
::Monad
m =>Fold
a c > (e > c > m e) > e > a > m efoldlMOf
::Monad
m =>Simple
Iso
a c > (e > c > m e) > e > a > m efoldlMOf
::Monad
m =>Simple
Lens
a c > (e > c > m e) > e > a > m efoldlMOf
::Monad
m =>Simple
Traversal
a c > (e > c > m e) > e > a > m e
Storing Folds
newtype ReifiedFold a c Source
Useful for storing folds in containers.
ReifyFold  
