Date_lib functions for durations

process/Date_lib/process.js

@@ -110,7 +110,11 @@ DateUtils.getDayDifference = function (pPastDate, pCurrentDate)
  * 
  * @return {String} the formatted and easy readable string
  */
-DateUtils.formatDuration = function(pDuration, pLocale) {
+DateUtils.formatDuration = function(pDuration, pLocale) 
+{
+    if (pDuration instanceof Duration)
+        pDuration = pDuration.valueOf();
+        
     var duration = eMath.divInt(pDuration, 1000);
     
     var hours = Math.floor( Math.abs( duration / datetime.ONE_HOUR ) );        
@@ -167,25 +171,23 @@ DateUtils.getCurrentYear = function ()
 
 
 /**
- * Object for handling durations. It consists of years, months, days and milliseconds. Because hours, minutes and seconds have fixed lengths, these
- * are all added to the milliseconds part, but years and months can have different amounts of days, so they are stored separately.
+ * Object for handling durations. It consists of months (a year = 12 months), days and milliseconds. Because hours, minutes and seconds have fixed 
+ * lengths, these are all added to the milliseconds part, but months can have different amounts of days, so they are stored separately.
  * 
- * @param {Number} [pYears=0] years
  * @param {Number} [pMonths=0] months
  * @param {Number} [pDays=0] days
  * @param {Number} [pMillis=0] milliseconds
  */
-function Duration (pYears, pMonths, pDays, pMillis)
+function Duration (pMonths, pDays, pMillis)
 {
-    this.years = pYears !== undefined ? Number(pYears) : 0;
-    this.months = pMonths !== undefined ? Number(pMonths) : 0;
+    this._totalMonths = pMonths ? Number(pMonths) : 0;
     //because of daylight saving time, a day is not always 24h
-    this.days = pDays !== undefined ? Number(pDays) : 0;
-    this.milliseconds = pMillis !== undefined ? Number(pMillis) : 0;
+    this._days = pDays ? Number(pDays) : 0;
+    this._milliseconds = pMillis ? Number(pMillis) : 0;
 }
 
 /**
- * creates a new Duration object, this function can also take hours, minutes and seconds (they are automatically converted to milliseconds)
+ * creates a new Duration object, this function can also take hours, minutes, seconds and milliseconds (they are automatically converted to milliseconds)
  * 
  * @param {Number} [pYears=0] years
  * @param {Number} [pMonths=0] months
@@ -193,21 +195,67 @@ function Duration (pYears, pMonths, pDays, pMillis)
  * @param {Number} [pHours=0] hours
  * @param {Number} [pMinutes=0] minutes
  * @param {Number} [pSeconds=0] seconds
+ * @param {Number} [pMilliseconds=0] milliseconds
  * @return {Duration} a new Duration object
  */
-Duration.of = function (pYears, pMonths, pDays, pHours, pMinutes, pSeconds)
+Duration.of = function (pYears, pMonths, pDays, pHours, pMinutes, pSeconds, pMilliseconds)
 {
-    if (pHours == undefined)
-        pHours = 0;
+    if (pMonths == undefined)
+        pMonths = 0;
     if (pMinutes == undefined)
         pMinutes = 0;
     if (pSeconds == undefined)
         pSeconds = 0;
+    if (pMilliseconds == undefined)
+        pMilliseconds = 0;
     
-    pMinutes += pHours * 60;
+    pMinutes += (pHours || 0) * 60;
     pSeconds += pMinutes * 60;
+    pMilliseconds += pSeconds * 1000;
     
-    return new Duration(pYears, pMonths, pDays, pSeconds * 1000);
+    if (pYears)
+        pMonths += pYears * 12;
+    
+    return new Duration(pMonths, pDays, pMilliseconds);
+}
+
+/**
+ * Creates a new Duration object, but only with years. This does basically the same as using Duration.of with only the first parameter set, so this
+ * function only exists for better readability.
+ * 
+ * @param {Number} pYears amount of years
+ * @return {Duration} a new Duration object
+ */
+Duration.ofYears = function (pYears)
+{
+    return Duration.of(pYears);
+}
+
+/**
+ * Creates a new Duration object, but only with months. This does basically the same as using Duration.of with only the second parameter set, so this
+ * function only exists for better readability.
+ * 
+ * @param {Number} pMonths amount months
+ * @return {Duration} a new Duration object
+ */
+Duration.ofMonths = function (pMonths)
+{
+    return Duration.of(0, pMonths);
+}
+
+/**
+ * Creates a new Duration object with the specified amount of days.
+ * 
+ * @param {Number} pDays amount of days
+ * @param {Boolean} [pConvertToMilliseconds=false] if true, the days will be converted to milliseconds, creating a duration based on time and 
+ *                                          not on date (can make a difference with daylight saving time)
+ * @return {Duration} a new Duration object
+ */
+Duration.ofDays = function (pDays, pConvertToMilliseconds)
+{
+    if (pConvertToMilliseconds)
+        return Duration.ofTime(pDays * 24);
+    return Duration.of(0, 0, pDays);
 }
 
 /**
@@ -216,11 +264,23 @@ Duration.of = function (pYears, pMonths, pDays, pHours, pMinutes, pSeconds)
  * @param {Number} [pHours=0] hours
  * @param {Number} [pMinutes=0] minutes
  * @param {Number} [pSeconds=0] seconds
+ * @param {Number} [pMilliseconds=0] milliseconds
  * @return {Duration} a new Duration object
  */
-Duration.ofTime = function (pHours, pMinutes, pSeconds)
+Duration.ofTime = function (pHours, pMinutes, pSeconds, pMilliseconds)
 {
-    return Duration.of(undefined, undefined, undefined, pHours, pMinutes, pSeconds);
+    return Duration.of(0, 0, 0, pHours, pMinutes, pSeconds, pMilliseconds);
+}
+
+/**
+ * creates a new Duration object with the given milliseconds
+ * 
+ * @param {Number} pMilliseconds amount of milliseconds
+ * @return {Duration} new Duration object
+ */
+Duration.ofMilliseconds = function (pMilliseconds)
+{
+    return new Duration(0, 0, pMilliseconds);
 }
 
 /**
@@ -256,6 +316,39 @@ Duration.parse = function (pIso8601Duration)
     }
 }
 
+/**
+ * gets the amount of years of the duration
+ * 
+ * @return {Number} amount of years
+ */
+Duration.prototype.getYears = function ()
+{
+    return Math.floor(this._totalMonths / 12);
+}
+
+/**
+ * gets the amount of months of the duration
+ * 
+ * @return {Number} amount of months
+ */
+Duration.prototype.getMonths = function ()
+{
+    return this._totalMonths % 12;
+}
+
+/**
+ * Returns the amount of milliseconds of the duration. Because years and months don't always have the same length, they can't be included here.
+ * 
+ * @param {Boolean} [pAddDaysAsMilliseconds=false] set this to true if the days should be included in the calculation
+ * @return {Number} amount of milliseconds
+ */
+Duration.prototype.valueOf = function (pAddDaysAsMilliseconds)
+{
+    if (pAddDaysAsMilliseconds)
+        return (this._days * datetime.ONE_DAY) + this._milliseconds;
+    return this._milliseconds;
+}
+
 /**
  * makes a ISO-8601 string representing the duration
  * 
@@ -263,14 +356,17 @@ Duration.parse = function (pIso8601Duration)
  */
 Duration.prototype.getIso8601Representation = function ()
 {
+    var years = this.getYears();
+    var months = this.getMonths();
+    
     var iso8601Duration = "P"
-        + (this.years ? this.years + "Y" : "")
-        + (this.months ? this.months + "M" : "")
-        + (this.days ? this.days + "D" : "");
+        + (years ? years + "Y" : "")
+        + (months ? months + "M" : "")
+        + (this._days ? this._days + "D" : "");
     
-    if (this.milliseconds)
+    if (this._milliseconds)
     {
-        var millis = this.milliseconds;
+        var millis = this._milliseconds;
         var seconds = Math.floor(millis / 1000);
         millis = millis % 1000;
         var minutes = Math.floor(seconds / 60);
@@ -298,10 +394,36 @@ Duration.prototype.getIso8601Representation = function ()
  */
 Duration.prototype.invert = function ()
 {
-    this.years = -this.years;
-    this.months = -this.months;
-    this.days = -this.days;
-    this.milliseconds = -this.milliseconds;
+    this._totalMonths = -this._totalMonths;
+    this._days = -this._days;
+    this._milliseconds = -this._milliseconds;
+    
+    return this;
+}
+
+/**
+ * adds the given Duration to the Duration object
+ * 
+ * @param {Duration} pDuration Duration object to add
+ * @reutrn {Duration} current Duration object
+ */
+Duration.prototype.addDuration = function (pDuration)
+{
+    this._totalMonths += pDuration._totalMonths;
+    this._days += pDuration._days;
+    this._milliseconds += pDuration._milliseconds;
+}
+
+/**
+ * ensures that the duration is positive
+ * 
+ * @return {Duration} current object
+ */
+Duration.prototype.absolute = function ()
+{
+    this._totalMonths = Math.abs(this._totalMonths);
+    this._days = Math.abs(this._days);
+    this._milliseconds = Math.abs(this._milliseconds);
     
     return this;
 }
@@ -316,15 +438,31 @@ Duration.prototype.addToDate = function (pDate)
 {
     if (!(pDate instanceof Date))
         pDate = new Date(pDate);
-        
-    if (this.years !== 0)
-        pDate.setFullYear(pDate.getFullYear() + this.years);
-    if (this.months !== 0)
-        pDate.setMonth(pDate.getMonth() + this.months);
-    if (this.days !== 0)
-        pDate.setDate(pDate.getDate() + this.days);
-    if (this.milliseconds !== 0)
-        pDate.setTime(pDate.getTime() + this.milliseconds);
+    
+    var years = this.getYears();
+    var months = this.getMonths();
+    
+    if (years !== 0)
+        pDate.setFullYear(pDate.getFullYear() + years);
+    if (months !== 0)
+        pDate.setMonth(pDate.getMonth() + months);
+    if (this._days !== 0)
+        pDate.setDate(pDate.getDate() + this._days);
+    if (this._milliseconds !== 0)
+        pDate.setTime(pDate.getTime() + this._milliseconds);
     
     return pDate;
 }
+
+/**
+ * Creates a new Date object with the value of the given date and adds the duration (note that the duration can also be negative). 
+ * This won't change the given object.
+ *
+ * @param {Date} pDate date to change, any value that is not of type "Date" will be converted to a Date
+ * @return {Date} the Date object
+ */
+Duration.prototype.getDateWithDurationAdded = function (pDate)
+{
+    //using .valueOf(), so it would also work with numbers/strings/etc
+    return this.addToDate(pDate.valueOf());
+}