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
017package com.google.common.collect;
018
019import com.google.common.annotations.GwtCompatible;
020import com.google.errorprone.annotations.CanIgnoreReturnValue;
021import java.io.Serializable;
022import java.math.BigInteger;
023import java.util.NoSuchElementException;
024
025/**
026 * A descriptor for a <i>discrete</i> {@code Comparable} domain such as all
027 * {@link Integer} instances. A discrete domain is one that supports the three basic
028 * operations: {@link #next}, {@link #previous} and {@link #distance}, according
029 * to their specifications. The methods {@link #minValue} and {@link #maxValue}
030 * should also be overridden for bounded types.
031 *
032 * <p>A discrete domain always represents the <i>entire</i> set of values of its
033 * type; it cannot represent partial domains such as "prime integers" or
034 * "strings of length 5."
035 *
036 * <p>See the Guava User Guide section on <a href=
037 * "https://github.com/google/guava/wiki/RangesExplained#discrete-domains">
038 * {@code DiscreteDomain}</a>.
039 *
040 * @author Kevin Bourrillion
041 * @since 10.0
042 */
043@GwtCompatible
044public abstract class DiscreteDomain<C extends Comparable> {
045
046  /**
047   * Returns the discrete domain for values of type {@code Integer}.
048   *
049   * @since 14.0 (since 10.0 as {@code DiscreteDomains.integers()})
050   */
051  public static DiscreteDomain<Integer> integers() {
052    return IntegerDomain.INSTANCE;
053  }
054
055  private static final class IntegerDomain extends DiscreteDomain<Integer> implements Serializable {
056    private static final IntegerDomain INSTANCE = new IntegerDomain();
057
058    @Override
059    public Integer next(Integer value) {
060      int i = value;
061      return (i == Integer.MAX_VALUE) ? null : i + 1;
062    }
063
064    @Override
065    public Integer previous(Integer value) {
066      int i = value;
067      return (i == Integer.MIN_VALUE) ? null : i - 1;
068    }
069
070    @Override
071    public long distance(Integer start, Integer end) {
072      return (long) end - start;
073    }
074
075    @Override
076    public Integer minValue() {
077      return Integer.MIN_VALUE;
078    }
079
080    @Override
081    public Integer maxValue() {
082      return Integer.MAX_VALUE;
083    }
084
085    private Object readResolve() {
086      return INSTANCE;
087    }
088
089    @Override
090    public String toString() {
091      return "DiscreteDomain.integers()";
092    }
093
094    private static final long serialVersionUID = 0;
095  }
096
097  /**
098   * Returns the discrete domain for values of type {@code Long}.
099   *
100   * @since 14.0 (since 10.0 as {@code DiscreteDomains.longs()})
101   */
102  public static DiscreteDomain<Long> longs() {
103    return LongDomain.INSTANCE;
104  }
105
106  private static final class LongDomain extends DiscreteDomain<Long> implements Serializable {
107    private static final LongDomain INSTANCE = new LongDomain();
108
109    @Override
110    public Long next(Long value) {
111      long l = value;
112      return (l == Long.MAX_VALUE) ? null : l + 1;
113    }
114
115    @Override
116    public Long previous(Long value) {
117      long l = value;
118      return (l == Long.MIN_VALUE) ? null : l - 1;
119    }
120
121    @Override
122    public long distance(Long start, Long end) {
123      long result = end - start;
124      if (end > start && result < 0) { // overflow
125        return Long.MAX_VALUE;
126      }
127      if (end < start && result > 0) { // underflow
128        return Long.MIN_VALUE;
129      }
130      return result;
131    }
132
133    @Override
134    public Long minValue() {
135      return Long.MIN_VALUE;
136    }
137
138    @Override
139    public Long maxValue() {
140      return Long.MAX_VALUE;
141    }
142
143    private Object readResolve() {
144      return INSTANCE;
145    }
146
147    @Override
148    public String toString() {
149      return "DiscreteDomain.longs()";
150    }
151
152    private static final long serialVersionUID = 0;
153  }
154
155  /**
156   * Returns the discrete domain for values of type {@code BigInteger}.
157   *
158   * @since 15.0
159   */
160  public static DiscreteDomain<BigInteger> bigIntegers() {
161    return BigIntegerDomain.INSTANCE;
162  }
163
164  private static final class BigIntegerDomain extends DiscreteDomain<BigInteger>
165      implements Serializable {
166    private static final BigIntegerDomain INSTANCE = new BigIntegerDomain();
167
168    private static final BigInteger MIN_LONG = BigInteger.valueOf(Long.MIN_VALUE);
169    private static final BigInteger MAX_LONG = BigInteger.valueOf(Long.MAX_VALUE);
170
171    @Override
172    public BigInteger next(BigInteger value) {
173      return value.add(BigInteger.ONE);
174    }
175
176    @Override
177    public BigInteger previous(BigInteger value) {
178      return value.subtract(BigInteger.ONE);
179    }
180
181    @Override
182    public long distance(BigInteger start, BigInteger end) {
183      return end.subtract(start).max(MIN_LONG).min(MAX_LONG).longValue();
184    }
185
186    private Object readResolve() {
187      return INSTANCE;
188    }
189
190    @Override
191    public String toString() {
192      return "DiscreteDomain.bigIntegers()";
193    }
194
195    private static final long serialVersionUID = 0;
196  }
197
198  /** Constructor for use by subclasses. */
199  protected DiscreteDomain() {}
200
201  /**
202   * Returns the unique least value of type {@code C} that is greater than
203   * {@code value}, or {@code null} if none exists. Inverse operation to {@link
204   * #previous}.
205   *
206   * @param value any value of type {@code C}
207   * @return the least value greater than {@code value}, or {@code null} if
208   *     {@code value} is {@code maxValue()}
209   */
210  public abstract C next(C value);
211
212  /**
213   * Returns the unique greatest value of type {@code C} that is less than
214   * {@code value}, or {@code null} if none exists. Inverse operation to {@link
215   * #next}.
216   *
217   * @param value any value of type {@code C}
218   * @return the greatest value less than {@code value}, or {@code null} if
219   *     {@code value} is {@code minValue()}
220   */
221  public abstract C previous(C value);
222
223  /**
224   * Returns a signed value indicating how many nested invocations of {@link
225   * #next} (if positive) or {@link #previous} (if negative) are needed to reach
226   * {@code end} starting from {@code start}. For example, if {@code end =
227   * next(next(next(start)))}, then {@code distance(start, end) == 3} and {@code
228   * distance(end, start) == -3}. As well, {@code distance(a, a)} is always
229   * zero.
230   *
231   * <p>Note that this function is necessarily well-defined for any discrete
232   * type.
233   *
234   * @return the distance as described above, or {@link Long#MIN_VALUE} or
235   *     {@link Long#MAX_VALUE} if the distance is too small or too large,
236   *     respectively.
237   */
238  public abstract long distance(C start, C end);
239
240  /**
241   * Returns the minimum value of type {@code C}, if it has one. The minimum
242   * value is the unique value for which {@link Comparable#compareTo(Object)}
243   * never returns a positive value for any input of type {@code C}.
244   *
245   * <p>The default implementation throws {@code NoSuchElementException}.
246   *
247   * @return the minimum value of type {@code C}; never null
248   * @throws NoSuchElementException if the type has no (practical) minimum
249   *     value; for example, {@link java.math.BigInteger}
250   */
251  @CanIgnoreReturnValue
252  public C minValue() {
253    throw new NoSuchElementException();
254  }
255
256  /**
257   * Returns the maximum value of type {@code C}, if it has one. The maximum
258   * value is the unique value for which {@link Comparable#compareTo(Object)}
259   * never returns a negative value for any input of type {@code C}.
260   *
261   * <p>The default implementation throws {@code NoSuchElementException}.
262   *
263   * @return the maximum value of type {@code C}; never null
264   * @throws NoSuchElementException if the type has no (practical) maximum
265   *     value; for example, {@link java.math.BigInteger}
266   */
267  @CanIgnoreReturnValue
268  public C maxValue() {
269    throw new NoSuchElementException();
270  }
271}