T
- the type of instance that can be contained. Optional
is naturally covariant on
this type, so it is safe to cast an Optional<T>
to Optional<S>
for any
supertype S
of T
.@GwtCompatible(serializable=true) public abstract class Optional<T> extends Object implements Serializable
null
".
A non-null Optional<T>
reference can be used as a replacement for a nullable T
reference. It allows you to represent "a T
that must be present" and a "a T
that
might be absent" as two distinct types in your program, which can aid clarity.
Some uses of this class include
null
to indicate that no
value was available
Optional.absent()
)
null
(though there are several other
approaches to this that should be considered first)
A common alternative to using this class is to find or create a suitable null object for the type in question.
This class is not intended as a direct analogue of any existing "option" or "maybe" construct from other programming environments, though it may bear some similarities.
Comparison to java.util.Optional
(JDK 8 and higher): A new Optional
class was added for Java 8. The two classes are extremely similar, but incompatible (they cannot
share a common supertype). All known differences are listed either here or with the
relevant methods below.
java.util.Optional
is not.
java.util.Optional
has the additional methods ifPresent
, filter
,
flatMap
, and orElseThrow
.
java.util
offers the primitive-specialized versions OptionalInt
, OptionalLong
and OptionalDouble
, the use of which is recommended; Guava does not
have these.
There are no plans to deprecate this class in the foreseeable future. However, we do gently recommend that you prefer the new, standard Java class whenever possible.
See the Guava User Guide article on using Optional
.
Modifier and Type | Method and Description |
---|---|
static <T> Optional<T> |
absent()
Returns an
Optional instance with no contained reference. |
abstract Set<T> |
asSet()
|
abstract boolean |
equals(@Nullable Object object)
Returns
true if object is an Optional instance, and either the
contained references are equal to each other or both are absent. |
static <T> @Nullable Optional<T> |
fromJavaUtil(Optional<T> javaUtilOptional)
Returns the equivalent
com.google.common.base.Optional value to the given java.util.Optional , or null if the argument is null. |
static <T> Optional<T> |
fromNullable(T nullableReference)
If
nullableReference is non-null, returns an Optional instance containing that
reference; otherwise returns absent() . |
abstract T |
get()
Returns the contained instance, which must be present.
|
abstract int |
hashCode()
Returns a hash code for this instance.
|
abstract boolean |
isPresent()
Returns
true if this holder contains a (non-null) instance. |
static <T> Optional<T> |
of(T reference)
Returns an
Optional instance containing the given non-null reference. |
abstract Optional<T> |
or(Optional<? extends T> secondChoice)
Returns this
Optional if it has a value present; secondChoice otherwise. |
abstract T |
or(Supplier<? extends T> supplier)
Returns the contained instance if it is present;
supplier.get() otherwise. |
abstract T |
or(T defaultValue)
Returns the contained instance if it is present;
defaultValue otherwise. |
abstract T |
orNull()
Returns the contained instance if it is present;
null otherwise. |
static <T> Iterable<T> |
presentInstances(Iterable<? extends Optional<? extends T>> optionals)
Returns the value of each present instance from the supplied
optionals , in order,
skipping over occurrences of absent() . |
Optional<T> |
toJavaUtil()
Returns the equivalent
java.util.Optional value to this optional. |
static <T> Optional<T> |
toJavaUtil(@Nullable Optional<T> googleOptional)
Returns the equivalent
java.util.Optional value to the given com.google.common.base.Optional , or null if the argument is null. |
abstract String |
toString()
Returns a string representation for this instance.
|
abstract <V> Optional<V> |
transform(Function<? super T,V> function)
|
public static <T> Optional<T> absent()
Optional
instance with no contained reference.
Comparison to java.util.Optional
: this method is equivalent to Java 8's
Optional.empty
.
public static <T> Optional<T> of(T reference)
Optional
instance containing the given non-null reference. To have null
treated as absent()
, use fromNullable(T)
instead.
Comparison to java.util.Optional
: no differences.
NullPointerException
- if reference
is nullpublic static <T> Optional<T> fromNullable(T nullableReference)
nullableReference
is non-null, returns an Optional
instance containing that
reference; otherwise returns absent()
.
Comparison to java.util.Optional
: this method is equivalent to Java 8's
Optional.ofNullable
.
public static <T> @Nullable Optional<T> fromJavaUtil(Optional<T> javaUtilOptional)
com.google.common.base.Optional
value to the given java.util.Optional
, or null
if the argument is null.public static <T> Optional<T> toJavaUtil(@Nullable Optional<T> googleOptional)
java.util.Optional
value to the given com.google.common.base.Optional
, or null
if the argument is null.
If googleOptional
is known to be non-null, use googleOptional.toJavaUtil()
instead.
Unfortunately, the method reference Optional::toJavaUtil
will not work, because it
could refer to either the static or instance version of this method. Write out the lambda
expression o -> Optional.toJavaUtil(o)
instead.
public Optional<T> toJavaUtil()
java.util.Optional
value to this optional.
Unfortunately, the method reference Optional::toJavaUtil
will not work, because it
could refer to either the static or instance version of this method. Write out the lambda
expression o -> o.toJavaUtil()
instead.
public abstract boolean isPresent()
true
if this holder contains a (non-null) instance.
Comparison to java.util.Optional
: no differences.
public abstract T get()
or(Object)
or orNull()
instead.
Comparison to java.util.Optional
: when the value is absent, this method
throws IllegalStateException
, whereas the Java 8 counterpart throws NoSuchElementException
.
IllegalStateException
- if the instance is absent (isPresent()
returns false
); depending on this specific exception type (over the more general RuntimeException
) is discouragedpublic abstract T or(T defaultValue)
defaultValue
otherwise. If no default
value should be required because the instance is known to be present, use get()
instead. For a default value of null
, use orNull()
.
Note about generics: The signature public T or(T defaultValue)
is overly
restrictive. However, the ideal signature, public <S super T> S or(S)
, is not legal
Java. As a result, some sensible operations involving subtypes are compile errors:
Optional<Integer> optionalInt = getSomeOptionalInt();
Number value = optionalInt.or(0.5); // error
FluentIterable<? extends Number> numbers = getSomeNumbers();
Optional<? extends Number> first = numbers.first();
Number value = first.or(0.5); // error
As a workaround, it is always safe to cast an Optional<? extends T>
to Optional<T>
. Casting either of the above example Optional
instances to Optional<Number>
(where Number
is the desired output type) solves the problem:
Optional<Number> optionalInt = (Optional) getSomeOptionalInt();
Number value = optionalInt.or(0.5); // fine
FluentIterable<? extends Number> numbers = getSomeNumbers();
Optional<Number> first = (Optional) numbers.first();
Number value = first.or(0.5); // fine
Comparison to java.util.Optional
: this method is similar to Java 8's Optional.orElse
, but will not accept null
as a defaultValue
(orNull()
must be used instead). As a result, the value returned by this method is guaranteed non-null,
which is not the case for the java.util
equivalent.
public abstract Optional<T> or(Optional<? extends T> secondChoice)
Optional
if it has a value present; secondChoice
otherwise.
Comparison to java.util.Optional
: this method has no equivalent in Java 8's
Optional
class; write thisOptional.isPresent() ? thisOptional : secondChoice
instead.
@Beta public abstract T or(Supplier<? extends T> supplier)
supplier.get()
otherwise.
Comparison to java.util.Optional
: this method is similar to Java 8's Optional.orElseGet
, except when supplier
returns null
. In this case this
method throws an exception, whereas the Java 8 method returns the null
to the caller.
NullPointerException
- if this optional's value is absent and the supplier returns null
public abstract T orNull()
null
otherwise. If the instance is
known to be present, use get()
instead.
Comparison to java.util.Optional
: this method is equivalent to Java 8's
Optional.orElse(null)
.
public abstract Set<T> asSet()
Set
whose only element is the contained instance if it
is present; an empty immutable Set
otherwise.
Comparison to java.util.Optional
: this method has no equivalent in Java 8's
Optional
class. However, this common usage:
for (Foo foo : possibleFoo.asSet()) {
doSomethingWith(foo);
}
... can be replaced with:
possibleFoo.ifPresent(foo -> doSomethingWith(foo));
public abstract <V> Optional<V> transform(Function<? super T,V> function)
Function
; otherwise,
absent()
is returned.
Comparison to java.util.Optional
: this method is similar to Java 8's Optional.map
, except when function
returns null
. In this case this method
throws an exception, whereas the Java 8 method returns Optional.absent()
.
NullPointerException
- if the function returns null
public abstract boolean equals(@Nullable Object object)
true
if object
is an Optional
instance, and either the
contained references are equal to each other or both are absent.
Note that Optional
instances of differing parameterized types can be equal.
Comparison to java.util.Optional
: no differences.
equals
in class Object
object
- the reference object with which to compare.true
if this object is the same as the obj
argument; false
otherwise.Object.hashCode()
,
HashMap
public abstract int hashCode()
Comparison to java.util.Optional
: this class leaves the specific choice of
hash code unspecified, unlike the Java 8 equivalent.
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public abstract String toString()
Comparison to java.util.Optional
: this class leaves the specific string
representation unspecified, unlike the Java 8 equivalent.
@Beta public static <T> Iterable<T> presentInstances(Iterable<? extends Optional<? extends T>> optionals)
optionals
, in order,
skipping over occurrences of absent()
. Iterators are unmodifiable and are
evaluated lazily.
Comparison to java.util.Optional
: this method has no equivalent in Java 8's
Optional
class; use optionals.stream().filter(Optional::isPresent).map(Optional::get)
instead.
Copyright © 2010–2019. All rights reserved.