Option (Functional Extensions Library 4.5.1 API)

java.lang.Object
- io.atlassian.fugue.Option<A>

Type Parameters:

A - the value type the option contains

All Implemented Interfaces:

Effect.Applicant<A>, Maybe<A>, Serializable, Iterable<A>
```
public abstract class Option<A>
extends Object
implements Iterable<A>, Maybe<A>, 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

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static <A> Predicate<Option<A>>`	`defined()` Predicate for filtering defined options only.
`boolean`	`equals(Object obj)`
`boolean`	`exists(Predicate<? super A> p)` Whether this is `is defined` and applying the predicate to the contained value returns true.
`Option<A>`	`filter(Predicate<? super A> p)` Returns this `Option` if it is nonempty and applying the predicate to this option's value returns true.
`<B> Option<B>`	`flatMap(Function<? super A,? extends Option<? extends B>> f)` Apply `f` to the value if defined.
`abstract <B> B`	`fold(Supplier<? extends B> none, Function<? super A,? extends B> some)` If this is a some value apply the some function, otherwise get the None value.
`boolean`	`forall(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(Optional<A> optional)` Factory method for `Option` instances from `Optional` instances.
`A`	`getOr(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(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.
`Iterator<A>`	`iterator()` Return an iterator for this type.
`<B> Option<B>`	`map(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(Class<A> type)` Factory method for None instances where the type token is handy.
`static <A> 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(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(Supplier<X> right)` Creates an Either from this Option.
`abstract Optional<A>`	`toOptional()` Create an `Optional` from this option.
`<X> Either<X,A>`	`toRight(Supplier<X> left)` Creates an Either from this Option.
`abstract Stream<A>`	`toStream()` Create a `Stream` from this option.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface io.atlassian.fugue.Maybe
get, getOrError, getOrThrow, isDefined

Methods inherited from interface java.lang.Iterable
forEach, spliterator

Methods inherited from interface io.atlassian.fugue.Effect.Applicant
foreach

- 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:
 
 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(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> 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> 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(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 fold(Supplier<? extends B> none,
 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  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(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(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(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(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(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 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 Maybe<A>
 
 Specified by:
 
 iterator in interface Iterable<A>
 
 Returns:
 
 an iterator over the contained value if defined, or an empty one otherwise.
 - map
```
public final  Option map(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  Option flatMap(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(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
 - toRight
```
public final <X> Either<X,A> toRight(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(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 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 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 Object
 - equals
```
public final boolean equals(Object obj)
```
 Overrides:
 
 equals in class Object
 - toString
```
public final String toString()
```
 Overrides:
 
 toString in class Object

Class Option<A>

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface io.atlassian.fugue.Maybe

Methods inherited from interface java.lang.Iterable

Methods inherited from interface io.atlassian.fugue.Effect.Applicant

Method Detail

option

some

none

none

defined

noneSupplier

fromOptional

fold

getOrElse

getOr

getOrElse

getOrNull

orElse

orElse

exists

forall

isEmpty

iterator

map

flatMap

filter

toRight

toLeft

toOptional

toStream

hashCode

equals

toString