LanguageExt.Core

LanguageExt.Core Traits Choice

Choice<F> allows for propagation of 'failure' and 'choice' (in some appropriate sense, depending on the type).

Choice is a SemigroupK, but has a Choose method, rather than relying on the SemigroupK.Combine method, (which now has a default implementation of invoking Choose). That creates a new semantic meaning for Choose, which is about choice propagation rather than the broader meaning of Combine. It also allows for Choose and Combine to have separate implementations depending on the type.

The way to think about Choose and the inherited SemigroupK.Combine methods is:

Any type that supports the Choice trait should also implement the | operator, to enable easy choice/failure propagation. If there is a different implementation of Combine (rather than accepting the default), then the type should also implement the + operator.

ChoiceLaw can help you test your implementation:

choose(Pure(a),   Pure(b))  = Pure(a)
choose(Fail,      Pure(b))  = Pure(b)
choose(Pure(a),   Fail)     = Pure(a)
choose(Fail [1],  Fail [2]) = Fail [2]

It also tests the Applicative and Functor laws.

Contents

class ChoiceExtensions Source #

A semigroup on applicative functors

Methods

method K<F, A> Choose <F, A> (this K<F, A> fa, K<F, A> fb) Source #

where F : Choice<F>

Where F defines some notion of failure or choice, this function picks the first argument that succeeds. So, if fa succeeds, then fa is returned; if it fails, then fb is returned.

Parameters

type F

Alternative structure type

type A

Bound value type

param fa

First structure to test

param fb

Second structure to return if the first one fails

returns

First argument to succeed

method K<F, Seq<A>> Some <F, A> (this K<F, A> v) Source #

where F : Choice<F>

One or more...

Run the applicative functor repeatedly, collecting the results, until failure.

Will always succeed if at least one item has been yielded.

Parameters

param v

Applicative functor

returns

One or more values

method K<F, Seq<A>> Many <F, A> (this K<F, A> v) Source #

where F : Choice<F>

Zero or more...

Run the applicative functor repeatedly, collecting the results, until failure.

Will always succeed.

Parameters

param v

Applicative functor

returns

Zero or more values

class ChoiceLaw <F> Source #

where F : Choice<F>

Functions that test that Alternative laws hold for the F Alternative provided.

NOTE: Equals must be implemented for the K<F, *> derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

Parameters

type F

Alternative type

Methods

method Unit assert (K<F, int> failure, Func<K<F, int>, K<F, int>, bool>? equals = null) Source #

Assert that the Alternative laws hold

NOTE: Equals must be implemented for the K<F, *> derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

method Validation<Error, Unit> validate (K<F, int> failure, Func<K<F, int>, K<F, int>, bool>? equals = null) Source #

Validate that the Alternative laws hold

NOTE: Equals must be implemented for the K<F, *> derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

method Validation<Error, Unit> leftZeroLaw (K<F, int> failure, Func<K<F, int>, K<F, int>, bool> equals) Source #

Left-zero law

choose(empty, pure(x)) = pure(x)

NOTE: Equals must be implemented for the K<F, *> derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

method Validation<Error, Unit> rightZeroLaw (K<F, int> failure, Func<K<F, int>, K<F, int>, bool> equals) Source #

Right-zero law

choose(pure(x), empty) = pure(x)

NOTE: Equals must be implemented for the K<F, *> derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

method Validation<Error, Unit> leftCatchLaw (Func<K<F, int>, K<F, int>, bool> equals) Source #

Left catch law

choose(pure(x), pure(y)) = pure(x)

NOTE: Equals must be implemented for the K<F, *> derived-type, so that the laws can be proven to be true. If your Alternative structure doesn't have Equals then you must provide the optional equals parameter so that the equality of outcomes can be tested.

class Choice Source #

Methods

method K<F, A> choose <F, A> (K<F, A> fa, K<F, A> fb) Source #

where F : Choice<F>

Where F defines some notion of failure or choice, this function picks the first argument that succeeds. So, if fa succeeds, then fa is returned; if it fails, then fb is returned.

Parameters

type F

Alternative structure type

type A

Bound value type

param fa

First structure to test

param fb

Second structure to return if the first one fails

returns

First argument to succeed

method K<F, Seq<A>> some <F, A> (K<F, A> fa) Source #

where F : Choice<F>, Applicative<F>

One or more...

Run the applicative functor repeatedly, collecting the results, until failure.

Will always succeed if at least one item has been yielded.

NOTE: It is important that the F applicative-type overrides Apply (the one with Func laziness) in its trait-implementations otherwise this will likely result in a stack-overflow.

Parameters

param fa

Applicative functor

returns

One or more values

method K<F, Seq<A>> many <F, A> (K<F, A> fa) Source #

where F : Choice<F>, Applicative<F>

Zero or more...

Run the applicative functor repeatedly, collecting the results, until failure. Will always succeed.

NOTE: It is important that the F applicative-type overrides ApplyLazy in its trait-implementations otherwise this will likely result in a stack-overflow.

Parameters

param fa

Applicative functor

returns

Zero or more values

class Prelude Source #

Methods

method K<F, A> choose <F, A> (K<F, A> fa, K<F, A> fb) Source #

where F : Choice<F>

Where F defines some notion of failure or choice, this function picks the first argument that succeeds. So, if fa succeeds, then fa is returned; if it fails, then fb is returned.

Parameters

type F

Alternative structure type

type A

Bound value type

param fa

First structure to test

param fb

Second structure to return if the first one fails

returns

First argument to succeed

method K<F, Seq<A>> some <F, A> (K<F, A> fa) Source #

where F : Choice<F>, Applicative<F>

One or more...

Run the applicative functor repeatedly, collecting the results, until failure.

Will always succeed if at least one item has been yielded.

NOTE: It is important that the F applicative-type overrides Apply (the one with Func laziness) in its trait-implementations otherwise this will likely result in a stack-overflow.

Parameters

param fa

Applicative functor

returns

One or more values

method K<F, Seq<A>> many <F, A> (K<F, A> fa) Source #

where F : Choice<F>, Applicative<F>

Zero or more...

Run the applicative functor repeatedly, collecting the results, until failure. Will always succeed.

NOTE: It is important that the F applicative-type overrides ApplyLazy in its trait-implementations otherwise this will likely result in a stack-overflow.

Parameters

param fa

Applicative functor

returns

Zero or more values

interface Choice <F> Source #

where F : Choice<F>

A semigroup on applicative functors

Parameters

type F