v5.2.0: add Duration#divide() method that takes another Duration and …

…outputs a unitless number.

doc/API.md

@@ -149,6 +149,7 @@ duration2 = duration.add(tc.hours(5)); // 18002 seconds
 duration2 = duration.sub(tc.milliseconds(500)); // 1.5 seconds
 duration2 = duration.multiply(3); // 6 seconds
 duration2 = duration.divide(3); // 0.67 seconds
+tc.years(1).divide(tc.months(2)); // 1 year divided by 2 months = 6
 
 // note that e.g. adding hours to months gives an approximate value
 // as not all months are equally long

doc/CHANGELOG.md

@@ -1,6 +1,10 @@
 
 # Changelog
 
+## 5.2.0 (2016-11-06)
+
+* Add Duration#divide() method that takes another Duration and outputs a unitless number.
+
 ## 5.1.2 (2016-10-28)
 
 * Inline the sourcemaps as requested in issue #28

package.json

@@ -1,6 +1,6 @@
 {
   "name": "timezonecomplete",
-  "version": "5.1.2",
+  "version": "5.2.0",
   "description": "DateTime, TimeZone, Duration and Period library aimed at providing a consistent and complete date-time interface, away from the original JavaScript Date class.",
   "keywords": [
     "Date",

src/lib/duration.ts

@@ -477,24 +477,38 @@ export class Duration {
 	}
 
 	/**
-	 * Approximate if the durations have units that cannot be converted
 	 * Multiply with a fixed number.
+	 * Approximate if the durations have units that cannot be converted
 	 * @return a new Duration of (this * value)
 	 */
 	public multiply(value: number): Duration {
 		return new Duration(this._amount * value, this._unit);
 	}
 
 	/**
-	 * Approximate if the durations have units that cannot be converted
-	 * Divide by a fixed number.
+	 * Divide by a unitless number. The result is a Duration, e.g. 1 year / 2 = 0.5 year
+	 * The result is approximate if this duration as a unit that cannot be converted to a number (e.g. 1 month has variable length)
 	 * @return a new Duration of (this / value)
 	 */
-	public divide(value: number): Duration {
-		if (value === 0) {
-			throw new Error("Duration.divide(): Divide by zero");
+	public divide(value: number): Duration;
+	/**
+	 * Divide this Duration by a Duration. The result is a unitless number e.g. 1 year / 1 month = 12
+	 * The result is approximate if this duration as a unit that cannot be converted to a number (e.g. 1 month has variable length)
+	 * @return a new Duration of (this / value)
+	 */
+	public divide(value: Duration): number;
+	public divide(value: number | Duration): Duration | number {
+		if (typeof value === "number") {
+			if (value === 0) {
+				throw new Error("Duration.divide(): Divide by zero");
+			}
+			return new Duration(this._amount / value, this._unit);
+		} else {
+			if (value._amount === 0) {
+				throw new Error("Duration.divide(): Divide by zero duration");
+			}
+			return this.milliseconds() / value.milliseconds();
 		}
-		return new Duration(this._amount / value, this._unit);
 	}
 
 	/**

src/test/test-duration.ts

@@ -337,7 +337,7 @@ describe("Duration()", (): void => {
 		});
 	});
 
-	describe("divide()", (): void => {
+	describe("divide() by number", (): void => {
 		it("should divide by positive number", (): void => {
 			expect(Duration.milliseconds(6).divide(3).milliseconds()).to.equal(2);
 		});
@@ -351,6 +351,20 @@ describe("Duration()", (): void => {
 		});
 	});
 
+	describe("divide() by Duration", (): void => {
+		it("should divide by positive Duration", (): void => {
+			expect(Duration.years(1).divide(Duration.months(2))).to.equal(6);
+		});
+		it("should throw on divide by 0", (): void => {
+			assert.throws((): void => {
+				Duration.milliseconds(6).divide(Duration.months(0));
+			});
+		});
+		it("should divide by negative number", (): void => {
+			expect(Duration.years(1).divide(Duration.months(-2))).to.equal(-6);
+		});
+	});
+
 	describe("add()", (): void => {
 		it("should add positive number", (): void => {
 			expect(Duration.milliseconds(2).add(Duration.milliseconds(3)).milliseconds()).to.equal(5);