Added compare, release v0.7.0

HISTORY.md

@@ -1,5 +1,8 @@
 # History
 
+## 2019-05-28, v0.7.0
+- Added compare
+
 ## 2019-05-28, v0.6.0
 - Implement valueOf()
 - Added lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual

README.md

@@ -636,6 +636,16 @@ UnitMath will use your custom type's `toString()` method when formatting a custo
   unit('3 ft').equals('1 yard') // true
   ```
 
+- `#compare(other: unit | string)`
+
+  Returns a value indicating whether this unit is less than (-1), greater than (1), or equal to (0), another unit.
+
+  ```js
+  unit('30 min').compare('1 hour') // -1
+  unit('60 min').compare('1 hour') // 0
+  unit('90 min').compare('1 hour') // 1
+  ```
+
 - `#lessThan(other: unit | string)`
 
   Compares this and another unit and returns true if this unit is less than the other.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitmath",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "JavaScript library for unit conversion and arithmetic",
   "main": "index.js",
   "module": "src/Unit.js",

src/Unit.js

@@ -436,6 +436,26 @@ let _config = function _config (options) {
       return this.equalQuantity(other) && options.type.eq(value1, value2)
     }
 
+    /**
+     * Compare this unit to another and return a value indicating whether this unit is less than, greater than, or equal to the other.
+     * @param {Unit} other
+     * @return {number} -1 if this unit is less than, 1 if this unit is greater than, and 0 if this unit is equal to the other unit.
+     */
+    compare (other) {
+      if (!options.type.conv._IS_UNITMATH_DEFAULT_FUNCTION && (options.type.gt._IS_UNITMATH_DEFAULT_FUNCTION || options.type.lt._IS_UNITMATH_DEFAULT_FUNCTION)) {
+        throw new Error(`When using custom types, compare requires a type.gt and a type.lt function`)
+      }
+      other = _convertParamToUnit(other)
+      let { value1, value2 } = _comparePrepare(this, other, true)
+      if (options.type.lt(value1, value2)) {
+        return -1
+      } else if (options.type.gt(value1, value2)) {
+        return 1
+      } else {
+        return 0
+      }
+    }
+
     /**
      * Compare this unit to another and return whether this unit is less than the other.
      * @param {Unit} other

test/Unit.test.js

@@ -696,6 +696,30 @@ describe('unitmath', () => {
     })
   })
 
+  describe('compare', () => {
+    it('should compare two units', () => {
+      assert.strictEqual(unit('30 min').compare('1 hour'), -1)
+      assert.strictEqual(unit('60 min').compare('1 hour'), 0)
+      assert.strictEqual(unit('90 min').compare('1 hour'), 1)
+    })
+
+    it('should work with valueless units', () => {
+      assert.strictEqual(unit('kg/hr').compare('kg/min'), -1)
+      assert.strictEqual(unit('kg/hr').compare('kg/hr'), 0)
+      assert.strictEqual(unit('kg/hr').compare('g/hr'), 1)
+    })
+
+    it('should throw if dimensions do not match', () => {
+      assert.throws(() => unit(100, 'N').compare(unit(100, 'kg m / s')), /Cannot compare units.*dimensions do not match/)
+      assert.throws(() => unit(100, 'cm').compare(unit(1, 'kg')), /Cannot compare units.*dimensions do not match/)
+    })
+
+    it('should convert parameter to a unit', () => {
+      assert.strictEqual(unit(100, 'cm').compare('2 m'), -1)
+      assert.strictEqual(unit('3 kg / kg').compare(2), 1)
+    })
+  })
+
   describe('lessThan', () => {
     it('should test whether one unit is less than another', () => {
       assert.strictEqual(unit(100, 'cm').lessThan(unit(1, 'm')), false)
@@ -2024,6 +2048,9 @@ describe('unitmath', () => {
         assert(unitDec('5 km').lessThanOrEqual('500000 cm'))
         assert(unitDec('5 N').greaterThan('5 dyne'))
         assert(unitDec('10 kg').greaterThanOrEqual('1 kg'))
+        assert.strictEqual(unitDec('60 min').compare('2 hour'), -1)
+        assert.strictEqual(unitDec('60 min').compare('1 hour'), 0)
+        assert.strictEqual(unitDec('60 min').compare('0.5 hour'), 1)
       })
 
       it('should do setValue', () => {