All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.google.common.base.Optional Maven / Gradle / Ivy

/*
 * Copyright (C) 2011 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.base;

import static com.google.common.base.Preconditions.checkNotNull;

import com.google.common.annotations.Beta;
import com.google.common.annotations.GwtCompatible;

import java.io.Serializable;
import java.util.Iterator;
import java.util.Set;

import javax.annotation.Nullable;

/**
 * An immutable object that may contain a non-null reference to another object. Each
 * instance of this type either contains a non-null reference, or contains nothing (in
 * which case we say that the reference is "absent"); it is never said to "contain {@code
 * null}".
 *
 * 

A non-null {@code Optional} reference can be used as a replacement for a nullable * {@code T} reference. It allows you to represent "a {@code T} that must be present" and * a "a {@code T} that might be absent" as two distinct types in your program, which can * aid clarity. * *

Some uses of this class include * *

    *
  • As a method return type, as an alternative to returning {@code null} to indicate * that no value was available *
  • To distinguish between "unknown" (for example, not present in a map) and "known to * have no value" (present in the map, with value {@code Optional.absent()}) *
  • To wrap nullable references for storage in a collection that does not support * {@code 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. * *

See the Guava User Guide article on * using {@code Optional}. * * @param the type of instance that can be contained. {@code Optional} is naturally * covariant on this type, so it is safe to cast an {@code Optional} to {@code * Optional} for any supertype {@code S} of {@code T}. * @author Kurt Alfred Kluever * @author Kevin Bourrillion * @since 10.0 */ @GwtCompatible(serializable = true) public abstract class Optional implements Serializable { /** * Returns an {@code Optional} instance with no contained reference. */ public static Optional absent() { return Absent.withType(); } /** * Returns an {@code Optional} instance containing the given non-null reference. */ public static Optional of(T reference) { return new Present(checkNotNull(reference)); } /** * If {@code nullableReference} is non-null, returns an {@code Optional} instance containing that * reference; otherwise returns {@link Optional#absent}. */ public static Optional fromNullable(@Nullable T nullableReference) { return (nullableReference == null) ? Optional.absent() : new Present(nullableReference); } Optional() {} /** * Returns {@code true} if this holder contains a (non-null) instance. */ public abstract boolean isPresent(); /** * Returns the contained instance, which must be present. If the instance might be * absent, use {@link #or(Object)} or {@link #orNull} instead. * * @throws IllegalStateException if the instance is absent ({@link #isPresent} returns * {@code false}) */ public abstract T get(); /** * Returns the contained instance if it is present; {@code defaultValue} otherwise. If * no default value should be required because the instance is known to be present, use * {@link #get()} instead. For a default value of {@code null}, use {@link #orNull}. * *

Note about generics: The signature {@code public T or(T defaultValue)} is overly * restrictive. However, the ideal signature, {@code public S or(S)}, is not legal * Java. As a result, some sensible operations involving subtypes are compile errors: *

   {@code
   *
   *   Optional optionalInt = getSomeOptionalInt();
   *   Number value = optionalInt.or(0.5); // error
   *
   *   FluentIterable numbers = getSomeNumbers();
   *   Optional first = numbers.first();
   *   Number value = first.or(0.5); // error}
* *

As a workaround, it is always safe to cast an {@code Optional} to {@code * Optional}. Casting either of the above example {@code Optional} instances to {@code * Optional} (where {@code Number} is the desired output type) solves the problem: *

   {@code
   *
   *   Optional optionalInt = (Optional) getSomeOptionalInt();
   *   Number value = optionalInt.or(0.5); // fine
   *
   *   FluentIterable numbers = getSomeNumbers();
   *   Optional first = (Optional) numbers.first();
   *   Number value = first.or(0.5); // fine}
*/ public abstract T or(T defaultValue); /** * Returns this {@code Optional} if it has a value present; {@code secondChoice} * otherwise. */ public abstract Optional or(Optional secondChoice); /** * Returns the contained instance if it is present; {@code supplier.get()} otherwise. If the * supplier returns {@code null}, a {@link NullPointerException} is thrown. * * @throws NullPointerException if the supplier returns {@code null} */ @Beta public abstract T or(Supplier supplier); /** * Returns the contained instance if it is present; {@code null} otherwise. If the * instance is known to be present, use {@link #get()} instead. */ @Nullable public abstract T orNull(); /** * Returns an immutable singleton {@link Set} whose only element is the contained instance * if it is present; an empty immutable {@link Set} otherwise. * * @since 11.0 */ public abstract Set asSet(); /** * If the instance is present, it is transformed with the given {@link Function}; otherwise, * {@link Optional#absent} is returned. If the function returns {@code null}, a * {@link NullPointerException} is thrown. * * @throws NullPointerException if the function returns {@code null} * * @since 12.0 */ public abstract Optional transform(Function function); /** * Returns {@code true} if {@code object} is an {@code Optional} instance, and either * the contained references are {@linkplain Object#equals equal} to each other or both * are absent. Note that {@code Optional} instances of differing parameterized types can * be equal. */ @Override public abstract boolean equals(@Nullable Object object); /** * Returns a hash code for this instance. */ @Override public abstract int hashCode(); /** * Returns a string representation for this instance. The form of this string * representation is unspecified. */ @Override public abstract String toString(); /** * Returns the value of each present instance from the supplied {@code optionals}, in order, * skipping over occurrences of {@link Optional#absent}. Iterators are unmodifiable and are * evaluated lazily. * * @since 11.0 (generics widened in 13.0) */ @Beta public static Iterable presentInstances( final Iterable> optionals) { checkNotNull(optionals); return new Iterable() { @Override public Iterator iterator() { return new AbstractIterator() { private final Iterator> iterator = checkNotNull(optionals.iterator()); @Override protected T computeNext() { while (iterator.hasNext()) { Optional optional = iterator.next(); if (optional.isPresent()) { return optional.get(); } } return endOfData(); } }; } }; } private static final long serialVersionUID = 0; }