    001    /*
    002     * Copyright (C) 2009 The Guava Authors
    003     *
    004     * Licensed under the Apache License, Version 2.0 (the "License");
    005     * you may not use this file except in compliance with the License.
    006     * You may obtain a copy of the License at
    007     *
    008     * http://www.apache.org/licenses/LICENSE-2.0
    009     *
    010     * Unless required by applicable law or agreed to in writing, software
    011     * distributed under the License is distributed on an "AS IS" BASIS,
    012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    013     * See the License for the specific language governing permissions and
    014     * limitations under the License.
    015     */
    016
    017    package com.google.common.collect;
    018
    019    import com.google.common.annotations.Beta;
    020    import com.google.common.annotations.GwtCompatible;
    021
    022    import java.util.NoSuchElementException;
    023
    024    /**
    025     * A descriptor for a <i>discrete</i> {@code Comparable} domain such as all
    026     * {@link Integer}s. A discrete domain is one that supports the three basic
    027     * operations: {@link #next}, {@link #previous} and {@link #distance}, according
    028     * to their specifications. The methods {@link #minValue} and {@link #maxValue}
    029     * should also be overridden for bounded types.
    030     *
    031     * <p>A discrete domain always represents the <i>entire</i> set of values of its
    032     * type; it cannot represent partial domains such as "prime integers" or
    033     * "strings of length 5."
    034     *
    035     * <p>See the Guava User Guide section on <a href=
    036     * "http://code.google.com/p/guava-libraries/wiki/RangesExplained#Discrete_Domains">
    037     * {@code DiscreteDomain}</a>.
    038     *
    039     * @author Kevin Bourrillion
    040     * @since 10.0
    041     * @see DiscreteDomains
    042     */
    043    @GwtCompatible
    044    @Beta
    045    public abstract class DiscreteDomain<C extends Comparable> {
    046      /** Constructor for use by subclasses. */
    047      protected DiscreteDomain() {}
    048
    049      /**
    050       * Returns the unique least value of type {@code C} that is greater than
    051       * {@code value}, or {@code null} if none exists. Inverse operation to {@link
    052       * #previous}.
    053       *
    054       * @param value any value of type {@code C}
    055       * @return the least value greater than {@code value}, or {@code null} if
    056       *     {@code value} is {@code maxValue()}
    057       */
    058      public abstract C next(C value);
    059
    060      /**
    061       * Returns the unique greatest value of type {@code C} that is less than
    062       * {@code value}, or {@code null} if none exists. Inverse operation to {@link
    063       * #next}.
    064       *
    065       * @param value any value of type {@code C}
    066       * @return the greatest value less than {@code value}, or {@code null} if
    067       *     {@code value} is {@code minValue()}
    068       */
    069      public abstract C previous(C value);
    070
    071      /**
    072       * Returns a signed value indicating how many nested invocations of {@link
    073       * #next} (if positive) or {@link #previous} (if negative) are needed to reach
    074       * {@code end} starting from {@code start}. For example, if {@code end =
    075       * next(next(next(start)))}, then {@code distance(start, end) == 3} and {@code
    076       * distance(end, start) == -3}. As well, {@code distance(a, a)} is always
    077       * zero.
    078       *
    079       * <p>Note that this function is necessarily well-defined for any discrete
    080       * type.
    081       *
    082       * @return the distance as described above, or {@link Long#MIN_VALUE} or
    083       *     {@link Long#MAX_VALUE} if the distance is too small or too large,
    084       *     respectively.
    085       */
    086      public abstract long distance(C start, C end);
    087
    088      /**
    089       * Returns the minimum value of type {@code C}, if it has one. The minimum
    090       * value is the unique value for which {@link Comparable#compareTo(Object)}
    091       * never returns a positive value for any input of type {@code C}.
    092       *
    093       * <p>The default implementation throws {@code NoSuchElementException}.
    094       *
    095       * @return the minimum value of type {@code C}; never null
    096       * @throws NoSuchElementException if the type has no (practical) minimum
    097       *     value; for example, {@link java.math.BigInteger}
    098       */
    099      public C minValue() {
    100        throw new NoSuchElementException();
    101      }
    102
    103      /**
    104       * Returns the maximum value of type {@code C}, if it has one. The maximum
    105       * value is the unique value for which {@link Comparable#compareTo(Object)}
    106       * never returns a negative value for any input of type {@code C}.
    107       *
    108       * <p>The default implementation throws {@code NoSuchElementException}.
    109       *
    110       * @return the maximum value of type {@code C}; never null
    111       * @throws NoSuchElementException if the type has no (practical) maximum
    112       *     value; for example, {@link java.math.BigInteger}
    113       */
    114      public C maxValue() {
    115        throw new NoSuchElementException();
    116      }
    117    }