com.jnape.palatable.lambda.adt

## Class Maybe<A>

- java.lang.Object
- - com.jnape.palatable.lambda.adt.Maybe<A>

- Type Parameters:
    `A` - the optional parameter type
  All Implemented Interfaces:
    CoProduct2<Unit,A,Maybe<A>>, Applicative<A,Maybe<?>>, Functor<A,Maybe<?>>, Monad<A,Maybe<?>>, MonadError<Unit,A,Maybe<?>>, MonadRec<A,Maybe<?>>, Traversable<A,Maybe<?>>

      public abstract class Maybe<A>
      extends Object
      implements CoProduct2<Unit,A,Maybe<A>>, MonadError<Unit,A,Maybe<?>>, MonadRec<A,Maybe<?>>, Traversable<A,Maybe<?>>

  The optional type, representing a potentially absent value. This is lambda's analog of `Optional`, supporting all the usual suspects like `Functor`, `Applicative`, `Traversable`, etc.
  See Also:
    `Optional`

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `Maybe<A>` | `catchError(Fn1<? super Unit,? extends Monad<A,Maybe<?>>> recoveryFn)` Catch any `thrown` errors inside the `Monad` and resume normal operations.
    `<B> Maybe<B>` | `discardL(Applicative<B,Maybe<?>> appB)` Sequence both this `Applicative` and `appB`, discarding this `Applicative's` result and returning `appB`.
    `<B> Maybe<A>` | `discardR(Applicative<B,Maybe<?>> appB)` Sequence both this `Applicative` and `appB`, discarding `appB's` result and returning this `Applicative`.
    `<B> Choice3<Unit,A,B>` | `diverge()` Diverge this coproduct by introducing another possible type that it could represent.
    `Maybe<A>` | `filter(Fn1<? super A,? extends Boolean> predicate)` If this value is present and satisfies `predicate`, return `just` the value; otherwise, return `nothing`.
    `<B> Maybe<B>` | `flatMap(Fn1<? super A,? extends Monad<B,Maybe<?>>> f)` Chain dependent computations that may continue or short-circuit based on previous results.
    `<B> Maybe<B>` | `fmap(Fn1<? super A,? extends B> fn)` Covariantly transmute this functor's parameter using the given mapping function.
    `static <A> Maybe<A>` | `fromEither(Either<?,A> either)` Convenience static factory method for creating a `Maybe` from an `Either`.
    `static <A> Maybe<A>` | `fromOptional(Optional<? extends A> optional)` Convenience static factory method for creating a `Maybe` from an `Optional`.
    `Choice2<A,Unit>` | `invert()` Swap the type parameters.
    `static <A> Maybe<A>` | `just(A a)` Lift a non-null value into `Maybe`.
    `<B> Lazy<Maybe<B>>` | `lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,Maybe<?>>> lazyAppFn)` Terminate early if this is a `Nothing`; otherwise, continue the `zip`.
    `static <A> Maybe<A>` | `maybe(A a)` Lift a potentially null value into `Maybe`.
    `static <A> Maybe<A>` | `nothing()` Return nothing.
    `A` | `orElse(A other)` If the value is present, return it; otherwise, return `other`.
    `A` | `orElseGet(Fn0<A> otherFn0)` If the value is present, return it; otherwise, return the value supplied by `otherSupplier`.
    `<E extends Throwable> A` | `orElseThrow(Fn0<? extends E> throwableSupplier)` If the value is present, return it; otherwise, throw the `Throwable` supplied by `throwableSupplier`.
    `Maybe<A>` | `peek(Fn1<? super A,? extends IO<?>> effect)` Deprecated. in favor of `matching` into an `IO` and explicitly running it
    `Tuple2<Maybe<Unit>,Maybe<A>>` | `project()` Project this coproduct onto a product, such that the index in the product that corresponds to this coproduct's value is present, while the other indices are absent.
    `<B> Maybe<B>` | `pure(B b)` Lift the value into the `Maybe` monad
    `static Pure<Maybe<?>>` | `pureMaybe()` The canonical `Pure` instance for `Maybe`.
    `Maybe<A>` | `throwError(Unit unit)` Throw an error value of type `E` into the `monad`.
    `<L> Either<L,A>` | `toEither(Fn0<L> lFn0)` If this value is absent, return the value supplied by `lSupplier` wrapped in `Either.left`.
    `Optional<A>` | `toOptional()` Convert to `Optional`.
    `<B> Maybe<B>` | `trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,Maybe<?>>> fn)` Given some operation yielding a `RecursiveResult` inside this `MonadRec`, internally trampoline the operation until it yields a `termination` instruction.
    `<B,App extends Applicative<?,App>,TravB extends Traversable<B,Maybe<?>>,AppTrav extends Applicative<TravB,App>> AppTrav` | `traverse(Fn1<? super A,? extends Applicative<B,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.
    `<B> Maybe<B>` | `zip(Applicative<Fn1<? super A,? extends B>,Maybe<?>> 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.monad.Monad

      `join`

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

      `coerce`

- - ### Method Detail

    - #### orElseGet

          public final A orElseGet(Fn0<A> otherFn0)

      If the value is present, return it; otherwise, return the value supplied by `otherSupplier`.
      Parameters:
        `otherFn0` - the supplier for the other value
      Returns:
        this value, or the supplied other value

    - #### orElse

          public final A orElse(A other)

      If the value is present, return it; otherwise, return `other`.
      Parameters:
        `other` - the other value
      Returns:
        this value, or the other value

    - #### orElseThrow

          public final <E extends Throwable> A orElseThrow(Fn0<? extends E> throwableSupplier)
                                                    throws E extends Throwable

      If the value is present, return it; otherwise, throw the `Throwable` supplied by `throwableSupplier`.
      Type Parameters:
        `E` - the Throwable type
      Parameters:
        `throwableSupplier` - the supplier of the potentially thrown `Throwable`
      Returns:
        the value, if present
      Throws:
        `E` - the throwable, if the value is absent
        `E extends Throwable`

    - #### filter

          public final Maybe<A> filter(Fn1<? super A,? extends Boolean> predicate)

      If this value is present and satisfies `predicate`, return `just` the value; otherwise, return `nothing`.
      Parameters:
        `predicate` - the predicate to apply to the possibly absent value
      Returns:
        maybe the present value that satisfied the predicate

    - #### throwError

          public Maybe<A> throwError(Unit unit)

      Throw an error value of type `E` into the `monad`.
      Specified by:
        `throwError` in interface `MonadError<Unit,A,Maybe<?>>`
      Parameters:
        `unit` - the error type
      Returns:
        the `monad`

    - #### catchError

          public Maybe<A> catchError(Fn1<? super Unit,? extends Monad<A,Maybe<?>>> recoveryFn)

      Catch any `thrown` errors inside the `Monad` and resume normal operations.
      Specified by:
        `catchError` in interface `MonadError<Unit,A,Maybe<?>>`
      Parameters:
        `recoveryFn` - the catch function
      Returns:
        the recovered `Monad`

    - #### toEither

          public final <L> Either<L,A> toEither(Fn0<L> lFn0)

      If this value is absent, return the value supplied by `lSupplier` wrapped in `Either.left`. Otherwise, wrap the value in `Either.right` and return it.
      Type Parameters:
        `L` - the left parameter type
      Parameters:
        `lFn0` - the supplier for the left value
      Returns:
        this value wrapped in an Either.right, or an Either.left around the result of lSupplier

    - #### toOptional

          public final Optional<A> toOptional()

      Convert to `Optional`.
      Returns:
        the Optional

    - #### pure

          public final <B> Maybe<B> pure(B b)

      Lift the value into the `Maybe` monad
      Specified by:
        `pure` in interface `Applicative<A,Maybe<?>>`
      Specified by:
        `pure` in interface `Monad<A,Maybe<?>>`
      Specified by:
        `pure` in interface `MonadError<Unit,A,Maybe<?>>`
      Specified by:
        `pure` in interface `MonadRec<A,Maybe<?>>`
      Type Parameters:
        `B` - the value type
      Parameters:
        `b` - the value
      Returns:
        Just b

    - #### fmap

          public final <B> Maybe<B> fmap(Fn1<? super A,? extends B> 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.

      If the value is present, return `just(A)` `fn` applied to the value; otherwise, return `nothing()`.

      Specified by:
        `fmap` in interface `Applicative<A,Maybe<?>>`
      Specified by:
        `fmap` in interface `Functor<A,Maybe<?>>`
      Specified by:
        `fmap` in interface `Monad<A,Maybe<?>>`
      Specified by:
        `fmap` in interface `MonadError<Unit,A,Maybe<?>>`
      Specified by:
        `fmap` in interface `MonadRec<A,Maybe<?>>`
      Specified by:
        `fmap` in interface `Traversable<A,Maybe<?>>`
      Type Parameters:
        `B` - the new parameter type
      Parameters:
        `fn` - the mapping function
      Returns:
        a functor over B (the new parameter type)

    - #### zip

          public final <B> Maybe<B> zip(Applicative<Fn1<? super A,? extends B>,Maybe<?>> 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,Maybe<?>>`
      Specified by:
        `zip` in interface `Monad<A,Maybe<?>>`
      Specified by:
        `zip` in interface `MonadError<Unit,A,Maybe<?>>`
      Specified by:
        `zip` in interface `MonadRec<A,Maybe<?>>`
      Type Parameters:
        `B` - the resulting applicative parameter type
      Parameters:
        `appFn` - the other applicative instance
      Returns:
        the mapped applicative

    - #### lazyZip

          public <B> Lazy<Maybe<B>> lazyZip(Lazy<? extends Applicative<Fn1<? super A,? extends B>,Maybe<?>>> lazyAppFn)

      Terminate early if this is a `Nothing`; otherwise, continue the `zip`.
      Specified by:
        `lazyZip` in interface `Applicative<A,Maybe<?>>`
      Specified by:
        `lazyZip` in interface `Monad<A,Maybe<?>>`
      Specified by:
        `lazyZip` in interface `MonadError<Unit,A,Maybe<?>>`
      Specified by:
        `lazyZip` in interface `MonadRec<A,Maybe<?>>`
      Type Parameters:
        `B` - the result type
      Parameters:
        `lazyAppFn` - the lazy other applicative instance
      Returns:
        the zipped `Maybe`
      See Also:
        `Maybe`, `Either`

    - #### discardL

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

    - #### discardR

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

    - #### flatMap

          public final <B> Maybe<B> flatMap(Fn1<? super A,? extends Monad<B,Maybe<?>>> f)

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

    - #### trampolineM

          public <B> Maybe<B> trampolineM(Fn1<? super A,? extends MonadRec<RecursiveResult<A,B>,Maybe<?>>> 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,Maybe<?>>`
      Type Parameters:
        `B` - 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`

    - #### diverge

          public <B> Choice3<Unit,A,B> 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<Unit,A,Maybe<A>>`
      Type Parameters:
        `B` - the additional possible type of this coproduct
      Returns:
        a `CoProduct3`<A, B, C>

    - #### project

          public Tuple2<Maybe<Unit>,Maybe<A>> project()

      Project this coproduct onto a product, such that the index in the product that corresponds to this coproduct's value is present, while the other indices are absent.
      Specified by:
        `project` in interface `CoProduct2<Unit,A,Maybe<A>>`
      Returns:
        a product of the coproduct projection

    - #### invert

          public Choice2<A,Unit> invert()

      Swap the type parameters.
      Specified by:
        `invert` in interface `CoProduct2<Unit,A,Maybe<A>>`
      Returns:
        The inverted coproduct

    - #### peek

          @Deprecated
          public final Maybe<A> peek(Fn1<? super A,? extends IO<?>> effect)

      Deprecated. in favor of `matching` into an `IO` and explicitly running it
      If this value is present, accept it by `consumer`; otherwise, do nothing.
      Parameters:
        `effect` - the consumer
      Returns:
        the same Maybe instance

    - #### traverse

          public final <B,App extends Applicative<?,App>,TravB extends Traversable<B,Maybe<?>>,AppTrav extends Applicative<TravB,App>> AppTrav traverse(Fn1<? super A,? extends Applicative<B,App>> fn,
                                                                                                                                                        Fn1<? super TravB,? extends AppTrav> pure)

      Description copied from interface: `Traversable`
      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,Maybe<?>>`
      Type Parameters:
        `B` - 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

    - #### fromEither

          public static <A> Maybe<A> fromEither(Either<?,A> either)

      Convenience static factory method for creating a `Maybe` from an `Either`. If `either` is a right value, wrap the value in a `just` and return it; otherwise, return `nothing()`.
      Type Parameters:
        `A` - the potential right value
      Parameters:
        `either` - the either instance
      Returns:
        "Just" the right value, or nothing

    - #### fromOptional

          public static <A> Maybe<A> fromOptional(Optional<? extends A> optional)

      Convenience static factory method for creating a `Maybe` from an `Optional`.
      Type Parameters:
        `A` - the optional parameter type
      Parameters:
        `optional` - the optional
      Returns:
        the equivalent Maybe instance

    - #### maybe

          public static <A> Maybe<A> maybe(A a)

      Lift a potentially null value into `Maybe`. If `a` is not null, returns `just(a)`; otherwise, returns `nothing()`.
      Type Parameters:
        `A` - the value parameter type
      Parameters:
        `a` - the potentially null value
      Returns:
        "Just" the value, or nothing

    - #### just

          public static <A> Maybe<A> just(A a)

      Lift a non-null value into `Maybe`. This differs from `maybe(A)` in that the value *must* be non-null; if it is null, a `NullPointerException` is thrown.
      Type Parameters:
        `A` - the value parameter type
      Parameters:
        `a` - the non-null value
      Returns:
        "Just" the value
      Throws:
        `NullPointerException` - if a is null

    - #### nothing

          public static <A> Maybe<A> nothing()

      Return nothing.
      Type Parameters:
        `A` - the type of the value, if there was one
      Returns:
        nothing

    - #### pureMaybe

          public static Pure<Maybe<?>> pureMaybe()

      The canonical `Pure` instance for `Maybe`.
      Returns:
        the `Pure` instance