DiscreteDomain
Date: 2016-05-24

com.google.common.collect

## Class DiscreteDomain<C extends java.lang.Comparable>

- java.lang.Object
- - com.google.common.collect.DiscreteDomain<C>

-     @GwtCompatible
      @Beta
      public abstract class DiscreteDomain<C extends java.lang.Comparable>
      extends java.lang.Object

  A descriptor for a discrete `Comparable` domain such as all `Integer` instances. A discrete domain is one that supports the three basic operations: `next(C)`, `previous(C)` and `distance(C, C)`, 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`.

  Since:
    10.0

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `DiscreteDomain()` Constructor for use by subclasses.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static DiscreteDomain<java.math.BigInteger>` | `bigIntegers()` Returns the discrete domain for values of type `BigInteger`.
    `abstract long` | `distance(C start, C end)` Returns a signed value indicating how many nested invocations of `next(C)` (if positive) or `previous(C)` (if negative) are needed to reach `end` starting from `start`.
    `static DiscreteDomain<java.lang.Integer>` | `integers()` Returns the discrete domain for values of type `Integer`.
    `static DiscreteDomain<java.lang.Long>` | `longs()` Returns the discrete domain for values of type `Long`.
    `C` | `maxValue()` Returns the maximum value of type `C`, if it has one.
    `C` | `minValue()` Returns the minimum value of type `C`, if it has one.
    `abstract C` | `next(C value)` Returns the unique least value of type `C` that is greater than `value`, or `null` if none exists.
    `abstract C` | `previous(C value)` Returns the unique greatest value of type `C` that is less than `value`, or `null` if none exists.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DiscreteDomain

          protected DiscreteDomain()

      Constructor for use by subclasses.

  - ### Method Detail

    - #### integers

          public static DiscreteDomain<java.lang.Integer> integers()

      Returns the discrete domain for values of type `Integer`.
      Since:
        14.0 (since 10.0 as `DiscreteDomains.integers()`)

    - #### longs

          public static DiscreteDomain<java.lang.Long> longs()

      Returns the discrete domain for values of type `Long`.
      Since:
        14.0 (since 10.0 as `DiscreteDomains.longs()`)

    - #### bigIntegers

          public static DiscreteDomain<java.math.BigInteger> bigIntegers()

      Returns the discrete domain for values of type `BigInteger`.
      Since:
        15.0

    - #### next

          public abstract C next(C value)

      Returns the unique least value of type `C` that is greater than `value`, or `null` if none exists. Inverse operation to `previous(C)`.
      Parameters:
        `value` - any value of type `C`
      Returns:
        the least value greater than `value`, or `null` if `value` is `maxValue()`

    - #### previous

          public abstract C previous(C value)

      Returns the unique greatest value of type `C` that is less than `value`, or `null` if none exists. Inverse operation to `next(C)`.
      Parameters:
        `value` - any value of type `C`
      Returns:
        the greatest value less than `value`, or `null` if `value` is `minValue()`

    - #### distance

          public abstract long distance(C start,
                      C end)

      Returns a signed value indicating how many nested invocations of `next(C)` (if positive) or `previous(C)` (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.

    - #### minValue

          public C minValue()

      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`.

      Returns:
        the minimum value of type `C`; never null
      Throws:
        `java.util.NoSuchElementException` - if the type has no (practical) minimum value; for example, `BigInteger`

    - #### maxValue

          public C maxValue()

      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`.

      Returns:
        the maximum value of type `C`; never null
      Throws:
        `java.util.NoSuchElementException` - if the type has no (practical) maximum value; for example, `BigInteger`