> ## Class DateTimeSpan

> The static DateTimeSpan class provides functions to determine the amount of time between two dates or times, and to add or subtract time spans. It provides a set of functions for working with the difference between two dates. Since date spans are just numbers, the application can use normal math on them: multiplication, division, addition, subtraction, and so forth. This class is static. The application cannot create instances of the class.

> ### DateTimeSpan.addDate

> This function returns a new date that is the sum of adding the given number of years, months, and days to the start date. The months can be greater than 12, and the days can be greater than the number of days in a month. The net effect is as if there were three different operations. Add the years first. Then, using the resulting date, add the months. Then, using the resulting date, add the days.

> When adding a month, the resulting date may not be valid. For example, adding one month to Jan. 31 would produce the invalid date Feb. 31. The function adjusts the date to be valid, in this case, if the year is not a leap year, then Feb. has 28 days and the resulting date would be Mar. 3.

> Any of the years, months or days arguments can be null or undefined. If so, then that value is treated as if it was zero.

> Any of the years, months or days arguments can be negative. In this case, the result is as if that unit was subtracted from the base date.

> Syntax

> DateTimeSpan.addDate( startDate, years, months, days )

> Arguments

> n | startDate

> A date object that represents the base date.

> n | years

> The number of years to add to the date.

> n | months

> The number of months to add to the date.

> n | days

> The number of days to add to the date.

> Returns

> A date that results from adding the years, months, and days to the start date.

> Example

> var startDate = date.parse( "2004-12-31" );
> var endDate;
> endDate = DateTimeSpan( startDate, 1, 0, 0 ); // returns 2005-12-31
> endDate = DateTimeSpan( startDate, 0, 1, 0 ); // returns 2005-1-31
> endDate = DateTimeSpan( startDate, 0, 0, 1 ); // returns 2005-1-1
> endDate = DateTimeSpan( startDate, 1, 1, 1 ); // returns 2005-3-4

> See also

> DateTimeSpan.addTime function

> DateTimeSpan.subDate function

> ### DateTimeSpan.addTime

> This function returns a new date that is the sum of adding the given number of hours, minutes, and seconds to the start date. The hours can be greater than 24, and the minutes and seconds can be greater than 60. The net effect is as if there were three different operations: add the hours first. Then, using the resulting date, add the minutes. Then, using the resulting date, add the seconds.

> Any of the hours, minutes, and seconds arguments can be null or undefined. If so, then that value is treated as if it was zero.

> Any of the hours, minutes, and seconds arguments can be negative. In this case, the result is as if that unit was subtracted from the base date.

> Syntax

> DateTimeSpan.addTime( startDate, hours, minutes, seconds )

> Arguments

> n | startDate

> A date object that represents the base date.

> n | hours

> The number of hours to add to the date.

> n | minutes

> The number of minutes to add to the date.

> n | seconds

> The number of seconds to add to the date.

> Returns

> A date that results from adding the hours, minutes, and seconds to the start date.

> See also

> DateTimeSpan.addDate function

> DateTimeSpan.subTime function

> ### DateTimeSpan.days

> Returns the number of days between two dates. A day is defined as a change of the calendar. Thus, 11:59:59 PM Feb. 27 to Midnight Feb. 28 is one day, as is midnight Feb. 27 to 11:59:59 Feb. 28.

> Syntax

> DateTimeSpan.days( startDate, endDate )

> Arguments

> n | startDate

> A date object that represents the start of the span.

> n | endDate

> A date object that represents the end of the span.

> Returns

> Returns number of days between two dates.

> ### DateTimeSpan.hours

> This function returns the number of whole hours between two times. A whole hour is defined a span from a given minute of the hour in hour, to the same minute in the next hour. For example, 1:23:00 to 2:23:00 is one hour, while 1:23:00 to 2:22:59 is zero whole hours.

> Syntax

> DateTimeSpan.hours( startDate, endDate )

> Arguments

> n | startDate

> A date object that represents the start of the span.

> n | endDate

> A date object that represents the end of the span.

> Returns

> The number of whole hours between two dates.

> ### DateTimeSpan.minutes

> This function returns the number of whole minutes between two times. A whole minutes is defined a span from a given second of a minute, to the same second in the next minute. For example, 1:23:00 to 1:24:00 is one minute, while 1:23:00 to 1:22:59 is zero whole minutes.

> Syntax

> DateTimeSpan.minutes( startDate, endDate )

> Arguments

> n | startDate

> A date object that represents the start of the span.

> n | endDate

> A date object that represents the end of the span.

> Returns

> The number of whole minutes between two dates.

> ### DateTimeSpan.months

> This function returns the number of whole months between two dates. A whole month is defined a span of time from the nth of one month to the nth of the following month. For example, Feb. 28 to Mar. 28 is one month, while Feb. 28 to Mar. 26 is zero whole months.

> Syntax

> DateTimeSpan.months( startDate, endDate )

> Arguments

> n | startDate

> A date object that represents the start of the span.

> n | endDate

> A date object that represents the end of the span.

> Returns

> Returns the number of whole months between two dates.

> ### DateTimeSpan.seconds

> This function returns the number of seconds between two times.

> Syntax

> DateTimeSpan.seconds( startDate, endDate )

> Arguments

> n | startDate

> A date object that represents the start of the span.

> n | endDate

> A date object that represents the end of the span.

> Returns

> The number of whole minutes between two dates.

> ### DateTimeSpan.subDate

> This function returns a new date that is the result of subtracting the given number of years, months, and days from the start date. The months can be greater than 12, and the days can be greater than the number of days in a month. The net effect is as if there were three different operations. Subtract the years first. Then, using the resulting date, subtract the months. Then, using the resulting date, subtract the days.

> When subtracting a month, the resulting date may not be valid. For example, subtracting one month from Mar. 30 would produce the invalid date Feb. 30. The function adjusts the date to be valid, adjusting the date to the last valid day in the month. In this case, if the year is not a leap year, the date would be adjusted to Feb. 28.

> Any of the years, months or days arguments can be null or undefined. In this case, that value is treated as if it was zero.

> Any of the years, months or days arguments can be negative. In this case, the result is as if that unit was added to the base date.

> Syntax

> DateTimeSpan.subDate( startDate, years, months, days )

> Arguments

> n | startDate

> A date object that represents the base date.

> n | years

> The number of years to subtract from the date.

> n | months

> The number of months to subtract from the date.

> n | days

> The number of days to subtract from the date.

> Returns

> A date that results from subtracting the years, months, and days from the start date.

> See also

> DateTimeSpan.addDate function

> DateTimeSpan.subTime function

> ### DateTimeSpan.subTime

> This function returns a new date that is the result of subtracting the given number of hours, minutes, and seconds from the start date. The hours can be greater than 24, and the minutes and seconds can be greater than 60. The net effect is as if there were three different operations. Subtract the hours first. Then, using the resulting date, subtract the minutes. Then, using the resulting date, subtract the seconds.

> Any of the hours, minutes, and seconds arguments can be null or undefined. In this case, that value is treated as if it was zero.

> Any of the hours, minutes, and seconds arguments can be negative. In this case, the result is as if that unit was added to the base date.

> Syntax

> DateTimeSpan.subTime( startDate, hours, minutes, seconds )

> Arguments

> n | startDate

> A date object that represents the base date.

> n | hours

> The number of hours to subtract from the date.

> n | minutes

> The number of minutes to subtract from the date.

> n | seconds

> The number of seconds to subtract from the date.

> Returns

> A date that results from subtracting the hours, minutes, and seconds from the start date.

> See also

> DateTimeSpan.addTime function

> DateTimeSpan.subDate function

> ### DateTimeSpan.years

> This function computes the number of whole years between the two dates. A whole year is defined as running from a given month, day, and time in one year to the same month, day, and time in the next year. Because of leap years, a whole year will sometimes include 365 days and sometimes 366 days.

> If either argument is other than a date, an exception is thrown. If either argument is null, then the result is also null.

> Syntax

> DateTimeSpan.years( startDate, endDate )

> Arguments

> n | startDate

> A date object that represents the start of the span.

> n | endDate

> A date object that represents the end of the span.

> Returns

> The number of whole years between the two dates.

(c) Copyright Actuate Corporation 2008