1 /*

     2  * Copyright (c) 2012, 2013, 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.LongConsumer;

    28 import java.util.function.LongSupplier;

    29 import java.util.function.Supplier;

    30 

    31 /**

    32  * A container object which may or may not contain a {@code long} value.

    33  * If a value is present, {@code isPresent()} will return {@code true} and

    34  * {@code getAsLong()} will return the value.

    35  *

    36  * <p>Additional methods that depend on the presence or absence of a contained

    37  * value are provided, such as {@link #orElse(long) orElse()}

    38  * (return a default value if value not present) and

    39  * {@link #ifPresent(java.util.function.LongConsumer) ifPresent()} (execute a block

    40  * of code if the value is present).

    41  *

    42  * <p>This is a <a href="../lang/doc-files/ValueBased.html">value-based</a>

    43  * class; use of identity-sensitive operations (including reference equality

    44  * ({@code ==}), identity hash code, or synchronization) on instances of

    45  * {@code OptionalLong} may have unpredictable results and should be avoided.

    46  *

    47  * @since 1.8

    48  */

    49 public final class OptionalLong {

    50     /**

    51      * Common instance for {@code empty()}.

    52      */

    53     private static final OptionalLong EMPTY = new OptionalLong();

    54 

    55     /**

    56      * If true then the value is present, otherwise indicates no value is present

    57      */

    58     private final boolean isPresent;

    59     private final long value;

    60 

    61     /**

    62      * Construct an empty instance.

    63      *

    64      * @implNote generally only one empty instance, {@link OptionalLong#EMPTY},

    65      * should exist per VM.

    66      */

    67     private OptionalLong() {

    68         this.isPresent = false;

    69         this.value = 0;

    70     }

    71 

    72     /**

    73      * Returns an empty {@code OptionalLong} instance.  No value is present for this

    74      * OptionalLong.

    75      *

    76      * @apiNote Though it may be tempting to do so, avoid testing if an object

    77      * is empty by comparing with {@code ==} against instances returned by

    78      * {@code Option.empty()}. There is no guarantee that it is a singleton.

    79      * Instead, use {@link #isPresent()}.

    80      *

    81      *  @return an empty {@code OptionalLong}.

    82      */

    83     public static OptionalLong empty() {

    84         return EMPTY;

    85     }

    86 

    87     /**

    88      * Construct an instance with the value present.

    89      *

    90      * @param value the long value to be present

    91      */

    92     private OptionalLong(long value) {

    93         this.isPresent = true;

    94         this.value = value;

    95     }

    96 

    97     /**

    98      * Return an {@code OptionalLong} with the specified value present.

    99      *

   100      * @param value the value to be present

   101      * @return an {@code OptionalLong} with the value present

   102      */

   103     public static OptionalLong of(long value) {

   104         return new OptionalLong(value);

   105     }

   106 

   107     /**

   108      * If a value is present in this {@code OptionalLong}, returns the value,

   109      * otherwise throws {@code NoSuchElementException}.

   110      *

   111      * @return the value held by this {@code OptionalLong}

   112      * @throws NoSuchElementException if there is no value present

   113      *

   114      * @see OptionalLong#isPresent()

   115      */

   116     public long getAsLong() {

   117         if (!isPresent) {

   118             throw new NoSuchElementException("No value present");

   119         }

   120         return value;

   121     }

   122 

   123     /**

   124      * Return {@code true} if there is a value present, otherwise {@code false}.

   125      *

   126      * @return {@code true} if there is a value present, otherwise {@code false}

   127      */

   128     public boolean isPresent() {

   129         return isPresent;

   130     }

   131 

   132     /**

   133      * Have the specified consumer accept the value if a value is present,

   134      * otherwise do nothing.

   135      *

   136      * @param consumer block to be executed if a value is present

   137      * @throws NullPointerException if value is present and {@code consumer} is

   138      * null

   139      */

   140     public void ifPresent(LongConsumer consumer) {

   141         if (isPresent)

   142             consumer.accept(value);

   143     }

   144 

   145     /**

   146      * Return the value if present, otherwise return {@code other}.

   147      *

   148      * @param other the value to be returned if there is no value present

   149      * @return the value, if present, otherwise {@code other}

   150      */

   151     public long orElse(long other) {

   152         return isPresent ? value : other;

   153     }

   154 

   155     /**

   156      * Return the value if present, otherwise invoke {@code other} and return

   157      * the result of that invocation.

   158      *

   159      * @param other a {@code LongSupplier} whose result is returned if no value

   160      * is present

   161      * @return the value if present otherwise the result of {@code other.getAsLong()}

   162      * @throws NullPointerException if value is not present and {@code other} is

   163      * null

   164      */

   165     public long orElseGet(LongSupplier other) {

   166         return isPresent ? value : other.getAsLong();

   167     }

   168 

   169     /**

   170      * Return the contained value, if present, otherwise throw an exception

   171      * to be created by the provided supplier.

   172      *

   173      * @apiNote A method reference to the exception constructor with an empty

   174      * argument list can be used as the supplier. For example,

   175      * {@code IllegalStateException::new}

   176      *

   177      * @param <X> Type of the exception to be thrown

   178      * @param exceptionSupplier The supplier which will return the exception to

   179      * be thrown

   180      * @return the present value

   181      * @throws X if there is no value present

   182      * @throws NullPointerException if no value is present and

   183      * {@code exceptionSupplier} is null

   184      */

   185     public<X extends Throwable> long orElseThrow(Supplier<X> exceptionSupplier) throws X {

   186         if (isPresent) {

   187             return value;

   188         } else {

   189             throw exceptionSupplier.get();

   190         }

   191     }

   192 

   193     /**

   194      * Indicates whether some other object is "equal to" this OptionalLong. The

   195      * other object is considered equal if:

   196      * <ul>

   197      * <li>it is also an {@code OptionalLong} and;

   198      * <li>both instances have no value present or;

   199      * <li>the present values are "equal to" each other via {@code ==}.

   200      * </ul>

   201      *

   202      * @param obj an object to be tested for equality

   203      * @return {code true} if the other object is "equal to" this object

   204      * otherwise {@code false}

   205      */

   206     @Override

   207     public boolean equals(Object obj) {

   208         if (this == obj) {

   209             return true;

   210         }

   211 

   212         if (!(obj instanceof OptionalLong)) {

   213             return false;

   214         }

   215 

   216         OptionalLong other = (OptionalLong) obj;

   217         return (isPresent && other.isPresent)

   218                 ? value == other.value

   219                 : isPresent == other.isPresent;

   220     }

   221 

   222     /**

   223      * Returns the hash code value of the present value, if any, or 0 (zero) if

   224      * no value is present.

   225      *

   226      * @return hash code value of the present value or 0 if no value is present

   227      */

   228     @Override

   229     public int hashCode() {

   230         return isPresent ? Long.hashCode(value) : 0;

   231     }

   232 

   233     /**

   234      * {@inheritDoc}

   235      *

   236      * Returns a non-empty string representation of this object suitable for

   237      * debugging. The exact presentation format is unspecified and may vary

   238      * between implementations and versions.

   239      *

   240      * @implSpec If a value is present the result must include its string

   241      * representation in the result. Empty and present instances must be

   242      * unambiguously differentiable.

   243      *

   244      * @return the string representation of this instance

   245      */

   246     @Override

   247     public String toString() {

   248         return isPresent

   249                 ? String.format("OptionalLong[%s]", value)

   250                 : "OptionalLong.empty";

   251     }

   252 }