Foldable
Related Docs:
object Foldable
| package cats
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 PartialFunctions.
Like collectFirst from scala.collection.Traversable but takes A => Option[B]
instead of PartialFunctions.
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
ListorVector), these methods will fold together (combine) the values contained in the collection to produce a single result. Most collection types havefoldLeftmethods, which will usually be used by the associatedFoldable[_]instance.Instances of Foldable should be ordered collections to allow for consistent folding. Use the
UnorderedFoldabletype class if you want to fold over unordered collections.Foldable[F] is implemented in terms of two basic methods:
foldLeft(fa, b)(f)eagerly foldsfafrom left-to-right.foldRight(fa, b)(f)lazily foldsfafrom 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