Additional methods that depend on the presence or absence of a contained * value are provided, such as {@link #orElse(long) orElse()} * (returns a default value if no value is present) and * {@link #ifPresent(LongConsumer) ifPresent()} (performs an * action if a value is present). * *
This is a value-based * class; use of identity-sensitive operations (including reference equality * ({@code ==}), identity hash code, or synchronization) on instances of * {@code OptionalLong} may have unpredictable results and should be avoided. * * @apiNote * {@code 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 is * {@code OptionalLong} should never itself be {@code null}; it should always point * to an {@code OptionalLong} instance. * * @since 1.8 */ public final class OptionalLong { /** * Common instance for {@code empty()}. */ private static final OptionalLong EMPTY = new OptionalLong(); /** * If true then the value is present, otherwise indicates no value is present */ private final boolean isPresent; private final long value; /** * Construct an empty instance. * * @implNote generally only one empty instance, {@link OptionalLong#EMPTY}, * should exist per VM. */ private OptionalLong() { this.isPresent = false; this.value = 0; } /** * Returns an empty {@code OptionalLong} instance. No value is present for * this {@code OptionalLong}. * * @apiNote * Though it may be tempting to do so, avoid testing if an object is empty * by comparing with {@code ==} against instances returned by * {@code OptionalLong.empty()}. There is no guarantee that it is a singleton. * Instead, use {@link #isPresent()}. * * @return an empty {@code OptionalLong}. */ public static OptionalLong empty() { return EMPTY; } /** * Construct an instance with the described value. * * @param value the long value to describe */ private OptionalLong(long value) { this.isPresent = true; this.value = value; } /** * Returns an {@code OptionalLong} describing the given value. * * @param value the value to describe * @return an {@code OptionalLong} with the value present */ public static OptionalLong of(long value) { return new OptionalLong(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 OptionalLong} * @throws NoSuchElementException if no value is present */ public long getAsLong() { 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 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(LongConsumer 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(LongConsumer action, Runnable emptyAction) { if (isPresent) { action.accept(value); } else { emptyAction.run(); } } /** * If a value is present, returns a sequential {@link LongStream} containing * only that value, otherwise returns an empty {@code LongStream}. * * @apiNote * This method can be used to transform a {@code Stream} of optional longs * to an {@code LongStream} of present longs: *
{@code
* Stream os = ..
* LongStream s = os.flatMapToLong(OptionalLong::stream)
* }
*
* @return the optional value as an {@code LongStream}
* @since 9
*/
public LongStream stream() {
if (isPresent) {
return LongStream.of(value);
} else {
return LongStream.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 long orElse(long 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 long orElseGet(LongSupplier supplier) {
return isPresent ? value : supplier.getAsLong();
}
/**
* If a value is present, returns the value, otherwise throws
* {@code NoSuchElementException}.
*
* @return the value described by this {@code OptionalLong}
* @throws NoSuchElementException if no value is present
* @since 10
*/
public long 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