191: Allow non-double arguments for some Unit operations

Task-Url: https://github.com/unitsofmeasurement/unit-api/issues/issues/191

Author: keilw

src/main/java/javax/measure/Unit.java

@@ -67,7 +67,7 @@
  * @author <a href="mailto:steve@unidata.ucar.edu">Steve Emmerson</a>
  * @author <a href="mailto:martin.desruisseaux@geomatys.com">Martin Desruisseaux</a>
  * @author <a href="mailto:werner@units.tech">Werner Keil</a>
- * @version 1.6, April 12, 2019
+ * @version 2.0, April 24, 2019
  * @since 1.0
  *
  * @see <a href="http://en.wikipedia.org/wiki/Units_of_measurement">Wikipedia: Units of measurement</a>
@@ -232,6 +232,24 @@ public interface Unit<Q extends Quantity<Q>> {
      */
     Unit<Q> alternate(String symbol);
 
+    /**
+     * 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:
+     *
+     * <code>
+     *    CELSIUS = KELVIN.shift(273.15);
+     * </code>
+     *
+     * 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
+     * <em>subtracting</em> the offset to the value in the old unit.
+     *
+     * @param offset
+     *          the offset added (expressed in this unit).
+     * @return this unit offset by the specified value.
+     * @since 2.0
+     */
+    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:
@@ -261,6 +279,21 @@ public interface Unit<Q extends Quantity<Q>> {
      * @param multiplier
      *          the multiplier
      * @return this unit scaled by the specified multiplier.
+     * @since 2.0
+     */
+    Unit<Q> multiply(Number multiplier);
+    
+    /**
+     * Returns the result of multiplying this unit by the specified factor. For example:
+     *
+     * <code>
+     *    FOOT = METRE.multiply(3048).divide(10000); // Exact definition.
+     *    ELECTRON_MASS = KILOGRAM.multiply(9.10938188e-31); // Approximation.
+     * </code>
+     *
+     * @param multiplier
+     *          the multiplier
+     * @return this unit scaled by the specified multiplier.
      */
     Unit<Q> multiply(double multiplier);
 
@@ -282,7 +315,7 @@ public interface Unit<Q extends Quantity<Q>> {
     Unit<?> inverse();
 
     /**
-     * Returns the result of dividing this unit by an approximate divisor. If the factor is an integer value, the division is exact. For example:
+     * Returns the result of dividing this unit by a divisor. If the factor is an integer value, the division is exact. For example:
      *
      * <code>
      *    GRAM = KILOGRAM.divide(1000); // Exact definition.
@@ -291,6 +324,20 @@ public interface Unit<Q extends Quantity<Q>> {
      * @param divisor
      *          the divisor value.
      * @return this unit divided by the specified divisor.
+     * @since 2.0
+     */
+    Unit<Q> divide(Number divisor);
+    
+    /**
+     * Returns the result of dividing this unit by an approximate divisor. For example:
+     *
+     * <code>
+     *    GRAM = KILOGRAM.divide(1000d);
+     * </code>
+     *
+     * @param divisor
+     *          the divisor value.
+     * @return this unit divided by the specified divisor.
      */
     Unit<Q> divide(double divisor);
 

src/test/java/javax/measure/test/EnumUnit.java

@@ -30,6 +30,7 @@
 package javax.measure.test;
 
 import java.util.Map;
+import java.util.Objects;
 
 import javax.measure.Dimension;
 import javax.measure.IncommensurableException;
@@ -145,4 +146,22 @@ public Unit prefix(Prefix prefix) {
         final MultiplyConverter converter = new MultiplyConverter(Math.pow(prefix.getBase(), prefix.getExponent()));
         return this.transform(converter);
     }
+
+	@Override
+	public Unit shift(Number offset) {
+		Objects.requireNonNull(offset);
+		return multiply(offset.doubleValue());
+	}
+
+	@Override
+	public Unit multiply(Number multiplier) {
+		Objects.requireNonNull(multiplier);
+		return multiply(multiplier.doubleValue());
+	}
+
+	@Override
+	public Unit divide(Number divisor) {
+		Objects.requireNonNull(divisor);
+		return divide(divisor.doubleValue());
+	}
 }

src/test/java/javax/measure/test/TestUnit.java

@@ -30,6 +30,7 @@
 package javax.measure.test;
 
 import java.util.Map;
+import java.util.Objects;
 
 import javax.measure.Dimension;
 import javax.measure.Quantity;
@@ -113,7 +114,7 @@ public UnitConverter getConverterTo(Unit<Q> that) throws UnconvertibleException
     public UnitConverter getConverterToAny(Unit<?> that) throws IncommensurableException, UnconvertibleException {
         if (!isCompatible(that))
             throw new IncommensurableException(this + " is not compatible with " + that);
-        TestUnit thatAbstr = (TestUnit) that; // Since both units are
+        TestUnit<?> thatAbstr = (TestUnit<?>) that; // Since both units are
         // compatible they must
         // be both test
         // units.
@@ -147,7 +148,7 @@ public boolean isCompatible(Unit<?> that) {
     }
 
     public Unit<Q> multiply(double factor) {
-        return new BaseUnit(symbol, multFactor * factor);
+        return new BaseUnit<Q>(symbol, multFactor * factor);
     }
 
     public Unit<?> multiply(Unit<?> that) {
@@ -211,4 +212,22 @@ public String toString() {
         }
         return sb.toString();
     }
+    
+	@Override
+	public Unit<Q> shift(Number offset) {
+		Objects.requireNonNull(offset);
+		return multiply(offset.doubleValue());
+	}
+
+	@Override
+	public Unit<Q> multiply(Number multiplier) {
+		Objects.requireNonNull(multiplier);
+		return multiply(multiplier.doubleValue());
+	}
+
+	@Override
+	public Unit<Q> divide(Number divisor) {
+		Objects.requireNonNull(divisor);
+		return divide(divisor.doubleValue());
+	}
 }

src/test/java/javax/measure/test/UnitTest.java

@@ -47,6 +47,8 @@
  *
  */
 public class UnitTest {
+	private static final Number NULL_NUMBER = null;
+	
     @SuppressWarnings("rawtypes")
     private Unit sut;
 
@@ -91,4 +93,31 @@ public void testGetConverterTo() {
             assertNotNull(converter);
         });
     }
+    
+    @Test
+    public void testDivideNull() {
+        assertThrows(NullPointerException.class, () -> {
+            sut = DistanceUnit.m;          
+            @SuppressWarnings({ "rawtypes", "unused" })
+			Unit result = sut.divide(NULL_NUMBER);
+        });
+    }
+    
+    @Test
+    public void testMultiplyNull() {
+        assertThrows(NullPointerException.class, () -> {
+            sut = DistanceUnit.m;          
+            @SuppressWarnings({ "unused", "rawtypes" })
+			Unit result = sut.multiply(NULL_NUMBER);
+        });
+    }
+    
+    @Test
+    public void testShiftNull() {
+        assertThrows(NullPointerException.class, () -> {
+            sut = DistanceUnit.m;          
+            @SuppressWarnings({ "unused", "rawtypes" })
+			Unit result = sut.shift(NULL_NUMBER);
+        });
+    }
 }