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:
Choose
is the failure/choice propagation operator:|
Combine
is the concatenation/combination/addition operator:+
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.
- ChoiceExtensions
- Choose <F, A> (this K<F, A> fa, K<F, A> fb)
- Some <F, A> (this K<F, A> v)
- Many <F, A> (this K<F, A> v)
- ChoiceLaw <F>
- assert (K<F, int> failure, Func<K<F, int>, K<F, int>, bool>? equals = null)
- validate (K<F, int> failure, Func<K<F, int>, K<F, int>, bool>? equals = null)
- leftZeroLaw (K<F, int> failure, Func<K<F, int>, K<F, int>, bool> equals)
- rightZeroLaw (K<F, int> failure, Func<K<F, int>, K<F, int>, bool> equals)
- leftCatchLaw (Func<K<F, int>, K<F, int>, bool> equals)
- Choice
- Prelude
- Choice <F>
class ChoiceExtensions Source #
A semigroup on applicative functors
method K<F, A> Choose <F, A> (this K<F, A> fa, K<F, A> fb) Source #
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.
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 |
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.
type | F | Alternative type |
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.
method K<F, A> choose <F, A> (K<F, A> fa, K<F, A> fb) Source #
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.
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 #
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.
param | fa | Applicative functor |
returns | One or more values |
method K<F, Seq<A>> many <F, A> (K<F, A> fa) Source #
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.
param | fa | Applicative functor |
returns | Zero or more values |
method K<F, A> choose <F, A> (K<F, A> fa, K<F, A> fb) Source #
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.
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 #
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.
param | fa | Applicative functor |
returns | One or more values |
method K<F, Seq<A>> many <F, A> (K<F, A> fa) Source #
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.
param | fa | Applicative functor |
returns | Zero or more values |