Unit (jscience 4.3.1 API)

java.lang.Object
- javax.measure.unit.Unit<Q>

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

BaseUnit, DerivedUnit
```
public abstract class Unit<Q extends Quantity>
extends Object
implements Serializable
```
This class represents a determinate quantity (as of length, time, heat, or value) adopted as a standard of measurement.

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 standard unit. Such units may appear in derivative quantities. For example °C/m is an 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 are immutable.

Version:

3.2, August 28, 2006

Author:

Jean-Marie Dautelle, Steve Emmerson, Martin Desruisseaux

See Also:
Wikipedia: Units of measurement, Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

static Unit<Dimensionless> ONE
Holds the dimensionless unit ONE.

Fields
Modifier and Type	Field and Description
`static Unit<Dimensionless>`	`ONE` Holds the dimensionless unit `ONE`.

Constructor Summary

Constructors
Modifier Constructor and Description

protected Unit()
Default constructor.

Constructors
Modifier	Constructor and Description
`protected`	`Unit()` Default constructor.

Method Summary

Methods
Modifier and Type	Method and Description
`<A extends Quantity> AlternateUnit<A>`	`alternate(String symbol)` Returns a unit equivalent to this unit but used in expressions to distinguish between quantities of a different nature but of the same dimensions.
`<T extends Quantity> Unit<T>`	`asType(Class<T> type)` Casts this unit to a parameterized unit of specified nature or throw a `ClassCastException` if the dimension of the specified quantity and this unit's dimension do not match.
`CompoundUnit<Q>`	`compound(Unit<Q> subunit)` Returns the combination of this unit with the specified sub-unit.
`Unit<Q>`	`divide(double divisor)` Returns the result of dividing this unit by an approximate divisor.
`Unit<Q>`	`divide(long divisor)` Returns the result of dividing this unit by an exact divisor.
`Unit<? extends Quantity>`	`divide(Unit<?> that)` Returns the quotient of this unit with the one specified.
`abstract boolean`	`equals(Object that)` Indicates if the specified unit can be considered equals to the one specified.
`UnitConverter`	`getConverterTo(Unit<?> that)` Returns a converter of numeric values from this unit to another unit.
`Dimension`	`getDimension()` Returns the dimension of this unit (depends upon the current dimensional `model`).
`abstract Unit<? super Q>`	`getStandardUnit()` Returns the `base unit`, `alternate unit` or product of base units and alternate units this unit is derived from.
`abstract int`	`hashCode()` Returns the hash code for this unit.
`Unit<? extends Quantity>`	`inverse()` Returns the inverse of this unit.
`boolean`	`isCompatible(Unit<?> that)` Indicates if this unit is compatible with the unit specified.
`boolean`	`isStandardUnit()` Indicates if this unit is a standard unit (base units and alternate units are standard units).
`Unit<Q>`	`plus(double offset)` Returns the result of adding an offset to this unit.
`Unit<? extends Quantity>`	`pow(int n)` Returns a unit equals to this unit raised to an exponent.
`Unit<? extends Quantity>`	`root(int n)` Returns a unit equals to the given root of this unit.
`Unit<Q>`	`times(double factor)` Returns the result of multiplying this unit by a an approximate factor
`Unit<Q>`	`times(long factor)` Returns the result of multiplying this unit by an exact factor.
`Unit<? extends Quantity>`	`times(Unit<?> that)` Returns the product of this unit with the one specified.
`abstract UnitConverter`	`toStandardUnit()` Returns the converter from this unit to its system unit.
`String`	`toString()` Returns the standard `String` representation of this unit.
`Unit<Q>`	`transform(UnitConverter operation)` Returns the unit derived from this unit using the specified converter.
`static Unit<? extends Quantity>`	`valueOf(CharSequence csq)` Returns a unit instance that is defined from the specified character sequence using the `standard unit format`.

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.
- Constructor Detail
  - Unit
```
protected Unit()
```
    Default constructor.
- Method Detail
  - getStandardUnit
```
public abstract Unit<? super Q> getStandardUnit()
```
    Returns the base unit, alternate unit or product of base units and alternate units this unit is derived from. The standard unit identifies the "type" of quantity for which this unit is employed. For example:[code] boolean isAngularVelocity(Unit u) { return u.getStandardUnit().equals(RADIAN.divide(SECOND)); } assert(REVOLUTION.divide(MINUTE).isAngularVelocity()); [/code]
    Note: Having the same system unit is not sufficient to ensure that a converter exists between the two units (e.g. °C/m and K/m).
    
    Returns:
    the system unit this unit is derived from.
  - toStandardUnit
```
public abstract UnitConverter toStandardUnit()
```
    Returns the converter from this unit to its system unit.
    
    Returns:
    this.getConverterTo(this.getSystemUnit())
  - hashCode
```
public abstract int hashCode()
```
    Returns the hash code for this unit.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    this unit hashcode value.
  - equals
```
public abstract boolean equals(Object that)
```
    Indicates if the specified unit can be considered equals to the one specified.
    
    Overrides:
    
    equals in class Object
    
    Parameters:
    that - the object to compare to.
    
    Returns:
    true if this unit is considered equal to that unit; false otherwise.
  - isStandardUnit
```
public boolean isStandardUnit()
```
    Indicates if this unit is a standard unit (base units and alternate units are standard units). The standard unit identifies the "type" of quantity for which the unit is employed.
    
    Returns:
    getStandardUnit().equals(this)
  - 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:[code] RADIAN.equals(ONE) == false RADIAN.isCompatible(ONE) == true [/code]
    
    Parameters:
    that - the other unit.
    
    Returns:
    this.getDimension().equals(that.getDimension())
    See Also:
    getDimension()
  - asType
```
public final <T extends Quantity> Unit<T> asType(Class<T> type)
                                      throws ClassCastException
```
    Casts this unit to a parameterized unit of specified nature or throw a ClassCastException if the dimension of the specified quantity and this unit's dimension do not match. For example:[code] Unit LIGHT_YEAR = NonSI.C.times(NonSI.YEAR).asType(Length.class); [/code]
    
    Parameters:
    type - the quantity class identifying the nature of the unit.
    
    Returns:
    this unit parameterized with the specified type.
    
    Throws:
    
    ClassCastException - if the dimension of this unit is different from the specified quantity dimension.
    
    UnsupportedOperationException - if the specified quantity class does not have a public static field named "UNIT" holding the standard unit for the quantity.
  - getDimension
```
public final Dimension getDimension()
```
    Returns the dimension of this unit (depends upon the current dimensional model).
    
    Returns:
    the dimension of this unit for the current model.
  - getConverterTo
```
public final UnitConverter 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 <A extends Quantity> AlternateUnit<A> alternate(String symbol)
```
    Returns a unit equivalent to this unit but used in expressions to distinguish between quantities of a different nature but of the same dimensions.
    Examples of alternate units:[code] Unit RADIAN = ONE.alternate("rad"); Unit NEWTON = METER.times(KILOGRAM).divide(SECOND.pow(2)).alternate("N"); Unit PASCAL = NEWTON.divide(METER.pow(2)).alternate("Pa"); [/code]
    
    Parameters:
    symbol - the new symbol for the alternate unit.
    
    Returns:
    the alternate unit.
    
    Throws:
    
    UnsupportedOperationException - if this unit is not a standard unit.
    
    IllegalArgumentException - if the specified symbol is already 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:[code] HOUR_MINUTE = NonSI.HOUR.compound(NonSI.MINUTE); DEGREE_MINUTE_SECOND_ANGLE = NonSI.DEGREE_ANGLE.compound( NonSI.DEGREE_MINUTE).compound(NonSI.SECOND_ANGLE); [/code]
    
    Parameters:
    subunit - the sub-unit to combine with this unit.
    
    Returns:
    the corresponding compound unit.
  - transform
```
public final Unit<Q> transform(UnitConverter operation)
```
    Returns the unit derived from this unit using the specified converter. The converter does not need to be linear. For example:[code] Unit DECIBEL = Unit.ONE.transform( new LogConverter(10).inverse().concatenate( new RationalConverter(1, 10)));[/code]
    
    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(long factor)
```
    Returns the result of multiplying this unit by an exact factor.
    
    Parameters:
    factor - the exact scale factor (e.g. KILOMETER = METER.times(1000)).
    
    Returns:
    this.transform(new RationalConverter(factor, 1))
  - times
```
public final Unit<Q> times(double factor)
```
    Returns the result of multiplying this unit by a an approximate factor
    
    Parameters:
    factor - the approximate factor (e.g. ELECTRON_MASS = KILOGRAM.times(9.10938188e-31)).
    
    Returns:
    this.transform(new MultiplyConverter(factor))
  - times
```
public final Unit<? extends Quantity> times(Unit<?> that)
```
    Returns the product of this unit with the one specified.
    
    Parameters:
    that - the unit multiplicand.
    
    Returns:
    this * that
  - inverse
```
public final Unit<? extends Quantity> inverse()
```
    Returns the inverse of this unit.
    
    Returns:
    1 / this
  - divide
```
public final Unit<Q> divide(long divisor)
```
    Returns the result of dividing this unit by an exact divisor.
    
    Parameters:
    divisor - the exact divisor. (e.g. QUART = GALLON_LIQUID_US.divide(4)).
    
    Returns:
    this.transform(new RationalConverter(1 , divisor))
  - divide
```
public final Unit<Q> divide(double divisor)
```
    Returns the result of dividing this unit by an approximate divisor.
    
    Parameters:
    divisor - the approximate divisor.
    
    Returns:
    this.transform(new MultiplyConverter(1.0 / divisor))
  - divide
```
public final Unit<? extends Quantity> divide(Unit<?> that)
```
    Returns the quotient of this unit with the one specified.
    
    Parameters:
    that - the unit divisor.
    
    Returns:
    this / that
  - root
```
public final Unit<? extends Quantity> 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:
    
    ArithmeticException - if n == 0.
  - pow
```
public final Unit<? extends Quantity> 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.
  - valueOf
```
public static Unit<? extends Quantity> valueOf(CharSequence csq)
```
    Returns a unit instance that is defined from the specified character sequence using the standard unit format.
    Examples of valid entries (all for meters per second squared) are:
    Parameters:
    csq - the character sequence to parse.
    
    Returns:
    UnitFormat.getStandardInstance().parse(csq, new ParsePosition(0))
    
    Throws:
    
    IllegalArgumentException - if the specified character sequence cannot be correctly parsed (e.g. symbol unknown).
  - toString
```
public final String toString()
```
    Returns the standard String representation of this unit. This representation is not affected by locale. Locale-sensitive unit formatting and parsing is handled by the MeasureFormat class and its subclasses.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    UnitFormat.getStandardInstance().format(this)

Class Unit<Q extends Quantity>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ONE

Constructor Detail

Unit

Method Detail

getStandardUnit

toStandardUnit

hashCode

equals

isStandardUnit

isCompatible

asType

getDimension

getConverterTo

alternate

compound

transform

plus

times

times

times

inverse

divide

divide

divide

root

pow

valueOf

toString