1 /*
   2  * Copyright (c) 2012, 2018, 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.DoubleConsumer;
  28 import java.util.function.DoubleSupplier;
  29 import java.util.function.Supplier;
  30 import java.util.stream.DoubleStream;
  31 
  32 /**
  33  * A container object which may or may not contain a {@code double} value.
  34  * If a value is present, {@code isPresent()} returns {@code true}. If no
  35  * value is present, the object is considered <i>empty</i> and
  36  * {@code isPresent()} returns {@code false}.
  37  *
  38  * <p>Additional methods that depend on the presence or absence of a contained
  39  * value are provided, such as {@link #orElse(double) orElse()}
  40  * (returns a default value if no value is present) and
  41  * {@link #ifPresent(DoubleConsumer) ifPresent()} (performs
  42  * an action if a value is present).
  43  *
  44  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>
  45  * class; use of identity-sensitive operations (including reference equality
  46  * ({@code ==}), identity hash code, or synchronization) on instances of
  47  * {@code OptionalDouble} may have unpredictable results and should be avoided.
  48  *
  49  * @apiNote
  50  * {@code OptionalDouble} is primarily intended for use as a method return type where
  51  * there is a clear need to represent "no result." A variable whose type is
  52  * {@code OptionalDouble} should never itself be {@code null}; it should always point
  53  * to an {@code OptionalDouble} instance.
  54  *
  55  * @since 1.8
  56  */
  57 public final class OptionalDouble {
  58     /**
  59      * Common instance for {@code empty()}.
  60      */
  61     private static final OptionalDouble EMPTY = new OptionalDouble();
  62 
  63     /**
  64      * If true then the value is present, otherwise indicates no value is present
  65      */
  66     private final boolean isPresent;
  67     private final double value;
  68 
  69     /**
  70      * Construct an empty instance.
  71      *
  72      * @implNote generally only one empty instance, {@link OptionalDouble#EMPTY},
  73      * should exist per VM.
  74      */
  75     private OptionalDouble() {
  76         this.isPresent = false;
  77         this.value = Double.NaN;
  78     }
  79 
  80     /**
  81      * Returns an empty {@code OptionalDouble} instance.  No value is present
  82      * for this {@code OptionalDouble}.
  83      *
  84      * @apiNote
  85      * Though it may be tempting to do so, avoid testing if an object is empty
  86      * by comparing with {@code ==} against instances returned by
  87      * {@code OptionalDouble.empty()}.  There is no guarantee that it is a singleton.
  88      * Instead, use {@link #isPresent()}.
  89      *
  90      *  @return an empty {@code OptionalDouble}.
  91      */
  92     public static OptionalDouble empty() {
  93         return EMPTY;
  94     }
  95 
  96     /**
  97      * Construct an instance with the described value.
  98      *
  99      * @param value the double value to describe.
 100      */
 101     private OptionalDouble(double value) {
 102         this.isPresent = true;
 103         this.value = value;
 104     }
 105 
 106     /**
 107      * Returns an {@code OptionalDouble} describing the given value.
 108      *
 109      * @param value the value to describe
 110      * @return an {@code OptionalDouble} with the value present
 111      */
 112     public static OptionalDouble of(double value) {
 113         return new OptionalDouble(value);
 114     }
 115 
 116     /**
 117      * If a value is present, returns the value, otherwise throws
 118      * {@code NoSuchElementException}.
 119      *
 120      * @apiNote
 121      * The preferred alternative to this method is {@link #orElseThrow()}.
 122      *
 123      * @return the value described by this {@code OptionalDouble}
 124      * @throws NoSuchElementException if no value is present
 125      */
 126     public double getAsDouble() {
 127         if (!isPresent) {
 128             throw new NoSuchElementException("No value present");
 129         }
 130         return value;
 131     }
 132 
 133     /**
 134      * If a value is present, returns {@code true}, otherwise {@code false}.
 135      *
 136      * @return {@code true} if a value is present, otherwise {@code false}
 137      */
 138     public boolean isPresent() {
 139         return isPresent;
 140     }
 141 
 142     /**
 143      * If a value is not present, returns {@code true}, otherwise
 144      * {@code false}.
 145      *
 146      * @return {@code true} if a value is not present, otherwise {@code false}
 147      */
 148     public boolean isEmpty() {
 149         return !isPresent;
 150     }
 151 
 152 
 153     /**
 154      * If a value is present, performs the given action with the value,
 155      * otherwise does nothing.
 156      *
 157      * @param action the action to be performed, if a value is present
 158      * @throws NullPointerException if value is present and the given action is
 159      *         {@code null}
 160      */
 161     public void ifPresent(DoubleConsumer action) {
 162         if (isPresent) {
 163             action.accept(value);
 164         }
 165     }
 166 
 167     /**
 168      * If a value is present, performs the given action with the value,
 169      * otherwise performs the given empty-based action.
 170      *
 171      * @param action the action to be performed, if a value is present
 172      * @param emptyAction the empty-based action to be performed, if no value is
 173      * present
 174      * @throws NullPointerException if a value is present and the given action
 175      *         is {@code null}, or no value is present and the given empty-based
 176      *         action is {@code null}.
 177      * @since 9
 178      */
 179     public void ifPresentOrElse(DoubleConsumer action, Runnable emptyAction) {
 180         if (isPresent) {
 181             action.accept(value);
 182         } else {
 183             emptyAction.run();
 184         }
 185     }
 186 
 187     /**
 188      * If a value is present, returns a sequential {@link DoubleStream}
 189      * containing only that value, otherwise returns an empty
 190      * {@code DoubleStream}.
 191      *
 192      * @apiNote
 193      * This method can be used to transform a {@code Stream} of optional doubles
 194      * to a {@code DoubleStream} of present doubles:
 195      * <pre>{@code
 196      *     Stream<OptionalDouble> os = ..
 197      *     DoubleStream s = os.flatMapToDouble(OptionalDouble::stream)
 198      * }</pre>
 199      *
 200      * @return the optional value as a {@code DoubleStream}
 201      * @since 9
 202      */
 203     public DoubleStream stream() {
 204         if (isPresent) {
 205             return DoubleStream.of(value);
 206         } else {
 207             return DoubleStream.empty();
 208         }
 209     }
 210 
 211     /**
 212      * If a value is present, returns the value, otherwise returns
 213      * {@code other}.
 214      *
 215      * @param other the value to be returned, if no value is present
 216      * @return the value, if present, otherwise {@code other}
 217      */
 218     public double orElse(double other) {
 219         return isPresent ? value : other;
 220     }
 221 
 222     /**
 223      * If a value is present, returns the value, otherwise returns the result
 224      * produced by the supplying function.
 225      *
 226      * @param supplier the supplying function that produces a value to be returned
 227      * @return the value, if present, otherwise the result produced by the
 228      *         supplying function
 229      * @throws NullPointerException if no value is present and the supplying
 230      *         function is {@code null}
 231      */
 232     public double orElseGet(DoubleSupplier supplier) {
 233         return isPresent ? value : supplier.getAsDouble();
 234     }
 235 
 236     /**
 237      * If a value is present, returns the value, otherwise throws
 238      * {@code NoSuchElementException}.
 239      *
 240      * @return the value described by this {@code OptionalDouble}
 241      * @throws NoSuchElementException if no value is present
 242      * @since 10
 243      */
 244     public double orElseThrow() {
 245         if (!isPresent) {
 246             throw new NoSuchElementException("No value present");
 247         }
 248         return value;
 249     }
 250 
 251     /**
 252      * If a value is present, returns the value, otherwise throws an exception
 253      * produced by the exception supplying function.
 254      *
 255      * @apiNote
 256      * A method reference to the exception constructor with an empty argument
 257      * list can be used as the supplier. For example,
 258      * {@code IllegalStateException::new}
 259      *
 260      * @param <X> Type of the exception to be thrown
 261      * @param exceptionSupplier the supplying function that produces an
 262      *        exception to be thrown
 263      * @return the value, if present
 264      * @throws X if no value is present
 265      * @throws NullPointerException if no value is present and the exception
 266      *         supplying function is {@code null}
 267      */
 268     public<X extends Throwable> double orElseThrow(Supplier<? extends X> exceptionSupplier) throws X {
 269         if (isPresent) {
 270             return value;
 271         } else {
 272             throw exceptionSupplier.get();
 273         }
 274     }
 275 
 276     /**
 277      * Indicates whether some other object is "equal to" this
 278      * {@code OptionalDouble}. The other object is considered equal if:
 279      * <ul>
 280      * <li>it is also an {@code OptionalDouble} and;
 281      * <li>both instances have no value present or;
 282      * <li>the present values are "equal to" each other via
 283      * {@code Double.compare() == 0}.
 284      * </ul>
 285      *
 286      * @param obj an object to be tested for equality
 287      * @return {@code true} if the other object is "equal to" this object
 288      *         otherwise {@code false}
 289      */
 290     @Override
 291     public boolean equals(Object obj) {
 292         if (this == obj) {
 293             return true;
 294         }
 295 
 296         if (!(obj instanceof OptionalDouble)) {
 297             return false;
 298         }
 299 
 300         OptionalDouble other = (OptionalDouble) obj;
 301         return (isPresent && other.isPresent)
 302                ? Double.compare(value, other.value) == 0
 303                : isPresent == other.isPresent;
 304     }
 305 
 306     /**
 307      * Returns the hash code of the value, if present, otherwise {@code 0}
 308      * (zero) if no value is present.
 309      *
 310      * @return hash code value of the present value or {@code 0} if no value is
 311      *         present
 312      */
 313     @Override
 314     public int hashCode() {
 315         return isPresent ? Double.hashCode(value) : 0;
 316     }
 317 
 318     /**
 319      * Returns a non-empty string representation of this {@code OptionalDouble}
 320      * suitable for debugging.  The exact presentation format is unspecified and
 321      * may vary between implementations and versions.
 322      *
 323      * @implSpec
 324      * If a value is present the result must include its string representation
 325      * in the result.  Empty and present {@code OptionalDouble}s must be
 326      * unambiguously differentiable.
 327      *
 328      * @return the string representation of this instance
 329      */
 330     @Override
 331     public String toString() {
 332         return isPresent
 333                 ? String.format("OptionalDouble[%s]", value)
 334                 : "OptionalDouble.empty";
 335     }
 336 }