Target

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

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

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

Example:
{{{
scala> import cats.ApplicativeError
scala> import cats.instances.option._

scala> ApplicativeError[Option, Unit] .fromEither(Right(1))
res0: scala.Option[Int] = Some(1)

scala> ApplicativeError[Option, Unit] .fromEither(Left(()))
res1: scala.Option[Nothing] = None
}}}

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

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

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

{{{
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> ListInt.flatTap(nCats)
res2: List[Int] = List()
scala> ListInt.flatTap(nCats)
res3: List[Int] = List(4, 4, 4, 4)
}}}

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

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

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

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

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

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

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

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption

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

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.

Example:
{{{
scala> import cats.implicits._
scala> import cats.ApplicativeError
scala> val F = ApplicativeError[Either[String, *] , String]

scala> F.fromOption(Some(1), "Empty")
res0: scala.Either[String, Int] = Right(1)

scala> F.fromOption(Option.empty[Int] , "Empty")
res1: scala.Either[String, Int] = Left(Empty)
}}}

If there is no error, then an scala.util.Right value will be returned instead.

All non-fatal errors should be handled by this method.

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

This is an optimization on usage of attempt and flatMap,
this equivalence being available:

{{{
fa.redeemWith(fe, fs) <-> fa.attempt.flatMap(_.fold(fe, fs))
}}}

Usage of redeemWith subsumes handleErrorWith because:

{{{
fa.redeemWith(fe, F.pure) <-> fa.handleErrorWith(fe)
}}}

Usage of redeemWith also subsumes flatMap because:

{{{
fa.redeemWith(F.raiseError, fs) <-> fa.flatMap(fs)
}}}

Implementations are free to override it in order to optimize
error recovery.

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

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

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

}}}

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

In the following example, only one of the errors is logged,
but they are both rethrown, to be possibly handled by another
layer of the program:

{{{
scala> import cats., data., implicits._

scala> case class Err(msg: String)

scala> type F[A] = EitherT[State[String, *] , Err, A]

scala> val action: PartialFunction[Err, F[Unit] ] = {
| case Err("one") => EitherT.liftF(State.set("one"))
| }

scala> val prog1: F[Int] = (Err("one")).raiseError[F, Int]
scala> val prog2: F[Int] = (Err("two")).raiseError[F, Int]

scala> prog1.onError(action).value.run("").value

res0: (String, Either[Err,Int] ) = (one,Left(Err(one)))

scala> prog2.onError(action).value.run("").value
res1: (String, Either[Err,Int] ) = ("",Left(Err(two)))
}}}

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

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

Example:
{{{
scala> import cats.implicits._

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

Example:
{{{
scala> import cats.implicits._

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

This is an optimization on usage of attempt and map,
this equivalence being available:

{{{
fa.redeem(fe, fs) <-> fa.attempt.map(_.fold(fe, fs))
}}}

Usage of redeem subsumes handleError because:

{{{
fa.redeem(fe, id) <-> fa.handleError(fe)
}}}

Implementations are free to override it in order to optimize
error recovery.

Example:
{{{
scala> import cats.implicits._
scala> import cats.ApplicativeError

scala> ApplicativeError[Option, Unit] .fromValidated(1.valid[Unit] )
res0: scala.Option[Int] = Some(1)

scala> ApplicativeError[Option, Unit] .fromValidated(().invalid[Int] )
res1: scala.Option[Int] = None
}}}

Example:
{{{
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForList

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

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

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.byString, Int

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

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

Example:
{{{
scala> import cats.implicits._
scala> import scala.util.{Try, Success}

scala> val a: Try[Either[Throwable, Int] ] = Success(Left(new java.lang.Exception))
scala> a.rethrow
res0: scala.util.Try[Int] = Failure(java.lang.Exception)

scala> val b: Try[Either[Throwable, Int] ] = Success(Right(1))
scala> b.rethrow
res1: scala.util.Try[Int] = Success(1)
}}}

Example:
{{{
scala> import cats.implicits._

// integer-rounded division
scala> def divide[F[_] ](dividend: Int, divisor: Int)(implicit F: ApplicativeError[F, String] ): F[Int] =
| if (divisor === 0) F.raiseError("division by zero")
| else F.pure(dividend / divisor)

scala> type ErrorOr[A] = Either[String, A]

scala> divide[ErrorOr] (6, 3)
res0: ErrorOr[Int] = Right(2)

scala> divide[ErrorOr] (6, 0)
res1: ErrorOr[Int] = Left(division by zero)
}}}

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

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

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

Note that if the effect returned by f fails, the resulting effect will fail too.

Alias for fa.attempt.flatTap(f).rethrow for convenience.

Example:
{{{
scala> import cats.implicits._
scala> import scala.util.{Try, Success, Failure}

scala> def checkError(result: Either[Throwable, Int] ): Try[String] = result.fold(_ => Failure(new java.lang.Exception), _ => Success("success"))

scala> val a: Try[Int] = Failure(new Throwable("failed"))
scala> a.attemptTap(checkError)
res0: scala.util.Try[Int] = Failure(java.lang.Exception)

scala> val b: Try[Int] = Success(1)
scala> b.attemptTap(checkError)
res1: scala.util.Try[Int] = Success(1)
}}}

Based on Phil Freeman's
Stack Safety for Free.

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