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.errorprone.annotations.DoNotMock;

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 org.checkerframework.checker.nullness.qual.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. * *

Comparison to {@code java.util.Optional} (JDK 8 and higher): A new {@code 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. * *

    *
  • This class is serializable; {@code java.util.Optional} is not. *
  • {@code java.util.Optional} has the additional methods {@code ifPresent}, {@code filter}, * {@code flatMap}, and {@code orElseThrow}. *
  • {@code java.util} offers the primitive-specialized versions {@code OptionalInt}, {@code * OptionalLong} and {@code 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 {@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 */ @DoNotMock("Use Optional.of(value) or Optional.absent()") @GwtCompatible(serializable = true) public abstract class Optional implements Serializable { /** * Returns an {@code Optional} instance with no contained reference. * *

Comparison to {@code java.util.Optional}: this method is equivalent to Java 8's * {@code Optional.empty}. */ public static Optional absent() { return Absent.withType(); } /** * Returns an {@code Optional} instance containing the given non-null reference. To have {@code * null} treated as {@link #absent}, use {@link #fromNullable} instead. * *

Comparison to {@code java.util.Optional}: no differences. * * @throws NullPointerException if {@code reference} is null */ 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}. * *

Comparison to {@code java.util.Optional}: this method is equivalent to Java 8's * {@code Optional.ofNullable}. */ public static Optional fromNullable(@Nullable T nullableReference) { return (nullableReference == null) ? Optional.absent() : new Present(nullableReference); } /** * Returns the equivalent {@code com.google.common.base.Optional} value to the given {@code * java.util.Optional}, or {@code null} if the argument is null. * * @since 21.0 */ public static @Nullable Optional fromJavaUtil( java.util.@Nullable Optional javaUtilOptional) { return (javaUtilOptional == null) ? null : fromNullable(javaUtilOptional.orElse(null)); } /** * Returns the equivalent {@code java.util.Optional} value to the given {@code * com.google.common.base.Optional}, or {@code null} if the argument is null. * *

If {@code googleOptional} is known to be non-null, use {@code googleOptional.toJavaUtil()} * instead. * *

Unfortunately, the method reference {@code Optional::toJavaUtil} will not work, because it * could refer to either the static or instance version of this method. Write out the lambda * expression {@code o -> Optional.toJavaUtil(o)} instead. * * @since 21.0 */ public static java.util.@Nullable Optional toJavaUtil( @Nullable Optional googleOptional) { return googleOptional == null ? null : googleOptional.toJavaUtil(); } /** * Returns the equivalent {@code java.util.Optional} value to this optional. * *

Unfortunately, the method reference {@code Optional::toJavaUtil} will not work, because it * could refer to either the static or instance version of this method. Write out the lambda * expression {@code o -> o.toJavaUtil()} instead. * * @since 21.0 */ public java.util.Optional toJavaUtil() { return java.util.Optional.ofNullable(orNull()); } Optional() {} /** * Returns {@code true} if this holder contains a (non-null) instance. * *

Comparison to {@code java.util.Optional}: no differences. */ 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. * *

Comparison to {@code java.util.Optional}: when the value is absent, this method * throws {@link IllegalStateException}, whereas the Java 8 counterpart throws {@link * java.util.NoSuchElementException NoSuchElementException}. * * @throws IllegalStateException if the instance is absent ({@link #isPresent} returns {@code * false}); depending on this specific exception type (over the more general {@link * RuntimeException}) is discouraged */ 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
   * }
* *

Comparison to {@code java.util.Optional}: this method is similar to Java 8's {@code * Optional.orElse}, but will not accept {@code null} as a {@code defaultValue} ({@link #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 {@code java.util} equivalent. */ public abstract T or(T defaultValue); /** * Returns this {@code Optional} if it has a value present; {@code secondChoice} otherwise. * *

Comparison to {@code java.util.Optional}: this method has no equivalent in Java 8's * {@code Optional} class; write {@code thisOptional.isPresent() ? thisOptional : secondChoice} * instead. */ public abstract Optional or(Optional secondChoice); /** * Returns the contained instance if it is present; {@code supplier.get()} otherwise. * *

Comparison to {@code java.util.Optional}: this method is similar to Java 8's {@code * Optional.orElseGet}, except when {@code supplier} returns {@code null}. In this case this * method throws an exception, whereas the Java 8 method returns the {@code null} to the caller. * * @throws NullPointerException if this optional's value is absent and 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. * *

Comparison to {@code java.util.Optional}: this method is equivalent to Java 8's * {@code Optional.orElse(null)}. */ public abstract @Nullable 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. * *

Comparison to {@code java.util.Optional}: this method has no equivalent in Java 8's * {@code Optional} class. However, this common usage: * *

{@code
   * for (Foo foo : possibleFoo.asSet()) {
   *   doSomethingWith(foo);
   * }
   * }
* * ... can be replaced with: * *
{@code
   * possibleFoo.ifPresent(foo -> doSomethingWith(foo));
   * }
* *

Java 9 users: some use cases can be written with calls to {@code optional.stream()}. * * @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. * *

Comparison to {@code java.util.Optional}: this method is similar to Java 8's {@code * Optional.map}, except when {@code function} returns {@code null}. In this case this method * throws an exception, whereas the Java 8 method returns {@code Optional.absent()}. * * @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. * *

Comparison to {@code java.util.Optional}: no differences. */ @Override public abstract boolean equals(@Nullable Object object); /** * Returns a hash code for this instance. * *

Comparison to {@code java.util.Optional}: this class leaves the specific choice of * hash code unspecified, unlike the Java 8 equivalent. */ @Override public abstract int hashCode(); /** * Returns a string representation for this instance. * *

Comparison to {@code java.util.Optional}: this class leaves the specific string * representation unspecified, unlike the Java 8 equivalent. */ @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. * *

Comparison to {@code java.util.Optional}: this method has no equivalent in Java 8's * {@code Optional} class; use {@code * optionals.stream().filter(Optional::isPresent).map(Optional::get)} instead. * *

Java 9 users: use {@code optionals.stream().flatMap(Optional::stream)} instead. * * @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; }