InputCats

Alias for productR.

Alias for productL.

Alias for ap.

Align two structures with the same element, combining results according to their semigroup instances.

Example:

scala> import cats.implicits._
scala> Align[List].alignCombine(List(1, 2), List(10, 11, 12))
res0: List[Int] = List(11, 13, 12)

Align two structures with the same element, combining results according to the given function.

Example:

scala> import cats.implicits._
scala> Align[List].alignMergeWith(List(1, 2), List(10, 11, 12))(_ + _)
res0: List[Int] = List(11, 13, 12)

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

Example:

scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List].as(List(1,2,3), "hello")
res0: List[String] = List(hello, hello, hello)

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.

Compose Invariant F[_] and G[_] then produce Invariant[F[G[_]]] using their imap.

Example:

scala> import cats.implicits._
scala> import scala.concurrent.duration._

scala> val durSemigroupList: Semigroup[List[FiniteDuration]] =
    | Invariant[Semigroup].compose[List].imap(Semigroup[List[Long]])(Duration.fromNanos)(_.toNanos)
scala> durSemigroupList.combine(List(2.seconds, 3.seconds), List(4.seconds))
res1: List[FiniteDuration] = List(2 seconds, 3 seconds, 4 seconds)

Compose an Applicative[F] and an Applicative[G] into an Applicative[λ[α => F[G[α]]]].

Example:

scala> import cats.implicits._

scala> val alo = Applicative[List].compose[Option]

scala> alo.pure(3)
res0: List[Option[Int]] = List(Some(3))

scala> alo.product(List(None, Some(true), Some(false)), List(Some(2), None))
res1: List[Option[(Boolean, Int)]] = List(None, None, Some((true,2)), None, Some((false,2)), None)

Compose an Apply[F] and an Apply[G] into an Apply[λ[α => F[G[α]]]].

Example:

scala> import cats.implicits._

scala> val alo = Apply[List].compose[Option]

scala> alo.product(List(None, Some(true), Some(false)), List(Some(2), None))
res1: List[Option[(Boolean, Int)]] = List(None, None, Some((true,2)), None, Some((false,2)), None)

Compose an Applicative[F] and a ContravariantMonoidal[G] into a ContravariantMonoidal[λ[α => F[G[α]]]].

Example:

scala> import cats.kernel.Comparison
scala> import cats.implicits._

// compares strings by alphabetical order
scala> val alpha: Order[String] = Order[String]

// compares strings by their length
scala> val strLength: Order[String] = Order.by[String, Int](_.length)

scala> val stringOrders: List[Order[String]] = List(alpha, strLength)

// first comparison is with alpha order, second is with string length
scala> stringOrders.map(o => o.comparison("abc", "de"))
res0: List[Comparison] = List(LessThan, GreaterThan)

scala> val le = Applicative[List].composeContravariantMonoidal[Order]

// create Int orders that convert ints to strings and then use the string orders
scala> val intOrders: List[Order[Int]] = le.contramap(stringOrders)(_.toString)

// first comparison is with alpha order, second is with string length
scala> intOrders.map(o => o.comparison(12, 3))
res1: List[Comparison] = List(LessThan, GreaterThan)

// create the `product` of the string order list and the int order list
// `p` contains a list of the following orders:
// 1. (alpha comparison on strings followed by alpha comparison on ints)
// 2. (alpha comparison on strings followed by length comparison on ints)
// 3. (length comparison on strings followed by alpha comparison on ints)
// 4. (length comparison on strings followed by length comparison on ints)
scala> val p: List[Order[(String, Int)]] = le.product(stringOrders, intOrders)

scala> p.map(o => o.comparison(("abc", 12), ("def", 3)))
res2: List[Comparison] = List(LessThan, LessThan, LessThan, GreaterThan)

Compose Invariant F[_] and Functor G[_] then produce Invariant[F[G[_]]] using F's imap and G's map.

Example:

scala> import cats.implicits._
scala> import scala.concurrent.duration._

scala> val durSemigroupList: Semigroup[List[FiniteDuration]] =
    | Invariant[Semigroup]
    |   .composeFunctor[List]
    |   .imap(Semigroup[List[Long]])(Duration.fromNanos)(_.toNanos)
scala> durSemigroupList.combine(List(2.seconds, 3.seconds), List(4.seconds))
res1: List[FiniteDuration] = List(2 seconds, 3 seconds, 4 seconds)

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)

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

Apply a monadic function and discard the result while keeping the effect.

scala> import cats._, implicits._
scala> Option(1).flatTap(_ => None)
res0: Option[Int] = None
scala> Option(1).flatTap(_ => Some("123"))
res1: Option[Int] = Some(1)
scala> def nCats(n: Int) = List.fill(n)("cat")
nCats: (n: Int)List[String]
scala> List[Int](0).flatTap(nCats)
res2: List[Int] = List()
scala> List[Int](4).flatTap(nCats)
res3: List[Int] = List(4, 4, 4, 4)

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" a nested F of F structure into a single-layer F structure.

This is also commonly called join.

Example:

scala> import cats.Eval
scala> import cats.implicits._

scala> val nested: Eval[Eval[Int]] = Eval.now(Eval.now(3))
scala> val flattened: Eval[Int] = nested.flatten
scala> flattened.value
res0: Int = 3

Alias for map, since map can't be injected as syntax if the implementing type already had a built-in .map method.

Example:

scala> import cats.implicits._

scala> val m: Map[Int, String] = Map(1 -> "hi", 2 -> "there", 3 -> "you")

scala> m.fmap(_ ++ "!")
res0: Map[Int,String] = Map(1 -> hi!, 2 -> there!, 3 -> you!)

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

Like an infinite loop of >> calls. This is most useful effect loops that you want to run forever in for instance a server.

This will be an infinite loop, or it will return an F[Nothing].

Be careful using this. For instance, a List of length k will produce a list of length k^n at iteration n. This means if k = 0, we return an empty list, if k = 1, we loop forever allocating single element lists, but if we have a k > 1, we will allocate exponentially increasing memory and very quickly OOM.

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

Example:

scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> Functor[Option].fproduct(Option(42))(_.toString)
res0: Option[(Int, String)] = Some((42,42))

Pair the result of function application with A.

Example:

scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> Functor[Option].fproductLeft(Option(42))(_.toString)
res0: Option[(String, Int)] = Some((42,42))

Get the element at the index of the Foldable.

An if-then-else lifted into the F context. This function combines the effects of the fcond condition and of the two branches, in the order in which they are given.

The value of the result is, depending on the value of the condition, the value of the first argument, or the value of the second argument.

Example:

scala> import cats.implicits._

scala> val b1: Option[Boolean] = Some(true)
scala> val asInt1: Option[Int] = Apply[Option].ifA(b1)(Some(1), Some(0))
scala> asInt1.get
res0: Int = 1

scala> val b2: Option[Boolean] = Some(false)
scala> val asInt2: Option[Int] = Apply[Option].ifA(b2)(Some(1), Some(0))
scala> asInt2.get
res1: Int = 0

scala> val b3: Option[Boolean] = Some(true)
scala> val asInt3: Option[Int] = Apply[Option].ifA(b3)(Some(1), None)
asInt2: Option[Int] = None

Simulates an if/else-if/else in the context of an F. It evaluates conditions until one evaluates to true, and returns the associated F[A]. If no condition is true, returns els.

scala> import cats._
scala> Monad[Eval].ifElseM(Eval.later(false) -> Eval.later(1), Eval.later(true) -> Eval.later(2))(Eval.later(5)).value
res0: Int = 2

Based on a gist by Daniel Spiewak with a stack-safe implementation due to P. Oscar Boykin

Lifts if to Functor

Example:

scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List].ifF(List(true, false, false))(1, 0)
res0: List[Int] = List(1, 0, 0)

if lifted into monad.

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.

iterateForeverM is almost exclusively useful for effect types. For instance, A may be some state, we may take the current state, run some effect to get a new state and repeat.

Execute an action repeatedly until its result satisfies the given predicate and return that result, discarding all others.

Apply a monadic function iteratively until its result satisfies the given predicate and return that result.

Execute an action repeatedly until its result fails to satisfy the given predicate and return that result, discarding all others.

Apply a monadic function iteratively until its result fails to satisfy the given predicate and return that result.

Lift a function f to operate on Functors

Example:

scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> val o = Option(42)
scala> Functor[Option].lift((x: Int) => x + 10)(o)
res0: Option[Int] = Some(52)

Similar to map2 but uses Eval to allow for laziness in the F[B] argument. This can allow for "short-circuiting" of computations.

NOTE: the default implementation of map2Eval does not short-circuit computations. For data structures that can benefit from laziness, Apply instances should override this method.

In the following example, x.map2(bomb)(_ + _) would result in an error, but map2Eval "short-circuits" the computation. x is None and thus the result of bomb doesn't even need to be evaluated in order to determine that the result of map2Eval should be None.

scala> import cats.{Eval, Later}
scala> import cats.implicits._
scala> val bomb: Eval[Option[Int]] = Later(sys.error("boom"))
scala> val x: Option[Int] = None
scala> x.map2Eval(bomb)(_ + _).value
res0: Option[Int] = None

Akin to map, but also provides the value's index in structure F when calling the function.

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 the maximum A item in this structure according to the Order[A].

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 the minimum A item in this structure according to the Order[A].

Pair A with the result of function application.

Example:

scala> import cats.implicits._
scala> List("12", "34", "56").mproduct(_.toList)
res0: List[(String, Char)] = List((12,1), (12,2), (34,3), (34,4), (56,5), (56,6))

Same as align, but forgets from the type that one of the two elements must be present.

Example:

scala> import cats.implicits._
scala> Align[List].padZip(List(1, 2), List(10))
res0: List[(Option[Int], Option[Int])] = List((Some(1),Some(10)), (Some(2),None))

Same as alignWith, but forgets from the type that one of the two elements must be present.

Example:

scala> import cats.implicits._
scala> Align[List].padZipWith(List(1, 2), List(10, 11, 12))(_ |+| _)
res0: List[Option[Int]] = List(Some(11), Some(13), Some(12))

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

point lifts any value into a Monoidal Functor.

Example:

scala> import cats.implicits._

scala> InvariantMonoidal[Option].point(10)
res0: Option[Int] = Some(10)

Sequentially compose two actions, discarding any value produced by the second. This variant of productL also lets you define the evaluation strategy of the second action. For instance you can evaluate it only ''after'' the first action has finished:

scala> import cats.Eval
scala> import cats.implicits._
scala> var count = 0
scala> val fa: Option[Int] = Some(3)
scala> def fb: Option[Unit] = Some(count += 1)
scala> fa.productLEval(Eval.later(fb))
res0: Option[Int] = Some(3)
scala> assert(count == 1)
scala> none[Int].productLEval(Eval.later(fb))
res1: Option[Int] = None
scala> assert(count == 1)

Sequentially compose two actions, discarding any value produced by the first. This variant of productR also lets you define the evaluation strategy of the second action. For instance you can evaluate it only ''after'' the first action has finished:

scala> import cats.Eval
scala> import cats.implicits._
scala> val fa: Option[Int] = Some(3)
scala> def fb: Option[String] = Some("foo")
scala> fa.productREval(Eval.later(fb))
res0: Option[String] = Some(foo)

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.

Given fa and n, apply fa n times to construct an F[List[A]] value.

Example:

scala> import cats.data.State

scala> type Counter[A] = State[Int, A]
scala> val getAndIncrement: Counter[Int] = State { i => (i + 1, i) }
scala> val getAndIncrement5: Counter[List[Int]] =
    | Applicative[Counter].replicateA(5, getAndIncrement)
scala> getAndIncrement5.run(0).value
res0: (Int, List[Int]) = (5,List(0, 1, 2, 3, 4))

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

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

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[A] in a G context, ignoring the values returned by provided function.

Example:

scala> import cats.implicits._
scala> import java.io.IOException
scala> type IO[A] = Either[IOException, A]
scala> def debug(msg: String): IO[Unit] = Right(())
scala> List("1", "2", "3").traverseTap(debug)
res1: IO[List[String]] = Right(List(1, 2, 3))

Akin to traverse, but also provides the value's index in structure F when calling the function.

This performs the traversal in a single pass but requires that effect G is monadic. An applicative traversal can be performed in two passes using zipWithIndex followed by traverse.

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.

Example:

scala> import scala.collection.immutable.Queue
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForQueue

scala> Functor[Queue].tupleLeft(Queue("hello", "world"), 42)
res0: scala.collection.immutable.Queue[(Int, String)] = Queue((42,hello), (42,world))

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

Example:

scala> import scala.collection.immutable.Queue
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForQueue

scala> Functor[Queue].tupleRight(Queue("hello", "world"), 42)
res0: scala.collection.immutable.Queue[(String, Int)] = Queue((hello,42), (world,42))

Returns an F[Unit] value, equivalent with pure(()).

A useful shorthand, also allowing implementations to optimize the returned reference (e.g. it can be a val).

Example:

scala> import cats.implicits._

scala> Applicative[Option].unit
res0: Option[Unit] = Some(())

Returns the given argument (mapped to Unit) if cond is false, otherwise, unit lifted into F.

Example:

scala> import cats.implicits._

scala> Applicative[List].unlessA(true)(List(1, 2, 3))
res0: List[Unit] = List(())

scala> Applicative[List].unlessA(false)(List(1, 2, 3))
res1: List[Unit] = List((), (), ())

scala> Applicative[List].unlessA(true)(List.empty[Int])
res2: List[Unit] = List(())

scala> Applicative[List].unlessA(false)(List.empty[Int])
res3: List[Unit] = List()

This repeats an F until we get defined values. This can be useful for polling type operations on State (or RNG) Monads, or in effect monads.

Execute an action repeatedly until the Boolean condition returns true. The condition is evaluated after the loop body. Collects results into an arbitrary Alternative value, such as a Vector. This implementation uses append on each evaluation result, so avoid data structures with non-constant append performance, e.g. List.

Execute an action repeatedly until the Boolean condition returns true. The condition is evaluated after the loop body. Discards results.

Un-zips an F[(A, B)] consisting of element pairs or Tuple2 into two separate F's tupled.

NOTE: Check for effect duplication, possibly memoize before

scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List].unzip(List((1,2), (3, 4)))
res0: (List[Int], List[Int]) = (List(1, 3),List(2, 4))

Empty the fa of the values, preserving the structure

Example:

scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

scala> Functor[List].void(List(1,2,3))
res0: List[Unit] = List((), (), ())

Returns the given argument (mapped to Unit) if cond is true, otherwise, unit lifted into F.

Example:

scala> import cats.implicits._

scala> Applicative[List].whenA(true)(List(1, 2, 3))
res0: List[Unit] = List((), (), ())

scala> Applicative[List].whenA(false)(List(1, 2, 3))
res1: List[Unit] = List(())

scala> Applicative[List].whenA(true)(List.empty[Int])
res2: List[Unit] = List()

scala> Applicative[List].whenA(false)(List.empty[Int])
res3: List[Unit] = List(())

Execute an action repeatedly as long as the given Boolean expression returns true. The condition is evaluated before the loop body. Collects the results into an arbitrary Alternative value, such as a Vector. This implementation uses append on each evaluation result, so avoid data structures with non-constant append performance, e.g. List.

Execute an action repeatedly as long as the given Boolean expression returns true. The condition is evaluated before the loop body. Discards results.

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.

Example:

scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

scala> val s = Some(42)
scala> Functor[Option].widen(s)
res0: Option[Int] = Some(42)

Pairs elements of two structures along the union of their shapes, using placeholders for missing values.

Example:

scala> import cats.implicits._
scala> Align[List].zipAll(List(1, 2), List(10, 11, 12), 20, 21)
res0: List[(Int, Int)] = List((1,10), (2,11), (20,12))

Traverses through the structure F, pairing the values with assigned indices.

The behavior is consistent with the Scala collection library's zipWithIndex for collections such as List.