Handle any error, potentially recovering from it, by mapping it to an F[A] value.

pure lifts any value into the Applicative Functor.

Example:

scala> import cats.implicits._

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

Lift an error into the F context.

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)

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.

Transform certain errors using pf and rethrow them. Non matching errors and successful values are not affected by this function.

Example:

scala> import cats._, implicits._

scala> def pf: PartialFunction[String, String] = { case "error" => "ERROR" }

scala> ApplicativeError[Either[String, *], String].adaptError("error".asLeft[Int])(pf)
res0: Either[String,Int] = Left(ERROR)

scala> ApplicativeError[Either[String, *], String].adaptError("err".asLeft[Int])(pf)
res1: Either[String,Int] = Left(err)

scala> ApplicativeError[Either[String, *], String].adaptError(1.asRight[String])(pf)
res2: Either[String,Int] = Right(1)

The same function is available in ApplicativeErrorOps as adaptErr - it cannot have the same name because this would result in ambiguous implicits due to adaptError having originally been included in the MonadError API and syntax.

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)

Handle errors by turning them into scala.util.Either values.

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.

Similar to attempt, but it only handles errors of type EE.

Similar to attempt, but wraps the result in a cats.data.EitherT for convenience.

Reifies the value or error of the source and performs an effect on the result, then recovers the original value or error back into F.

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)

Often E is Throwable. Here we try to call pure or catch and raise.

Often E is Throwable. Here we try to call pure or catch and raise

Evaluates the specified block, catching exceptions of the specified type. Uncaught exceptions are propagated.

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

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

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

Convert from scala.Either

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

Convert from scala.Option

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 the error type is Throwable, we can convert from a scala.util.Try

Convert from cats.data.Validated

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

Handle any error, by mapping it to an A value.

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.

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

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)

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

Execute a callback on certain errors, then rethrow them. Any non matching error is rethrown as well.

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

point lifts any value into a Monoidal Functor.

Example:

scala> import cats.implicits._

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

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)

Returns raiseError when cond is false, otherwise F.unit

Returns raiseError when the cond is true, otherwise F.unit

Recover from certain errors by mapping them to an A value.

Recover from certain errors by mapping them to an F[A] value.

Returns a new value that transforms the result of the source, given the recover or map functions, which get executed depending on whether the result is successful or if it ends in error.

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.

Returns a new value that transforms the result of the source, given the recover or bind functions, which get executed depending on whether the result is successful or if it ends in error.

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.

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

Inverse of attempt

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)