DateAndTime.DateDiff Method

Reference

Definition

Namespace:: Microsoft.VisualBasic

Assembly:: Microsoft.VisualBasic.Core.dll

Assembly:: Microsoft.VisualBasic.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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

Overloads

DateDiff(DateInterval, DateTime, DateTime, FirstDayOfWeek, FirstWeekOfYear)	Subtracts `Date1` from `Date2` to give a long value specifying the number of time intervals between the two `Date` values.
DateDiff(String, Object, Object, FirstDayOfWeek, FirstWeekOfYear)	Subtracts `Date1` from `Date2` to give a long value specifying the number of time intervals between the two `Date` values.

DateDiff(DateInterval, DateTime, DateTime, FirstDayOfWeek, FirstWeekOfYear)

Source:: DateAndTime.vb

Source:: DateAndTime.vb

Source:: DateAndTime.vb

Subtracts Date1 from Date2 to give a long value specifying the number of time intervals between the two Date values.

public static long DateDiff (Microsoft.VisualBasic.DateInterval Interval, DateTime Date1, DateTime Date2, Microsoft.VisualBasic.FirstDayOfWeek DayOfWeek = Microsoft.VisualBasic.FirstDayOfWeek.Sunday, Microsoft.VisualBasic.FirstWeekOfYear WeekOfYear = Microsoft.VisualBasic.FirstWeekOfYear.Jan1);

static member DateDiff : Microsoft.VisualBasic.DateInterval * DateTime * DateTime * Microsoft.VisualBasic.FirstDayOfWeek * Microsoft.VisualBasic.FirstWeekOfYear -> int64

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

Parameters

Interval: DateInterval

Required. A DateInterval enumeration value or a string expression representing the time interval you want to use as the unit of difference between Date1 and Date2.

Date1: DateTime

Required. The first date/time value you want to use in the calculation.

Date2: DateTime

Required. The second date/time value you want to use in the calculation.

DayOfWeek: FirstDayOfWeek

Optional. A value chosen from the FirstDayOfWeek enumeration that specifies the first day of the week. If not specified, Sunday is used.

WeekOfYear: FirstWeekOfYear

Optional. A value chosen from the FirstWeekOfYear enumeration that specifies the first week of the year. If not specified, Jan1 is used.

Returns

Int64

A long value specifying the number of time intervals between two Date values.

Exceptions

ArgumentException

Date1, Date2, or DayofWeek is out of range.

InvalidCastException

Date1 or Date2 is of an invalid type.

Examples

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

Dim date2Entered As String = InputBox("Enter a date")

Try
    Dim date2 As Date = Date.Parse(date2Entered)
    Dim date1 As Date = Now

    ' Determine the number of days between the two dates.
    Dim days As Long = DateDiff(DateInterval.Day, date1, date2)

    ' This statement has a string interval argument, and
    ' is equivalent to the above statement.
    'Dim days As Long = DateDiff("d", date1, date2)

    MessageBox.Show("Days from today: " & days.ToString)
Catch ex As Exception
    MessageBox.Show("Invalid Date: " & ex.Message)
End Try

Remarks

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.

Behavior

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.
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.

For cultures such as Japanese that have multiple eras, the DateDiff method does not return a difference in years if the difference spans two or more eras. Instead, you can calculate the difference in values returned by the Year property, as shown in the following example: date2.Year - date1.Year.
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: DateTime.Subtract subtracts a TimeSpan from a Date variable to return another Date value, and DateTime.Subtract 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 Double = runLength.TotalMilliseconds
```

The Interval argument can have one of the following settings.

Enumeration value	String value	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

Applies to

DateDiff(String, Object, Object, FirstDayOfWeek, FirstWeekOfYear)

Source:: DateAndTime.vb

Source:: DateAndTime.vb

Source:: DateAndTime.vb

Subtracts Date1 from Date2 to give a long value specifying the number of time intervals between the two Date values.

public static long DateDiff (string Interval, object? Date1, object? Date2, Microsoft.VisualBasic.FirstDayOfWeek DayOfWeek = Microsoft.VisualBasic.FirstDayOfWeek.Sunday, Microsoft.VisualBasic.FirstWeekOfYear WeekOfYear = Microsoft.VisualBasic.FirstWeekOfYear.Jan1);

public static long DateDiff (string Interval, object Date1, object Date2, Microsoft.VisualBasic.FirstDayOfWeek DayOfWeek = Microsoft.VisualBasic.FirstDayOfWeek.Sunday, Microsoft.VisualBasic.FirstWeekOfYear WeekOfYear = Microsoft.VisualBasic.FirstWeekOfYear.Jan1);

static member DateDiff : string * obj * obj * Microsoft.VisualBasic.FirstDayOfWeek * Microsoft.VisualBasic.FirstWeekOfYear -> int64

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

Parameters

Interval: String

Required. A DateInterval enumeration value or a string expression representing the time interval you want to use as the unit of difference between Date1 and Date2.

Date1: Object

Required. The first date/time value you want to use in the calculation.

Date2: Object

Required. The second date/time value you want to use in the calculation.

DayOfWeek: FirstDayOfWeek

Optional. A value chosen from the FirstDayOfWeek enumeration that specifies the first day of the week. If not specified, Sunday is used.

WeekOfYear: FirstWeekOfYear

Optional. A value chosen from the FirstWeekOfYear enumeration that specifies the first week of the year. If not specified, Jan1 is used.

Returns

Int64

A long value specifying the number of time intervals between two Date values.

Exceptions

ArgumentException

Date1, Date2, or DayofWeek is out of range.

InvalidCastException

Date1 or Date2 is of an invalid type.

Examples

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

Dim date2Entered As String = InputBox("Enter a date")

Try
    Dim date2 As Date = Date.Parse(date2Entered)
    Dim date1 As Date = Now

    ' Determine the number of days between the two dates.
    Dim days As Long = DateDiff(DateInterval.Day, date1, date2)

    ' This statement has a string interval argument, and
    ' is equivalent to the above statement.
    'Dim days As Long = DateDiff("d", date1, date2)

    MessageBox.Show("Days from today: " & days.ToString)
Catch ex As Exception
    MessageBox.Show("Invalid Date: " & ex.Message)
End Try

Remarks

Behavior

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.
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.

For cultures such as Japanese that have multiple eras, the DateDiff method does not return a difference in years if the difference spans two or more eras. Instead, you can calculate the difference in values returned by the Year property, as shown in the following example: date2.Year - date1.Year.
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: DateTime.Subtract subtracts a TimeSpan from a Date variable to return another Date value, and DateTime.Subtract 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 Double = runLength.TotalMilliseconds
```

The Interval argument can have one of the following settings.

Enumeration value	String value	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

Applies to

Share via

DateAndTime.DateDiff Method

Definition

Overloads

DateDiff(DateInterval, DateTime, DateTime, FirstDayOfWeek, FirstWeekOfYear)

Parameters

Returns

Exceptions

Examples

Remarks

Behavior

See also

Applies to

DateDiff(String, Object, Object, FirstDayOfWeek, FirstWeekOfYear)

Parameters

Returns

Exceptions

Examples

Remarks

Behavior

See also

Applies to

Additional resources