1 /* 2 * Copyright (C) 2009 The Guava Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.google.common.collect; 18 19 import com.google.common.annotations.Beta; 20 import com.google.common.annotations.GwtCompatible; 21 22 import java.util.NoSuchElementException; 23 24 /** 25 * A descriptor for a <i>discrete</i> {@code Comparable} domain such as all 26 * {@link Integer}s. A discrete domain is one that supports the three basic 27 * operations: {@link #next}, {@link #previous} and {@link #distance}, according 28 * to their specifications. The methods {@link #minValue} and {@link #maxValue} 29 * should also be overridden for bounded types. 30 * 31 * <p>A discrete domain always represents the <i>entire</i> set of values of its 32 * type; it cannot represent partial domains such as "prime integers" or 33 * "strings of length 5." 34 * 35 * @author Kevin Bourrillion 36 * @since 10.0 37 * @see DiscreteDomains 38 */ 39 @GwtCompatible 40 @Beta 41 public abstract class DiscreteDomain<C extends Comparable> { 42 /** Constructor for use by subclasses. */ 43 protected DiscreteDomain() {} 44 45 /** 46 * Returns the unique least value of type {@code C} that is greater than 47 * {@code value}, or {@code null} if none exists. Inverse operation to {@link 48 * #previous}. 49 * 50 * @param value any value of type {@code C} 51 * @return the least value greater than {@code value}, or {@code null} if 52 * {@code value} is {@code maxValue()} 53 */ 54 public abstract C next(C value); 55 56 /** 57 * Returns the unique greatest value of type {@code C} that is less than 58 * {@code value}, or {@code null} if none exists. Inverse operation to {@link 59 * #next}. 60 * 61 * @param value any value of type {@code C} 62 * @return the greatest value less than {@code value}, or {@code null} if 63 * {@code value} is {@code minValue()} 64 */ 65 public abstract C previous(C value); 66 67 /** 68 * Returns a signed value indicating how many nested invocations of {@link 69 * #next} (if positive) or {@link #previous} (if negative) are needed to reach 70 * {@code end} starting from {@code start}. For example, if {@code end = 71 * next(next(next(start)))}, then {@code distance(start, end) == 3} and {@code 72 * distance(end, start) == -3}. As well, {@code distance(a, a)} is always 73 * zero. 74 * 75 * <p>Note that this function is necessarily well-defined for any discrete 76 * type. 77 * 78 * @return the distance as described above, or {@link Long#MIN_VALUE} or 79 * {@link Long#MIN_VALUE} if the distance is too small or too large, 80 * respectively. 81 */ 82 public abstract long distance(C start, C end); 83 84 /** 85 * Returns the minimum value of type {@code C}, if it has one. The minimum 86 * value is the unique value for which {@link Comparable#compareTo(Object)} 87 * never returns a positive value for any input of type {@code C}. 88 * 89 * <p>The default implementation throws {@code NoSuchElementException}. 90 * 91 * @return the minimum value of type {@code C}; never null 92 * @throws NoSuchElementException if the type has no (practical) minimum 93 * value; for example, {@link java.math.BigInteger} 94 */ 95 public C minValue() { 96 throw new NoSuchElementException(); 97 } 98 99 /** 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 } 114
