org.wandora.utils

Class Option<T>

java.lang.Object

org.wandora.utils.Option<T>

All Implemented Interfaces:

java.lang.Iterable<T>

public class Option<T>
extends java.lang.Object
implements java.lang.Iterable<T>

Use Option<T> instead of T as a function return or argument type to signal that it might be null. The key benefit is that usage that might throw NullPointerException is statically prevented by the compiler. Accessing the value works either through iteration (option implements Iterable<T>) or through the value() getter that throws a checked exception if the value is null.
To create a value, use Option.some(x) and to create a null object, use Option.none(). To use a value, "iterate" over the value or use a try/catch with the getter, or use one of the various member functions to access the value in some other manner (for example mapping it to a function or extracting the value with a default value)

 for(Value val : tryGetItem())
     list.addItem(val);
 
 // as opposed to
 
 Value val = tryGetItem();
 if(val != null)
     list.addItem(val);
 
 // or the potential NullPointerException situation:
 Value val = tryGetItem();
 list.addItem(val);
 

Example usage (method of a class storing key/value pairs):

 class Storage<KeyT, ValueT> {
     public Option<ValueT> get(KeyT key) {
         ValueT value = find(key);
         if(value == null)
             return Option.none();
         else
             return Option.some(value);
     }
 
     ...
 }
 

Author:

anttirt

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Option.EmptyOptionException A checked exception that is thrown if the value getter is used on an empty Option.

Field Summary

Fields

Modifier and Type	Field and Description
private static Option	none_
private T	value_

Constructor Summary

Constructors

Modifier	Constructor and Description
private	Option()
private	Option(T val)

Method Summary

Modifier and Type	Method and Description
void	apply(Functional.Pr1<? super T> f) opt.apply(f) is the same as for(Object val : opt) f.invoke(val);
boolean	empty() Checks whether this instance contains a value.
boolean	equals(java.lang.Object other)
<R> Option<R>	flatMap(Functional.Fn1<Option<R>,? super T> f) Essentially the map operation from functional programming where Option is a list that contains either 0 or 1 elements.
T	getOrElse(Functional.Fn0<? extends T> f) Gets the value of this Option or if no value exists returns the result of f
T	getOrElse(T other) Gets the value of this Option or if no value exists, returns other
int	hashCode()
static <U,C extends java.util.Collection<U>> Functional.Pr1<U>	inserter(C collection) A convenience procedure that can be used with Option.apply to add the value of an Option into a Collection:
java.util.Iterator<T>	iterator() Creates an iterator that treats the Option as a list that contains either 0 or 1 elements.
<R> Option<R>	map(Delegate<R,? super T> f) Essentially the map operation from functional programming where Option is a list that contains either 0 or 1 elements.
<R> Option<R>	map(Functional.Fn1<R,? super T> f) Essentially the map operation from functional programming where Option is a list that contains either 0 or 1 elements.
<R> R	mapOrElse(Delegate<R,? super T> f, Functional.Fn0<R> g) Maps the value through f or if no value exists returns the result of g
<R> R	mapOrElse(Delegate<R,? super T> f, R other) Maps the value through f or if no value exists returns other
<R> R	mapOrElse(Functional.Fn1<R,? super T> f, Functional.Fn0<R> g) Maps the value through f or if no value exists returns the result of g
<R> R	mapOrElse(Functional.Fn1<R,? super T> f, R other) Maps the value through f or if no value exists returns other
static <T> Option<T>	none() Returns an Option that represents null
Option<T>	or(Option<? extends T> other) Replaces this with other if this is empty, otherwise yields this.
Option<T>	or(T other) Replaces this with other if this is empty, otherwise yields this.
static <U extends java.lang.Runnable> Functional.Pr1<U>	runner() A convenience procedure that can be used with Option.apply to run the value of an Option<T extends Runnable>
static <T> Option<T>	some(T val) Creates an Option that contains a non-null value
static <T,C extends java.util.Collection<Option<T>>> java.util.Collection<T>	somes(C col) Creates a collection containing only the actual values from a collection of options
T	value() Throws a checked exception if the value is null, in order to prevent situations where NullPointerException is thrown from arising.

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

none_

private static final Option none_

value_

private final T value_

Constructor Detail

Option

private Option()

Option

private Option(T val)

Method Detail

some

public static <T> Option<T> some(T val)

Creates an Option that contains a non-null value

Parameters:

The - value to encapsulate

Returns:

none

public static <T> Option<T> none()

Returns an Option that represents null

Returns:

iterator

public java.util.Iterator<T> iterator()

Creates an iterator that treats the Option as a list that contains either 0 or 1 elements.

Specified by:

iterator in interface java.lang.Iterable<T>

Returns:

A new iterator over this Option instance

map

public <R> Option<R> map(Delegate<R,? super T> f)

Essentially the map operation from functional programming where Option is a list that contains either 0 or 1 elements.

Parameters:

f - A function to call on the value contained in this instance.

Returns:

some(delegate.invoke(value)) if value is not null, none() otherwise

map

public <R> Option<R> map(Functional.Fn1<R,? super T> f)

Essentially the map operation from functional programming where Option is a list that contains either 0 or 1 elements.

Parameters:

f - A function to call on the value contained in this instance.

Returns:

some(delegate.invoke(value)) if value is not null, none() otherwise

flatMap

public <R> Option<R> flatMap(Functional.Fn1<Option<R>,? super T> f)

Essentially the map operation from functional programming where Option is a list that contains either 0 or 1 elements. flatMap additionally unwraps the result of the call to the passed function, so as to not result in Option<Option<U>> where R = Option<U> Also corresponds to the >>= operation for monads.

Parameters:

f - A function to call on the value contained in this instance.

Returns:

f.invoke(value) if value is not null, none() otherwise

apply

public void apply(Functional.Pr1<? super T> f)

opt.apply(f) is the same as for(Object val : opt) f.invoke(val);

Parameters:

f - The function that is invoked if a value exists

getOrElse

public T getOrElse(Functional.Fn0<? extends T> f)

Gets the value of this Option or if no value exists returns the result of f

Parameters:

f - The function to call if this Option is empty

Returns:

value if not null, f.invoke() otherwise

getOrElse

public T getOrElse(T other)

Gets the value of this Option or if no value exists, returns other

Parameters:

other - The value to return if this Option is empty

Returns:

value if not null, other otherwise

mapOrElse

public <R> R mapOrElse(Delegate<R,? super T> f,
                       Functional.Fn0<R> g)

Maps the value through f or if no value exists returns the result of g

Parameters:

f - The function to call if a value exists

g - The function to call otherwise

Returns:

f.invoke(value) if value is not null, g.invoke() otherwise

mapOrElse

public <R> R mapOrElse(Delegate<R,? super T> f,
                       R other)

Maps the value through f or if no value exists returns other

Parameters:

f - The function to call if a value exists

other - The value to return otherwise

Returns:

f.invoke(value) if value is not null, other otherwise

mapOrElse

public <R> R mapOrElse(Functional.Fn1<R,? super T> f,
                       Functional.Fn0<R> g)

Maps the value through f or if no value exists returns the result of g

Parameters:

f - The function to call if a value exists

g - The function to call otherwise

Returns:

f.invoke(value) if value is not null, g.invoke() otherwise

mapOrElse

public <R> R mapOrElse(Functional.Fn1<R,? super T> f,
                       R other)

Maps the value through f or if no value exists returns other

Parameters:

f - The function to call if a value exists

other - The value to return otherwise

Returns:

f.invoke(value) if value is not null, other otherwise

or

public Option<T> or(Option<? extends T> other)

Replaces this with other if this is empty, otherwise yields this.

Parameters:

other -

Returns:

or

public Option<T> or(T other)

Replaces this with other if this is empty, otherwise yields this.

Parameters:

other -

Returns:

value

public T value()
        throws Option.EmptyOptionException

Throws a checked exception if the value is null, in order to prevent situations where NullPointerException is thrown from arising.

Returns:

The contained value.

Throws:

Option.EmptyOptionException

empty

public boolean empty()

Checks whether this instance contains a value.

Returns:

true if this instance contains a value.

equals

public boolean equals(java.lang.Object other)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

somes

public static <T,C extends java.util.Collection<Option<T>>> java.util.Collection<T> somes(C col)

Creates a collection containing only the actual values from a collection of options

Parameters:

col - The Collection to filter

Returns:

The resulting Collection of non-null values

inserter

public static <U,C extends java.util.Collection<U>> Functional.Pr1<U> inserter(C collection)

A convenience procedure that can be used with Option.apply to add the value of an Option into a Collection:

 List<String> foo;
 getOpt(bar).apply(Option.inserter(foo));
 

Parameters:

collection - A Collection into which the value will be added if it exists

Returns:

A function that inserts its argument into collection

runner

public static <U extends java.lang.Runnable> Functional.Pr1<U> runner()

A convenience procedure that can be used with Option.apply to run the value of an Option<T extends Runnable>

 getProc().apply(Option.runner());
 

Returns:

A function that calls .run() on its argument