All Downloads are FREE. Search and download functionalities are using the official Maven repository.
  • Log In
  • Register

    • javadoc.com.google.common.base.Optional.html Maven / Gradle / Ivy

    There is a newer version: 8.0.0
    Show newest version
    






Optional (Guava: Google Core Libraries for Java 11.0.1 API)













    






    

    



    
  
    
      Overview 
      Package 
    Class 
      Use 
      Tree 
      Deprecated 
      Index 
      Help 
  
    

    
    		




    


    

 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 





    

    

  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

    

    




    


    

com.google.common.base

    
Class Optional<T>
    

    java.lang.Object
  extended by com.google.common.base.Optional<T>

    

    

    Type Parameters:
    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.
    

    

    All Implemented Interfaces: 
    Serializable
    

    

    

    

    @Beta
@GwtCompatible
public abstract class Optional<T>
    extends Object
    implements Serializable

    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 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

    • As a method return type, as an alternative to returning 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 Optional.absent())
    • To wrap nullable references for storage in a collection that does not support 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.

    Since:
    10.0
    Author:
    Kurt Alfred Kluever, Kevin Bourrillion
    See Also:
    Serialized Form

    Method Summary
    static
    <T> Optional<T>
    		absent()
              Returns an Optional instance with no contained reference.
    abstract  Set<T> asSet()
              Returns an immutable singleton Set whose only element is the contained instance if it is present; an empty immutable Set otherwise.
    abstract  boolean equals(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> 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<Optional<T>> optionals)
              Returns the value of each present instance from the supplied optionals, in order, skipping over occurrences of absent().
    abstract  String toString()
              Returns a string representation for this instance.
     
    Methods inherited from class java.lang.Object
    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
     

    Method Detail

    absent

    public static <T> Optional<T> absent()
    Returns an Optional instance with no contained reference.

    of

    public static <T> Optional<T> of(T reference)
    Returns an Optional instance containing the given non-null reference.

    fromNullable

    public static <T> Optional<T> fromNullable(@Nullable
                                           T nullableReference)
    If nullableReference is non-null, returns an Optional instance containing that reference; otherwise returns absent().

    isPresent

    public abstract boolean isPresent()
    Returns true if this holder contains a (non-null) instance.

    get

    public abstract T get()
    Returns the contained instance, which must be present. If the instance might be absent, use or(Object) or orNull() instead.

    Throws:
    IllegalStateException - if the instance is absent (isPresent() returns false)

    or

    public abstract T or(T defaultValue)
    Returns the contained instance if it is present; 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().

    or

    public abstract Optional<T> or(Optional<? extends T> secondChoice)
    Returns this Optional if it has a value present; secondChoice otherwise.

    or

    public abstract T or(Supplier<? extends T> supplier)
    Returns the contained instance if it is present; supplier.get() otherwise. If the supplier returns null, a NullPointerException will be thrown.

    Throws:
    NullPointerException - if the supplier returns null

    orNull

    @Nullable
public abstract T orNull()
    Returns the contained instance if it is present; null otherwise. If the instance is known to be present, use get() instead.

    asSet

    public abstract Set<T> asSet()
    Returns an immutable singleton Set whose only element is the contained instance if it is present; an empty immutable Set otherwise.

    Since:
    11.0

    equals

    public 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. Note that Optional instances of differing parameterized types can be equal.

    Overrides:
    equals in class Object

    hashCode

    public abstract int hashCode()
    Returns a hash code for this instance.

    Overrides:
    hashCode in class Object

    toString

    public abstract String toString()
    Returns a string representation for this instance. The form of this string representation is unspecified.

    Overrides:
    toString in class Object

    presentInstances

    public static <T> Iterable<T> presentInstances(Iterable<Optional<T>> optionals)
    Returns the value of each present instance from the supplied optionals, in order, skipping over occurrences of absent(). Iterators are unmodifiable and are evaluated lazily.

    Since:
    11.0
    Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
     PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
    SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
    Copyright © 2010-2012. All Rights Reserved.



    © 2015 - 2025 Weber Informatics LLC | Privacy Policy