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
17package com.google.common.collect;
18
19import com.google.common.annotations.Beta;
20import com.google.common.annotations.GwtCompatible;
21
22import 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
41public 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