org.unitsofmeasurement.unit
Interface UnitConverter

public interface UnitConverter

A converter of numeric values.

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

Since:

0.6.0

Author:

Jean-Marie Dautelle, Werner Keil

Method Summary

UnitConverter	concatenate(UnitConverter converter) Concatenates this converter with another converter.
BigDecimal	convert(BigDecimal value, MathContext ctx) Converts a BigDecimal number according to the specified math context.
double	convert(double value) Converts a double value.
Number	convert(Number value) Converts a Number value.
List<? extends UnitConverter>	getCompoundConverters() Returns the chain of fundamental converters making up this converter or null if this converter is a fundamental converter.
UnitConverter	inverse() Returns the inverse of this converter.
boolean	isIdentity() Indicates if this converter is the identity converter.
boolean	isLinear() Indicates if this converter is linear.

Method Detail

isIdentity

boolean isIdentity()

Indicates if this converter is the identity converter. The identity converter does nothing (convert(x) == x).

Returns:

true if this converter is an identity converter.

isLinear

boolean isLinear()

Indicates if this converter is linear. A converter is linear if:

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

For linear converters the following property always hold:

   y1 = c1.convert(x1);
   y2 = c2.convert(x2);
   assert y1*y2 == c1.concatenate(c2).convert(x1*x2);
 

Returns:

true if this converter is linear; 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

double convert(double value)

Converts a double value.

Parameters:

value - the numeric value to convert.

Returns:

the double value after conversion.

convert

Number convert(Number value)

Converts a Number value.

Parameters:

value - the numeric value to convert.

Returns:

the Number value after conversion.

convert

BigDecimal convert(BigDecimal value,
                   MathContext ctx)
                   throws ArithmeticException

Converts a BigDecimal number according to the specified math context.

Parameters:

value - the decimal number to convert.

ctx - the math context being used for conversion.

Returns:

the decimal number after conversion.

Throws:

ArithmeticException - if the result is inexact but the context is MathContext.UNLIMITED, or the precision is 0 and the quotient has a non-terminating decimal expansion.

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.

getCompoundConverters

List<? extends UnitConverter> getCompoundConverters()

Returns the chain of fundamental converters making up this converter or null if this converter is a fundamental converter. For example, cvtr1.concatenate(cvtr2).getCompoundConverters() returns {cvtr1, cvtr2}.

Returns:

the list of fundamental converters which concatenated makes up this converter.