net.innig.collect
Interface Radix

All Superinterfaces:

java.util.Comparator

All Known Implementing Classes:

IntegralRadix, StringRadix

public interface Radix
extends java.util.Comparator

Extracts a radix representation -- a sequence of digits -- from objects. Radix representations allow certain sorting and lookup algorithms which are more efficient in large cases than those which are possible with comparison alone.

Maturity: All the radix utilities in innig-util are completely experimental. They mostly work, but perform poorly. They may stay; they may improve; they may go away.

Plans: Experiment.

See Also:

InnigCollections.radixSort(List,Radix), RadixMap

Method Summary

int	digit(java.lang.Object o, int position) Returns the digits of the radix representation of the given object.
int	getBase() Returns the base (the number of digit values) in this radix.
int	getMaxPosition(java.lang.Object o) Returns the position of the most significant digit for this radix.
int	getMaxPositionForAll(java.util.Collection values) Returns the hightest position of the most significant digit of any of the values in the collection.
int	getMinPosition(java.lang.Object o) Returns the position of the most significant digit for this radix.
int	getMinPositionForAll(java.util.Collection values) Returns the lowest position of the least significant digit of any of the values in the collection.
java.lang.Object	objectFromDigits(int[] digits) Constructs an object from the given digits (optional operation).
java.lang.Object	objectFromDigits(int[] digits, int offset, int len) Constructs an object from the given digits (optional operation).

Methods inherited from interface java.util.Comparator

compare, equals

Method Detail

getBase

int getBase()

Returns the base (the number of digit values) in this radix. For the decimal radix we're familiar with, for example, the base is 10.

digit

int digit(java.lang.Object o,
          int position)

Returns the digits of the radix representation of the given object. Lower positions are less significant digits.

Parameters:

o - An object from which this radix can extract digits.

position - A digit position within o.

Returns:

a digit d, with -1 <= x < getBase(). A variable-length radix uses the digit -1 signifies that the position is beyond the end of the object's representation.

Throws:

java.lang.ClassCastException - if this radix doesn't handle the given object.

getMaxPosition

int getMaxPosition(java.lang.Object o)

Returns the position of the most significant digit for this radix. Can be negative.

Throws:

java.lang.ClassCastException - if this radix doesn't handle the object

getMinPosition

int getMinPosition(java.lang.Object o)

Returns the position of the most significant digit for this radix. Can be negative.

Throws:

java.lang.ClassCastException - if this radix doesn't handle the object

getMaxPositionForAll

int getMaxPositionForAll(java.util.Collection values)

Returns the hightest position of the most significant digit of any of the values in the collection. If the radix is not variable-length, this method needn't scan the collection. Can be negative.

Throws:

java.lang.ClassCastException - if this radix doesn't handle an object in the collection. This exception is not guaranteed to be thrown if the list contains an unhandled object, since some implementations may not actually scan the values.

getMinPositionForAll

int getMinPositionForAll(java.util.Collection values)

Returns the lowest position of the least significant digit of any of the values in the collection. If the radix is not variable-length, this method needn't scan the collection. Can be negative.

Throws:

java.lang.ClassCastException - if this radix doesn't handle an object in the collection. This exception is not guaranteed to be thrown if the list contains an unhandled object, since some implementations may not actually scan the values.

objectFromDigits

java.lang.Object objectFromDigits(int[] digits)

Constructs an object from the given digits (optional operation). This operation inverts @{#digit(Object,int)}. Element 0 of the array corresponds to the digit in the position given by getMaxPosition(Object).

Throws:

java.lang.UnsupportedOperationException - if this radix doesn't support this method.

java.lang.IllegalArgumentException - if any of the digits exceed the base, any digits are negative, the number of digits is too large, or the digits don't represent a valid object.

objectFromDigits

java.lang.Object objectFromDigits(int[] digits,
                                  int offset,
                                  int len)

Constructs an object from the given digits (optional operation). This operation inverts @{#digit(Object,int)}. The element of the array at the given offset corresponds to the digit in the position given by getMaxPosition(Object).

Throws:

java.lang.UnsupportedOperationException - if this radix doesn't support this method.

java.lang.IllegalArgumentException - if any of the digits exceed the base, any digits are negative, the number of digits is too large, or the digits don't represent a valid object.