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
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.
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.
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. This is because ^? works by using the
First monoid, which can occasionally cause space leaks.
Example1 expression
>>> Left 4 ^?_LeftJust 4
Example1 expression
>>> Right 4 ^?_LeftNothing
Example1 expression
>>> "world" ^? ix 3Just 'l'
Example1 expression
>>> "world" ^? ix 20Nothing
This operator works as an infix version of preview.
Retrieve the first value targeted by a Fold or Traversal (or Just the result
from a Getter or Lens). See also firstOf and ^?, which are similar with
some subtle differences (explained below).
Unlike ^?, this function uses a
MonadReader to read the value to be focused in on.
This allows one to pass the value as the last argument by using the
MonadReader instance for (->) s
However, it may also be used as part of some deeply nested transformer stack.
preview uses a monoidal value to obtain the result.
This means that it generally has good performance, but can occasionally cause space leaks
or even stack overflows on some data types.
There is another function, firstOf, which avoids these issues at the cost of
a slight constant performance cost and a little less flexibility.
It may be helpful to think of preview as having one of the following
more specialized types:
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.
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.
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).
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.
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
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
Calls pure on the targets of a Traversal, Fold, or Prism, and
combines them with <|> (or empty if none). Intuitively, it collects
targets into an Alternative until the container fills up or it runs out of
targets, whichever comes first.
>>> altOf both ("hello", "world") :: [String]["hello","world"]>>> altOf both ("hello", "world") :: Maybe StringJust "hello"
altOf :: Applicative f => Lens' s a -> s -> f a
altOf :: Applicative f => Getter s a -> s -> f a
altOf :: Applicative f => Iso' s a -> s -> f a
altOf :: Alternative f => Traversal' s a -> s -> f a
altOf :: Alternative f => Fold s a -> s -> f a
altOf :: Alternative f => Prism' s a -> s -> f a
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.
The answer is computed in a manner that leaks space less than preview or ^?'
and gives you back access to the outermost Just constructor more quickly, but does so
in a way that builds an intermediate structure, and thus may have worse
constant factors. This also means that it can not be used in any MonadReader,
but must instead have s passed as its last argument, unlike preview.
The answer is computed in a manner that leaks space less than alaLast.foldMapOf
and gives you back access to the outermost Just constructor more quickly, but may have worse
constant factors.
In the interest of efficiency, This operation has semantics more strict than strictly necessary.
rmapgetMax (foldMapOf l Max) has lazier semantics but could leak memory.
In the interest of efficiency, This operation has semantics more strict than strictly necessary.
rmapgetMin (foldMapOf l Min) has lazier semantics but could leak memory.
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.
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.
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.
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.
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.
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.
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.
Run monadic actions for each target of an IndexedFold or IndexedTraversal with access to the index,
discarding the results (with the arguments flipped).
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.
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.
Fold a value using its Foldable instance using
explicitly provided Monoid operations. This is like fold
where the Monoid instance can be manually specified.
Fold a value using its Foldable instance using
explicitly provided Monoid operations. This is like foldMap
where the Monoid instance can be manually specified.
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
Example1 expression
>>> foldMapByOf both (+) 0 length ("hello","world")10