/*
 * Copyright (C) 2009 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.collect;

import static com.google.common.base.Preconditions.checkArgument;
import static com.google.common.collect.CollectPreconditions.checkNonnegative;

import com.google.common.annotations.GwtCompatible;
import com.google.common.primitives.Ints;
import com.google.errorprone.annotations.CanIgnoreReturnValue;
import java.io.Serializable;
import java.math.BigInteger;
import java.util.NoSuchElementException;

A descriptor for a discrete Comparable domain such as all Integer instances. A discrete domain is one that supports the three basic operations: next, previous and distance, according to their specifications. The methods minValue and maxValue should also be overridden for bounded types.

A discrete domain always represents the entire set of values of its type; it cannot represent partial domains such as "prime integers" or "strings of length 5."

See the Guava User Guide section on DiscreteDomain.

Author:Kevin Bourrillion
Since:10.0
/** * A descriptor for a <i>discrete</i> {@code Comparable} domain such as all {@link Integer} * instances. A discrete domain is one that supports the three basic operations: {@link #next}, * {@link #previous} and {@link #distance}, according to their specifications. The methods {@link * #minValue} and {@link #maxValue} should also be overridden for bounded types. * * <p>A discrete domain always represents the <i>entire</i> set of values of its type; it cannot * represent partial domains such as "prime integers" or "strings of length 5." * * <p>See the Guava User Guide section on <a href= * "https://github.com/google/guava/wiki/RangesExplained#discrete-domains"> {@code * DiscreteDomain}</a>. * * @author Kevin Bourrillion * @since 10.0 */
@GwtCompatible public abstract class DiscreteDomain<C extends Comparable> {
Returns the discrete domain for values of type Integer.
Since:14.0 (since 10.0 as DiscreteDomains.integers())
/** * Returns the discrete domain for values of type {@code Integer}. * * @since 14.0 (since 10.0 as {@code DiscreteDomains.integers()}) */
public static DiscreteDomain<Integer> integers() { return IntegerDomain.INSTANCE; } private static final class IntegerDomain extends DiscreteDomain<Integer> implements Serializable { private static final IntegerDomain INSTANCE = new IntegerDomain(); IntegerDomain() { super(true); } @Override public Integer next(Integer value) { int i = value; return (i == Integer.MAX_VALUE) ? null : i + 1; } @Override public Integer previous(Integer value) { int i = value; return (i == Integer.MIN_VALUE) ? null : i - 1; } @Override Integer offset(Integer origin, long distance) { checkNonnegative(distance, "distance"); return Ints.checkedCast(origin.longValue() + distance); } @Override public long distance(Integer start, Integer end) { return (long) end - start; } @Override public Integer minValue() { return Integer.MIN_VALUE; } @Override public Integer maxValue() { return Integer.MAX_VALUE; } private Object readResolve() { return INSTANCE; } @Override public String toString() { return "DiscreteDomain.integers()"; } private static final long serialVersionUID = 0; }
Returns the discrete domain for values of type Long.
Since:14.0 (since 10.0 as DiscreteDomains.longs())
/** * Returns the discrete domain for values of type {@code Long}. * * @since 14.0 (since 10.0 as {@code DiscreteDomains.longs()}) */
public static DiscreteDomain<Long> longs() { return LongDomain.INSTANCE; } private static final class LongDomain extends DiscreteDomain<Long> implements Serializable { private static final LongDomain INSTANCE = new LongDomain(); LongDomain() { super(true); } @Override public Long next(Long value) { long l = value; return (l == Long.MAX_VALUE) ? null : l + 1; } @Override public Long previous(Long value) { long l = value; return (l == Long.MIN_VALUE) ? null : l - 1; } @Override Long offset(Long origin, long distance) { checkNonnegative(distance, "distance"); long result = origin + distance; if (result < 0) { checkArgument(origin < 0, "overflow"); } return result; } @Override public long distance(Long start, Long end) { long result = end - start; if (end > start && result < 0) { // overflow return Long.MAX_VALUE; } if (end < start && result > 0) { // underflow return Long.MIN_VALUE; } return result; } @Override public Long minValue() { return Long.MIN_VALUE; } @Override public Long maxValue() { return Long.MAX_VALUE; } private Object readResolve() { return INSTANCE; } @Override public String toString() { return "DiscreteDomain.longs()"; } private static final long serialVersionUID = 0; }
Returns the discrete domain for values of type BigInteger.
Since:15.0
/** * Returns the discrete domain for values of type {@code BigInteger}. * * @since 15.0 */
public static DiscreteDomain<BigInteger> bigIntegers() { return BigIntegerDomain.INSTANCE; } private static final class BigIntegerDomain extends DiscreteDomain<BigInteger> implements Serializable { private static final BigIntegerDomain INSTANCE = new BigIntegerDomain(); BigIntegerDomain() { super(true); } private static final BigInteger MIN_LONG = BigInteger.valueOf(Long.MIN_VALUE); private static final BigInteger MAX_LONG = BigInteger.valueOf(Long.MAX_VALUE); @Override public BigInteger next(BigInteger value) { return value.add(BigInteger.ONE); } @Override public BigInteger previous(BigInteger value) { return value.subtract(BigInteger.ONE); } @Override BigInteger offset(BigInteger origin, long distance) { checkNonnegative(distance, "distance"); return origin.add(BigInteger.valueOf(distance)); } @Override public long distance(BigInteger start, BigInteger end) { return end.subtract(start).max(MIN_LONG).min(MAX_LONG).longValue(); } private Object readResolve() { return INSTANCE; } @Override public String toString() { return "DiscreteDomain.bigIntegers()"; } private static final long serialVersionUID = 0; } final boolean supportsFastOffset;
Constructor for use by subclasses.
/** Constructor for use by subclasses. */
protected DiscreteDomain() { this(false); }
Private constructor for built-in DiscreteDomains supporting fast offset.
/** Private constructor for built-in DiscreteDomains supporting fast offset. */
private DiscreteDomain(boolean supportsFastOffset) { this.supportsFastOffset = supportsFastOffset; }
Returns, conceptually, "origin + distance", or equivalently, the result of calling next on origin distance times.
/** * Returns, conceptually, "origin + distance", or equivalently, the result of calling {@link * #next} on {@code origin} {@code distance} times. */
C offset(C origin, long distance) { checkNonnegative(distance, "distance"); for (long i = 0; i < distance; i++) { origin = next(origin); } return origin; }
Returns the unique least value of type C that is greater than value, or null if none exists. Inverse operation to previous.
Params:
  • value – any value of type C
Returns:the least value greater than value, or null if value is maxValue()
/** * Returns the unique least value of type {@code C} that is greater than {@code value}, or {@code * null} if none exists. Inverse operation to {@link #previous}. * * @param value any value of type {@code C} * @return the least value greater than {@code value}, or {@code null} if {@code value} is {@code * maxValue()} */
public abstract C next(C value);
Returns the unique greatest value of type C that is less than value, or null if none exists. Inverse operation to next.
Params:
  • value – any value of type C
Returns:the greatest value less than value, or null if value is minValue()
/** * Returns the unique greatest value of type {@code C} that is less than {@code value}, or {@code * null} if none exists. Inverse operation to {@link #next}. * * @param value any value of type {@code C} * @return the greatest value less than {@code value}, or {@code null} if {@code value} is {@code * minValue()} */
public abstract C previous(C value);
Returns a signed value indicating how many nested invocations of next (if positive) or previous (if negative) are needed to reach end starting from start. For example, if end = next(next(next(start))), then distance(start, end) == 3 and distance(end, start) == -3. As well, distance(a, a) is always zero.

Note that this function is necessarily well-defined for any discrete type.

Returns:the distance as described above, or Long.MIN_VALUE or Long.MAX_VALUE if the distance is too small or too large, respectively.
/** * Returns a signed value indicating how many nested invocations of {@link #next} (if positive) or * {@link #previous} (if negative) are needed to reach {@code end} starting from {@code start}. * For example, if {@code end = next(next(next(start)))}, then {@code distance(start, end) == 3} * and {@code distance(end, start) == -3}. As well, {@code distance(a, a)} is always zero. * * <p>Note that this function is necessarily well-defined for any discrete type. * * @return the distance as described above, or {@link Long#MIN_VALUE} or {@link Long#MAX_VALUE} if * the distance is too small or too large, respectively. */
public abstract long distance(C start, C end);
Returns the minimum value of type C, if it has one. The minimum value is the unique value for which Comparable.compareTo(Object) never returns a positive value for any input of type C.

The default implementation throws NoSuchElementException.

Throws:
Returns:the minimum value of type C; never null
/** * Returns the minimum value of type {@code C}, if it has one. The minimum value is the unique * value for which {@link Comparable#compareTo(Object)} never returns a positive value for any * input of type {@code C}. * * <p>The default implementation throws {@code NoSuchElementException}. * * @return the minimum value of type {@code C}; never null * @throws NoSuchElementException if the type has no (practical) minimum value; for example, * {@link java.math.BigInteger} */
@CanIgnoreReturnValue public C minValue() { throw new NoSuchElementException(); }
Returns the maximum value of type C, if it has one. The maximum value is the unique value for which Comparable.compareTo(Object) never returns a negative value for any input of type C.

The default implementation throws NoSuchElementException.

Throws:
Returns:the maximum value of type C; never null
/** * Returns the maximum value of type {@code C}, if it has one. The maximum value is the unique * value for which {@link Comparable#compareTo(Object)} never returns a negative value for any * input of type {@code C}. * * <p>The default implementation throws {@code NoSuchElementException}. * * @return the maximum value of type {@code C}; never null * @throws NoSuchElementException if the type has no (practical) maximum value; for example, * {@link java.math.BigInteger} */
@CanIgnoreReturnValue public C maxValue() { throw new NoSuchElementException(); } }