Package javax.measure

Interface Unit<Q extends Quantity<Q>>

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.

Since:
1.0
Version:
2.4, November 11, 2020
Author:
Jean-Marie Dautelle, Steve Emmerson, Martin Desruisseaux, Werner Keil
See Also:

  • Method Summary

    Modifier and Type
    Method
    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<Q>
    divide(Number divisor)
    Returns the result of dividing this unit by a divisor.
    Unit<?>
    divide(Unit<?> divisor)
    Returns the quotient of this unit with the one specified.
    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).
    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.
    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 reciprocal (multiplicative inverse) of this unit.
    boolean
    isCompatible(Unit<?> that)
    Indicates if this unit is compatible with the unit specified.
    boolean
    isEquivalentTo(Unit<Q> that)
    Indicates if this unit represents the same quantity than the given unit, ignoring name and symbols.
    Unit<Q>
    multiply(double multiplier)
    Returns the result of multiplying this unit by the specified factor.
    Unit<Q>
    multiply(Number 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 an unit raised to the n-th (integer) power of this unit.
    Unit<Q>
    prefix(Prefix prefix)
    Returns a new unit equal to this unit prefixed by the specified prefix.
    Unit<?>
    root(int n)
    Returns an unit that is the n-th (integer) 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.
    Unit<Q>
    shift(Number 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 operation)
    Returns the unit derived from this unit using the specified converter.

  • Method Details

    • 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:

    • 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:

    • 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:

    • 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:

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

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

    • getBaseUnits

      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:
      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 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 - the other unit to compare for compatibility.
      Returns:
      this.getDimension().equals(that.getDimension())
      See Also:

    • isEquivalentTo

      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 - the Unit<Q> to be compared with this instance.
      Returns:
      true if that ≡ this.
      Throws:
      NullPointerException - if the unit is null
      Since:
      2.1
      See Also:

    • 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:
      Unit<Speed> C = METRE.multiply(299792458).divide(SECOND).asType(Speed.class);
      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 as 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

      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:

    • 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:

      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 - the new symbol for the alternate unit.
      Returns:
      the alternate unit.
      Throws:
      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.

    • shift

      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 - the offset added (expressed in this unit).
      Returns:
      this unit offset by the specified value.
      Since:
      2.0

    • 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:
      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 - the offset added (expressed in this unit).
      Returns:
      this unit offset by the specified value.

    • multiply

      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 - the multiplier
      Returns:
      this unit scaled by the specified multiplier.
      Since:
      2.0

    • multiply

      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 - 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 reciprocal (multiplicative inverse) of this unit.
      Returns:
      1 / this
      See Also:

    • divide

      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 - the divisor value.
      Returns:
      this unit divided by the specified divisor.
      Since:
      2.0

    • divide

      Unit<Q> divide(double divisor)
      Returns the result of dividing this unit by an approximate divisor. For example:
      GRAM = KILOGRAM.divide(1000d);
      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 an unit that is the n-th (integer) root of this unit. Equivalent to the mathematical expression unit^(1/n).
      Parameters:
      n - an integer giving the root's order as in 'n-th root'
      Returns:
      the n-th 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 an unit raised to the n-th (integer) power of this unit. Equivalent to the mathematical expression unit^n.
      Parameters:
      n - the exponent.
      Returns:
      the result of raising this unit to the exponent.

    • transform

      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 - the converter from the transformed unit to this unit.
      Returns:
      the unit after the specified transformation.

    • 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 by the means of a particular device and platform.

      Overrides:
      toString in class Object
      Returns:
      the string representation of this unit.
      See Also:

    • prefix

      Unit<Q> prefix(Prefix prefix)
      Returns a new unit equal to this unit prefixed by the specified prefix.
      Parameters:
      prefix - the prefix to apply on this unit.
      Returns:
      the unit with the given prefix applied.
      Since:
      2.0