Given a value and a function in the Apply context, applies the function to the value.

Example:

scala> import cats.implicits._

scala> val someF: Option[Int => Long] = Some(_.toLong + 1L)
scala> val noneF: Option[Int => Long] = None
scala> val someInt: Option[Int] = Some(3)
scala> val noneInt: Option[Int] = None

scala> Apply[Option].ap(someF)(someInt)
res0: Option[Long] = Some(4)

scala> Apply[Option].ap(noneF)(someInt)
res1: Option[Long] = None

scala> Apply[Option].ap(someF)(noneInt)
res2: Option[Long] = None

scala> Apply[Option].ap(noneF)(noneInt)
res3: Option[Long] = None

Combine two F[A] values.

Example:

scala> import cats.implicits._
scala> SemigroupK[List].combineK(List(1, 2), List(3, 4))
res0: List[Int] = List(1, 2, 3, 4)

Given a type A, create an "empty" F[A] value.

Example:

scala> import cats.implicits._
scala> MonoidK[List].empty[Long]
res0: List[Long] = List()

pure lifts any value into the Applicative Functor.

Example:

scala> import cats.implicits._

scala> Applicative[Option].pure(10)
res0: Option[Int] = Some(10)

Alias for productR.

Alias for productL.

Alias for ap.

Given a type A, create a concrete Monoid[F[A]].

Example:

scala> import cats.implicits._
scala> MonoidK[List].algebra[Long].empty
res0: List[Long] = List()

ap2 is a binary version of ap, defined in terms of ap.

Lift a into F[_] and append it to fa.

Example:

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

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)

Given a sequence of as, sum them using the monoidK and return the total.

Example:

scala> MonoidK[List].combineAllK(List(List("One"), List("Two"), List("Three")))
res0: List[String] = List(One, Two, Three)

scala> MonoidK[List].combineAllK[String](List.empty)
res1: List[String] = List()

Given a sequence of as, combine them and return the total.

If the sequence is empty, returns None. Otherwise, returns Some(total).

Example:

scala> SemigroupK[List].combineAllOptionK(List(List("One"), List("Two"), List("Three")))
res0: Option[List[String]] = Some(List(One, Two, Three))

scala> SemigroupK[List].combineAllOptionK[String](List.empty)
res1: Option[List[String]] = None

Similar to combineK but uses Eval to allow for laziness in the second argument. This can allow for "short-circuiting" of computations.

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

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

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

Return a combined with itself n times.

Example:

scala> SemigroupK[List].combineNK(List(1), 5)
res0: List[Int] = List(1, 1, 1, 1, 1)

scala> MonoidK[List].combineNK(List("ha"), 0)
res1: List[String] = List()

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)

Given a kind G, create an "composed" MonoidK[F[G[_]]

Example:

scala> import cats.implicits._
scala> val monoidK = MonoidK[List].compose[Option]
scala> monoidK.combineK(List(Some(1)), List(Some(2), None))
res0: List[Option[Int]] = List(Some(1), Some(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 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 Invariant F[_] and Contravariant G[_] then produce Invariant[F[G[_]]] using F's imap and G's contramap.

Example:

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

scala> type ToInt[T] = T => Int
scala> val durSemigroupToInt: Semigroup[ToInt[FiniteDuration]] =
     | Invariant[Semigroup]
     |   .composeContravariant[ToInt]
     |   .imap(Semigroup[ToInt[Long]])(Duration.fromNanos)(_.toNanos)
// semantically equal to (2.seconds.toSeconds.toInt + 1) + (2.seconds.toSeconds.toInt * 2) = 7
scala> durSemigroupToInt.combine(_.toSeconds.toInt + 1, _.toSeconds.toInt * 2)(2.seconds)
res1: Int = 7

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)

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

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

Return ().pure[F] if condition is true, empty otherwise

Example:

scala> import cats.implicits._
scala> def even(i: Int): Option[String] = Alternative[Option].guard(i % 2 == 0).as("even")
scala> even(2)
res0: Option[String] = Some(even)
scala> even(3)
res1: Option[String] = None

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)

Transform an F[A] into an F[B] by providing a transformation from A to B and one from B to A.

Example:

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

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

Tests if a is the identity.

Example:

scala> MonoidK[List].isEmpty(List.empty[String])
res0: Boolean = true

scala> MonoidK[List].isEmpty(List("something"))
res1: Boolean = false

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)

Applies the pure (binary) function f to the effectful values fa and fb.

map2 can be seen as a binary version of cats.Functor#map.

Example:

scala> import cats.implicits._

scala> val someInt: Option[Int] = Some(3)
scala> val noneInt: Option[Int] = None
scala> val someLong: Option[Long] = Some(4L)
scala> val noneLong: Option[Long] = None

scala> Apply[Option].map2(someInt, someLong)((i, l) => i.toString + l.toString)
res0: Option[String] = Some(34)

scala> Apply[Option].map2(someInt, noneLong)((i, l) => i.toString + l.toString)
res0: Option[String] = None

scala> Apply[Option].map2(noneInt, noneLong)((i, l) => i.toString + l.toString)
res0: Option[String] = None

scala> Apply[Option].map2(noneInt, someLong)((i, l) => i.toString + l.toString)
res0: Option[String] = None

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

point lifts any value into a Monoidal Functor.

Example:

scala> import cats.implicits._

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

Lift a into F[_] and prepend it to fa.

Example:

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

Combine an F[A] and an F[B] into an F[(A, B)] that maintains the effects of both fa and fb.

Example:

scala> import cats.implicits._

scala> val noneInt: Option[Int] = None
scala> val some3: Option[Int] = Some(3)
scala> val noneString: Option[String] = None
scala> val someFoo: Option[String] = Some("foo")

scala> Semigroupal[Option].product(noneInt, noneString)
res0: Option[(Int, String)] = None

scala> Semigroupal[Option].product(noneInt, someFoo)
res1: Option[(Int, String)] = None

scala> Semigroupal[Option].product(some3, noneString)
res2: Option[(Int, String)] = None

scala> Semigroupal[Option].product(some3, someFoo)
res3: Option[(Int, String)] = Some((3,foo))

Compose two actions, discarding any value produced by the second.

Compose two actions, discarding any value produced by the first.

Return a combined with itself more than once.

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

Given fa and n, apply fa n times discarding results to return F[Unit].

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[Unit] =
     | Applicative[Counter].replicateA_(5, getAndIncrement)
scala> getAndIncrement5.run(0).value
res0: (Int, Unit) = (5,())

return a semigroupK that reverses the order so combineK(a, b) == reverse.combineK(b, a)

Separate the inner foldable values into the "lefts" and "rights".

Example:

scala> val l: List[Either[String, Int]] = List(Right(1), Left("error"))
scala> Alternative[List].separate(l)
res0: (List[String], List[Int]) = (List(error),List(1))

Separate the inner foldable values into the "lefts" and "rights".

A variant of separate that is specialized for Fs that have Foldable instances which allows for a single-pass implementation (as opposed to

separate

which is 2-pass).

Example:

scala> import cats.implicits._
scala> val l: List[Either[String, Int]] = List(Right(1), Left("error"))
scala> Alternative[List].separateFoldable(l)
res0: (List[String], List[Int]) = (List(error),List(1))

separate }}}

Example:

scala> import cats.implicits._
scala> val l: List[Either[String, Int]] = List(Right(1), Left("error"))
scala> Alternative[List].separateFoldable(l)
res0: (List[String], List[Int]) = (List(error),List(1))

Combines F[A] and F[B] into a F[Either[A,B]]].

Example:

scala> import cats.SemigroupK
scala> import cats.data.NonEmptyList
scala> SemigroupK[NonEmptyList].sum(NonEmptyList.one("abc"), NonEmptyList.one(2))
res0: NonEmptyList[Either[String,Int]] = NonEmptyList(Left(abc), Right(2))