Module java.base
Package java.util

Class OptionalLong


  • 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 and getAsLong() returns the value.

    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

      All Methods Static Methods Instance Methods Concrete Methods 
      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 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.
      <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 Detail

      • empty

        public static OptionalLong 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

        public static OptionalLong of​(long value)
        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 methods orElse and orElseGet are generally preferable to this method, as they return a substitute value if the value is absent, instead of throwing an exception.
        Returns:
        the value described by this OptionalLong
        Throws:
        NoSuchElementException - if no value is present
        See Also:
        isPresent()

      • isPresent

        public boolean isPresent​()
        If a value is present, returns true, otherwise false.
        Returns:
        true if a value is present, otherwise false

      • ifPresent

        public void ifPresent​(LongConsumer action)
        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

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

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

        public long orElseGet​(LongSupplier supplier)
        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 <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

      • toString

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