Left associative fold on 'F' using the function 'f'.
Left associative fold on 'F' using the function 'f'.
Example:
scala> import cats.Foldable, cats.implicits._ scala> val fa = Option(1) Folding by addition to zero: scala> Foldable[Option].foldLeft(fa, Option(0))((a, n) => a.map(_ + n)) res0: Option[Int] = Some(1)
With syntax extensions, foldLeft
can be used like:
Folding `Option` with addition from zero: scala> fa.foldLeft(Option(0))((a, n) => a.map(_ + n)) res1: Option[Int] = Some(1) There's also an alias `foldl` which is equivalent: scala> fa.foldl(Option(0))((a, n) => a.map(_ + n)) res2: Option[Int] = Some(1)
Right associative lazy fold on F
using the folding function 'f'.
Right associative lazy fold on F
using the folding function 'f'.
This method evaluates lb
lazily (in some cases it will not be
needed), and returns a lazy value. We are using (A, Eval[B]) =>
Eval[B]
to support laziness in a stack-safe way. Chained
computation should be performed via .map and .flatMap.
For more detailed information about how this method works see the
documentation for Eval[_]
.
Example:
scala> import cats.Foldable, cats.Eval, cats.implicits._ scala> val fa = Option(1) Folding by addition to zero: scala> val folded1 = Foldable[Option].foldRight(fa, Eval.now(0))((n, a) => a.map(_ + n)) Since `foldRight` yields a lazy computation, we need to force it to inspect the result: scala> folded1.value res0: Int = 1 With syntax extensions, we can write the same thing like this: scala> val folded2 = fa.foldRight(Eval.now(0))((n, a) => a.map(_ + n)) scala> folded2.value res1: Int = 1 Unfortunately, since `foldRight` is defined on many collections - this extension clashes with the operation defined in `Foldable`. To get past this and make sure you're getting the lazy `foldRight` defined in `Foldable`, there's an alias `foldr`: scala> val folded3 = fa.foldr(Eval.now(0))((n, a) => a.map(_ + n)) scala> folded3.value res1: Int = 1
Like collectFirst
from scala.collection.Traversable
but takes A => Option[B]
instead of PartialFunction
s.
Like collectFirst
from scala.collection.Traversable
but takes A => Option[B]
instead of PartialFunction
s.
scala> import cats.implicits._ scala> val keys = List(1, 2, 4, 5) scala> val map = Map(4 -> "Four", 5 -> "Five") scala> keys.collectFirstSome(map.get) res0: Option[String] = Some(Four) scala> val map2 = Map(6 -> "Six", 7 -> "Seven") scala> keys.collectFirstSome(map2.get) res1: Option[String] = None
Alias for fold.
Convert F[A] to a List[A], dropping all initial elements which
match p
.
Check whether at least one element satisfies the predicate.
Check whether at least one element satisfies the predicate.
If there are no elements, the result is false
.
Check whether at least one element satisfies the effectful predicate.
Check whether at least one element satisfies the effectful predicate.
If there are no elements, the result is false
. existsM
short-circuits,
i.e. once a true
result is encountered, no further effects are produced.
For example:
scala> import cats.implicits._ scala> val F = Foldable[List] scala> F.existsM(List(1,2,3,4))(n => Option(n <= 4)) res0: Option[Boolean] = Some(true) scala> F.existsM(List(1,2,3,4))(n => Option(n > 4)) res1: Option[Boolean] = Some(false) scala> F.existsM(List(1,2,3,4))(n => if (n <= 2) Option(true) else Option(false)) res2: Option[Boolean] = Some(true) scala> F.existsM(List(1,2,3,4))(n => if (n <= 2) Option(true) else None) res3: Option[Boolean] = Some(true) scala> F.existsM(List(1,2,3,4))(n => if (n <= 2) None else Option(true)) res4: Option[Boolean] = None
Convert F[A] to a List[A], only including elements which match p
.
Find the first element matching the predicate, if one exists.
Fold implemented using the given Monoid[A] instance.
Fold implemented using the given MonoidK[G]
instance.
Fold implemented using the given MonoidK[G]
instance.
This method is identical to fold, except that we use the universal monoid (MonoidK[G]
)
to get a Monoid[G[A]]
instance.
For example:
scala> import cats.implicits._ scala> val F = Foldable[List] scala> F.foldK(List(1 :: 2 :: Nil, 3 :: 4 :: 5 :: Nil)) res0: List[Int] = List(1, 2, 3, 4, 5)
Alias for foldM.
Perform a stack-safe monadic left fold from the source context F
into the target monad G
.
Perform a stack-safe monadic left fold from the source context F
into the target monad G
.
This method can express short-circuiting semantics. Even when
fa
is an infinite structure, this method can potentially
terminate if the foldRight
implementation for F
and the
tailRecM
implementation for G
are sufficiently lazy.
Instances for concrete structures (e.g. List
) will often
have a more efficient implementation than the default one
in terms of foldRight
.
Fold implemented by mapping A
values into B
and then
combining them using the given Monoid[B]
instance.
Monadic folding on F
by mapping A
values to G[B]
, combining the B
values using the given Monoid[B]
instance.
Monadic folding on F
by mapping A
values to G[B]
, combining the B
values using the given Monoid[B]
instance.
Similar to foldM, but using a Monoid[B]
.
scala> import cats.Foldable scala> import cats.implicits._ scala> val evenNumbers = List(2,4,6,8,10) scala> val evenOpt: Int => Option[Int] = | i => if (i % 2 == 0) Some(i) else None scala> Foldable[List].foldMapM(evenNumbers)(evenOpt) res0: Option[Int] = Some(30) scala> Foldable[List].foldMapM(evenNumbers :+ 11)(evenOpt) res1: Option[Int] = None
Check whether all elements satisfy the predicate.
Check whether all elements satisfy the predicate.
If there are no elements, the result is true
.
Check whether all elements satisfy the effectful predicate.
Check whether all elements satisfy the effectful predicate.
If there are no elements, the result is true
. forallM
short-circuits,
i.e. once a false
result is encountered, no further effects are produced.
For example:
scala> import cats.implicits._ scala> val F = Foldable[List] scala> F.forallM(List(1,2,3,4))(n => Option(n <= 4)) res0: Option[Boolean] = Some(true) scala> F.forallM(List(1,2,3,4))(n => Option(n <= 1)) res1: Option[Boolean] = Some(false) scala> F.forallM(List(1,2,3,4))(n => if (n <= 2) Option(true) else Option(false)) res2: Option[Boolean] = Some(false) scala> F.forallM(List(1,2,3,4))(n => if (n <= 2) Option(false) else None) res3: Option[Boolean] = Some(false) scala> F.forallM(List(1,2,3,4))(n => if (n <= 2) None else Option(false)) res4: Option[Boolean] = None
Get the element at the index of the Foldable
.
Intercalate/insert an element between the existing elements while folding.
Intercalate/insert an element between the existing elements while folding.
scala> import cats.implicits._ scala> Foldable[List].intercalate(List("a","b","c"), "-") res0: String = a-b-c scala> Foldable[List].intercalate(List("a"), "-") res1: String = a scala> Foldable[List].intercalate(List.empty[String], "-") res2: String = "" scala> Foldable[Vector].intercalate(Vector(1,2,3), 1) res3: Int = 8
Returns true if there are no elements.
Returns true if there are no elements. Otherwise false.
Find the maximum A
item in this structure according to the Order[A]
.
Find the maximum A
item in this structure according to the Order[A]
.
None
if the structure is empty, otherwise the maximum element
wrapped in a Some
.
minimumOption for minimum instead of maximum.
Reducible#maximum for a version that doesn't need to return an
Option
for structures that are guaranteed to be non-empty.
Find the minimum A
item in this structure according to the Order[A]
.
Find the minimum A
item in this structure according to the Order[A]
.
None
if the structure is empty, otherwise the minimum element
wrapped in a Some
.
maximumOption for maximum instead of minimum.
Reducible#minimum for a version that doesn't need to return an
Option
for structures that are guaranteed to be non-empty.
Separate this Foldable into a Tuple by a separating function A => Either[B, C]
Equivalent to Functor#map
and then Alternative#separate
.
Separate this Foldable into a Tuple by a separating function A => Either[B, C]
Equivalent to Functor#map
and then Alternative#separate
.
scala> import cats.implicits._ scala> val list = List(1,2,3,4) scala> Foldable[List].partitionEither(list)(a => if (a % 2 == 0) Left(a.toString) else Right(a)) res0: (List[String], List[Int]) = (List(2, 4),List(1, 3)) scala> Foldable[List].partitionEither(list)(a => Right(a * 4)) res1: (List[Nothing], List[Int]) = (List(),List(4, 8, 12, 16))
Reduce the elements of this structure down to a single value by applying the provided aggregation function in a left-associative manner.
Reduce the elements of this structure down to a single value by applying the provided aggregation function in a left-associative manner.
None
if the structure is empty, otherwise the result of combining
the cumulative left-associative result of the f
operation over all of the
elements.
Reducible#reduceLeft for a version that doesn't need to return an
Option
for structures that are guaranteed to be non-empty.
Example:
scala> import cats.implicits._ scala> val l = List(6, 3, 2) This is equivalent to (6 - 3) - 2 scala> Foldable[List].reduceLeftOption(l)(_ - _) res0: Option[Int] = Some(1) scala> Foldable[List].reduceLeftOption(List.empty[Int])(_ - _) res1: Option[Int] = None
reduceRightOption for a right-associative alternative.
Reduce the elements of this structure down to a single value by applying the provided aggregation function in a right-associative manner.
Reduce the elements of this structure down to a single value by applying the provided aggregation function in a right-associative manner.
None
if the structure is empty, otherwise the result of combining
the cumulative right-associative result of the f
operation over the
A
elements.
Reducible#reduceRight for a version that doesn't need to return an
Option
for structures that are guaranteed to be non-empty.
Example:
scala> import cats.implicits._ scala> val l = List(6, 3, 2) This is eqivalent to 6 - (3 - 2) scala> Foldable[List].reduceRightOption(l)((current, rest) => rest.map(current - _)).value res0: Option[Int] = Some(5) scala> Foldable[List].reduceRightOption(List.empty[Int])((current, rest) => rest.map(current - _)).value res1: Option[Int] = None
reduceLeftOption for a left-associative alternative
Sequence F[G[A]]
using Applicative[G]
.
Sequence F[G[A]]
using Applicative[G]
.
This is similar to traverse_
except it operates on F[G[A]]
values, so no additional functions are needed.
For example:
scala> import cats.implicits._ scala> val F = Foldable[List] scala> F.sequence_(List(Option(1), Option(2), Option(3))) res0: Option[Unit] = Some(()) scala> F.sequence_(List(Option(1), None, Option(3))) res1: Option[Unit] = None
The size of this UnorderedFoldable.
The size of this UnorderedFoldable.
This is overridden in structures that have more efficient size implementations (e.g. Vector, Set, Map).
Note: will not terminate for infinite-sized collections.
Convert F[A] to a List[A], retaining only initial elements which
match p
.
Convert F[A] to a List[A].
Traverse F[A]
using Applicative[G]
.
Traverse F[A]
using Applicative[G]
.
A
values will be mapped into G[B]
and combined using
Applicative#map2
.
For example:
scala> import cats.implicits._ scala> def parseInt(s: String): Option[Int] = Either.catchOnly[NumberFormatException](s.toInt).toOption scala> val F = Foldable[List] scala> F.traverse_(List("333", "444"))(parseInt) res0: Option[Unit] = Some(()) scala> F.traverse_(List("333", "zzz"))(parseInt) res1: Option[Unit] = None
This method is primarily useful when G[_]
represents an action
or effect, and the specific A
aspect of G[A]
is not otherwise
needed.
Data structures that can be folded to a summary value.
In the case of a collection (such as
List
orVector
), these methods will fold together (combine) the values contained in the collection to produce a single result. Most collection types havefoldLeft
methods, which will usually be used by the associatedFoldable[_]
instance.Instances of Foldable should be ordered collections to allow for consistent folding. Use the
UnorderedFoldable
type class if you want to fold over unordered collections.Foldable[F] is implemented in terms of two basic methods:
foldLeft(fa, b)(f)
eagerly foldsfa
from left-to-right.foldRight(fa, b)(f)
lazily foldsfa
from right-to-left.Beyond these it provides many other useful methods related to folding over F[A] values.
See: A tutorial on the universality and expressiveness of fold