Package cms.util.maybe

Class Maybe<T>

  • All Implemented Interfaces:
    java.lang.Iterable<T>
    public abstract class Maybe<T>
extends java.lang.Object
implements java.lang.Iterable<T>
    An object that may contain a value of type T. Similar to Java's Optional class but uses a fast checked exception instead of a slow unchecked exception.

    • Constructor Summary

      Constructors 
      Constructor Description
      Maybe()  

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      static <T,​U extends T>
      Maybe<T>      		 cast​(Maybe<U> in)
      Convert a Maybe<U> to a Maybe<T>, when T is a supertype of U.
      static <T> Maybe<T> from​(T v)
      Create a Maybe from a possibly null value v.
      static <T> Maybe<T> fromOptional​(java.util.Optional<T> optional)
      Create a Maybe from an Optional value.
      abstract T get()
      Returns the contained value, if present.
      static <T> T getOptional​(java.util.Optional<T> optional)
      Get the value in an Optional, if present; otherwise throw the checked exception NoMaybeValue.
      abstract boolean isPresent()
      Returns whether a value is contained in this Maybe.
      abstract java.util.Iterator<T> iterator()
      Provide an iterator that yields either one T or none, depending.
      static <T> Maybe<T> none()
      Returns an empty Maybe.
      abstract T orElse​(T other)
      Returns the contained value, if any; otherwise, returns other.
      abstract T orElseGet​(java.util.function.Supplier<T> other)
      Returns the contained value, if any; otherwise, returns other.get().
      abstract Maybe<T> orElseMaybe​(java.util.function.Supplier<Maybe<T>> other)
      Returns this if a value is contained; otherwise, returns other.get().
      static <T> Maybe<T> some​(T v)
      Creates a Maybe from a non-null argument.
      abstract <U> Maybe<U> then​(java.util.function.Function<T,​U> f)
      If a value v is present, returns a Maybe containing f(v), which must be non-null.
      abstract void thenDo​(java.util.function.Consumer<T> cons)
      Call cons on the contained value, if any.
      abstract <U> Maybe<U> thenMaybe​(java.util.function.Function<T,​Maybe<U>> f)
      If a value v is present, returns f(v).
      java.util.Optional<T> toOptional()
      Create an Optional from a Maybe

      • Methods inherited from class java.lang.Object

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

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Constructor Detail

      • Maybe

        public Maybe()

    • Method Detail

      • isPresent

        public abstract boolean isPresent()
        Returns whether a value is contained in this Maybe.
        Returns:
        whether a value is contained.

      • get

        public abstract T get()
               throws NoMaybeValue
        Returns the contained value, if present. Otherwise, throws the exception.
        Returns:
        the contained value
        Throws:
        NoMaybeValue - if no value is contained in this Maybe. This method is primarily useful for writing code that is supposed to perform side effects, e.g.: 
         Maybe<T> m = ...
 try {
    ... m.get() ...
 } catch (NoMaybeValue e) {
    ...
 }

      • thenMaybe

        public abstract <U> Maybe<U> thenMaybe​(java.util.function.Function<T,​Maybe<U>> f)
        If a value v is present, returns f(v). Otherwise, returns an empty Maybe. (This is a monadic bind.) This method is useful for chaining together a series of Maybe accesses. For example, supposing T.foo() returns a Maybe: 
         
 Maybe<T> mt = ...
 mt.thenMaybe(t -> t.foo().then(f -> ...))
   .orElse(...)
        Type Parameters:
        U - The type of the value that may be returned by the function f.
        Parameters:
        f - The function to be applied to the contained value, if any.
        Returns:
        the Maybe returned by f, if a value is contained in this Maybe. Otherwise, an empty Maybe.

      • then

        public abstract <U> Maybe<U> then​(java.util.function.Function<T,​U> f)
        If a value v is present, returns a Maybe containing f(v), which must be non-null. Otherwise, returns an empty Maybe. (This is a monadic bind composed with a monadic unit.) This method can be used conveniently along with orElse to handle both maybe cases, e.g.: 
         
 Maybe<T> mt = ...
 mt.then(t -> ...)
   .orElse(...)
        Type Parameters:
        U - The type of the value that may be returned by the function f.
        Parameters:
        f - The function to be applied to the contained value, if any.
        Returns:
        a Maybe containing the value f, if a value is contained in this Maybe. Otherwise, an empty Maybe.

      • orElse

        public abstract T orElse​(T other)
        Returns the contained value, if any; otherwise, returns other. Note: since orElse is an ordinary method call, its argument is always computed, unlike a Java else statement. If the argument is expensive to compute or has side effects, orElseGet() should be used instead.
        Parameters:
        other - The value to be returned if no value is in this Maybe.
        Returns:
        The contained value, or an empty Maybe.

      • orElseGet

        public abstract T orElseGet​(java.util.function.Supplier<T> other)
        Returns the contained value, if any; otherwise, returns other.get().
        Parameters:
        other - The function to use when this Maybe is empty.
        Returns:
        the contained value or other.get().

      • orElseMaybe

        public abstract Maybe<T> orElseMaybe​(java.util.function.Supplier<Maybe<T>> other)
        Returns this if a value is contained; otherwise, returns other.get().
        Parameters:
        other - The function to use when this Maybe is empty.
        Returns:
        this or other.get().

      • thenDo

        public abstract void thenDo​(java.util.function.Consumer<T> cons)
        Call cons on the contained value, if any.
        Parameters:
        cons - The function to send the contained value to.

      • iterator

        public abstract java.util.Iterator<T> iterator()
        Provide an iterator that yields either one T or none, depending.
        Specified by:
        iterator in interface java.lang.Iterable<T>

      • from

        public static <T> Maybe<T> from​(T v)
        Create a Maybe from a possibly null value v. The Maybe will contain a value if v is non-null.
        Type Parameters:
        T - The type of Maybe to be created.
        Parameters:
        v - The value to put into a Maybe, or null.

      • fromOptional

        public static <T> Maybe<T> fromOptional​(java.util.Optional<T> optional)
        Create a Maybe from an Optional value.
        Type Parameters:
        T - The type of the value inside the Optional.
        Parameters:
        optional - The Optional value.
        Returns:
        If the Optional contains a value, then Some of that value, otherwise None.

      • toOptional

        public java.util.Optional<T> toOptional()
        Create an Optional from a Maybe

      • getOptional

        public static <T> T getOptional​(java.util.Optional<T> optional)
                         throws NoMaybeValue
        Get the value in an Optional, if present; otherwise throw the checked exception NoMaybeValue. This method allows Optionals to be used as if they were Maybes.
        Returns:
        The value in the optional, if any
        Throws:
        NoMaybeValue - if no value is present.

      • none

        public static <T> Maybe<T> none()
        Returns an empty Maybe.

      • some

        public static <T> Maybe<T> some​(T v)
        Creates a Maybe from a non-null argument.
        Parameters:
        v - must be non-null
        Throws:
        java.lang.IllegalArgumentException - if a null value is passed to it.

      • cast

        public static <T,​U extends T> Maybe<T> cast​(Maybe<U> in)
        Convert a Maybe<U> to a Maybe<T>, when T is a supertype of U. This covariant subtyping is safe because Maybes are immutable.