public final class OptionalLong
extends Object

A container object which may or may not contain a long value. If a value is present, isPresent() returns true. If no value is present, the object is considered empty and isPresent() returns false.

Additional methods that depend on the presence or absence of a contained value are provided, such as orElse() (returns a default value if no value is present) and ifPresent() (performs an action if a value is present).

This is a value-based class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of OptionalLong may have unpredictable results and should be avoided.

API Note:
OptionalLong is primarily intended for use as a method return type where there is a clear need to represent "no result." A variable whose type is OptionalLong should never itself be null; it should always point to an OptionalLong instance.
Since:
1.8

  • Method Summary

    Modifier and Type Method Description
    static OptionalLong empty()

    Returns an empty OptionalLong instance.
    boolean equals​(Object obj)

    Indicates whether some other object is "equal to" this OptionalLong.
    long getAsLong()

    If a value is present, returns the value, otherwise throws NoSuchElementException.
    int hashCode()

    Returns the hash code of the value, if present, otherwise 0 (zero) if no value is present.
    void ifPresent​(LongConsumer action)

    If a value is present, performs the given action with the value, otherwise does nothing.
    void ifPresentOrElse​(LongConsumer action, Runnable emptyAction)

    If a value is present, performs the given action with the value, otherwise performs the given empty-based action.
    boolean isEmpty()

    If a value is not present, returns true, otherwise false.
    boolean isPresent()

    If a value is present, returns true, otherwise false.
    static OptionalLong of​(long value)

    Returns an OptionalLong describing the given value.
    long orElse​(long other)

    If a value is present, returns the value, otherwise returns other.
    long orElseGet​(LongSupplier supplier)

    If a value is present, returns the value, otherwise returns the result produced by the supplying function.
    long orElseThrow()

    If a value is present, returns the value, otherwise throws NoSuchElementException.
    <X extends Throwable>
    long    		 orElseThrow​(Supplier<? extends X> exceptionSupplier)

    If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function.
    LongStream stream()

    If a value is present, returns a sequential LongStream containing only that value, otherwise returns an empty LongStream.
    String toString()

    Returns a non-empty string representation of this OptionalLong suitable for debugging.

  • Method Details

    • empty

      Returns an empty OptionalLong instance. No value is present for this OptionalLong.

      API Note:
      Though it may be tempting to do so, avoid testing if an object is empty by comparing with == against instances returned by OptionalLong.empty(). There is no guarantee that it is a singleton. Instead, use isPresent().
      Returns:
      an empty OptionalLong.

    • of

      Returns an OptionalLong describing the given value.

      Parameters:
      value - the value to describe
      Returns:
      an OptionalLong with the value present

    • getAsLong

      public long getAsLong()

      If a value is present, returns the value, otherwise throws NoSuchElementException.

      API Note:
      The preferred alternative to this method is orElseThrow().
      Returns:
      the value described by this OptionalLong
      Throws:
      NoSuchElementException - if no value is present

    • isPresent

      public boolean isPresent()

      If a value is present, returns true, otherwise false.

      Returns:
      true if a value is present, otherwise false

    • isEmpty

      public boolean isEmpty()

      If a value is not present, returns true, otherwise false.

      Returns:
      true if a value is not present, otherwise false
      Since:
      11

    • ifPresent

      If a value is present, performs the given action with the value, otherwise does nothing.

      Parameters:
      action - the action to be performed, if a value is present
      Throws:
      NullPointerException - if value is present and the given action is null

    • ifPresentOrElse

      If a value is present, performs the given action with the value, otherwise performs the given empty-based action.

      Parameters:
      action - the action to be performed, if a value is present
      emptyAction - the empty-based action to be performed, if no value is present
      Throws:
      NullPointerException - if a value is present and the given action is null, or no value is present and the given empty-based action is null.
      Since:
      9

    • stream

      If a value is present, returns a sequential LongStream containing only that value, otherwise returns an empty LongStream.

      API Note:
      This method can be used to transform a Stream of optional longs to an LongStream of present longs: 
      
     Stream<OptionalLong> os = ..
     LongStream s = os.flatMapToLong(OptionalLong::stream)
      Returns:
      the optional value as an LongStream
      Since:
      9

    • orElse

      public long orElse​(long other)

      If a value is present, returns the value, otherwise returns other.

      Parameters:
      other - the value to be returned, if no value is present
      Returns:
      the value, if present, otherwise other

    • orElseGet

      If a value is present, returns the value, otherwise returns the result produced by the supplying function.

      Parameters:
      supplier - the supplying function that produces a value to be returned
      Returns:
      the value, if present, otherwise the result produced by the supplying function
      Throws:
      NullPointerException - if no value is present and the supplying function is null

    • orElseThrow

      public long orElseThrow()

      If a value is present, returns the value, otherwise throws NoSuchElementException.

      Returns:
      the value described by this OptionalLong
      Throws:
      NoSuchElementException - if no value is present
      Since:
      10

    • orElseThrow

      public <X extends Throwable> long orElseThrow​(Supplier<? extends X> exceptionSupplier) throws X extends Throwable

      If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function.

      API Note:
      A method reference to the exception constructor with an empty argument list can be used as the supplier. For example, IllegalStateException::new
      Type Parameters:
      X - Type of the exception to be thrown
      Parameters:
      exceptionSupplier - the supplying function that produces an exception to be thrown
      Returns:
      the value, if present
      Throws:
      X - if no value is present
      NullPointerException - if no value is present and the exception supplying function is null
      X extends Throwable

    • equals

      public boolean equals​(Object obj)

      Indicates whether some other object is "equal to" this OptionalLong. The other object is considered equal if:

      • it is also an OptionalLong and;
      • both instances have no value present or;
      • the present values are "equal to" each other via ==.
      Overrides:
      equals in class Object
      Parameters:
      obj - an object to be tested for equality
      Returns:
      true if the other object is "equal to" this object otherwise false
      See Also:
      Object.hashCode(), HashMap

    • hashCode

      public int hashCode()

      Returns the hash code of the value, if present, otherwise 0 (zero) if no value is present.

      Overrides:
      hashCode in class Object
      Returns:
      hash code value of the present value or 0 if no value is present
      See Also:
      Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

    • toString

      Returns a non-empty string representation of this OptionalLong suitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.

      Overrides:
      toString in class Object
      Implementation Requirements:
      If a value is present the result must include its string representation in the result. Empty and present OptionalLongs must be unambiguously differentiable.
      Returns:
      the string representation of this instance