Additional methods that depend on the presence or absence of a contained * value are provided, such as {@link #orElse(int) orElse()} * (returns a default value if no value is present) and * {@link #ifPresent(IntConsumer) ifPresent()} (performs an * action if a value is present). * *
This is a value-based * class; programmers should treat instances that are * {@linkplain #equals(Object) equal} as interchangeable and should not * use instances for synchronization, or unpredictable behavior may * occur. For example, in a future release, synchronization may fail. * * @apiNote * {@code 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 is * {@code OptionalInt} should never itself be {@code null}; it should always point * to an {@code OptionalInt} instance. * * @since 1.8 */ @jdk.internal.ValueBased public final class OptionalInt { /** * Common instance for {@code empty()}. */ private static final OptionalInt EMPTY = new OptionalInt(); /** * If true then the value is present, otherwise indicates no value is present */ private final boolean isPresent; private final int value; /** * Construct an empty instance. * * @implNote Generally only one empty instance, {@link OptionalInt#EMPTY}, * should exist per VM. */ private OptionalInt() { this.isPresent = false; this.value = 0; } /** * Returns an empty {@code OptionalInt} instance. No value is present for * this {@code OptionalInt}. * * @apiNote * Though it may be tempting to do so, avoid testing if an object is empty * by comparing with {@code ==} or {@code !=} against instances returned by * {@code OptionalInt.empty()}. There is no guarantee that it is a singleton. * Instead, use {@link #isEmpty()} or {@link #isPresent()}. * * @return an empty {@code OptionalInt} */ public static OptionalInt empty() { return EMPTY; } /** * Construct an instance with the described value. * * @param value the int value to describe */ private OptionalInt(int value) { this.isPresent = true; this.value = value; } /** * Returns an {@code OptionalInt} describing the given value. * * @param value the value to describe * @return an {@code OptionalInt} with the value present */ public static OptionalInt of(int value) { return new OptionalInt(value); } /** * If a value is present, returns the value, otherwise throws * {@code NoSuchElementException}. * * @apiNote * The preferred alternative to this method is {@link #orElseThrow()}. * * @return the value described by this {@code OptionalInt} * @throws NoSuchElementException if no value is present */ public int getAsInt() { if (!isPresent) { throw new NoSuchElementException("No value present"); } return value; } /** * If a value is present, returns {@code true}, otherwise {@code false}. * * @return {@code true} if a value is present, otherwise {@code false} */ public boolean isPresent() { return isPresent; } /** * If a value is not present, returns {@code true}, otherwise * {@code false}. * * @return {@code true} if a value is not present, otherwise {@code false} * @since 11 */ public boolean isEmpty() { return !isPresent; } /** * If a value is present, performs the given action with the value, * otherwise does nothing. * * @param action the action to be performed, if a value is present * @throws NullPointerException if value is present and the given action is * {@code null} */ public void ifPresent(IntConsumer action) { if (isPresent) { action.accept(value); } } /** * If a value is present, performs the given action with the value, * otherwise performs the given empty-based action. * * @param action the action to be performed, if a value is present * @param emptyAction the empty-based action to be performed, if no value is * present * @throws NullPointerException if a value is present and the given action * is {@code null}, or no value is present and the given empty-based * action is {@code null}. * @since 9 */ public void ifPresentOrElse(IntConsumer action, Runnable emptyAction) { if (isPresent) { action.accept(value); } else { emptyAction.run(); } } /** * If a value is present, returns a sequential {@link IntStream} containing * only that value, otherwise returns an empty {@code IntStream}. * * @apiNote * This method can be used to transform a {@code Stream} of optional * integers to an {@code IntStream} of present integers: *
{@code
* Stream os = ..
* IntStream s = os.flatMapToInt(OptionalInt::stream)
* }
*
* @return the optional value as an {@code IntStream}
* @since 9
*/
public IntStream stream() {
if (isPresent) {
return IntStream.of(value);
} else {
return IntStream.empty();
}
}
/**
* If a value is present, returns the value, otherwise returns
* {@code other}.
*
* @param other the value to be returned, if no value is present
* @return the value, if present, otherwise {@code other}
*/
public int orElse(int other) {
return isPresent ? value : other;
}
/**
* If a value is present, returns the value, otherwise returns the result
* produced by the supplying function.
*
* @param supplier the supplying function that produces a value to be returned
* @return the value, if present, otherwise the result produced by the
* supplying function
* @throws NullPointerException if no value is present and the supplying
* function is {@code null}
*/
public int orElseGet(IntSupplier supplier) {
return isPresent ? value : supplier.getAsInt();
}
/**
* If a value is present, returns the value, otherwise throws
* {@code NoSuchElementException}.
*
* @return the value described by this {@code OptionalInt}
* @throws NoSuchElementException if no value is present
* @since 10
*/
public int orElseThrow() {
if (!isPresent) {
throw new NoSuchElementException("No value present");
}
return value;
}
/**
* If a value is present, returns the value, otherwise throws an exception
* produced by the exception supplying function.
*
* @apiNote
* A method reference to the exception constructor with an empty argument
* list can be used as the supplier. For example,
* {@code IllegalStateException::new}
*
* @param