visad
Class Unit

java.lang.Object
  visad.Unit

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

BaseUnit, DerivedUnit, LogarithmicUnit, OffsetUnit, PromiscuousUnit, ScaledUnit

public abstract class Unit
extends Object
implements Serializable

A class that represents a unit of a quantity. Instances are immutable.

Author:

Steven R. Emmerson This is part of Steve Emmerson's Unit package that has been incorporated into VisAD.

See Also:

Serialized Form

Field Summary

protected int

hashCode

Constructor Summary

protected	Unit() Constructs from nothing.
protected	Unit(String identifier) Constructs from an identifier.

Method Summary

protected String	adjustCheckAndCache(String identifier) Adjusts, checks, and caches a unit identifier and its unit.
static boolean	canConvert(Unit unita, Unit unitb) Indicates if values in two units are convertible.
static boolean	canConvertArray(Unit[] unita, Unit[] unitb) Indicates whether or not two unit arrays are convertible.
Unit	clone(String identifier) Clones this unit, changing the identifier.
static double[][]	convertTuple(double[][] value, Unit[] units_in, Unit[] units_out) Converts a tuple of double value arrays; returning a new tuple.
static double[][]	convertTuple(double[][] value, Unit[] units_in, Unit[] units_out, boolean copy) Converts a tuple of double value arrays, optionally returning a new tuple depending on the value of copy.
static float[][]	convertTuple(float[][] value, Unit[] units_in, Unit[] units_out) Converts a tuple of float value arrays; returning a new tuple.
static float[][]	convertTuple(float[][] value, Unit[] units_in, Unit[] units_out, boolean copy) Converts a tuple of float value arrays, optionally returning a new tuple depending on the value of copy.
static Unit[]	copyUnitsArray(Unit[] units) Copys an array of units.
abstract Unit	divide(Unit that) Divide this unit by another unit.
protected abstract Unit	divideInto(Unit that) Divide this unit into another unit.
boolean	equals(Object that) Indicates whether or not this instance is equal to an object.
abstract boolean	equals(Unit unit) Indicates whether or not this instance is equal to a unit.
Unit	getAbsoluteUnit() Gets the absolute unit of this unit.
abstract String	getDefinition() Returns the definition of this unit.
abstract DerivedUnit	getDerivedUnit() Returns the derived unit that underlies this unit.
String	getIdentifier() Returns the identifier (name or abbreviation) of this unit.
abstract int	hashCode() Abstract method for computing hashcode
abstract boolean	isConvertible(Unit unit) Indicate whether this unit is convertible with another unit.
abstract boolean	isDimensionless() Indicates if this instance is dimensionless.
abstract Unit	log(double base) Returns the logarithmic unit that has this unit as its reference level.
static void	main(String[] args) Test this class.
abstract Unit	multiply(Unit that) Multiply this unit by another unit.
abstract Unit	pow(double power) Raise a unit to a power.
abstract Unit	pow(int power) Raise this unit to a power.
protected abstract Unit	protectedClone(String identifier) Clones this unit, changing the identifier.
abstract Unit	root(int root) Returns the N-th root of this unit.
abstract Unit	scale(double amount) Scale this unit by an amount.
abstract Unit	shift(double offset) Shift this unit by an amount.
Unit	sqrt() Returns the square-root of this unit.
String	toString() Returns a string representation of this unit.
abstract double[]	toThat(double[] values, Unit that) Convert values from this unit to another unit.
double[]	toThat(double[] values, Unit that, boolean copy) Convert values from this unit to another unit.
double	toThat(double value, Unit that) Convert a value from this unit to another unit.
abstract float[]	toThat(float[] values, Unit that) Convert values from this unit to another unit.
float[]	toThat(float[] values, Unit that, boolean copy) Convert values from this unit to another unit.
abstract double[]	toThis(double[] values, Unit that) Convert values to this unit from another unit.
double[]	toThis(double[] values, Unit that, boolean copy) Convert values to this unit from another unit.
double	toThis(double value, Unit that) Convert a value to this unit from another unit.
abstract float[]	toThis(float[] values, Unit that) Convert values to this unit from another unit.
float[]	toThis(float[] values, Unit that, boolean copy) Convert values to this unit from another unit.
static double[]	transformUnits(Unit unit_out, ErrorEstimate[] errors_out, Unit unit_in, ErrorEstimate error_in, double[] value) Transform double values and (optionally) error estimates.
static double[]	transformUnits(Unit unit_out, ErrorEstimate[] errors_out, Unit unit_in, ErrorEstimate error_in, double[] value, boolean copy) Transform double values and (optionally) error estimates.
static float[]	transformUnits(Unit unit_out, ErrorEstimate[] errors_out, Unit unit_in, ErrorEstimate error_in, float[] value) Transform float values and (optionally) error estimates.
static float[]	transformUnits(Unit unit_out, ErrorEstimate[] errors_out, Unit unit_in, ErrorEstimate error_in, float[] value, boolean copy) Transform float values and (optionally) error estimates.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

hashCode

protected transient int hashCode

Constructor Detail

Unit

protected Unit()

Constructs from nothing.

Unit

protected Unit(String identifier)

Constructs from an identifier.

Parameters:

identifier - Name or abbreviation for the unit. May be null or empty.

Method Detail

convertTuple

public static double[][] convertTuple(double[][] value,
                                      Unit[] units_in,
                                      Unit[] units_out)
                               throws UnitException,
                                      VisADException

Converts a tuple of double value arrays; returning a new tuple.

This implementation uses toThis(double[], Unit) to convert the individual arrays.

Parameters:

value - The tuple of numeric value arrays to convert. value[i][j] is the value of the i th component of sample-point j .

units_in - The units of the input numeric values. units_in[i] is the unit of the ith conponent.

units_out - The units of the output numeric values. units_out[i] is the unit for the ith conponent.

Returns:

Returns the converted values in a new array where RETURN_VALUE [i][j] is the converted value of value[i][j].

Throws:

UnitException - If an ouput unit is null and the corresponding input unit is neither null nor a PromiscuousUnit, or if an input unit is not convertible with its corresponding output unit.

VisADException - if a VisAD failure occurs.

convertTuple

public static double[][] convertTuple(double[][] value,
                                      Unit[] units_in,
                                      Unit[] units_out,
                                      boolean copy)
                               throws UnitException,
                                      VisADException

Converts a tuple of double value arrays, optionally returning a new tuple depending on the value of copy.

This implementation uses toThis(double[], Unit) to convert the individual arrays.

Parameters:

value - The tuple of numeric value arrays to convert. value[i][j] is the value of the i th component of sample-point j .

units_in - The units of the input numeric values. units_in[i] is the unit of the ith conponent.

units_out - The units of the output numeric values. units_out[i] is the unit for the ith conponent.

copy - If true, a new array is created, otherwise if a unit in units_in equals the unit at the corresponding index in the units_out, the input value array at that index is returned instead of a new array.

Returns:

If units_in equals units_out copy is false, then this just returns the value argument. Otherwise, returns the the converted values in a new array where RETURN_VALUE [i][j] is the converted value of value[i][j].

Throws:

UnitException - If an ouput unit is null and the corresponding input unit is neither null nor a PromiscuousUnit, or if an input unit is not convertible with its corresponding output unit.

VisADException - if a VisAD failure occurs.

convertTuple

public static float[][] convertTuple(float[][] value,
                                     Unit[] units_in,
                                     Unit[] units_out)
                              throws UnitException,
                                     VisADException

Converts a tuple of float value arrays; returning a new tuple.

This implementation uses toThis(float[], Unit) to convert the individual arrays.

Parameters:

value - The tuple of numeric value arrays to convert. value[i][j] is the value of the i th component of sample-point j .

units_in - The units of the input numeric values. units_in[i] is the unit of the ith conponent.

units_out - The units of the output numeric values. units_out[i] is the unit for the ith conponent.

Returns:

Returns the converted values in a new array where RETURN_VALUE [i][j] is the converted value of value[i][j].

Throws:

UnitException - If an ouput unit is null and the corresponding input unit is neither null nor a PromiscuousUnit, or if an input unit is not convertible with its corresponding output unit.

VisADException - if a VisAD failure occurs.

convertTuple

public static float[][] convertTuple(float[][] value,
                                     Unit[] units_in,
                                     Unit[] units_out,
                                     boolean copy)
                              throws UnitException,
                                     VisADException

Converts a tuple of float value arrays, optionally returning a new tuple depending on the value of copy.

This implementation uses toThis(float[], Unit) to convert the individual arrays.

Parameters:

value - The tuple of numeric value arrays to convert. value[i][j] is the value of the i th component of sample-point j .

units_in - The units of the input numeric values. units_in[i] is the unit of the ith conponent.

units_out - The units of the output numeric values. units_out[i] is the unit for the ith conponent.

copy - If true, a new array is created, otherwise if a unit in units_in equals the unit at the corresponding index in the units_out, the input value array at that index is returned instead of a new array.

Returns:

If units_in equals units_out copy is false, then this just returns the value argument. Otherwise, returns the the converted values in a new array where RETURN_VALUE [i][j] is the converted value of value[i][j].

Throws:

UnitException - If an ouput unit is null and the corresponding input unit is neither null nor a PromiscuousUnit, or if an input unit is not convertible with its corresponding output unit.

VisADException - if a VisAD failure occurs.

canConvert

public static boolean canConvert(Unit unita,
                                 Unit unitb)

Indicates if values in two units are convertible. The values of two units are convertible if each unit is either null or the promiscuous unit, or if one unit is neither null nor the promiscuous unit and the other unit is either the promiscuous unit or a convertible unit.

Parameters:

unita - One unit.

unitb - The other unit.

Returns:

true if and only if values in the the two units are convertible.

See Also:

isConvertible(Unit)

isConvertible

public abstract boolean isConvertible(Unit unit)

Indicate whether this unit is convertible with another unit. If one unit is convertible with another, then the toThis(...)/ and toThat(...) methods will not throw a UnitException. Unit A is convertible with unit B if and only if unit B is convertible with unit A; hence, calling-order is irrelevant.

Parameters:

unit - The other unit.

Returns:

True if and only if this unit is convertible with the other unit.

canConvertArray

public static boolean canConvertArray(Unit[] unita,
                                      Unit[] unitb)

Indicates whether or not two unit arrays are convertible. Two such arrays are convertible if and only if the units of their corresponding elements are convertible.

This implementation uses canConvert(Unit, Unit) to determine convertibility of the element pairs.

Parameters:

unita - One array of units. May be null.

unitb - The other array of units. May be null.

Returns:

true if and only if both unit arrays are null or the two unit arrays are element-by-element convertible.

copyUnitsArray

public static Unit[] copyUnitsArray(Unit[] units)

Copys an array of units. This is a helper method for Set, RealTupleType, CoordinateSystem, etc.

Parameters:

units - The array of units or null.

Returns:

A copy of the array of units or null. if the input array is null.

equals

public boolean equals(Object that)

Indicates whether or not this instance is equal to an object.

Overrides:

equals in class Object

Parameters:

that - The object in question.

Returns:

true if and only if this instance equals the unit.

hashCode

public abstract int hashCode()

Abstract method for computing hashcode

Overrides:

hashCode in class Object

equals

public abstract boolean equals(Unit unit)

Indicates whether or not this instance is equal to a unit.

Parameters:

unit - The unit.

Returns:

true if and only if this instance equals the unit.

transformUnits

public static double[] transformUnits(Unit unit_out,
                                      ErrorEstimate[] errors_out,
                                      Unit unit_in,
                                      ErrorEstimate error_in,
                                      double[] value)
                               throws UnitException,
                                      VisADException

Transform double values and (optionally) error estimates.

Parameters:

unit_out - The unit of the output numeric values or null.

errors_out - The output error estimate. errors_out[0] will contain the output error estimate, which may be null.

unit_in - The unit of the input numeric values.

error_in - The input error estimate or null.

value - The input numeric value.

Returns:

The corresponding, transformed numeric values in the same array only if the input and output units were null; otherwise, a new array is returned.

Throws:

NullPointerException - if errors_out is null .

UnitException - if the input and output unit aren't convertible.

VisADException - if a VisAD failure occurs.

transformUnits

public static float[] transformUnits(Unit unit_out,
                                     ErrorEstimate[] errors_out,
                                     Unit unit_in,
                                     ErrorEstimate error_in,
                                     float[] value)
                              throws UnitException,
                                     VisADException

Transform float values and (optionally) error estimates.

Parameters:

unit_out - The unit of the output numeric values or null.

errors_out - The output error estimate. errors_out[0] will contain the output error estimate, which may be null.

unit_in - The unit of the input numeric values.

error_in - The input error estimate or null.

value - The input numeric value.

Returns:

The corresponding, transformed numeric values in the same array only if the input and output units were null; otherwise, a new array is returned.

Throws:

NullPointerException - if errors_out is null .

UnitException - if the input and output unit aren't convertible.

VisADException - if a VisAD failure occurs.

transformUnits

public static double[] transformUnits(Unit unit_out,
                                      ErrorEstimate[] errors_out,
                                      Unit unit_in,
                                      ErrorEstimate error_in,
                                      double[] value,
                                      boolean copy)
                               throws UnitException,
                                      VisADException

Transform double values and (optionally) error estimates.

Parameters:

unit_out - The unit of the output numeric values or null.

errors_out - The output error estimate. errors_out[0] will contain the output error estimate, which may be null.

unit_in - The unit of the input numeric values.

error_in - The input error estimate or null.

value - The input numeric value.

copy - if false and unit_out equals unit_in , transform values in place.

Returns:

The corresponding, transformed numeric values in the same array only if the input and output units were null; otherwise, a new array is returned.

Throws:

NullPointerException - if errors_out is null .

UnitException - if the input and output unit aren't convertible.

VisADException - if a VisAD failure occurs.

transformUnits

public static float[] transformUnits(Unit unit_out,
                                     ErrorEstimate[] errors_out,
                                     Unit unit_in,
                                     ErrorEstimate error_in,
                                     float[] value,
                                     boolean copy)
                              throws UnitException,
                                     VisADException

Transform float values and (optionally) error estimates.

Parameters:

unit_out - The unit of the output numeric values or null.

errors_out - The output error estimate. errors_out[0] will contain the output error estimate, which may be null.

unit_in - The unit of the input numeric values.

error_in - The input error estimate or null.

value - The input numeric value.

copy - if false and unit_out equals unit_in , transform values in place.

Returns:

The corresponding, transformed numeric values in the same array only if the input and output units were null; otherwise, a new array is returned.

Throws:

NullPointerException - if errors_out is null .

UnitException - if the input and output unit aren't convertible.

VisADException - if a VisAD failure occurs.

adjustCheckAndCache

protected final String adjustCheckAndCache(String identifier)
                                    throws UnitExistsException

Adjusts, checks, and caches a unit identifier and its unit.

Parameters:

identifier - Name or abbreviation for the unit. May be null or empty.

Returns:

The identifier adjusted as necessary in order to be valid (e.g. whitespace replacement).

Throws:

UnitExistsException - A different unit with the same, non-null and non-empty identifier already exists. The identifier and unit are not cached.

isDimensionless

public abstract boolean isDimensionless()

Indicates if this instance is dimensionless. A unit is dimensionless if it is a measure of a dimensionless quantity like angle or concentration. Examples of dimensionless units include radian, degree, steradian, and "g/kg".

Returns:

True if an only if this unit is dimensionless.

clone

public Unit clone(String identifier)
           throws UnitException

Clones this unit, changing the identifier.

This implementation uses the protectedClone(String) method.

Parameters:

identifier - The name or abbreviation for the cloned unit. May be null or empty.

Returns:

A unit equal to this instance but with the given identifier (adjusted if necessary).

Throws:

UnitException - The unit may not be cloned. This will only occur if getIdentifier()!=null.

See Also:

adjustCheckAndCache(String)

protectedClone

protected abstract Unit protectedClone(String identifier)
                                throws UnitException

Clones this unit, changing the identifier.

Parameters:

identifier - The name or abbreviation for the cloned unit. May be null or empty. It shall have already passed the adjustCheckAndCache(String) method.

Returns:

A unit equal to this instance but with the given identifier.

Throws:

UnitException - if the unit may not be cloned. This will only occur if getIdentifier()!=null.

pow

public abstract Unit pow(int power)
                  throws UnitException

Raise this unit to a power.

Parameters:

power - The power to raise this unit by.

Returns:

The resulting unit. require: The unit is not an offset unit. promise: The unit has not been modified.

Throws:

UnitException - It's meaningless to raise this unit by a power.

root

public abstract Unit root(int root)
                   throws IllegalArgumentException,
                          UnitException

Returns the N-th root of this unit.

Parameters:

root - The root to take (e.g. 2 means square root). Must not be zero.

Returns:

The unit corresponding to the root-th root of this unit. require: The unit is not an offset unit. promise: The unit has not been modified.

Throws:

UnitException - It's meaningless to raise this unit by a power.

IllegalArgumentException - The root value is zero or the resulting unit would have a non-integral unit dimension.

sqrt

public Unit sqrt()
          throws IllegalArgumentException,
                 UnitException

Returns the square-root of this unit. This method is identical to root(int root) with a value of 2.

Returns:

The unit corresponding to the square-root of this unit. promise: This unit has not been modified.

Throws:

IllegalArgumentException - The resulting unit would have a non-integral unit dimension.

UnitException - It is meaningless to take a root of this unit.

pow

public abstract Unit pow(double power)
                  throws UnitException,
                         IllegalArgumentException

Raise a unit to a power.

Parameters:

power - The power to raise this unit by. If this unit is not dimensionless, then the value must be integral.

Returns:

The unit resulting from raising this unit to power.

Throws:

UnitException - It's meaningless to raise this unit by a power.

IllegalArgumentException - This unit is not dimensionless and power has a non-integral value. promise: The unit has not been modified.

scale

public abstract Unit scale(double amount)
                    throws UnitException

Scale this unit by an amount.

Parameters:

amount - The amount by which to scale this unit. E.g. Unit yard = meter.scale(0.9144);

Returns:

A unit equal to this instance scaled by the given amount.

Throws:

UnitException - This unit cannot be scaled.

shift

public abstract Unit shift(double offset)
                    throws UnitException

Shift this unit by an amount.

Parameters:

offset - The amount by which to shift this unit. E.g. Unit celsius = kelvin.shift(273.15);

Returns:

A unit equal to this instance with the origin shifted by the given amount.

Throws:

UnitException - The unit subclass is unknown.

log

public abstract Unit log(double base)
                  throws UnitException

Returns the logarithmic unit that has this unit as its reference level. Not all units can be used as a reference level.

Parameters:

base - The logarithmic base: one of 2, Math.E, or 10.

Returns:

The logarithmic unit that has this instance as its reference level.

Throws:

IllegalArgumentException - if base isn't one of the allowed values.

UnitException - if this unit can't be used as a reference level for a logarithmic unit.

multiply

public abstract Unit multiply(Unit that)
                       throws UnitException

Multiply this unit by another unit.

Parameters:

that - The given unit to multiply this unit by.

Returns:

The resulting unit.

Throws:

UnitException - It's meaningless to multiply these units.

divide

public abstract Unit divide(Unit that)
                     throws UnitException

Divide this unit by another unit.

Parameters:

that - The unit to divide into this unit.

Returns:

The quotient of the two units. promise: Neither unit has been modified.

Throws:

UnitException - It's meaningless to divide these units.

divideInto

protected abstract Unit divideInto(Unit that)
                            throws UnitException

Divide this unit into another unit.

Parameters:

that - The unit to be divided by this unit.

Returns:

The quotient of the two units.

Throws:

UnitException - It's meaningless to divide these units.

toThis

public double toThis(double value,
                     Unit that)
              throws UnitException

Convert a value to this unit from another unit.

Parameters:

value - The value in units of the other unit.

that - The other unit.

Returns:

The value converted from the other unit to this unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toThis

public abstract double[] toThis(double[] values,
                                Unit that)
                         throws UnitException

Convert values to this unit from another unit.

Parameters:

values - Values in units of the other unit.

that - The other unit.

Returns:

Values in this unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toThis

public abstract float[] toThis(float[] values,
                               Unit that)
                        throws UnitException

Convert values to this unit from another unit.

Parameters:

values - Values in units of the other unit.

that - The other unit.

Returns:

Values in this unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toThis

public double[] toThis(double[] values,
                       Unit that,
                       boolean copy)
                throws UnitException

Convert values to this unit from another unit.

Parameters:

values - Values in units of the other unit.

that - The other unit.

copy - true to make a copy if units are not equal. Ignored in this class.

Returns:

Values in this unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toThis

public float[] toThis(float[] values,
                      Unit that,
                      boolean copy)
               throws UnitException

Convert values to this unit from another unit.

Parameters:

values - Values in units of the other unit.

that - The other unit.

copy - true to make a copy if units are not equal. Ignored in this class.

Returns:

Values in this unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toThat

public double toThat(double value,
                     Unit that)
              throws UnitException

Convert a value from this unit to another unit.

Parameters:

value - The value in this unit.

that - The other unit.

Returns:

The value in units of the other unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toThat

public abstract double[] toThat(double[] values,
                                Unit that)
                         throws UnitException

Convert values from this unit to another unit.

Parameters:

values - The values in this unit.

that - The other unit.

Returns:

Values converted to the other unit from this unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toThat

public abstract float[] toThat(float[] values,
                               Unit that)
                        throws UnitException

Convert values from this unit to another unit.

Parameters:

values - The values in this unit.

that - The other unit.

Returns:

Values converted to the other unit from this unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toThat

public double[] toThat(double[] values,
                       Unit that,
                       boolean copy)
                throws UnitException

Convert values from this unit to another unit.

Parameters:

values - The values in this unit.

that - The other unit.

copy - true to make a copy if units are not equal. Ignored in this class.

Returns:

Values converted to the other unit from this unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toThat

public float[] toThat(float[] values,
                      Unit that,
                      boolean copy)
               throws UnitException

Convert values from this unit to another unit.

Parameters:

values - The values in this unit.

that - The other unit.

copy - true to make a copy if units are not equal. Ignored in this class.

Returns:

Values converted to the other unit from this unit. require: The units are convertible. promise: Neither unit has been modified.

Throws:

UnitException - The units are not convertible.

toString

public final String toString()

Returns a string representation of this unit.

Overrides:

toString in class Object

Returns:

The string representation of this unit. Won't be null but may be empty.

getIdentifier

public final String getIdentifier()

Returns the identifier (name or abbreviation) of this unit.

Returns:

The identifier of this unit. May be null but won't be empty.

getDefinition

public abstract String getDefinition()

Returns the definition of this unit.

Returns:

The definition of this unit. Won't be null but may be empty.

getAbsoluteUnit

public Unit getAbsoluteUnit()

Gets the absolute unit of this unit. An interval in the underlying physical quantity has the same numeric value in an absolute unit of a unit as in the unit itself -- but an absolute unit is always referenced to the physical origin of the underlying physical quantity. For example, the absolute unit corresponding to degrees celsius is degrees kelvin -- and calling this method on a degrees celsius unit obtains a degrees kelvin unit.

Returns:

The absolute unit corresponding to this unit.

getDerivedUnit

public abstract DerivedUnit getDerivedUnit()

Returns the derived unit that underlies this unit.

Returns:

The derived unit that underlies this unit.

main

public static void main(String[] args)
                 throws UnitException

Test this class.

Parameters:

args - Arguments (ignored).

Throws:

UnitException - A problem occurred.