# DateAndTime.DateDiff Method

## Definition

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

values.

## Overloads

DateDiff(DateInterval, DateTime, DateTime, FirstDayOfWeek, FirstWeekOfYear) |
Returns a long value specifying the number of time intervals between two |

DateDiff(String, Object, Object, FirstDayOfWeek, FirstWeekOfYear) |
Returns a long value specifying the number of time intervals between two |

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

Returns a long value specifying the number of time intervals between 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

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

values.

#### Exceptions

`Date1`

, `Date2`

, or `DayofWeek`

is out of range.

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

### See also

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

Returns a long value specifying the number of time intervals between 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

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

values.

#### Exceptions

`Date1`

, `Date2`

, or `DayofWeek`

is out of range.

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