Package io.atlassian.fugue

Class Option<A>

  • Type Parameters:
    A - the value type the option contains
    All Implemented Interfaces:
    Effect.Applicant<A>, Maybe<A>, java.io.Serializable, java.lang.Iterable<A>
    Direct Known Subclasses:
    Option.None, Option.Some
    public abstract class Option<A>
extends java.lang.Object
implements java.lang.Iterable<A>, Maybe<A>, java.io.Serializable
    A class that encapsulates missing values. An Option may be either some value or none.

    If it is a value it may be tested with the Maybe.isDefined() method, but more often it is useful to either return the value or an alternative if not set, or map or filter.

    Mapping a none of type A to type B will simply return a none of type B if performed on a none of type A. Similarly, filtering will always fail on a none.

    This class is often used as an alternative to null where null may be used to represent an optional value. There are however some situations where null may be a legitimate value, and that even though the option is defined, it still carries a null inside. Specifically, this will happen if a function is mapped across it returns null, as it is necessary to preserve the Functor composition law. Note however, that this should be rare as functions that return null is a bad idea anyway. Note that if a function returns null to indicate optionality, it can be lifted into a partial function and then flat mapped instead.

    Note: while this class is public and abstract it does not expose a constructor as only the concrete internal subclasses are designed to be used.

    Since:
    1.0
    See Also:
    Serialized Form

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      (package private) static class  Option.None
      One of the big two actual implementation classes.
      (package private) static class  Option.Some<A>
      One of the big two actual implementation classes.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private static java.io.Serializable NONE
      Deprecated.
      private static java.util.function.Supplier<java.lang.Integer> NONE_HASH  
      private static java.util.function.Supplier<java.lang.String> NONE_STRING  
      private static long serialVersionUID  
      private static java.util.function.Function<java.lang.Object,​java.lang.Integer> SOME_HASH  
      private static java.util.function.Function<java.lang.Object,​java.lang.String> SOME_STRING  

    • Constructor Summary

      Constructors 
      Constructor Description
      Option()
      do not constructor

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static <A> java.util.function.Predicate<Option<A>> defined()
      Predicate for filtering defined options only.
      boolean equals​(java.lang.Object obj)
      boolean exists​(java.util.function.Predicate<? super A> p)
      Whether this is is defined and applying the predicate to the contained value returns true.
      Option<A> filter​(java.util.function.Predicate<? super A> p)
      Returns this Option if it is nonempty and applying the predicate to this option's value returns true.
      Option<A> filterNot​(java.util.function.Predicate<? super A> p)
      Returns this Option if it is nonempty and applying the predicate to this option's value returns false.
      <B> Option<B> flatMap​(java.util.function.Function<? super A,​? extends Option<? extends B>> f)
      Apply f to the value if defined.
      abstract <B> B fold​(java.util.function.Supplier<? extends B> none, java.util.function.Function<? super A,​? extends B> some)
      If this is a some value apply the some function, otherwise get the None value.
      boolean forall​(java.util.function.Predicate<? super A> p)
      Returns true if empty or the result of the application of the given function to the value.
      static <A> Option<A> fromOptional​(java.util.Optional<A> optional)
      Factory method for Option instances from Optional instances.
      A getOr​(java.util.function.Supplier<? extends A> supplier)
      Get the value if defined or call the supplier and return its value if not.
      <B extends A>
      A      		 getOrElse​(B other)
      Get the value if defined, otherwise returns other.
      A getOrElse​(java.util.function.Supplier<? extends A> supplier)
      Deprecated.
      A getOrNull()
      Get the value if defined or null if not.
      int hashCode()
      boolean isEmpty()
      If the type does not contain a value return true.
      java.util.Iterator<A> iterator()
      Return an iterator for this type.
      <B> Option<B> map​(java.util.function.Function<? super A,​? extends B> f)
      Apply f to the value if defined.
      static <A> Option<A> none()
      Factory method for None instances.
      static <A> Option<A> none​(java.lang.Class<A> type)
      Factory method for None instances where the type token is handy.
      static <A> java.util.function.Supplier<Option<A>> noneSupplier()
      Supplies None as required.
      static <A> Option<A> option​(A a)
      Factory method for Option instances.
      Option<A> orElse​(Option<? extends A> orElse)
      If this is a some, return the same some.
      Option<A> orElse​(java.util.function.Supplier<? extends Option<? extends A>> orElse)
      If this is a some, return the same some.
      static <A> Option<A> some​(A value)
      Factory method for Some instances.
      <X> Either<A,​X> toLeft​(java.util.function.Supplier<X> right)
      Creates an Either from this Option.
      abstract java.util.Optional<A> toOptional()
      Create an Optional from this option.
      <X> Either<X,​A> toRight​(java.util.function.Supplier<X> left)
      Creates an Either from this Option.
      abstract java.util.stream.Stream<A> toStream()
      Create a Stream from this option.
      java.lang.String toString()
      private java.util.function.Function<java.lang.Object,​java.lang.Boolean> valuesEqual()  

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

      • Methods inherited from interface java.lang.Iterable

        forEach, spliterator

    • Field Detail

      • NONE_STRING

        private static final java.util.function.Supplier<java.lang.String> NONE_STRING

      • NONE_HASH

        private static final java.util.function.Supplier<java.lang.Integer> NONE_HASH

      • SOME_STRING

        private static final java.util.function.Function<java.lang.Object,​java.lang.String> SOME_STRING

      • SOME_HASH

        private static final java.util.function.Function<java.lang.Object,​java.lang.Integer> SOME_HASH

      • NONE

        @Deprecated
private static final java.io.Serializable NONE
        Deprecated.
        Backwards compatibility requires us to have a class Option$1 so we can deserialize it into Option$None.
        Since:
        4.2.0

    • Constructor Detail

      • Option

        Option()
        do not constructor

    • Method Detail

      • option

        public static <A> Option<A> option​(A a)
        Factory method for Option instances.
        Type Parameters:
        A - the contained type
        Parameters:
        a - the value to hold
        Returns:
        a Some if the parameter is not null or a None if it is

      • some

        public static <A> Option<A> some​(A value)
        Factory method for Some instances.
        Type Parameters:
        A - the contained type
        Parameters:
        value - the value to hold, must not be null
        Returns:
        a Some if the parameter is not null
        Throws:
        java.lang.NullPointerException - if the parameter is null

      • none

        public static <A> Option<A> none()
        Factory method for None instances.
        Type Parameters:
        A - the held type
        Returns:
        a None

      • none

        public static <A> Option<A> none​(java.lang.Class<A> type)
        Factory method for None instances where the type token is handy. Allows calling in-line where the type inferencer would otherwise complain.
        Type Parameters:
        A - the contained type
        Parameters:
        type - token of the right type, unused, only here for the type inferencer
        Returns:
        a None

      • defined

        public static <A> java.util.function.Predicate<Option<A>> defined()
        Predicate for filtering defined options only.
        Type Parameters:
        A - the contained type
        Returns:
        a Predicate that returns true only for defined options

      • noneSupplier

        public static <A> java.util.function.Supplier<Option<A>> noneSupplier()
        Supplies None as required. Useful as the zero value for folds.
        Type Parameters:
        A - the contained type
        Returns:
        a Supplier of None instances

      • fromOptional

        public static <A> Option<A> fromOptional​(java.util.Optional<A> optional)
        Factory method for Option instances from Optional instances.
        Type Parameters:
        A - the contained type
        Parameters:
        optional - a Optional object.
        Returns:
        a Some if Optional.isPresent() or a None otherwise.

      • fold

        public abstract <B> B fold​(java.util.function.Supplier<? extends B> none,
                           java.util.function.Function<? super A,​? extends B> some)
        If this is a some value apply the some function, otherwise get the None value.
        Type Parameters:
        B - the result type
        Parameters:
        none - the supplier of the None type
        some - the function to apply if this is a Some
        Returns:
        the appropriate value

      • getOrElse

        public final <B extends A> A getOrElse​(B other)
        Get the value if defined, otherwise returns other.
        Specified by:
        getOrElse in interface Maybe<A>
        Type Parameters:
        B - default value type
        Parameters:
        other - value to return if this is empty
        Returns:
        wrapped value if this is defined, otherwise returns other

      • getOr

        public final A getOr​(java.util.function.Supplier<? extends A> supplier)
        Get the value if defined or call the supplier and return its value if not. Replaces Maybe.getOrElse(Supplier). Get the value if defined or call the supplier and return its value if not.
        Specified by:
        getOr in interface Maybe<A>
        Parameters:
        supplier - called if this is empty
        Returns:
        the wrapped value or the value from the Supplier

      • getOrElse

        @Deprecated
public final A getOrElse​(java.util.function.Supplier<? extends A> supplier)
        Deprecated.
        Get the value if defined or call the supplier and return its value if not.
        Specified by:
        getOrElse in interface Maybe<A>
        Parameters:
        supplier - called if this is empty
        Returns:
        the wrapped value or the value from the Supplier

      • getOrNull

        public final A getOrNull()
        Get the value if defined or null if not.

        Although the use of null is discouraged, code written to use these must often interface with code that expects and returns nulls.

        Specified by:
        getOrNull in interface Maybe<A>
        Returns:
        the value or null if not defined

      • orElse

        public final Option<A> orElse​(Option<? extends A> orElse)
        If this is a some, return the same some. Otherwise, return orElse.
        Parameters:
        orElse - option to return if this is none
        Returns:
        this or orElse
        Since:
        1.1

      • orElse

        public final Option<A> orElse​(java.util.function.Supplier<? extends Option<? extends A>> orElse)
        If this is a some, return the same some. Otherwise, return value supplied by orElse.
        Parameters:
        orElse - supplier which provides the option to return if this is none
        Returns:
        this or value supplied by orElse
        Since:
        1.1

      • exists

        public final boolean exists​(java.util.function.Predicate<? super A> p)
        Whether this is is defined and applying the predicate to the contained value returns true.
        Specified by:
        exists in interface Maybe<A>
        Parameters:
        p - the predicate to test, must not be null
        Returns:
        true if defined and the predicate returns true for the contained value, false otherwise.

      • forall

        public final boolean forall​(java.util.function.Predicate<? super A> p)
        Returns true if empty or the result of the application of the given function to the value.
        Specified by:
        forall in interface Maybe<A>
        Parameters:
        p - The predicate function to test on the contained value, must not be null
        Returns:
        true if no value or returns the result of the application of the given function to the value.

      • isEmpty

        public final boolean isEmpty()
        If the type does not contain a value return true.
        Specified by:
        isEmpty in interface Maybe<A>
        Returns:
        true if this does not hold a value, false otherwise.

      • iterator

        public final java.util.Iterator<A> iterator()
        Return an iterator for this type. In most cases this takes the form of an iterator returning zero or one values.
        Specified by:
        iterator in interface java.lang.Iterable<A>
        Specified by:
        iterator in interface Maybe<A>
        Returns:
        an iterator over the contained value if defined, or an empty one otherwise.

      • map

        public final <B> Option<B> map​(java.util.function.Function<? super A,​? extends B> f)
        Apply f to the value if defined.

        Transforms to an option of the result type.

        Type Parameters:
        B - return type of f
        Parameters:
        f - function to apply to wrapped value
        Returns:
        new wrapped value

      • flatMap

        public final <B> Option<B> flatMap​(java.util.function.Function<? super A,​? extends Option<? extends B>> f)
        Apply f to the value if defined.

        Transforms to an option of the result type.

        Type Parameters:
        B - return type of f
        Parameters:
        f - function to apply to wrapped value
        Returns:
        value returned from f

      • filter

        public final Option<A> filter​(java.util.function.Predicate<? super A> p)
        Returns this Option if it is nonempty and applying the predicate to this option's value returns true. Otherwise, return none().
        Parameters:
        p - the predicate to test
        Returns:
        this option, or none

      • filterNot

        public final Option<A> filterNot​(java.util.function.Predicate<? super A> p)
        Returns this Option if it is nonempty and applying the predicate to this option's value returns false. Otherwise, return none().
        Parameters:
        p - the predicate to test
        Returns:
        this option, or none
        Since:
        6.1

      • toRight

        public final <X> Either<X,​A> toRight​(java.util.function.Supplier<X> left)
        Creates an Either from this Option. Puts the contained value in a right if Maybe.isDefined() otherwise puts the supplier's value in a left.
        Type Parameters:
        X - the left type
        Parameters:
        left - the Supplier to evaluate and return if this is empty
        Returns:
        the content of this option if defined as a right, or the supplier's content as a left if not
        See Also:
        toLeft(java.util.function.Supplier<X>)

      • toLeft

        public final <X> Either<A,​X> toLeft​(java.util.function.Supplier<X> right)
        Creates an Either from this Option. Puts the contained value in a left if Maybe.isDefined() otherwise puts the supplier's value in a right.
        Type Parameters:
        X - the right type
        Parameters:
        right - the Supplier to evaluate and return if this is empty
        Returns:
        the content of this option if defined as a left, or the supplier's content as a right if not defined.
        See Also:
        toRight(java.util.function.Supplier<X>)

      • toOptional

        public abstract java.util.Optional<A> toOptional()
        Create an Optional from this option. Will throw a NullPointerException if this option is defined and contains a null value.
        Returns:
        Optional.of(Object) with the value if defined and not null, Optional.empty() if not defined.

      • toStream

        public abstract java.util.stream.Stream<A> toStream()
        Create a Stream from this option.
        Returns:
        Stream.of(Object) with the value if defined, Stream.empty() if not defined.
        Since:
        4.5.0

      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public final boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • toString

        public final java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • valuesEqual

        private java.util.function.Function<java.lang.Object,​java.lang.Boolean> valuesEqual()