Previous TopicNext Topic


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

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

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

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

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

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

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

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

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

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

Returns

The number of whole years between the two dates.


(c) Copyright Actuate Corporation 2006

Previous TopicNext Topic