com.jnape.palatable.lambda.functor.builtin

## Class Const<A,B>

- java.lang.Object
- - com.jnape.palatable.lambda.functor.builtin.Const<A,B>

- Type Parameters:
    `A` - the left parameter type, and the type of the stored value
    `B` - the right (phantom) parameter type
  All Implemented Interfaces:
    Applicative<B,Const<A,?>>, Bifunctor<A,B,Const<?,?>>, BoundedBifunctor<A,B,Object,Object,Const<?,?>>, Functor<B,Const<A,?>>, Monad<B,Const<A,?>>, MonadRec<B,Const<A,?>>, Traversable<B,Const<A,?>>

      public final class Const<A,B>
      extends Object
      implements MonadRec<B,Const<A,?>>, Bifunctor<A,B,Const<?,?>>, Traversable<B,Const<A,?>>

  A (surprisingly useful) functor over some phantom type `B`, retaining a value of type `A` that can be retrieved later. This is useful in situations where it is desirable to retain constant information throughout arbitrary functor transformations, such that at the end of the chain, regardless of how `B` has been altered, `A` is still pristine and retrievable.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Const(A a)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `<C,D> Const<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.
    `<Z> Const<Z,B>` | `biMapL(Fn1<? super A,? extends Z> fn)` Covariantly map over the left parameter.
    `<C> Const<A,C>` | `biMapR(Fn1<? super B,? extends C> fn)` Covariantly map over the right parameter.
    `<C> Const<A,C>` | `discardL(Applicative<C,Const<A,?>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `<C> Const<A,B>` | `discardR(Applicative<C,Const<A,?>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `boolean` | `equals(Object other)`
    `<C> Const<A,C>` | `flatMap(Fn1<? super B,? extends Monad<C,Const<A,?>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `<C> Const<A,C>` | `fmap(Fn1<? super B,? extends C> fn)` Map over the right parameter.
    `int` | `hashCode()`
    `<C> Lazy<Const<A,C>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super B,? extends C>,Const<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.
    `<C> Const<A,C>` | `pure(C c)` Lift the value `b` into this applicative functor.
    `static <A> Pure<Const<A,?>>` | `pureConst(A a)` The canonical `Pure` instance for `Const`.
    `A` | `runConst()` Retrieve the stored value.
    `String` | `toString()`
    `<C> Const<A,C>` | `trampolineM(Fn1<? super B,? extends MonadRec<RecursiveResult<B,C>,Const<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,Const<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> Const<A,C>` | `zip(Applicative<Fn1<? super B,? extends C>,Const<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, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface com.jnape.palatable.lambda.monad.Monad

      `join`

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

      `coerce`

- - ### Constructor Detail

    - #### Const

          public Const(A a)

  - ### Method Detail

    - #### runConst

          public A runConst()

      Retrieve the stored value.
      Returns:
        the value

    - #### fmap

          public <C> Const<A,C> fmap(Fn1<? super B,? extends C> fn)

      Map over the right parameter. Note that because `B` is never actually known quantity outside of a type signature, this is effectively a no-op that serves only to alter `Const's` type signature.
      Specified by:
        `fmap` in interface `Applicative<B,Const<A,?>>`
      Specified by:
        `fmap` in interface `Functor<B,Const<A,?>>`
      Specified by:
        `fmap` in interface `Monad<B,Const<A,?>>`
      Specified by:
        `fmap` in interface `MonadRec<B,Const<A,?>>`
      Specified by:
        `fmap` in interface `Traversable<B,Const<A,?>>`
      Type Parameters:
        `C` - the new right parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a Const over A (the same value) and C (the new phantom parameter)

    - #### pure

          public <C> Const<A,C> pure(C c)

      Lift the value `b` into this applicative functor.
      Specified by:
        `pure` in interface `Applicative<B,Const<A,?>>`
      Specified by:
        `pure` in interface `Monad<B,Const<A,?>>`
      Specified by:
        `pure` in interface `MonadRec<B,Const<A,?>>`
      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> Const<A,C> zip(Applicative<Fn1<? super B,? extends C>,Const<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<B,Const<A,?>>`
      Specified by:
        `zip` in interface `Monad<B,Const<A,?>>`
      Specified by:
        `zip` in interface `MonadRec<B,Const<A,?>>`
      Type Parameters:
        `C` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### lazyZip

          public <C> Lazy<Const<A,C>> lazyZip(Lazy<? extends Applicative<Fn1<? super B,? extends C>,Const<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<B,Const<A,?>>`
      Specified by:
        `lazyZip` in interface `Monad<B,Const<A,?>>`
      Specified by:
        `lazyZip` in interface `MonadRec<B,Const<A,?>>`
      Type Parameters:
        `C` - the resulting applicative parameter type
      Parameters:
        `lazyAppFn` - the lazy other applicative instance
      Returns:
        the mapped applicative
      See Also:
        `Maybe`, `Either`

    - #### discardL

          public <C> Const<A,C> discardL(Applicative<C,Const<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<B,Const<A,?>>`
      Specified by:
        `discardL` in interface `Monad<B,Const<A,?>>`
      Specified by:
        `discardL` in interface `MonadRec<B,Const<A,?>>`
      Type Parameters:
        `C` - the type of the returned Applicative's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        appB

    - #### discardR

          public <C> Const<A,B> discardR(Applicative<C,Const<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<B,Const<A,?>>`
      Specified by:
        `discardR` in interface `Monad<B,Const<A,?>>`
      Specified by:
        `discardR` in interface `MonadRec<B,Const<A,?>>`
      Type Parameters:
        `C` - the type of appB's parameter
      Parameters:
        `appB` - the other Applicative
      Returns:
        this Applicative

    - #### flatMap

          public <C> Const<A,C> flatMap(Fn1<? super B,? extends Monad<C,Const<A,?>>> f)

      Chain dependent computations that may continue or short-circuit based on previous results.
      Specified by:
        `flatMap` in interface `Monad<B,Const<A,?>>`
      Specified by:
        `flatMap` in interface `MonadRec<B,Const<A,?>>`
      Type Parameters:
        `C` - the resulting monad parameter type
      Parameters:
        `f` - the dependent computation over A
      Returns:
        the new monad instance

    - #### trampolineM

          public <C> Const<A,C> trampolineM(Fn1<? super B,? extends MonadRec<RecursiveResult<B,C>,Const<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<B,Const<A,?>>`
      Type Parameters:
        `C` - the ultimate resulting carrier type
      Parameters:
        `fn` - the function to internally trampoline
      Returns:
        the trampolined `MonadRec`
      See Also:
        `for a basic implementation`, `for a {@link CoProduct2 coproduct} implementation`, `for an implementation leveraging an already stack-safe {@link Monad#flatMap(Fn1)}`, `for a {@link MonadT monad transformer} implementation`

    - #### traverse

          public <C,App extends Applicative<?,App>,TravB extends Traversable<C,Const<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<B,Const<A,?>>`
      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

    - #### biMapL

          public <Z> Const<Z,B> biMapL(Fn1<? super A,? extends Z> fn)

      Covariantly map over the left parameter.
      Specified by:
        `biMapL` in interface `Bifunctor<A,B,Const<?,?>>`
      Specified by:
        `biMapL` in interface `BoundedBifunctor<A,B,Object,Object,Const<?,?>>`
      Type Parameters:
        `Z` - 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 <C> Const<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,Const<?,?>>`
      Specified by:
        `biMapR` in interface `BoundedBifunctor<A,B,Object,Object,Const<?,?>>`
      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 <C,D> Const<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,Const<?,?>>`
      Specified by:
        `biMap` in interface `BoundedBifunctor<A,B,Object,Object,Const<?,?>>`
      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)

    - #### equals

          public boolean equals(Object other)

      Overrides:
        `equals` in class `Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### pureConst

          public static <A> Pure<Const<A,?>> pureConst(A a)

      The canonical `Pure` instance for `Const`.
      Type Parameters:
        `A` - the left parameter type, and the type of the stored value
      Parameters:
        `a` - the stored value
      Returns:
        the `Pure` instance