Update to include mathematical operations

README.md

@@ -48,42 +48,162 @@ Note: ⚠️  All property/method names up for bikeshedding.
 
 * `precision`, a number indicating the precision of the measurement. This precision is (provisionally) represented in terms of the number of fractional digits displayed.
 
-Note: ⚠️  It may be appropriate to instead represent precision in terms of number of significant digits. Feedback on this matter is desired.
+* `exponent`, an integer representing the power to which the unit is raised. "centimeters squared" could be {unit: "centimeter", exponent: 2}. It may be preferable to use CLDR names for commonly-used units; "cubic-meter" instead of {unit: "meter", exponent: 3}, for example.
 
-Constructor:
+* `usage`, the type of thing being measured. Useful for localization.
 
-* `Measure(value, unit, precision)`. Constructs a Measure with `value` as the numerical value of the Measure and `unit` as the unit of measurement, with the optional `precision` parameter used to specify the precision of the measurement. In the case of `unit` values indicating mixed units, the `value` is given in terms of the quantity of the *largest* unit.
+## Constructor
+
+* `Measure(value, {unit, precision, exponent, usage})`. Constructs a Measure with `value` as the numerical value of the Measure and `unit` as the unit of measurement, with the optional `precision` parameter used to specify the precision of the measurement. In the case of `unit` values indicating mixed units, the `value` is given in terms of the quantity of the *largest* unit.
 
 The object prototype would provide the following methods:
 
 * `convertTo(unit, precision)`. This method returns a Measure in the scale indicated by the `unit` parameter, with the value of the new Measure being the value of the Measure it is called on converted to the new scale. The `precision` parameter is optional.
 
-* `split()`. This method returns the measurement represented as an array of objects. The returned array for a Measure given in non-mixed units would contain one object with the following properties:
+* `toString()`. This method returns a string representation of the unit.
 
-    - `value`, representing the numerical value
-    - `unit`, representing the unit of measurement.
-    - `precision`, representing the precision of the measurement.
+* `toComponents()`. This method returns each component of the measurement as an object in an array. Intended for use
+with mixed units.
 
-The returned array for a Measure given in mixed units would contain one element for each component of the Measure. The `precision` property would only be present in the object representing the smallest unit.
+```js
+    let centimeters = new Measurement(30, {unit: "centimeter"})
+    centimeters.toString()
+    // "30 centimeters"
 
-* `convertToLocale(locale, usage)`. This method returns a Measure in the customary scale and at the customary precision for `locale`. The optional `usage` parameter can be used to indicate that the Measure should use the (potentially idiosyncratic) locale-specific customary unit of measurement for measurements of specific types of things. If, for example, the value was a measurement of a person's height, the value of `usage` would be (following the CLDR names) `"person-height"`. If the measurement is of a distance traveled by road, the value of `usage` would be `"road"`.
+    footAndInch.toComponents()
+    // [ {value: 5, unit: "foot"}, {value: 6, unit: "inch"}]
+```
 
-* `toLocaleString(locale, usage)`. This method returns an appropriately formatted string for the locale given by `locale` and the usage given by `usage`, with `usage` being an optional parameter.
+### Mixed units
 
-* `toString()`. This method returns a string representation of the unit.
+We absolutely must include mixed units in Measurement, because they're absolutely 
+needed for Smart Units. We can't just include "foot-and-inch" in Smart Units
+and not Measurement, since that invites specifically the type of abuse of 
+i18n tools for non-i18n purposes that we're trying to avoid with the Measure proposal
 
-# Examples
+The value of mixed units should be expressed in terms of the largest unit in the mixed unit. 
+(Alternately, the Measurement's value could be expressed in terms of the smallest unit. We're
+going with largest for the example below)
 
 ```js
 
-let m = new Measure(1.8, "meter");
-m.convertTo('foot', 2);
-// Returns a new Measure with the following properties:
-// `{value: 5.905511811023621, unit: "foot", precision: 2}`
-m.toString();
-// "5.91 feet"
-m.localeConvert("en-CA", "person-height")
-// `{value: 5.905511811023621, unit: "foot-and-inch", precision: 2}`
-m.toLocaleString("en-CA", "person-height")
-// "5 feet 11 inches"
+    let footAndInch = new Measurement(5.5, {unit: "foot-and-inch"})
+    footAndInch.toComponents()
+    // [ {value: 5, unit: "foot"}, {value: 6, unit: "inch"}]
+    footAndInch.toString()
+    // "5 feet and 6 inches"
+```
+
+
+## Mathematical operations
+
+Below is a list of mathematical operations that we should consider supporting. 
+Assume that we use [CLDR data](https://github.com/unicode-org/cldr/blob/main/common/supplemental/units.xml) 
+for now, and that both our unit names and the conversion constants are as in CLDR.
+
+This version places the options `unit`, `exponent`, and `precision` in an options bag. `unit` can be
+a required unit, or could default to `unit: "dimensionless"`
+
+### Precision
+A big question is how we should handle precision. Currently this explainer assumes precision means fractional 
+digits, not because it seems good but instead because it seems least-bad. [The Java Units of Measurement API](https://unitsofmeasurement.github.io/unit-api/) 
+appears to resolve this problem by not handling precision at all.
+
+### Proposed mathematical operations
+
+Raise a Measurement to an exponent:
+
+'''js
+    let measurement = new Measurement(10, {unit: "centimeter"})
+    measurement.exp(3)
+    // { value: 1000, unit: "cubic-centimeter"}
 ```
+
+* Multiply/divide a measurement by a constant
+
+```js
+    let measurement = new Measurement(10, {unit: "centimeter"})
+    measurement.multiply(20)
+    // {value: 200, unit: "centimeter"}
+    measurement.divide(10)
+    // {value: 20, unit: "centimeter"}
+```
+
+* Add/subtract two measurements of the same dimension
+
+```js
+    let measurement1 = new Measurement(10, {unit: "centimeter"})
+    let measurement2 = new Measurement(5, {unit: "centimeter"})
+    measurement1.add(measurement2)
+    // {value: 15, unit: "centimeter"}
+
+    let measurement3 = new Measurement(5, {unit: "meter"})
+    measurement1.add(measurement3)
+    // in the units of the Measurement that `add` is called on?
+    // {value: 510, unit: "centimeter"}
+
+    measurement1.subtract(measurement2);
+    // {value: 505, unit: "centimeter"}
+
+    // Precision is given in fractional digits. If doing calculation with units with
+    // precision values, the precision should be set to the least precise (taking 
+    // into account that units will have to be converted to the same scale)
+    let measurementWithPrecision1 = new Measurement(10.12, {unit: "centimeter", precision: 2}
+    let measurementWithPrecision2 = new Measurement(10.1234 {unit: "centimeter", precision: 4}
+    measurementWithPrecision1.add(measurementWithPrecision2);
+    // {value: 20.24, unit: "centimeter", precision: 2}
+
+```
+
+* Multiply / divide a Measurement by another Measurement 
+
+```js
+    let gallons = new Measurement(2, {unit: "gallon"})
+    let miles = new Measurement(30, {unit: "mile"})
+    miles.divide(gallon)
+    // {value: 15, unit: "miles-per-gallon"}
+
+    let centimeters1 = new Measurement(10, {unit: "centimeter"})
+    let centimeters2 = new Measurement(5, {unit: "centimeter"})
+    centimeters1.multiply(centimeters2)
+    // {value: 50, unit: "square-centimeter" }
+    // alternately: {value: 50, unit: "centimeter", exponent: 2}
+
+    centimeters1.divide(centimeters2)
+    // {value: 10, unit: "dimensionless"}
+```
+
+* Convert between scales
+
+```js
+    let inches = new Measure(12, {unit: "inch"})
+    inches.convert("centimeter")
+    // {value: 30.48, unit: "centimeter}
+
+    // using optional `precision` option
+    inches.convert("centimeter", 1);
+    // { value: 30.5, unit: "centimeter" }
+```
+
+* All of the above operations throw if incompatible dimensions are used, for example, adding 
+a measure of volume to a measure of speed.
+
+### Methods shifted to Smart Units
+
+All of the localization-related methods are shifted to Smart Units. There can be
+a `usage` option added to the options bag for Measurements in order to track
+what sort of thing is being measured. The `usage` option is used for the method below:
+
+* convertToLocale(locale)
+
+```js
+
+    let centimeters = Measurement(30.48, {unit: "centimeter", usage: "person-height"});
+    centimeters.convertToLocale("en");
+    // {value: 5.5, unit: "foot-and-inch"}
+
+    centimeters.toLocaleString('en');
+    // "5 feet and 6 inches"
+
+```
+