Treatment of Parameters. DateDiff subtracts the value of Date1 from the value of Date2 to produce the difference. Neither value is changed in the calling program.

Return Values. Because Date1 and Date2 are of the Date data type, they hold date and time values accurate to 100-nanosecond ticks on the system timer. However, DateDiff always returns the number of time intervals as a Long value.

If Date1 represents a later date and time than Date2, DateDiff returns a negative number.

Day Intervals. If Interval is set to DateInterval.DayOfYear, it is treated the same as DateInterval.Day, because DayOfYear is not a meaningful unit for a time interval.

Week Intervals. If Interval is set to DateInterval.WeekOfYear, the return value represents the number of weeks between the first day of the week containing Date1 and the first day of the week containing Date2. The following example shows how this produces different results from DateInterval.Weekday.

' The following statements set datTim1 to a Thursday
' and datTim2 to the following Tuesday.
Dim datTim1 As Date = #1/4/2001#
Dim datTim2 As Date = #1/9/2001#
' Assume Sunday is specified as first day of the week.
Dim wD As Long = DateDiff(DateInterval.Weekday, datTim1, datTim2)
Dim wY As Long = DateDiff(DateInterval.WeekOfYear, datTim1, datTim2)

In the preceding example, DateDiff returns 0 to wD because the difference between the two dates is less than seven days, but it returns 1 to wY because there is a seven-day difference between the first days of the respective calendar weeks.

Caution
When the time part of Date1 is greater than that of Date2 and Interval is set to DateInterval.WeekOfYear, the DateDiff function returns a value that is one less than the correct value.

Larger Intervals. If Interval is set to DateInterval.Year, the return value is calculated purely from the year parts of Date1 and Date2. Similarly, the return value for DateInterval.Month is calculated purely from the year and month parts of the arguments, and for DateInterval.Quarter from the quarters containing the two dates.

For example, when comparing December 31 to January 1 of the following year, DateDiff returns 1 for DateInterval.Year, DateInterval.Quarter, or DateInterval.Month, even though at most only one day has elapsed.

Other Intervals. Since every Date value is supported by a DateTime structure, its methods give you additional options in finding time intervals. For example, you can use the Subtract method in either of its overloaded forms: System.DateTime.Subtract(System.TimeSpan) subtracts a TimeSpan from a Date variable to return another Date value, and System.DateTime.Subtract(System.DateTime) subtracts a Date value to return a TimeSpan. You can time a process to find out how many milliseconds it takes, as the following example shows.

Dim startTime As Date = Now
' Run the process that is to be timed.
Dim runLength As Global.System.TimeSpan = Now.Subtract(startTime)
Dim millisecs As Integer = runLength.Milliseconds