javadoc.src-html.com.google.common.collect.DiscreteDomain.html Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of guava-osgi
Repackaging of Google Guava libraries as OSGi bundle
The newest version!


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     * @author Kevin Bourrillion
036     * @since 10.0
037     * @see DiscreteDomains
038     */
039    @GwtCompatible
040    @Beta
041    public abstract class DiscreteDomain<C extends Comparable> {
042      /** Constructor for use by subclasses. */
043      protected DiscreteDomain() {}
044    
045      /**
046       * Returns the unique least value of type {@code C} that is greater than
047       * {@code value}, or {@code null} if none exists. Inverse operation to {@link
048       * #previous}.
049       *
050       * @param value any value of type {@code C}
051       * @return the least value greater than {@code value}, or {@code null} if
052       *     {@code value} is {@code maxValue()}
053       */
054      public abstract C next(C value);
055    
056      /**
057       * Returns the unique greatest value of type {@code C} that is less than
058       * {@code value}, or {@code null} if none exists. Inverse operation to {@link
059       * #next}.
060       *
061       * @param value any value of type {@code C}
062       * @return the greatest value less than {@code value}, or {@code null} if
063       *     {@code value} is {@code minValue()}
064       */
065      public abstract C previous(C value);
066    
067      /**
068       * Returns a signed value indicating how many nested invocations of {@link
069       * #next} (if positive) or {@link #previous} (if negative) are needed to reach
070       * {@code end} starting from {@code start}. For example, if {@code end =
071       * next(next(next(start)))}, then {@code distance(start, end) == 3} and {@code
072       * distance(end, start) == -3}. As well, {@code distance(a, a)} is always
073       * zero.
074       *
075       * <p>Note that this function is necessarily well-defined for any discrete
076       * type.
077       *
078       * @return the distance as described above, or {@link Long#MIN_VALUE} or
079       *     {@link Long#MIN_VALUE} if the distance is too small or too large,
080       *     respectively.
081       */
082      public abstract long distance(C start, C end);
083    
084      /**
085       * Returns the minimum value of type {@code C}, if it has one. The minimum
086       * value is the unique value for which {@link Comparable#compareTo(Object)}
087       * never returns a positive value for any input of type {@code C}.
088       *
089       * <p>The default implementation throws {@code NoSuchElementException}.
090       *
091       * @return the minimum value of type {@code C}; never null
092       * @throws NoSuchElementException if the type has no (practical) minimum
093       *     value; for example, {@link java.math.BigInteger}
094       */
095      public C minValue() {
096        throw new NoSuchElementException();
097      }
098    
099      /**
100       * Returns the maximum value of type {@code C}, if it has one. The maximum
101       * value is the unique value for which {@link Comparable#compareTo(Object)}
102       * never returns a negative value for any input of type {@code C}.
103       *
104       * <p>The default implementation throws {@code NoSuchElementException}.
105       *
106       * @return the maximum value of type {@code C}; never null
107       * @throws NoSuchElementException if the type has no (practical) maximum
108       *     value; for example, {@link java.math.BigInteger}
109       */
110      public C maxValue() {
111        throw new NoSuchElementException();
112      }
113    }