Example usage:
+ *{@code
+ * MeasureUnit meter = MeasureUnit.METER;
+ * MeasureUnit centimeter = MeasureUnit.CENTIMETER;
+ * BigDecimal valueInCentimeters = new BigDecimal("100");
+ * BigDecimal valueInMeters = meter.convertFrom(valueInCentimeters, centimeter);
+ * }
+ *
+ * Note: This method supports conversion only between SINGLE and COMPOUND units. + * Conversion involving MIXED units is not supported.
+ * + *See {@link Complexity} for details on unit types.
+ * + * @param value The numeric value in the other unit to be converted. + * @param source The unit from which the value is being converted. + * @return The value converted to this unit. + * @throws IllegalArgumentException if one of the units is MIXED. + * @throws UnitsIncompatibleException if the units are not convertible. + * @throws UnsupportedOperationException if conversion info is not set for this unit or the other unit. + * + * @draft ICU 78 + */ + public double convertFrom(double value, MeasureUnit source ) { + if (this.getComplexity() == Complexity.MIXED || source.getComplexity() == Complexity.MIXED) { + throw new IllegalArgumentException("Conversion between mixed units is not supported"); + } + + if (conversionInfo == null || source.conversionInfo == null) { + throw new UnsupportedOperationException("Conversion info not set for this unit"); + } + + String targetBaseUnit = this.conversionInfo.getBaseUnit(); + String sourceBaseUnit = source.conversionInfo.getBaseUnit(); + String sourceReciprocalBaseUnit = source.conversionInfo.getReciprocalBaseUnit(); + + // Determine convertibility + Convertibility convertibility; + if (targetBaseUnit.equals(sourceBaseUnit)) { + convertibility = Convertibility.CONVERTIBLE; + } else if (targetBaseUnit.equals(sourceReciprocalBaseUnit)) { + convertibility = Convertibility.RECIPROCAL; + } else { + throw new UnitsIncompatibleException("Units are not convertible"); + } + + double sourceRate = source.conversionInfo.getConversionRateToBaseUnit(); + double sourceOffset = source.conversionInfo.getOffsetToBaseUnit(); + + double targetRate = this.conversionInfo.getConversionRateToBaseUnit(); + double targetOffset = this.conversionInfo.getOffsetToBaseUnit(); + + + // In order to calculate the final result, there are two cases: + // 1. the units are convertible (linearly convertible) + // in this case, we have the following formulas: + // source * sourceRate + sourceOffset = Base + // target * targetRate + targetOffset = Base + // by solving these equations, we get the final conversion rate and offset. + // target = source * (sourceRate / targetRate) + (targetOffset - sourceOffset)/ targetRate. + // + // 2. the units are reciprocal (reciprocally convertible) + // Note: when the units are reciprocal, the offset is 0. + // in this case, we have the following formulas: + // source * sourceRate = Base + // target * targetRate = 1 / Base + // by solving these equations, we get the final conversion rate and offset. + // target = 1 / (source * sourceRate * targetRate) + if (convertibility == Convertibility.CONVERTIBLE) { + return value * sourceRate / targetRate + (targetOffset - sourceOffset)/ targetRate; + } else { + return 1 / (value * sourceRate * targetRate); + } + } + + /** + * Converts a Measure from another unit to this unit. + * + *+ * Example usage: + *
+ * + *{@code
+ * MeasureUnit meter = MeasureUnit.METER;
+ * MeasureUnit centimeter = MeasureUnit.CENTIMETER;
+ * Measure measure = new Measure(new BigDecimal("100"), centimeter);
+ * Measure convertedMeasure = meter.convertFrom(measure);
+ * }
+ *
+ * + * Note: This method supports conversion only between SINGLE and COMPOUND units. + * Conversion involving MIXED units is not supported. + *
+ * + *+ * See {@link Complexity} for details on unit types. + *
+ * + *+ * Note: This method is a wrapper around {@link #convertFrom(MeasureUnit, BigDecimal)}. + *
+ * + * @param measure The measure to be converted. + * @return The measure converted to this unit. + * @throws IllegalArgumentException if one of the measure's units is MIXED or conversion info is not set. + * @throws UnitsIncompatibleException if the measure's units are not convertible. + * + * @draft ICU 78 + */ + public Measure convertFrom(Measure measure) { + if (measure == null) { + throw new UnsupportedOperationException("`measure` must not be null"); + } + + MeasureUnit sourceUnit = measure.getUnit(); + + // If the measure's unit is the same as the current unit, no conversion is needed. + if (this.equals(sourceUnit)) { + return measure; + } + + if (this.getComplexity() == Complexity.MIXED || sourceUnit.getComplexity() == Complexity.MIXED) { + throw new UnsupportedOperationException("Conversion involving MIXED units is not supported"); + } + + double sourceValue = measure.getNumber().doubleValue(); + double convertedValue = this.convertFrom( sourceValue, sourceUnit); + + return new Measure(convertedValue, this); } /** @@ -435,7 +593,9 @@ public static MeasureUnit forIdentifier(String identifier) { return NoUnit.BASE; } - return MeasureUnitImpl.forIdentifier(identifier).build(); + ConversionRates conversionRates = new ConversionRates(); + + return MeasureUnitImpl.forIdentifier(identifier, conversionRates).build(); } /** @@ -457,6 +617,14 @@ public static MeasureUnit fromMeasureUnitImpl(MeasureUnitImpl measureUnitImpl) { private MeasureUnit(MeasureUnitImpl measureUnitImpl) { type = null; subType = null; + conversionInfo = null; + this.measureUnitImpl = measureUnitImpl.copy(); + } + + private MeasureUnit(MeasureUnitImpl measureUnitImpl, ConversionInfoToBase conversionInfo) { + type = null; + subType = null; + this.conversionInfo = conversionInfo; this.measureUnitImpl = measureUnitImpl.copy(); } diff --git a/icu4j/main/core/src/main/java/com/ibm/icu/util/UnitsIncompatibleException.java b/icu4j/main/core/src/main/java/com/ibm/icu/util/UnitsIncompatibleException.java new file mode 100644 index 000000000000..23528f931baf --- /dev/null +++ b/icu4j/main/core/src/main/java/com/ibm/icu/util/UnitsIncompatibleException.java @@ -0,0 +1,63 @@ +package com.ibm.icu.util; + +/** + * Exception thrown when an attempt is made to convert between units + * that are not compatible with each other. + * + * Examples of unit compatibility: + * - Converting "meter" to "mile" is linearly convertible (compatible). + * - Converting "liter-per-100km" to "mile-per-gallon" is reciprocally + * convertible (compatible). + * - Converting "meter" to "kilogram" is not convertible (incompatible). + * + * @draft ICU 78 + */ +public class UnitsIncompatibleException extends IllegalArgumentException { + + // TODO: is the number correct? + private static final long serialVersionUID = 1286569061095434541L; + + /** + * Constructs a new UnitsIncompatibleException with no detail message. + * + * @draft ICU 78 + */ + public UnitsIncompatibleException() { + super(); + } + + /** + * Constructs a new UnitsIncompatibleException with the specified detail + * message. + * + * @param message the detail message + * @draft ICU 78 + */ + public UnitsIncompatibleException(String message) { + super(message); + } + + /** + * Constructs a new UnitsIncompatibleException with the specified cause. + * + * @param cause original exception (normally a {@link IllegalArgumentException}) + * @draft ICU 78 + */ + + public UnitsIncompatibleException(Throwable cause) { + super(cause); + } + + /** + * Constructs a new UnitsIncompatibleException with the specified detail + * message and cause. + * + * @param message the detail message + * @param cause the cause (normally an {@link IllegalArgumentException}) + * @draft ICU 78 + */ + public UnitsIncompatibleException(String message, Throwable cause) { + super(message, cause); + } + +}