org.jscience.physics.units
Class Unit<Q extends Quantity>

java.lang.Object
  org.jscience.physics.units.Unit<Q>

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

BaseUnit, DerivedUnit

public abstract class Unit<Q extends Quantity>
extends java.lang.Object
implements java.io.Serializable

This class represents a unit of physical quantity.

It is helpful to think of instances of this class as recording the history by which they are created. Thus, for example, the string "g/kg" (which is a dimensionless unit) would result from invoking the method toString() on a unit that was created by dividing a gram unit by a kilogram unit. Yet, "kg" divided by "kg" returns ONE and not "kg/kg" due to automatic unit factorization.

This class supports the multiplication of offsets units. The result is usually a unit not convertible to its system unit. Such units may appear in derivative quantities. For example °C/m is a unit of gradient, which is common in atmospheric and oceanographic research.

Units raised at rational powers are also supported. For example the cubic root of "liter" is a unit compatible with meter.

Instances of this class (and sub-classes) are immutable and unique.

Version:

2.0, October 19, 2005

Author:

Jean-Marie Dautelle, Steve Emmerson, Martin Desruisseaux

See Also:

Serialized Form

Field Summary

static Unit<Dimensionless>

ONE Holds the dimensionless unit ONE.

Method Summary

Unit<Q>	alias(java.lang.String alias) Attaches a system-wide alias to this unit.
<T extends Q> org.jscience.physics.units.AlternateUnit<T>	alternate(java.lang.String symbol) Returns a unit compatible to this unit except it uses the specified symbol.
CompoundUnit<Q>	compound(Unit<Q> subunit) Returns the combination of this unit with the specified sub-unit.
<Q extends Quantity> Unit<Q>	divide(Unit that) Returns the quotient of this unit with the one specified.
boolean	equals(java.lang.Object that) Indicates if this unit is equal to the object specified.
protected abstract boolean	equalsImpl(java.lang.Object that) Indicates if the specified unit can be considered equals to the one specified (for unicity purpose).
Unit<? super Q>	getBaseUnits() Returns the base unit or product of base units this unit is derived from.
Converter	getConverterTo(Unit that) Returns a converter of numeric values from this unit to another unit.
Dimension	getDimension() Returns the local dimension of this unit.
protected static <Q extends Quantity> Unit<Q>	getInstance(Unit<Q> template) This method returns an Unit from the collection identified by the specified template; if such units does not exists the specified template is added to the unit collection and returned.
static java.util.Set<Unit>	getInstances() Returns a read-only/thread safe set of the currently-defined units.
Unit<? super Q>	getParentUnit() Returns the unit this unit is derived from.
protected abstract Unit<? super Q>	getParentUnitImpl() Returns the parent units this unit is derived from.
int	hashCode() Returns the hash code value for this unit.
protected abstract int	hashCodeImpl() Returns the hash code for this unit (calculated only once as units are unique).
<Q extends Quantity> Unit<Q>	inverse() Returns the inverse of this unit.
boolean	isCompatible(Unit that) Indicates if this unit is compatible with the unit specified.
Unit<Q>	label(java.lang.String label) Attaches a system-wide label to the specified unit.
Unit<Q>	plus(double offset) Returns the result of adding an offset to this unit.
<Q extends Quantity> Unit<Q>	pow(int n) Returns a unit equals to this unit raised to an exponent.
protected java.lang.Object	readResolve() Overrides readResolve() to ensure that deserialization maintains unit's unicity.
<Q extends Quantity> Unit<Q>	root(int n) Returns a unit equals to the given root of this unit.
Unit<Q>	times(double scale) Returns the result of multiplying this unit by a scale factor.
<Q extends Quantity> Unit<Q>	times(Unit that) Returns the product of this unit with the one specified.
Converter	toBaseUnits() Returns the converter from this unit to its base units.
Converter	toParentUnit() Returns the converter from this unit to its parent unit.
protected abstract Converter	toParentUnitImpl() Returns the converter to the parent unit.
java.lang.String	toString() Returns the standard String representation of this unit.
Text	toText() Returns the textual representation of this unit.
Unit<Q>	transform(Converter operation) Returns the unit derived from this unit using the specified converter.
static Unit	valueOf(java.lang.CharSequence csq) Returns a unit instance that is defined from the specified character sequence.

Methods inherited from class java.lang.Object

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

Field Detail

ONE

public static final Unit<Dimensionless> ONE

Holds the dimensionless unit ONE.

Method Detail

hashCodeImpl

protected abstract int hashCodeImpl()

Returns the hash code for this unit (calculated only once as units are unique).

Returns:

this unit hashcode value.

equalsImpl

protected abstract boolean equalsImpl(java.lang.Object that)

Indicates if the specified unit can be considered equals to the one specified (for unicity purpose).

Returns:

true if this unit is considered equal to that unit; false otherwise.

getParentUnitImpl

protected abstract Unit<? super Q> getParentUnitImpl()

Returns the parent units this unit is derived from.

Returns:

the parent unit or this if this unit is a base unit or a product of base units.

toParentUnitImpl

protected abstract Converter toParentUnitImpl()

Returns the converter to the parent unit.

Returns:

the converter to getParentUnitImpl()

getParentUnit

public final Unit<? super Q> getParentUnit()

Returns the unit this unit is derived from.

Note: Having the same parent unit is not sufficient to ensure that a converter exists between the two units (e.g. °C/m and K/m).

Returns:

the parent unit or this if this unit is a base unit or a product of base units.

toParentUnit

public final Converter toParentUnit()

Returns the converter from this unit to its parent unit.

Returns:

this.getConverterTo(this.getParentUnit())

getBaseUnits

public final Unit<? super Q> getBaseUnits()

Returns the base unit or product of base units this unit is derived from.

Note: Having the same base units is not sufficient to ensure that a converter exists between the two units (e.g. °C/m and K/m).

Returns:

the base units this unit is derived from.

toBaseUnits

public final Converter toBaseUnits()

Returns the converter from this unit to its base units.

Returns:

this.getConverterTo(this.getBaseUnits())

isCompatible

public final boolean isCompatible(Unit that)

Indicates if this unit is compatible with the unit specified. Units don't need to be equals to be compatible. For example:

     RADIAN.equals(ONE) == false
     RADIAN.isCompatible(ONE) == true.
 

Parameters:

that - the other unit.

Returns:

this.getDimension() == that.getDimension()

getDimension

public final Dimension getDimension()

Returns the local dimension of this unit.

Returns:

this unit dimension.

See Also:

BaseUnit.setDimension(org.jscience.physics.units.Dimension, org.jscience.physics.units.Converter)

getConverterTo

public final Converter getConverterTo(Unit that)
                               throws ConversionException

Returns a converter of numeric values from this unit to another unit.

Parameters:

that - the unit to which to convert the numeric values.

Returns:

the converter from this unit to that unit.

Throws:

ConversionException - if the conveter cannot be constructed (e.g. !this.isCompatible(that)).

alternate

public final <T extends Q> org.jscience.physics.units.AlternateUnit<T> alternate(java.lang.String symbol)

Returns a unit compatible to this unit except it uses the specified symbol. The alternate unit can itself be used to form expressions and symbols for other derived units. For example:

   Unit<Angle> RADIAN = Unit.ONE.alternate("rad");
   Unit<Force> NEWTON = METER.multiply(KILOGRAM).divide(SECOND.pow(2)).alternate("N");
   Unit<Pressure> PASCAL = NEWTON.divide(METER.pow(2)).alternate("Pa");
 

Any unit having the specified symbol as label loses its label (symbols and labels cannot conflict).

Parameters:

symbol - the unique symbol for the alternate unit.

Returns:

AlternateUnit.getInstance(symbol, this)

Throws:

java.lang.IllegalArgumentException - if the specified symbol is currently a symbol associated to a different unit.

compound

public final CompoundUnit<Q> compound(Unit<Q> subunit)

Returns the combination of this unit with the specified sub-unit. Compound units are typically used for formatting purpose. Examples of compound units:

   HOUR_MINUTE = NonSI.HOUR.compound(NonSI.MINUTE);
   DEGREE_MINUTE_SECOND_ANGLE = NonSI.DEGREE_ANGLE.compound(
       NonSI.DEGREE_MINUTE).compound(NonSI.SECOND_ANGLE);

Parameters:

subunit - the sub-unit to combine with this unit.

Returns:

CompoundUnit.getInstance(this, subUnit)

transform

public final Unit<Q> transform(Converter operation)

Returns the unit derived from this unit using the specified converter. The converter does not need to be linear. For example:

 Unit>Dimensionless> DECIBEL = Unit.ONE.transform(
     new LogConverter(10).inverse().concatenate(
           new MultiplyConverter(0.1))).label("dB");

Parameters:

operation - the converter from the transformed unit to this unit.

Returns:

the unit after the specified transformation.

plus

public final Unit<Q> plus(double offset)

Returns the result of adding an offset to this unit. The returned unit is convertible with all units that are convertible with this unit.

Parameters:

offset - the offset added (expressed in this unit, e.g. CELSIUS = KELVIN.plus(273.15)).

Returns:

this.transform(new AddConverter(offset))

times

public final Unit<Q> times(double scale)

Returns the result of multiplying this unit by a scale factor. The returned unit is convertible with all units that are convertible with this unit.

Parameters:

scale - the scale factor (e.g. KILOMETER = METER.multiply(1000)).

Returns:

this.transform(new MultiplyConverter(scale))

times

public final <Q extends Quantity> Unit<Q> times(Unit that)

Returns the product of this unit with the one specified.

Parameters:

that - the unit multiplicand.

Returns:

this * that

inverse

public final <Q extends Quantity> Unit<Q> inverse()

Returns the inverse of this unit.

Returns:

1 / this

divide

public final <Q extends Quantity> Unit<Q> divide(Unit that)

Returns the quotient of this unit with the one specified.

Parameters:

that - the unit divisor.

Returns:

this / that

root

public final <Q extends Quantity> Unit<Q> root(int n)

Returns a unit equals to the given root of this unit.

Parameters:

n - the root's order.

Returns:

the result of taking the given root of this unit.

Throws:

java.lang.ArithmeticException - if n == 0.

pow

public final <Q extends Quantity> Unit<Q> pow(int n)

Returns a unit equals to this unit raised to an exponent.

Parameters:

n - the exponent.

Returns:

the result of raising this unit to the exponent.

label

public Unit<Q> label(java.lang.String label)

Attaches a system-wide label to the specified unit. This method removes any previous label association of the specified label as units may only have one label (but multiple aliases). For example:

     DAY.multiply(365).label("year");
     Unit FOOT = METER.multiply(0.3048).label("ft");
 

Parameters:

label - the new label for this unit or null to detache the previous label (if any).

Returns:

this unit.

Throws:

java.lang.IllegalArgumentException - if the specified label is a known symbol (base unit or alternate unit).

alias

public Unit<Q> alias(java.lang.String alias)

Attaches a system-wide alias to this unit. Multiple aliases may be attached to the same unit. Aliases are used during parsing to recognize different variants of the same unit. For example:

     METER.multiply(0.3048).alias("foot");
     METER.multiply(0.3048).alias("feet");
     METER.alias("meter");
     METER.alias("metre");
 

Parameters:

alias - the alias being attached to this unit.

Returns:

this unit.

Throws:

java.lang.IllegalArgumentException - if the specified alias is a known symbol (base unit / alternate unit) or a currently associated label.

valueOf

public static Unit valueOf(java.lang.CharSequence csq)

Returns a unit instance that is defined from the specified character sequence. If the specified character sequence is a combination of units (e.g. ProductUnit), then the corresponding unit is created if not already defined.

Examples of valid entries (all for meters per second squared) are:

• m*s-2
• m/s²
• m·s-²
• m*s**-2
• m^+1 s^-2
• m¹·s^-2

Parameters:

csq - the character sequence to parse.

Returns:

UnitFormat.current().parse(csq)

Throws:

java.lang.IllegalArgumentException - if the specified character sequence cannot be correctly parsed (e.g. symbol unknown).

See Also:

UnitFormat.current()

getInstances

public static java.util.Set<Unit> getInstances()

Returns a read-only/thread safe set of the currently-defined units. The collection returned is backed by the actual collection of units -- so it grows as more units are defined.

Returns:

an unmodifiable view of the units collection.

toText

public Text toText()

Returns the textual representation of this unit.

Returns:

the text representation of this unit using the current format.

See Also:

UnitFormat

toString

public final java.lang.String toString()

Returns the standard String representation of this unit.

Overrides:

toString in class java.lang.Object

Returns:

toText().toString();

getInstance

protected static <Q extends Quantity> Unit<Q> getInstance(Unit<Q> template)

This method returns an Unit from the collection identified by the specified template; if such units does not exists the specified template is added to the unit collection and returned.

Parameters:

template - the unit template for comparison.

Returns:

a unit from the collection equals to the specified template; or the template itself.

Throws:

java.lang.IllegalArgumentException - if the template uses an intrinsic symbol already taken by a different unit.

See Also:

equalsImpl(Object)

equals

public final boolean equals(java.lang.Object that)

Indicates if this unit is equal to the object specified. Units are unique and immutable, therefore users might want to use == to test for equality.

Overrides:

equals in class java.lang.Object

Parameters:

that - the object to compare for equality.

Returns:

this == that

hashCode

public final int hashCode()

Returns the hash code value for this unit.

Overrides:

hashCode in class java.lang.Object

Returns:

the unit hash code.

readResolve

protected java.lang.Object readResolve()

Overrides readResolve() to ensure that deserialization maintains unit's unicity.

Returns:

a new unit or an existing unit.