DateAndTime.DateDiff Method
Definition
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 |
DateDiff(String, Object, Object, FirstDayOfWeek, FirstWeekOfYear) |
Subtracts |
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
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 ofDate1
from the value ofDate2
to produce the difference. Neither value is changed in the calling program.Return Values. Because
Date1
andDate2
are of theDate
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 aLong
value.If
Date1
represents a later date and time thanDate2
,DateDiff
returns a negative number.Day Intervals. If
Interval
is set toDateInterval.DayOfYear
, it is treated the same asDateInterval.Day
, becauseDayOfYear
is not a meaningful unit for a time interval.Week Intervals. If
Interval
is set toDateInterval.WeekOfYear
, the return value represents the number of weeks between the first day of the week containingDate1
and the first day of the week containingDate2
. The following example shows how this produces different results fromDateInterval.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 towD
because the difference between the two dates is less than seven days, but it returns 1 towY
because there is a seven-day difference between the first days of the respective calendar weeks.Larger Intervals. If
Interval
is set toDateInterval.Year
, the return value is calculated purely from the year parts ofDate1
andDate2
. Similarly, the return value forDateInterval.Month
is calculated purely from the year and month parts of the arguments, and forDateInterval.Quarter
from the quarters containing the two dates.For example, when comparing December 31 to January 1 of the following year,
DateDiff
returns 1 forDateInterval.Year
,DateInterval.Quarter
, orDateInterval.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 theSubtract
method in either of its overloaded forms: DateTime.Subtract subtracts a TimeSpan from aDate
variable to return anotherDate
value, and DateTime.Subtract subtracts aDate
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
- DateAdd
- DatePart
- Day(DateTime)
- Format(Object, String)
- Now
- Weekday(DateTime, FirstDayOfWeek)
- Year(DateTime)
- DateTime
- TimeSpan
- Data Type Summary (Visual Basic)
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
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 ofDate1
from the value ofDate2
to produce the difference. Neither value is changed in the calling program.Return Values. Because
Date1
andDate2
are of theDate
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 aLong
value.If
Date1
represents a later date and time thanDate2
,DateDiff
returns a negative number.Day Intervals. If
Interval
is set toDateInterval.DayOfYear
, it is treated the same asDateInterval.Day
, becauseDayOfYear
is not a meaningful unit for a time interval.Week Intervals. If
Interval
is set toDateInterval.WeekOfYear
, the return value represents the number of weeks between the first day of the week containingDate1
and the first day of the week containingDate2
. The following example shows how this produces different results fromDateInterval.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 towD
because the difference between the two dates is less than seven days, but it returns 1 towY
because there is a seven-day difference between the first days of the respective calendar weeks.Larger Intervals. If
Interval
is set toDateInterval.Year
, the return value is calculated purely from the year parts ofDate1
andDate2
. Similarly, the return value forDateInterval.Month
is calculated purely from the year and month parts of the arguments, and forDateInterval.Quarter
from the quarters containing the two dates.For example, when comparing December 31 to January 1 of the following year,
DateDiff
returns 1 forDateInterval.Year
,DateInterval.Quarter
, orDateInterval.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 theSubtract
method in either of its overloaded forms: DateTime.Subtract subtracts a TimeSpan from aDate
variable to return anotherDate
value, and DateTime.Subtract subtracts aDate
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
- DateAdd
- DatePart
- Day(DateTime)
- Format(Object, String)
- Now
- Weekday(DateTime, FirstDayOfWeek)
- Year(DateTime)
- DateTime
- TimeSpan
- Data Type Summary (Visual Basic)
Applies to
משוב
https://aka.ms/ContentUserFeedback.
בקרוב: במהלך 2024, נפתור בעיות GitHub כמנגנון המשוב לתוכן ונחליף אותו במערכת משוב חדשה. לקבלת מידע נוסף, ראה:שלח והצג משוב עבור