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'.

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.

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

Monadic version of collectFirstSome.

If there are no elements, the result is None. collectFirstSomeM short-circuits, i.e. once a Some element is found, no further effects are produced.

For example:

scala> import cats.implicits._
scala> def parseInt(s: String): Either[String, Int] = Either.catchOnly[NumberFormatException](s.toInt).leftMap(_.getMessage)
scala> val keys1 = List("1", "2", "4", "5")
scala> val map1 = Map(4 -> "Four", 5 -> "Five")
scala> Foldable[List].collectFirstSomeM(keys1)(parseInt(_) map map1.get)
res0: scala.util.Either[String,Option[String]] = Right(Some(Four))

scala> val map2 = Map(6 -> "Six", 7 -> "Seven")
scala> Foldable[List].collectFirstSomeM(keys1)(parseInt(_) map map2.get)
res1: scala.util.Either[String,Option[String]] = Right(None)

scala> val keys2 = List("1", "x", "4", "5")
scala> Foldable[List].collectFirstSomeM(keys2)(parseInt(_) map map1.get)
res2: scala.util.Either[String,Option[String]] = Left(For input string: "x")

scala> val keys3 = List("1", "2", "4", "x")
scala> Foldable[List].collectFirstSomeM(keys3)(parseInt(_) map map1.get)
res3: scala.util.Either[String,Option[String]] = Right(Some(Four))

Tear down a subset of this structure using a PartialFunction.

scala> import cats.implicits._
scala> val xs = List(1, 2, 3, 4)
scala> Foldable[List].collectFold(xs) { case n if n % 2 == 0 => n }
res0: Int = 6

Tear down a subset of this structure using a A => Option[M].

scala> import cats.implicits._
scala> val xs = List(1, 2, 3, 4)
scala> def f(n: Int): Option[Int] = if (n % 2 == 0) Some(n) else None
scala> Foldable[List].collectFoldSome(xs)(f)
res0: Int = 6

Alias for fold.

Count the number of elements in the structure that satisfy the given predicate.

For example:

scala> import cats.implicits._
scala> val map1 = Map[Int, String]()
scala> val p1: String => Boolean = _.length > 0
scala> UnorderedFoldable[Map[Int, *]].count(map1)(p1)
res0: Long = 0

scala> val map2 = Map(1 -> "hello", 2 -> "world", 3 -> "!")
scala> val p2: String => Boolean = _.length > 1
scala> UnorderedFoldable[Map[Int, *]].count(map2)(p2)
res1: Long = 2

Convert F[A] to a List[A], dropping all initial elements which match p.

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.

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.

Find the first element matching the effectful predicate, if one exists.

If there are no elements, the result is None. findM short-circuits, i.e. once an element is found, no further effects are produced.

For example:

scala> import cats.implicits._
scala> val list = List(1,2,3,4)
scala> Foldable[List].findM(list)(n => (n >= 2).asRight[String])
res0: Either[String,Option[Int]] = Right(Some(2))

scala> Foldable[List].findM(list)(n => (n > 4).asRight[String])
res1: Either[String,Option[Int]] = Right(None)

scala> Foldable[List].findM(list)(n => Either.cond(n < 3, n >= 2, "error"))
res2: Either[String,Option[Int]] = Right(Some(2))

scala> Foldable[List].findM(list)(n => Either.cond(n < 3, false, "error"))
res3: Either[String,Option[Int]] = Left(error)

Fold implemented using the given Monoid[A] instance.

Fold implemented using the given Applicative[G] and Monoid[A] instance.

This method is similar to fold, but may short-circuit.

For example:

scala> import cats.implicits._
scala> val F = Foldable[List]
scala> F.foldA(List(Either.right[String, Int](1), Either.right[String, Int](2)))
res0: Either[String, Int] = Right(3)

See this issue for an explanation of @noop usage.

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.

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.

Fold in an Applicative context by mapping the A values to G[B]. combining the B values using the given Monoid[B] instance.

Similar to foldMapM, but will typically be less efficient.

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].foldMapA(evenNumbers)(evenOpt)
res0: Option[Int] = Some(30)
scala> Foldable[List].foldMapA(evenNumbers :+ 11)(evenOpt)
res1: Option[Int] = None

Fold implemented by mapping A values into B in a context G and then combining them using the MonoidK[G] instance.

scala> import cats._, cats.implicits._
scala> val f: Int => Endo[String] = i => (s => s + i)
scala> val x: Endo[String] = Foldable[List].foldMapK(List(1, 2, 3))(f)
scala> val a = x("foo")
a: String = "foo321"

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]. Will typically be more efficient than foldMapA.

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.

If there are no elements, the result is true.

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.

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. Otherwise false.

Find the maximum A item in this structure according to an Order.by(f).

Find all the maximum A items in this structure according to an Order.by(f). For all elements in the result Order.eqv(x, y) is true. Preserves order.

Find all the maximum A items in this structure according to an Order.by(f). For all elements in the result Order.eqv(x, y) is true. Preserves order.

Find the maximum A item in this structure according to an Order.by(f).

Find all the maximum A items in this structure. For all elements in the result Order.eqv(x, y) is true. Preserves order.

Find all the maximum A items in this structure. For all elements in the result Order.eqv(x, y) is true. Preserves order.

Find the maximum A item in this structure according to the Order[A].

Find the minimum A item in this structure according to an Order.by(f).

Find all the minimum A items in this structure according to an Order.by(f). For all elements in the result Order.eqv(x, y) is true. Preserves order.

Find all the minimum A items in this structure according to an Order.by(f). For all elements in the result Order.eqv(x, y) is true. Preserves order.

Find the minimum A item in this structure according to an Order.by(f).

Find all the minimum A items in this structure. For all elements in the result Order.eqv(x, y) is true. Preserves order.

Find all the minimum A items in this structure. For all elements in the result Order.eqv(x, y) is true. Preserves order.

Find the minimum A item in this structure according to the Order[A].

Intercalate/insert an element between the existing elements while reducing.

scala> import cats.implicits._
scala> import cats.data.NonEmptyList
scala> val nel = NonEmptyList.of("a", "b", "c")
scala> Reducible[NonEmptyList].nonEmptyIntercalate(nel, "-")
res0: String = a-b-c
scala> Reducible[NonEmptyList].nonEmptyIntercalate(NonEmptyList.of("a"), "-")
res1: String = a

Partition this Reducible by a separating function A => Either[B, C]

scala> import cats.data.NonEmptyList
scala> val nel = NonEmptyList.of(1,2,3,4)
scala> Reducible[NonEmptyList].nonEmptyPartition(nel)(a => if (a % 2 == 0) Left(a.toString) else Right(a))
res0: cats.data.Ior[cats.data.NonEmptyList[String],cats.data.NonEmptyList[Int]] = Both(NonEmptyList(2, 4),NonEmptyList(1, 3))
scala> Reducible[NonEmptyList].nonEmptyPartition(nel)(a => Right(a * 4))
res1: cats.data.Ior[cats.data.NonEmptyList[Nothing],cats.data.NonEmptyList[Int]] = Right(NonEmptyList(4, 8, 12, 16))

Sequence F[G[A]] using Apply[G].

This method is similar to Foldable.sequence_ but requires only an Apply instance for G instead of Applicative. See the nonEmptyTraverse_ documentation for a description of the differences.

Traverse F[A] using Apply[G].

A values will be mapped into G[B] and combined using Apply#map2.

This method is similar to Foldable.traverse_. There are two main differences:

1. We only need an Apply instance for G here, since we don't need to call Applicative.pure for a starting value. 2. This performs a strict left-associative traversal and thus must always traverse the entire data structure. Prefer Foldable.traverse_ if you have an Applicative instance available for G and want to take advantage of short-circuiting the traversal.

Separate this Foldable into a Tuple by a separating function A => H[B, C] for some Bifoldable[H] Equivalent to Functor#map and then Alternative#separate.

scala> import cats.implicits._, cats.Foldable, cats.data.Const
scala> val list = List(1,2,3,4)
scala> Foldable[List].partitionBifold(list)(a => ("value " + a.toString(), if (a % 2 == 0) -a else a))
res0: (List[String], List[Int]) = (List(value 1, value 2, value 3, value 4),List(1, -2, 3, -4))
scala> Foldable[List].partitionBifold(list)(a => Const[Int, Nothing with Any](a))
res1: (List[Int], List[Nothing with Any]) = (List(1, 2, 3, 4),List())

Separate this Foldable into a Tuple by an effectful separating function A => G[H[B, C]] for some Bifoldable[H] Equivalent to Traverse#traverse over Alternative#separate

scala> import cats.implicits._, cats.Foldable, cats.data.Const
scala> val list = List(1,2,3,4)
`Const`'s second parameter is never instantiated, so we can use an impossible type:
scala> Foldable[List].partitionBifoldM(list)(a => Option(Const[Int, Nothing with Any](a)))
res0: Option[(List[Int], List[Nothing with Any])] = Some((List(1, 2, 3, 4),List()))

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))

Separate this Foldable into a Tuple by an effectful separating function A => G[Either[B, C]] Equivalent to Traverse#traverse over Alternative#separate

scala> import cats.implicits._, cats.Foldable, cats.Eval
scala> val list = List(1,2,3,4)
scala> val partitioned1 = Foldable[List].partitionEitherM(list)(a => if (a % 2 == 0) Eval.now(Either.left[String, Int](a.toString)) else Eval.now(Either.right[String, Int](a)))
Since `Eval.now` yields a lazy computation, we need to force it to inspect the result:
scala> partitioned1.value
res0: (List[String], List[Int]) = (List(2, 4),List(1, 3))
scala> val partitioned2 = Foldable[List].partitionEitherM(list)(a => Eval.later(Either.right(a * 4)))
scala> partitioned2.value
res1: (List[Nothing], List[Int]) = (List(),List(4, 8, 12, 16))

Reduce a F[G[A]] value using Applicative[G] and Semigroup[A], a universal semigroup for G[_].

This method is similar to reduce, but may short-circuit.

See this issue for an explanation of @noop usage.

Reduce a F[G[A]] value using SemigroupK[G], a universal semigroup for G[_].

This method is a generalization of reduce.

Left-associative reduction on F using the function f.

Implementations should override this method when possible.

Reduce the elements of this structure down to a single value by applying the provided aggregation function in a left-associative manner.

Overridden from Foldable for efficiency.

Reduce in an Apply context by mapping the A values to G[B]. combining the B values using the given Semigroup[B] instance.

Similar to reduceMapM, but may be less efficient.

scala> import cats.Reducible
scala> import cats.data.NonEmptyList
scala> import cats.implicits._
scala> val evenOpt: Int => Option[Int] =
     |   i => if (i % 2 == 0) Some(i) else None
scala> val allEven = NonEmptyList.of(2,4,6,8,10)
allEven: cats.data.NonEmptyList[Int] = NonEmptyList(2, 4, 6, 8, 10)
scala> val notAllEven = allEven ++ List(11)
notAllEven: cats.data.NonEmptyList[Int] = NonEmptyList(2, 4, 6, 8, 10, 11)
scala> Reducible[NonEmptyList].reduceMapA(allEven)(evenOpt)
res0: Option[Int] = Some(30)
scala> Reducible[NonEmptyList].reduceMapA(notAllEven)(evenOpt)
res1: Option[Int] = None

Apply f to each element of fa and combine them using the given SemigroupK[G].

scala> import cats._, cats.data._, cats.implicits._
scala> val f: Int => Endo[String] = i => (s => s + i)
scala> val x: Endo[String] = Reducible[NonEmptyList].reduceMapK(NonEmptyList.of(1, 2, 3))(f)
scala> val a = x("foo")
a: String = "foo321"

Reduce in an FlatMap context by mapping the A values to G[B]. combining the B values using the given Semigroup[B] instance.

Similar to reduceLeftM, but using a Semigroup[B]. May be more efficient than reduceMapA.

scala> import cats.Reducible
scala> import cats.data.NonEmptyList
scala> import cats.implicits._
scala> val evenOpt: Int => Option[Int] =
     |   i => if (i % 2 == 0) Some(i) else None
scala> val allEven = NonEmptyList.of(2,4,6,8,10)
allEven: cats.data.NonEmptyList[Int] = NonEmptyList(2, 4, 6, 8, 10)
scala> val notAllEven = allEven ++ List(11)
notAllEven: cats.data.NonEmptyList[Int] = NonEmptyList(2, 4, 6, 8, 10, 11)
scala> Reducible[NonEmptyList].reduceMapM(allEven)(evenOpt)
res0: Option[Int] = Some(30)
scala> Reducible[NonEmptyList].reduceMapM(notAllEven)(evenOpt)
res1: Option[Int] = None

Reduce the elements of this structure down to a single value by applying the provided aggregation function in a right-associative manner.

Overridden from Foldable for efficiency.

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.

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 an Iterable[A].

This method may be overridden for the sake of performance, but implementers should take care not to force a full materialization of the collection.

Convert F[A] to a List[A].

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.