A DateDiff represents a period of time or, as the name implies, the difference between two moments in time. DateDiff values are used heavily in many types of date/time math. You can get a DateDiff as the result of subtracting two Date values, two Time values or two DateTime values. You can also create a DateDiff using the toDateDiff function.

DateDiff values are comprised of several fields or parts. All fields can be both read and modified (assuming the entire value of the DateDiff, as a whole, can be modified). They are accessed as dateDiffValue.fieldName. For instance, to get the number of days since date x you would write: (curDate() - x).totalDays

 

Field	Data Type	Description
isNegative	Boolean	Similar to a positive/negative number, dateDiffs can represent a time period going forward or backward in time.  Even if isNegative is true, all of the other fields will contain positive values.
years	Integer	The number of years in this DateDiff, not including any fractional years
months	Integer	The number of months in this DateDiff, not including any full years or fractional months
days	Integer	The number of days in this DateDiff, not including any full months/years or any fractional days
hours	Integer	The number of hours in this DateDiff, not including any full days/months/years or any fractional hours
minutes	Integer	The number of minutes in this DateDiff, not including any full hours/days/months/years or fractional minutes
seconds	Integer	The number of seconds in this DateDiff, not including any full minutes/hours/days/months/years or fractional seconds
milliseconds	Integer	The number of minutes in this DateDiff, not including any full seconds/minutes/hours/days/months/years
totalMillis	Integer	The total number of milliseconds in this DateDiff, including all larger units of time multiplied out into milliseconds
totalSeconds	Float	The total number of seconds in this DateDiff including all larger units of time multiplied out into seconds, including fractional seconds
totalMinutes	Float	The total number of minutes in this DateDiff including all larger units of time multiplied out into minutes, including fractional minutes
totalHours	Float	The total number of hours in this DateDiff including all larger units of time multiplied out into hours, including fractional hours
totalDays	Float	The total number of days in this DateDiff including all larger units of time multiplied out into days, including fractional days
totalMonths	Float	The total number of months in this DateDiff including all larger units of time multiplied out into months, including fractional months
totalYears	Float	The total number of years in this DateDiff, including fractional years

 

It is important to know that when converting months to days and vice-versa, the DateDiff internal logic considers a month to be exactly (365.25 / 12) days long, which is the average lengh of a month in a normal four year period. The internal logic attempts to refrain from doing this conversion, but conversion is sometimes unavoidable. This can result in some rather odd paradoxes. For instance, if you ask how many months and days there are between February 1, 2005 and March 2, 2005. You might consider it more accurate to say 29 days rather than 1 month and 1 day. Exactly which result is returned depends on how the DateDiff is created and which fields you query.