Class OptionalInt
- java.lang.Object
-
- java.util.OptionalInt
public final class OptionalInt extends Object
A container object which may or may not contain an int
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 OptionalInt
may have unpredictable results and should be avoided.
- API Note:
-
OptionalInt
is primarily intended for use as a method return type where there is a clear need to represent "no result." A variable whose type isOptionalInt
should never itself benull
; it should always point to anOptionalInt
instance. - Since:
- 1.8
Method Summary
Modifier and Type | Method | Description |
---|---|---|
static OptionalInt | empty() | Returns an empty |
boolean | equals(Object obj) | Indicates whether some other object is "equal to" this |
int | getAsInt() | If a value is present, returns the value, otherwise throws |
int | hashCode() | Returns the hash code of the value, if present, otherwise |
void | ifPresent(IntConsumer action) | If a value is present, performs the given action with the value, otherwise does nothing. |
void | ifPresentOrElse(IntConsumer 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 OptionalInt | of(int value) | Returns an |
int | orElse(int other) | If a value is present, returns the value, otherwise returns |
int | orElseGet(IntSupplier supplier) | If a value is present, returns the value, otherwise returns the result produced by the supplying function. |
int | 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. |
IntStream | 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 OptionalInt empty()
Returns an empty OptionalInt
instance. No value is present for this OptionalInt
.
- API Note:
- Though it may be tempting to do so, avoid testing if an object is empty by comparing with
==
against instances returned byOptionalInt.empty()
. There is no guarantee that it is a singleton. Instead, useisPresent()
. - Returns:
- an empty
OptionalInt
of
public static OptionalInt of(int value)
Returns an OptionalInt
describing the given value.
- Parameters:
-
value
- the value to describe - Returns:
- an
OptionalInt
with the value present
getAsInt
public int getAsInt()
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
OptionalInt
- 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(IntConsumer 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(IntConsumer 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 IntStream stream()
If a value is present, returns a sequential IntStream
containing only that value, otherwise returns an empty IntStream
.
- API Note:
- This method can be used to transform a
Stream
of optional integers to anIntStream
of present integers:Stream<OptionalInt> os = .. IntStream s = os.flatMapToInt(OptionalInt::stream)
- Returns:
- the optional value as an
IntStream
- Since:
- 9
orElse
public int orElse(int 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 int orElseGet(IntSupplier 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 int orElseThrow()
If a value is present, returns the value, otherwise throws NoSuchElementException
.
- Returns:
- the value described by this
OptionalInt
- Throws:
-
NoSuchElementException
- if no value is present - Since:
- 10
orElseThrow
public <X extends Throwable> int 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 OptionalInt
. The other object is considered equal if:
- it is also an
OptionalInt
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 OptionalInt
suitable for debugging. The exact presentation format is unspecified and may vary between implementations and versions.