lens-3.7.6: Lenses, Folds and Traversals

PortabilityRank2Types
Stabilityprovisional
MaintainerEdward Kmett <ekmett@gmail.com>
Safe HaskellTrustworthy

Control.Lens.Fold

Contents

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 Accessor to obtain

type Fold s a = forall m. Monoid m => Getting m s s a 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

Folds

type Fold s a = forall f. (Gettable f, Applicative f) => (a -> f a) -> s -> f sSource

A Fold describes how to retrieve multiple values in a way that can be composed with other lens-like 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.

(^..) :: s -> Getting (Endo [a]) s t a b -> [a]Source

A convenient infix (flipped) version of toListOf.

>>> [[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 -> Simple Lens s a      -> [a]
 (^..) :: s -> Simple Iso s a       -> [a]
 (^..) :: s -> Simple Traversal s a -> [a]
 (^..) :: s -> Simple Prism s a     -> [a]

(^?) :: s -> Getting (First a) s t a b -> Maybe aSource

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 preview
 (^?) :: s -> Getter s a           -> Maybe a
 (^?) :: s -> Fold s a             -> Maybe a
 (^?) :: s -> Simple Lens s a      -> Maybe a
 (^?) :: s -> Simple Iso s a       -> Maybe a
 (^?) :: s -> Simple Traversal s a -> Maybe a

(^?!) :: s -> Getting (First a) s t a b -> aSource

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

 (^?!) :: s -> Getter s a           -> a
 (^?!) :: s -> Fold s a             -> a
 (^?!) :: s -> Simple Lens s a      -> a
 (^?!) :: s -> Simple Iso s a       -> a
 (^?!) :: s -> Simple Traversal s a -> a

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

Retrieve the first value targeted by a Fold or Traversal (or Just the result from a Getter or Lens). See also (^?).

listToMaybe . toListpreview folded

This is usually applied in the reader monad (->) s.

 preview :: Getter s a           -> s -> Maybe a
 preview :: Fold s a             -> s -> Maybe a
 preview :: Simple Lens s a      -> s -> Maybe a
 preview :: Simple Iso s a       -> s -> Maybe a
 preview :: Simple 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 => Simple Lens s a      -> m (Maybe a)
 preview :: MonadReader s m => Simple Iso s a       -> m (Maybe a)
 preview :: MonadReader s m => Simple Traversal s a -> m (Maybe a)

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

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

This is usually applied in the reader monad (->) s.

 previews :: Getter s a           -> (a -> r) -> s -> Maybe a
 previews :: Fold s a             -> (a -> r) -> s -> Maybe a
 previews :: Simple Lens s a      -> (a -> r) -> s -> Maybe a
 previews :: Simple Iso s a       -> (a -> r) -> s -> Maybe a
 previews :: Simple Traversal s a -> (a -> r) -> s -> Maybe a

However, it may be useful to think of its full generality when working with a monad transformer stack:

 previews :: MonadReader s m => Getter s a           -> (a -> r) -> m (Maybe r)
 previews :: MonadReader s m => Fold s a             -> (a -> r) -> m (Maybe r)
 previews :: MonadReader s m => Simple Lens s a      -> (a -> r) -> m (Maybe r)
 previews :: MonadReader s m => Simple Iso s a       -> (a -> r) -> m (Maybe r)
 previews :: MonadReader s m => Simple Traversal s a -> (a -> r) -> m (Maybe r)

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

Retrieve the first value targeted by a Fold or Traversal (or Just the result from a Getter or Lens) into the current state.

 preuse :: MonadState s m => Getter s a           -> m (Maybe a)
 preuse :: MonadState s m => Fold s a             -> m (Maybe a)
 preuse :: MonadState s m => Simple Lens s a      -> m (Maybe a)
 preuse :: MonadState s m => Simple Iso s a       -> m (Maybe a)
 preuse :: MonadState s m => Simple Traversal s a -> m (Maybe a)

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

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

 preuses :: 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 => Simple Lens s a      -> (a -> r) -> m (Maybe r)
 preuses :: MonadState s m => Simple Iso s a       -> (a -> r) -> m (Maybe r)
 preuses :: MonadState s m => Simple Traversal s a -> (a -> r) -> m (Maybe r)

Building Folds

folding :: (Foldable f, Applicative g, Gettable g) => (s -> f a) -> LensLike g s t a bSource

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]

folded :: Foldable f => Fold (f a) aSource

Obtain a Fold from any Foldable.

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

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

Build a fold that unfolds its values from a seed.

unfoldrtoListOf . 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 :: (a -> a) -> Fold a aSource

x ^. iterated f Return an infinite fold of repeated applications of f to x.

toListOf (iterated f) a ≡ iterate f a

filtered :: Applicative f => (a -> Bool) -> SimpleLensLike f a aSource

Obtain a Fold that can be composed with to filter another Lens, Iso, Getter, Fold (or Traversal)

Note: This is not a legal Traversal, unless you are very careful not to invalidate the predicate on the target.

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!

filtered :: (a -> Bool) -> Fold a a

backwards :: LensLike (Backwards f) s t a b -> LensLike f s t a bSource

This allows you to traverse the elements of a Traversal or Fold in the opposite order. This will demote an IndexedTraversal or IndexedFold to a regular Traversal or Fold, respectively; to preserve the indices, use ibackwards instead.

Note: backwards should have no impact on a Getter, Setter, Lens or Iso.

To change the direction of an Iso, use from.

repeated :: Fold a aSource

Fold by repeating the input forever.

repeattoListOf repeated
>>> 5^..taking 20 repeated
[5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5]

replicated :: Int -> Fold a aSource

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 :: (Applicative f, Gettable f) => LensLike f s t a b -> LensLike f s t a bSource

Transform a fold into a fold that loops over its elements over and over.

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

takingWhile :: (Gettable f, Applicative f) => (a -> Bool) -> Getting (Endo (f s)) s s a a -> LensLike f s s a aSource

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

takeWhile p ≡ toListOf (takingWhile p folded)
>>> toListOf (takingWhile (<=3) folded) [1..]
[1,2,3]

droppingWhile :: (Gettable f, Applicative f) => (a -> Bool) -> Getting (Endo (f s, f s)) s s a a -> LensLike f s s a aSource

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]

Folding

foldMapOf :: Getting r s t a b -> (a -> r) -> s -> rSource

foldMap = foldMapOf folded
foldMapOfviews
 foldMapOf ::             Getter s a           -> (a -> r) -> s -> r
 foldMapOf :: Monoid r => Fold s a             -> (a -> r) -> s -> r
 foldMapOf ::             Simple Lens s a      -> (a -> r) -> s -> r
 foldMapOf ::             Simple Iso s a       -> (a -> r) -> s -> r
 foldMapOf :: Monoid r => Simple Traversal s a -> (a -> r) -> s -> r
 foldMapOf :: Monoid r => Simple Prism s a     -> (a -> r) -> s -> r

foldOf :: Getting a s t a b -> s -> aSource

fold = foldOf folded
foldOfview
 foldOf ::             Getter s m           -> s -> m
 foldOf :: Monoid m => Fold s m             -> s -> m
 foldOf ::             Simple Lens s m      -> s -> m
 foldOf ::             Simple Iso s m       -> s -> m
 foldOf :: Monoid m => Simple Traversal s m -> s -> m
 foldOf :: Monoid m => Simple Prism s m     -> s -> m

foldrOf :: Getting (Endo r) s t a b -> (a -> r -> r) -> r -> s -> rSource

Right-associative fold of parts of a structure that are viewed through a Lens, Getter, Fold or Traversal.

foldrfoldrOf folded
 foldrOf :: Getter s a           -> (a -> r -> r) -> r -> s -> r
 foldrOf :: Fold s a             -> (a -> r -> r) -> r -> s -> r
 foldrOf :: Simple Lens s a      -> (a -> r -> r) -> r -> s -> r
 foldrOf :: Simple Iso s a       -> (a -> r -> r) -> r -> s -> r
 foldrOf :: Simple Traversal s a -> (a -> r -> r) -> r -> s -> r
 foldrOf :: Simple Prism s a     -> (a -> r -> r) -> r -> s -> r

foldlOf :: Getting (Dual (Endo r)) s t a b -> (r -> a -> r) -> r -> s -> rSource

Left-associative fold of the parts of a structure that are viewed through a Lens, Getter, Fold or Traversal.

foldlfoldlOf folded
 foldlOf :: Getter s a           -> (r -> a -> r) -> r -> s -> r
 foldlOf :: Fold s a             -> (r -> a -> r) -> r -> s -> r
 foldlOf :: Simple Lens s a      -> (r -> a -> r) -> r -> s -> r
 foldlOf :: Simple Iso s a       -> (r -> a -> r) -> r -> s -> r
 foldlOf :: Simple Traversal s a -> (r -> a -> r) -> r -> s -> r
 foldlOf :: Simple Prism s a     -> (r -> a -> r) -> r -> s -> r

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

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

 toListtoListOf folded
 (^..) ≡ flip toListOf

anyOf :: Getting Any s t a b -> (a -> Bool) -> s -> BoolSource

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))
True
anyanyOf folded
 anyOf :: Getter s a               -> (a -> Bool) -> s -> Bool
 anyOf :: Fold s a                 -> (a -> Bool) -> s -> Bool
 anyOf :: Simple Lens s a      -> (a -> Bool) -> s -> Bool
 anyOf :: Simple Iso s a       -> (a -> Bool) -> s -> Bool
 anyOf :: Simple Traversal s a -> (a -> Bool) -> s -> Bool
 anyOf :: Simple Prism s a     -> (a -> Bool) -> s -> Bool

allOf :: Getting All s t a b -> (a -> Bool) -> s -> BoolSource

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

>>> allOf both (>=3) (4,5)
True
>>> allOf folded (>=2) [1..10]
False
allallOf folded
 allOf :: Getter s a           -> (a -> Bool) -> s -> Bool
 allOf :: Fold s a             -> (a -> Bool) -> s -> Bool
 allOf :: Simple Lens s a      -> (a -> Bool) -> s -> Bool
 allOf :: Simple Iso s a       -> (a -> Bool) -> s -> Bool
 allOf :: Simple Traversal s a -> (a -> Bool) -> s -> Bool
 allOf :: Simple Prism s a     -> (a -> Bool) -> s -> Bool

andOf :: Getting All s t Bool b -> s -> BoolSource

Returns True if every target of a Fold is True.

>>> andOf both (True,False)
False
>>> andOf both (True,True)
True
andandOf folded
 andOf :: Getter s Bool           -> s -> Bool
 andOf :: Fold s Bool             -> s -> Bool
 andOf :: Simple Lens s Bool      -> s -> Bool
 andOf :: Simple Iso s Bool       -> s -> Bool
 andOf :: Simple Traversal s Bool -> s -> Bool
 andOf :: Simple Prism s Bool     -> s -> Bool

orOf :: Getting Any s t Bool b -> s -> BoolSource

Returns True if any target of a Fold is True.

>>> orOf both (True,False)
True
>>> orOf both (False,False)
False
ororOf folded
 orOf :: Getter s Bool           -> s -> Bool
 orOf :: Fold s Bool             -> s -> Bool
 orOf :: Simple Lens s Bool      -> s -> Bool
 orOf :: Simple Iso s Bool       -> s -> Bool
 orOf :: Simple Traversal s Bool -> s -> Bool
 orOf :: Simple Prism s Bool     -> s -> Bool

productOf :: Getting (Product a) s t a b -> s -> aSource

Calculate the product of every number targeted by a Fold

>>> productOf both (4,5)
20
>>> productOf folded [1,2,3,4,5]
120
productproductOf folded
 productOf ::          Getter s a           -> s -> a
 productOf :: Num a => Fold s a             -> s -> a
 productOf ::          Simple Lens s a      -> s -> a
 productOf ::          Simple Iso s a       -> s -> a
 productOf :: Num a => Simple Traversal s a -> s -> a
 productOf :: Num a => Simple Prism s a     -> s -> a

sumOf :: Getting (Sum a) s t a b -> s -> aSource

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
sumsumOf folded
 sumOf _1 :: (a, b) -> a
 sumOf (folded . _1) :: (Foldable f, Num a) => f (a, b) -> a
 sumOf ::          Getter s a           -> s -> a
 sumOf :: Num a => Fold s a             -> s -> a
 sumOf ::          Simple Lens s a      -> s -> a
 sumOf ::          Simple Iso s a       -> s -> a
 sumOf :: Num a => Simple Traversal s a -> s -> a
 sumOf :: Num a => Simple Prism s a     -> s -> a

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

Traverse over all of the targets of a Fold (or Getter), computing an Applicative (or Functor) -based answer, but unlike traverseOf do not construct a new structure. traverseOf_ generalizes traverse_ to work over any Fold.

When passed a Getter, traverseOf_ can work over any Functor, but when passed a Fold, traverseOf_ requires an Applicative.

>>> traverseOf_ both putStrLn ("hello","world")
hello
world
traverse_traverseOf_ folded
 traverseOf_ _2 :: Functor f => (c -> f r) -> (d, 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 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     => Simple Lens s a      -> (a -> f r) -> s -> f ()
 traverseOf_ :: Functor f     => Simple Iso s a       -> (a -> f r) -> s -> f ()
 traverseOf_ :: Applicative f => Simple Traversal s a -> (a -> f r) -> s -> f ()
 traverseOf_ :: Applicative f => Simple Prism s a     -> (a -> f r) -> s -> f ()

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

Traverse over all of the targets of a Fold (or Getter), computing an Applicative (or Functor) -based answer, but unlike forOf do not construct a new structure. forOf_ generalizes for_ to work over any Fold.

When passed a Getter, forOf_ can work over any Functor, but when passed a Fold, forOf_ requires an Applicative.

for_forOf_ folded

The rather specific signature of forOf_ allows it to be used as if the signature was any of:

 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     => Simple Lens s a      -> s -> (a -> f r) -> f ()
 forOf_ :: Functor f     => Simple Iso s a       -> s -> (a -> f r) -> f ()
 forOf_ :: Applicative f => Simple Traversal s a -> s -> (a -> f r) -> f ()
 forOf_ :: Applicative f => Simple Prism s a     -> s -> (a -> f r) -> f ()

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

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

sequenceA_sequenceAOf_ folded
 sequenceAOf_ :: Functor f     => Getter s (f a)           -> s -> f ()
 sequenceAOf_ :: Applicative f => Fold s (f a)             -> s -> f ()
 sequenceAOf_ :: Functor f     => Simple Lens s (f a)      -> s -> f ()
 sequenceAOf_ :: Functor f     => Simple Iso s (f a)       -> s -> f ()
 sequenceAOf_ :: Applicative f => Simple Traversal s (f a) -> s -> f ()
 sequenceAOf_ :: Applicative f => Simple Prism s (f a)     -> s -> f ()

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

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

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 => Simple Lens s a      -> (a -> m r) -> s -> m ()
 mapMOf_ :: Monad m => Simple Iso s a       -> (a -> m r) -> s -> m ()
 mapMOf_ :: Monad m => Simple Traversal s a -> (a -> m r) -> s -> m ()
 mapMOf_ :: Monad m => Simple Prism s a     -> (a -> m r) -> s -> m ()

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

forMOf_ is mapMOf_ with two of its arguments flipped.

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 => Simple Lens s a      -> s -> (a -> m r) -> m ()
 forMOf_ :: Monad m => Simple Iso s a       -> s -> (a -> m r) -> m ()
 forMOf_ :: Monad m => Simple Traversal s a -> s -> (a -> m r) -> m ()
 forMOf_ :: Monad m => Simple Prism s a     -> s -> (a -> m r) -> m ()

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

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

sequence_sequenceOf_ folded
 sequenceOf_ :: Monad m => Getter s (m a)           -> s -> m ()
 sequenceOf_ :: Monad m => Fold s (m a)             -> s -> m ()
 sequenceOf_ :: Monad m => Simple Lens s (m a)      -> s -> m ()
 sequenceOf_ :: Monad m => Simple Iso s (m a)       -> s -> m ()
 sequenceOf_ :: Monad m => Simple Traversal s (m a) -> s -> m ()
 sequenceOf_ :: Monad m => Simple Prism s (m a)     -> s -> m ()

asumOf :: Alternative f => Getting (Endo (f a)) s t (f a) b -> s -> f aSource

The sum of a collection of actions, generalizing concatOf.

asumasumOf folded
 asumOf :: Alternative f => Getter s a           -> s -> f a
 asumOf :: Alternative f => Fold s a             -> s -> f a
 asumOf :: Alternative f => Simple Lens s a      -> s -> f a
 asumOf :: Alternative f => Simple Iso s a       -> s -> f a
 asumOf :: Alternative f => Simple Traversal s a -> s -> f a
 asumOf :: Alternative f => Simple Prism s a     -> s -> f a

msumOf :: MonadPlus m => Getting (Endo (m a)) s t (m a) b -> s -> m aSource

The sum of a collection of actions, generalizing concatOf.

msummsumOf folded
 msumOf :: MonadPlus m => Getter s a           -> s -> m a
 msumOf :: MonadPlus m => Fold s a             -> s -> m a
 msumOf :: MonadPlus m => Simple Lens s a      -> s -> m a
 msumOf :: MonadPlus m => Simple Iso s a       -> s -> m a
 msumOf :: MonadPlus m => Simple Traversal s a -> s -> m a
 msumOf :: MonadPlus m => Simple Prism s a     -> s -> m a

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

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

concatMapconcatMapOf folded
 concatMapOf :: Getter s a           -> (a -> [r]) -> s -> [r]
 concatMapOf :: Fold s a             -> (a -> [r]) -> s -> [r]
 concatMapOf :: Simple Lens s a      -> (a -> [r]) -> s -> [r]
 concatMapOf :: Simple Iso s a       -> (a -> [r]) -> s -> [r]
 concatMapOf :: Simple Traversal s a -> (a -> [r]) -> s -> [r]

concatOf :: Getting [r] s t [r] b -> s -> [r]Source

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

>>> concatOf both ("pan","ama")
"panama"
 concatconcatOf folded
 concatOfview
 concatOf :: Getter s [r]           -> s -> [r]
 concatOf :: Fold s [r]             -> s -> [r]
 concatOf :: Simple Iso s [r]       -> s -> [r]
 concatOf :: Simple Lens s [r]      -> s -> [r]
 concatOf :: Simple Traversal s [r] -> s -> [r]

elemOf :: Eq a => Getting Any s t a b -> a -> s -> BoolSource

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

>>> elemOf both "hello" ("hello","world")
True
elemelemOf folded
 elemOf :: Eq a => Getter s a           -> a -> s -> Bool
 elemOf :: Eq a => Fold s a             -> a -> s -> Bool
 elemOf :: Eq a => Simple Lens s a      -> a -> s -> Bool
 elemOf :: Eq a => Simple Iso s a       -> a -> s -> Bool
 elemOf :: Eq a => Simple Traversal s a -> a -> s -> Bool
 elemOf :: Eq a => Simple Prism s a     -> a -> s -> Bool

notElemOf :: Eq a => Getting All s t a b -> a -> s -> BoolSource

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

notElemnotElemOf folded
 notElemOf :: Eq a => Getter s a           -> a -> s -> Bool
 notElemOf :: Eq a => Fold s a             -> a -> s -> Bool
 notElemOf :: Eq a => Simple Iso s a       -> a -> s -> Bool
 notElemOf :: Eq a => Simple Lens s a      -> a -> s -> Bool
 notElemOf :: Eq a => Simple Traversal s a -> a -> s -> Bool
 notElemOf :: Eq a => Simple Prism s a     -> a -> s -> Bool

lengthOf :: Getting (Sum Int) s t a b -> s -> IntSource

Note: this can be rather inefficient for large containers.

lengthlengthOf folded
>>> lengthOf _1 ("hello",())
1
lengthOf (folded . folded) :: Foldable f => f (g a) -> Int
 lengthOf :: Getter s a           -> s -> Int
 lengthOf :: Fold s a             -> s -> Int
 lengthOf :: Simple Lens s a      -> s -> Int
 lengthOf :: Simple Iso s a       -> s -> Int
 lengthOf :: Simple Traversal s a -> s -> Int

nullOf :: Getting All s t a b -> s -> 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

nullnullOf folded

This may be rather inefficient compared to the null check of many containers.

>>> nullOf _1 (1,2)
False
nullOf (folded . _1 . folded) :: Foldable f => f (g a, b) -> Bool
 nullOf :: Getter s a           -> s -> Bool
 nullOf :: Fold s a             -> s -> Bool
 nullOf :: Simple Iso s a       -> s -> Bool
 nullOf :: Simple Lens s a      -> s -> Bool
 nullOf :: Simple Traversal s a -> s -> Bool

notNullOf :: Getting Any s t a b -> s -> BoolSource

Returns True if this Fold or Traversal has any targets in the given container.

Note: notNullOf on a valid Iso, Lens or Getter should always return True

nullnotNullOf folded

This may be rather inefficient compared to the not . null check of many containers.

>>> notNullOf _1 (1,2)
True
notNullOf (folded . _1 . folded) :: Foldable f => f (g a, b) -> Bool
 notNullOf :: Getter s a           -> s -> Bool
 notNullOf :: Fold s a             -> s -> Bool
 notNullOf :: Simple Iso s a       -> s -> Bool
 notNullOf :: Simple Lens s a      -> s -> Bool
 notNullOf :: Simple Traversal s a -> s -> Bool

firstOf :: Getting (First a) s t a b -> s -> Maybe aSource

Retrieve the First entry of a Fold or Traversal or retrieve Just the result from a Getter or Lens.

 firstOf :: Getter s a           -> s -> Maybe a
 firstOf :: Fold s a             -> s -> Maybe a
 firstOf :: Simple Lens s a      -> s -> Maybe a
 firstOf :: Simple Iso s a       -> s -> Maybe a
 firstOf :: Simple Traversal s a -> s -> Maybe a

lastOf :: Getting (Last a) s t a b -> s -> Maybe aSource

Retrieve the Last entry of a Fold or Traversal or retrieve Just the result from a Getter or Lens.

 lastOf :: Getter s a           -> s -> Maybe a
 lastOf :: Fold s a             -> s -> Maybe a
 lastOf :: Simple Lens s a      -> s -> Maybe a
 lastOf :: Simple Iso s a       -> s -> Maybe a
 lastOf :: Simple Traversal s a -> s -> Maybe a

maximumOf :: Getting (Max a) s t a b -> s -> Maybe aSource

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.

maximumfromMaybe (error "empty") . maximumOf folded
 maximumOf ::          Getter s a           -> s -> Maybe a
 maximumOf :: Ord a => Fold s a             -> s -> Maybe a
 maximumOf ::          Simple Iso s a       -> s -> Maybe a
 maximumOf ::          Simple Lens s a      -> s -> Maybe a
 maximumOf :: Ord a => Simple Traversal s a -> s -> Maybe a

minimumOf :: Getting (Min a) s t a b -> s -> Maybe aSource

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.

minimumfromMaybe (error "empty") . minimumOf folded
 minimumOf ::          Getter s a           -> s -> Maybe a
 minimumOf :: Ord a => Fold s a             -> s -> Maybe a
 minimumOf ::          Simple Iso s a       -> s -> Maybe a
 minimumOf ::          Simple Lens s a      -> s -> Maybe a
 minimumOf :: Ord a => Simple Traversal s a -> s -> Maybe a

maximumByOf :: Getting (Endo (Maybe a)) s t a b -> (a -> a -> Ordering) -> s -> Maybe aSource

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 s a           -> (a -> a -> Ordering) -> s -> Maybe a
 maximumByOf :: Fold s a             -> (a -> a -> Ordering) -> s -> Maybe a
 maximumByOf :: Simple Iso s a       -> (a -> a -> Ordering) -> s -> Maybe a
 maximumByOf :: Simple Lens s a      -> (a -> a -> Ordering) -> s -> Maybe a
 maximumByOf :: Simple Traversal s a -> (a -> a -> Ordering) -> s -> Maybe a

minimumByOf :: Getting (Endo (Maybe a)) s t a b -> (a -> a -> Ordering) -> s -> Maybe aSource

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 s a           -> (a -> a -> Ordering) -> s -> Maybe a
 minimumByOf :: Fold s a             -> (a -> a -> Ordering) -> s -> Maybe a
 minimumByOf :: Simple Iso s a       -> (a -> a -> Ordering) -> s -> Maybe a
 minimumByOf :: Simple Lens s a      -> (a -> a -> Ordering) -> s -> Maybe a
 minimumByOf :: Simple Traversal s a -> (a -> a -> Ordering) -> s -> Maybe a

findOf :: Getting (First a) s t a b -> (a -> Bool) -> s -> Maybe aSource

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 s a           -> (a -> Bool) -> s -> Maybe a
 findOf :: Fold s a             -> (a -> Bool) -> s -> Maybe a
 findOf :: Simple Iso s a       -> (a -> Bool) -> s -> Maybe a
 findOf :: Simple Lens s a      -> (a -> Bool) -> s -> Maybe a
 findOf :: Simple Traversal s a -> (a -> Bool) -> s -> Maybe a

foldrOf' :: Getting (Dual (Endo (r -> r))) s t a b -> (a -> r -> r) -> r -> s -> rSource

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' :: Simple Iso s a       -> (a -> r -> r) -> r -> s -> r
 foldrOf' :: Simple Lens s a      -> (a -> r -> r) -> r -> s -> r
 foldrOf' :: Simple Traversal s a -> (a -> r -> r) -> r -> s -> r

foldlOf' :: Getting (Endo (r -> r)) s t a b -> (r -> a -> r) -> r -> s -> rSource

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' :: Simple Iso s a       -> (r -> a -> r) -> r -> s -> r
 foldlOf' :: Simple Lens s a      -> (r -> a -> r) -> r -> s -> r
 foldlOf' :: Simple Traversal s a -> (r -> a -> r) -> r -> s -> r

foldr1Of :: Getting (Endo (Maybe a)) s t a b -> (a -> a -> a) -> s -> aSource

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
 foldr1foldr1Of folded
 foldr1Of :: Getter s a           -> (a -> a -> a) -> s -> a
 foldr1Of :: Fold s a             -> (a -> a -> a) -> s -> a
 foldr1Of :: Simple Iso s a       -> (a -> a -> a) -> s -> a
 foldr1Of :: Simple Lens s a      -> (a -> a -> a) -> s -> a
 foldr1Of :: Simple Traversal s a -> (a -> a -> a) -> s -> a

foldl1Of :: Getting (Dual (Endo (Maybe a))) s t a b -> (a -> a -> a) -> s -> aSource

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 l f ≡ foldl1Of l f . toList
 foldl1foldl1Of folded
 foldl1Of :: Getter s a           -> (a -> a -> a) -> s -> a
 foldl1Of :: Fold s a             -> (a -> a -> a) -> s -> a
 foldl1Of :: Simple Iso s a       -> (a -> a -> a) -> s -> a
 foldl1Of :: Simple Lens s a      -> (a -> a -> a) -> s -> a
 foldl1Of :: Simple Traversal s a -> (a -> a -> a) -> s -> a

foldrMOf :: Monad m => Getting (Dual (Endo (r -> m r))) s t a b -> (a -> r -> m r) -> r -> s -> m rSource

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

foldrMfoldrMOf 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 => Simple Iso s a       -> (a -> r -> m r) -> r -> s -> m r
 foldrMOf :: Monad m => Simple Lens s a      -> (a -> r -> m r) -> r -> s -> m r
 foldrMOf :: Monad m => Simple Traversal s a -> (a -> r -> m r) -> r -> s -> m r

foldlMOf :: Monad m => Getting (Endo (r -> m r)) s t a b -> (r -> a -> m r) -> r -> s -> m rSource

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

foldlMfoldlMOf 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 => Simple Iso s a       -> (r -> a -> m r) -> r -> s -> m r
 foldlMOf :: Monad m => Simple Lens s a      -> (r -> a -> m r) -> r -> s -> m r
 foldlMOf :: Monad m => Simple Traversal s a -> (r -> a -> m r) -> r -> s -> m r

Storing Folds

newtype ReifiedFold s a Source

Useful for storing folds in containers.

Constructors

ReifyFold 

Fields

reflectFold :: Fold s a
 

Deprecated

headOf :: Getting (First a) s t a b -> s -> Maybe aSource

Deprecated: headOf will be removed in 3.8. (Use preview or firstOf)

A deprecated alias for firstOf