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
    UnitConverter
    concatenate(UnitConverter converter)
    Concatenates this converter with another converter.
    double
    convert(double value)
    Converts a double value.
    Number
    convert(Number value)
    Converts a Number value.
    List<? extends UnitConverter>
    getConversionSteps()
    Returns the steps of fundamental converters making up this converter or this if the converter is a fundamental converter.
    UnitConverter
    inverse()
    Returns the inverse of this converter.
    boolean
    isIdentity()
    Indicates if this converter is an identity converter.
    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.

  • 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

      UnitConverter 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

      Number convert(Number value)
      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

      UnitConverter concatenate(UnitConverter converter)
      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

      List<? extends UnitConverter> 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.