Algebra
Value members
Concrete methods
Inherited methods
Wait for the specified duration after the execution of fa
before returning the result.
Wait for the specified duration after the execution of fa
before returning the result.
- Value parameters:
- fa
The effect to execute
- time
The duration to wait after executing fa
- Inherited from:
- GenTemporal
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
Replaces the A
value in F[A]
with the supplied value.
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)
- Inherited from:
- Functor
The asynchronous FFI.
The asynchronous FFI.
k
takes a callback of type Either[Throwable, A] => Unit
to signal the result of the
asynchronous computation. The execution of async(k)
is semantically blocked until the
callback is invoked.
k
returns an Option[F[Unit]]
which is an optional finalizer to be run in the event that
the fiber running
async(k)
is canceled.
async(k) }}}
- Inherited from:
- Async
A convenience version of Async.async for when we don't need to perform F[_]
effects
or perform finalization in the event of cancelation.
A convenience version of Async.async for when we don't need to perform F[_]
effects
or perform finalization in the event of cancelation.
- Inherited from:
- Async
Similar to attempt, but it only handles errors of type EE
.
Similar to attempt, but it only handles errors of type EE
.
- Inherited from:
- ApplicativeError
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.
- Inherited from:
- ApplicativeError
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
.
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)
- Inherited from:
- MonadError
Returns a Resource that manages the concurrent execution of a fiber. The inner effect can be used to wait on the outcome of the child fiber; it is effectively a join.
Returns a Resource that manages the concurrent execution of a fiber. The inner effect can be used to wait on the outcome of the child fiber; it is effectively a join.
The child fiber is canceled in two cases: either the resource goes out of scope or the parent fiber is canceled. If the child fiber terminates before one of these cases occurs, then cancelation is a no-op. This avoids fiber leaks because the child fiber is always canceled before the parent fiber drops the reference to it.
// Starts a fiber that continously prints "A".
// After 10 seconds, the resource scope exits so the fiber is canceled.
F.background(F.delay(println("A")).foreverM).use { _ =>
F.sleep(10.seconds)
}
- Value parameters:
- fa
the effect for the spawned fiber
- Inherited from:
- GenSpawn
Start a new background fiber on a different execution context.
Start a new background fiber on a different execution context.
See GenSpawn.background for more details.
- Inherited from:
- Async
Like Sync.delay but intended for thread blocking operations. blocking
will shift the
execution of the blocking operation to a separate threadpool to avoid blocking on the main
execution context. See the thread-model documentation for more information on why this is
necessary. Note that the created effect will be uncancelable; if you need cancelation
then you should use Sync.interruptible or Sync.interruptibleMany.
Like Sync.delay but intended for thread blocking operations. blocking
will shift the
execution of the blocking operation to a separate threadpool to avoid blocking on the main
execution context. See the thread-model documentation for more information on why this is
necessary. Note that the created effect will be uncancelable; if you need cancelation
then you should use Sync.interruptible or Sync.interruptibleMany.
Sync[F].blocking(scala.io.Source.fromFile("path").mkString)
- Value parameters:
- thunk
The side effect which is to be suspended in
F[_]
and evaluated on a blocking execution context
- Inherited from:
- Sync
Races the evaluation of two fibers and returns the result of both.
Races the evaluation of two fibers and returns the result of both.
The following rules describe the semantics of both:
- If the winner completes with Outcome.Succeeded, the race waits for the loser to complete. 2. If the winner completes with Outcome.Errored, the race raises the error. The loser is canceled. 3. If the winner completes with Outcome.Canceled, the loser and the race are canceled as well. 4. If the loser completes with Outcome.Succeeded, the race returns the successful value of both fibers. 5. If the loser completes with Outcome.Errored, the race returns the error. 6. If the loser completes with Outcome.Canceled, the race is canceled. 7. If the race is canceled before one or both participants complete, then whichever ones are incomplete are canceled. 8. If the race is masked and is canceled because one or both participants canceled, the fiber will block indefinitely.
- Value parameters:
- fa
the effect for the first racing fiber
- fb
the effect for the second racing fiber
- See also:
bothOutcome for a variant that returns the Outcome of both fibers.
- Inherited from:
- GenSpawn
Races the evaluation of two fibers and returns the Outcome of both. If the race is canceled before one or both participants complete, then then whichever ones are incomplete are canceled.
Races the evaluation of two fibers and returns the Outcome of both. If the race is canceled before one or both participants complete, then then whichever ones are incomplete are canceled.
- Value parameters:
- fa
the effect for the first racing fiber
- fb
the effect for the second racing fiber
- See also:
both for a simpler variant that returns the results of both fibers.
- Inherited from:
- GenSpawn
A pattern for safely interacting with effectful lifecycles.
A pattern for safely interacting with effectful lifecycles.
If acquire
completes successfully, use
is called. If use
succeeds, fails, or is
canceled, release
is guaranteed to be called exactly once.
acquire
is uncancelable. release
is uncancelable. use
is cancelable by default, but
can be masked.
- Value parameters:
- acquire
the lifecycle acquisition action
- release
the lifecycle release action
- use
the effect to which the lifecycle is scoped, whose result is the return value of this function
- See also:
bracketCase for a more powerful variant
Resource for a composable datatype encoding of effectful lifecycles
- Inherited from:
- MonadCancel
A pattern for safely interacting with effectful lifecycles.
A pattern for safely interacting with effectful lifecycles.
If acquire
completes successfully, use
is called. If use
succeeds, fails, or is
canceled, release
is guaranteed to be called exactly once.
acquire
is uncancelable. release
is uncancelable. use
is cancelable by default, but
can be masked.
- Value parameters:
- acquire
the lifecycle acquisition action
- release
the lifecycle release action which depends on the outcome of
use
- use
the effect to which the lifecycle is scoped, whose result is the return value of this function
- See also:
bracketFull for a more powerful variant
Resource for a composable datatype encoding of effectful lifecycles
- Inherited from:
- MonadCancel
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.
- Inherited from:
- ApplicativeError
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
- Inherited from:
- ApplicativeError
Evaluates the specified block, catching exceptions of the specified type. Uncaught exceptions are propagated.
Evaluates the specified block, catching exceptions of the specified type. Uncaught exceptions are propagated.
- Inherited from:
- ApplicativeError
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)
- Inherited from:
- Applicative
Compose Invariant F[_]
and G[_]
then produce Invariant[F[G[_]]]
using their imap
.
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)
- Inherited from:
- Invariant
Compose an Apply[F]
and an Apply[G]
into an Apply[λ[α => F[G[α]]]]
.
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)
- Inherited from:
- Apply
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)
- Inherited from:
- Applicative
Compose Invariant F[_]
and Functor G[_]
then produce Invariant[F[G[_]]]
using F's imap
and G's map
.
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)
- Inherited from:
- Invariant
Suspends the evaluation of an F[_]
reference.
Suspends the evaluation of an F[_]
reference.
Equivalent to FlatMap.flatten
for pure expressions, the purpose of this function is to
suspend side effects in F[_]
.
- Inherited from:
- Sync
The synchronous FFI - lifts any by-name parameter into the F[_]
context.
The synchronous FFI - lifts any by-name parameter into the F[_]
context.
Equivalent to Applicative.pure for pure expressions, the purpose of this function is to
suspend side effects in F
. Use Sync.delay if your side effect is not thread-blocking;
otherwise you should use Sync.blocking (uncancelable) or Sync.interruptible (cancelable).
- Value parameters:
- thunk
The side effect which is to be suspended in
F[_]
- Inherited from:
- Sync
Delay the execution of fa
by a given duration.
Delay the execution of fa
by a given duration.
- Value parameters:
- fa
The effect to execute
- time
The duration to wait before executing fa
- Inherited from:
- GenTemporal
Turns a successful value into an error if it does not satisfy a given predicate.
Turns a successful value into an error if it does not satisfy a given predicate.
- Inherited from:
- MonadError
Turns a successful value into an error specified by the error
function 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.
- Inherited from:
- MonadError
Async.evalOn as a natural transformation.
Async.evalOn as a natural transformation.
- Inherited from:
- Async
Defer instances, like functions, parsers, generators, IO, etc... often are used in recursive settings where this function is useful
Defer instances, like functions, parsers, generators, IO, etc... often are used in recursive settings where this function is useful
fix(fn) == fn(fix(fn))
example:
val parser: P[Int] = Defer[P].fix[Int] { rec => CharsIn("0123456789") | P("(") ~ rec ~ P(")") }
Note, fn may not yield a terminating value in which case both of the above F[A] run forever.
- Inherited from:
- Defer
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)
- Inherited from:
- FlatMap
"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
- Inherited from:
- FlatMap
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!)
- Inherited from:
- Functor
Like an infinite loop of >> calls. This is most useful effect loops that you want to run forever in for instance a server.
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.
- Inherited from:
- FlatMap
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
Example:
scala> import cats.Functor
scala> import cats.implicits.catsStdInstancesForOption
scala> Functor[Option].fproduct(Option(42))(_.toString)
res0: Option[(Int, String)] = Some((42,42))
- Inherited from:
- Functor
Pair the result of function application with A
.
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))
- Inherited from:
- Functor
Suspend a java.util.concurrent.CompletableFuture
into the F[_]
context.
Suspend a java.util.concurrent.CompletableFuture
into the F[_]
context.
- Value parameters:
- fut
The
java.util.concurrent.CompletableFuture
to suspend inF[_]
- Inherited from:
- AsyncPlatform
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
- Inherited from:
- ApplicativeError
Lifts a scala.concurrent.Future into an F
effect.
Lifts a scala.concurrent.Future into an F
effect.
- Inherited from:
- Async
Convert from scala.Option
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)
- Inherited from:
- ApplicativeError
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
- Inherited from:
- ApplicativeError
Convert from cats.data.Validated
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
- Inherited from:
- ApplicativeError
Handle any error, by mapping it to an A
value.
Handle any error, by mapping it to an A
value.
- See also:
handleErrorWith to map to an
F[A]
value instead of simply anA
value.recover to only recover from certain errors.
- Inherited from:
- ApplicativeError
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.
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
- See also:
See https://gitter.im/typelevel/cats-effect?at=5f297e4314c413356f56d230 for the discussion.
- Inherited from:
- Monad
Lifts if
to Functor
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)
- Inherited from:
- Functor
Like Sync.blocking but will attempt to abort the blocking operation using thread interrupts in the event of cancelation. The interrupt will be attempted only once.
Like Sync.blocking but will attempt to abort the blocking operation using thread interrupts in the event of cancelation. The interrupt will be attempted only once.
- Value parameters:
- thunk
The side effect which is to be suspended in
F[_]
and evaluated on a blocking execution context
- Inherited from:
- Sync
Like Sync.blocking but will attempt to abort the blocking operation using thread interrupts in the event of cancelation. The interrupt will be attempted repeatedly until the blocking operation completes or exits.
Like Sync.blocking but will attempt to abort the blocking operation using thread interrupts in the event of cancelation. The interrupt will be attempted repeatedly until the blocking operation completes or exits.
- Value parameters:
- thunk
The side effect which is to be suspended in
F[_]
and evaluated on a blocking execution context
- Inherited from:
- Sync
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.
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.
- Inherited from:
- FlatMap
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.
- Inherited from:
- Monad
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.
- Inherited from:
- Monad
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.
- Inherited from:
- Monad
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.
- Inherited from:
- Monad
Lift a function f to operate on Functors
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)
- Inherited from:
- Functor
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
Caches the result of fa
.
Caches the result of fa
.
The returned inner effect, hence referred to as get
, when sequenced, will evaluate fa
and cache the result. If get
is sequenced multiple times fa
will only be evaluated
once.
If all get
s are canceled prior to fa
completing, it will be canceled and evaluated
again the next time get
is sequenced.
- Inherited from:
- GenConcurrent
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))
- Inherited from:
- FlatMap
An effect that never terminates.
An effect that never terminates.
Polymorphic so it can be used in situations where an arbitrary effect is expected eg Fiber.joinWithNever
- Inherited from:
- Async
Execute a callback on certain errors, then rethrow them. Any non matching error is rethrown as well.
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)))
- Inherited from:
- ApplicativeError
Like Parallel.parReplicateA
, but limits the degree of parallelism.
Like Parallel.parReplicateA
, but limits the degree of parallelism.
- Inherited from:
- GenConcurrent
Like Parallel.parSequence
, but limits the degree of parallelism.
Like Parallel.parSequence
, but limits the degree of parallelism.
- Inherited from:
- GenConcurrent
Like Parallel.parTraverse
, but limits the degree of parallelism. Note that the semantics
of this operation aim to maximise fairness: when a spot to execute becomes available, every
task has a chance to claim it, and not only the next n
tasks in ta
Like Parallel.parTraverse
, but limits the degree of parallelism. Note that the semantics
of this operation aim to maximise fairness: when a spot to execute becomes available, every
task has a chance to claim it, and not only the next n
tasks in ta
- Inherited from:
- GenConcurrent
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)
- Inherited from:
- InvariantMonoidal
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:
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)
- Inherited from:
- FlatMap
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:
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)
- Inherited from:
- FlatMap
Races the evaluation of two fibers that returns the result of the winner, except in the case of cancelation.
Races the evaluation of two fibers that returns the result of the winner, except in the case of cancelation.
The semantics of race are described by the following rules:
- If the winner completes with Outcome.Succeeded, the race returns the successful value. The loser is canceled before returning. 2. If the winner completes with Outcome.Errored, the race raises the error. The loser is canceled before returning. 3. If the winner completes with Outcome.Canceled, the race returns the result of the loser, consistent with the first two rules. 4. If both the winner and loser complete with Outcome.Canceled, the race is canceled. 8. If the race is masked and is canceled because both participants canceled, the fiber will block indefinitely.
- Value parameters:
- fa
the effect for the first racing fiber
- fb
the effect for the second racing fiber
- See also:
raceOutcome for a variant that returns the outcome of the winner.
- Inherited from:
- GenSpawn
Races the evaluation of two fibers that returns the Outcome of the winner. The winner of the race is considered to be the first fiber that completes with an outcome. The loser of the race is canceled before returning.
Races the evaluation of two fibers that returns the Outcome of the winner. The winner of the race is considered to be the first fiber that completes with an outcome. The loser of the race is canceled before returning.
- Value parameters:
- fa
the effect for the first racing fiber
- fb
the effect for the second racing fiber
- See also:
race for a simpler variant that returns the successful outcome.
- Inherited from:
- GenSpawn
Returns raiseError
when cond
is false, otherwise F.unit
Returns raiseError
when cond
is false, otherwise F.unit
- Example:
val tooMany = 5 val x: Int = ??? F.raiseUnless(x < tooMany)(new IllegalArgumentException("Too many"))
- Inherited from:
- ApplicativeError
Returns raiseError
when the cond
is true, otherwise F.unit
Returns raiseError
when the cond
is true, otherwise F.unit
- Example:
val tooMany = 5 val x: Int = ??? F.raiseWhen(x >= tooMany)(new IllegalArgumentException("Too many"))
- Inherited from:
- ApplicativeError
Recover from certain errors by mapping them to an A
value.
Recover from certain errors by mapping them to an A
value.
- See also:
handleError to handle any/all errors.
recoverWith to recover from certain errors by mapping them to
F[A]
values.- Inherited from:
- ApplicativeError
Recover from certain errors by mapping them to an F[A]
value.
Recover from certain errors by mapping them to an F[A]
value.
- See also:
handleErrorWith to handle any/all errors.
recover to recover from certain errors by mapping them to
A
values.- Inherited from:
- ApplicativeError
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.
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.
- Value parameters:
- fa
is the source whose result is going to get transformed
- recover
is the function that gets called to recover the source in case of error
- See also:
MonadError.redeemWith, attempt and handleError
- Inherited from:
- ApplicativeError
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.
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.
- Value parameters:
- bind
is the function that gets to transform the source in case of success
- fa
is the source whose result is going to get transformed
- recover
is the function that gets called to recover the source in case of error
- See also:
redeem, attempt and handleErrorWith
- Inherited from:
- MonadError
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))
- Inherited from:
- Applicative
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)
- Inherited from:
- MonadError
Start a new fiber on a different execution context.
Start a new fiber on a different execution context.
See GenSpawn.start for more details.
- Inherited from:
- Async
Returns an effect that completes with the result of the source together with the duration that it took to complete.
Returns an effect that completes with the result of the source together with the duration that it took to complete.
- Value parameters:
- fa
The effect which we wish to time the execution of
- Inherited from:
- Clock
Returns an effect that either completes with the result of the source within the specified
time duration
or otherwise raises a TimeoutException
.
Returns an effect that either completes with the result of the source within the specified
time duration
or otherwise raises a TimeoutException
.
The source is canceled in the event that it takes longer than the specified time duration
to complete. Once the source has been successfully canceled (and has completed its
finalizers), the TimeoutException
will be raised. If the source is uncancelable, the
resulting effect will wait for it to complete before raising the exception.
- Value parameters:
- duration
The time span for which we wait for the source to complete; in the event that the specified time has passed without the source completing, a
TimeoutException
is raised
- Inherited from:
- GenTemporal
Returns an effect that either completes with the result of the source within the specified
time duration
or otherwise raises a TimeoutException
.
Returns an effect that either completes with the result of the source within the specified
time duration
or otherwise raises a TimeoutException
.
The source is canceled in the event that it takes longer than the specified time duration to complete. Unlike timeout, the cancelation of the source will be ''requested'' but not awaited, and the exception will be raised immediately upon the completion of the timer. This may more closely match intuitions about timeouts, but it also violates backpressure guarantees and intentionally leaks fibers.
This combinator should be applied very carefully.
- Value parameters:
- duration
The time span for which we wait for the source to complete; in the event that the specified time has passed without the source completing, a
TimeoutException
is raised
- See also:
timeout for a variant which respects backpressure and does not leak fibers
- Inherited from:
- GenTemporal
Returns an effect that either completes with the result of the source within the specified
time duration
or otherwise evaluates the fallback
.
Returns an effect that either completes with the result of the source within the specified
time duration
or otherwise evaluates the fallback
.
The source is canceled in the event that it takes longer than the specified time duration to complete. Once the source has been successfully canceled (and has completed its finalizers), the fallback will be sequenced. If the source is uncancelable, the resulting effect will wait for it to complete before evaluating the fallback.
- Value parameters:
- duration
The time span for which we wait for the source to complete; in the event that the specified time has passed without the source completing, the
fallback
gets evaluated- fallback
The task evaluated after the duration has passed and the source canceled
- Inherited from:
- GenTemporal
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
- Inherited from:
- ApplyArityFunctions
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.
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))
- Inherited from:
- Functor
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.
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))
- Inherited from:
- Functor
Yields a value that is guaranteed to be unique ie (F.unique, F.unique).mapN(_ =!= _)
Yields a value that is guaranteed to be unique ie (F.unique, F.unique).mapN(_ =!= _)
- Inherited from:
- Sync
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(())
- Inherited from:
- Applicative
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()
- Inherited from:
- Applicative
This repeats an F until we get defined values. This can be useful for polling type operations on State (or RNG) Monads, or in effect monads.
This repeats an F until we get defined values. This can be useful for polling type operations on State (or RNG) Monads, or in effect monads.
- Inherited from:
- FlatMap
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
.
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
.
- Inherited from:
- Monad
Execute an action repeatedly until the Boolean
condition returns true
.
The condition is evaluated after the loop body. Discards results.
Execute an action repeatedly until the Boolean
condition returns true
.
The condition is evaluated after the loop body. Discards results.
- Inherited from:
- Monad
Un-zips an F[(A, B)]
consisting of element pairs or Tuple2 into two separate F's tupled.
Un-zips an F[(A, B)]
consisting of element pairs or Tuple2 into two separate F's tupled.
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))
- Inherited from:
- Functor
Empty the fa of the values, preserving the structure
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((), (), ())
- Inherited from:
- Functor
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(())
- Inherited from:
- Applicative
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
. 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
.
- Inherited from:
- Monad
Execute an action repeatedly as long as the given Boolean
expression
returns true
. The condition is evaluated before the loop body.
Discards results.
Execute an action repeatedly as long as the given Boolean
expression
returns true
. The condition is evaluated before the loop body.
Discards results.
- Inherited from:
- Monad
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
.
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)
- Inherited from:
- Functor