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 }