com.google.common.collect
Class DiscreteDomain<C extends Comparable>

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

@GwtCompatible
@Beta
public abstract class DiscreteDomain<C extends Comparable>
extends Object

A descriptor for a discrete Comparable domain such as all Integers. 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

Author:

Kevin Bourrillion

See Also:

DiscreteDomains

Constructor Summary

protected

DiscreteDomain() Constructor for use by subclasses.

Method Summary

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

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:

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:

NoSuchElementException - if the type has no (practical) maximum value; for example, BigInteger