Package javax.measure

Interface UnitConverter


public interface UnitConverter
A converter of numeric values between different units.

Instances of this class are usually obtained through the Unit.getConverterTo(Unit) method.

Since:
1.0
Version:
1.4, May 12, 2019
Author:
Jean-Marie Dautelle, Werner Keil, Martin Desruisseaux, Thodoris Bais, Andi Huber
See Also:
  • Method Summary

    Modifier and Type
    Method
    Description
    Concatenates this converter with another converter.
    double
    convert(double value)
    Converts a double value.
    convert(Number value)
    Converts a Number value.
    List<? extends UnitConverter>
    Returns the steps of fundamental converters making up this converter or this if the converter is a fundamental converter.
    Returns the inverse of this converter.
    boolean
    Indicates if this converter is an identity converter.
    boolean
    Indicates whether this converter represents a (one-dimensional) linear transformation, that is a linear map (wikipedia) from a one-dimensional vector space (a scalar) to a one-dimensional vector space.
  • Method Details

    • isIdentity

      boolean isIdentity()
      Indicates if this converter is an identity converter. The identity converter returns its input argument (convert(x) == x).

      Note: Identity converters are also always 'linear', see isLinear().

      Returns:
      true if this converter is an identity converter.
    • isLinear

      boolean isLinear()
      Indicates whether this converter represents a (one-dimensional) linear transformation, that is a linear map (wikipedia) from a one-dimensional vector space (a scalar) to a one-dimensional vector space. Typically from 'R' to 'R', with 'R' the real numbers.

      Given such a 'linear' converter 'A', let 'u', 'v' and 'r' be arbitrary numbers, then the following must hold by definition:

      • A(u + v) == A(u) + A(v)
      • A(r * u) == r * A(u)

      Given a second 'linear' converter 'B', commutativity of composition follows by above definition:

      • (A o B) (u) == (B o A) (u)
      In other words, two 'linear' converters do have the property that A(B(u)) == B(A(u)), meaning for 'A' and 'B' the order of their composition does not matter. Expressed as Java code:

      A.concatenate(B).convert(u) == B.concatenate(A).convert(u)

      Note: For composing UnitConverters see also concatenate(UnitConverter).
      Returns:
      true if this converter represents a linear transformation; false otherwise.
    • inverse

      Returns the inverse of this converter. If x is a valid value, then x == inverse().convert(convert(x)) to within the accuracy of computer arithmetic.
      Returns:
      the inverse of this converter.
    • convert

      Converts a Number value.
      Parameters:
      value - the Number value to convert.
      Returns:
      the Number value after conversion.
    • convert

      double convert(double value)
      Converts a double value.
      Parameters:
      value - the numeric value to convert.
      Returns:
      the double value after conversion.
    • concatenate

      Concatenates this converter with another converter. The resulting converter is equivalent to first converting by the specified converter (right converter), and then converting by this converter (left converter).
      Parameters:
      converter - the other converter to concatenate with this converter.
      Returns:
      the concatenation of this converter with the other converter.
    • getConversionSteps

      Returns the steps of fundamental converters making up this converter or this if the converter is a fundamental converter.

      For example, converter1.getConversionSteps() returns converter1 while converter1.concatenate(converter2).getConversionSteps() returns converter1, converter2.

      Returns:
      the list of fundamental converters which concatenated make up this converter.