Unit (Units of Measurement API 0.7 API)

Type Parameters:
Q - The type of the quantity measured by this unit.
```
public interface Unit<Q extends Quantity<Q>>
```
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.

This interface 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 Celsius per meter is an unit of gradient, which is common in atmospheric and oceanographic research.

Units raised at non-integral powers are not supported. For example, LITRE.root(2) raises an ArithmeticException, but HECTARE.root(2) returns HECTOMETRE (100 metres).

Unit instances shall be immutable.

Version:

0.16, December 8, 2014

Author:

Jean-Marie Dautelle, Steve Emmerson, Martin Desruisseaux, Werner Keil

See Also:
Wikipedia: Units of measurement

Method Summary

Methods
Modifier and Type	Method and Description
`Unit<Q>`	`alternate(String symbol)` Returns a system unit equivalent to this unscaled standard unit but used in expressions to distinguish between quantities of a different nature but of the same dimensions.
`<T extends Quantity<T>> 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.
`Unit<Q>`	`divide(double divisor)` Returns the result of dividing this unit by an approximate divisor.
`Unit<?>`	`divide(Unit<?> divisor)` Returns the quotient of this unit with the one specified.
`UnitConverter`	`getConverterTo(Unit<Q> that)` Returns a converter of numeric values from this unit to another unit of same type.
`UnitConverter`	`getConverterToAny(Unit<?> that)` Returns a converter from this unit to the specified unit of type unknown.
`Dimension`	`getDimension()` Returns the dimension of this unit.
`String`	`getName()` Returns the name (if any) of this unit.
`Map<? extends Unit<?>,Integer>`	`getProductUnits()` Returns the base units and their exponent whose product is this unit, or `null` if this unit is a base unit (not a product of existing units).
`String`	`getSymbol()` Returns the symbol (if any) of this unit.
`Unit<Q>`	`getSystemUnit()` Returns the unscaled system unit from which this unit is derived.
`Unit<?>`	`inverse()` Returns the inverse of this unit.
`boolean`	`isCompatible(Unit<?> that)` Indicates if this unit is compatible with the unit specified.
`Unit<Q>`	`multiply(double multiplier)` Returns the result of multiplying this unit by the specified factor.
`Unit<?>`	`multiply(Unit<?> multiplier)` Returns the product of this unit with the one specified.
`Unit<?>`	`pow(int n)` Returns a unit equals to this unit raised to an exponent.
`Unit<?>`	`root(int n)` Returns a unit equals to the given root of this unit.
`Unit<Q>`	`shift(double offset)` Returns the result of setting the origin of the scale of measurement to the given value.
`String`	`toString()` Returns a string representation of this unit.
`Unit<Q>`	`transform(UnitConverter converter)` Returns the unit derived from this unit using the specified converter.

- Method Detail
  - getSymbol
```
String getSymbol()
```
    Returns the symbol (if any) of this unit. This method returns null if this unit has no specific symbol associated with.
    
    Returns:
    this unit symbol, or null if this unit has not specific symbol associated with (e.g. product of units).
    See Also:
    toString(), UnitFormat
  - getName
```
String getName()
```
    Returns the name (if any) of this unit. This method returns null if this unit has no specific name associated with.
    
    Returns:
    this unit name, or null if this unit has not specific name associated with (e.g. product of units).
    See Also:
    toString(), UnitFormat
  - getDimension
```
Dimension getDimension()
```
    Returns the dimension of this unit. Two units u1 and u2 are compatible if and only if u1.getDimension().equals(u2.getDimension()).
    
    Returns:
    the dimension of this unit.
    See Also:
    isCompatible(Unit)
  - getSystemUnit
```
Unit<Q> getSystemUnit()
```
    Returns the unscaled system unit from which this unit is derived. System units are either base units, alternate units or product of rational powers of system units.
    Because the system unit is unique by quantity type, it can be be used to identify the quantity given the unit. For example:
    [code] static boolean isAngularSpeed(Unit unit) { return unit.getSystemUnit().equals(RADIAN.divide(SECOND)); } assert isAngularSpeed(REVOLUTION.divide(MINUTE)); // Returns true. [/code]
    
    Returns:
    the system unit this unit is derived from, or this if this unit is a system unit.
  - getProductUnits
```
Map<? extends Unit<?>,Integer> getProductUnits()
```
    Returns the base units and their exponent whose product is this unit, or null if this unit is a base unit (not a product of existing units).
    
    Returns:
    the base units and their exponent making up this unit.
  - isCompatible
```
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 (assuming ONE is a dimensionless unit): [code] RADIAN.equals(ONE) == false RADIAN.isCompatible(ONE) == true [/code]
    
    Parameters:
    that - the other unit to compare for compatibility.
    
    Returns:
    this.getDimension().equals(that.getDimension())
    See Also:
    getDimension()
  - asType
```
<T extends Quantity<T>> 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 C = METRE.times(299792458).divide(SECOND).asType(Speed.class); [/code]
    
    Type Parameters:
    T - The type of the quantity measured by the unit.
    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.
  - getConverterTo
```
UnitConverter getConverterTo(Unit<Q> that)
                             throws UnconvertibleException
```
    Returns a converter of numeric values from this unit to another unit of same type. This method performs the same work than getConverterToAny(Unit) without raising checked exception.
    
    Parameters:
    that - the unit of same type to which to convert the numeric values.
    
    Returns:
    the converter from this unit to that unit.
    
    Throws:
    
    UnconvertibleException - if a converter cannot be constructed.
    See Also:
    getConverterToAny(Unit)
  - getConverterToAny
```
UnitConverter getConverterToAny(Unit<?> that)
                                throws IncommensurableException,
                                       UnconvertibleException
```
    Returns a converter from this unit to the specified unit of type unknown. This method can be used when the quantity type of the specified unit is unknown at compile-time or when dimensional analysis allows for conversion between units of different type.
    To convert to a unit having the same parameterized type, getConverterTo(Unit) is preferred (no checked exception raised).
    
    Parameters:
    that - the unit to which to convert the numeric values.
    
    Returns:
    the converter from this unit to that unit.
    
    Throws:
    
    IncommensurableException - if this unit is not compatible with that unit.
    
    UnconvertibleException - if a converter cannot be constructed.
    See Also:
    getConverterTo(Unit), isCompatible(Unit)
  - alternate
```
Unit<Q> alternate(String symbol)
```
    Returns a system unit equivalent to this unscaled standard 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").asType(Angle.class); Unit NEWTON = METRE.times(KILOGRAM).divide(SECOND.pow(2)).alternate("N").asType(Force.class); Unit PASCAL = NEWTON.divide(METRE.pow(2)).alternate("Pa").asType(Pressure.class); [/code]
    
    Parameters:
    symbol - the new symbol for the alternate unit.
    
    Returns:
    the alternate unit.
    
    Throws:
    
    UnsupportedOperationException - if this unit is not an unscaled standard unit.
    
    IllegalArgumentException - if the specified symbol is already associated to a different unit.
  - shift
```
Unit<Q> shift(double offset)
```
    Returns the result of setting the origin of the scale of measurement to the given value. The returned unit is convertible with all units that are convertible with this unit. For example the following code: [code] CELSIUS = KELVIN.shift(273.15); [/code] creates a new unit where 0°C (the origin of the new unit) is equals to 273.15 K. Converting from the old unit to the new one is equivalent to subtracting the offset to the value in the old unit.
    
    Parameters:
    offset - the offset added (expressed in this unit).
    
    Returns:
    this unit offset by the specified value.
  - multiply
```
Unit<Q> multiply(double multiplier)
```
    Returns the result of multiplying this unit by the specified factor. If the factor is an integer value, the multiplication is exact (recommended). For example: [code] FOOT = METRE.multiply(3048).divide(10000); // Exact definition. ELECTRON_MASS = KILOGRAM.multiply(9.10938188e-31); // Approximation. [/code]
    
    Parameters:
    multiplier - the multiplier
    
    Returns:
    this unit scaled by the specified multiplier.
  - multiply
```
Unit<?> multiply(Unit<?> multiplier)
```
    Returns the product of this unit with the one specified.
    
    Parameters:
    multiplier - the unit multiplier.
    
    Returns:
    this * multiplier
  - inverse
```
Unit<?> inverse()
```
    Returns the inverse of this unit.
    
    Returns:
    1 / this
  - divide
```
Unit<Q> divide(double divisor)
```
    Returns the result of dividing this unit by an approximate divisor. If the factor is an integer value, the division is exact. For example: [code] QUART = GALLON_LIQUID_US.divide(4); // Exact definition. [/code]
    
    Parameters:
    divisor - the divisor value.
    
    Returns:
    this unit divided by the specified divisor.
  - divide
```
Unit<?> divide(Unit<?> divisor)
```
    Returns the quotient of this unit with the one specified.
    
    Parameters:
    divisor - the unit divisor.
    
    Returns:
    this / divisor
  - root
```
Unit<?> 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 or if this operation would result in an unit with a fractional exponent.
  - pow
```
Unit<?> 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.
  - toString
```
String toString()
```
    Returns a string representation of this unit. The string representation may be the unit symbol, or may be some representation of product units, multiplication factor and offset if any. The string may be localized at implementation choice.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    the (eventually localized) string representation of this unit.
    See Also:
    getSymbol()
  - transform
```
Unit<Q> transform(UnitConverter converter)
```
    Returns the unit derived from this unit using the specified converter. The converter does not need to be linear. For example:
    Unit DECIBEL = Unit.ONE.transform( new LogConverter(10).inverse().concatenate( new RationalConverter(1, 10)));
    
    Parameters:
    operation - the converter from the transformed unit to this unit.
    
    Returns:
    the unit after the specified transformation.

Interface Unit<Q extends Quantity<Q>>

Method Summary

Method Detail

getSymbol

getName

getDimension

getSystemUnit

getProductUnits

isCompatible

asType

getConverterTo

getConverterToAny

alternate

shift

multiply

multiply

inverse

divide

divide

root

pow

toString

transform