Class Choice2<A,B>

java.lang.Object
com.jnape.palatable.lambda.adt.choice.Choice2<A,B>
Type Parameters:
A - the first possible type
B - the second possible type
All Implemented Interfaces:
CoProduct2<A,B,Choice2<A,B>>, Applicative<B,Choice2<A,?>>, Bifunctor<A,B,Choice2<?,?>>, BoundedBifunctor<A,B,Object,Object,Choice2<?,?>>, Functor<B,Choice2<A,?>>, Monad<B,Choice2<A,?>>, MonadRec<B,Choice2<A,?>>, Traversable<B,Choice2<A,?>>
Direct Known Subclasses:
Choice2._A, Choice2._B

public abstract class Choice2<A,B> extends Object implements CoProduct2<A,B,Choice2<A,B>>, MonadRec<B,Choice2<A,?>>, Bifunctor<A,B,Choice2<?,?>>, Traversable<B,Choice2<A,?>>
Canonical ADT representation of CoProduct2. Unlike Either, there is no concept of "success" or "failure", so the domain of reasonable function semantics is more limited.
See Also:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private static final class 
     
    private static final class 
     
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
     
  • Method Summary

    Modifier and Type
    Method
    Description
    static <A, B> Choice2<A,B>
    a(A a)
    Static factory method for wrapping a value of type A in a Choice2.
    static <A, B> Choice2<A,B>
    b(B b)
    Static factory method for wrapping a value of type B in a Choice2.
    final <C, D> Choice2<C,D>
    biMap(Fn1<? super A,? extends C> lFn, Fn1<? super B,? extends D> rFn)
    Dually map covariantly over both the left and right parameters.
    final <C> Choice2<C,B>
    biMapL(Fn1<? super A,? extends C> fn)
    Covariantly map over the left parameter.
    final <C> Choice2<A,C>
    biMapR(Fn1<? super B,? extends C> fn)
    Covariantly map over the right parameter.
    <C> Choice2<A,C>
    Sequence both this Applicative and appB, discarding this Applicative's result and returning appB.
    <C> Choice2<A,B>
    Sequence both this Applicative and appB, discarding appB's result and returning this Applicative.
    final <C> Choice3<A,B,C>
    Diverge this coproduct by introducing another possible type that it could represent.
    final <C> Choice2<A,C>
    flatMap(Fn1<? super B,? extends Monad<C,Choice2<A,?>>> f)
    Chain dependent computations that may continue or short-circuit based on previous results.
    final <C> Choice2<A,C>
    fmap(Fn1<? super B,? extends C> fn)
    Covariantly transmute this functor's parameter using the given mapping function.
    Swap the type parameters.
    <C> Lazy<Choice2<A,C>>
    lazyZip(Lazy<? extends Applicative<Fn1<? super B,? extends C>,Choice2<A,?>>> lazyAppFn)
    Given a lazy instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
    Specialize this choice's projection to a Tuple2.
    <C> Choice2<A,C>
    pure(C c)
    Lift the value b into this applicative functor.
    static <A> Pure<Choice2<A,?>>
    The canonical Pure instance for Choice2.
    <C> Choice2<A,C>
    trampolineM(Fn1<? super B,? extends MonadRec<RecursiveResult<B,C>,Choice2<A,?>>> fn)
    Given some operation yielding a RecursiveResult inside this MonadRec, internally trampoline the operation until it yields a termination instruction.
    <C, App extends Applicative<?, App>, TravB extends Traversable<C, Choice2<A, ?>>, AppTrav extends Applicative<TravB, App>>
    AppTrav
    traverse(Fn1<? super B,? extends Applicative<C,App>> fn, Fn1<? super TravB,? extends AppTrav> pure)
    Apply fn to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.
    <C> Choice2<A,C>
    zip(Applicative<Fn1<? super B,? extends C>,Choice2<A,?>> appFn)
    Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface com.jnape.palatable.lambda.adt.coproduct.CoProduct2

    embed, match, projectA, projectB

    Methods inherited from interface com.jnape.palatable.lambda.functor.Functor

    coerce
  • Constructor Details

    • Choice2

      private Choice2()
  • Method Details

    • project

      public Tuple2<Maybe<A>,Maybe<B>> project()
      Specialize this choice's projection to a Tuple2.
      Specified by:
      project in interface CoProduct2<A,B,Choice2<A,B>>
      Returns:
      a Tuple2
    • diverge

      public final <C> Choice3<A,B,C> diverge()
      Diverge this coproduct by introducing another possible type that it could represent. As no morphisms can be provided mapping current types to the new type, this operation merely acts as a convenience method to allow the use of a more convergent coproduct with a more divergent one; that is, if a CoProduct3<String, Integer, Boolean> is expected, a CoProduct2<String, Integer> should suffice.

      Generally, we use inheritance to make this a non-issue; however, with coproducts of differing magnitudes, we cannot guarantee variance compatibility in one direction conveniently at construction time, and in the other direction, at all. A CoProduct2 could not be a CoProduct3 without specifying all type parameters that are possible for a CoProduct3 - more specifically, the third possible type - which is not necessarily known at construction time, or even useful if never used in the context of a CoProduct3. The inverse inheritance relationship - CoProduct3 < CoProduct2 - is inherently unsound, as a CoProduct3 cannot correctly implement CoProduct2.match(com.jnape.palatable.lambda.functions.Fn1<? super A, ? extends R>, com.jnape.palatable.lambda.functions.Fn1<? super B, ? extends R>), given that the third type C is always possible.

      For this reason, there is a diverge method supported between all CoProduct types of single magnitude difference.

      Specified by:
      diverge in interface CoProduct2<A,B,Choice2<A,B>>
      Type Parameters:
      C - the additional possible type of this coproduct
      Returns:
      a CoProduct3<A, B, C>
    • invert

      public Choice2<B,A> invert()
      Swap the type parameters.
      Specified by:
      invert in interface CoProduct2<A,B,Choice2<A,B>>
      Returns:
      The inverted coproduct
    • fmap

      public final <C> Choice2<A,C> fmap(Fn1<? super B,? extends C> fn)
      Covariantly transmute this functor's parameter using the given mapping function. Generally this method is specialized to return an instance of the class implementing Functor.
      Specified by:
      fmap in interface Applicative<A,B>
      Specified by:
      fmap in interface Functor<A,B>
      Specified by:
      fmap in interface Monad<A,B>
      Specified by:
      fmap in interface MonadRec<A,B>
      Specified by:
      fmap in interface Traversable<A,B>
      Type Parameters:
      C - the new parameter type
      Parameters:
      fn - the mapping function
      Returns:
      a functor over B (the new parameter type)
    • biMapL

      public final <C> Choice2<C,B> biMapL(Fn1<? super A,? extends C> fn)
      Covariantly map over the left parameter.
      Specified by:
      biMapL in interface Bifunctor<A,B,Choice2<?,?>>
      Specified by:
      biMapL in interface BoundedBifunctor<A,B,Object,Object,Choice2<?,?>>
      Type Parameters:
      C - the new left parameter type
      Parameters:
      fn - the mapping function
      Returns:
      a bifunctor over C (the new left parameter) and B (the same right parameter)
    • biMapR

      public final <C> Choice2<A,C> biMapR(Fn1<? super B,? extends C> fn)
      Covariantly map over the right parameter. For all bifunctors that are also functors, it should hold that biMapR(f) == fmap(f).
      Specified by:
      biMapR in interface Bifunctor<A,B,Choice2<?,?>>
      Specified by:
      biMapR in interface BoundedBifunctor<A,B,Object,Object,Choice2<?,?>>
      Type Parameters:
      C - the new right parameter type
      Parameters:
      fn - the mapping function
      Returns:
      a bifunctor over A (the same left parameter) and C (the new right parameter)
    • biMap

      public final <C, D> Choice2<C,D> biMap(Fn1<? super A,? extends C> lFn, Fn1<? super B,? extends D> rFn)
      Dually map covariantly over both the left and right parameters. This is isomorphic to biMapL(lFn).biMapR(rFn).
      Specified by:
      biMap in interface Bifunctor<A,B,Choice2<?,?>>
      Specified by:
      biMap in interface BoundedBifunctor<A,B,Object,Object,Choice2<?,?>>
      Type Parameters:
      C - the new left parameter type
      D - the new right parameter type
      Parameters:
      lFn - the left parameter mapping function
      rFn - the right parameter mapping function
      Returns:
      a bifunctor over C (the new left parameter type) and D (the new right parameter type)
    • pure

      public <C> Choice2<A,C> pure(C c)
      Lift the value b into this applicative functor.
      Specified by:
      pure in interface Applicative<A,B>
      Specified by:
      pure in interface Monad<A,B>
      Specified by:
      pure in interface MonadRec<A,B>
      Type Parameters:
      C - the type of the returned applicative's parameter
      Parameters:
      c - the value
      Returns:
      an instance of this applicative over b
    • zip

      public <C> Choice2<A,C> zip(Applicative<Fn1<? super B,? extends C>,Choice2<A,?>> appFn)
      Given another instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports.
      Specified by:
      zip in interface Applicative<A,B>
      Specified by:
      zip in interface Monad<A,B>
      Specified by:
      zip in interface MonadRec<A,B>
      Type Parameters:
      C - the resulting applicative parameter type
      Parameters:
      appFn - the other applicative instance
      Returns:
      the mapped applicative
    • lazyZip

      public <C> Lazy<Choice2<A,C>> lazyZip(Lazy<? extends Applicative<Fn1<? super B,? extends C>,Choice2<A,?>>> lazyAppFn)
      Given a lazy instance of this applicative over a mapping function, "zip" the two instances together using whatever application semantics the current applicative supports. This is useful for applicatives that support lazy evaluation and early termination.
      Specified by:
      lazyZip in interface Applicative<A,B>
      Specified by:
      lazyZip in interface Monad<A,B>
      Specified by:
      lazyZip in interface MonadRec<A,B>
      Type Parameters:
      C - the resulting applicative parameter type
      Parameters:
      lazyAppFn - the lazy other applicative instance
      Returns:
      the mapped applicative
      See Also:
    • discardL

      public <C> Choice2<A,C> discardL(Applicative<C,Choice2<A,?>> appB)
      Sequence both this Applicative and appB, discarding this Applicative's result and returning appB. This is generally useful for sequentially performing side-effects.
      Specified by:
      discardL in interface Applicative<A,B>
      Specified by:
      discardL in interface Monad<A,B>
      Specified by:
      discardL in interface MonadRec<A,B>
      Type Parameters:
      C - the type of the returned Applicative's parameter
      Parameters:
      appB - the other Applicative
      Returns:
      appB
    • discardR

      public <C> Choice2<A,B> discardR(Applicative<C,Choice2<A,?>> appB)
      Sequence both this Applicative and appB, discarding appB's result and returning this Applicative. This is generally useful for sequentially performing side-effects.
      Specified by:
      discardR in interface Applicative<A,B>
      Specified by:
      discardR in interface Monad<A,B>
      Specified by:
      discardR in interface MonadRec<A,B>
      Type Parameters:
      C - the type of appB's parameter
      Parameters:
      appB - the other Applicative
      Returns:
      this Applicative
    • flatMap

      public final <C> Choice2<A,C> flatMap(Fn1<? super B,? extends Monad<C,Choice2<A,?>>> f)
      Chain dependent computations that may continue or short-circuit based on previous results.
      Specified by:
      flatMap in interface Monad<A,B>
      Specified by:
      flatMap in interface MonadRec<A,B>
      Type Parameters:
      C - the resulting monad parameter type
      Parameters:
      f - the dependent computation over A
      Returns:
      the new monad instance
    • trampolineM

      public <C> Choice2<A,C> trampolineM(Fn1<? super B,? extends MonadRec<RecursiveResult<B,C>,Choice2<A,?>>> fn)
      Given some operation yielding a RecursiveResult inside this MonadRec, internally trampoline the operation until it yields a termination instruction.

      Stack-safety depends on implementations guaranteeing that the growth of the call stack is a constant factor independent of the number of invocations of the operation. For various examples of how this can be achieved in stereotypical circumstances, see the referenced types.

      Specified by:
      trampolineM in interface MonadRec<A,B>
      Type Parameters:
      C - the ultimate resulting carrier type
      Parameters:
      fn - the function to internally trampoline
      Returns:
      the trampolined MonadRec
      See Also:
    • traverse

      public <C, App extends Applicative<?, App>, TravB extends Traversable<C, Choice2<A, ?>>, AppTrav extends Applicative<TravB, App>> AppTrav traverse(Fn1<? super B,? extends Applicative<C,App>> fn, Fn1<? super TravB,? extends AppTrav> pure)
      Apply fn to each element of this traversable from left to right, and collapse the results into a single resulting applicative, potentially with the assistance of the applicative's pure function.
      Specified by:
      traverse in interface Traversable<A,B>
      Type Parameters:
      C - the resulting element type
      App - the result applicative type
      TravB - this Traversable instance over B
      AppTrav - the full inferred resulting type from the traversal
      Parameters:
      fn - the function to apply
      pure - the applicative pure function
      Returns:
      the traversed Traversable, wrapped inside an applicative
    • a

      public static <A, B> Choice2<A,B> a(A a)
      Static factory method for wrapping a value of type A in a Choice2.
      Type Parameters:
      A - the first possible type
      B - the second possible type
      Parameters:
      a - the value
      Returns:
      the wrapped value as a Choice2<A, B>
    • b

      public static <A, B> Choice2<A,B> b(B b)
      Static factory method for wrapping a value of type B in a Choice2.
      Type Parameters:
      A - the first possible type
      B - the second possible type
      Parameters:
      b - the value
      Returns:
      the wrapped value as a Choice2<A, B>
    • pureChoice

      public static <A> Pure<Choice2<A,?>> pureChoice()
      The canonical Pure instance for Choice2.
      Type Parameters:
      A - the first possible type
      Returns:
      the Pure instance