Top Description Methods
javax.measure

public Interface Unit<Q extends javax.measure.Quantity<Q>>

Type Parameters
<Q>
The type of the quantity measured by this unit.
Imports
java.util.Map
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.

Authors
Jean-Marie Dautelle, Steve Emmerson, Martin Desruisseaux, Werner Keil
Since
1.0
Version
2.4, November 11, 2020
See Also
Wikipedia: Units of measurement

Method Summary

Modifier and TypeMethod and Description
public Unit<Q>

Returns:

the alternate unit.
alternate(String
the new symbol for the alternate unit.
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.

public <
The type of the quantity measured by the unit.
T extends Quantity<T>> Unit<T>

Returns:

this unit parameterized with the specified type.
asType(Class<T>
the quantity class identifying the nature of the unit.
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.

public Unit<Q>

Returns:

this unit divided by the specified divisor.
divide(Number
the divisor value.
divisor)

Returns the result of dividing this unit by a divisor.

public Unit<Q>

Returns:

this unit divided by the specified divisor.
divide(double
the divisor value.
divisor)

Returns the result of dividing this unit by an approximate divisor.

public Unit<?>

Returns:

this / divisor
divide(Unit<?>
the unit divisor.
divisor)

Returns the quotient of this unit with the one specified.

public Map<? extends Unit<?>, Integer>

Returns:

the base units and their exponent making up this unit.
getBaseUnits()

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

public UnitConverter

Returns:

the converter from this unit to that unit.
getConverterTo(Unit<Q>
the unit of same type to which to convert the numeric values.
that)

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

public UnitConverter

Returns:

the converter from this unit to that unit.
getConverterToAny(Unit<?>
the unit to which to convert the numeric values.
that)

Returns a converter from this unit to the specified unit of type unknown.

public Dimension

Returns:

the dimension of this unit.
getDimension()

Returns the dimension of this unit.

public String

Returns:

this unit name, or null if this unit has not specific name associated with (e.g. product of units).
getName()

Returns the name (if any) of this unit.

public String

Returns:

this unit symbol, or null if this unit has not specific symbol associated with (e.g. product of units).
getSymbol()

Returns the symbol (if any) of this unit.

public Unit<Q>

Returns:

the system unit this unit is derived from, or this if this unit is a system unit.
getSystemUnit()

Returns the unscaled system unit from which this unit is derived.

public Unit<?>

Returns:

1 / this
inverse()

Returns the reciprocal (multiplicative inverse) of this unit.

public boolean

Returns:

this.getDimension().equals(that.getDimension())
isCompatible(Unit<?>
the other unit to compare for compatibility.
that)

Indicates if this unit is compatible with the unit specified.

public boolean

Returns:

true if that ≡ this.
isEquivalentTo(Unit<Q>
the Unit<Q> to be compared with this instance.
that)

Indicates if this unit represents the same quantity than the given unit, ignoring name and symbols.

public Unit<Q>

Returns:

this unit scaled by the specified multiplier.
multiply(Number
the multiplier
multiplier)

Returns the result of multiplying this unit by the specified factor.

public Unit<Q>

Returns:

this unit scaled by the specified multiplier.
multiply(double
the multiplier
multiplier)

Returns the result of multiplying this unit by the specified factor.

public Unit<?>

Returns:

this * multiplier
multiply(Unit<?>
the unit multiplier.
multiplier)

Returns the product of this unit with the one specified.

public Unit<?>

Returns:

the result of raising this unit to the exponent.
pow(int
the exponent.
n)

Returns an unit raised to the n-th (integer) power of this unit.

public Unit<Q>

Returns:

the unit with the given prefix applied.
prefix(Prefix
the prefix to apply on this unit.
prefix)

Returns a new unit equal to this unit prefixed by the specified prefix.

public Unit<?>

Returns:

the n-th root of this unit.
root(int
an integer giving the root's order as in 'n-th root'
n)

Returns an unit that is the n-th (integer) root of this unit.

public Unit<Q>

Returns:

this unit offset by the specified value.
shift(Number
the offset added (expressed in this unit).
offset)

Returns the result of setting the origin of the scale of measurement to the given value.

public Unit<Q>

Returns:

this unit offset by the specified value.
shift(double
the offset added (expressed in this unit).
offset)

Returns the result of setting the origin of the scale of measurement to the given value.

public String

Returns:

the string representation of this unit.
toString()

Returns a string representation of this unit.

public Unit<Q>

Returns:

the unit after the specified transformation.
transform(UnitConverter
the converter from the transformed unit to this unit.
operation)

Returns the unit derived from this unit using the specified converter.

Method Detail

alternateback to summary
public 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:

Unit<Angle> RADIAN = ONE.alternate("rad").asType(Angle.class);
Unit<Force> NEWTON = METRE.multiply(KILOGRAM).divide(SECOND.pow(2)).alternate("N").asType(Force.class);
Unit<Pressure> PASCAL = NEWTON.divide(METRE.pow(2)).alternate("Pa").asType(Pressure.class);
Parameters
symbol:String

the new symbol for the alternate unit.

Returns:Unit<Q>

the alternate unit.

Exceptions
IllegalArgumentException:
if this unit is not an unscaled standard unit.
MeasurementException:
if the specified symbol is not valid or is already associated to a different unit.
asTypeback to summary
public <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:
Unit<Speed> C = METRE.multiply(299792458).divide(SECOND).asType(Speed.class);

Parameters
<T>
The type of the quantity measured by the unit.
type:Class<T>

the quantity class identifying the nature of the unit.

Returns:Unit<T>

this unit parameterized with the specified type.

Exceptions
ClassCastException:
if the dimension of this unit is different from the specified quantity dimension.
divideback to summary
public Unit<Q> divide(Number divisor)

Returns the result of dividing this unit by a divisor. If the factor is an integer value, the division is exact. For example:
GRAM = KILOGRAM.divide(1000); // Exact definition.

Parameters
divisor:Number

the divisor value.

Returns:Unit<Q>

this unit divided by the specified divisor.

Since
2.0
divideback to summary
public Unit<Q> divide(double divisor)

Returns the result of dividing this unit by an approximate divisor. For example:
GRAM = KILOGRAM.divide(1000d);

Parameters
divisor:double

the divisor value.

Returns:Unit<Q>

this unit divided by the specified divisor.

divideback to summary
public Unit<?> divide(Unit<?> divisor)

Returns the quotient of this unit with the one specified.

Parameters
divisor:Unit<?>

the unit divisor.

Returns:Unit<?>

this / divisor

getBaseUnitsback to summary
public Map<? extends Unit<?>, Integer> getBaseUnits()

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:Map<? extends Unit<?>, Integer>

the base units and their exponent making up this unit.

getConverterToback to summary
public 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 as getConverterToAny(Unit) without raising checked exception.

Parameters
that:Unit<Q>

the unit of same type to which to convert the numeric values.

Returns:UnitConverter

the converter from this unit to that unit.

Exceptions
UnconvertibleException:
if a converter cannot be constructed.
See Also
getConverterToAny(Unit)
getConverterToAnyback to summary
public 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:Unit<?>

the unit to which to convert the numeric values.

Returns:UnitConverter

the converter from this unit to that unit.

Exceptions
IncommensurableException:
if this unit is not compatible with that unit.
UnconvertibleException:
if a converter cannot be constructed.
See Also
getConverterTo(Unit), isCompatible(Unit)
getDimensionback to summary
public 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:Dimension

the dimension of this unit.

See Also
isCompatible(Unit)
getNameback to summary
public String getName()

Returns the name (if any) of this unit. This method returns null if this unit has no specific name associated with.

Returns:String

this unit name, or null if this unit has not specific name associated with (e.g. product of units).

See Also
toString(), javax.measure.format.UnitFormat
getSymbolback to summary
public String getSymbol()

Returns the symbol (if any) of this unit. This method returns null if this unit has no specific symbol associated with.

Returns:String

this unit symbol, or null if this unit has not specific symbol associated with (e.g. product of units).

See Also
toString(), javax.measure.format.UnitFormat
getSystemUnitback to summary
public 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:

static boolean isAngularSpeed(Unit<?> unit) {
   return unit.getSystemUnit().equals(RADIAN.divide(SECOND));
}
assert isAngularSpeed(REVOLUTION.divide(MINUTE)); // Returns true.
Returns:Unit<Q>

the system unit this unit is derived from, or this if this unit is a system unit.

inverseback to summary
public Unit<?> inverse()

Returns the reciprocal (multiplicative inverse) of this unit.

Returns:Unit<?>

1 / this

See Also
Wikipedia: Multiplicative inverse
isCompatibleback to summary
public boolean isCompatible(Unit<?> that)

Indicates if this unit is compatible with the unit specified. Units don't need to be equal to be compatible. For example (assuming ONE is a dimensionless unit):
RADIAN.equals(ONE) == false
RADIAN.isCompatible(ONE) == true
RADIAN.isEquivalentTo(ONE) doesn't compile

Parameters
that:Unit<?>

the other unit to compare for compatibility.

Returns:boolean

this.getDimension().equals(that.getDimension())

See Also
getDimension()
isEquivalentToback to summary
public boolean isEquivalentTo(Unit<Q> that)

Indicates if this unit represents the same quantity than the given unit, ignoring name and symbols. Two units are equivalent if the conversion between them is identity.

Unlike isCompatible(Unit) an equivalence check requires both units to be strictly type-compatible, because it makes no sense to compare e.g. gram and mm for equivalence. By contrast, the compatibility check can works across different quantity types.

Parameters
that:Unit<Q>

the Unit<Q> to be compared with this instance.

Returns:boolean

true if that ≡ this.

Exceptions
NullPointerException:
if the unit is null
Since
2.1
See Also
Cambridge Dictionary: equivalent, LEXICO: equivalent
multiplyback to summary
public Unit<Q> multiply(Number 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:
FOOT = METRE.multiply(3048).divide(10000); // Exact definition.
ELECTRON_MASS = KILOGRAM.multiply(9.10938188e-31); // Approximation.

Parameters
multiplier:Number

the multiplier

Returns:Unit<Q>

this unit scaled by the specified multiplier.

Since
2.0
multiplyback to summary
public Unit<Q> multiply(double multiplier)

Returns the result of multiplying this unit by the specified factor. For example:
FOOT = METRE.multiply(3048).divide(10000); // Exact definition.
ELECTRON_MASS = KILOGRAM.multiply(9.10938188e-31); // Approximation.

Parameters
multiplier:double

the multiplier

Returns:Unit<Q>

this unit scaled by the specified multiplier.

multiplyback to summary
public Unit<?> multiply(Unit<?> multiplier)

Returns the product of this unit with the one specified.

Parameters
multiplier:Unit<?>

the unit multiplier.

Returns:Unit<?>

this * multiplier

powback to summary
public Unit<?> pow(int n)

Returns an unit raised to the n-th (integer) power of this unit. Equivalent to the mathematical expression unit^n.

Parameters
n:int

the exponent.

Returns:Unit<?>

the result of raising this unit to the exponent.

prefixback to summary
public Unit<Q> prefix(Prefix prefix)

Returns a new unit equal to this unit prefixed by the specified prefix.

Parameters
prefix:Prefix

the prefix to apply on this unit.

Returns:Unit<Q>

the unit with the given prefix applied.

Since
2.0
rootback to summary
public Unit<?> root(int n)

Returns an unit that is the n-th (integer) root of this unit. Equivalent to the mathematical expression unit^(1/n).

Parameters
n:int

an integer giving the root's order as in 'n-th root'

Returns:Unit<?>

the n-th root of this unit.

Exceptions
ArithmeticException:
if n == 0 or if this operation would result in an unit with a fractional exponent.
shiftback to summary
public Unit<Q> shift(Number 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:
CELSIUS = KELVIN.shift(273.15); 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:Number

the offset added (expressed in this unit).

Returns:Unit<Q>

this unit offset by the specified value.

Since
2.0
shiftback to summary
public 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:
CELSIUS = KELVIN.shift(273.15); 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:double

the offset added (expressed in this unit).

Returns:Unit<Q>

this unit offset by the specified value.

toStringback to summary
public 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 by the means of a particular device and platform.

Returns:String

the string representation of this unit.

Annotations
@Override
See Also
getSymbol(), javax.measure.format.UnitFormat
transformback to summary
public 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:

    Unit<Dimensionless> DECIBEL = Unit.ONE.transform(
        new LogConverter(10).inverse().concatenate(
            new RationalConverter(1, 10)));
Parameters
operation:UnitConverter

the converter from the transformed unit to this unit.

Returns:Unit<Q>

the unit after the specified transformation.