Bracket

An extension of MonadError exposing the bracket operation,
a generalized abstracted pattern of safe resource acquisition and
release in the face of errors or interruption.

Companion: object

trait MonadError[F, E]

trait Monad[F]

trait FlatMap[F]

trait ApplicativeError[F, E]

trait Applicative[F]

trait InvariantMonoidal[F]

trait Apply[F]

trait ApplyArityFunctions[F]

trait InvariantSemigroupal[F]

trait Semigroupal[F]

trait Functor[F]

trait Invariant[F]

trait Serializable

class Object

trait Matchable

class Any

trait Async[F]

trait Concurrent[F]

trait ConcurrentEffect[F]

trait Effect[F]

trait Sync[F]

trait SyncEffect[F]

Document{}

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Inhertied from: ApplyArityFunctions

Value members

Methods

Implicitly added by catsKleisliBracket

A generalized version of bracket which uses ExitCase
to distinguish between different exit cases when releasing
the acquired resource.

Value Params

acquire: is an action that "acquires" some expensive
resource, that needs to be used and then discarded
release: is the action that's supposed to release the
allocated resource after use is done, by observing
and acting on its exit condition. Throwing inside
this function leads to undefined behavior since it's
left to the implementation.
use: is the action that uses the newly allocated
resource and that will provide the final result

Implicitly added by catsKleisliBracket

Operation meant for specifying tasks with safe resource
acquisition and release in the face of errors and interruption.

This operation provides the equivalent of try/catch/finally
statements in mainstream imperative languages for resource
acquisition and release.

Value Params

acquire: is an action that "acquires" some expensive
resource, that needs to be used and then discarded
release: is the action that's supposed to release the
allocated resource after use is done, regardless of
its exit condition. Throwing inside this function
is undefined behavior since it's left to the implementation.
use: is the action that uses the newly allocated
resource and that will provide the final result

Implicitly added by catsKleisliBracket

Operation meant for ensuring a given task continues execution even
when interrupted.

Implicitly added by catsKleisliBracket

Executes the given finalizer when the source is finished,
either in success or in error, or if canceled.

This variant of guaranteeCase evaluates the given finalizer
regardless of how the source gets terminated:

normal completion
completion in error
cancelation

This equivalence always holds:

{{{
F.guarantee(fa)(f) <-> F.bracket(F.unit)(_ => fa)(_ => f)
}}}

As best practice, it's not a good idea to release resources
via guaranteeCase in polymorphic code. Prefer bracket
for the acquisition and release of resources.

See also: guaranteeCase for the version that can discriminate
between termination conditions

bracket for the more general operation

Implicitly added by catsKleisliBracket

Executes the given finalizer when the source is finished,
either in success or in error, or if canceled, allowing
for differentiating between exit conditions.

This variant of guarantee injects an ExitCase in
the provided function, allowing one to make a difference
between:

normal completion
completion in error
cancelation

This equivalence always holds:

{{{
F.guaranteeCase(fa)(f) <-> F.bracketCase(F.unit)(_ => fa)((_, e) => f(e))
}}}

As best practice, it's not a good idea to release resources
via guaranteeCase in polymorphic code. Prefer bracketCase
for the acquisition and release of resources.

See also: guarantee for the simpler version

bracketCase for the more general operation

Implicitly added by catsKleisliBracket

Executes the given finalizer when the source is canceled.

The typical use case for this function arises in the
implementation of concurrent abstractions, which generally
consist of operations that perform asynchronous waiting after
concurrently modifying some state: in case the user asks for
cancelation, we want to interrupt the waiting operation, and
restore the state to its previous value.

{{{
waitingOp.onCancel(restoreState)
}}}

A direct use of bracket is not a good fit for this case as it
would make the waiting action uncancelable.

NOTE: This function handles interruption only, you need to take
care of the success and error case elsewhere in your code

See also: guaranteeCase for the version that can discriminate
between termination conditions

bracket for the more general operation

Concurrent.continual when you have a use case similar to
the cancel/restore example above, but require access to the
result of F[A]

A generalized version of bracket which uses ExitCase
to distinguish between different exit cases when releasing
the acquired resource.

Value Params

acquire: is an action that "acquires" some expensive
resource, that needs to be used and then discarded
release: is the action that's supposed to release the
allocated resource after use is done, by observing
and acting on its exit condition. Throwing inside
this function leads to undefined behavior since it's
left to the implementation.
use: is the action that uses the newly allocated
resource and that will provide the final result

Operation meant for specifying tasks with safe resource
acquisition and release in the face of errors and interruption.

This operation provides the equivalent of try/catch/finally
statements in mainstream imperative languages for resource
acquisition and release.

Value Params

acquire: is an action that "acquires" some expensive
resource, that needs to be used and then discarded
release: is the action that's supposed to release the
allocated resource after use is done, regardless of
its exit condition. Throwing inside this function
is undefined behavior since it's left to the implementation.
use: is the action that uses the newly allocated
resource and that will provide the final result

Operation meant for ensuring a given task continues execution even
when interrupted.

Executes the given finalizer when the source is finished,
either in success or in error, or if canceled.

This variant of guaranteeCase evaluates the given finalizer
regardless of how the source gets terminated:

normal completion
completion in error
cancelation

This equivalence always holds:

{{{
F.guarantee(fa)(f) <-> F.bracket(F.unit)(_ => fa)(_ => f)
}}}

As best practice, it's not a good idea to release resources
via guaranteeCase in polymorphic code. Prefer bracket
for the acquisition and release of resources.

See also: guaranteeCase for the version that can discriminate
between termination conditions

bracket for the more general operation

Executes the given finalizer when the source is finished,
either in success or in error, or if canceled, allowing
for differentiating between exit conditions.

This variant of guarantee injects an ExitCase in
the provided function, allowing one to make a difference
between:

normal completion
completion in error
cancelation

This equivalence always holds:

{{{
F.guaranteeCase(fa)(f) <-> F.bracketCase(F.unit)(_ => fa)((_, e) => f(e))
}}}

As best practice, it's not a good idea to release resources
via guaranteeCase in polymorphic code. Prefer bracketCase
for the acquisition and release of resources.

See also: guarantee for the simpler version

bracketCase for the more general operation

Executes the given finalizer when the source is canceled.

{{{
waitingOp.onCancel(restoreState)
}}}

A direct use of bracket is not a good fit for this case as it
would make the waiting action uncancelable.

NOTE: This function handles interruption only, you need to take
care of the success and error case elsewhere in your code

See also: guaranteeCase for the version that can discriminate
between termination conditions

bracket for the more general operation

Concurrent.continual when you have a use case similar to
the cancel/restore example above, but require access to the
result of F[A]

Inherited methods

Implicitly added by catsKleisliBracket

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.

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: Invariant

@inline

Implicitly added by catsKleisliBracket

Alias for productL.

Inhertied from: Apply

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

@noop

Implicitly added by catsKleisliBracket

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.

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

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.
Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

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 Params

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

Inhertied from

ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

@noop

Implicitly added by catsKleisliBracket

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.

Inhertied from: Monad

Implicitly added by catsKleisliBracket

Inhertied from: InvariantSemigroupal

Implicitly added by catsKleisliBracket

If the error type is Throwable, we can convert from a scala.util.Try

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

Implicitly added by catsKleisliBracket

Execute an action repeatedly until the Boolean condition returns true.
The condition is evaluated after the loop body. Discards results.

Inhertied from: Monad

Implicitly added by catsKleisliBracket

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

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

point lifts any value into a Monoidal Functor.

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

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

Inhertied from: InvariantMonoidal

Implicitly added by catsKleisliBracket

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

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

@noop

Implicitly added by catsKleisliBracket

An if-then-else lifted into the F context.
This function combines the effects of the fcond condition and of the two branches,
in the order in which they are given.

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

}}}

Inhertied from: Apply

@noop

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

Implicitly added by catsKleisliBracket

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

Inhertied from: Applicative

Implicitly added by catsKleisliBracket

Turns a successful value into an error specified by the error function if it does not satisfy a given predicate.

Inhertied from: MonadError

Implicitly added by catsKleisliBracket

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

Inhertied from: MonadError

Implicitly added by catsKleisliBracket

Execute an action repeatedly until its result fails to satisfy the given predicate
and return that result, discarding all others.

Inhertied from: Monad

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: Applicative

Implicitly added by catsKleisliBracket

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

Inhertied from: Invariant

Implicitly added by catsKleisliBracket

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

Inhertied from: Apply

Implicitly added by catsKleisliBracket

Inhertied from: Functor

Implicitly added by catsKleisliBracket

Turns a successful value into an error if it does not satisfy a given predicate.

Inhertied from: MonadError

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

Implicitly added by catsKleisliBracket

Execute an action repeatedly until its result satisfies the given predicate
and return that result, discarding all others.

Inhertied from: Monad

@noop

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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.
Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

Implicitly added by catsKleisliBracket

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

See also: handleErrorWith to map to an F[A] value instead of simply an
A value.

recover to only recover from certain errors.
Inhertied from: ApplicativeError

@noop

Implicitly added by catsKleisliBracket

if lifted into monad.

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

@noop

Implicitly added by catsKleisliBracket

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.
Inhertied from: Monad

@noop

Implicitly added by catsKleisliBracket

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.

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

Apply a monadic function iteratively until its result satisfies
the given predicate and return that result.

Inhertied from: Monad

Implicitly added by catsKleisliBracket

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

Inhertied from: Applicative

Implicitly added by catsKleisliBracket

pure lifts any value into the Applicative Functor.

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

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

Inhertied from: Applicative

Implicitly added by catsKleisliBracket

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

Inhertied from: Applicative

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

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

Inhertied from: Applicative

Implicitly added by catsKleisliBracket

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

Inhertied from: Apply

Implicitly added by catsKleisliBracket

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.

Inhertied from: Monad

Implicitly added by catsKleisliBracket

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

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

@noop

Implicitly added by catsKleisliBracket

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.

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

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

Inhertied from: MonadError

Implicitly added by catsKleisliBracket

Apply a monadic function iteratively until its result fails
to satisfy the given predicate and return that result.

Inhertied from: Monad

@noop

Implicitly added by catsKleisliBracket

Execute an action repeatedly as long as the given Boolean expression
returns true. The condition is evaluated before the loop body.
Discards results.

Inhertied from: Monad

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

Implicitly added by catsKleisliBracket

Inhertied from: ApplyArityFunctions

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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 Params

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

Inhertied from

MonadError

Implicitly added by catsKleisliBracket

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

Inhertied from: Functor

@inline

Implicitly added by catsKleisliBracket

Alias for productR.

Inhertied from: Apply

Implicitly added by catsKleisliBracket

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

See also: handleError to handle any error by simply mapping it to an A
value instead of an F[A].

recoverWith to recover from only certain errors.
Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: ApplicativeError

Implicitly added by catsKleisliBracket

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

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

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.

Inhertied from: FlatMap

Implicitly added by catsKleisliBracket

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

Inhertied from: Applicative

@inline

Implicitly added by catsKleisliBracket

Alias for ap.

Inhertied from: Apply

Definition Classes: Functor -> Invariant
Inhertied from: Functor

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.

Inhertied from: ApplicativeError

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._

Inhertied from: Invariant

@inline

Alias for productL.

Inhertied from: Apply

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

Inhertied from: Functor

@noop

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.

Inhertied from: FlatMap

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.
Inhertied from: ApplicativeError

Definition Classes: FlatMap -> Apply
Inhertied from: FlatMap

Inhertied from: FlatMap

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 Params

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

Inhertied from

ApplicativeError

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

Inhertied from: Functor

@noop

Inhertied from: Monad

Inhertied from: InvariantSemigroupal

If the error type is Throwable, we can convert from a scala.util.Try

Inhertied from: ApplicativeError

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

Inhertied from: Functor

Execute an action repeatedly until the Boolean condition returns true.
The condition is evaluated after the loop body. Discards results.

Inhertied from: Monad

Definition Classes: MonadError -> ApplicativeError
Inhertied from: MonadError

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

Inhertied from: FlatMap

point lifts any value into a Monoidal Functor.

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

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

Inhertied from: InvariantMonoidal

Definition Classes: Monad -> Applicative -> Functor
Inhertied from: Monad

Inhertied from: FlatMap

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

Inhertied from: ApplicativeError

@noop

An if-then-else lifted into the F context.
This function combines the effects of the fcond condition and of the two branches,
in the order in which they are given.

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

}}}

Inhertied from: Apply

@noop

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

Inhertied from: Functor

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

Inhertied from: Applicative

Turns a successful value into an error specified by the error function if it does not satisfy a given predicate.

Inhertied from: MonadError

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

Inhertied from: MonadError

Execute an action repeatedly until its result fails to satisfy the given predicate
and return that result, discarding all others.

Inhertied from: Monad

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

Inhertied from: Functor

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

Inhertied from: ApplicativeError

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

Inhertied from: ApplicativeError

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

Inhertied from: ApplicativeError

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

Inhertied from: Applicative

Compose Invariant F[_] and G[_] then produce Invariant[F[G[_]]] using their imap.

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

Inhertied from: Invariant

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

Inhertied from: Apply

Inhertied from: Functor

Turns a successful value into an error if it does not satisfy a given predicate.

Inhertied from: MonadError

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

Inhertied from: Functor

Definition Classes: FlatMap -> Apply
Inhertied from: FlatMap

Execute an action repeatedly until its result satisfies the given predicate
and return that result, discarding all others.

Inhertied from: Monad

@noop

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

Inhertied from: Functor

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

Inhertied from: ApplicativeError

Definition Classes: FlatMap -> Apply
Inhertied from: FlatMap

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.
Inhertied from: ApplicativeError

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

Inhertied from: Functor

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

See also: handleErrorWith to map to an F[A] value instead of simply an
A value.

recover to only recover from certain errors.
Inhertied from: ApplicativeError

@noop

if lifted into monad.

Inhertied from: FlatMap

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

Inhertied from: Functor

@noop

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.
Inhertied from: Monad

@noop

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.

Inhertied from: FlatMap

Definition Classes: Functor -> Invariant
Inhertied from: Functor

Apply a monadic function iteratively until its result satisfies
the given predicate and return that result.

Inhertied from: Monad

Definition Classes: FlatMap -> Apply
Inhertied from: FlatMap

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

Inhertied from: Applicative

pure lifts any value into the Applicative Functor.

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

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

Inhertied from: Applicative

Given fa and n, apply fa n times to construct an F[List[A]] value.

Example:
{{{
scala> import cats.data.State

Inhertied from: Applicative

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

Inhertied from: ApplicativeError

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

Inhertied from: FlatMap

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

Inhertied from: Applicative

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.

Inhertied from: Apply

Inhertied from: Monad

Apply a monadic function and discard the result while keeping the effect.

Inhertied from: FlatMap

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

Inhertied from: ApplicativeError

@noop

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] .

Inhertied from: FlatMap

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

Inhertied from: MonadError

Apply a monadic function iteratively until its result fails
to satisfy the given predicate and return that result.

Inhertied from: Monad

@noop

Execute an action repeatedly as long as the given Boolean expression
returns true. The condition is evaluated before the loop body.
Discards results.

Inhertied from: Monad

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

Inhertied from: Functor

Inhertied from: ApplyArityFunctions

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

Inhertied 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.

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 Params

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

Inhertied from

MonadError

Definition Classes: FlatMap -> Apply -> Semigroupal
Inhertied from: FlatMap

Lifts natural subtyping covariance of covariant Functors.

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

Inhertied from: Functor

@inline

Alias for productR.

Inhertied from: Apply

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

See also: handleError to handle any error by simply mapping it to an A
value instead of an F[A].

recoverWith to recover from only certain errors.
Inhertied from: ApplicativeError

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

Inhertied from: ApplicativeError

Lift an error into the F context.

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

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

Inhertied from: ApplicativeError

Inhertied from: FlatMap

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.

Inhertied from: FlatMap

Definition Classes: FlatMap -> Apply
Inhertied from: FlatMap