Keeps calling f until a scala.util.Right[B] is returned.

Based on Phil Freeman's Stack Safety for Free.

Implementations of this method should use constant stack space relative to f.

Alias for productR.

Alias for productL.

Alias for ap.

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

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

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)

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)

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)

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

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

if lifted into monad.

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

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

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

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.

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)

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

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)

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

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

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)