| /* |
| * 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 <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 {@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 {@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 {@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. */ |
| protected DiscreteDomain() { |
| this(false); |
| } |
| |
| /** 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 {@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 {@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 {@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 {@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 {@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 {@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(); |
| } |
| } |