Class OptionalLong

java.lang.Object
java.util.OptionalLong
public final classOptionalLongextendsObject
A container object which may or may not contain along value. If a value is present,isPresent() returnstrue. If no value is present, the object is consideredempty andisPresent() returnsfalse.

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

This is avalue-based class; programmers should treat instances that areequal as interchangeable and should not use instances for synchronization, or unpredictable behavior may occur. For example, in a future release, synchronization may fail.

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 isOptionalLong should never itself benull; it should always point to anOptionalLong instance.
Since:
1.8

  • Method Summary

    Modifier and Type
    Method
    Description
    Returns an emptyOptionalLong instance.
    boolean
    Indicates whether some other object is "equal to" thisOptionalLong.
    long
    If a value is present, returns the value, otherwise throwsNoSuchElementException.
    int
    Returns the hash code of the value, if present, otherwise0 (zero) if no value is present.
    void
    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
    If a value is not present, returnstrue, otherwisefalse.
    boolean
    If a value is present, returnstrue, otherwisefalse.
    of(long value)
    Returns anOptionalLong describing the given value.
    long
    orElse(long other)
    If a value is present, returns the value, otherwise returnsother.
    long
    If a value is present, returns the value, otherwise returns the result produced by the supplying function.
    long
    If a value is present, returns the value, otherwise throwsNoSuchElementException.
    <X extendsThrowable>
    long
    orElseThrow(Supplier<? extends X> exceptionSupplier)
    If a value is present, returns the value, otherwise throws an exception produced by the exception supplying function.
    If a value is present, returns a sequentialLongStream containing only that value, otherwise returns an emptyLongStream.
    Returns a non-empty string representation of thisOptionalLong suitable for debugging.

    Methods declared in class java.lang.Object

    clone,finalize,getClass,notify,notifyAll,wait,wait,wait

  • Method Details

    • empty

      public static OptionalLong empty()
      Returns an emptyOptionalLong instance. No value is present for thisOptionalLong.
      API Note:
      Though it may be tempting to do so, avoid testing if an object is empty by comparing with== or!= against instances returned byOptionalLong.empty(). There is no guarantee that it is a singleton. Instead, useisEmpty() orisPresent().
      Returns:
      an emptyOptionalLong.

    • of

      public static OptionalLong of(long value)
      Returns anOptionalLong describing the given value.
      Parameters:
      value - the value to describe
      Returns:
      anOptionalLong with the value present

    • getAsLong

      public long getAsLong()
      If a value is present, returns the value, otherwise throwsNoSuchElementException.
      API Note:
      The preferred alternative to this method isorElseThrow().
      Returns:
      the value described by thisOptionalLong
      Throws:
      NoSuchElementException - if no value is present

    • isPresent

      public boolean isPresent()
      If a value is present, returnstrue, otherwisefalse.
      Returns:
      true if a value is present, otherwisefalse

    • isEmpty

      public boolean isEmpty()
      If a value is not present, returnstrue, otherwisefalse.
      Returns:
      true if a value is not present, otherwisefalse
      Since:
      11

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

    • 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 isnull, or no value is present and the given empty-based action isnull.
      Since:
      9

    • stream

      public LongStream stream()
      If a value is present, returns a sequentialLongStream containing only that value, otherwise returns an emptyLongStream.
      API Note:
      This method can be used to transform aStream of optional longs to anLongStream of present longs:
           Stream<OptionalLong> os = ..     LongStream s = os.flatMapToLong(OptionalLong::stream)
      Returns:
      the optional value as anLongStream
      Since:
      9

    • orElse

      public long orElse(long other)
      If a value is present, returns the value, otherwise returnsother.
      Parameters:
      other - the value to be returned, if no value is present
      Returns:
      the value, if present, otherwiseother

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

    • orElseThrow

      public long orElseThrow()
      If a value is present, returns the value, otherwise throwsNoSuchElementException.
      Returns:
      the value described by thisOptionalLong
      Throws:
      NoSuchElementException - if no value is present
      Since:
      10

    • orElseThrow

      public <X extendsThrowable> long orElseThrow(Supplier<? extends X> exceptionSupplier) throwsX
      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 isnull

    • equals

      public boolean equals(Object obj)
      Indicates whether some other object is "equal to" thisOptionalLong. The other object is considered equal if:
      • it is also anOptionalLong 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 otherwisefalse
      See Also:

    • hashCode

      public int hashCode()
      Returns the hash code of the value, if present, otherwise0 (zero) if no value is present.
      Overrides:
      hashCode in class Object
      Returns:
      hash code value of the present value or0 if no value is present
      See Also:

    • toString

      public String toString()
      Returns a non-empty string representation of thisOptionalLong 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 presentOptionalLongs must be unambiguously differentiable.
      Returns:
      the string representation of this instance