Handle any error, potentially recovering from it, by mapping it to an
F[A]
value.
Handle any error, potentially recovering from it, by mapping it to an
F[A]
value.
recoverWith to recover from only certain errors.
handleError to handle any error by simply mapping it to an A
value instead of an F[A]
.
pure
lifts any value into the Applicative Functor.
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.
Lift an error into the F
context.
Keeps calling f
until a scala.util.Right[B]
is returned.
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.
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> "error".asLeft[Int].adaptError(pf) res0: Either[String,Int] = Left(ERROR) scala> "err".asLeft[Int].adaptError(pf) res1: Either[String,Int] = Left(err) scala> 1.asRight[String].adaptError(pf) res2: Either[String,Int] = Right(1)
Given a value and a function in the Apply context, applies the function to the value.
ap2 is a binary version of ap, defined in terms of ap.
ap2 is a binary version of ap, defined in terms of ap.
Replaces the A
value in F[A]
with the supplied value.
Replaces the A
value in F[A]
with the supplied value.
Handle errors by turning them into scala.util.Either values.
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 wraps the result in a cats.data.EitherT for convenience.
Similar to attempt, but wraps the result in a cats.data.EitherT for convenience.
Often E is Throwable.
Often E is Throwable. Here we try to call pure or catch and raise.
Often E is Throwable.
Often E is Throwable. Here we try to call pure or catch and raise
Compose an Applicative[F]
and an Applicative[G]
into an
Applicative[λ[α => F[G[α]]]]
.
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 Applicative[F]
and a ContravariantMonoidal[G]
into a
ContravariantMonoidal[λ[α => F[G[α]]]]
.
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)
Turns a successful value into an error if it does not satisfy a given predicate.
Turns a successful value into an error specified by the error
function if it does not satisfy a given predicate.
Apply a monadic function and discard the result while keeping the effect.
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.
"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.
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
Tuple the values in fa with the result of applying a function with the value
Convert from scala.Either
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
If the error type is Throwable, we can convert from a scala.util.Try
If the error type is Throwable, we can convert from a scala.util.Try
Handle any error, by mapping it to an A
value.
Handle any error, by mapping it to an A
value.
recover to only recover from certain errors.
handleErrorWith to map to an F[A]
value instead of simply an
A
value.
if
lifted into monad.
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
.
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
Execute an action repeatedly until its result satisfies the given predicate and return that result, discarding all others.
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.
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.
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.
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
Lift a function f to operate on Functors
Applies the pure (binary) function f to the effectful values fa and fb.
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.
Similar to map2 but uses Eval to allow for laziness in the F[B]
argument.
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.
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.
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.
point
lifts any value into a Monoidal Functor.
Example:
scala> import cats.implicits._ scala> InvariantMonoidal[Option].point(10) res0: Option[Int] = Some(10)
Compose two actions, discarding any value produced by the second.
Compose two actions, discarding any value produced by the second.
Sequentially 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.
Compose two actions, discarding any value produced by the first.
Sequentially 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)
Recover from certain errors by mapping them to an A
value.
Recover from certain errors by mapping them to an A
value.
recoverWith to recover from certain errors by mapping them to
F[A]
values.
handleError to handle any/all errors.
Recover from certain errors by mapping them to an F[A]
value.
Recover from certain errors by mapping them to an F[A]
value.
recover to recover from certain errors by mapping them to A
values.
handleErrorWith to handle any/all errors.
Given fa
and n
, apply fa
n
times to construct an F[List[A]]
value.
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
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)
Tuples the A
value in F[A]
with the supplied B
value, with the B
value on the left.
Tuples the A
value in F[A]
with the supplied B
value, with the B
value on the left.
Tuples the A
value in F[A]
with the supplied B
value, with the B
value on the right.
Tuples the A
value in F[A]
with the supplied B
value, with the B
value on the right.
Returns an F[Unit]
value, equivalent with pure(())
.
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.
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()
Execute an action repeatedly until the Boolean
condition returns true
.
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
.
Execute an action repeatedly until the Boolean
condition returns true
.
The condition is evaluated after the loop body. Discards results.
Empty the fa of the values, preserving the structure
Empty the fa of the values, preserving the structure
Returns the given argument (mapped to Unit) if cond
is true
, otherwise,
unit lifted into F.
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
.
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
.
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.
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
.
Alias for productR.
(Since version 1.0.0-RC2) Use apREval instead.
Alias for productL.
(Since version 1.0.0-RC2) Use apLEval instead.
A monad that also allows you to raise and or handle an error value.
This type class allows one to abstract over error-handling monads.