- java.lang.Object
-
- java.util.OptionalLong
-
public final class OptionalLong extends Object
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 considered empty andisPresent()
returnsfalse
.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) andifPresent()
(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 ofOptionalLong
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 isOptionalLong
should never itself benull
; it should always point to anOptionalLong
instance.- Since:
- 1.8
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static OptionalLong
empty()
Returns an emptyOptionalLong
instance.boolean
equals(Object obj)
Indicates whether some other object is "equal to" thisOptionalLong
.long
getAsLong()
If a value is present, returns the value, otherwise throwsNoSuchElementException
.int
hashCode()
Returns the hash code of the value, if present, otherwise0
(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, returnstrue
, otherwisefalse
.boolean
isPresent()
If a value is present, returnstrue
, otherwisefalse
.static OptionalLong
of(long value)
Returns anOptionalLong
describing the given value.long
orElse(long other)
If a value is present, returns the value, otherwise returnsother
.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 throwsNoSuchElementException
.<X extends Throwable>
longorElseThrow(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 sequentialLongStream
containing only that value, otherwise returns an emptyLongStream
.String
toString()
Returns a non-empty string representation of thisOptionalLong
suitable for debugging.
-
-
-
Method Detail
-
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
==
against instances returned byOptionalLong.empty()
. There is no guarantee that it is a singleton. Instead, useisPresent()
. - Returns:
- an empty
OptionalLong
.
-
of
public static OptionalLong of(long value)
Returns anOptionalLong
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 throwsNoSuchElementException
.- 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, 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 presentemptyAction
- 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 a
Stream
of optional longs to anLongStream
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 returnsother
.- 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 isnull
-
orElseThrow
public long orElseThrow()
If a value is present, returns the value, otherwise throwsNoSuchElementException
.- 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
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 presentNullPointerException
- if no value is present and the exception supplying function isnull
X extends Throwable
-
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 an
OptionalLong
and; - both instances have no value present or;
- the present values are "equal to" each other via
==
.
- Overrides:
equals
in classObject
- Parameters:
obj
- an object to be tested for equality- Returns:
true
if the other object is "equal to" this object otherwisefalse
- See Also:
Object.hashCode()
,HashMap
- it is also an
-
hashCode
public int hashCode()
Returns the hash code of the value, if present, otherwise0
(zero) if no value is present.- Overrides:
hashCode
in classObject
- 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
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.
-
-