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

java.lang.Object
  extended by 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."

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


Copyright © 2010-2011. All Rights Reserved.