Copyright 2008 - 2009 Tony Morris, Runar Bjarnason, Tom Adams, Brad Clow, Ricky Clarkson

This software is released under an open source BSD licence.

fj.data
Class Option<A>

java.lang.Object
  extended by fj.data.Option<A>
All Implemented Interfaces:
Iterable<A>

public abstract class Option<A>
extends Object
implements Iterable<A>

An optional value that may be none (no value) or some (a value). This type is a replacement for the use of null with better type checks.

Version:
2.20

Method Summary
<B> Option<B>
apply(Option<F<A,B>> of)
          Performs function application within an optional value (applicative functor pattern).
static
<A,B> F<F<A,Option<B>>,F<Option<A>,Option<B>>>
bind()
          First-class bind function.
<B> Option<B>
bind(F<A,Option<B>> f)
          Binds the given function across the element of this optional value with a final join.
<B,C> Option<C>
bind(Option<B> ob, F<A,F<B,C>> f)
          Binds the given function across the element of this optional value and the given optional value with a final join.
<B,C,D> Option<D>
bind(Option<B> ob, Option<C> oc, F<A,F<B,F<C,D>>> f)
          Binds the given function across the element of this optional value and the given optional value with a final join.
<B,C,D,E> Option<E>
bind(Option<B> ob, Option<C> oc, Option<D> od, F<A,F<B,F<C,F<D,E>>>> f)
          Binds the given function across the element of this optional value and the given optional value with a final join.
<B,C,D,E,F$>
Option<F$>
bind(Option<B> ob, Option<C> oc, Option<D> od, Option<E> oe, F<A,F<B,F<C,F<D,F<E,F$>>>>> f)
          Binds the given function across the element of this optional value and the given optional value with a final join.
<B,C,D,E,F$,G>
Option<G>
bind(Option<B> ob, Option<C> oc, Option<D> od, Option<E> oe, Option<F$> of, F<A,F<B,F<C,F<D,F<E,F<F$,G>>>>>> f)
          Binds the given function across the element of this optional value and the given optional value with a final join.
<B,C,D,E,F$,G,H>
Option<H>
bind(Option<B> ob, Option<C> oc, Option<D> od, Option<E> oe, Option<F$> of, Option<G> og, F<A,F<B,F<C,F<D,F<E,F<F$,F<G,H>>>>>>> f)
          Binds the given function across the element of this optional value and the given optional value with a final join.
<B,C,D,E,F$,G,H,I>
Option<I>
bind(Option<B> ob, Option<C> oc, Option<D> od, Option<E> oe, Option<F$> of, Option<G> og, Option<H> oh, F<A,F<B,F<C,F<D,F<E,F<F$,F<G,F<H,I>>>>>>>> f)
          Binds the given function across the element of this optional value and the given optional value with a final join.
 boolean exists(F<A,Boolean> f)
          Returns true is this optional value has a value and the given predicate function holds on that value, false otherwise.
 Option<A> filter(F<A,Boolean> f)
          Filters elements from this optional value by returning only elements which produce true when the given function is applied to them.
 boolean forall(F<A,Boolean> f)
          Returns true if this optional value has no value, or the predicate holds for the given predicate function, false otherwise.
 void foreach(Effect<A> f)
          Performs a side-effect for the value of this optional value.
 Unit foreach(F<A,Unit> f)
          Performs a side-effect for the value of this optional value.
static
<T> Option<T>
fromNull(T t)
          Turns an unsafe nullable value into a safe optional value.
static
<A> F<Option<A>,A>
fromSome()
          Returns a function that takes an optional value to a value or errors if there is no value.
static F<String,Option<String>> fromString()
          Returns a function that transforms a string to an optional non-empty string, or no value if the string is empty.
static Option<String> fromString(String s)
          Returns an optional non-empty string, or no value if the given string is empty.
static
<A> F2<F<A,Boolean>,A,Option<A>>
iif()
          First-class version of the iif function.
static
<A> Option<A>
iif(F<A,Boolean> f, A a)
          Returns an optional value that has a value of the given argument, if the given predicate holds on that argument, otherwise, returns no value.
static
<A> F<Option<A>,Boolean>
isNone_()
          A first-class version of the isNone method.
 boolean isNone()
          Returns false if this optional value has a value, true otherwise.
static
<A> F<Option<A>,Boolean>
isSome_()
          A first-class version of the isSome method.
 boolean isSome()
          Returns true if this optional value has a value, false otherwise.
 Iterator<A> iterator()
          Returns an iterator for this optional value.
static
<A> F<Option<Option<A>>,Option<A>>
join()
          First-class join function.
static
<A> Option<A>
join(Option<Option<A>> o)
          Joins the given optional value of optional value using a bind operation.
 int length()
          Returns the length of this optional value; 1 is there is a value, 0 otherwise.
static
<A,B,C> F<Option<A>,F<Option<B>,Option<C>>>
liftM2(F<A,F<B,C>> f)
          Promotes a function of arity-2 so that it operates over options.
static
<A,B> F<F<A,B>,F<Option<A>,Option<B>>>
map()
          A first-class map function.
<B> Option<B>
map(F<A,B> f)
          Maps the given function across this optional value.
static
<T> Option<T>
none()
          Constructs an optional value that has no value.
<B> B
option(B b, F<A,B> f)
          Performs a reduction on this optional value using the given arguments.
 Option<A> orElse(Option<A> o)
          Returns this optional value if there is one, otherwise, returns the argument optional value.
 Option<A> orElse(P1<Option<A>> o)
          Returns this optional value if there is one, otherwise, returns the argument optional value.
 A orSome(A a)
          Returns the value of this optional value or the given argument.
 A orSome(P1<A> a)
          Returns the value of this optional value or the given argument.
static
<A> Option<List<A>>
sequence(List<Option<A>> a)
          Sequence through the option monad.
<B> Option<B>
sequence(Option<B> o)
          Performs a bind across the optional value, but ignores the element value in the function.
static
<T> F<T,Option<T>>
some_()
           
abstract  A some()
          Returns the value from this optional value, or fails if there is no value.
static
<T> Option<T>
some(T t)
          Constructs an optional value that has a value of the given argument.
static
<A> List<A>
somes(List<Option<A>> as)
          Returns all the values in the given list.
static
<A> Stream<A>
somes(Stream<Option<A>> as)
          Returns all the values in the given stream.
 Array<A> toArray()
          Returns an array projection of this optional value.
 Array<A> toArray(Class<A[]> c)
          Returns an array projection of this optional value.
 Collection<A> toCollection()
          Projects an immutable collection of this optional value.
static
<A,X> F<Option<A>,F<X,Either<X,A>>>
toEither()
          A first-class version of the toEither method.
<X> Either<X,A>
toEither(P1<X> x)
          Returns an either projection of this optional value; the given argument in Left if no value, or the value in Right.
<X> Either<X,A>
toEither(X x)
          Returns an either projection of this optional value; the given argument in Left if no value, or the value in Right.
 List<A> toList()
          Returns a list projection of this optional value.
 Stream<A> toStream()
          Returns a stream projection of this optional value.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

iterator

public Iterator<A> iterator()
Returns an iterator for this optional value. This method exists to permit the use in a for-each loop.

Specified by:
iterator in interface Iterable<A>
Returns:
A iterator for this optional value.

some

public abstract A some()
Returns the value from this optional value, or fails if there is no value.

Returns:
The value from this optional value, or fails if there is no value.

isSome

public boolean isSome()
Returns true if this optional value has a value, false otherwise.

Returns:
true if this optional value has a value, false otherwise.

isNone

public boolean isNone()
Returns false if this optional value has a value, true otherwise.

Returns:
false if this optional value has a value, true otherwise.

isSome_

public static <A> F<Option<A>,Boolean> isSome_()
A first-class version of the isSome method.

Returns:
A function that returns true if a given optional value has a value, otherwise false.

isNone_

public static <A> F<Option<A>,Boolean> isNone_()
A first-class version of the isNone method.

Returns:
A function that returns false if a given optional value has a value, otherwise true.

option

public <B> B option(B b,
                    F<A,B> f)
Performs a reduction on this optional value using the given arguments.

Parameters:
b - The value to return if this optional value has no value.
f - The function to apply to the value of this optional value.
Returns:
A reduction on this optional value.

length

public int length()
Returns the length of this optional value; 1 is there is a value, 0 otherwise.

Returns:
The length of this optional value; 1 is there is a value, 0 otherwise.

orSome

public A orSome(P1<A> a)
Returns the value of this optional value or the given argument.

Parameters:
a - The argument to return if this optiona value has no value.
Returns:
The value of this optional value or the given argument.

orSome

public A orSome(A a)
Returns the value of this optional value or the given argument.

Parameters:
a - The argument to return if this optiona value has no value.
Returns:
The value of this optional value or the given argument.

map

public <B> Option<B> map(F<A,B> f)
Maps the given function across this optional value.

Parameters:
f - The function to map across this optional value.
Returns:
A new optional value after the given function has been applied to its element.

map

public static <A,B> F<F<A,B>,F<Option<A>,Option<B>>> map()
A first-class map function.

Returns:
A function that maps a given function across a given optional value.

foreach

public Unit foreach(F<A,Unit> f)
Performs a side-effect for the value of this optional value.

Parameters:
f - The side-effect to perform for the given element.
Returns:
The unit value.

foreach

public void foreach(Effect<A> f)
Performs a side-effect for the value of this optional value.

Parameters:
f - The side-effect to perform for the given element.

filter

public Option<A> filter(F<A,Boolean> f)
Filters elements from this optional value by returning only elements which produce true when the given function is applied to them.

Parameters:
f - The predicate function to filter on.
Returns:
A new optional value whose value matches the given predicate if it has one.

bind

public <B> Option<B> bind(F<A,Option<B>> f)
Binds the given function across the element of this optional value with a final join.

Parameters:
f - The function to apply to the element of this optional value.
Returns:
A new optional value after performing the map, then final join.

bind

public <B,C> Option<C> bind(Option<B> ob,
                            F<A,F<B,C>> f)
Binds the given function across the element of this optional value and the given optional value with a final join.

Parameters:
ob - A given optional value to bind the given function with.
f - The function to apply to the element of this optional value and the given optional value.
Returns:
A new optional value after performing the map, then final join.

bind

public <B,C,D> Option<D> bind(Option<B> ob,
                              Option<C> oc,
                              F<A,F<B,F<C,D>>> f)
Binds the given function across the element of this optional value and the given optional value with a final join.

Parameters:
ob - A given optional value to bind the given function with.
oc - A given optional value to bind the given function with.
f - The function to apply to the element of this optional value and the given optional value.
Returns:
A new optional value after performing the map, then final join.

bind

public <B,C,D,E> Option<E> bind(Option<B> ob,
                                Option<C> oc,
                                Option<D> od,
                                F<A,F<B,F<C,F<D,E>>>> f)
Binds the given function across the element of this optional value and the given optional value with a final join.

Parameters:
ob - A given optional value to bind the given function with.
oc - A given optional value to bind the given function with.
od - A given optional value to bind the given function with.
f - The function to apply to the element of this optional value and the given optional value.
Returns:
A new optional value after performing the map, then final join.

bind

public <B,C,D,E,F$> Option<F$> bind(Option<B> ob,
                                    Option<C> oc,
                                    Option<D> od,
                                    Option<E> oe,
                                    F<A,F<B,F<C,F<D,F<E,F$>>>>> f)
Binds the given function across the element of this optional value and the given optional value with a final join.

Parameters:
ob - A given optional value to bind the given function with.
oc - A given optional value to bind the given function with.
od - A given optional value to bind the given function with.
oe - A given optional value to bind the given function with.
f - The function to apply to the element of this optional value and the given optional value.
Returns:
A new optional value after performing the map, then final join.

bind

public <B,C,D,E,F$,G> Option<G> bind(Option<B> ob,
                                     Option<C> oc,
                                     Option<D> od,
                                     Option<E> oe,
                                     Option<F$> of,
                                     F<A,F<B,F<C,F<D,F<E,F<F$,G>>>>>> f)
Binds the given function across the element of this optional value and the given optional value with a final join.

Parameters:
ob - A given optional value to bind the given function with.
oc - A given optional value to bind the given function with.
od - A given optional value to bind the given function with.
oe - A given optional value to bind the given function with.
of - A given optional value to bind the given function with.
f - The function to apply to the element of this optional value and the given optional value.
Returns:
A new optional value after performing the map, then final join.

bind

public <B,C,D,E,F$,G,H> Option<H> bind(Option<B> ob,
                                       Option<C> oc,
                                       Option<D> od,
                                       Option<E> oe,
                                       Option<F$> of,
                                       Option<G> og,
                                       F<A,F<B,F<C,F<D,F<E,F<F$,F<G,H>>>>>>> f)
Binds the given function across the element of this optional value and the given optional value with a final join.

Parameters:
ob - A given optional value to bind the given function with.
oc - A given optional value to bind the given function with.
od - A given optional value to bind the given function with.
oe - A given optional value to bind the given function with.
of - A given optional value to bind the given function with.
og - A given optional value to bind the given function with.
f - The function to apply to the element of this optional value and the given optional value.
Returns:
A new optional value after performing the map, then final join.

bind

public <B,C,D,E,F$,G,H,I> Option<I> bind(Option<B> ob,
                                         Option<C> oc,
                                         Option<D> od,
                                         Option<E> oe,
                                         Option<F$> of,
                                         Option<G> og,
                                         Option<H> oh,
                                         F<A,F<B,F<C,F<D,F<E,F<F$,F<G,F<H,I>>>>>>>> f)
Binds the given function across the element of this optional value and the given optional value with a final join.

Parameters:
ob - A given optional value to bind the given function with.
oc - A given optional value to bind the given function with.
od - A given optional value to bind the given function with.
oe - A given optional value to bind the given function with.
of - A given optional value to bind the given function with.
og - A given optional value to bind the given function with.
oh - A given optional value to bind the given function with.
f - The function to apply to the element of this optional value and the given optional value.
Returns:
A new optional value after performing the map, then final join.

sequence

public <B> Option<B> sequence(Option<B> o)
Performs a bind across the optional value, but ignores the element value in the function.

Parameters:
o - The optional value to apply in the final join.
Returns:
A new optional value after the final join.

apply

public <B> Option<B> apply(Option<F<A,B>> of)
Performs function application within an optional value (applicative functor pattern).

Parameters:
of - The optional value of functions to apply.
Returns:
A new optional value after applying the given optional value of functions through this optional value.

orElse

public Option<A> orElse(P1<Option<A>> o)
Returns this optional value if there is one, otherwise, returns the argument optional value.

Parameters:
o - The optional value to return if this optional value has no value.
Returns:
This optional value if there is one, otherwise, returns the argument optional value.

orElse

public Option<A> orElse(Option<A> o)
Returns this optional value if there is one, otherwise, returns the argument optional value.

Parameters:
o - The optional value to return if this optional value has no value.
Returns:
This optional value if there is one, otherwise, returns the argument optional value.

toEither

public <X> Either<X,A> toEither(P1<X> x)
Returns an either projection of this optional value; the given argument in Left if no value, or the value in Right.

Parameters:
x - The value to return in left if this optional value has no value.
Returns:
An either projection of this optional value.

toEither

public <X> Either<X,A> toEither(X x)
Returns an either projection of this optional value; the given argument in Left if no value, or the value in Right.

Parameters:
x - The value to return in left if this optional value has no value.
Returns:
An either projection of this optional value.

toEither

public static <A,X> F<Option<A>,F<X,Either<X,A>>> toEither()
A first-class version of the toEither method.

Returns:
A function that returns an either projection of a given optional value, given a value to return in left.

toList

public List<A> toList()
Returns a list projection of this optional value.

Returns:
A list projection of this optional value.

toStream

public Stream<A> toStream()
Returns a stream projection of this optional value.

Returns:
A stream projection of this optional value.

toArray

public Array<A> toArray()
Returns an array projection of this optional value.

Returns:
An array projection of this optional value.

toArray

public Array<A> toArray(Class<A[]> c)
Returns an array projection of this optional value.

Parameters:
c - The class type of the array to return.
Returns:
An array projection of this optional value.

forall

public boolean forall(F<A,Boolean> f)
Returns true if this optional value has no value, or the predicate holds for the given predicate function, false otherwise.

Parameters:
f - the predicate function to test on the value of this optional value.
Returns:
true if this optional value has no value, or the predicate holds for the given predicate function, false otherwise.

exists

public boolean exists(F<A,Boolean> f)
Returns true is this optional value has a value and the given predicate function holds on that value, false otherwise.

Parameters:
f - the predicate function to test on the value of this optional value.
Returns:
true is this optional value has a value and the given predicate function holds on that value, false otherwise.

toCollection

public Collection<A> toCollection()
Projects an immutable collection of this optional value.

Returns:
An immutable collection of this optional value.

some_

public static <T> F<T,Option<T>> some_()

some

public static <T> Option<T> some(T t)
Constructs an optional value that has a value of the given argument.

Parameters:
t - The value for the returned optional value.
Returns:
An optional value that has a value of the given argument.

none

public static <T> Option<T> none()
Constructs an optional value that has no value.

Returns:
An optional value that has no value.

fromNull

public static <T> Option<T> fromNull(T t)
Turns an unsafe nullable value into a safe optional value. If t == null then return none, otherwise, return the given value in some.

Parameters:
t - The unsafe nullable value.
Returns:
If t == null then return it in some, otherwise, return none.

join

public static <A> Option<A> join(Option<Option<A>> o)
Joins the given optional value of optional value using a bind operation.

Parameters:
o - The optional value of optional value to join.
Returns:
A new optional value that is the join of the given optional value.

sequence

public static <A> Option<List<A>> sequence(List<Option<A>> a)
Sequence through the option monad.

Parameters:
a - The list of option to sequence.
Returns:
The option of list after sequencing.

iif

public static <A> Option<A> iif(F<A,Boolean> f,
                                A a)
Returns an optional value that has a value of the given argument, if the given predicate holds on that argument, otherwise, returns no value.

Parameters:
f - The predicate to test on the given argument.
a - The argument to test the predicate on and potentially use as the value of the returned optional value.
Returns:
an optional value that has a value of the given argument, if the given predicate holds on that argument, otherwise, returns no value.

iif

public static <A> F2<F<A,Boolean>,A,Option<A>> iif()
First-class version of the iif function.

Returns:
a function that returns an optional value that has a value of the given argument, if the given predicate holds on that argument, or no value otherwise.

somes

public static <A> List<A> somes(List<Option<A>> as)
Returns all the values in the given list.

Parameters:
as - The list of potential values to get actual values from.
Returns:
All the values in the given list.

somes

public static <A> Stream<A> somes(Stream<Option<A>> as)
Returns all the values in the given stream.

Parameters:
as - The stream of potential values to get actual values from.
Returns:
All the values in the given stream.

fromString

public static Option<String> fromString(String s)
Returns an optional non-empty string, or no value if the given string is empty.

Parameters:
s - A string to turn into an optional non-empty string.
Returns:
an optional non-empty string, or no value if the given string is empty.

fromString

public static F<String,Option<String>> fromString()
Returns a function that transforms a string to an optional non-empty string, or no value if the string is empty.

Returns:
a function that transforms a string to an optional non-empty string, or no value if the string is empty.

fromSome

public static <A> F<Option<A>,A> fromSome()
Returns a function that takes an optional value to a value or errors if there is no value.

Returns:
A function that takes an optional value to a value or errors if there is no value.

liftM2

public static <A,B,C> F<Option<A>,F<Option<B>,Option<C>>> liftM2(F<A,F<B,C>> f)
Promotes a function of arity-2 so that it operates over options.

Parameters:
f - A function to promote.
Returns:
The given function promoted to operate on options.

bind

public static <A,B> F<F<A,Option<B>>,F<Option<A>,Option<B>>> bind()
First-class bind function.

Returns:
A function that binds a given function across an option with a final join.

join

public static <A> F<Option<Option<A>>,Option<A>> join()
First-class join function.

Returns:
A function that joins an Option of an Option to make a single Option.

Copyright 2008 - 2009 Tony Morris, Runar Bjarnason, Tom Adams, Brad Clow, Ricky Clarkson

This software is released under an open source BSD licence.