1 /*
   2  * Copyright (c) 2012, 2017, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package java.util;
  26 
  27 import java.util.function.IntConsumer;
  28 import java.util.function.IntSupplier;
  29 import java.util.function.Supplier;
  30 import java.util.stream.IntStream;
  31 
  32 /**
  33  * A container object which may or may not contain an {@code int} value.  If a
  34  * value is present, {@code isPresent()} returns {@code true} and
  35  * {@code getAsInt()} returns the value.
  36  *
  37  * <p>Additional methods that depend on the presence or absence of a contained
  38  * value are provided, such as {@link #orElse(int) orElse()}
  39  * (returns a default value if no value is present) and
  40  * {@link #ifPresent(IntConsumer) ifPresent()} (performs an
  41  * action if a value is present).
  42  *
  43  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
  44  * class; use of identity-sensitive operations (including reference equality
  45  * ({@code ==}), identity hash code, or synchronization) on instances of
  46  * {@code OptionalInt} may have unpredictable results and should be avoided.
  47  *
  48  * @apiNote
  49  * {@code OptionalInt} is primarily intended for use as a method return type where
  50  * there is a clear need to represent "no result." A variable whose type is
  51  * {@code OptionalInt} should never itself be {@code null}; it should always point
  52  * to an {@code OptionalInt} instance.
  53  *
  54  * @since 1.8
  55  */
  56 public final class OptionalInt {
  57     /**
  58      * Common instance for {@code empty()}.
  59      */
  60     private static final OptionalInt EMPTY = new OptionalInt();
  61 
  62     /**
  63      * If true then the value is present, otherwise indicates no value is present
  64      */
  65     private final boolean isPresent;
  66     private final int value;
  67 
  68     /**
  69      * Construct an empty instance.
  70      *
  71      * @implNote Generally only one empty instance, {@link OptionalInt#EMPTY},
  72      * should exist per VM.
  73      */
  74     private OptionalInt() {
  75         this.isPresent = false;
  76         this.value = 0;
  77     }
  78 
  79     /**
  80      * Returns an empty {@code OptionalInt} instance.  No value is present for
  81      * this {@code OptionalInt}.
  82      *
  83      * @apiNote
  84      * Though it may be tempting to do so, avoid testing if an object is empty
  85      * by comparing with {@code ==} against instances returned by
  86      * {@code OptionalInt.empty()}.  There is no guarantee that it is a singleton.
  87      * Instead, use {@link #isPresent()}.
  88      *
  89      * @return an empty {@code OptionalInt}
  90      */
  91     public static OptionalInt empty() {
  92         return EMPTY;
  93     }
  94 
  95     /**
  96      * Construct an instance with the described value.
  97      *
  98      * @param value the int value to describe
  99      */
 100     private OptionalInt(int value) {
 101         this.isPresent = true;
 102         this.value = value;
 103     }
 104 
 105     /**
 106      * Returns an {@code OptionalInt} describing the given value.
 107      *
 108      * @param value the value to describe
 109      * @return an {@code OptionalInt} with the value present
 110      */
 111     public static OptionalInt of(int value) {
 112         return new OptionalInt(value);
 113     }
 114 
 115     /**
 116      * If a value is present, returns the value, otherwise throws
 117      * {@code NoSuchElementException}.
 118      *
 119      * @apiNote
 120      * The methods {@link #orElse(int) orElse} and
 121      * {@link #orElseGet(IntSupplier) orElseGet}
 122      * are generally preferable to this method, as they return a substitute
 123      * value if the value is absent, instead of throwing an exception.
 124      *
 125      * @return the value described by this {@code OptionalInt}
 126      * @throws NoSuchElementException if no value is present
 127      * @see OptionalInt#isPresent()
 128      */
 129     public int getAsInt() {
 130         if (!isPresent) {
 131             throw new NoSuchElementException("No value present");
 132         }
 133         return value;
 134     }
 135 
 136     /**
 137      * If a value is present, returns {@code true}, otherwise {@code false}.
 138      *
 139      * @return {@code true} if a value is present, otherwise {@code false}
 140      */
 141     public boolean isPresent() {
 142         return isPresent;
 143     }
 144 
 145     /**
 146      * If a value is present, performs the given action with the value,
 147      * otherwise does nothing.
 148      *
 149      * @param action the action to be performed, if a value is present
 150      * @throws NullPointerException if value is present and the given action is
 151      *         {@code null}
 152      */
 153     public void ifPresent(IntConsumer action) {
 154         if (isPresent) {
 155             action.accept(value);
 156         }
 157     }
 158 
 159     /**
 160      * If a value is present, performs the given action with the value,
 161      * otherwise performs the given empty-based action.
 162      *
 163      * @param action the action to be performed, if a value is present
 164      * @param emptyAction the empty-based action to be performed, if no value is
 165      *        present
 166      * @throws NullPointerException if a value is present and the given action
 167      *         is {@code null}, or no value is present and the given empty-based
 168      *         action is {@code null}.
 169      * @since 9
 170      */
 171     public void ifPresentOrElse(IntConsumer action, Runnable emptyAction) {
 172         if (isPresent) {
 173             action.accept(value);
 174         } else {
 175             emptyAction.run();
 176         }
 177     }
 178 
 179     /**
 180      * If a value is present, returns a sequential {@link IntStream} containing
 181      * only that value, otherwise returns an empty {@code IntStream}.
 182      *
 183      * @apiNote
 184      * This method can be used to transform a {@code Stream} of optional
 185      * integers to an {@code IntStream} of present integers:
 186      * <pre>{@code
 187      *     Stream<OptionalInt> os = ..
 188      *     IntStream s = os.flatMapToInt(OptionalInt::stream)
 189      * }</pre>
 190      *
 191      * @return the optional value as an {@code IntStream}
 192      * @since 9
 193      */
 194     public IntStream stream() {
 195         if (isPresent) {
 196             return IntStream.of(value);
 197         } else {
 198             return IntStream.empty();
 199         }
 200     }
 201 
 202     /**
 203      * If a value is present, returns the value, otherwise returns
 204      * {@code other}.
 205      *
 206      * @param other the value to be returned, if no value is present
 207      * @return the value, if present, otherwise {@code other}
 208      */
 209     public int orElse(int other) {
 210         return isPresent ? value : other;
 211     }
 212 
 213     /**
 214      * If a value is present, returns the value, otherwise returns the result
 215      * produced by the supplying function.
 216      *
 217      * @param supplier the supplying function that produces a value to be returned
 218      * @return the value, if present, otherwise the result produced by the
 219      *         supplying function
 220      * @throws NullPointerException if no value is present and the supplying
 221      *         function is {@code null}
 222      */
 223     public int orElseGet(IntSupplier supplier) {
 224         return isPresent ? value : supplier.getAsInt();
 225     }
 226 
 227     /**
 228      * If a value is present, returns the value, otherwise throws an exception
 229      * produced by the exception supplying function.
 230      *
 231      * @apiNote
 232      * A method reference to the exception constructor with an empty argument
 233      * list can be used as the supplier. For example,
 234      * {@code IllegalStateException::new}
 235      *
 236      * @param <X> Type of the exception to be thrown
 237      * @param exceptionSupplier the supplying function that produces an
 238      *        exception to be thrown
 239      * @return the value, if present
 240      * @throws X if no value is present
 241      * @throws NullPointerException if no value is present and the exception
 242      *         supplying function is {@code null}
 243      */
 244     public<X extends Throwable> int orElseThrow(Supplier<? extends X> exceptionSupplier) throws X {
 245         if (isPresent) {
 246             return value;
 247         } else {
 248             throw exceptionSupplier.get();
 249         }
 250     }
 251 
 252     /**
 253      * Indicates whether some other object is "equal to" this
 254      * {@code OptionalInt}.  The other object is considered equal if:
 255      * <ul>
 256      * <li>it is also an {@code OptionalInt} and;
 257      * <li>both instances have no value present or;
 258      * <li>the present values are "equal to" each other via {@code ==}.
 259      * </ul>
 260      *
 261      * @param obj an object to be tested for equality
 262      * @return {@code true} if the other object is "equal to" this object
 263      *         otherwise {@code false}
 264      */
 265     @Override
 266     public boolean equals(Object obj) {
 267         if (this == obj) {
 268             return true;
 269         }
 270 
 271         if (!(obj instanceof OptionalInt)) {
 272             return false;
 273         }
 274 
 275         OptionalInt other = (OptionalInt) obj;
 276         return (isPresent && other.isPresent)
 277                 ? value == other.value
 278                 : isPresent == other.isPresent;
 279     }
 280 
 281     /**
 282      * Returns the hash code of the value, if present, otherwise {@code 0}
 283      * (zero) if no value is present.
 284      *
 285      * @return hash code value of the present value or {@code 0} if no value is
 286      *         present
 287      */
 288     @Override
 289     public int hashCode() {
 290         return isPresent ? Integer.hashCode(value) : 0;
 291     }
 292 
 293     /**
 294      * Returns a non-empty string representation of this {@code OptionalInt}
 295      * suitable for debugging.  The exact presentation format is unspecified and
 296      * may vary between implementations and versions.
 297      *
 298      * @implSpec
 299      * If a value is present the result must include its string representation
 300      * in the result.  Empty and present {@code OptionalInt}s must be
 301      * unambiguously differentiable.
 302      *
 303      * @return the string representation of this instance
 304      */
 305     @Override
 306     public String toString() {
 307         return isPresent
 308                 ? String.format("OptionalInt[%s]", value)
 309                 : "OptionalInt.empty";
 310     }
 311 }