planet-mitchell-0.1.0: Planet Mitchell

Optic.Fold

Contents

Synopsis

# Fold

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.

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


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)


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.

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)


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


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]


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 to the first target also does not pass the predicate! Otherwise subsequent traversals will visit fewer elements and Traversal fusion is not sound. So for any traversal t and predicate p, droppingWhile p t may not be lawful, but (dropping 1 . droppingWhile p) t is. For example: >>> let l :: Traversal' [Int] Int; l = droppingWhile (<= 1) traverse >>> let l' :: Traversal' [Int] Int; l' = dropping 1 l  l is not a lawful setter because over l f . over l g ≢ over l (f . g): >>> [1,2,3] & l .~ 0 & l .~ 4 [1,0,0] >>> [1,2,3] & l .~ 4 [1,4,4]  l' on the other hand behaves lawfully: >>> [1,2,3] & l' .~ 0 & l' .~ 4 [1,2,4] >>> [1,2,3] & l' .~ 4 [1,2,4]  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 :: Semigroup r => Fold1 s a -> (a -> r) -> s -> r foldMapOf :: Lens' s a -> (a -> r) -> s -> r foldMapOf :: Iso' s a -> (a -> r) -> s -> r foldMapOf :: Monoid r => Traversal' s a -> (a -> r) -> s -> r foldMapOf :: Semigroup r => Traversal1' s a -> (a -> r) -> s -> r foldMapOf :: Monoid r => Prism' s a -> (a -> r) -> s -> r  foldMapOf :: Getting r s a -> (a -> r) -> s -> r  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  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  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"  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  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  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  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  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  toListOf :: Getting (Endo [a]) s a -> s -> [a] # Extract a list of the targets of a Fold. See also (^..). toList ≡ toListOf folded (^..) ≡ flip toListOf  toNonEmptyOf :: Getting (NonEmptyDList a) s a -> s -> NonEmpty a # Extract a NonEmpty of the targets of Fold1. >>> toNonEmptyOf both1 ("hello", "world") "hello" :| ["world"]  toNonEmptyOf :: Getter s a -> s -> NonEmpty a toNonEmptyOf :: Fold1 s a -> s -> NonEmpty a toNonEmptyOf :: Lens' s a -> s -> NonEmpty a toNonEmptyOf :: Iso' s a -> s -> NonEmpty a toNonEmptyOf :: Traversal1' s a -> s -> NonEmpty a toNonEmptyOf :: Prism' s a -> s -> NonEmpty a  anyOf :: Getting Any s a -> (a -> Bool) -> s -> Bool # 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 ()  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]  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. Note: this could been named headOf. >>> 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


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