arrow-core-data / arrow.core / Eval

Eval

sealed class Eval<out A> : EvalOf<A>

Eval is a monad which controls evaluation of a value or a computation that produces a value.

Three basic evaluation strategies:

  • Now: evaluated immediately
  • Later: evaluated once when value is needed
  • Always: evaluated every time value is needed

The Later and Always are both lazy strategies while Now is eager. Later and Always are distinguished from each other only by memoization: once evaluated Later will save the value to be returned immediately if it is needed again. Always will run its computation every time.

methods, which use an internal trampoline to avoid stack overflows. Computation done within .map and .flatMap is always done lazily, even when applied to a Now instance.

It is not generally good style to pattern-match on Eval instances. Rather, use .map and .flatMap to chain computation, and use .value to get the result when needed. It is also not good style to create Eval instances whose computation involves calling .value on another Eval instance – this can defeat the trampolining and lead to stack overflows.

Example of stack safety:

import arrow.core.Eval

//sampleStart
fun even(n: Int): Eval<Boolean> =
  Eval.always { n == 0 }.flatMap {
    if(it == true) Eval.now(true)
    else odd(n - 1)
  }

fun odd(n: Int): Eval<Boolean> =
  Eval.always { n == 0 }.flatMap {
    if(it == true) Eval.now(false)
    else even(n - 1)
  }

// if not wrapped in eval this type of computation would blow the stack and result in a StackOverflowError
fun main() {
  println(odd(100000).value())
}
//sampleEnd

Types

Always Construct a lazy Eval instance.data class Always<out A> : Eval<A>
Defer Defer is a type of Eval that is used to defer computations which produce Eval.data class Defer<out A> : Eval<A>
FlatMap FlatMap is a type of Eval that is used to chain computations involving .map and .flatMap. Along with Eval#flatMap. It implements the trampoline that guarantees stack-safety.abstract class FlatMap<out A> : Eval<A>
Later Construct a lazy Eval instance.data class Later<out A> : Eval<A>
Now Construct an eager Eval instance. In some sense it is equivalent to using a val.data class Now<out A> : Eval<A>

Functions

ap fun <B> ~~ap~~(ff: EvalOf<(A) -> B>): Eval<B>
coflatMap fun <B> ~~coflatMap~~(f: (EvalOf<A>) -> B): Eval<B>
fun <B> coflatMap(f: (Eval<A>) -> B): Eval<B>
extract fun ~~extract~~(): A
flatMap fun <B> ~~flatMap~~(f: (A) -> EvalOf<B>): Eval<B>
fun <B> flatMap(f: (A) -> Eval<B>): Eval<B>
map fun <B> map(f: (A) -> B): Eval<B>
memoize abstract fun memoize(): Eval<A>
toString open fun toString(): String
value abstract fun value(): A

Companion Object Properties

False val ~~False~~: Eval<Boolean>
One val ~~One~~: Eval<Int>
True val ~~True~~: Eval<Boolean>
Unit val ~~Unit~~: Eval<Unit>
Zero val ~~Zero~~: Eval<Int>

Companion Object Functions

always Creates an Eval instance from a function deferring it’s evaluation until .value() is invoked recomputing each time .value() is invoked.fun <A> always(f: () -> A): Always<A>
defer fun <A> defer(f: () -> Eval<A>): Eval<A>
just fun <A> ~~just~~(a: A): Eval<A>
later Creates an Eval instance from a function deferring it’s evaluation until .value() is invoked memoizing the computed value.fun <A> later(f: () -> A): Later<A>
now Creates an Eval instance from an already constructed value but still defers evaluation when chaining expressions with map and flatMapfun <A> now(a: A): Eval<A>
raise fun raise(t: Throwable): Eval<Nothing>
tailRecM fun <A, B> ~~tailRecM~~(a: A, f: (A) -> EvalOf<Either<A, B>>): Eval<B>

Extension Functions

altFold fun <T, F, A> Kind<T, A>.altFold(AF: Alternative<F>, FT: Foldable<T>): Kind<F, A>
altSum fun <T, F, A> Kind<T, Kind<F, A>>.altSum(AF: Alternative<F>, FT: Foldable<T>): Kind<F, A>
fix fun <A> EvalOf<A>.~~fix~~(): Eval<A>
replicate fun <A> Eval<A>.replicate(n: Int): Eval<List<A>>
fun <A> Eval<A>.replicate(n: Int, MA: Monoid<A>): Eval<A>
value fun <A> EvalOf<A>.~~value~~(): A
zip fun <A, B, Z> Eval<A>.zip(b: Eval<B>, map: (A, B) -> Z): Eval<Z>
fun <A, B> Eval<A>.zip(b: Eval<B>): Eval<Pair<A, B>>
fun <A, B, C, D> Eval<A>.zip(b: Eval<B>, c: Eval<C>, map: (A, B, C) -> D): Eval<D>
fun <A, B, C, D, E> Eval<A>.zip(b: Eval<B>, c: Eval<C>, d: Eval<D>, map: (A, B, C, D) -> E): Eval<E>
fun <A, B, C, D, E, F> Eval<A>.zip(b: Eval<B>, c: Eval<C>, d: Eval<D>, e: Eval<E>, map: (A, B, C, D, E) -> F): Eval<F>
fun <A, B, C, D, E, F, G> Eval<A>.zip(b: Eval<B>, c: Eval<C>, d: Eval<D>, e: Eval<E>, f: Eval<F>, map: (A, B, C, D, E, F) -> G): Eval<G>
fun <A, B, C, D, E, F, G, H> Eval<A>.zip(b: Eval<B>, c: Eval<C>, d: Eval<D>, e: Eval<E>, f: Eval<F>, g: Eval<G>, map: (A, B, C, D, E, F, G) -> H): Eval<H>
fun <A, B, C, D, E, F, G, H, I> Eval<A>.zip(b: Eval<B>, c: Eval<C>, d: Eval<D>, e: Eval<E>, f: Eval<F>, g: Eval<G>, h: Eval<H>, map: (A, B, C, D, E, F, G, H) -> I): Eval<I>
fun <A, B, C, D, E, F, G, H, I, J> Eval<A>.zip(b: Eval<B>, c: Eval<C>, d: Eval<D>, e: Eval<E>, f: Eval<F>, g: Eval<G>, h: Eval<H>, i: Eval<I>, map: (A, B, C, D, E, F, G, H, I) -> J): Eval<J>
fun <A, B, C, D, E, F, G, H, I, J, K> Eval<A>.zip(b: Eval<B>, c: Eval<C>, d: Eval<D>, e: Eval<E>, f: Eval<F>, g: Eval<G>, h: Eval<H>, i: Eval<I>, j: Eval<J>, map: (A, B, C, D, E, F, G, H, I, J) -> K): Eval<K>

Do you like Arrow?

Arrow Org
<