Left associative fold on 'F' using the 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[_].

A combined traverse and filter. Filtering is handled via Option instead of Boolean such that the output type B can be different than the input type A.

Example:

scala> import cats.implicits._
scala> val m: Map[Int, String] = Map(1 -> "one", 3 -> "three")
scala> val l: List[Int] = List(1, 2, 3, 4)
scala> def asString(i: Int): Eval[Option[String]] = Now(m.get(i))
scala> val result: Eval[List[String]] = l.traverseFilter(asString)
scala> result.value
res0: List[String] = List(one, three)

Replaces the A value in F[A] with the supplied value.

Similar to mapFilter but uses a partial function instead of a function that returns an Option.

Example:

scala> import cats.implicits._
scala> val l: List[Int] = List(1, 2, 3, 4)
scala> FunctorFilter[List].collect(l){
     |   case 1 => "one"
     |   case 3 => "three"
     | }
res0: List[String] = List(one, three)

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.

If there are no elements, the result is false.

Apply a filter to a structure such that the output structure contains all A elements in the input structure that satisfy the predicate f but none that don't.

Filter values inside a G context.

This is a generalized version of Haskell's filterM. This StackOverflow question about filterM may be helpful in understanding how it behaves.

Example:

scala> import cats.implicits._
scala> val l: List[Int] = List(1, 2, 3, 4)
scala> def odd(i: Int): Eval[Boolean] = Now(i % 2 == 1)
scala> val res: Eval[List[Int]] = l.filterA(odd)
scala> res.value
res0: List[Int] = List(1, 3)

scala> List(1, 2, 3).filterA(_ => List(true, false))
res1: List[List[Int]] = List(List(1, 2, 3), List(1, 2), List(1, 3), List(1), List(2, 3), List(2), List(3), List())

Convert F[A] to a List[A], only including elements which match p.

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

Thread all the G effects through the F structure and flatten to invert the structure from F[G[F[A]]] to G[F[A]].

Example:

scala> import cats.implicits._
scala> val x: List[Option[List[Int]]] = List(Some(List(1, 2)), Some(List(3)))
scala> val y: List[Option[List[Int]]] = List(None, Some(List(3)))
scala> x.flatSequence
res0: Option[List[Int]] = Some(List(1, 2, 3))
scala> y.flatSequence
res1: Option[List[Int]] = None

A traverse followed by flattening the inner result.

Example:

scala> import cats.implicits._
scala> def parseInt(s: String): Option[Int] = Either.catchOnly[NumberFormatException](s.toInt).toOption
scala> val x = Option(List("1", "two", "3"))
scala> x.flatTraverse(_.map(parseInt))
res0: List[Option[Int]] = List(Some(1), None, Some(3))

"Flatten" out a structure by collapsing Options.

Example:

scala> import cats.implicits._
scala> val l: List[Option[Int]] = List(Some(1), None, Some(3), None)
scala> l.flattenOption
res0: List[Int] = List(1, 3)

Fold implemented using the given Monoid[A] 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)

Left associative monadic folding on F.

The default implementation of this is based on foldLeft, and thus will always fold across the entire structure. Certain structures are able to implement this in such a way that folds can be short-circuited (not traverse the entirety of the structure), depending on the G result produced at a given step.

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.

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.

If there are no elements, the result is true.

Tuple the values in fa with the result of applying a function with the value

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.

Lift a function f to operate on Functors

A combined map and filter. Filtering is handled via Option instead of Boolean such that the output type B can be different than the input type A.

Example:

scala> import cats.implicits._
scala> val m: Map[Int, String] = Map(1 -> "one", 3 -> "three")
scala> val l: List[Int] = List(1, 2, 3, 4)
scala> def asString(i: Int): Option[String] = m.get(i)
scala> l.mapFilter(i => m.get(i))
res0: List[String] = List(one, three)

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

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

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 right-associative manner.

Thread all the G effects through the F structure to invert the structure from F[G[A]] to G[F[A]].

Example:

scala> import cats.implicits._
scala> val x: List[Option[Int]] = List(Some(1), Some(2))
scala> val y: List[Option[Int]] = List(None, Some(2))
scala> x.sequence
res0: Option[List[Int]] = Some(List(1, 2))
scala> y.sequence
res1: Option[List[Int]] = None

Behaves just like sequence, but uses Unapply to find the Applicative instance for G.

Example:

scala> import cats.data.{Validated, ValidatedNel}
scala> import cats.implicits._
scala> val x: List[ValidatedNel[String, Int]] = List(Validated.valid(1), Validated.invalid("a"), Validated.invalid("b")).map(_.toValidatedNel)
scala> x.sequenceU
res0: cats.data.ValidatedNel[String,List[Int]] = Invalid(NonEmptyList(a, b))
scala> x.sequence[ValidatedNel[String, ?], Int]
res1: cats.data.ValidatedNel[String,List[Int]] = Invalid(NonEmptyList(a, b))

Behaves like sequence_, but uses Unapply to find the Applicative instance for G - used when G is a type constructor with two or more parameters such as scala.util.Either

scala> import cats.implicits._
scala> val F = Foldable[List]
scala> F.sequenceU_(List(Either.right[String, Int](333), Right(444)))
res0: Either[String, Unit] = Right(())
scala> F.sequenceU_(List(Either.right[String, Int](333), Left("boo")))
res1: Either[String, Unit] = Left(boo)

Note that using sequence_ instead of sequenceU_ would not compile without explicitly passing in the type parameters - the type checker has trouble inferring the appropriate instance.

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

This is overriden 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].

Given a function which returns a G effect, thread this effect through the running of this function on all the values in F, returning an F[B] in a G context.

Example:

scala> import cats.implicits._
scala> def parseInt(s: String): Option[Int] = Either.catchOnly[NumberFormatException](s.toInt).toOption
scala> List("1", "2", "3").traverse(parseInt)
res0: Option[List[Int]] = Some(List(1, 2, 3))
scala> List("1", "two", "3").traverse(parseInt)
res1: Option[List[Int]] = None

Behaves just like traverse, but uses Unapply to find the Applicative instance for G.

Example:

scala> import cats.implicits._
scala> def parseInt(s: String): Either[String, Int] = Either.catchOnly[NumberFormatException](s.toInt).leftMap(_ => "no number")
scala> val ns = List("1", "2", "3")
scala> ns.traverseU(parseInt)
res0: Either[String, List[Int]] = Right(List(1, 2, 3))
scala> ns.traverse[Either[String, ?], Int](parseInt)
res1: Either[String, List[Int]] = Right(List(1, 2, 3))

Behaves like traverse_, but uses Unapply to find the Applicative instance for G - used when G is a type constructor with two or more parameters such as scala.util.Either

scala> import cats.implicits._
scala> def parseInt(s: String): Either[String, Int] =
     |   try { Right(s.toInt) }
     |   catch { case _: NumberFormatException => Left("boo") }
scala> val F = Foldable[List]
scala> F.traverseU_(List("333", "444"))(parseInt)
res0: Either[String, Unit] = Right(())
scala> F.traverseU_(List("333", "zzz"))(parseInt)
res1: Either[String, Unit] = Left(boo)

Note that using traverse_ instead of traverseU_ would not compile without explicitly passing in the type parameters - the type checker has trouble inferring the appropriate instance.

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.

Tuples the A value in F[A] with the supplied B value, with the B value on the left.

Tuples the A value in F[A] with the supplied B value, with the B value on the right.

Empty the fa of the values, preserving the structure

Lifts natural subtyping covariance of covariant Functors.

NOTE: In certain (perhaps contrived) situations that rely on universal equality this can result in a ClassCastException, because it is implemented as a type cast. It could be implemented as map(identity), but according to the functor laws, that should be equal to fa, and a type cast is often much more performant. See this example of widen creating a ClassCastException.