net.tribe7.common.collect

Class DiscreteDomain<C extends java.lang.Comparable>

java.lang.Object

net.tribe7.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
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())

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