visad
Class Unit

java.lang.Object
  extended by visad.Unit
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
BaseUnit, DerivedUnit, OffsetUnit, PromiscuousUnit, ScaledUnit

public abstract class Unit
extends java.lang.Object
implements java.io.Serializable

A class that represents a unit of a quantity.

See Also:
Serialized Form

Constructor Summary
protected Unit()
          Constructs from nothing.
protected Unit(java.lang.String identifier)
          Constructs from an identifier.
 
Method Summary
protected  java.lang.String adjustCheckAndCache(java.lang.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(java.lang.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.
static float[][] convertTuple(float[][] value, Unit[] units_in, Unit[] units_out)
          Converts a tuple of float value arrays.
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.
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  java.lang.String getDefinition()
          Returns the definition of this unit.
 java.lang.String getIdentifier()
          Returns the identifier (name or abbreviation) of this unit.
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 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(java.lang.String identifier)
          Clones this unit, changing the identifier.
abstract  Unit root(int root)
          Returns the N-th root of this unit.
 Unit scale(double amount)
          Scale this unit by an amount.
 Unit shift(double offset)
          Shift this unit by an amount.
 Unit sqrt()
          Returns the square-root of this unit.
 java.lang.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 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.
abstract  double[] toThis(double[] values, Unit that)
          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.
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 float[] transformUnits(Unit unit_out, ErrorEstimate[] errors_out, Unit unit_in, ErrorEstimate error_in, float[] value)
          Transform float values and (optionally) error estimates.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Unit

protected Unit()
Constructs from nothing.


Unit

protected Unit(java.lang.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.

This implementation uses {@link #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 ith 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:
The converted values in a new array. 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.

This implementation uses {@link #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 ith 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:
The converted values in a new array. 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 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:
java.lang.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:
java.lang.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 java.lang.String adjustCheckAndCache(java.lang.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(java.lang.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(java.lang.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() 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.
Throws:
UnitException - It's meaningless to raise this unit by a power.

root

public abstract Unit root(int root)
                   throws java.lang.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.
Throws:
UnitException - It's meaningless to raise this unit by a power.
java.lang.IllegalArgumentException - The root value is zero or the resulting unit would have a non-integral unit dimension.

sqrt

public Unit sqrt()
          throws java.lang.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.
Throws:
java.lang.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,
                         java.lang.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.
java.lang.IllegalArgumentException - This unit is not dimensionless and power has a non-integral value.

scale

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

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.
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.
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.
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.
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.
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.
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.
Throws:
UnitException - The units are not convertible.

toString

public final java.lang.String toString()
Returns a string representation of this unit.

Overrides:
toString in class java.lang.Object
Returns:
The string representation of this unit. Won't be null but may be empty.

getIdentifier

public final java.lang.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 java.lang.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.