This documentation is archived and is not being maintained.

DateDiff Function

Returns a Long value specifying the number of time intervals between two Date values.

Public Overloads Function DateDiff( _
   ByVal Interval As DateInterval, _
   ByVal Date1 As DateTime, _
   ByVal Date2 As DateTime, _
   Optional ByVal DayOfWeek As FirstDayOfWeek = FirstDayOfWeek.Sunday, _
   Optional ByVal  WeekOfYear As FirstWeekOfYear = FirstWeekOfYear.Jan1 _
) As Long


Public Overloads Function DateDiff( _
   ByVal Interval As String, _
   ByVal Date1 As Object, _
   ByVal Date2 As Object, _
   Optional ByVal DayOfWeek As FirstDayOfWeek = FirstDayOfWeek.Sunday, _
   Optional ByVal WeekOfYear As FirstWeekOfYear = FirstWeekOfYear.Jan1 _
) As Long


Required. DateInterval enumeration value or String expression representing the time interval you want to use as the unit of difference between Date1 and Date2.
Date1, Date2
Required. Date. The two date/time values you want to use in the calculation. The value of Date1 is subtracted from the value of Date2 to produce the difference. Neither value is changed in the calling program.
Optional. A value chosen from the FirstDayOfWeek enumeration that specifies the first day of the week. If not specified, FirstDayOfWeek.Sunday is used.
Optional. A value chosen from the FirstWeekOfYear enumeration that specifies the first week of the year. If not specified, FirstWeekOfYear.Jan1 is used.


The Interval argument can have one of the following settings.

Enumeration value String Unit of time difference
DateInterval.Day d Day
DateInterval.DayOfYear y Day
DateInterval.Hour h Hour
DateInterval.Minute n Minute
DateInterval.Month m Month
DateInterval.Quarter q Quarter
DateInterval.Second s Second
DateInterval.Weekday w Week
DateInterval.WeekOfYear ww Calendar week
DateInterval.Year yyyy Year

The DayOfWeek argument can have one of the following settings.

Enumeration value Value Description
FirstDayOfWeek.System 0 First day of week specified in system settings
FirstDayOfWeek.Sunday 1 Sunday (default)
FirstDayOfWeek.Monday 2 Monday (complies with ISO standard 8601, section 3.17)
FirstDayOfWeek.Tuesday 3 Tuesday
FirstDayOfWeek.Wednesday 4 Wednesday
FirstDayOfWeek.Thursday 5 Thursday
FirstDayOfWeek.Friday 6 Friday
FirstDayOfWeek.Saturday 7 Saturday

The WeekOfYear argument can have one of the following settings.

Enumeration value Value Description
FirstWeekOfYear.System 0 First week of year specified in system settings
FirstWeekOfYear.Jan1 1 Week in which January 1 occurs (default)
FirstWeekOfYear.FirstFourDays 2 Week that has at least four days in the new year (complies with ISO standard 8601, section 3.17)
FirstWeekOfYear.FirstFullWeek 3 First full week in the new year


Exception type Error number Condition
ArgumentException 5 Invalid Interval.
ArgumentException 5 Date or DayofWeek are out of range.
InvalidCastException 13 Date1 or Date2 are invalid types.


You can use the DateDiff function to determine how many specified time intervals exist between two date/time values. For example, you might use DateDiff to calculate the number of days between two dates, or the number of weeks between today and the end of the year.

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.

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.

Dim DatTim1 As Date = #1/4/2001#   ' This is a Thursday.
Dim DatTim2 As Date = #1/9/2001#   ' This is the next Tuesday.
' 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.

If Interval is set to DateInterval.Year, the return value is calculated purely from the year parts of Date1 and Date2.

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.

If any argument has an invalid value, an ArgumentException error occurs. If either the Date1 or Date2 argument has a value that cannot be coerced to a valid Date value, an InvalidCastException error occurs.

Note   When comparing December 31 to January 1 of the following year, DateDiff returns 1 for DateInterval.Year, DateInterval.Quarter, or DateInterval.Month, even though only one day has elapsed.

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. One of these subtracts a TimeSpan from a Date variable to return another Date value; the other subtracts a Date value to return a TimeSpan. You can time a process to find out how many milliseconds it takes, as follows:

Dim StartTime As Date = Now   ' Starting date/time.
' Run the process that is to be timed.
Dim RunLength As System.TimeSpan = Now.Subtract(StartTime)
Dim Millisecs As Integer = RunLength.Milliseconds


This example uses the DateDiff function to display the number of days between a given date and today.

Dim FirstDate, Msg As String   ' Declare variables.
Dim SecondDate As Date
FirstDate = InputBox("Enter a date")
SecondDate = CDate(FirstDate)
Msg = "Days from today: " & DateDiff(DateInterval.Day, Now, SecondDate)
MsgBox (Msg)


Namespace: Microsoft.VisualBasic

Module: DateAndTime

Assembly: Microsoft Visual Basic .NET Runtime (in Microsoft.VisualBasic.dll)

See Also

DateAdd Function | DatePart Function | Day Function | Format Function | Now Property | Weekday Function | Year Function | Date Data Type | System Namespace | DateTime Structure | TimeSpan Structure | ArgumentException Class | InvalidCastException Class