Option (Functional Guava Extensions 2.4.0 API)

java.lang.Object
- com.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

Methods
Modifier and Type	Method and Description
`static <A> com.google.common.base.Predicate<Option<A>>`	`defined()` Predicate for filtering defined options only.
`boolean`	`equals(Object obj)`
`boolean`	`exists(com.google.common.base.Predicate<? super A> p)` Whether this is `is defined` and applying the predicate to the contained value returns true.
`Option<A>`	`filter(com.google.common.base.Predicate<? super A> p)` Returns this `Option` if it is nonempty and applying the predicate to this option's value returns true.
`static <A> Iterable<Option<A>>`	`filterNone(Iterable<Option<A>> options)` Deprecated. since 1.1 use `Options.filterNone(Iterable)` instead
`static <A> Option<A>`	`find(Iterable<Option<A>> options)` Deprecated. since 1.1 use `Options.find(Iterable)` instead
`<B> Option<B>`	`flatMap(com.google.common.base.Function<? super A,? extends Option<? extends B>> f)` Apply `f` to the value if defined.
`abstract <B> B`	`fold(com.google.common.base.Supplier<? extends B> none, com.google.common.base.Function<? super A,? extends B> some)` If this is a some value apply the some function, otherwise get the None value.
`boolean`	`forall(com.google.common.base.Predicate<? super A> p)` Returns `true` `if empty` or the result of the application of the given function to the value.
`<B extends A> A`	`getOrElse(B other)` Get the value if defined, otherwise returns `other`.
`A`	`getOrElse(com.google.common.base.Supplier<? extends A> supplier)` Get the value `if defined` or call the supplier and return its value if not.
`A`	`getOrNull()` Get the value if defined or null if not.
`int`	`hashCode()`
`boolean`	`isEmpty()`
`Iterator<A>`	`iterator()`
`<B> Option<B>`	`map(com.google.common.base.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> com.google.common.base.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(com.google.common.base.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(com.google.common.base.Supplier<X> right)` Creates an Either from this Option.
`<X> Either<X,A>`	`toRight(com.google.common.base.Supplier<X> left)` Creates an Either from this Option.
`String`	`toString()`

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

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

Methods inherited from interface com.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
 
 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> com.google.common.base.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> com.google.common.base.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
 - find
```
@Deprecated
public static <A> Option<A> find(Iterable<Option<A>> options)
```
 Deprecated. since 1.1 use Options.find(Iterable) instead
 
 Find the first option that isDefined, or if there aren't any, then None.
 
 Type Parameters:
 A - the contained type
 Parameters:
 options - an Iterable of options to search through
 
 Returns:
 the first option that isDefined, or none
 - filterNone
```
@Deprecated
public static <A> Iterable<Option<A>> filterNone(Iterable<Option<A>> options)
```
 Deprecated. since 1.1 use Options.filterNone(Iterable) instead
 
 Filter out undefined options.
 
 Type Parameters:
 A - the contained type
 Parameters:
 options - many options that may or may not be defined
 
 Returns:
 the filtered options
 - fold
```
public abstract  B fold(com.google.common.base.Supplier<? extends B> none,
 com.google.common.base.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)
```
 Description copied from interface: Maybe
 
 Get the value if defined, otherwise returns other.
 
 Specified by:
 
 getOrElse in interface Maybe<A>
 
 Type Parameters:
 B - the destination type
 Parameters:
 other - value to return if this is empty
 
 Returns:
 wrapped value if this is defined, otherwise returns other
 - getOrElse
```
public final A getOrElse(com.google.common.base.Supplier<? extends A> supplier)
```
 Description copied from interface: Maybe
 
 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()
```
 Description copied from interface: Maybe
 
 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(com.google.common.base.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(com.google.common.base.Predicate<? super A> p)
```
 Description copied from interface: Maybe
 
 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
 
 Returns:
 true if defined and the predicate returns true for the contained value, false otherwise.
 - forall
```
public boolean forall(com.google.common.base.Predicate<? super A> p)
```
 Description copied from interface: Maybe
 
 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.
 
 Returns:
 true if no value or returns the result of the application of the given function to the value.
 - isEmpty
```
public final boolean isEmpty()
```
 Specified by:
 
 isEmpty in interface Maybe<A>
 
 Returns:
 true if this does not hold a value, false otherwise.
 - iterator
```
public final Iterator<A> iterator()
```
 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(com.google.common.base.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(com.google.common.base.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(com.google.common.base.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(com.google.common.base.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
 - toLeft
```
public final <X> Either<A,X> toLeft(com.google.common.base.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
 - 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 com.atlassian.fugue.Maybe

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

Method Detail

option

some

none

none

defined

noneSupplier

find

filterNone

fold

getOrElse

getOrElse

getOrNull

orElse

orElse

exists

forall

isEmpty

iterator

map

flatMap

filter

toRight

toLeft

hashCode

equals

toString