Class OptionalLong
- java.lang.Object
-
- java.util.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
. 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 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 empty |
boolean | equals(Object obj) | Indicates whether some other object is "equal to" this |
long | getAsLong() | If a value is present, returns the value, otherwise throws |
int | hashCode() | Returns the hash code of the value, if present, otherwise |
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 |
boolean | isPresent() | If a value is present, returns |
static OptionalLong | of(long value) | Returns an |
long | orElse(long other) | If a value is present, returns the value, otherwise returns |
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 |
<X extends Throwable> | 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 |
String | toString() | Returns a non-empty string representation of this |
Methods declared in class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
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 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 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, otherwisefalse
isEmpty
public boolean isEmpty()
If a value is not present, returns true
, otherwise false
.
- 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 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 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 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 isnull
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 isnull
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 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
hashCode
public int hashCode()
Returns the hash code of the value, if present, otherwise 0
(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 this OptionalLong
suitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.