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